effect-app 4.0.0-beta.24 → 4.0.0-beta.240

package/src/client.ts

@@ -1,6 +1,7 @@
 // codegen:start {preset: barrel, include: ./client/*.ts}
-export * from "./client/apiClientFactory.js"
-export * from "./client/clientFor.js"
-export * from "./client/errors.js"
-export * from "./client/makeClient.js"
+export * from "./client/apiClientFactory.ts"
+export * from "./client/clientFor.ts"
+export * from "./client/errors.ts"
+export * from "./client/InvalidationKeys.ts"
+export * from "./client/makeClient.ts"
 // codegen:end

package/src/http/Request.ts

@@ -1,4 +1,4 @@
-import { Option } from "effect"
+import * as Option from "effect/Option"
 import type { HttpClientResponse } from "effect/unstable/http/HttpClientResponse"
 import * as Effect from "../Effect.js"
 import { HttpClient, HttpClientError, HttpClientRequest, HttpHeaders } from "./internal/lib.js"

package/src/ids.ts

@@ -1,5 +1,6 @@
 import { brandedStringId, type Codec, NonEmptyString255, StringId, type StringIdBrand, withDefaultMake } from "effect-app/Schema"
 import type { B } from "effect-app/Schema/schema"
+import * as Effect from "effect/Effect"
 import type { Simplify } from "effect/Types"
 import { S } from "./index.js"
 import { extendM } from "./utils.js"
@@ -9,7 +10,16 @@ export interface RequestIdBrand extends StringIdBrand {
 }
 
 export type RequestId = NonEmptyString255
-// a request id may be made from a span id, which does not comply with StringId schema.
+/**
+ * Schema for a request id.
+ *
+ * A request id may be made from a span id, which does not comply with the
+ * `StringId` schema (hence the looser `NonEmptyString255` base).
+ *
+ * `.withConstructorDefault` => fresh `StringId` (construction-only; not
+ * applied during decode — cannot be used to JIT-migrate database fields).
+ * See `./Schema/ext.ts` for the full policy note.
+ */
 export const RequestId = extendM(
   Object
     .assign(Object.create(NonEmptyString255) as {}, NonEmptyString255 as unknown as Codec<NonEmptyString255, string>),
@@ -17,12 +27,24 @@ export const RequestId = extendM(
     const make = StringId.make as () => NonEmptyString255
     return ({
       make,
-      withDefault: s.pipe(S.withDefaultConstructor(make))
+      /**
+       * Construction-only default: fresh `StringId`. Applied only when the
+       * field is omitted from `.make(...)` input. NOT applied during decode —
+       * cannot be used to JIT-migrate database fields. See `./Schema/ext.ts`
+       * file-level note.
+       */
+      withConstructorDefault: S.withConstructorDefault(Effect.sync(make))(s as typeof s & S.WithoutConstructorDefault)
     })
   }
 )
   .pipe(withDefaultMake)
 
 export interface UserProfileIdBrand extends Simplify<B.Brand<"UserProfileId"> & StringIdBrand> {}
-export type UserProfileId = StringId & UserProfileIdBrand
+export type UserProfileId = string & UserProfileIdBrand
+/**
+ * Branded `StringId` for user profiles.
+ *
+ * Exposes `.withConstructorDefault` (fresh id) — construction-only; not
+ * applied during decode. See `./Schema/ext.ts` for the full policy note.
+ */
 export const UserProfileId = brandedStringId<UserProfileId>()

package/src/index.ts

@@ -1,24 +1,18 @@
+// eslint-disable-next-line import/no-unassigned-import
 import "./builtin.js"
 
-import * as ServiceMap from "./ServiceMap.js"
-
 export * as Fnc from "./Function.js"
 export * as Utils from "./utils.js"
 
 export * as Array from "./Array.js"
+export * as Config from "./Config.js"
+export * as ConfigProvider from "./ConfigProvider.js"
+export * as Context from "./Context.js"
 export * as Effect from "./Effect.js"
 export * as Layer from "./Layer.js"
 export * as NonEmptySet from "./NonEmptySet.js"
