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

package/src/mutate.ts

@@ -1,23 +1,61 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { type InvalidateOptions, type InvalidateQueryFilters, type QueryClient, useQueryClient } from "@tanstack/vue-query"
-import { type Cause, Effect, type Exit, Option } from "effect-app"
-import { type Req } from "effect-app/client"
-import type { ClientForOptions, RequestHandler, RequestHandlerWithInput } from "effect-app/client/clientFor"
+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"
 import { tuple } from "effect-app/Function"
-import * as AsyncResult from "effect/unstable/reactivity/AsyncResult"
+import * as Option from "effect-app/Option"
+import { isReadonlyArrayNonEmpty } from "effect/Array"
+import type * as Cause from "effect/Cause"
+import * as Exit from "effect/Exit"
+import * as AsyncResult from "effect/reactivity/AsyncResult"
+import type * as Reactivity from "effect/reactivity/Reactivity"
+import * as Ref from "effect/Ref"
+import * as Stream from "effect/Stream"
 import { computed, type ComputedRef, shallowRef } from "vue"
-import { makeQueryKey } from "./lib.js"
+import { invalidateAndAwait, invalidateSoft } from "./atomQuery.ts"
+import { getDerivedInvalidationKeys, partitionInvalidationKeys } from "./dependencyMetadata.ts"
+import { reportRuntimeError } from "./lib.ts"
 
