@playfast/reform 0.0.2 → 0.0.4

package/{dist/esm/internal/errors.js → src/internal/errors.ts}

@@ -1,54 +1,69 @@
-import { Data } from 'effect';
+import { Data } from 'effect'
+
 /**
  * Tagged errors for the framework's synchronous boundaries. Even when thrown
  * (React render, layer build, reflection), an error carries a `_tag` and its
  * structured fields — never a bare `Error` — so callers and tooling can match on
  * it. `Data.TaggedError` subclasses are real `Error`s, so `throw` still works.
  */
+
 /** A `<slots.X/>` was rendered without a render-target host to realize it. */
-export class SlotRenderingUnavailable extends Data.TaggedError('reform/SlotRenderingUnavailable') {
-    get message() {
-        return `reform: rendering slot '${this.slot}' requires @reform/react`;
-    }
+export class SlotRenderingUnavailable extends Data.TaggedError('reform/SlotRenderingUnavailable')<{
+  readonly slot: string
+}> {
+  override get message(): string {
+    return `reform: rendering slot '${this.slot}' requires @reform/react`
+  }
 }
+
 /** `provide(target, …)` was handed something that is neither a ui contract nor a slot. */
-export class InvalidProvideTarget extends Data.TaggedError('reform/InvalidProvideTarget') {
-    get message() {
-        return 'reform: provide target is neither a ui contract nor a slot';
-    }
+export class InvalidProvideTarget extends Data.TaggedError('reform/InvalidProvideTarget')<{}> {
+  override get message(): string {
+    return 'reform: provide target is neither a ui contract nor a slot'
+  }
 }
+
 /** `StateGroup.select(group, name)` named a state the group does not contain. */
-export class UnknownGroupState extends Data.TaggedError('reform/UnknownGroupState') {
-    get message() {
-        return `reform: unknown state '${this.name}' in group`;
-    }
+export class UnknownGroupState extends Data.TaggedError('reform/UnknownGroupState')<{
+  readonly name: string
+}> {
+  override get message(): string {
+    return `reform: unknown state '${this.name}' in group`
+  }
 }
+
 /**
  * A lazy `Feature`'s `load` Effect failed — the dynamic `import()` rejected (a
  * missing chunk, a network failure, a module-eval throw). Surfaced as a typed
  * failure the host hands to the feature's `placeholder.failed`, never a bare
  * rejection. `cause` is the original rejection value.
  */
-export class FeatureLoadFailed extends Data.TaggedError('reform/FeatureLoadFailed') {
-    get message() {
-        return `reform: a feature failed to load (${String(this.cause)})`;
-    }
+export class FeatureLoadFailed extends Data.TaggedError('reform/FeatureLoadFailed')<{
+  readonly cause: unknown
+}> {
+  override get message(): string {
+    return `reform: a feature failed to load (${String(this.cause)})`
+  }
 }
+
 /** A reducer fold returned a thenable — folds must be pure synchronous writes. */
-export class AsyncReducer extends Data.TaggedError('reform/AsyncReducer') {
-    get message() {
-        return 'reform: a reducer fold must be synchronous (it returned a Promise)';
-    }
+export class AsyncReducer extends Data.TaggedError('reform/AsyncReducer')<{}> {
+  override get message(): string {
+    return 'reform: a reducer fold must be synchronous (it returned a Promise)'
+  }
 }
+
 /**
  * Two distinct primitives were registered under one name into the same runtime —
  * a silent footgun, since names key DI tags and channel lanes. Thrown for a
  * channel name reused with a different policy (the second would otherwise be
  * dropped). Reducer/procedure name clashes are warned (logged), not thrown.
  */
-export class DuplicateRegistration extends Data.TaggedError('reform/DuplicateRegistration') {
-    get message() {
-        return `reform: duplicate ${this.kind} registered under name '${this.name}'`;
-    }
+export class DuplicateRegistration extends Data.TaggedError('reform/DuplicateRegistration')<{
+  readonly kind: string
+  readonly name: string
+}> {
+  override get message(): string {
+    return `reform: duplicate ${this.kind} registered under name '${this.name}'`
+  }
 }
-//# sourceMappingURL=errors.js.map

package/src/internal/inspect.ts

@@ -0,0 +1,34 @@
+import { format, type Inspectable, NodeInspectSymbol } from 'effect/Inspectable'
+
+export { type Inspectable, NodeInspectSymbol }
+
+/**
+ * The `Inspectable` trio built around a `toJSON`, so every reform value prints
+ * like an Effect value — `_id`-tagged JSON under `console.log`, Node's
+ * inspector, `JSON.stringify`, and `String(...)` — instead of `[object Object]`.
+ * Mirrors Effect's `BaseProto` / `Inspectable.Class` (`Inspectable.ts:170`).
+ */
+export const inspectable = (toJSON: () => unknown): Inspectable => ({
+  toJSON,
+  toString: () => format(toJSON()),
+  [NodeInspectSymbol]: () => toJSON(),
+})
+
+/**
+ * Attach the `Inspectable` trio to an existing object as *non-enumerable* own
+ * properties (so they don't show up in `Object.keys`/`for…in` over a definition
+ * class). Used where the value is built by other means — the definition classes,
+ * whose statics are merged in separately.
+ */
+export const attachInspectable = <T extends object>(target: T, toJSON: () => unknown): T => {
+  const trio = inspectable(toJSON) as unknown as Record<PropertyKey, unknown>
+  for (const key of Reflect.ownKeys(trio)) {
+    Object.defineProperty(target, key, {
+      value: trio[key],
+      enumerable: false,
+      writable: true,
+      configurable: true,
+    })
+  }
+  return target
+}

package/src/internal/queryDriver.ts

@@ -0,0 +1,247 @@
+import {
+  Brand,
+  Cause,
+  Chunk,
+  Effect,
+  MutableRef,
+  Option,
+  Queue,
+  Schema,
+  type Scope,
+  Stream,
+} from 'effect'
+import { type AnyAsyncData, AsyncData } from '../calc/asyncData'
+import { reuse } from './reuse'
+import { resolveScheduler } from './scheduler'
+import {
+  type InputsObject,
+  type InputStores,
+  type InvalidateBy,
+  sameKey,
+  wireSources,
+} from './sources'
+import { makeStore, type Store } from './store'
+import { type AnySource } from '../state/token'
+
+// The query-lifecycle driver shared by `AsyncCalc.live` and `RemoteState.live`:
+// sense the inputs, run the query latest-wins (or trailing-conflated), fold the
+// result into an `AnyAsyncData` store with stale-while-revalidate semantics.
+// Extracted so both primitives run the exact same machinery — the asyncCalc
+// test suite is the driver's regression suite.
+
+/** `Gated` (whether the `Idle` arm exists) is the inverse of `alwaysOn`. */
+export type GatedOf<AlwaysOn extends boolean> = AlwaysOn extends true ? false : true
+
+/** The runtime gated flag for an `alwaysOn` config, typed as its `Gated` literal. */
+export const gatedFlag = <AlwaysOn extends boolean>(alwaysOn: AlwaysOn | undefined): GatedOf<AlwaysOn> =>
+  (alwaysOn !== true) as GatedOf<AlwaysOn>
+
+// The hidden revision behind `invalidateOn` — a module-local *branded* number.
+// Reform store services are type-identified (`Context.GenericTag<Store<A>>`), so
+// the hidden state's value type must be un-collidable: `Layer.provide` erases
+// exactly `Store<Revision>` from the returned layer and can never type-level
+// erase a user input that happens to be a number state. Never exported from the
+// package index, so the editor catalog (which only indexes module exports)
+// never sees it.
+export type Revision = number & Brand.Brand<'reform/Revision'>
+export const Revision = Brand.nominal<Revision>()
+export const RevisionSchema: Schema.Schema<Revision, number> = Schema.Number.pipe(
+  Schema.brand('reform/Revision'),
+)
+export const revisionZero: Revision = Revision(0)
+export const bumpRevision = (r: Revision): Revision => Revision(r + 1)
+
+export interface QueryDriverOptions<Inputs extends ReadonlyArray<AnySource>, A, E, R> {
+  /** The owning definition's name — only for the defect log line. */
+  readonly name: string
+  /** The owning primitive's kind label — only for the defect log line. */
+  readonly label: string
+  /** Whether `disabled` is honored / the `Idle` arm can occur. */
+  readonly gated: boolean
+  readonly inputs: Inputs
+  readonly query: (inputs: InputsObject<Inputs>) => Effect.Effect<A, E, R>
+  readonly invalidateBy?: InvalidateBy<Inputs> | undefined
+  readonly disabled?: ((inputs: InputsObject<Inputs>) => boolean) | undefined
+  readonly coalesce?: 'switch' | 'trailing' | undefined
+  readonly reuse?: boolean | undefined
+  /**
+   * An extra key segment + wake source beyond the declared inputs — the hidden
+   * `invalidateOn` revision. Kept out of `wireSources` so the user's `query`
+   * and `invalidateBy` see exactly the declared inputs.
+   */
+  readonly extraKey?:
+    | {
+        readonly read: () => unknown
+        readonly subscribe: (listener: () => void) => () => void
+      }
+    | undefined
+  /**
+   * Fired when a run's `Success` value has landed in the store (same scheduler
+   * flush — never before the converged value is readable), with the run's
+   * generation. Not fired on `Error`, interrupt, or while disabled. The seam
+   * `RemoteState` settles pending intents through.
+   */
+  readonly onSettled?: ((generation: number) => void) | undefined
+}
+
+export interface QueryDriver<A, E> {
+  /** The lifecycle store (the full union — callers narrow to their arms). */
+  readonly store: Store<AnyAsyncData<A, E>>
+  /**
+   * The highest generation requested so far (0 before the first kick).
+   * Generations are assigned when a run is REQUESTED (enqueued), so a waiter
+   * registered as `requested() + 1` is satisfied only by a run that began
+   * after registration — the settle-ordering rule `RemoteState` builds on.
+   */
+  readonly requested: () => number
+}
+
+/**
+ * Build the driver: store + subscription + request queue + run fiber, all owned
+ * by the ambient scope (callers run this under `Layer.scoped`). A change to an
+ * input re-runs the query latest-wins (a new run cancels the in-flight one; or,
+ * with `coalesce: 'trailing'`, lets it finish and runs one trailing refetch);
+ * while a re-run is in flight the last `Success`/`Error` is kept with
+ * `refetching: true`.
+ */
+export const makeQueryDriver = <Inputs extends ReadonlyArray<AnySource>, A, E, R>(
+  options: QueryDriverOptions<Inputs, A, E, R>,
+): Effect.Effect<QueryDriver<A, E>, never, InputStores<Inputs> | R | Scope.Scope> =>
+  Effect.gen(function* () {
+    const scheduler = yield* resolveScheduler
+    const sources = yield* wireSources(options.inputs, options.invalidateBy)
+    const extraKey = options.extraKey
+
+    const keyOf = (args: InputsObject<Inputs>): ReadonlyArray<unknown> =>
+      extraKey === undefined ? sources.keyOf(args) : [...sources.keyOf(args), extraKey.read()]
+    const subscribeAll = (listener: () => void): (() => void) => {
+      const offSources = sources.subscribe(listener)
+      const offExtra = extraKey?.subscribe(listener)
+      return () => {
+        offSources()
+        offExtra?.()
+      }
+    }
+    const disabledNow = (args: InputsObject<Inputs> = sources.snapshot()): boolean =>
+      options.gated && options.disabled !== undefined ? options.disabled(args) : false
+
+    const store = makeStore<AnyAsyncData<A, E>>(
+      disabledNow() ? AsyncData.idle : AsyncData.loading,
+      scheduler,
+    )
+    // The last requested key, so a change that doesn't move it (or only churns
+    // an input `invalidateBy` ignores) doesn't re-fetch.
+    const lastKey = MutableRef.make<ReadonlyArray<unknown> | undefined>(undefined)
+    // The run-generation counter: bumped when a run is REQUESTED (enqueued), so
+    // `requested()` names the newest run that could possibly be in flight.
+    const generation = MutableRef.make(0)
+    const nextGeneration = (): number => {
+      MutableRef.update(generation, (n) => n + 1)
+      return MutableRef.get(generation)
+    }
+
+    // Mark a re-fetch in flight without dropping the visible value (SWR).
+    const markRefetching = () => {
+      const prev = store.get()
+      if (prev._tag === 'Success') store.set(AsyncData.success(prev.value, true))
+      else if (prev._tag === 'Error') store.set(AsyncData.error(prev.error, true))
+      else store.set(AsyncData.loading)
+    }
+
+    // One run of the query, folded into the store. A failure becomes `Error`; an
+    // interrupt (latest-wins cancel) leaves the state untouched; a defect (a bug
+    // in the body) is logged and isolated — the driver keeps running. A `Success`
+    // additionally reports its generation through `onSettled`, after the write,
+    // so settle-driven consequences observe the converged value.
+    const runQuery = (request: Request): Effect.Effect<void, never, R> =>
+      options.query(request.args).pipe(
+        Effect.tapDefect((defect) =>
+          Effect.logError(`reform: ${options.label} '${options.name}' query defect`, defect),
+        ),
+        Effect.matchCause({
+          onSuccess: (value) => {
+            if (!disabledNow()) {
+              // `reuse`: share unchanged subtrees with the previous Success
+              // value, so a refetch that barely moved keeps identities stable.
+              const prev = store.get()
+              const shared =
+                options.reuse === true && prev._tag === 'Success'
+                  ? reuse(prev.value, value)
+                  : value
+              store.set(AsyncData.success(shared, false))
+              options.onSettled?.(request.generation)
+            }
+          },
+          onFailure: (cause) => {
+            const failure = Cause.failureOption(cause)
+            if (Option.isSome(failure) && !disabledNow()) {
+              store.set(AsyncData.error(failure.value, false))
+            }
+          },
+        }),
+      )
+
+    interface Request {
+      readonly args: InputsObject<Inputs>
+      readonly generation: number
+    }
+
+    // The driver. `'switch'` (default): each new request cancels the in-flight
+    // run — the same latest-wins semantics a `latest` channel gives procedures.
+    // `'trailing'`: a strictly sequential consumer that, on wake, drains every
+    // request that piled up during the flight and runs the LATEST one —
+    // "exactly one trailing run after settle" by construction. The trailing
+    // run's generation is the max drained (the latest request's), so it
+    // vouches for every request it conflated.
+    const trailing = options.coalesce === 'trailing'
+    const requests = yield* Queue.unbounded<Request>()
+    yield* Effect.forkScoped(
+      trailing
+        ? Effect.forever(
+            Effect.gen(function* () {
+              const first = yield* Queue.take(requests)
+              const queued = yield* Queue.takeAll(requests)
+              const request = Option.getOrElse(Chunk.last(queued), () => first)
+              // A disable that landed while the request waited: skip the run.
+              if (!disabledNow()) yield* runQuery(request)
+              // The settle may have written a stale-key result with
+              // `refetching: false`; if a newer request is already waiting,
+              // restore the syncing flag before the next take — both writes
+              // coalesce into one scheduler flush for subscribers.
+              const pending = yield* Queue.size(requests)
+              if (pending > 0 && !disabledNow()) yield* Effect.sync(markRefetching)
+            }),
+          )
+        : Stream.fromQueue(requests).pipe(
+            Stream.flatMap((request) => Stream.fromEffect(runQuery(request)), { switch: true }),
+            Stream.runDrain,
+          ),
+    )
+
+    const trigger = () => {
+      const args = sources.snapshot()
+      if (disabledNow(args)) {
+        // Switched off: show Idle and forget the key so re-enabling always re-runs.
+        MutableRef.set(lastKey, undefined)
+        store.set(AsyncData.idle)
+        return
+      }
+      const key = keyOf(args)
+      const previous = MutableRef.get(lastKey)
+      if (previous !== undefined && sameKey(key, previous)) return
+      MutableRef.set(lastKey, key)
+      markRefetching()
+      Queue.unsafeOffer(requests, { args, generation: nextGeneration() })
+    }
+    const unsubscribe = subscribeAll(trigger)
+    yield* Effect.addFinalizer(() => Effect.sync(unsubscribe))
+
+    // Kick off the first fetch unless the query starts disabled.
+    const initial = sources.snapshot()
+    if (!disabledNow(initial)) {
+      MutableRef.set(lastKey, keyOf(initial))
+      Queue.unsafeOffer(requests, { args: initial, generation: nextGeneration() })
+    }
+
+    return { store, requested: () => MutableRef.get(generation) }
+  })

package/src/internal/reuse.ts

@@ -0,0 +1,73 @@
+import { Equal } from 'effect'
+
+// Structural sharing for recomputed calc outputs: reconcile a fresh output
+// against the previous one, substituting previous nodes wherever value equality
+// holds, so identities only move where values moved. Downstream memo boundaries
+// (React subtrees keyed on object identity) then skip everything that didn't
+// change. Referentially transparent: the result is value-equal to `next` — only
+// identities shift toward `previous` — and neither argument is mutated, so the
+// pass composes with the framework's Equal-based invalidation untouched.
+
+// Bounds the walk; calc outputs are shallow plain data by framework convention.
+const maxDepth = 16
+
+const isPlainRecord = (v: unknown): v is Record<string, unknown> =>
+  typeof v === 'object' &&
+  v !== null &&
+  (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null)
+
+const go = (prev: unknown, next: unknown, depth: number): unknown => {
+  if (Object.is(prev, next)) return prev
+  // Data/Schema classes implement Equal+Hash: substitute wholesale on value
+  // equality. Plain objects/arrays fall through (their Equal is referential).
+  if (Equal.equals(prev, next)) return prev
+  if (depth <= 0) return next
+  if (Array.isArray(prev) && Array.isArray(next)) {
+    const out = next.map((item, i) => (i < prev.length ? go(prev[i], item, depth - 1) : item))
+    return prev.length === next.length && out.every((v, i) => Object.is(v, prev[i]))
+      ? prev
+      : out
+  }
+  if (isPlainRecord(prev) && isPlainRecord(next)) {
+    const keys = Object.keys(next)
+    const out: Record<string, unknown> = {}
+    for (const key of keys) out[key] = key in prev ? go(prev[key], next[key], depth - 1) : next[key]
+    const allPrev =
+      keys.length === Object.keys(prev).length &&
+      keys.every((key) => key in prev && Object.is(out[key], prev[key]))
+    return allPrev ? prev : out
+  }
+  // Data/Schema class instances that DIFFER still get walked: their Equal is
+  // fieldwise over own enumerable fields, so a reconstruction over reconciled
+  // fields (same prototype; the constructor is bypassed, but every leaf is a
+  // validated value out of `prev` or `next`) stays value-equal to `next` while
+  // unchanged children — e.g. one untouched element inside a class-typed
+  // container — keep their `prev` identity.
+  if (
+    Equal.isEqual(prev) &&
+    Equal.isEqual(next) &&
+    Object.getPrototypeOf(prev) === Object.getPrototypeOf(next)
+  ) {
+    const prevFields = Object.fromEntries(Object.entries(prev))
+    const nextFields = Object.entries(next)
+    const out: Record<string, unknown> = {}
+    for (const [key, value] of nextFields)
+      out[key] = key in prevFields ? go(prevFields[key], value, depth - 1) : value
+    const allPrev =
+      nextFields.length === Object.keys(prevFields).length &&
+      nextFields.every(([key]) => key in prevFields && Object.is(out[key], prevFields[key]))
+    return allPrev ? prev : Object.assign(Object.create(Object.getPrototypeOf(next)), out)
+  }
+  // Class instances without Equal (Date, Map, …) are opaque leaves.
+  return next
+}
+
+/**
+ * Substitute `previous` nodes into `next` wherever they are value-equal. The
+ * walker only ever returns `previous`, `next`, or a key/index-wise
+ * reconstruction of `next` whose every leaf came from one of them, so the
+ * result is value-equal to `next` and the type is preserved by construction —
+ * the single cast below is that argument, in the style of `wireSources` /
+ * `narrowStore`.
+ */
+export const reuse = <A>(previous: A, next: A): A => go(previous, next, maxDepth) as A

package/src/internal/scheduler.ts

@@ -0,0 +1,91 @@
+import { Context, Effect, Layer, MutableRef, Option } from 'effect'
+
+/**
+ * Coalesces store notifications into a single microtask flush so a batch of
+ * writes wakes each subscriber at most once (RESEARCH #3). React owns frame
+ * timing; we only collapse the notifications.
+ *
+ * One scheduler is shared by every store in a runtime, so writes across
+ * different stores in the same tick batch into one flush. The instance is
+ * resolved per store at creation: `Notifications` when a runtime provides it
+ * (per-runtime isolation — see `resolveScheduler`), else the process-wide
+ * `defaultScheduler`.
+ */
+export interface Scheduler {
+  readonly schedule: (listeners: Iterable<() => void>) => void
+}
+
+export const makeScheduler = (): Scheduler => {
+  const pending = new Set<() => void>()
+  const armed = MutableRef.make(false)
+
+  const flush = () => {
+    MutableRef.set(armed, false)
+    // Drain to a fixpoint within ONE microtask. A derived store's `onChange`
+    // re-schedules during the pass (it is itself a listener of its upstream), so
+    // resolving the whole dependency graph here — instead of re-arming a fresh
+    // microtask per layer — collapses a depth-N propagation into a single flush
+    // and wakes each leaf subscriber once at its final value. Converges because
+    // a derived store schedules only when its output actually moves (Equal).
+    while (pending.size > 0) {
+      const due = [...pending]
+      pending.clear()
+      for (const listener of due) {
+        // One listener's throw (a defect in a user calc body) must not abandon
+        // the rest of the flush; surface it to the host's global handler on a
+        // fresh microtask instead of unwinding this loop.
+        try {
+          listener()
+        } catch (error) {
+          queueMicrotask(() => {
+            throw error
+          })
+        }
+      }
+    }
+  }
+
+  const schedule = (listeners: Iterable<() => void>) => {
+    for (const listener of listeners) pending.add(listener)
+    if (pending.size > 0 && !MutableRef.get(armed)) {
+      MutableRef.set(armed, true)
+      queueMicrotask(flush)
+    }
+  }
+
+  return { schedule }
+}
+
+/**
+ * The process-wide scheduler, used by any store created outside a runtime that
+ * provides its own `Notifications`. Fine for a single client app (microtask
+ * ordering is global anyway); a runtime that needs isolation — concurrent SSR,
+ * multiple mounted roots — provides `Notifications` upstream of its stores.
+ */
+export const defaultScheduler: Scheduler = makeScheduler()
+
+/**
+ * Optional per-runtime scheduler. When a runtime provides it upstream of its
+ * state/calc layers, those stores coalesce on it instead of the global default,
+ * isolating their notification timing from other runtimes in the same process.
+ */
+export class Notifications extends Context.Tag('reform/Notifications')<Notifications, Scheduler>() {}
+
+/**
+ * A fresh per-runtime scheduler. Merged into `Engine`, so a runtime that wires
+ * its state/calc layers *downstream* of `Engine` gets isolated notification
+ * timing; the common sibling wiring falls back to `defaultScheduler` (still
+ * correct, just process-shared).
+ */
+export const notificationsLayer: Layer.Layer<Notifications> = Layer.sync(Notifications, makeScheduler)
+
+/**
+ * Resolve the scheduler a store should use: the runtime's `Notifications` if one
+ * is in context, else the global default. Uses `serviceOption` so it imposes no
+ * hard requirement — a store layer wired as a sibling of the runtime (the common
+ * pattern) simply falls back to the default.
+ */
+export const resolveScheduler: Effect.Effect<Scheduler> = Effect.map(
+  Effect.serviceOption(Notifications),
+  Option.getOrElse(() => defaultScheduler),
+)

package/{dist/dts/internal/seeds.d.ts → src/internal/seeds.ts}

@@ -1,4 +1,5 @@
-import { FiberRef } from 'effect';
+import { FiberRef, GlobalValue } from 'effect'
+
 /**
  * The sanctioned tooling/test seam for seeding CLOSED scenes. A scene's layers
  * are pre-composed (each state group seeds its own live store), so an outer
@@ -13,5 +14,7 @@ import { FiberRef } from 'effect';
  * keeps a single ref instance even if the module is loaded twice (duplicated
  * bundles, HMR), so the writer and the reader always agree.
  */
-export declare const CurrentSeedOverrides: FiberRef.FiberRef<Readonly<Record<string, unknown>>>;
-//# sourceMappingURL=seeds.d.ts.map
+export const CurrentSeedOverrides: FiberRef.FiberRef<Readonly<Record<string, unknown>>> =
+  GlobalValue.globalValue(Symbol.for('reform/CurrentSeedOverrides'), () =>
+    FiberRef.unsafeMake<Readonly<Record<string, unknown>>>({}),
+  )

package/src/internal/sources.ts

@@ -0,0 +1,104 @@
+import { type Context, Effect, Equal, Predicate } from 'effect'
+import { type AnySource, type SourceName, type SourceValue } from '../state/token'
+import { type Store } from './store'
+
+// The reactive plumbing shared by `Calc` and `AsyncCalc`: read a list of input
+// `Source`s, snapshot them by name, project a comparable invalidation key, and
+// subscribe to changes. Both derived primitives sense their inputs the same way
+// and differ only in what they do with a change (recompute vs. re-run a query).
+
+/** The decoded inputs handed to a calc body, keyed by each source's name. */
+export type InputsObject<Inputs extends ReadonlyArray<AnySource>> = {
+  readonly [S in Inputs[number] as SourceName<S>]: SourceValue<S>
+}
+
+/**
+ * The store services a list of store-carriers requires, as a *union of distinct*
+ * stores (each carrier has its own backing tag), not a single store of a union.
+ * Structural over the `store` tag, so it serves both calc inputs (`Source`s) and
+ * state-group members (`StateClass`es) — anything carrying a `store` tag.
+ */
+export type StoresOf<Items extends ReadonlyArray<unknown>> = {
+  [I in keyof Items]: Items[I] extends { readonly store: Context.Tag<infer Svc, any> } ? Svc : never
+}[number]
+
+/** The store requirement a calc's inputs impose. */
+export type InputStores<Inputs extends ReadonlyArray<AnySource>> = StoresOf<Inputs>
+
+/** Project inputs into a comparable key; the calc reacts only when it moves. */
+export type InvalidateBy<Inputs extends ReadonlyArray<AnySource>> = (
+  inputs: InputsObject<Inputs>,
+) => ReadonlyArray<unknown>
+
+/**
+ * The runtime key an input contributes to the inputs object. Prefer the
+ * explicit `manifest.name` — the string handed to `make` — over the structural
+ * `name`: a `Calc`/`AsyncCalc` *class* satisfies `Source` through its static
+ * `name`, and a user subclass declaration (`class Feed extends Calc.make(…)`)
+ * defines its OWN `name` from the class binding, shadowing the explicit one.
+ * That binding is what minifiers rename, so keying the snapshot by `input.name`
+ * made every subclassed calc input `undefined` in production builds (and would
+ * silently mis-key in dev whenever the binding differs from the `make` name —
+ * the type-level key, `SourceName<S>`, is always the `make` string). The
+ * manifest is inherited through the static prototype chain and never shadowed.
+ * `StateToken`s carry no manifest; their `name` is an instance field holding
+ * the explicit member key, so the fallback is always the declared string.
+ */
+const inputKey = (input: AnySource): string =>
+  Predicate.hasProperty(input, 'manifest') &&
+  Predicate.isRecord(input.manifest) &&
+  Predicate.isString(input.manifest.name)
+    ? input.manifest.name
+    : input.name
+
+/** Element-wise value equality of two invalidation keys. */
+export const sameKey = (a: ReadonlyArray<unknown>, b: ReadonlyArray<unknown>): boolean =>
+  a.length === b.length && a.every((value, i) => Equal.equals(value, b[i]))
+
+/** The sensing surface both `Calc.live` and `AsyncCalc.live` build on. */
+export interface WiredSources<Inputs extends ReadonlyArray<AnySource>> {
+  /** Snapshot every input by name — the decoded inputs object a calc body sees. */
+  readonly snapshot: () => InputsObject<Inputs>
+  /** The invalidation key for an inputs object: the projection, or all input values. */
+  readonly keyOf: (inputs: InputsObject<Inputs>) => ReadonlyArray<unknown>
+  /** Subscribe to every source at once; the returned thunk unsubscribes from all. */
+  readonly subscribe: (listener: () => void) => () => void
+}
+
+/**
+ * Read each input's backing store and return the shared sensing surface. The
+ * caller owns lifecycle: register the `subscribe` result's unsubscribe as a
+ * scope finalizer (both live bodies run under `Layer.scoped`).
+ */
+export const wireSources = <Inputs extends ReadonlyArray<AnySource>>(
+  inputs: Inputs,
+  invalidateBy?: InvalidateBy<Inputs>,
+): Effect.Effect<WiredSources<Inputs>, never, InputStores<Inputs>> =>
+  Effect.gen(function* () {
+    const sources: Array<Store<unknown>> = []
+    for (const input of inputs) sources.push(yield* input.store)
+
+    const snapshot = (): InputsObject<Inputs> => {
+      const args: Record<string, unknown> = {}
+      inputs.forEach((input, i) => {
+        // `noUncheckedIndexedAccess`: `sources` is built 1:1 with `inputs`, but
+        // guard the index so the read is honestly total.
+        const source = sources[i]
+        if (source !== undefined) args[inputKey(input)] = source.getSnapshot()
+      })
+      return args as InputsObject<Inputs>
+    }
+    const keyOf = (args: InputsObject<Inputs>): ReadonlyArray<unknown> =>
+      invalidateBy ? invalidateBy(args) : Object.values(args)
+    const subscribe = (listener: () => void): (() => void) => {
+      const unsubscribes = sources.map((source) => source.subscribe(listener))
+      return () => {
+        for (const unsubscribe of unsubscribes) unsubscribe()
+      }
+    }
+    return { snapshot, keyOf, subscribe }
+    // Yielding each `input.store` (a `Context.Tag<Store<unknown>>`) widens the
+    // inferred requirement to `Store<unknown>`; restate the precise per-input
+    // `InputStores<Inputs>` union the signature promises. This is the single
+    // place that cast lives — `Calc.live`/`AsyncCalc.live` inherit it.
+  }) as Effect.Effect<WiredSources<Inputs>, never, InputStores<Inputs>>