-export * as ServiceMap from "./ServiceMap.js"
 export * as Set from "./Set.js"
 
-export {
-  /**
-   * @deprecated use ServiceMap directly instead
-   */
-  ServiceMap as Context
-}
-
 export { type NonEmptyArray, type NonEmptyReadonlyArray } from "./Array.js"
 
 export * from "effect"
@@ -26,5 +20,6 @@ export * from "effect"
 export type * as Types from "./Types.js"
 
 export * as SecretURL from "./Config/SecretURL.js"
+export * as RpcX from "./rpc.js"
 export * as S from "./Schema.js"
 export { copy } from "./utils.js"

package/src/middleware.ts

@@ -1,21 +1,25 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { ServiceMap } from "effect-app"
-import { RpcX } from "./rpc.js"
+import * as Context from "effect-app/Context"
+import { RpcMiddleware } from "./rpc.js"
 
-export class DevMode extends ServiceMap.Reference("DevMode", { defaultValue: () => false }) {}
+export class DevMode extends Context.Reference("DevMode", { defaultValue: () => false }) {}
 
-export class RequestCacheMiddleware
-  extends RpcX.RpcMiddleware.Tag<RequestCacheMiddleware>()("RequestCacheMiddleware")
-{}
+export class RequestCacheMiddleware extends RpcMiddleware.Tag<RequestCacheMiddleware>()("RequestCacheMiddleware") {}
 
 export class ConfigureInterruptibilityMiddleware
-  extends RpcX.RpcMiddleware.Tag<ConfigureInterruptibilityMiddleware>()("ConfigureInterruptibilityMiddleware")
+  extends RpcMiddleware.Tag<ConfigureInterruptibilityMiddleware>()("ConfigureInterruptibilityMiddleware")
 {}
 
-export class LoggerMiddleware extends RpcX.RpcMiddleware.Tag<LoggerMiddleware>()("LoggerMiddleware") {}
+export class LoggerMiddleware extends RpcMiddleware.Tag<LoggerMiddleware>()("LoggerMiddleware") {}
 
-export class DevModeMiddleware extends RpcX.RpcMiddleware.Tag<DevModeMiddleware>()("DevModeMiddleware") {}
+export class DevModeMiddleware extends RpcMiddleware.Tag<DevModeMiddleware>()("DevModeMiddleware") {}
 