-export const getQueryKey = (h: { id: string; options?: ClientForOptions }) => {
+export type GetQueryKey = (h: { id: string; options?: ClientForOptions }) => string[]
+
+/**
+ * Default heuristic: invalidate the parent namespace of the action.
+ * e.g. `$project/$configuration.get` -> `["$project"]`
+ * e.g. `$project/$configuration/$something.get` -> `["$project","$configuration"]`
+ */
+export const defaultGetQueryKey: GetQueryKey = (h) => {
   const key = makeQueryKey(h)
   const ns = key.filter((_) => _.startsWith("$"))
-  // we invalidate the parent namespace e.g $project/$configuration.get, we invalidate $project
-  // for $project/$configuration/$something.get, we invalidate $project/$configuration
   const k = ns.length ? ns.length > 1 ? ns.slice(0, ns.length - 1) : ns : undefined
   if (!k) throw new Error("empty query key for: " + h.id)
   return k
 }
 
+let activeGetQueryKey: GetQueryKey = defaultGetQueryKey
+
+/**
+ * Override the default query-key heuristic used by mutations for cache
+ * invalidation. Call once at app bootstrap. Pass `undefined` to restore the
+ * built-in default.
+ *
+ * @example
+ * ```ts
+ * // invalidate the full namespace of the action (no parent collapse)
+ * setDefaultGetQueryKey((h) => {
+ *   const key = makeQueryKey(h)
+ *   const ns = key.filter((_) => _.startsWith("$"))
+ *   if (!ns.length) throw new Error("empty query key for: " + h.id)
+ *   return ns
+ * })
+ * ```
+ */
+export const setDefaultGetQueryKey = (fn: GetQueryKey | undefined) => {
+  activeGetQueryKey = fn ?? defaultGetQueryKey
+}
+
+export const getQueryKey: GetQueryKey = (h) => activeGetQueryKey(h)
+
 export function mutationResultToVue<A, E>(
   mutationResult: AsyncResult.AsyncResult<A, E>
 ): Res<A, E> {
@@ -67,197 +105,412 @@ export function make<A, E, R>(self: Effect.Effect<A, E, R>) {
   return tuple(result, latestSuccess, execute)
 }
 
-export interface MutationOptionsBase {
+/**
+ * An entry for `queryInvalidation`: a raw query key, an `{ id }` handler ref, or a
+ * `{ filters }` shape. The atom engine acts on entries that carry a concrete query
+ * key: raw arrays, handler refs, or `{ filters: { queryKey } }`. Predicate-only
+ * filters have no exact-key reactivity equivalent and fail fast.
+ */
+export type QueryKeyInvalidationFilters = {
+  readonly queryKey: ReadonlyArray<unknown>
+}
+export type InvalidationEntry = InvalidateQueryInstruction<QueryKeyInvalidationFilters>
+export type QueryInvalidationEffect<R = never> = (
+  keys: ReadonlyArray<ReadonlyArray<unknown>>
+) => Effect.Effect<void, never, R>
+export interface QueryInvalidator<R = never> {
+  readonly invalidateAndAwait: QueryInvalidationEffect<R>
+  readonly invalidateSoft?: QueryInvalidationEffect<R>
+}
+
+export const atomQueryInvalidator: QueryInvalidator<Reactivity.Reactivity> = {
+  invalidateAndAwait,
+  invalidateSoft
+}
+
+export const combineQueryInvalidators = <R>(
+  ...invalidators: ReadonlyArray<QueryInvalidator<R>>
+): QueryInvalidator<R> => ({
+  invalidateAndAwait: (keys) =>
+    Effect.forEach(
+      invalidators,
+      (invalidator) => invalidator.invalidateAndAwait(keys),
+      { discard: true, concurrency: "unbounded" }
+    ),
+  invalidateSoft: (keys) =>
+    Effect.forEach(
+      invalidators,
+      (invalidator) => invalidator.invalidateSoft?.(keys) ?? Effect.void,
+      { discard: true, concurrency: "unbounded" }
+    )
+})
+
+const isRecord = (value: unknown): value is { readonly [key: string]: unknown } =>
+  typeof value === "object" && value !== null
+
+const isQueryKey = (entry: InvalidationEntry): entry is ReadonlyArray<string> => Array.isArray(entry)
+
+const queryKeyFromFilters = (
+  entry: Exclude<InvalidationEntry, ReadonlyArray<string>>
+): ReadonlyArray<unknown> | undefined => {
+  if (!("filters" in entry)) return undefined
+  const filters = entry.filters
+  if (!isRecord(filters)) return undefined
+  const queryKey = filters["queryKey"]
+  return Array.isArray(queryKey) ? queryKey : undefined
+}
+
+export interface MutationOptionsBase<A = unknown, B = A, E2 = never, R2 = never> {
   /**
    * By default we invalidate one level of the query key, e.g $project/$configuration.get, we invalidate $project.
-   * This can be overridden by providing a function that returns an array of filters and options.
+   * This can be overridden by providing a function that returns an array of filters and options,
+   * or RPC handlers directly (their query keys are derived automatically).
+   *
+   * @example
+   * ```ts
+   * queryInvalidation: (queryKey) => [
+   *   { filters: { queryKey } },
+   *   GetMe,
+   *   PackListIndex
+   * ]
+   * ```
    */
-  queryInvalidation?: (defaultKey: string[], name: string) => {
-    filters?: InvalidateQueryFilters | undefined
-    options?: InvalidateOptions | undefined
-  }[]
-}
-
-/** @deprecated prefer more basic @see MutationOptionsBase and separate useMutation from Command.fn */
-export interface MutationOptions<A, E, R, A2 = A, E2 = E, R2 = R, I = void> extends MutationOptionsBase {
+  queryInvalidation?: (
+    defaultKey: string[],
+    name: string,
+    input?: unknown,
+    output?: Exit.Exit<unknown, unknown>
+  ) => InvalidationEntry[]
   /**
-   * Map the handler; cache invalidation is already done in this handler.
-   * This is useful for e.g navigating, as you know caches have already updated.
+   * Run an additional Effect after the mutation succeeds. Its output becomes the
+   * final result returned to the caller. Query cache is invalidated once on
+   * mutation exit and again after this Effect completes. Useful for long-running
+   * operations (e.g. polling a background job) where you want the caller to
+   * receive the downstream result and the cache to refresh once it is ready.
    *
-   * @deprecated use `Command.fn` instead of `useMutation*` with `mapHandler` option.
+   * @example
+   * ```ts
+   * useMutation(startExportCommand, {
+   *   select: (result) => pollUntilDone(result.jobId)
+   *   // caller receives the pollUntilDone output, not the original result
+   * })
+   * ```
    */
-  mapHandler?: (handler: Effect.Effect<A, E, R>, input: I) => Effect.Effect<A2, E2, R2>
+  select?: (result: A) => Effect.Effect<B, E2, R2>
 }
 
-// TODO: more efficient invalidation, including args etc
-// return Effect.promise(() => queryClient.invalidateQueries({
-//   predicate: (_) => nses.includes(_.queryKey.filter((_) => _.startsWith("$")).join("/"))
-// }))
-/*
-            // const nses: string[] = []`
-                // for (let i = 0; i < ns.length; i++) {
-                //   nses.push(ns.slice(0, i + 1).join("/"))
-                // }
-                */
-
-export const asResult: {
-  <A, E, R>(
-    handler: Effect.Effect<A, E, R>
-  ): readonly [ComputedRef<AsyncResult.AsyncResult<A, E>>, Effect.Effect<Exit.Exit<A, E>, never, R>]
-  <Args extends readonly any[], A, E, R>(
-    handler: (...args: Args) => Effect.Effect<A, E, R>
-  ): readonly [ComputedRef<AsyncResult.AsyncResult<A, E>>, (...args: Args) => Effect.Effect<Exit.Exit<A, E>, never, R>]
-} = <Args extends readonly any[], A, E, R>(
-  handler: Effect.Effect<A, E, R> | ((...args: Args) => Effect.Effect<A, E, R>)
-) => {
+export const asResult = <Args extends readonly any[], A, E, R>(
+  handler: (...args: Args) => Effect.Effect<A, E, R>
+): readonly [
+  ComputedRef<AsyncResult.AsyncResult<A, E>>,
+  (...args: Args) => Effect.Effect<Exit.Exit<A, E>, never, R>
+] => {
   const state = shallowRef<AsyncResult.AsyncResult<A, E>>(AsyncResult.initial())
 
-  const act = Effect.isEffect(handler)
-    ? Effect
+  const act = (...args: Args) =>
+    Effect
       .sync(() => {
         state.value = AsyncResult.initial(true)
       })
       .pipe(
         Effect.andThen(Effect.suspend(() =>
-          handler.pipe(
+          handler(...args).pipe(
             Effect.exit,
             Effect.tap((exit) => Effect.sync(() => (state.value = AsyncResult.fromExit(exit))))
           )
         ))
       )
-    : (...args: Args) =>
-      Effect
-        .sync(() => {
-          state.value = AsyncResult.initial(true)
-        })
-        .pipe(
-          Effect.andThen(Effect.suspend(() =>
-            handler(...args).pipe(
-              Effect.exit,
-              Effect.tap((exit) => Effect.sync(() => (state.value = AsyncResult.fromExit(exit))))
+
+  return tuple(computed(() => state.value), act)
+}
+
+/**
+ * Like `asResult`, but for streams. The ref is updated with each emitted value
+ * (keeping `waiting: true`) and is finalised (with `waiting: false`) once the
+ * stream terminates successfully. Errors are surfaced as `AsyncResult.failure`.
+ */
+export const asStreamResult = <Args extends readonly any[], A, E, R>(
+  handler: (...args: Args) => Stream.Stream<A, E, R>
+): readonly [ComputedRef<AsyncResult.AsyncResult<A, E>>, (...args: Args) => Effect.Effect<void, never, R>] => {
+  const state = shallowRef<AsyncResult.AsyncResult<A, E>>(AsyncResult.initial())
+
+  const runStream = (stream: Stream.Stream<A, E, R>): Effect.Effect<void, never, R> =>
+    Effect
+      .sync(() => {
+        state.value = AsyncResult.initial(true)
+      })
+      .pipe(
+        Effect.andThen(
+          stream.pipe(
+            Stream.runForEach((value) =>
+              Effect.sync(() => {
+                state.value = AsyncResult.success(value, { waiting: true })
+              })
+            ),
+            Effect.exit,
+            Effect.flatMap((exit) =>
+              Effect.sync(() => {
+                if (exit._tag === "Success") {
+                  const current = state.value
+                  if (AsyncResult.isSuccess(current)) {
+                    state.value = AsyncResult.success(current.value, { waiting: false })
+                  } else {
+                    state.value = AsyncResult.initial(false)
+                  }
+                } else {
+                  state.value = AsyncResult.failure(exit.cause)
+                }
+              })
             )
-          ))
+          )
         )
+      )
 
-  return tuple(computed(() => state.value), act) as any
+  const act = (...args: Args) => runStream(handler(...args))
+
+  return tuple(computed(() => state.value), act)
 }
 
-export const invalidateQueries = (
-  queryClient: QueryClient,
-  self: { id: string; options?: ClientForOptions },
-  options?: MutationOptionsBase["queryInvalidation"]
+const buildInvalidateCache = <RInvalidator>(
+  self: { id: string; options?: ClientForOptions; disableQueryInvalidation?: boolean },
+  queryInvalidation: MutationOptionsBase["queryInvalidation"] | undefined,
+  queryInvalidator: QueryInvalidator<RInvalidator>
 ) => {
-  const invalidateQueries = (
-    filters?: InvalidateQueryFilters,
-    options?: InvalidateOptions
-  ) =>
-    Effect.currentSpan.pipe(
-      Effect.orElseSucceed(() => null),
-      Effect.flatMap((span) =>
-        Effect.promise(() => queryClient.invalidateQueries(filters, { ...options, updateMeta: { span } }))
-      )
-    )
-
-  const invalidateCache = Effect.suspend(() => {
+  // Concrete reactivity keys to invalidate: a raw query key, one derived from an `{ id }`
+  // entry, or a compatibility `{ filters: { queryKey } }` entry.
+  // Predicate-only `{ filters }` entries have no exact-key reactivity equivalent and throw.
+  const getClientInvalidationKeys = (
+    input: unknown,
+    output: Exit.Exit<unknown, unknown>
+  ): ReadonlyArray<ReadonlyArray<unknown>> => {
     const queryKey = getQueryKey(self)
 
-    if (options) {
-      const opts = options(queryKey, self.id)
-      if (!opts.length) {
-        return Effect.void
+    if (queryInvalidation) {
+      const keys: Array<ReadonlyArray<unknown>> = []
+      for (const entry of queryInvalidation(queryKey, self.id, input, output)) {
+        if (isQueryKey(entry)) {
+          keys.push(entry)
+          continue
+        }
+        if ("id" in entry) {
+          keys.push(makeQueryKey(entry.options ? { id: entry.id, options: entry.options } : { id: entry.id }))
+          continue
+        }
+        const filterQueryKey = queryKeyFromFilters(entry)
+        if (filterQueryKey !== undefined) {
+          keys.push(filterQueryKey)
+          continue
+        }
+        throw new Error("Unsupported query invalidation filter: only filters.queryKey is supported")
       }
+      return keys
+    }
+
+    // No manual `invalidatesQueries`: contribute nothing. Invalidation rides entirely on the
+    // repository-derived write-dependencies (plus any server-provided keys) — there is no default
+    // namespace invalidation of the command's own resource.
+    return []
+  }
+
+  const invalidateCache = (
+    input: unknown,
+    output: Exit.Exit<unknown, unknown>,
+    serverKeys: ReadonlyArray<InvalidationKey>,
+    writeDependencies: DataDependencies.DataDependencies = DataDependencies.empty()
+  ) =>
+    Effect.suspend(() => {
+      if (self.disableQueryInvalidation) return Effect.void
+
+      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, ...derivedKeys]
+
+      if (!isReadonlyArrayNonEmpty(keys)) return Effect.void
+
+      const { awaitKeys, softKeys } = partitionInvalidationKeys(keys)
+
       return Effect
         .andThen(
-          Effect.annotateCurrentSpan({ queryKey, opts }),
-          Effect.forEach(opts, (_) => invalidateQueries(_.filters, _.options), { concurrency: "inherit" })
+          Effect.annotateCurrentSpan({
+            keys,
+            awaitKeys,
+            softKeys,
+            clientKeys,
+            serverKeys,
+            derivedKeys,
+            writeDependencies: [...writeDependencies]
+          }),
+          // refetch + AWAIT every live query registered under these keys, so by the time the
+          // mutation resolves the affected queries are fresh.
+          Effect.gen(function*() {
+            if (softKeys.length > 0) {
+              yield* (queryInvalidator.invalidateSoft?.(softKeys) ?? Effect.void).pipe(
+                Effect.catchCause((cause) =>
+                  reportRuntimeError(cause, { invalidation: "soft", keys: softKeys }).pipe(Effect.asVoid)
+                ),
+                Effect.forkDetach({ startImmediately: true })
+              )
+            }
+            if (awaitKeys.length > 0) {
+              yield* queryInvalidator.invalidateAndAwait(awaitKeys)
+            }
+          })
         )
-        .pipe(Effect.withSpan("client.query.invalidation", {}, { captureStackTrace: false }))
-    }
+        .pipe(
+          Effect.tap(Effect.sleep(0.1)), // allow for refs to update etc
+          Effect.withSpan("client.query.invalidation", {}, { captureStackTrace: false })
+        )
+    })
 
-    if (!queryKey) return Effect.void
+  return invalidateCache
+}
 
-    return Effect
-      .andThen(
-        Effect.annotateCurrentSpan({ queryKey }),
-        invalidateQueries({ queryKey })
-      )
-      .pipe(
-        Effect.tap(
-          // hand over control back to the event loop so that state can be updated..
-          // TODO: should we do this in general on any mutation, regardless of invalidation?
-          Effect.sleep(0)
-        ),
-        Effect.withSpan("client.query.invalidation", {}, { captureStackTrace: false })
-      )
-  })
+export const invalidateQueries = <RInvalidator>(
+  self: { id: string; options?: ClientForOptions; disableQueryInvalidation?: boolean },
+  options: MutationOptionsBase | undefined,
+  queryInvalidator: QueryInvalidator<RInvalidator>
+) => {
+  const invalidateCache = buildInvalidateCache(self, options?.queryInvalidation, queryInvalidator)
 
-  const handle = <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.ensuring(self, invalidateCache)
+  const select = options?.select
+
+  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.empty())
+      const writesRef = yield* Ref.make(DataDependencies.empty())
+      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)
+            const writeDependencies = yield* Ref.get(writesRef)
+            yield* invalidateCache(input, exit, serverKeys, writeDependencies)
+          })
+        )
+      )
+      if (select) {
+        return yield* select(result).pipe(
+          Effect.onExit((exit) =>
+            Effect.gen(function*() {
+              const serverKeys = yield* Ref.get(keysRef)
+              const writeDependencies = yield* Ref.get(writesRef)
+              yield* invalidateCache(input, exit, serverKeys, writeDependencies)
+            })
+          )
+        )
+      }
+      return result
+    })
 
   return handle
 }
 
