@playfast/reform 0.0.2 → 0.0.4

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.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.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,
+  )
+}

package/src/channel/channel.ts

@@ -0,0 +1,265 @@
+import { Chunk, Context, type Duration, Effect, Layer, Match, Queue, Stream } from 'effect'
+import { type Manifest, definitionClass } from '../definition/definition'
+import { DuplicateRegistration } from '../internal/errors'
+import type { Tagged } from '../runtime/bus'
+
+/**
+ * How a channel schedules the procedure work routed to it. Channels generalize
+ * the old per-procedure `concurrency`: a named lane with one policy, shared by
+ * every procedure that declares it.
+ *
+ * - `merge`     run every routed event concurrently (the default).
+ * - `latest`    a new event cancels the in-flight run (switch).
+ * - `debounce`  collapse a burst, run only after `duration` of quiet.
+ * - `throttle`  rate-limit to `units` per `duration` (shape or enforce).
+ * - `exclusive` one run at a time across the whole channel (mutual exclusion).
+ */
+export type ChannelPolicy =
+  | { readonly _tag: 'merge' }
+  | { readonly _tag: 'latest' }
+  | { readonly _tag: 'debounce'; readonly duration: Duration.DurationInput }
+  | {
+      readonly _tag: 'throttle'
+      readonly units: number
+      readonly duration: Duration.DurationInput
+      readonly cost?: number
+      readonly burst?: number
+      readonly strategy?: 'enforce' | 'shape'
+    }
+  | { readonly _tag: 'exclusive' }
+
+/** The reflectable descriptor a channel carries. */
+export interface ChannelManifest extends Manifest {
+  readonly kind: 'Channel'
+}
+
+export interface ChannelClass {
+  new (): {}
+  readonly manifest: ChannelManifest
+  readonly policy: ChannelPolicy
+}
+
+export interface ChannelConfig {
+  readonly policy: ChannelPolicy
+}
+
+/**
+ * A registered procedure body, with its trigger events and the channel it runs
+ * on. `run`'s context (RPC clients, etc.) is already provided at registration
+ * (see `Procedure.live`), so the channel fiber can run it with no R.
+ */
+export interface ProcedureEntry {
+  /** The procedure's name — used only to warn on duplicate registration. */
+  readonly name: string
+  readonly channelName: string
+  readonly handles: ReadonlySet<string>
+  readonly run: (event: Tagged) => Effect.Effect<unknown, unknown, never>
+}
+
+/**
+ * Mutable collector procedures register into; channels read it to find their
+ * bodies. `byTag` indexes entries by trigger tag, so a channel routes an event
+ * to O(procedures handling it) rather than scanning every registered procedure.
+ */
+export interface ProcedureRegistry {
+  readonly entries: Array<ProcedureEntry>
+  readonly byTag: Map<string, Array<ProcedureEntry>>
+  /**
+   * Distinct channel names per event tag. The drain loop routes through this so
+   * it offers each event to each channel exactly once — not once per matching
+   * procedure, which would re-run every procedure on a shared channel per offer.
+   */
+  readonly channelsByTag: Map<string, Array<string>>
+  /**
+   * Procedures keyed by (channel, tag), so a channel's `runMatching` is a direct
+   * lookup instead of scanning `byTag` and re-filtering by channel per event.
+   */
+  readonly byChannelTag: Map<string, Map<string, Array<ProcedureEntry>>>
+  readonly register: (entry: ProcedureEntry) => void
+  /**
+   * Remove a previously-registered entry — the inverse of `register`, used when a
+   * lazy feature unmounts (scope close) so its procedures stop running and their
+   * index entries are reclaimed. Eager procedures (root scope) never call it.
+   */
+  readonly unregister: (entry: ProcedureEntry) => void
+}
+
+export class Procedures extends Context.Tag('reform/Procedures')<Procedures, ProcedureRegistry>() {}
+
+/** Get a map entry, creating and inserting it on first access (avoids `let`). */
+const getOrCreate = <K, V>(map: Map<K, V>, key: K, make: () => V): V => {
+  const existing = map.get(key)
+  if (existing !== undefined) return existing
+  const created = make()
+  map.set(key, created)
+  return created
+}
+
+/** Drop an item from a `Map<K, Array>` bucket, pruning the key when it empties. */
+const dropFrom = <K, T>(map: Map<K, Array<T>>, key: K, item: T): void => {
+  const bucket = map.get(key)
+  if (bucket === undefined) return
+  const next = bucket.filter((value) => value !== item)
+  if (next.length === 0) map.delete(key)
+  else map.set(key, next)
+}
+
+const makeProcedureRegistry = (): ProcedureRegistry => {
+  const entries: Array<ProcedureEntry> = []
+  const byTag = new Map<string, Array<ProcedureEntry>>()
+  const channelsByTag = new Map<string, Array<string>>()
+  const byChannelTag = new Map<string, Map<string, Array<ProcedureEntry>>>()
+  return {
+    entries,
+    byTag,
+    channelsByTag,
+    byChannelTag,
+    register: (entry) => {
+      entries.push(entry)
+      for (const tag of entry.handles) {
+        getOrCreate(byTag, tag, () => []).push(entry)
+        const channels = getOrCreate(channelsByTag, tag, () => [])
+        if (!channels.includes(entry.channelName)) channels.push(entry.channelName)
+        getOrCreate(getOrCreate(byChannelTag, entry.channelName, () => new Map()), tag, () => []).push(
+          entry,
+        )
+      }
+    },
+    unregister: (entry) => {
+      const index = entries.indexOf(entry)
+      if (index >= 0) entries.splice(index, 1)
+      for (const tag of entry.handles) {
+        dropFrom(byTag, tag, entry)
+        const channelMap = byChannelTag.get(entry.channelName)
+        if (channelMap !== undefined) {
+          dropFrom(channelMap, tag, entry)
+          // If no procedure on this channel still handles the tag, drop the
+          // channel from `channelsByTag[tag]` so the loop stops offering to it.
+          if (channelMap.get(tag) === undefined) dropFrom(channelsByTag, tag, entry.channelName)
+          if (channelMap.size === 0) byChannelTag.delete(entry.channelName)
+        }
+      }
+    },
+  }
+}
+
+export const proceduresLayer = Layer.sync(Procedures, makeProcedureRegistry)
+
+/** A live channel: the single loop offers events here; the channel drives them. */
+export interface ChannelRuntime {
+  readonly name: string
+  /** The policy this channel was built with — used to reject a name clash. */
+  readonly policy: ChannelPolicy
+  readonly offer: (event: Tagged) => void
+}
+
+/** Registry of live channels, keyed by name. The single loop routes through it. */
+export class Channels extends Context.Tag('reform/Channels')<
+  Channels,
+  { readonly byName: Map<string, ChannelRuntime> }
+>() {}
+
+export const channelsLayer = Layer.sync(Channels, () => ({ byName: new Map() }))
+
+/**
+ * A scheduling lane for procedures. The *definition* (`Channel.make`) is a
+ * reflectable name + policy; the *implementation* (`Channel.live`) builds the
+ * queue + fiber that applies the policy. Procedures reference a channel by value
+ * and register into it; `Channel.live` is merged into the app once per channel.
+ */
+export const make = (name: string, config: ChannelConfig): ChannelClass =>
+  definitionClass<ChannelClass>({
+    manifest: { kind: 'Channel' as const, name } satisfies ChannelManifest,
+    policy: config.policy,
+  })
+
+/**
+ * Build and register the live machinery for a channel. Idempotent by name, so
+ * procedures sharing an `exclusive`/`latest` channel share one queue + fiber +
+ * semaphore (and therefore truly serialize / cancel across each other).
+ */
+export const live = (channel: ChannelClass): Layer.Layer<never, never, Channels | Procedures> =>
+  Layer.scopedDiscard(
+    Effect.gen(function* () {
+      const name = channel.manifest.name
+      const channels = yield* Channels
+      const existing = channels.byName.get(name)
+      if (existing !== undefined) {
+        // Idempotent for the *same* channel `.live`'d through several sub-layers
+        // (shared `exclusive`/`latest` lane). A *different* channel reusing the
+        // name is a silent footgun — the second policy would be dropped — so
+        // reject it loudly instead.
+        if (existing.policy !== channel.policy) {
+          throw new DuplicateRegistration({ kind: 'Channel', name })
+        }
+        return
+      }
+      const procedures = yield* Procedures
+      const queue = yield* Queue.unbounded<Tagged>()
+
+      // Run every procedure on THIS channel that handles the event. Read the live
+      // index each time so procedures registered later are still seen.
+      // A procedure is expected to model expected failures as events; a leaked
+      // defect (a bug in the body) is logged before being isolated, so one
+      // procedure's crash never tears down the channel fiber — but is observable.
+      const runMatching = (event: Tagged): Effect.Effect<void> =>
+        Effect.forEach(
+          procedures.byChannelTag.get(name)?.get(event._tag) ?? [],
+          (e) =>
+            e.run(event).pipe(
+              Effect.tapErrorCause((cause) =>
+                Effect.logError(`reform: procedure on channel '${name}' failed`, cause),
+              ),
+              Effect.catchAllCause(() => Effect.void),
+            ),
+          { discard: true, concurrency: 'unbounded' },
+        )
+
+      // Map the policy to its scheduling stream. `Match.exhaustive` makes a new
+      // policy variant a compile error, and each arm is a self-contained const.
+      const events = Stream.fromQueue(queue)
+      const driven: Stream.Stream<unknown> = Match.value(channel.policy).pipe(
+        Match.tag('merge', () => Stream.mapEffect(events, runMatching, { concurrency: 'unbounded' })),
+        Match.tag('latest', () =>
+          Stream.flatMap(events, (e) => Stream.fromEffect(runMatching(e)), { switch: true }),
+        ),
+        Match.tag('debounce', (policy) =>
+          events.pipe(
+            Stream.debounce(policy.duration),
+            Stream.mapEffect(runMatching, { concurrency: 'unbounded' }),
+          ),
+        ),
+        Match.tag('throttle', (policy) =>
+          events.pipe(
+            Stream.throttle({
+              cost: (chunk) => Chunk.size(chunk) * (policy.cost ?? 1),
+              units: policy.units,
+              duration: policy.duration,
+              ...(policy.burst !== undefined ? { burst: policy.burst } : {}),
+              strategy: policy.strategy ?? 'shape',
+            }),
+            Stream.mapEffect(runMatching, { concurrency: 'unbounded' }),
+          ),
+        ),
+        // `concurrency: 1` runs one event at a time AND in offer order — a true
+        // serialized lane. (An unbounded fork racing for a single semaphore permit
+        // would serialize but could reorder under contention.)
+        Match.tag('exclusive', () => Stream.mapEffect(events, runMatching, { concurrency: 1 })),
+        Match.exhaustive,
+      )
+
+      yield* Effect.forkScoped(Stream.runDrain(driven))
+      channels.byName.set(name, {
+        name,
+        policy: channel.policy,
+        offer: (event) => {
+          Queue.unsafeOffer(queue, event)
+        },
+      })
+      // On scope close (a lazy feature unmounting) remove the live channel so the
+      // loop stops routing to it; the drain fiber is already torn down by
+      // `forkScoped`. Eager channels live on the root scope, so this is a no-op
+      // until app dispose.
+      yield* Effect.addFinalizer(() => Effect.sync(() => channels.byName.delete(name)))
+    }),
+  )