+/**
+ * Generic middlewares attached by `makeRouter` to every request.
+ *
+ * Invalidation key wrap/unwrap is handled by the routing layer (server) and the
+ * api client factory (client) directly — there is no middleware tag for it.
+ */
 export const DefaultGenericMiddlewares = [
   RequestCacheMiddleware,
   ConfigureInterruptibilityMiddleware,

package/src/rpc/Invalidation.ts

@@ -0,0 +1,226 @@
+import * as Ref from "effect/Ref"
+import { Rpc } from "effect/unstable/rpc"
+import * as Context from "../Context.js"
+import * as Effect from "../Effect.js"
+import * as S from "../Schema.js"
+
+/**
+ * A single segment within an `InvalidationKey` array.
+ * Accepts any JSON-compatible value: string, number, boolean, null,
+ * arrays and objects recursively — matching TanStack Query's `queryKey` element type.
+ */
+export const InvalidationKeySegment = S.Json
+export type InvalidationKeySegment = S.Schema.Type<typeof InvalidationKeySegment>
+
+/** Schema for a single invalidation key – an array of segments compatible with TanStack Query `queryKey`. */
+export const InvalidationKey = S.Array(InvalidationKeySegment)
+export type InvalidationKey = S.Schema.Type<typeof InvalidationKey>
+
+/** Schema for the full set of invalidation keys – an array of `InvalidationKey`. */
+export const InvalidationKeys = S.Array(InvalidationKey)
+export type InvalidationKeys = S.Schema.Type<typeof InvalidationKeys>
+
+/** Metadata included in every command response for server-driven cache invalidation. */
+export const CommandMetaData = S.Struct({ invalidateQueries: InvalidationKeys })
+export type CommandMetaData = S.Schema.Type<typeof CommandMetaData>
+
+/**
+ * Wraps a command's success schema so that the wire format carries both the `payload`
+ * (the handler's actual return value) and `metadata` (server-driven cache invalidation keys).
+ * Transparent to users: the server handler returns the plain payload and the client receives
+ * the plain payload — wrapping/unwrapping is handled internally by the routing layer.
+ */
+export const CommandResponseWithMetaData = <S extends S.Top>(success: S) =>
+  S.Struct({ payload: success, metadata: CommandMetaData })
+
+/**
+ * Wraps a command's failure schema so that the wire format carries both the `error`
+ * (the handler's actual failure value) and `metadata` (server-driven cache invalidation keys
+ * accumulated thus far before the failure occurred).
+ * Transparent to users: the server handler fails with the plain error and the client receives
+ * the plain error — wrapping/unwrapping is handled internally by the routing layer.
+ */
+export const CommandFailureWithMetaData = <E extends S.Top>(error: E) =>
+  S.Struct({ _tag: S.Literal("CommandFailureWithMetaData"), error, metadata: CommandMetaData })
+
+/**
+ * Stream chunk schema for stream responses with metadata.
+ * Each item is either a data value, an intermediate "metadata" signal carrying cache
+ * invalidation keys accumulated since the previous drain, or a final "done" signal.
+ * Transparent to users: stream handlers return plain values and clients receive plain values —
+ * wrapping/unwrapping is handled internally by the routing layer.
+ *
+ * The "done" chunk is always the last item in the stream and carries any remaining invalidation
+ * keys. An optional "metadata" chunk may appear after any "value" chunk and carries keys
+ * accumulated since the last drain (V3: mid-stream invalidation).
+ */
+export const StreamResponseChunk = <S extends S.Top>(success: S) =>
+  S.Union([
+    S.Struct({ _tag: S.Literal("value"), value: success }),
+    S.Struct({ _tag: S.Literal("metadata"), metadata: CommandMetaData }),
+    S.Struct({ _tag: S.Literal("done"), metadata: CommandMetaData })
+  ])
+
+export type StreamResponseChunk<A> =
+  | { readonly _tag: "value"; readonly value: A }
+  | { readonly _tag: "metadata"; readonly metadata: CommandMetaData }
+  | { readonly _tag: "done"; readonly metadata: CommandMetaData }
+
+/**
+ * Stream chunk schema for stream failures with metadata.
+ * Used to signal a stream failure while still carrying cache invalidation keys
+ * accumulated thus far.
+ */
+export const StreamFailureChunk = <E extends S.Top>(error: E) =>
+  S.Struct({ _tag: S.Literal("error"), error, metadata: CommandMetaData })
+
+export type StreamFailureChunk<E> = { readonly _tag: "error"; readonly error: E; readonly metadata: CommandMetaData }
+
+/**
+ * Context annotation for declaring static cache invalidation keys on a low-level `Rpc` definition.
+ * These keys are always included in the command response metadata, regardless of the handler logic.
+ *
+ * Prefer using `makeQueryKey` over raw string arrays to stay in sync with the actual query
+ * definitions without manual string maintenance:
+ *
+ * ```ts
+ * import { makeQueryKey } from "effect-app/client"
+ * import { Invalidation } from "effect-app/rpc"
+ * import * as UserRsc from "../User/index.js"  // separate module to avoid circular deps
+ *
+ * class UpdateProfile extends Rpc.make("UpdateProfile", { ... })
+ *   .annotate(Invalidation.Invalidates, [makeQueryKey(UserRsc.GetMe), makeQueryKey(UserRsc.GetProfile)]) {}
+ * ```
+ *
+ * **Circular dependency note:** if mutations and queries live in the same file you may hit a
+ * circular reference at evaluation time. The idiomatic fix is to move mutations into their own
+ * module (e.g. `User/mutations.ts`) that directly imports the relevant query classes rather than
+ * re-exporting them through a barrel.
+ *
+ * For the higher-level `Command`/`Query` builders from `makeRpcClient`, use the
+ * `invalidatesQueries` callback argument instead (it receives the same query keys at runtime).
+ */
+export const Invalidates = Context.Reference<ReadonlyArray<InvalidationKey>>(
+  "effect-app/rpc/Invalidates",
+  { defaultValue: () => [] }
+)
+export type Invalidates = typeof Invalidates
+
+/** The shape of the per-request service that accumulates invalidation keys. */
+export interface InvalidationSetService {
+  readonly add: (key: InvalidationKey) => Effect.Effect<void>
+  readonly get: Effect.Effect<ReadonlyArray<InvalidationKey>>
+  /**
+   * V3: Reads all currently accumulated keys and resets the bucket to empty.
+   * Used by the stream routing layer to emit intermediate "metadata" chunks
+   * without re-sending keys that have already been forwarded to the client.
+   */
+  readonly drain: Effect.Effect<ReadonlyArray<InvalidationKey>>
+}
+
+/**
+ * Request-scoped service for accumulating invalidation keys dynamically inside a handler.
+ * Provided by `InvalidationMiddlewareLive` for every RPC call; has a no-op default so it is
+ * safe to use even when the HTTP middleware is absent (tests, workers, etc.).
+ *
+ * Use `InvalidationSet.use(_ => _.add(key))` (or `.useSync` for non-Effect callbacks) as a
+ * shorthand instead of yielding the service manually.
+ *
+ * Prefer `makeQueryKey` over raw string arrays so invalidation keys stay in sync with the
+ * actual query definitions automatically:
+ *
+ * ```ts
+ * import { makeQueryKey } from "effect-app/client"
+ * import * as Effect from "effect/Effect"
+ * import { Invalidation } from "effect-app/rpc"
+ * import * as CartRsc from "../Cart/queries.js"
+ * import * as UserRsc from "../User/queries.js"
+ *
+ * const handler = Effect.fnUntraced(function*(req: UpdateCartRequest) {
+ *   const cart = yield* CartRepo.save(req.cart)
+ *
+ *   // Stage 1 – unconditional: always invalidate after saving
+ *   yield* Invalidation.InvalidationSet.use(_ => _.add(makeQueryKey(UserRsc.GetMe)))
+ *
+ *   // Stage 2 – conditional: only if the cart changed state
+ *   if (cart.isCheckedOut) {
+ *     yield* Invalidation.InvalidationSet.use(_ => _.add(makeQueryKey(CartRsc.GetCartStats)))
+ *   }
+ *
+ *   return cart
+ * })
+ * ```
+ *
+ * You can combine static (`Invalidates` annotation) and dynamic (`InvalidationSet.use`) keys:
+ * the annotation pre-populates the set before the handler runs; dynamic additions accumulate
+ * throughout the handler. All keys are included in the command response metadata.
+ */
+export const InvalidationSet = Context.Reference<InvalidationSetService>(
+  "effect-app/rpc/InvalidationSet",
+  {
+    defaultValue: () => ({
+      add: (_key: InvalidationKey) => Effect.void,
+      get: Effect.succeed([] as ReadonlyArray<InvalidationKey>),
+      drain: Effect.succeed([] as ReadonlyArray<InvalidationKey>)
+    })
+  }
+)
+export type InvalidationSet = typeof InvalidationSet
+
+/** Creates a fresh `InvalidationSet` implementation backed by a `Ref`. */
+export const makeInvalidationSet = (ref: Ref.Ref<ReadonlyArray<InvalidationKey>>): InvalidationSetService => ({
+  add: (key) => Ref.update(ref, (keys) => [...keys, key]),
+  get: Ref.get(ref),
+  drain: Ref.getAndSet(ref, [])
+})
+
+/**
+ * `Rpc.Custom` definition for command RPCs that wrap the success/error schemas
+ * with `CommandResponseWithMetaData` / `CommandFailureWithMetaData`. The wrap
+ * lets server forward accumulated invalidation keys on both success and
+ * handler-thrown failure paths. Middleware-thrown errors bypass the wrap
+ * (the handler never ran, so no metadata) and flow raw at the Cause level —
+ * the client decodes them via the `rpc.middlewares[*].error` failure-union
+ * channel of `Rpc.exitSchema`.
+ */
+// eslint-disable-next-line import/namespace
+export interface CommandRpc extends Rpc.Custom {
+  readonly out: Rpc.Custom.Out<
+    ReturnType<typeof CommandResponseWithMetaData<this["success"] & S.Top>>,
+    ReturnType<typeof CommandFailureWithMetaData<this["error"] & S.Top>>
+  >
+}
+
+/**
+ * Custom Rpc constructor for command RPCs.
+ * Wraps the success schema with `CommandResponseWithMetaData` and the error
+ * schema with `CommandFailureWithMetaData`.
+ */
+export const makeCommandRpc = Rpc.custom<CommandRpc>(({ defect, error, success }) => ({
+  success: CommandResponseWithMetaData(success),
+  error: CommandFailureWithMetaData(error),
+  defect
+}))
+
+/**
+ * `Rpc.Custom` definition for stream RPCs that wrap the success/error schemas
+ * with `StreamResponseChunk` / `StreamFailureChunk`.
+ */
+// eslint-disable-next-line import/namespace
+export interface StreamRpc extends Rpc.Custom {
+  readonly out: Rpc.Custom.Out<
+    ReturnType<typeof StreamResponseChunk<this["success"] & S.Top>>,
+    ReturnType<typeof StreamFailureChunk<this["error"] & S.Top>>
+  >
+}
+
+/**
+ * Custom Rpc constructor for stream RPCs.
+ * Wraps the success schema with `StreamResponseChunk` and
+ * the error schema with `StreamFailureChunk`.
+ */
+export const makeStreamRpc = Rpc.custom<StreamRpc>(({ defect, error, success }) => ({
+  success: StreamResponseChunk(success),
+  error: StreamFailureChunk(error),
+  defect
+}))

package/src/rpc/MiddlewareMaker.ts

@@ -1,14 +1,15 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { Effect, Layer, type Schema, Schema as S, type Scope, ServiceMap } from "effect"
 import { type NonEmptyArray, type NonEmptyReadonlyArray } from "effect/Array"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as S from "effect/Schema"
+import type * as Scope from "effect/Scope"
 import { type Simplify } from "effect/Types"
 import { Rpc, type RpcGroup, type RpcSchema } from "effect/unstable/rpc"
 import { type HandlersFrom } from "effect/unstable/rpc/RpcGroup"
-import { type RequestId } from "effect/unstable/rpc/RpcMessage"
-import { type HttpHeaders } from "../http.js"
+import * as Context from "../Context.js"
 import { PreludeLogger } from "../logger.js"
 import { type TypeTestId } from "../TypeTest.js"
-import { typedValuesOf } from "../utils.js"
 import { type GetContextConfig, type RequestContextMapTagAny, type RpcContextMap } from "./RpcContextMap.js"
 import { type AddMiddleware, type AnyDynamic, type RpcDynamic, type RpcMiddlewareV4, type TagClassAny } from "./RpcMiddleware.js"
 import * as RpcMiddlewareX from "./RpcMiddleware.js"
@@ -61,13 +62,13 @@ export interface MiddlewareMaker<
     }
   >
 {
-  readonly layer: Layer.Layer<Self, never, ServiceMap.Service.Identifier<MiddlewareProviders[number]>>
+  readonly layer: Layer.Layer<Self, never, Context.Service.Identifier<MiddlewareProviders[number]>>
   readonly requestContext: RequestContextTag<RequestContextMap>
   readonly requestContextMap: RequestContextMap
 }
 
 export interface RequestContextTag<RequestContextMap extends Record<string, RpcContextMap.Any>>