-export const makeMutation = () => {
-  const useMutation: {
-    /**
-     * Pass a function that returns an Effect, e.g from a client action
-     * Executes query cache invalidation based on default rules or provided option.
-     */
-    <I, E, A, R, Request extends Req, Id extends string>(
-      self: RequestHandlerWithInput<I, A, E, R, Request, Id>,
-      options?: MutationOptionsBase
-    ): ((i: I) => Effect.Effect<A, E, R>) & { readonly id: Id }
-    /**
-     * Pass an Effect, e.g from a client action
-     * Executes query cache invalidation based on default rules or provided option.
-     */
-    <E, A, R, Request extends Req, Id extends string>(
-      self: RequestHandler<A, E, R, Request, Id>,
-      options?: MutationOptionsBase
-    ): Effect.Effect<A, E, R> & { readonly id: Id }
-  } = <I, E, A, R, Request extends Req, Id extends string>(
-    self: RequestHandlerWithInput<I, A, E, R, Request, Id> | RequestHandler<A, E, R, Request, Id>,
-    options?: MutationOptionsBase
-  ) => {
-    const queryClient = useQueryClient()
-    const handle = invalidateQueries(queryClient, self, options?.queryInvalidation)
-    const handler = self.handler
-    const r = Effect.isEffect(handler) ? handle(handler) : (i: I) => handle(handler(i))
+/**
+ * A callable mutation result. When `I = void` the input argument may be omitted.
+ */
+export interface MutationFn<I, A, E, R, Id extends string> {
+  <B = A, E2 = never, R2 = never>(
+    input: I,
+    options?: MutationOptionsBase<A, B, E2, R2>
+  ): Effect.Effect<B, E | E2, R | R2>
+  readonly id: Id
+}
 
+export const makeMutation = <RInvalidator>(queryInvalidator: QueryInvalidator<RInvalidator>) => {
+  /**
+   * Pass a function that returns an Effect, e.g from a client action.
+   * Executes query cache invalidation based on default rules or provided option.
+   * When `I = void` the input argument may be omitted.
+   */
+  const useMutation = <I, E, A, R, Request extends Req, Id extends string>(
+    self: RequestHandlerWithInput<I, A, E, R, Request, Id>
+  ): MutationFn<I, A, E, R, Id> => {
+    const r = (i: I, options?: MutationOptionsBase) =>
+      invalidateQueries(self, options, queryInvalidator)(self.handler(i), i)
     return Object.assign(r, { id: self.id }) as any
   }
   return useMutation
 }
 
-// calling hooks in the body
-export const useMakeMutation = () => {
-  const queryClient = useQueryClient()
-
-  const useMutation: {
-    /**
-     * Pass a function that returns an Effect, e.g from a client action
-     * Executes query cache invalidation based on default rules or provided option.
-     */
-    <I, E, A, R, Request extends Req, Id extends string>(
-      self: RequestHandlerWithInput<I, A, E, R, Request, Id>,
-      options?: MutationOptionsBase
-    ): ((i: I) => Effect.Effect<A, E, R>) & { readonly id: Id }
-    /**
-     * Pass an Effect, e.g from a client action
-     * Executes query cache invalidation based on default rules or provided option.
-     */
-    <E, A, R, Request extends Req, Id extends string>(
-      self: RequestHandler<A, E, R, Request, Id>,
-      options?: MutationOptionsBase
-    ): Effect.Effect<A, E, R> & { readonly id: Id }
-  } = <I, E, A, R, Request extends Req, Id extends string>(
-    self: RequestHandlerWithInput<I, A, E, R, Request, Id> | RequestHandler<A, E, R, Request, Id>,
-    options?: MutationOptionsBase
-  ) => {
-    const handle = invalidateQueries(queryClient, self, options?.queryInvalidation)
-    const handler = self.handler
-    const r = Effect.isEffect(handler) ? handle(handler) : (i: I) => handle(handler(i))
-
+export const useMakeMutation = <RInvalidator>(queryInvalidator: QueryInvalidator<RInvalidator>) => {
+  /**
+   * Pass a function that returns an Effect, e.g from a client action.
+   * Executes query cache invalidation based on default rules or provided option.
+   * When `I = void` the input argument may be omitted.
+   */
+  const useMutation = <I, E, A, R, Request extends Req, Id extends string>(
+    self: RequestHandlerWithInput<I, A, E, R, Request, Id>
+  ): MutationFn<I, A, E, R, Id> => {
+    const r = (i: I, options?: MutationOptionsBase) =>
+      invalidateQueries(self, options, queryInvalidator)(self.handler(i), i)
     return Object.assign(r, { id: self.id }) as any
   }
   return useMutation
 }
+
+/**
+ * Returns a stream-based mutation factory for use with `streamFn`.
+ * The outer Effect sets up per-invocation invalidation scaffolding
+ * and returns a stream that triggers query invalidation via `Stream.ensuring` when it completes.
+ *
+ * Use with `streamFn` / `Command.streamFn(id)(mutateHandler, ...combinators)` so that
+ * the command manages its own reactive state internally.
+ */
+export const makeStreamMutation2 = <RInvalidator>(queryInvalidator: QueryInvalidator<RInvalidator>) => {
+  return (
+    self: {
+      id: string
+      options?: ClientForOptions
+      disableQueryInvalidation?: boolean
+      handler: (i: any) => Stream.Stream<any, any, any>
+    },
+    mergedInvalidation?: MutationOptionsBase["queryInvalidation"]
+  ) => {
+    const invCache = buildInvalidateCache(self, mergedInvalidation, queryInvalidator)
+
+    const makeInvocationEffect = (input: unknown, source: Stream.Stream<any, any, any>) =>
+      Effect.gen(function*() {
+        const keysRef = yield* Ref.make<ReadonlyArray<InvalidationKey>>([])
+        // Server invalidation keys stay settlement-only: flushing them from `add` refetched
+        // live queries once per chunk (One-Pick List storms). Write-deps flush once when the
+        // first write arrives (job create → GetActiveJob) and again from `ensuring`.
+        const invKeys = makeInvalidationKeysService(keysRef)
+        const readsRef = yield* Ref.make(DataDependencies.empty())
+        const writesRef = yield* Ref.make(DataDependencies.empty())
+        const dependencyRecorder = DataDependencies.makeDataDependencyRecorder(readsRef, writesRef)
+        const lastRef = yield* Ref.make<any>(undefined)
+        let flushedFirstWrites = false
+        const flushFirstWrites = Effect.gen(function*() {
+          if (flushedFirstWrites) return
+          const writeDependencies = yield* Ref.get(writesRef)
+          if (!DataDependencies.isNonEmpty(writeDependencies)) return
+          flushedFirstWrites = true
+          const lastValue = yield* Ref.get(lastRef)
+          yield* invCache(input, Exit.succeed(lastValue), [], writeDependencies)
+        })
+        return source.pipe(
+          Stream.provideService(InvalidationKeysFromServer, invKeys),
+          Stream.provideService(DataDependencies.DataDependencyRecorder, dependencyRecorder),
+          Stream.tap((v) => Ref.set(lastRef, v)),
+          Stream.tap(() => flushFirstWrites),
+          Stream.ensuring(
+            Effect.gen(function*() {
+              const lastValue = yield* Ref.get(lastRef)
+              const serverKeys = yield* Ref.get(keysRef)
+              const writeDependencies = yield* Ref.get(writesRef)
+              yield* invCache(input, Exit.succeed(lastValue), serverKeys, writeDependencies)
+            })
+          )
+        )
+      })
+
+    return (i: any) => Stream.unwrap(makeInvocationEffect(i, self.handler(i)))
+  }
+}