@effect-app/vue 4.0.0-beta.281 → 4.0.0-beta.283

package/src/atomQuery.ts

@@ -14,7 +14,7 @@
  * abstraction (mirrors AtomRpc's recipe; see docs/atom-query-plan.md).
  */
 import { defaultRegistry } from "@effect/atom-vue"
-import { makeQueryKey } from "effect-app/client"
+import { DataDependencies, makeQueryKey } from "effect-app/client"
 import type { ClientForOptions } from "effect-app/client/clientFor"
 import { ServiceUnavailableError } from "effect-app/client/errors"
 import * as Effect from "effect-app/Effect"
@@ -25,12 +25,14 @@ import * as Duration from "effect/Duration"
 import * as Equal from "effect/Equal"
 import * as Hash from "effect/Hash"
 import type * as Layer from "effect/Layer"
+import * as Ref from "effect/Ref"
 import * as Stream from "effect/Stream"
 import { isHttpClientError } from "effect/unstable/http/HttpClientError"
 import * as AsyncResult from "effect/unstable/reactivity/AsyncResult"
 import * as Atom from "effect/unstable/reactivity/Atom"
 import * as AtomRegistry from "effect/unstable/reactivity/AtomRegistry"
 import * as Reactivity from "effect/unstable/reactivity/Reactivity"
+import { clearQueryReadDependencies, setQueryReadDependencies } from "./dependencyMetadata.ts"
 import { reportRuntimeError } from "./lib.ts"
 
 /** All non-empty prefixes of a key, longest last. `[a,b,c]` -> `[[a],[a,b],[a,b,c]]`. */
@@ -83,6 +85,15 @@ const trackWritableByKeys =
     )
   }
 
