@effect-app/infra 4.0.0-beta.99 → 4.0.0

package/test/rpc-context-map-streaming.test.ts

@@ -0,0 +1,265 @@
+/**
+ * E2E test for commit bb3f51d03 — `fix(infra): bind ContextMap to request scope
+ * for SSE streams`.
+ *
+ * Background
+ * ----------
+ *   The RpcServer returns `HttpServerResponse.stream(...)` for streaming RPC
+ *   resources. The body of that response keeps producing chunks AFTER the
+ *   outer Effect that built the response has returned. `RequestContextMiddleware`
+ *   provisions `ContextMapContainer` for the request. The acquireRelease
+ *   inside `ContextMapContainer.layer` calls `clear()` on finalize, wiping
+ *   the etag map and the per-request resolver/store cache.
+ *
+ *   If that layer is built against a sub-scope of the outer Effect (the
+ *   pre-fix behaviour: `Effect.provide(layer)`), the finalizer fires as soon
+ *   as the middleware Effect returns the HttpServerResponse — i.e. between
+ *   "handler done" and "first chunk written" — wiping ContextMap state that
+ *   later chunks still need. In production this surfaces as spurious
+ *   OptimisticConcurrencyException on writes that follow a streaming read.
+ *
+ *   The fix binds the layer to the ambient request scope via
+ *   `provideOnRequestScope`, so `clear()` only runs once the response body
+ *   has fully drained.
+ *
+ * Reproduction strategy
+ * ---------------------
+ *   - Mirror the production wiring: apply `RequestContextMiddleware` to the
+ *     RPC router (see `boilerplate/api/src/router.ts`).
+ *   - The stream handler sets an etag on the ContextMap BEFORE returning the
+ *     Stream value.
+ *   - The Stream emits three values 100ms apart; each emission reads back the
+ *     etag via `getContextMap` and yields 1 if the value is still present,
+ *     0 otherwise.
+ *   - Expectation: [1, 1, 1]. If the layer's `clear()` runs mid-stream the
+ *     later chunks observe an empty map and the assertion fails (typically
+ *     with [1, 0, 0] or [0, 0, 0]).
+ */
+import { NodeHttpServer } from "@effect/platform-node"
+import { expect, it } from "@effect/vitest"
+import { ApiClientFactory, makeRpcClient } from "effect-app/client"
+import { HttpRouter, HttpServer } from "effect-app/http"
+import { DefaultGenericMiddlewares } from "effect-app/middleware"
+import { MiddlewareMaker } from "effect-app/rpc"
+import * as S from "effect-app/Schema"
+import { getContextMap } from "effect-app/Store"
+import * as Effect from "effect/Effect"
+import { FetchHttpClient } from "effect/http"
+import * as Layer from "effect/Layer"
+import * as NetAddress from "effect/net/NetAddress"
+import * as Option from "effect/Option"
+import { RpcSerialization } from "effect/rpc"
+import * as Stream from "effect/Stream"
+import { createServer } from "http"
+import { RequestContextMiddleware } from "../src/internal/RequestContextMiddleware.js"
+import { makeRouter } from "../src/routing.js"
+import { DefaultGenericMiddlewaresLive } from "../src/routing/middleware.js"
+import { AllowAnonymous, AllowAnonymousLive, RequestContextMap, RequireRoles, RequireRolesLive, SomeElseMiddleware, SomeElseMiddlewareLive, SomeService, Test, TestLive } from "./fixtures.js"
+
+// ---------------------------------------------------------------------------
+// Middleware — mirrors AppMiddleware shape used by the other rpc e2e tests.
+// ---------------------------------------------------------------------------
+
+class AppMiddleware extends MiddlewareMaker
+  .Tag<AppMiddleware>()("AppMiddleware", RequestContextMap)
+  .middleware(RequireRoles, Test)
+  .middleware(AllowAnonymous)
+  .middleware(SomeElseMiddleware)
+  .middleware(...DefaultGenericMiddlewares)
+{
+  static Default = this.layer.pipe(
+    Layer.provide(
+      [
+        RequireRolesLive.pipe(Layer.provide(SomeService.Default)),
+        AllowAnonymousLive,
+        TestLive,
+        SomeElseMiddlewareLive,
+        DefaultGenericMiddlewaresLive
+      ] as const
+    )
+  )
+}
+
+const { Router, matchAll } = makeRouter(AppMiddleware.Default)
+
+// ---------------------------------------------------------------------------
+// Resource — single streaming command that exercises ContextMap mid-stream.
+// ---------------------------------------------------------------------------
+
+const { TaggedRequestFor } = makeRpcClient(AppMiddleware)
+const Req = TaggedRequestFor("CtxMap")
+
+class StreamEtag extends Req.Command<StreamEtag>()("StreamEtag", {}, {
+  stream: true,
+  allowAnonymous: true,
+  success: S.Number
+}) {}
+
+// Per-request isolation probes: each handler writes a caller-supplied value to
+// the SHARED key, then emits 3 chunks each re-reading the SHARED key. If two
+// concurrent requests share a ContextMap, the second writer overwrites the
+// first and the first request observes the wrong value mid-stream.
+class StreamWithEtag extends Req.Command<StreamWithEtag>()("StreamWithEtag", {
+  value: S.String
+}, {
+  stream: true,
+  allowAnonymous: true,
+  success: S.String
+}) {}
+
+class ReadEtagOnce extends Req.Query<ReadEtagOnce>()("ReadEtagOnce", {}, {
+  allowAnonymous: true,
+  success: S.String
+}) {}
+
+const Rsc = { StreamEtag, StreamWithEtag, ReadEtagOnce }
+
+// Distinct constants so an assertion failure points squarely at "the etag
+// the handler wrote was no longer there when later chunks ran".
+const ETAG_ID = "ctxmap-test-id"
+const ETAG_VALUE = "v1"
+const SHARED_KEY = "ctxmap-shared-key"
+const MISSING = "<missing>"
+
+const router = Router(Rsc)({
+  *effect(match) {
+    return match({
+      StreamEtag: () =>
+        Effect
+          .gen(function*() {
+            // 1) Acquire the request-scoped ContextMap. Fails (dies) if the
+            //    container is still the default "root" — which would mean
+            //    RequestContextMiddleware did not run for this request.
+            const ctxMap = yield* getContextMap.pipe(Effect.orDie)
+            // 2) Seed an etag BEFORE handing back the Stream. This write is
+            //    what the per-chunk readers below verify.
+            ctxMap.set(ETAG_ID, ETAG_VALUE)
+            // 3) Emit three values 100ms apart so chunks are produced AFTER
+            //    the outer Effect that built the response has returned. Each
+            //    emission re-reads the etag from the request-scoped ContextMap.
+            return Stream.fromIterable([0, 1, 2]).pipe(
+              Stream.mapEffect(() =>
+                Effect.sleep("100 millis").pipe(
+                  Effect.flatMap(() => getContextMap.pipe(Effect.orDie)),
+                  Effect.map((m) => m.get(ETAG_ID) === ETAG_VALUE ? 1 : 0)
+                )
+              )
+            )
+          })
+          .pipe(Stream.unwrap),
+      StreamWithEtag: ({ value }: { readonly value: string }) =>
+        Effect
+          .gen(function*() {
+            const ctxMap = yield* getContextMap.pipe(Effect.orDie)
+            ctxMap.set(SHARED_KEY, value)
+            return Stream.fromIterable([0, 1, 2]).pipe(
+              Stream.mapEffect(() =>
+                Effect.sleep("100 millis").pipe(
+                  Effect.flatMap(() => getContextMap.pipe(Effect.orDie)),
+                  Effect.map((m) => m.get(SHARED_KEY) ?? MISSING)
+                )
+              )
+            )
+          })
+          .pipe(Stream.unwrap),
+      ReadEtagOnce: () => getContextMap.pipe(Effect.orDie, Effect.map((m) => m.get(SHARED_KEY) ?? MISSING))
+    })
+  }
+})
+
+const RpcRouterLayer = matchAll({ router })
+
+// ---------------------------------------------------------------------------
+// HTTP wiring — fresh server on a loopback port per `it.live`. The critical
+// difference vs. rpc-stream-fullstack: we apply `RequestContextMiddleware`
+// here, exactly as the production boilerplate does, so the fix code path
+// is what runs.
+// ---------------------------------------------------------------------------
+
+const NodeServerLayer = NodeHttpServer.layer(() => createServer(), { port: 0 })
+
+const RequestContextMiddlewareLayer = HttpRouter.middleware(RequestContextMiddleware()).layer
+
+const ServerLayer = HttpRouter
+  .serve(
+    RpcRouterLayer.pipe(Layer.provide(RequestContextMiddlewareLayer))
+  )
+  .pipe(
+    Layer.provide(NodeServerLayer),
+    Layer.provide(RpcSerialization.layerNdjson)
+  )
+
+const ClientLayer = Layer
+  .unwrap(
+    Effect.gen(function*() {
+      const server = yield* HttpServer.HttpServer
+      const addr = server.address
+      if (NetAddress.isUnixPathAddress(addr)) {
+        return yield* Effect.die(new Error("expected inet address"))
+      }
+      const host = NetAddress.isUnspecified(addr.address) ? "127.0.0.1" : NetAddress.formatUrlHost(addr.address)
+      const url = `http://${host}:${addr.port}`
+      return ApiClientFactory
+        .layer({ url, headers: Option.none() })
+        .pipe(Layer.provide(FetchHttpClient.layer))
+    })
+  )
+  .pipe(Layer.provide(NodeServerLayer))
+
+const TestLayer = Layer.mergeAll(ServerLayer, ClientLayer)
+
+// ---------------------------------------------------------------------------
+// Test
+// ---------------------------------------------------------------------------
+
+it.live(
+  "ContextMap survives mid-stream: etag set in handler is readable by every chunk",
+  Effect.fnUntraced(function*() {
+    const client = yield* ApiClientFactory.makeFor(Layer.empty)(Rsc)
+    const values = yield* Stream.runCollect(client.StreamEtag.handler())
+    // All three chunks emit 1 → the etag was still readable when each chunk
+    // executed. If the layer-bound ContextMap's `clear()` finalizer fired
+    // mid-stream (the pre-fix behaviour), later chunks would emit 0.
+    expect(values).toStrictEqual([1, 1, 1])
+  }, Effect.provide(TestLayer)),
+  { timeout: 10_000 }
+)
+
+it.live(
+  "succeeding requests get a fresh ContextMap: request N+1 cannot see request N's writes",
+  Effect.fnUntraced(function*() {
+    const client = yield* ApiClientFactory.makeFor(Layer.empty)(Rsc)
+    // 1st request writes SHARED_KEY = "first" and drains its stream so its
+    // request scope (and ContextMap) is closed before request 2 starts.
+    const first = yield* Stream.runCollect(client.StreamWithEtag.handler({ value: "first" }))
+    expect(first).toStrictEqual(["first", "first", "first"])
+    // 2nd request must NOT observe the previous request's value at any point.
+    const peek = yield* client.ReadEtagOnce.handler()
+    expect(peek).toBe(MISSING)
+    // 3rd request writes a different value and drains; must not be polluted by request 1.
+    const third = yield* Stream.runCollect(client.StreamWithEtag.handler({ value: "third" }))
+    expect(third).toStrictEqual(["third", "third", "third"])
+  }, Effect.provide(TestLayer)),
+  { timeout: 10_000 }
+)
+
+it.live(
+  "overlapping requests get isolated ContextMaps: concurrent streams see only their own writes",
+  Effect.fnUntraced(function*() {
+    const client = yield* ApiClientFactory.makeFor(Layer.empty)(Rsc)
+    // Two streams in flight at the same time, each writing the SAME key with a
+    // different value. With per-request maps each stream reads back only its
+    // own value across all chunks. With a shared map the later writer's value
+    // would leak into the earlier stream's later chunks.
+    const [a, b] = yield* Effect.all(
+      [
+        Stream.runCollect(client.StreamWithEtag.handler({ value: "alpha" })),
+        Stream.runCollect(client.StreamWithEtag.handler({ value: "beta" }))
+      ],
+      { concurrency: "unbounded" }
+    )
+    expect(a).toStrictEqual(["alpha", "alpha", "alpha"])
+    expect(b).toStrictEqual(["beta", "beta", "beta"])
+  }, Effect.provide(TestLayer)),
+  { timeout: 10_000 }
+)

