@playfast/reform 0.0.7 → 0.0.9

package/src/calc/calc.ts

@@ -0,0 +1,120 @@
+import { Context, Effect, Layer, MutableRef, type Schema } from 'effect'
+import { type Manifest, yieldableClass } from '../definition/definition'
+import {
+  type InputsObject,
+  type InputStores,
+  type InvalidateBy,
+  sameKey,
+  wireSources,
+} from '../internal/sources'
+import { resolveScheduler } from '../internal/scheduler'
+import { reuse } from '../internal/reuse'
+import { makeDerivedStore, type Store } from '../internal/store'
+import { readTracked } from '../internal/track'
+import { type AnySource } from '../state/token'
+
+// Re-exported so `Calc.InputsObject` / `Calc.InvalidateBy` keep their home here
+// even though the reactive plumbing now lives in `internal/sources`.
+export { type InputsObject, type InputStores, type InvalidateBy } from '../internal/sources'
+
+export interface CalcOptions<Inputs extends ReadonlyArray<AnySource>> {
+  /**
+   * Custom invalidation: recompute only when the projected key changes by value
+   * equality (React-Query's `queryKey`). Omitted ⇒ recompute when any input
+   * value changes. Shared with `AsyncCalc`.
+   */
+  readonly invalidateBy?: InvalidateBy<Inputs>
+  /**
+   * Structural sharing: reconcile each recomputed output against the previous
+   * one, substituting previous nodes wherever value equality holds — so
+   * identities only move where values moved and downstream memo boundaries
+   * (React subtrees) skip unchanged regions. Referentially transparent (the
+   * result is value-equal to the fresh output); costs one O(output) walk per
+   * recompute, so opt in for large projections.
+   */
+  readonly reuse?: boolean
+}
+
+export interface CalcManifest<N extends string, Out> extends Manifest {
+  readonly kind: 'Calc'
+  readonly name: N
+  readonly output: Schema.Schema<Out, any>
+}
+
+export interface CalcClass<out N extends string, out Inputs extends ReadonlyArray<AnySource>, in out Out>
+  extends Effect.Effect<Out, never, Store<Out>> {
+  new (): {}
+  readonly manifest: CalcManifest<N, Out>
+  readonly store: Context.Tag<Store<Out>, Store<Out>>
+  /** The calc's name, so it doubles as a `Source` input to another calc. */
+  readonly name: N
+  /** Marker data read by `Calc.live`. */
+  readonly inputs: Inputs
+}
+
+export interface CalcConfig<Inputs extends ReadonlyArray<AnySource>, Out> {
+  readonly inputs: Inputs
+  readonly output: Schema.Schema<Out, any>
+}
+
+/**
+ * A derived, memoized value over explicit inputs (state members, other calcs, or
+ * async calcs). The *definition* fixes the inputs and the output schema; the
+ * *implementation* is the pure projection. Recomputes only when an input changes;
+ * `yield* Calc` reads the memoized value.
+ */
+export const make = <const N extends string, const Inputs extends ReadonlyArray<AnySource>, Out>(
+  name: N,
+  config: CalcConfig<Inputs, Out>,
+): CalcClass<N, Inputs, Out> => {
+  const store = Context.GenericTag<Store<Out>, Store<Out>>(`reform/calc/${name}`)
+  const manifest: CalcManifest<N, Out> = { kind: 'Calc', name, output: config.output }
+  const read = Effect.flatMap(store, readTracked)
+  return yieldableClass(read, { manifest, store, name, inputs: config.inputs })
+}
+
+/**
+ * Wire the pure projection for a calc. Recomputes only when its invalidation key
+ * changes (by default every input value; override with `invalidateBy`), memoized
+ * on that key; `yield* Calc` reads the memoized value. The derived store reuses
+ * the shared coalescing scheduler, so a recompute that yields an equal value
+ * wakes no subscriber.
+ */
+export const live = <N extends string, Inputs extends ReadonlyArray<AnySource>, Out>(
+  calc: CalcClass<N, Inputs, Out>,
+  compute: (inputs: InputsObject<Inputs>) => Out,
+  options: CalcOptions<Inputs> = {},
+): Layer.Layer<Store<Out>, never, InputStores<Inputs>> =>
+  // Scoped so the source subscriptions are released when the layer's scope
+  // closes (each proof/test builds and disposes its own runtime).
+  Layer.scoped(
+    calc.store,
+    Effect.gen(function* () {
+      const scheduler = yield* resolveScheduler
+      const sources = yield* wireSources(calc.inputs, options.invalidateBy)
+
+      // Memo cell: key and output captured together so reads are always
+      // consistent (no separate output that could lag the key it was computed for).
+      const memo = MutableRef.make<
+        { readonly key: ReadonlyArray<unknown>; readonly output: Out } | undefined
+      >(undefined)
+      const recompute = (): Out => {
+        const args = sources.snapshot()
+        const key = sources.keyOf(args)
+        const prev = MutableRef.get(memo)
+        if (prev !== undefined && sameKey(key, prev.key)) return prev.output
+        const fresh = compute(args)
+        // With `reuse`, a recompute that lands value-equal to the previous
+        // output returns the previous reference — the derived store's Equal
+        // gate then wakes no subscriber at all.
+        const output =
+          options.reuse === true && prev !== undefined ? reuse(prev.output, fresh) : fresh
+        MutableRef.set(memo, { key, output })
+        return output
+      }
+
+      const derived = makeDerivedStore(recompute, sources.subscribe, scheduler)
+      yield* Effect.addFinalizer(() => Effect.sync(derived.unsubscribe))
+      return derived.store
+    }),
+  )