+/** Drop a query's recorded read-dependencies when its atom is GC'd (mirrors `trackByKeys`). */
+const trackReadDependencies =
+  (key: ReadonlyArray<unknown>) =>
+  <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>): Atom.Atom<AsyncResult.AsyncResult<A, E>> =>
+    Atom.transform(atom, (get) => {
+      get.addFinalizer(() => clearQueryReadDependencies(key))
+      return get(atom)
+    }, { initialValueTarget: atom })
+
 const atomsForKeys = (keys: ReadonlyArray<unknown>): ReadonlyArray<Atom.Atom<AsyncResult.AsyncResult<any, any>>> => {
   const atoms = new Set<Atom.Atom<AsyncResult.AsyncResult<any, any>>>()
   for (const key of keys) {
@@ -319,9 +330,21 @@ export const buildQueryFamily = <I, A, E>(
   const baseKey = makeQueryKey(self) // hierarchical, input-independent
 
   return Atom.family((input: I) => {
-    let atom: Atom.Atom<AsyncResult.AsyncResult<A, E>> = rt.runtime.atom(
-      self
+    const fullKey = [...baseKey, input]
+    // Record the repository/server read-dependencies seen while fetching, keyed by `fullKey`, so a
+    // later mutation whose writes intersect them can derive this query as an invalidation target.
+    const recordReads = Effect.gen(function*() {
+      const readsRef = yield* Ref.make<DataDependencies.DataDependencies>([])
+      const writesRef = yield* Ref.make<DataDependencies.DataDependencies>([])
+      const recorder = DataDependencies.makeDataDependencyRecorder(readsRef, writesRef)
+      const result = yield* self
         .handler(input)
+        .pipe(Effect.provideService(DataDependencies.DataDependencyRecorder, recorder))
+      setQueryReadDependencies(fullKey, yield* Ref.get(readsRef))
+      return result
+    })
+    let atom: Atom.Atom<AsyncResult.AsyncResult<A, E>> = rt.runtime.atom(
+      recordReads
         .pipe(
           Effect.retry({ times: 5, while: isRetryable }),
           Effect.tapCauseIf(Cause.hasDies, (cause) => reportRuntimeError(cause)),
@@ -331,13 +354,13 @@ export const buildQueryFamily = <I, A, E>(
     // Register under every prefix of the full key => hierarchical (prefix) invalidation. Two roles:
     //   - withReactivity: `Reactivity.invalidate(key)` refreshes this atom (the actual refetch).
     //   - trackByKeys:    records the atom in `keyAtoms` so the mutation can AWAIT its settle.
-    const fullKey = [...baseKey, input]
     const projectedFullKey = self.queryKeyProjectionHash === undefined
       ? fullKey
       : [...baseKey, self.queryKeyProjectionHash, input]
     const reactivityKeys = uniqueKeys([...prefixesOf(fullKey), ...prefixesOf(projectedFullKey)])
     atom = rt.factory.withReactivity(reactivityKeys)(atom)
     atom = trackByKeys(reactivityKeys)(atom)
+    atom = trackReadDependencies(fullKey)(atom)
     // gcTime LAST so the whole chain (incl. the registration + tracking) stays alive through the
     // idle window, letting invalidation reach a cached-but-unmounted query.
     atom = Atom.setIdleTTL(atom, defaults.gcTime)

package/src/dependencyMetadata.ts

@@ -0,0 +1,38 @@
+import { DataDependencies } from "effect-app/client"
+import * as Hash from "effect/Hash"
+
+// Maps a live query's reactivity key (its full `[...queryKey, input]` key) to the
+// data dependencies it read while fetching. Populated when the query handler resolves and
+// cleared when the query atom is GC'd, so the set mirrors the live query atoms (mounted or
+// cached-within-ttl) — the atom equivalent of the former tanstack query cache.
+type Entry = { readonly key: ReadonlyArray<unknown>; readonly reads: DataDependencies.DataDependencies }
+const readDependencies = new Map<number, Entry>()
+
+export const setQueryReadDependencies = (
+  key: ReadonlyArray<unknown>,
+  reads: DataDependencies.DataDependencies
+) => {
+  const h = Hash.hash(key)
+  if (reads.length === 0) readDependencies.delete(h)
+  else readDependencies.set(h, { key, reads })
+}
+
+export const clearQueryReadDependencies = (key: ReadonlyArray<unknown>) => {
+  readDependencies.delete(Hash.hash(key))
+}
+
+/**
+ * Reactivity keys of every live query whose recorded read-dependencies intersect this
+ * mutation's `writeDependencies`. Returned keys are passed to `invalidateAndAwait`, refreshing
+ * exactly those queries.
+ */
+export const getDerivedInvalidationKeys = (
+  writeDependencies: ReadonlyArray<DataDependencies.DataDependency>
+): ReadonlyArray<ReadonlyArray<unknown>> => {
+  if (writeDependencies.length === 0) return []
+  const keys: Array<ReadonlyArray<unknown>> = []
+  for (const { key, reads } of readDependencies.values()) {
+    if (DataDependencies.intersects(reads, writeDependencies)) keys.push(key)
+  }
+  return keys
+}

package/src/internal/tanstackQuery.ts

@@ -1,6 +1,6 @@
 import { injectRegistry } from "@effect/atom-vue"
 import { QueryClient, useQuery as useTanstackQuery } from "@tanstack/vue-query"
-import { makeQueryKey, type Req } from "effect-app/client"
+import { DataDependencies, makeQueryKey, type Req } from "effect-app/client"
 import type { RequestHandlerWithInput } from "effect-app/client/clientFor"
 import { CauseException, ServiceUnavailableError } from "effect-app/client/errors"
 import type * as Context from "effect-app/Context"
@@ -8,11 +8,13 @@ import * as Effect from "effect-app/Effect"
 import * as Option from "effect-app/Option"
 import * as S from "effect-app/Schema"
 import * as Cause from "effect/Cause"
+import * as Ref from "effect/Ref"
 import { isHttpClientError } from "effect/unstable/http/HttpClientError"
 import * as AsyncResult from "effect/unstable/reactivity/AsyncResult"
 import * as Atom from "effect/unstable/reactivity/Atom"
 import { computed, type MaybeRefOrGetter, shallowRef, toValue, watch, type WatchSource } from "vue"
 import { replaceEqualDeep } from "../atomQuery.ts"
+import { clearQueryReadDependencies, setQueryReadDependencies } from "../dependencyMetadata.ts"
 import { reportRuntimeError } from "../lib.ts"
 import type { QueryInvalidator } from "../mutate.ts"
 import type { CustomDefinedInitialQueryOptions, CustomDefinedPlaceholderQueryOptions, CustomUndefinedInitialQueryOptions, CustomUseQueryOptions, MakeQuery2, QueryCacheUpdater, QueryHandle, QueryObserverResult, RefetchOptions } from "../query.ts"
@@ -131,6 +133,12 @@ export const makeTanstackQuery = <R>(
   getRuntime: () => Context.Context<R>,
   queryClient: QueryClient
 ): MakeQuery2<R> => {
+  // Drop a query's recorded read-dependencies when tanstack evicts it from the cache, so the
+  // registry mirrors the live queries (mirrors the atom engine's `trackReadDependencies` finalizer).
+  queryClient.getQueryCache().subscribe((event) => {
+    if (event.type === "removed") clearQueryReadDependencies(event.query.queryKey)
+  })
+
   const useQuery: MakeQuery2<R> = <I, A, E, Request extends Req, Name extends string>(
     q: RequestHandlerWithInput<I, A, E, R, Request, Name>
   ) =>
@@ -161,12 +169,24 @@ export const makeTanstackQuery = <R>(
       }),
       queryFn: ({ signal }: { readonly signal: AbortSignal }) =>
         runPromise(
-          q
-            .handler(resolveInput(arg, options?.mode)!)
-            .pipe(
-              Effect.tapCauseIf(Cause.hasDies, (cause) => reportRuntimeError(cause)),
-              Effect.withSpan(`query ${q.id}`, {}, { captureStackTrace: false })
-            ),
+          Effect.gen(function*() {
+            const input = resolveInput(arg, options?.mode)!
+            // Record the repository/server read-dependencies seen while fetching, keyed by the
+            // tanstack queryKey, so a later mutation whose writes intersect them derives this query
+            // as an invalidation target (the tanstack invalidator invalidates by this same key).
+            const readsRef = yield* Ref.make<DataDependencies.DataDependencies>([])
+            const writesRef = yield* Ref.make<DataDependencies.DataDependencies>([])
+            const recorder = DataDependencies.makeDataDependencyRecorder(readsRef, writesRef)
+            const result = yield* q
+              .handler(input)
+              .pipe(
+                Effect.provideService(DataDependencies.DataDependencyRecorder, recorder),
+                Effect.tapCauseIf(Cause.hasDies, (cause) => reportRuntimeError(cause)),
+                Effect.withSpan(`query ${q.id}`, {}, { captureStackTrace: false })
+              )
+            setQueryReadDependencies(fullQueryKey(q, queryKey, input), yield* Ref.get(readsRef))
+            return result
+          }),
           { signal }
         )
     }, queryClient)

package/src/mutate.ts

@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { type InvalidationKey, InvalidationKeysFromServer, makeInvalidationKeysService, makeQueryKey, type Req } from "effect-app/client"
+import { DataDependencies, type InvalidationKey, InvalidationKeysFromServer, makeInvalidationKeysService, makeQueryKey, type Req } from "effect-app/client"
 import type { ClientForOptions, RequestHandlerWithInput } from "effect-app/client/clientFor"
 import type { InvalidateQueryInstruction } from "effect-app/client/makeClient"
 import * as Effect from "effect-app/Effect"
@@ -14,6 +14,7 @@ import * as AsyncResult from "effect/unstable/reactivity/AsyncResult"
 import type * as Reactivity from "effect/unstable/reactivity/Reactivity"
 import { computed, type ComputedRef, shallowRef } from "vue"
 import { invalidateAndAwait } from "./atomQuery.ts"
+import { getDerivedInvalidationKeys } from "./dependencyMetadata.ts"
 
 export type GetQueryKey = (h: { id: string; options?: ClientForOptions }) => string[]
 
@@ -296,25 +297,32 @@ const buildInvalidateCache = <RInvalidator>(
       return keys
     }
 
-    return queryKey ? [queryKey] : []
+    // No implicit namespace invalidation: without an explicit `queryInvalidation` config, client
+    // keys are empty and invalidation is driven solely by server keys + repository write-dependency
+    // derivation. (`getQueryKey` is still offered to the config callback as a convenience base.)
+    return []
   }
 
   const invalidateCache = (
     input: unknown,
     output: Exit.Exit<unknown, unknown>,
-    serverKeys: ReadonlyArray<InvalidationKey>
+    serverKeys: ReadonlyArray<InvalidationKey>,
+    writeDependencies: ReadonlyArray<DataDependencies.DataDependency> = []
   ) =>
     Effect.suspend(() => {
       const clientKeys = getClientInvalidationKeys(input, output)
+      // Derive extra reactivity keys from repository write-dependencies: every live query whose
+      // recorded read-dependencies intersect this mutation's writes must be refreshed.
+      const derivedKeys = getDerivedInvalidationKeys(writeDependencies)
       // Invalidate exact reactivity keys (= the prefixes query atoms register under). Each key
       // array is hashed structurally, matching the query-side registration.
-      const keys: ReadonlyArray<ReadonlyArray<unknown>> = [...clientKeys, ...serverKeys]
+      const keys: ReadonlyArray<ReadonlyArray<unknown>> = [...clientKeys, ...serverKeys, ...derivedKeys]
 
       if (!isReadonlyArrayNonEmpty(keys)) return Effect.void
 
       return Effect
         .andThen(
-          Effect.annotateCurrentSpan({ clientKeys, serverKeys }),
+          Effect.annotateCurrentSpan({ clientKeys, serverKeys, writeDependencies }),
           // refetch + AWAIT every live query registered under these keys, so by the time the
           // mutation resolves the affected queries are fresh.
           queryInvalidator.invalidateAndAwait(keys)
@@ -340,12 +348,17 @@ export const invalidateQueries = <RInvalidator>(
   const handle = <A, E, R>(eff: Effect.Effect<A, E, R>, input?: unknown) =>
     Effect.gen(function*() {
       const keysRef = yield* Ref.make<ReadonlyArray<InvalidationKey>>([])
+      const readsRef = yield* Ref.make<DataDependencies.DataDependencies>([])
+      const writesRef = yield* Ref.make<DataDependencies.DataDependencies>([])
+      const dependencyRecorder = DataDependencies.makeDataDependencyRecorder(readsRef, writesRef)
       const result = yield* eff.pipe(
         Effect.provideService(InvalidationKeysFromServer, makeInvalidationKeysService(keysRef)),
+        Effect.provideService(DataDependencies.DataDependencyRecorder, dependencyRecorder),
         Effect.onExit((exit) =>
           Effect.gen(function*() {
             const serverKeys = yield* Ref.get(keysRef)
-            yield* invalidateCache(input, exit, serverKeys)
+            const writeDependencies = yield* Ref.get(writesRef)
+            yield* invalidateCache(input, exit, serverKeys, writeDependencies)
           })
         )
       )
@@ -354,7 +367,8 @@ export const invalidateQueries = <RInvalidator>(
           Effect.onExit((exit) =>
             Effect.gen(function*() {
               const serverKeys = yield* Ref.get(keysRef)
-              yield* invalidateCache(input, exit, serverKeys)
+              const writeDependencies = yield* Ref.get(writesRef)
+              yield* invalidateCache(input, exit, serverKeys, writeDependencies)
             })
           )
         )
@@ -436,15 +450,20 @@ export const makeStreamMutation2 = <RInvalidator>(queryInvalidator: QueryInvalid
           // returns void to keep the server-side invalidation service effect-free.
           (key) => invCache(input, Exit.succeed(undefined), [key]) as Effect.Effect<void>
         )
+        const readsRef = yield* Ref.make<DataDependencies.DataDependencies>([])
+        const writesRef = yield* Ref.make<DataDependencies.DataDependencies>([])
+        const dependencyRecorder = DataDependencies.makeDataDependencyRecorder(readsRef, writesRef)
         const lastRef = yield* Ref.make<any>(undefined)
         return source.pipe(
           Stream.provideService(InvalidationKeysFromServer, invKeys),
+          Stream.provideService(DataDependencies.DataDependencyRecorder, dependencyRecorder),
           Stream.tap((v) => Ref.set(lastRef, v)),
           Stream.ensuring(
             Effect.gen(function*() {
               const lastValue = yield* Ref.get(lastRef)
               const serverKeys = yield* Ref.get(keysRef)
-              yield* invCache(input, Exit.succeed(lastValue), serverKeys)
+              const writeDependencies = yield* Ref.get(writesRef)
+              yield* invCache(input, Exit.succeed(lastValue), serverKeys, writeDependencies)
             })
           )
         )

package/test/dependencyInvalidation.test.ts

@@ -0,0 +1,352 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { defaultRegistry } from "@effect/atom-vue"
+import { expect, it } from "@effect/vitest"
+import { QueryClient, VueQueryPlugin } from "@tanstack/vue-query"
+import { DataDependencies, type InvalidationKey, InvalidationKeysFromServer, makeQueryKey } from "effect-app/client"
+import * as Context from "effect-app/Context"
+import * as Effect from "effect-app/Effect"
+import * as Fiber from "effect/Fiber"
+import * as Layer from "effect/Layer"
+import * as ManagedRuntime from "effect/ManagedRuntime"
+import { TestClock } from "effect/testing"
+import * as Reactivity from "effect/unstable/reactivity/Reactivity"
+import { createApp, effectScope, ref } from "vue"
+import { awaitAtomResult, buildQueryFamily, invalidateAndAwait, makeAtomClientRuntime } from "../src/atomQuery.js"
+import { clearQueryReadDependencies, getDerivedInvalidationKeys, setQueryReadDependencies } from "../src/dependencyMetadata.js"
+import { makeTanstackQuery, makeTanstackQueryInvalidator } from "../src/internal/tanstackQuery.js"
+import { invalidateQueries, type MutationOptionsBase } from "../src/mutate.js"
+
+const repo = DataDependencies.repo("FrontendRepo")
+const otherRepo = DataDependencies.repo("OtherRepo")
+
+// --- shared registry + derivation logic --------------------------------------------------------
+
+it("getDerivedInvalidationKeys returns keys of queries whose reads intersect the writes", () => {
+  const inventoryKey = ["$Inventory", "List", undefined]
+  const ordersKey = ["$Orders", "List", undefined]
+  setQueryReadDependencies(inventoryKey, [repo])
+  setQueryReadDependencies(ordersKey, [otherRepo])
+
+  try {
+    expect(getDerivedInvalidationKeys([repo])).toEqual([inventoryKey])
+    expect(getDerivedInvalidationKeys([repo, otherRepo])).toEqual([inventoryKey, ordersKey])
+    expect(getDerivedInvalidationKeys([])).toEqual([])
+  } finally {
+    clearQueryReadDependencies(inventoryKey)
+    clearQueryReadDependencies(ordersKey)
+  }
+})
+
+it("clearing read dependencies drops the query from derivation", () => {
+  const inventoryKey = ["$Inventory", "List", undefined]
+  setQueryReadDependencies(inventoryKey, [repo])
+  clearQueryReadDependencies(inventoryKey)
+  expect(getDerivedInvalidationKeys([repo])).toEqual([])
+})
+
+it("derivation matches on both dependency type and name (repo vs signal)", () => {
+  const key = ["$Live", "Feed", undefined]
+  setQueryReadDependencies(key, [DataDependencies.signal("Feed")])
+  try {
+    // Same name but different type (repo "Feed") must NOT intersect a signal read.
+    expect(getDerivedInvalidationKeys([DataDependencies.repo("Feed")])).toEqual([])
+    // Same type and name does intersect.
+    expect(getDerivedInvalidationKeys([DataDependencies.signal("Feed")])).toEqual([key])
+  } finally {
+    clearQueryReadDependencies(key)
+  }
+})
+
+it("derivation intersects when any one of multiple reads matches a write", () => {
+  const key = ["$Mixed", "List", undefined]
+  setQueryReadDependencies(key, [DataDependencies.repo("A"), DataDependencies.repo("B")])
+  try {
+    expect(getDerivedInvalidationKeys([DataDependencies.repo("B")])).toEqual([key])
+    expect(getDerivedInvalidationKeys([DataDependencies.repo("C")])).toEqual([])
+  } finally {
+    clearQueryReadDependencies(key)
+  }
+})
+
+it.effect("a command's write deps invalidate active queries whose recorded reads intersect", () =>
+  Effect.gen(function*() {
+    const inventoryKey = ["$Inventory", "List", undefined]
+    setQueryReadDependencies(inventoryKey, [repo])
+
+    const recorded: Array<ReadonlyArray<unknown>> = []
+    const queryInvalidator = {
+      invalidateAndAwait: (keys: ReadonlyArray<ReadonlyArray<unknown>>) =>
+        Effect.sync(() => keys.forEach((key) => recorded.push(key)))
+    }
+
+    // The command handler records a write to the same repo the query read from.
+    const mutate = invalidateQueries({ id: "Admin.Save" }, undefined, queryInvalidator)
+    const command = DataDependencies.write(repo).pipe(Effect.as(123))
+
+    const fiber = yield* Effect.forkChild(mutate(command, { id: "abc" }))
+    yield* TestClock.adjust("1 millis")
+    const result = yield* Fiber.join(fiber)
+
+    clearQueryReadDependencies(inventoryKey)
+
+    expect(result).toBe(123)
+    expect(recorded).toContainEqual(inventoryKey)
+  }))
+
+// --- atom engine: recording wires through buildQueryFamily ---------------------------------------
+
+it("atom engine: a query records its read deps so a command's writes derive it", async () => {
+  const atomRepo = DataDependencies.repo("AtomRepo")
+  const mrt = ManagedRuntime.make(Layer.empty)
+  const baseContext = mrt.runSync(Effect.context<never>())
+  const rt = makeAtomClientRuntime(
+    () => Layer.succeedContext(baseContext) as Layer.Layer<any, never, never>,
+    mrt.memoMap
+  )
+
+  let runs = 0
+  const self = {
+    id: "AtomInv.List",
+    handler: () => DataDependencies.read(atomRepo).pipe(Effect.as(++runs))
+  }
+  const family = buildQueryFamily(rt as any, self as any)
+  const atom = family(undefined)
+
+  const unmount = defaultRegistry.mount(atom)
+  try {
+    await Effect.runPromise(awaitAtomResult(defaultRegistry, atom) as any)
+    expect(runs).toBe(1)
+
+    const fullKey = [...makeQueryKey(self), undefined]
+    expect(getDerivedInvalidationKeys([atomRepo])).toContainEqual(fullKey)
+    expect(getDerivedInvalidationKeys([repo])).not.toContainEqual(fullKey)
+  } finally {
+    unmount()
+    clearQueryReadDependencies([...makeQueryKey(self), undefined])
+  }
+})
+
+// --- legacy tanstack engine: recording + cache-removal cleanup -----------------------------------
+
+const makeTanstackContext = (queryClient: QueryClient) => {
+  const app = createApp({ render: () => null })
+  app.use(VueQueryPlugin, { queryClient })
+  const scope = effectScope(true)
+  const run = <T>(fn: () => T): T => {
+    let out!: T
+    app.runWithContext(() => {
+      scope.run(() => {
+        out = fn()
+      })
+    })
+    return out
+  }
+  return { run, dispose: () => scope.stop() }
+}
+
+it("tanstack engine: a query records reads, and a command's writes refetch it", async () => {
+  const tsRepo = DataDependencies.repo("TanstackRepo")
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false, gcTime: Infinity, staleTime: 0 } }
+  })
+  const useQuery = makeTanstackQuery(() => Context.empty(), queryClient)
+
+  let runs = 0
+  const self = { id: "TanstackInv.List", handler: () => DataDependencies.read(tsRepo).pipe(Effect.as(++runs)) }
+  const ctx = makeTanstackContext(queryClient)
+  const [, , , handle] = ctx.run(() => useQuery(self as any)(ref(undefined) as any, {} as any)) as any
+
+  try {
+    await Effect.runPromise(handle.refetch())
+    expect(runs).toBe(1)
+
+    const fullKey = [...makeQueryKey(self), undefined]
+    const derived = getDerivedInvalidationKeys([tsRepo])
+    expect(derived).toContainEqual(fullKey)
+
+    // Invalidating those derived keys via the tanstack invalidator refetches the active query.
+    await Effect.runPromise(makeTanstackQueryInvalidator(queryClient).invalidateAndAwait(derived))
+    expect(runs).toBe(2)
+  } finally {
+    ctx.dispose()
+  }
+})
+
+it("tanstack engine: evicting a query from the cache clears its recorded reads", () => {
+  const tsRepo = DataDependencies.repo("TanstackEvictRepo")
+  const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } })
+  // Installs the cache-removal subscription that clears the registry on eviction.
+  makeTanstackQuery(() => Context.empty(), queryClient)
+
+  const key = ["$TanstackEvict", "List", undefined]
+  const cache = queryClient.getQueryCache()
+  cache.build(queryClient, { queryKey: key, queryFn: () => Promise.resolve(1) })
+  setQueryReadDependencies(key, [tsRepo])
+  expect(getDerivedInvalidationKeys([tsRepo])).toContainEqual(key)
+
+  cache.clear()
+  expect(getDerivedInvalidationKeys([tsRepo])).not.toContainEqual(key)
+})
+
+// --- atom engine: GC finalizer clears recorded reads --------------------------------------------
+
+it("atom engine: disposing the query atom clears its recorded reads", async () => {
+  const atomRepo = DataDependencies.repo("AtomGcRepo")
+  const mrt = ManagedRuntime.make(Layer.empty)
+  const baseContext = mrt.runSync(Effect.context<never>())
+  const rt = makeAtomClientRuntime(
+    () => Layer.succeedContext(baseContext) as Layer.Layer<any, never, never>,
+    mrt.memoMap
+  )
+  const self = { id: "AtomGc.List", handler: () => DataDependencies.read(atomRepo).pipe(Effect.as(1)) }
+  const atom = buildQueryFamily(rt as any, self as any)(undefined)
+  const fullKey = [...makeQueryKey(self), undefined]
+
+  const unmount = defaultRegistry.mount(atom)
+  await Effect.runPromise(awaitAtomResult(defaultRegistry, atom) as any)
+  expect(getDerivedInvalidationKeys([atomRepo])).toContainEqual(fullKey)
+
+  // Disposing the registry runs the atom's finalizers, including `trackReadDependencies`.
+  unmount()
+  defaultRegistry.reset()
+  expect(getDerivedInvalidationKeys([atomRepo])).not.toContainEqual(fullKey)
+})
+
+// --- full engine e2e matrix: every invalidation source, on each engine ---------------------------
+//
+// For each engine, a live query records a repo read; then commands sharing the query's namespace are
+// run through the real mutate path, covering every invalidation source. The command namespace matches
+// the query's, so the "no refetch" cases also confirm there is NO implicit namespace invalidation.
+
+interface EngineHarness {
+  readonly queryFullKey: ReadonlyArray<unknown>
+  readonly serverInvalidationKey: InvalidationKey
+  readonly fetchInitial: () => Promise<unknown>
+  readonly runs: () => number
+  readonly runCommand: (
+    options: MutationOptionsBase | undefined,
+    command: Effect.Effect<unknown, never>
+  ) => Promise<unknown>
+  readonly dispose: () => void
+}
+
+const makeTanstackHarness = (queryRepo: DataDependencies.DataDependency): EngineHarness => {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false, gcTime: Infinity, staleTime: 0 } }
+  })
+  const useQuery = makeTanstackQuery(() => Context.empty(), queryClient)
+  const invalidator = makeTanstackQueryInvalidator(queryClient)
+  let runs = 0
+  const self = { id: "MatrixTs.List", handler: () => DataDependencies.read(queryRepo).pipe(Effect.as(++runs)) }
+  const ctx = makeTanstackContext(queryClient)
+  const [, , , handle] = ctx.run(() => useQuery(self as any)(ref(undefined) as any, {} as any)) as any
+  return {
+    queryFullKey: [...makeQueryKey(self), undefined],
+    serverInvalidationKey: makeQueryKey(self),
+    fetchInitial: () => Effect.runPromise(handle.refetch()),
+    runs: () => runs,
+    runCommand: (options, command) =>
+      Effect.runPromise(invalidateQueries({ id: "MatrixTs.Save" }, options, invalidator)(command, { id: "x" })),
+    dispose: () => ctx.dispose()
+  }
+}
+
+const makeAtomHarness = (queryRepo: DataDependencies.DataDependency): EngineHarness => {
+  const mrt = ManagedRuntime.make(Reactivity.layer)
+  const baseContext = mrt.runSync(Effect.context<Reactivity.Reactivity>())
+  const reactivity = Context.get(baseContext, Reactivity.Reactivity)
+  const rt = makeAtomClientRuntime(
+    () => Layer.succeedContext(baseContext) as Layer.Layer<any, never, never>,
+    mrt.memoMap
+  )
+  const invalidator = {
+    invalidateAndAwait: (keys: ReadonlyArray<ReadonlyArray<unknown>>) =>
+      invalidateAndAwait(keys).pipe(Effect.provideService(Reactivity.Reactivity, reactivity))
+  }
+  let runs = 0
+  const self = { id: "MatrixAtom.List", handler: () => DataDependencies.read(queryRepo).pipe(Effect.as(++runs)) }
+  const atom = buildQueryFamily(rt as any, self as any)(undefined)
+  const unmount = defaultRegistry.mount(atom)
+  return {
+    queryFullKey: [...makeQueryKey(self), undefined],
+    serverInvalidationKey: makeQueryKey(self),
+    fetchInitial: () => Effect.runPromise(awaitAtomResult(defaultRegistry, atom) as any),
+    runs: () => runs,
+    runCommand: (options, command) =>
+      Effect.runPromise(
+        invalidateQueries({ id: "MatrixAtom.Save" }, options, invalidator)(command, { id: "x" })
+          .pipe(Effect.andThen(awaitAtomResult(defaultRegistry, atom).pipe(Effect.exit))) as any
+      ),
+    dispose: () => {
+      unmount()
+      clearQueryReadDependencies([...makeQueryKey(self), undefined])
+    }
+  }
+}
+
+const runInvalidationMatrix = (engine: string, makeHarness: (repo: DataDependencies.DataDependency) => EngineHarness) =>
+  it(`${engine} engine e2e: invalidation source matrix`, async () => {
+    const queryRepo = DataDependencies.repo(`${engine}MatrixRepo`)
+    const otherRepo = DataDependencies.repo(`${engine}MatrixOther`)
+    const h = makeHarness(queryRepo)
+    const noop = Effect.succeed(undefined)
+
+    const expectRefetch = async (
+      label: string,
+      options: MutationOptionsBase | undefined,
+      command: Effect.Effect<unknown, never>
+    ) => {
+      const before = h.runs()
+      await h.runCommand(options, command)
+      expect(h.runs(), `${label} should refetch`).toBeGreaterThan(before)
+    }
+    const expectNoRefetch = async (
+      label: string,
+      options: MutationOptionsBase | undefined,
+      command: Effect.Effect<unknown, never>
+    ) => {
+      const before = h.runs()
+      await h.runCommand(options, command)
+      expect(h.runs(), `${label} must not refetch`).toBe(before)
+    }
+
+    try {
+      await h.fetchInitial()
+      expect(h.runs()).toBeGreaterThanOrEqual(1)
+
+      // 1. write-dependency derivation: command writes the repo the query read.
+      await expectRefetch(
+        "intersecting write dep",
+        undefined,
+        DataDependencies.write(queryRepo).pipe(Effect.as(undefined))
+      )
+
+      // 2. write-dependency derivation: command writes an UNRELATED repo (same namespace).
+      await expectNoRefetch(
+        "unrelated write dep",
+        undefined,
+        DataDependencies.write(otherRepo).pipe(Effect.as(undefined))
+      )
+
+      // 3. explicit `queryInvalidation` config targeting the query.
+      await expectRefetch("explicit config", { queryInvalidation: () => [h.queryFullKey as any] }, noop)
+
+      // 4. explicit config targeting an UNRELATED key.
+      await expectNoRefetch("unrelated explicit config", { queryInvalidation: () => [["$NotAQuery"]] }, noop)
+
+      // 5. server-sent invalidation key targeting the query.
+      await expectRefetch(
+        "server key",
+        undefined,
+        Effect.flatMap(InvalidationKeysFromServer, (svc) => svc.add(h.serverInvalidationKey)).pipe(Effect.as(undefined))
+      )
+
+      // 6. nothing — no config, no deps, no server keys, same namespace (no implicit invalidation).
+      await expectNoRefetch("empty command", undefined, noop)
+    } finally {
+      h.dispose()
+    }
+  })
+
+runInvalidationMatrix("tanstack", makeTanstackHarness)
+runInvalidationMatrix("atom", makeAtomHarness)

package/test/dist/dependencyInvalidation.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependencyInvalidation.test.d.ts","sourceRoot":"","sources":["../dependencyInvalidation.test.ts"],"names":[],"mappings":""}

package/test/dist/query-span.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-span.test.d.ts","sourceRoot":"","sources":["../query-span.test.ts"],"names":[],"mappings":""}