package/test/rpc-e2e-invalidation.test.ts

@@ -0,0 +1,421 @@
+/**
+ * E2E tests for the invalidation key flow exercised end-to-end via the
+ * production wrap/unwrap path:
+ *
+ *   server: routing.ts wraps command success with `CommandResponseWithMetaData`
+ *           and handler-thrown failure with `CommandFailureWithMetaData`;
+ *           routing wraps stream values into `{_tag:"value"|"metadata"|"done"}`
+ *           chunks. `InvalidationSet.use(...)` inside a handler accumulates keys.
+ *   client: apiClientFactory unwraps both envelopes and forwards keys to
+ *           `InvalidationKeysFromServer`.
+ *
+ * Transport is real HTTP (NodeHttpServer on a loopback port) so the wire
+ * encoding is exercised too.
+ */
+import { NodeHttpServer } from "@effect/platform-node"
+import { expect, it } from "@effect/vitest"
+import { ApiClientFactory, DataDependencies, InvalidationKeysFromServer, InvalidStateError, makeInvalidationKeysService, makeRpcClient, OptimisticConcurrencyException } from "effect-app/client"
+import * as Context from "effect-app/Context"
+import { HttpRouter, HttpServer } from "effect-app/http"
+import { DefaultGenericMiddlewares } from "effect-app/middleware"
+import { makeRepo, RepositoryRegistryLive } from "effect-app/Model"
+import { Invalidation, MiddlewareMaker } from "effect-app/rpc"
+import * as S from "effect-app/Schema"
+import { TaggedErrorClass } from "effect-app/Schema"
+import * as Cause from "effect/Cause"
+import * as Effect from "effect/Effect"
+import * as Exit from "effect/Exit"
+import { FetchHttpClient } from "effect/http"
+import * as Layer from "effect/Layer"
+import * as NetAddress from "effect/net/NetAddress"
+import * as Option from "effect/Option"
+import * as Ref from "effect/Ref"
+import { RpcSerialization } from "effect/rpc"
+import * as Stream from "effect/Stream"
+import { createServer } from "http"
+import { RequestContextMiddleware } from "../src/internal/RequestContextMiddleware.js"
+import { makeRouter } from "../src/routing.js"
+import { DefaultGenericMiddlewaresLive } from "../src/routing/middleware.js"
+import { MemoryStoreLive } from "../src/Store/Memory.js"
+import { AllowAnonymous, AllowAnonymousLive, RequestContextMap, RequireRoles, RequireRolesLive, SomeElseMiddleware, SomeElseMiddlewareLive, SomeService, Test, TestLive } from "./fixtures.js"
+
+// ---------------------------------------------------------------------------
+// Middleware (mirrors AppMiddleware shape — same composite as other e2e tests).
+// ---------------------------------------------------------------------------
+
+class AppMiddleware extends MiddlewareMaker
+  .Tag<AppMiddleware>()("AppMiddleware", RequestContextMap)
+  .middleware(RequireRoles, Test)
+  .middleware(AllowAnonymous)
+  .middleware(SomeElseMiddleware)
+  .middleware(...DefaultGenericMiddlewares)
+{
+  static Default = this.layer.pipe(
+    Layer.provide(
+      [
+        RequireRolesLive.pipe(Layer.provide(SomeService.Default)),
+        AllowAnonymousLive,
+        TestLive,
+        SomeElseMiddlewareLive,
+        DefaultGenericMiddlewaresLive
+      ] as const
+    )
+  )
+}
+
+const { Router, matchAll } = makeRouter(AppMiddleware.Default)
+
+// ---------------------------------------------------------------------------
+// Resources
+// ---------------------------------------------------------------------------
+
+const DynamicKey: Invalidation.InvalidationKey = ["dynamic", "key"]
+const ExtraKey: Invalidation.InvalidationKey = ["extra", "key"]
+const StreamKey: Invalidation.InvalidationKey = ["stream", "key"]
+
+const { TaggedRequestFor } = makeRpcClient(AppMiddleware)
+const Req = TaggedRequestFor("Inv")
+
+class CmdBoom extends TaggedErrorClass<CmdBoom>()("CmdBoom", { reason: S.String }) {}
+
+class DoNothing extends Req.Command<DoNothing>()("DoNothing", {}, {
+  allowAnonymous: true,
+  success: S.Void
+}) {}
+
+class DoWithDynamicKey extends Req.Command<DoWithDynamicKey>()("DoWithDynamicKey", {}, {
+  allowAnonymous: true,
+  success: S.String
+}) {}
+
+class DoWithBothKeys extends Req.Command<DoWithBothKeys>()("DoWithBothKeys", {}, {
+  allowAnonymous: true,
+  success: S.Number
+}) {}
+
+class DoAndFail extends Req.Command<DoAndFail>()("DoAndFail", {}, {
+  allowAnonymous: true,
+  success: S.Void,
+  error: CmdBoom
+}) {}
+
+class StreamWithKey extends Req.Command<StreamWithKey>()("StreamWithKey", {}, {
+  stream: true,
+  allowAnonymous: true,
+  success: S.Number
+}) {}
+
+class StreamWithRepoWrite extends Req.Command<StreamWithRepoWrite>()("StreamWithRepoWrite", {}, {
+  stream: true,
+  allowAnonymous: true,
+  success: S.Number
+}) {}
+
+class RepoItem extends S.Class<RepoItem>("RepoItem")({
+  id: S.String,
+  label: S.String
+}) {}
+
+class GetRepoCount extends Req.Query<GetRepoCount>()("GetRepoCount", {}, {
+  allowAnonymous: true,
+  success: S.Number
+}) {}
+
+class SaveRepoItem extends Req.Command<SaveRepoItem>()("SaveRepoItem", {
+  id: S.String,
+  label: S.String
+}, {
+  allowAnonymous: true,
+  error: S.Union([InvalidStateError, OptimisticConcurrencyException]),
+  success: S.Void
+}) {}
+
+class RepoItems extends Context.Service<RepoItems>()("RepoItems", {
+  make: makeRepo("RepoItem", RepoItem, {})
+}) {
+  static Default = Layer.effect(this, this.make).pipe(
+    Layer.provide(Layer.merge(MemoryStoreLive, RepositoryRegistryLive))
+  )
+}
+
+// A second, unrelated repo — its writes must NOT invalidate a query that only read `RepoItem`.
+class OtherItem extends S.Class<OtherItem>("OtherItem")({
+  id: S.String,
+  label: S.String
+}) {}
+
+class SaveOtherItem extends Req.Command<SaveOtherItem>()("SaveOtherItem", {
+  id: S.String,
+  label: S.String
+}, {
+  allowAnonymous: true,
+  success: S.Void
+}) {}
+
+class OtherItems extends Context.Service<OtherItems>()("OtherItems", {
+  make: makeRepo("OtherItem", OtherItem, {})
+}) {
+  static Default = Layer.effect(this, this.make).pipe(
+    Layer.provide(Layer.merge(MemoryStoreLive, RepositoryRegistryLive))
+  )
+}
+
+const InvRsc = {
+  DoNothing,
+  DoWithDynamicKey,
+  DoWithBothKeys,
+  DoAndFail,
+  StreamWithKey,
+  StreamWithRepoWrite,
+  GetRepoCount,
+  SaveRepoItem,
+  SaveOtherItem
+}
+
+// ---------------------------------------------------------------------------
+// Controllers / router
+// ---------------------------------------------------------------------------
+
+const router = Router(InvRsc)({
+  dependencies: [RepoItems.Default, OtherItems.Default],
+  *effect(match) {
+    const repo = yield* RepoItems
+    const otherRepo = yield* OtherItems
+    return match({
+      DoNothing: () => Effect.void,
+      DoWithDynamicKey: Effect.fnUntraced(function*() {
+        yield* Invalidation.InvalidationSet.use((_) => _.add(DynamicKey))
+        return "done"
+      }),
+      DoWithBothKeys: Effect.fnUntraced(function*() {
+        yield* Invalidation.InvalidationSet.use((_) => _.add(DynamicKey))
+        yield* Invalidation.InvalidationSet.use((_) => _.add(ExtraKey))
+        return 99
+      }),
+      DoAndFail: Effect.fnUntraced(function*() {
+        yield* Invalidation.InvalidationSet.use((_) => _.add(DynamicKey))
+        return yield* Effect.fail(new CmdBoom({ reason: "intentional failure" }))
+      }),
+      StreamWithKey: () =>
+        Stream.fromIterable([1, 2, 3]).pipe(
+          Stream.tap(() => Invalidation.InvalidationSet.use((_) => _.add(StreamKey)))
+        ),
+      StreamWithRepoWrite: () =>
+        Stream.fromIterable([1, 2, 3]).pipe(
+          Stream.tap((n) => repo.save(new RepoItem({ id: String(n), label: "x" })).pipe(Effect.orDie))
+        ),
+      GetRepoCount: () => repo.all.pipe(Effect.map((_) => _.length), Effect.orDie),
+      SaveRepoItem: ({ id, label }) => repo.save(new RepoItem({ id, label })).pipe(Effect.orDie),
+      SaveOtherItem: ({ id, label }) => otherRepo.save(new OtherItem({ id, label })).pipe(Effect.orDie)
+    })
+  }
+})
+
+const RpcRouterLayer = matchAll({ router })
+
+// ---------------------------------------------------------------------------
+// HTTP wiring — fresh server on loopback per `it.live`.
+// ---------------------------------------------------------------------------
+
+const NodeServerLayer = NodeHttpServer.layer(() => createServer(), { port: 0 })
+
+const ServerLayer = HttpRouter
+  .serve(RpcRouterLayer.pipe(Layer.provide(HttpRouter.middleware(RequestContextMiddleware()).layer)))
+  .pipe(
+    Layer.provide(NodeServerLayer),
+    Layer.provide(RpcSerialization.layerNdjson)
+  )
+
+const ClientLayer = Layer
+  .unwrap(
+    Effect.gen(function*() {
+      const server = yield* HttpServer.HttpServer
+      const addr = server.address
+      if (NetAddress.isUnixPathAddress(addr)) {
+        return yield* Effect.die(new Error("expected inet address"))
+      }
+      const host = NetAddress.isUnspecified(addr.address) ? "127.0.0.1" : NetAddress.formatUrlHost(addr.address)
+      const url = `http://${host}:${addr.port}`
+      return ApiClientFactory
+        .layer({ url, headers: Option.none() })
+        .pipe(Layer.provide(FetchHttpClient.layer))
+    })
+  )
+  .pipe(Layer.provide(NodeServerLayer))
+
+const TestLayer = Layer.mergeAll(ServerLayer, ClientLayer)
+
+// Helper: provide a fresh `InvalidationKeysFromServer` and capture forwarded keys.
+const withCapture = <A, E, R>(eff: Effect.Effect<A, E, R>) =>
+  Effect.gen(function*() {
+    const ref = yield* Ref.make<ReadonlyArray<Invalidation.InvalidationKey>>([])
+    const svc = makeInvalidationKeysService(ref)
+    const result = yield* eff.pipe(Effect.provideService(InvalidationKeysFromServer, svc), Effect.exit)
+    return { result, keys: yield* Ref.get(ref) }
+  })
+
+const withDependencyCapture = <A, E, R>(eff: Effect.Effect<A, E, R>) =>
+  Effect.gen(function*() {
+    const readsRef = yield* Ref.make(DataDependencies.empty())
+    const writesRef = yield* Ref.make(DataDependencies.empty())
+    const svc = DataDependencies.makeDataDependencyRecorder(readsRef, writesRef)
+    const result = yield* eff.pipe(Effect.provideService(DataDependencies.DataDependencyRecorder, svc), Effect.exit)
+    return { result, dependencies: yield* svc.get }
+  })
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+it.live(
+  "command with no invalidation keys: caller sees raw payload, no keys forwarded",
+  Effect.fnUntraced(function*() {
+    const client = yield* ApiClientFactory.makeFor(Layer.empty)(InvRsc)
+    const { result, keys } = yield* withCapture(client.DoNothing.handler())
+    expect(Exit.isSuccess(result)).toBe(true)
+    expect(keys).toStrictEqual([])
+  }, Effect.provide(TestLayer)),
+  { timeout: 10_000 }
+)
+
+it.live(
+  "command with dynamic InvalidationSet.use: payload + key forwarded",
+  Effect.fnUntraced(function*() {
+    const client = yield* ApiClientFactory.makeFor(Layer.empty)(InvRsc)
+    const { result, keys } = yield* withCapture(client.DoWithDynamicKey.handler())
+    expect(Exit.isSuccess(result) && result.value).toBe("done")
+    expect(keys).toStrictEqual([DynamicKey])
+  }, Effect.provide(TestLayer)),
+  { timeout: 10_000 }
+)
+
+it.live(
+  "command accumulating multiple dynamic keys: all keys forwarded in order",
+  Effect.fnUntraced(function*() {
+    const client = yield* ApiClientFactory.makeFor(Layer.empty)(InvRsc)
+    const { result, keys } = yield* withCapture(client.DoWithBothKeys.handler())
+    expect(Exit.isSuccess(result) && result.value).toBe(99)
+    expect(keys).toStrictEqual([DynamicKey, ExtraKey])
+  }, Effect.provide(TestLayer)),
+  { timeout: 10_000 }
+)
+
+it.live(
+  "per-request isolation: each command call starts with a fresh InvalidationSet",
+  Effect.fnUntraced(function*() {
+    const client = yield* ApiClientFactory.makeFor(Layer.empty)(InvRsc)
+    const r1 = yield* withCapture(client.DoWithDynamicKey.handler())
+    const r2 = yield* withCapture(client.DoWithDynamicKey.handler())
+    // Each call must have exactly one key — no accumulation across calls
+    expect(r1.keys).toStrictEqual([DynamicKey])
+    expect(r2.keys).toStrictEqual([DynamicKey])
+  }, Effect.provide(TestLayer)),
+  { timeout: 10_000 }
+)
+
+it.live(
+  "command failure (V2): keys accumulated before fail still reach the client; original error re-thrown",
+  Effect.fnUntraced(function*() {
+    const client = yield* ApiClientFactory.makeFor(Layer.empty)(InvRsc)
+    const { result, keys } = yield* withCapture(client.DoAndFail.handler())
+    expect(Exit.isFailure(result)).toBe(true)
+    if (Exit.isFailure(result)) {
+      const error = Cause.findErrorOption(result.cause)
+      expect(Option.isSome(error)).toBe(true)
+      if (Option.isSome(error)) {
+        expect(error.value._tag).toBe("CmdBoom")
+        expect(error.value.reason).toBe("intentional failure")
+      }
+    }
+    expect(keys).toStrictEqual([DynamicKey])
+  }, Effect.provide(TestLayer)),
+  { timeout: 10_000 }
+)
+
+it.live(
+  "stream: per-chunk metadata accumulates distinct keys",
+  Effect.fnUntraced(function*() {
+    const client = yield* ApiClientFactory.makeFor(Layer.empty)(InvRsc)
+    const ref = yield* Ref.make<ReadonlyArray<Invalidation.InvalidationKey>>([])
+    const svc = makeInvalidationKeysService(ref)
+    const values = yield* Stream.runCollect(client.StreamWithKey.handler()).pipe(
+      Effect.provideService(InvalidationKeysFromServer, svc)
+    )
+    const keys = yield* Ref.get(ref)
+    expect(values).toStrictEqual([1, 2, 3])
+    expect(keys).toStrictEqual([StreamKey])
+  }, Effect.provide(TestLayer)),
+  { timeout: 10_000 }
+)
+
+it.live(
+  "stream: per-chunk repo writes are drained and forwarded to the client recorder",
+  Effect.fnUntraced(function*() {
+    const client = yield* ApiClientFactory.makeFor(Layer.empty)(InvRsc)
+    const readsRef = yield* Ref.make(DataDependencies.empty())
+    const writesRef = yield* Ref.make(DataDependencies.empty())
+    const svc = DataDependencies.makeDataDependencyRecorder(readsRef, writesRef)
+    const values = yield* Stream.runCollect(client.StreamWithRepoWrite.handler()).pipe(
+      Effect.provideService(DataDependencies.DataDependencyRecorder, svc)
+    )
+    const writes = yield* Ref.get(writesRef)
+    expect(values).toStrictEqual([1, 2, 3])
+    // Each emitted value writes to RepoItem; routing drains the writes per chunk and the client
+    // accumulates their entity ids into one dependency.
+    expect(writes).toStrictEqual(new Set([DataDependencies.repo("RepoItem", ["1", "2", "3"])]))
+  }, Effect.provide(TestLayer)),
+  { timeout: 10_000 }
+)
+
+it.live(
+  "repository dependencies flow through query and command metadata",
+  Effect.fnUntraced(function*() {
+    const client = yield* ApiClientFactory.makeFor(Layer.empty)(InvRsc)
+
+    const query = yield* withDependencyCapture(client.GetRepoCount.handler())
+    expect(Exit.isSuccess(query.result) && query.result.value).toBe(0)
+    expect(query.dependencies.reads).toStrictEqual(new Set([DataDependencies.repo("RepoItem")]))
+    expect(query.dependencies.writes).toStrictEqual(DataDependencies.empty())
+
+    const command = yield* withDependencyCapture(client.SaveRepoItem.handler({ id: "1", label: "one" }))
+    expect(Exit.isSuccess(command.result)).toBe(true)
+    expect(command.dependencies.reads).toStrictEqual(DataDependencies.empty())
+    expect(command.dependencies.writes).toStrictEqual(new Set([DataDependencies.repo("RepoItem", ["1"])]))
+  }, Effect.provide(TestLayer)),
+  { timeout: 10_000 }
+)
+
+it.live(
+  "query invalidation: a command's writes invalidate exactly the queries whose reads intersect",
+  Effect.fnUntraced(function*() {
+    const client = yield* ApiClientFactory.makeFor(Layer.empty)(InvRsc)
+
+    // Client-side query registry: queryKey -> read dependencies forwarded by the server. Mirrors
+    // @effect-app/vue's `dependencyMetadata`; the derivation predicate (`intersects`) is the exact
+    // one the vue mutate engine uses to pick invalidation targets from a command's writes.
+    const queryReads = new Map<string, DataDependencies.DataDependencies>()
+    const invalidatedBy = (writes: DataDependencies.DataDependencies) =>
+      [...queryReads]
+        .filter(([, reads]) => DataDependencies.intersects(reads, writes))
+        .map(([key]) => key)
+
+    // Run the query through the real client; register its forwarded reads under its key.
+    const query = yield* withDependencyCapture(client.GetRepoCount.handler())
+    expect(Exit.isSuccess(query.result)).toBe(true)
+    queryReads.set("GetRepoCount", query.dependencies.reads)
+    // Before any command, nothing is invalidated.
+    expect(invalidatedBy(DataDependencies.empty())).toStrictEqual([])
+
+    // A command writing the SAME repo the query read => the query is selected for invalidation.
+    const save = yield* withDependencyCapture(client.SaveRepoItem.handler({ id: "1", label: "one" }))
+    expect(Exit.isSuccess(save.result)).toBe(true)
+    expect(invalidatedBy(save.dependencies.writes)).toStrictEqual(["GetRepoCount"])
+
+    // A command writing an UNRELATED repo => the query is NOT invalidated (negative control).
+    const saveOther = yield* withDependencyCapture(client.SaveOtherItem.handler({ id: "2", label: "two" }))
+    expect(Exit.isSuccess(saveOther.result)).toBe(true)
+    expect(saveOther.dependencies.writes).toStrictEqual(new Set([DataDependencies.repo("OtherItem", ["2"])]))
+    expect(invalidatedBy(saveOther.dependencies.writes)).toStrictEqual([])
+  }, Effect.provide(TestLayer)),
+  { timeout: 10_000 }
+)