package/src/calc/calcFamily.test.ts

@@ -0,0 +1,206 @@
+import { expect, it } from '@effect/vitest'
+import { Context, Duration, Effect, Exit, Layer, Schema as S, Scope } from 'effect'
+import { CalcFamily, State, StateGroup } from '../index'
+
+// CalcFamily: per-key derived stores over shared inputs. The behaviours under
+// test: members derive + memoize independently, a member only notifies when ITS
+// output moves, and every removal path releases the member's upstream
+// subscription (a derived member holds one; a StateFamily entry doesn't).
+
+const tick = Effect.sleep(Duration.millis(1))
+
+// Shared fixture shape: a record of named counters; each member projects one.
+const Board = S.Record({ key: S.String, value: S.Number })
+
+const fixture = () => {
+  class Feed extends State.make('feed', Board) {}
+  class Inputs extends StateGroup.make(Feed) {}
+  const runs = new Map<string, number>()
+  class Slice extends CalcFamily.make('Slice', {
+    key: S.String,
+    inputs: [StateGroup.select(Inputs, 'feed')],
+    output: S.Number,
+  }) {}
+  const SliceLive = CalcFamily.live(Slice, (key) => ({ feed }) => {
+    runs.set(key, (runs.get(key) ?? 0) + 1)
+    return feed[key] ?? 0
+  })
+  return { Inputs, Slice, SliceLive, runs }
+}
+
+it.live('a member derives from the shared inputs and recomputes when they change', () => {
+  const { Inputs, Slice, SliceLive } = fixture()
+  const TestLayer = SliceLive.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { feed: { a: 1, b: 10 } })),
+  )
+  return Effect.gen(function* () {
+    const feed = yield* StateGroup.select(Inputs, 'feed').store
+    expect(yield* CalcFamily.read(Slice, 'a')).toBe(1)
+    expect(yield* CalcFamily.read(Slice, 'b')).toBe(10)
+
+    feed.set({ a: 2, b: 10 })
+    yield* tick
+    expect(yield* CalcFamily.read(Slice, 'a')).toBe(2)
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('a member only notifies when its own slice of the projection moves', () => {
+  const { Inputs, Slice, SliceLive } = fixture()
+  const TestLayer = SliceLive.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { feed: { a: 1, b: 10 } })),
+  )
+  return Effect.gen(function* () {
+    const feed = yield* StateGroup.select(Inputs, 'feed').store
+    const family = yield* Slice.store
+    const wakes = { a: 0, b: 0 }
+    family.at('a').subscribe(() => {
+      wakes.a += 1
+    })
+    family.at('b').subscribe(() => {
+      wakes.b += 1
+    })
+
+    // Only `a` moves: b's member recomputes but its output is Equal — silent.
+    feed.set({ a: 2, b: 10 })
+    yield* tick
+    expect(wakes).toEqual({ a: 1, b: 0 })
+
+    feed.set({ a: 2, b: 11 })
+    yield* tick
+    expect(wakes).toEqual({ a: 1, b: 1 })
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('reading does not recompute while the shared inputs are unchanged (memoized per member)', () => {
+  const { Inputs, Slice, SliceLive, runs } = fixture()
+  const TestLayer = SliceLive.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { feed: { a: 1 } })),
+  )
+  return Effect.gen(function* () {
+    yield* CalcFamily.read(Slice, 'a')
+    yield* CalcFamily.read(Slice, 'a')
+    yield* CalcFamily.read(Slice, 'a')
+    expect(runs.get('a')).toBe(1)
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('invalidateBy: shared-input churn outside the key recomputes no member', () => {
+  class Feed extends State.make('feed', Board) {}
+  class Noise extends State.make('noise', S.Number) {}
+  class Inputs extends StateGroup.make(Feed, Noise) {}
+  const runs = new Map<string, number>()
+  class Slice extends CalcFamily.make('Slice', {
+    key: S.String,
+    inputs: [StateGroup.select(Inputs, 'feed'), StateGroup.select(Inputs, 'noise')],
+    output: S.Number,
+  }) {}
+  const SliceLive = CalcFamily.live(
+    Slice,
+    (key) => ({ feed }) => {
+      runs.set(key, (runs.get(key) ?? 0) + 1)
+      return feed[key] ?? 0
+    },
+    { invalidateBy: ({ feed }) => [feed] },
+  )
+  const TestLayer = SliceLive.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { feed: { a: 1 }, noise: 0 })),
+  )
+  return Effect.gen(function* () {
+    const noise = yield* StateGroup.select(Inputs, 'noise').store
+    expect(yield* CalcFamily.read(Slice, 'a')).toBe(1)
+    expect(runs.get('a')).toBe(1)
+
+    noise.set(99)
+    yield* tick
+    expect(yield* CalcFamily.read(Slice, 'a')).toBe(1)
+    expect(runs.get('a')).toBe(1)
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('forget releases the member and its upstream subscription', () => {
+  const { Inputs, Slice, SliceLive, runs } = fixture()
+  const TestLayer = SliceLive.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { feed: { a: 1 } })),
+  )
+  return Effect.gen(function* () {
+    const feed = yield* StateGroup.select(Inputs, 'feed').store
+    const family = yield* Slice.store
+    family.at('a')
+    expect(family.size()).toBe(1)
+
+    family.forget('a')
+    expect(family.size()).toBe(0)
+    // The dropped member no longer recomputes on upstream churn.
+    const before = runs.get('a') ?? 0
+    feed.set({ a: 2 })
+    yield* tick
+    expect(runs.get('a') ?? 0).toBe(before)
+
+    // Re-`at`-ing allocates a fresh member over the current snapshot.
+    expect(family.at('a').get()).toBe(2)
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('evictWhenUnused: an idle member is dropped on the next microtask and unsubscribes', () => {
+  class Feed extends State.make('feed', Board) {}
+  class Inputs extends StateGroup.make(Feed) {}
+  const runs = new Map<string, number>()
+  class Slice extends CalcFamily.make('Slice', {
+    key: S.String,
+    inputs: [StateGroup.select(Inputs, 'feed')],
+    output: S.Number,
+  }) {}
+  const SliceLive = CalcFamily.live(
+    Slice,
+    (key) => ({ feed }) => {
+      runs.set(key, (runs.get(key) ?? 0) + 1)
+      return feed[key] ?? 0
+    },
+    { evictWhenUnused: true },
+  )
+  const TestLayer = SliceLive.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { feed: { a: 1 } })),
+  )
+  return Effect.gen(function* () {
+    const feed = yield* StateGroup.select(Inputs, 'feed').store
+    const family = yield* Slice.store
+    const off = family.at('a').subscribe(() => {})
+    expect(family.size()).toBe(1)
+
+    off()
+    yield* tick
+    expect(family.size()).toBe(0)
+    const before = runs.get('a') ?? 0
+    feed.set({ a: 2 })
+    yield* tick
+    expect(runs.get('a') ?? 0).toBe(before)
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('the layer finalizer clears every member (no live subscriptions leak)', () => {
+  const { Inputs, Slice, SliceLive, runs } = fixture()
+  return Effect.scoped(
+    Effect.gen(function* () {
+      // Build the input stores once, then the family in its OWN scope over that
+      // exact context — so the stores outlive the family and we can prove the
+      // members' upstream subscriptions died with it.
+      const storesCtx = yield* Layer.build(StateGroup.live(Inputs, { feed: { a: 1, b: 2 } }))
+      const feed = Context.get(storesCtx, StateGroup.select(Inputs, 'feed').store)
+      const scope = yield* Scope.make()
+      const familyCtx = yield* Layer.buildWithScope(SliceLive, scope).pipe(
+        Effect.provide(storesCtx),
+      )
+      const family = Context.get(familyCtx, Slice.store)
+      family.at('a')
+      family.at('b')
+      expect(family.size()).toBe(2)
+
+      yield* Scope.close(scope, Exit.void)
+      expect(family.size()).toBe(0)
+      const before = [runs.get('a') ?? 0, runs.get('b') ?? 0]
+      feed.set({ a: 9, b: 9 })
+      yield* tick
+      expect([runs.get('a') ?? 0, runs.get('b') ?? 0]).toEqual(before)
+    }),
+  )
+})

package/src/calc/calcFamily.ts

@@ -0,0 +1,194 @@
+import { Context, Effect, Layer, MutableRef, type Schema } from 'effect'
+import { type Manifest, definitionClass } from '../definition/definition'
+import {
+  type InputsObject,
+  type InputStores,
+  type InvalidateBy,
+  sameKey,
+  wireSources,
+} from '../internal/sources'
+import { resolveScheduler } from '../internal/scheduler'
+import { makeDerivedStore, type Store } from '../internal/store'
+import { readTracked } from '../internal/track'
+import { type FamilyOptions, type FamilyStore } from '../state/stateFamily'
+import { type AnySource } from '../state/token'
+
+// `CalcFamily` is `Calc`'s keyed sibling, modeled on `StateFamily`: one derived,
+// memoized store per key over a SHARED set of inputs. Where a monolithic calc
+// rebuilds its whole output on any change (waking every consumer), a family
+// member recomputes lazily and notifies only when ITS slice of the projection
+// moves (the derived store's Equal gate) — per-row/per-group UI subscribes per
+// key and unrelated changes never wake it. Members are pure projections; a
+// Reducer cannot target a CalcFamily (its config requires a `StateFamily`
+// manifest), so calc purity holds structurally.
+
+export interface CalcFamilyManifest<N extends string, K, Out> extends Manifest {
+  readonly kind: 'CalcFamily'
+  readonly name: N
+  readonly key: Schema.Schema<K, any>
+  readonly output: Schema.Schema<Out, any>
+}
+
+export interface CalcFamilyClass<
+  out N extends string,
+  out Inputs extends ReadonlyArray<AnySource>,
+  in out K,
+  in out Out,
+> {
+  /** Instance carries the key phantom so `Family['Key']` resolves in key types. */
+  new (): { readonly Key: K }
+  readonly manifest: CalcFamilyManifest<N, K, Out>
+  readonly store: Context.Tag<FamilyStore<K, Out>, FamilyStore<K, Out>>
+  /** Marker data read by `CalcFamily.live` and the editor's graph builder. */
+  readonly inputs: Inputs
+}
+
+export interface CalcFamilyConfig<Inputs extends ReadonlyArray<AnySource>, K, Out> {
+  readonly key: Schema.Schema<K, any>
+  readonly inputs: Inputs
+  readonly output: Schema.Schema<Out, any>
+}
+
+/**
+ * Define a keyed derived value: per-key memoized projections over shared
+ * inputs. The *definition* fixes the key/output schemas and the inputs; the
+ * *implementation* (the per-key projection) is supplied by `CalcFamily.live`.
+ */
+export const make = <const N extends string, const Inputs extends ReadonlyArray<AnySource>, K, Out>(
+  name: N,
+  config: CalcFamilyConfig<Inputs, K, Out>,
+): CalcFamilyClass<N, Inputs, K, Out> => {
+  const store = Context.GenericTag<FamilyStore<K, Out>, FamilyStore<K, Out>>(
+    `reform/calcFamily/${name}`,
+  )
+  const manifest: CalcFamilyManifest<N, K, Out> = {
+    kind: 'CalcFamily',
+    name,
+    key: config.key,
+    output: config.output,
+  }
+  return definitionClass<CalcFamilyClass<N, Inputs, K, Out>>({
+    manifest,
+    store,
+    inputs: config.inputs,
+  })
+}
+
+/**
+ * Read one member by key — `CalcFamily.read(GroupProjection, id)`. Inside a
+ * render it subscribes exactly that member's store (unrelated members never
+ * wake the subtree); elsewhere it just snapshots — the same one-read-API
+ * contract as `StateFamily.read`.
+ */
+export const read = <N extends string, Inputs extends ReadonlyArray<AnySource>, K, Out>(
+  family: CalcFamilyClass<N, Inputs, K, Out>,
+  key: K,
+): Effect.Effect<Out, never, FamilyStore<K, Out>> =>
+  Effect.flatMap(family.store, (fs) => readTracked(fs.at(key)))
+
+export interface CalcFamilyLiveOptions<Inputs extends ReadonlyArray<AnySource>>
+  extends FamilyOptions {
+  /**
+   * Family-wide invalidation key over the SHARED inputs (the member key plays
+   * no part — it is fixed per member). Same contract as `Calc`'s.
+   */
+  readonly invalidateBy?: InvalidateBy<Inputs>
+}
+
+/**
+ * Wire the per-key projection. `compute` is curried — `(key) => (inputs) =>
+ * Out` — so per-key construction (closing over key-derived constants) runs once
+ * per member while the inner projection runs per recompute. Each member is a
+ * lazy derived store over the shared wired sources: memoized on the family's
+ * invalidation key, notifying only when its own output moves. Unlike a
+ * `StateFamily` entry, a member holds an upstream subscription, so every
+ * removal path (forget / clear / eviction / the layer finalizer) releases it.
+ */
+export const live = <N extends string, Inputs extends ReadonlyArray<AnySource>, K, Out>(
+  family: CalcFamilyClass<N, Inputs, K, Out>,
+  compute: (key: K) => (inputs: InputsObject<Inputs>) => Out,
+  options: CalcFamilyLiveOptions<Inputs> = {},
+): Layer.Layer<FamilyStore<K, Out>, never, InputStores<Inputs>> =>
+  Layer.scoped(
+    family.store,
+    Effect.gen(function* () {
+      const scheduler = yield* resolveScheduler
+      // Wired ONCE for the whole family — members share the sensing surface.
+      const sources = yield* wireSources(family.inputs, options.invalidateBy)
+      const entries = new Map<K, { readonly store: Store<Out>; readonly unsubscribe: () => void }>()
+      const evictWhenUnused = options.evictWhenUnused === true
+      // Live subscriber count per key — maintained only when eviction is on.
+      const subscribers = new Map<K, number>()
+
+      const dropEntry = (key: K): void => {
+        const entry = entries.get(key)
+        if (entry !== undefined) entry.unsubscribe()
+        entries.delete(key)
+        subscribers.delete(key)
+      }
+
+      // One member: the same memo block as `Calc.live`, with the key closed over.
+      const createMember = (key: K): { readonly store: Store<Out>; readonly unsubscribe: () => void } => {
+        const body = compute(key)
+        const memo = MutableRef.make<
+          { readonly key: ReadonlyArray<unknown>; readonly output: Out } | undefined
+        >(undefined)
+        const recompute = (): Out => {
+          const args = sources.snapshot()
+          const memoKey = sources.keyOf(args)
+          const prev = MutableRef.get(memo)
+          if (prev !== undefined && sameKey(memoKey, prev.key)) return prev.output
+          const output = body(args)
+          MutableRef.set(memo, { key: memoKey, output })
+          return output
+        }
+        return makeDerivedStore(recompute, sources.subscribe, scheduler)
+      }
+
+      // The `StateFamily` ref-count idiom: evict on the next microtask once a
+      // key falls idle (a same-commit re-subscribe cancels it) — here eviction
+      // also releases the member's upstream subscription via `dropEntry`.
+      const refCounted = (key: K, store: Store<Out>): Store<Out> => ({
+        ...store,
+        subscribe: (listener) => {
+          subscribers.set(key, (subscribers.get(key) ?? 0) + 1)
+          const off = store.subscribe(listener)
+          const released = { done: false }
+          return () => {
+            if (released.done) return
+            released.done = true
+            off()
+            const remaining = (subscribers.get(key) ?? 1) - 1
+            if (remaining > 0) {
+              subscribers.set(key, remaining)
+              return
+            }
+            subscribers.delete(key)
+            queueMicrotask(() => {
+              if ((subscribers.get(key) ?? 0) === 0) dropEntry(key)
+            })
+          }
+        },
+      })
+
+      const familyStore: FamilyStore<K, Out> = {
+        at: (key) => {
+          const existing = entries.get(key)
+          if (existing !== undefined) return existing.store
+          const member = createMember(key)
+          const created = evictWhenUnused
+            ? { store: refCounted(key, member.store), unsubscribe: member.unsubscribe }
+            : member
+          entries.set(key, created)
+          return created.store
+        },
+        forget: dropEntry,
+        clear: () => {
+          for (const key of [...entries.keys()]) dropEntry(key)
+        },
+        size: () => entries.size,
+      }
+      yield* Effect.addFinalizer(() => Effect.sync(() => familyStore.clear()))
+      return familyStore
+    }),
+  )

package/src/calc/compose.test.ts

@@ -0,0 +1,68 @@
+import { expect, it } from '@effect/vitest'
+import { Effect, Layer, Schema as S } from 'effect'
+import { Calc, composeCalcs, State, StateGroup } from '../index'
+
+// `composeCalcs` wires a calc-on-calc chain in dependency order. The shape under
+// test is the one that defeats a flat `Layer.mergeAll`: a linear chain where each
+// calc's only input is the previous calc — count → Doubled → PlusOne → Tripled.
+
+it.live('composeCalcs wires a linear calc chain; the result needs only the base state', () => {
+  class Count extends State.make('count', S.Number) {}
+  class Inputs extends StateGroup.make(Count) {}
+
+  class Doubled extends Calc.make('Doubled', {
+    inputs: [StateGroup.select(Inputs, 'count')],
+    output: S.Number,
+  }) {}
+  const DoubledLive = Calc.live(Doubled, ({ count }) => count * 2)
+
+  class PlusOne extends Calc.make('PlusOne', { inputs: [Doubled], output: S.Number }) {}
+  const PlusOneLive = Calc.live(PlusOne, ({ Doubled }) => Doubled + 1)
+
+  class Tripled extends Calc.make('Tripled', { inputs: [PlusOne], output: S.Number }) {}
+  const TripledLive = Calc.live(Tripled, ({ PlusOne }) => PlusOne * 3)
+
+  // Leaf-first, then upstreams in dependency order. The composed layer's only
+  // remaining requirement is the base `count` store — which the type system
+  // proves by letting us provide *only* the state group below.
+  // The chain's only remaining requirement is the base `count` store — provide
+  // (and expose, via provideMerge) just the state group and everything builds.
+  const Chain = composeCalcs(TripledLive, PlusOneLive, DoubledLive)
+  const TestLayer = Chain.pipe(Layer.provideMerge(StateGroup.live(Inputs, { count: 5 })))
+
+  return Effect.gen(function* () {
+    const source = yield* StateGroup.select(Inputs, 'count').store
+    const tripled = yield* Tripled.store
+    // count 5 → Doubled 10 → PlusOne 11 → Tripled 33
+    expect(tripled.get()).toBe(33)
+
+    source.set(2)
+    yield* Effect.yieldNow()
+    // count 2 → Doubled 4 → PlusOne 5 → Tripled 15
+    expect(tripled.get()).toBe(15)
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('composeCalcs(leaf, upstream) matches the hand-written provideMerge chain', () => {
+  class Count extends State.make('count', S.Number) {}
+  class Inputs extends StateGroup.make(Count) {}
+  class Doubled extends Calc.make('Doubled', {
+    inputs: [StateGroup.select(Inputs, 'count')],
+    output: S.Number,
+  }) {}
+  const DoubledLive = Calc.live(Doubled, ({ count }) => count * 2)
+  class PlusDoubled extends Calc.make('PlusDoubled', {
+    inputs: [StateGroup.select(Inputs, 'count'), Doubled],
+    output: S.Number,
+  }) {}
+  const PlusDoubledLive = Calc.live(PlusDoubled, ({ count, Doubled }) => count + Doubled)
+
+  const TestLayer = composeCalcs(PlusDoubledLive, DoubledLive).pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { count: 5 })),
+  )
+
+  return Effect.gen(function* () {
+    const derived = yield* PlusDoubled.store
+    expect(derived.get()).toBe(15) // 5 + (5*2), same as the manual-pipe test
+  }).pipe(Effect.provide(TestLayer))
+})

package/src/calc/compose.ts

@@ -0,0 +1,69 @@
+import { Layer } from 'effect'
+
+// Wiring a calc-on-calc chain (`FilteredAgents` ← `AllAgents` ← `AgentsQuery`)
+// is the one calc-graph shape that trips people up: each upstream calc's store
+// must be *provided into* the downstream live, in dependency order. A flat
+// `Layer.mergeAll(FilteredLive, AllLive, QueryLive)` does NOT do this — `mergeAll`
+// merges outputs but never provides members to one another, so the upstream
+// calc stores stay as unmet `Store<…>` requirements (the TS2322 the migration
+// hit). The correct shape is `leaf.pipe(provideMerge(u1), provideMerge(u2), …)`;
+// `composeCalcs` is that fold under one name so the right thing is the easy thing.
+
+/**
+ * Compose a calc-dependency chain: provide each upstream calc's `.live` layer
+ * into the downstream one, nearest dependency first. The result exposes every
+ * calc store in the chain and requires only the chain's *external* inputs (the
+ * base state stores) — never the intermediate calc stores.
+ *
+ * Order is leaf-first, then its upstreams in dependency order:
+ * `composeCalcs(FilteredLive, AllLive, QueryLive)` ≡
+ * `FilteredLive.pipe(Layer.provideMerge(AllLive), Layer.provideMerge(QueryLive))`.
+ * For chains deeper than three upstreams, nest `composeCalcs`.
+ */
+export function composeCalcs<LOut, LErr, LIn, AOut, AErr, AIn>(
+  leaf: Layer.Layer<LOut, LErr, LIn>,
+  upstream: Layer.Layer<AOut, AErr, AIn>,
+): Layer.Layer<LOut | AOut, LErr | AErr, AIn | Exclude<LIn, AOut>>
+export function composeCalcs<LOut, LErr, LIn, AOut, AErr, AIn, BOut, BErr, BIn>(
+  leaf: Layer.Layer<LOut, LErr, LIn>,
+  upstream1: Layer.Layer<AOut, AErr, AIn>,
+  upstream2: Layer.Layer<BOut, BErr, BIn>,
+): Layer.Layer<
+  LOut | AOut | BOut,
+  LErr | AErr | BErr,
+  BIn | Exclude<AIn | Exclude<LIn, AOut>, BOut>
+>
+export function composeCalcs<
+  LOut,
+  LErr,
+  LIn,
+  AOut,
+  AErr,
+  AIn,
+  BOut,
+  BErr,
+  BIn,
+  COut,
+  CErr,
+  CIn,
+>(
+  leaf: Layer.Layer<LOut, LErr, LIn>,
+  upstream1: Layer.Layer<AOut, AErr, AIn>,
+  upstream2: Layer.Layer<BOut, BErr, BIn>,
+  upstream3: Layer.Layer<COut, CErr, CIn>,
+): Layer.Layer<
+  LOut | AOut | BOut | COut,
+  LErr | AErr | BErr | CErr,
+  CIn | Exclude<BIn | Exclude<AIn | Exclude<LIn, AOut>, BOut>, COut>
+>
+export function composeCalcs(
+  leaf: Layer.Layer<unknown, unknown, unknown>,
+  ...upstream: ReadonlyArray<Layer.Layer<unknown, unknown, unknown>>
+): Layer.Layer<unknown, unknown, unknown> {
+  // Fold leaf-first: each upstream is provided into the accumulated downstream,
+  // so dependency order is exactly the argument order.
+  return upstream.reduce<Layer.Layer<unknown, unknown, unknown>>(
+    (downstream, up) => Layer.provideMerge(downstream, up),
+    leaf,
+  )
+}