-  extends ServiceMap.Service<"RequestContextConfig", GetContextConfig<RequestContextMap>>
+  extends Context.Service<"RequestContextConfig", GetContextConfig<RequestContextMap>>
 {}
 
 export namespace MiddlewareMaker {
@@ -169,9 +170,9 @@ export interface BuildingMiddleware<
 > {
   rpc: <
     const Tag extends string,
-    Payload extends Schema.Top | Schema.Struct.Fields = typeof Schema.Void,
-    Success extends Schema.Top = typeof Schema.Void,
-    Error extends Schema.Top = typeof Schema.Never,
+    Payload extends S.Top | S.Struct.Fields = typeof S.Void,
+    Success extends S.Top = typeof S.Void,
+    Error extends S.Top = typeof S.Never,
     const Stream extends boolean = false,
     Config extends GetContextConfig<RequestContextMap> = {}
   >(tag: Tag, options?: {
@@ -180,16 +181,16 @@ export interface BuildingMiddleware<
     readonly error?: Error
     readonly stream?: Stream
     readonly config?: Config
-    readonly primaryKey?: [Payload] extends [Schema.Struct.Fields] ? ((
-        payload: Payload extends Schema.Struct.Fields ? Simplify<Schema.Struct<Payload>["Type"]> : Payload["Type"]
+    readonly primaryKey?: [Payload] extends [S.Struct.Fields] ? ((
+        payload: Payload extends S.Struct.Fields ? Simplify<S.Struct<Payload>["Type"]> : Payload["Type"]
       ) => string)
       : never
   }) =>
     & Rpc.Rpc<
       Tag,
-      Payload extends Schema.Struct.Fields ? Schema.Struct<Payload> : Payload,
+      Payload extends S.Struct.Fields ? S.Struct<Payload> : Payload,
       Stream extends true ? RpcSchema.Stream<Success, Error> : Success,
-      Stream extends true ? typeof Schema.Never : Error
+      Stream extends true ? typeof S.Never : Error
     >
     & { readonly config: Config }
 
@@ -258,10 +259,10 @@ export type MiddlewaresBuilder<
     : { new(_: never): {} }
     : { new(_: never): {} })
 
-const middlewareMaker = <
+const middlewareMaker = Effect.fnUntraced(function*<
   MiddlewareProviders extends ReadonlyArray<MiddlewareMaker.Any>
->(middlewares: MiddlewareProviders): Effect.Effect<
-  RpcMiddlewareV4<
+>(middlewares: MiddlewareProviders) {
+  type Middleware = RpcMiddlewareV4<
     MiddlewareMaker.ManyProvided<MiddlewareProviders>,
     MiddlewareMaker.ManyErrors<MiddlewareProviders>,
     Exclude<
@@ -270,42 +271,32 @@ const middlewareMaker = <
     > extends never ? never
       : Exclude<MiddlewareMaker.ManyRequired<MiddlewareProviders>, MiddlewareMaker.ManyProvided<MiddlewareProviders>>
   >
-> => {
+  type Next = Parameters<Middleware>[0]
+  type Options = Parameters<Middleware>[1]
+
   // we want to run them in reverse order because latter middlewares will provide context to former ones
-  middlewares = middlewares.toReversed() as any
-
-  return Effect.gen(function*() {
-    const context = yield* Effect.services()
-
-    // returns a Effect/RpcMiddlewareV4 with Scope.Scope in requirements
-    // v4: wrap middleware takes (effect, options) as two params instead of a single options bag
-    return (
-      next: Effect.Effect<any, any, any>,
-      options: {
-        readonly clientId: number
-        readonly requestId: RequestId
-        readonly rpc: Rpc.AnyWithProps
-        readonly payload: unknown
-        readonly headers: HttpHeaders.Headers
-      }
-    ) => {
-      // we start with the actual handler
-      let handler = next
-
-      // inspired from Effect/RpcMiddleware
-      for (const tag of middlewares) {
-        // use the tag to get the middleware from context
-        const middleware = ServiceMap.getUnsafe(context, tag)
-
-        // wrap the current handler, allowing the middleware to run before and after it
-        handler = PreludeLogger.logDebug("Applying middleware wrap " + tag.key).pipe(
-          Effect.andThen(middleware(handler, options))
-        ) as any
-      }
-      return handler
+  const reversed = middlewares.toReversed()
+  const context = yield* Effect.context()
+
+  // returns a Effect/RpcMiddlewareV4 with Scope.Scope in requirements
+  // v4: wrap middleware takes (effect, options) as two params instead of a single options bag
+  return (next: Next, options: Options) => {
+    // we start with the actual handler
+    let handler = next
+
+    // inspired from Effect/RpcMiddleware
+    for (const tag of reversed) {
+      // use the tag to get the middleware from context
+      const middleware = Context.getUnsafe(context, tag)
+
+      // wrap the current handler, allowing the middleware to run before and after it
+      handler = PreludeLogger.logDebug("Applying middleware wrap " + tag.key).pipe(
+        Effect.andThen(middleware(handler, options))
+      ) as any
     }
-  }) as any
-}
+    return handler
+  }
+})
 
 const makeMiddlewareBasic = <Self>() =>
 // by setting RequestContextMap beforehand, execute contextual typing does not fuck up itself to anys
@@ -321,7 +312,26 @@ const makeMiddlewareBasic = <Self>() =>
   // reverse middlewares and wrap one after the other
   const middleware = middlewareMaker(make)
 
-  const failures = make.map((_) => _.error).filter(Boolean)
+  // Per-middleware error: union of the static `error` on the tag (if any) AND
+  // the rcm config entry pointed at by the middleware's `dynamic.key` (if any).
+  // Reason: middlewares declared with `dynamic: RequestContextMap.get("foo")`
+  // don't set a static `error` field — at runtime their `.error` defaults to
+  // `S.Never`. Without pulling from rcm, the composite middleware's
+  // `.error` collapses to `Never`, and `Rpc.exitSchema` (which walks
+  // `rpc.middlewares[*].error` to build the wire failure union) can't decode
+  // the actual middleware-thrown error type. Critical for stream rpcs whose
+  // top-level `errorSchema` is force-set to `Never` by effect-rpc.
+  const isMeaningfulError = (e: S.Top | undefined): e is S.Top => e !== undefined && e !== null && e !== S.Never
+  const rcmRecord = rcm as Record<string, RpcContextMap.Any>
+  const failures: Array<S.Top> = make.flatMap((_) => {
+    const out: Array<S.Top> = []
+    if (isMeaningfulError(_.error)) out.push(_.error)
+    const key = _.dynamic?.key as string | undefined
+    if (key && rcmRecord[key] && isMeaningfulError(rcmRecord[key].error)) {
+      out.push(rcmRecord[key].error)
+    }
+    return out
+  })
   const provides = make.flatMap((_) => !_.provides ? [] : Array.isArray(_.provides) ? _.provides : [_.provides])
   const requires = make
     .flatMap((_) => !_.requires ? [] : Array.isArray(_.requires) ? _.requires : [_.requires])
@@ -357,17 +367,18 @@ const makeMiddlewareBasic = <Self>() =>
     .effect(
       MiddlewareMaker,
       middleware as Effect.Effect<
-        any,
-        Effect.Error<typeof middleware>,
-        Effect.Services<typeof middleware>
+        any
       >
+      // todo; they dont change the type..
+      //  Effect.Error<typeof middleware>,
+      //  Effect.Services<typeof middleware>
     )
 
   // add to the tag a default implementation
   return Object.assign(MiddlewareMaker, {
     layer,
     // tag to be used to retrieve the RequestContextConfig from Rpc annotations
-    requestContext: ServiceMap.Service<"RequestContextConfig", GetContextConfig<RequestContextMap>>(
+    requestContext: Context.Service<"RequestContextConfig", GetContextConfig<RequestContextMap>>(
       "RequestContextConfig"
     ),
     requestContextMap: rcm
@@ -379,8 +390,8 @@ export const Tag = <Self>() =>
   const Id extends string,
   RequestContextMap extends RequestContextMapTagAny
 >(id: Id, rcm: RequestContextMap): MiddlewaresBuilder<Self, Id, RequestContextMap["config"]> => {
-  let allMiddleware: MiddlewareMaker.Any[] = []
-  const requestContext = ServiceMap.Service<"RequestContextConfig", GetContextConfig<RequestContextMap["config"]>>(
+  const allMiddleware: MiddlewareMaker.Any[] = []
+  const requestContext = Context.Service<"RequestContextConfig", GetContextConfig<RequestContextMap["config"]>>(
     "RequestContextConfig"
   )
   const it = {
@@ -388,9 +399,9 @@ export const Tag = <Self>() =>
     // rpc with config
     rpc: <
       const Tag extends string,
-      Payload extends Schema.Top | Schema.Struct.Fields = typeof Schema.Void,
-      Success extends Schema.Top = typeof Schema.Void,
-      Error extends Schema.Top = typeof Schema.Never,
+      Payload extends S.Top | S.Struct.Fields = typeof S.Void,
+      Success extends S.Top = typeof S.Void,
+      Error extends S.Top = typeof S.Never,
       const Stream extends boolean = false,
       Config extends GetContextConfig<RequestContextMap["config"]> = {}
     >(tag: Tag, options?: {
@@ -399,35 +410,32 @@ export const Tag = <Self>() =>
       readonly error?: Error
       readonly stream?: Stream
       readonly config?: Config
-      readonly primaryKey?: [Payload] extends [Schema.Struct.Fields] ? ((
-          payload: Payload extends Schema.Struct.Fields ? Simplify<Schema.Struct<Payload>["Type"]> : Payload["Type"]
+      readonly primaryKey?: [Payload] extends [S.Struct.Fields] ? ((
+          payload: Payload extends S.Struct.Fields ? Simplify<S.Struct<Payload>["Type"]> : Payload["Type"]
         ) => string)
         : never
     }):
       & Rpc.Rpc<
         Tag,
-        Payload extends Schema.Struct.Fields ? Schema.Struct<Payload> : Payload,
+        Payload extends S.Struct.Fields ? S.Struct<Payload> : Payload,
         // TODO: enhance `Error`. type based on middleware config.
         Stream extends true ? RpcSchema.Stream<Success, Error> : Success,
-        Stream extends true ? typeof Schema.Never : Error
+        Stream extends true ? typeof S.Never : Error
       >
       & { config: Config } =>
     {
       const config = options?.config ?? {} as Config
 
-      // based on the config, we must enhance (union) or set failures.
-      // TODO: we should only include errors that are relevant based on the middleware config.ks
-      const error = options?.error
-      const errors = typedValuesOf(rcm.config).map((_) => _.error).filter((_) => _ && _ !== S.Never) // TODO: only the errors relevant based on config
-      const allErrors = error ? [error, ...errors] : errors
-      const [firstError, ...restErrors] = allErrors
-      const newError = firstError ? S.Union([firstError, ...restErrors]) : S.Never
-
+      // The rpc's `error` schema carries ONLY the request's own declared errors.
+      // Middleware errors (rcm-derived) reach the wire via the middleware tag
+      // attached to the rpc group later (`RpcGroup.middleware(...)` at the
+      // routing/client level), and are unioned into the failure schema by
+      // `Rpc.exitSchema`'s `rpc.middlewares[*].error` walk.
       // @ts-expect-error — TypeScript can't prove Simplify<T> ≡ { [K in keyof T]: T[K] } for unresolved generics (primaryKey)
       const rpc = Rpc.make(tag, {
         ...options?.payload !== undefined ? { payload: options.payload } : {},
         ...options?.success !== undefined ? { success: options.success } : {},
-        error: newError,
+        ...options?.error !== undefined ? { error: options.error } : {},
         ...options?.stream !== undefined ? { stream: options.stream } : {},
         ...options?.primaryKey !== undefined ? { primaryKey: options.primaryKey } : {}
       }) as any
@@ -437,7 +445,7 @@ export const Tag = <Self>() =>
     middleware: (...middlewares: any[]) => {
       for (const mw of middlewares) {
         // recall that we run middlewares in reverse order
-        allMiddleware = [mw, ...allMiddleware]
+        allMiddleware.unshift(mw)
       }
       return allMiddleware.filter((m) => !!m.dynamic).length !== Object.keys(rcm.config).length
         // for sure, until all the dynamic middlewares are provided it's non sensical to call makeMiddlewareBasic