@playfast/reform 0.0.2 → 0.0.3

package/src/remote/remoteState.ts

@@ -0,0 +1,571 @@
+import { Context, Effect, Either, Layer, MutableRef, Option, Runtime, Schema } from 'effect'
+import { type AnyAsyncData, AsyncData, narrowStore, widenStore } from '../calc/asyncData'
+import * as Channel from '../channel/channel'
+import { type Manifest, yieldableClass } from '../definition/definition'
+import * as Event from '../event/event'
+import {
+  bumpRevision,
+  type GatedOf,
+  gatedFlag,
+  makeQueryDriver,
+  RevisionSchema,
+  revisionZero,
+} from '../internal/queryDriver'
+import { reuse as shareStructure } from '../internal/reuse'
+import { resolveScheduler } from '../internal/scheduler'
+import {
+  type InputsObject,
+  type InputStores,
+  type InvalidateBy,
+  sameKey,
+} from '../internal/sources'
+import { makeDerivedStore, makeStore, type Store } from '../internal/store'
+import { readTracked } from '../internal/track'
+import * as Reducer from '../reducer/reducer'
+import { Bus, narrowHandled, publish } from '../runtime/bus'
+import { type ReducerEntry, Reducers } from '../runtime/loop'
+import * as State from '../state/state'
+import { type AnySource, StateToken } from '../state/token'
+
+// `RemoteState` is server-owned state with optimistic mutations, as ONE
+// primitive. The model: remote state is *derived only* — the visible value is
+// `pending.reduce(apply, serverTruth)`, where `serverTruth` is a query's
+// lifecycle (the AsyncCalc machinery) and `pending` is the queue of intents
+// dispatched but not yet reflected by the server. The only write surface is
+// dispatching an intent event; there is no rollback machinery — a failed or
+// settled intent simply leaves the queue and the derivation converges.
+//
+// Lifecycle of one intent (dispatch → visible → durable):
+//   1. Dispatched like any event; the send procedure mints an `opId` and the
+//      hidden queue reducer appends `{opId, intent, status: 'sending'}` — the
+//      overlay shows the change in the same flush (no fetch fired yet).
+//   2. `send(intent)` runs on the channel. Failure (or a defect, or a cancel
+//      by a `latest`/`exclusive` channel): the intent settles immediately and
+//      the public `Failed` event carries `{intent, error}` — the overlay
+//      reverts by construction.
+//   3. Success: status flips to `'confirmed'` and the query is invalidated.
+//   4. THE GENERATION RULE: an intent acked while query-run generation g was
+//      the newest requested may be settled only by a run with generation > g
+//      that lands `Success`. A refetch that started before the ack can never
+//      settle it (it may predate the server applying the mutation), and an
+//      `Error` run settles nobody — so the optimistic change never visibly
+//      vanishes and reappears while the server converges.
+//   5. The settle lands in the same scheduler flush as the converged value:
+//      the overlay swaps optimistic-over-stale for server truth atomically
+//      from a subscriber's point of view.
+//
+// Queue order = dispatch order = apply order. While the query is disabled the
+// view is `Idle` but intents still queue and send; settles wait for the run
+// after re-enable. `apply` must be IDEMPOTENT against server truth that
+// already carries the intent: between the refetch landing and the settle
+// folding (adjacent flushes) the intent is applied over a value that already
+// contains it — `apply` seeing its own effect must be a no-op (e.g. skip an
+// insert whose id is already present). Everything is scoped: registry entries
+// unregister and the driver fiber/subscriptions/channel release with the
+// layer's scope.
+
+/** One queued intent: the dispatched event value plus the lifecycle metadata. */
+export interface PendingIntent<I> {
+  readonly opId: string
+  /** The dispatched intent event (`{ _tag, ...payload }`). */
+  readonly intent: I
+  /** `'sending'` until the RPC acks; `'confirmed'` until the post-ack refetch lands. */
+  readonly status: 'sending' | 'confirmed'
+}
+
+/** The payload of the public `Failed` event: which intent, and what `send` raised. */
+export interface FailedIntent<I> {
+  readonly intent: I
+  readonly error: unknown
+}
+
+export interface RemoteStateManifest<N extends string, A, E> extends Manifest {
+  readonly kind: 'RemoteState'
+  readonly name: N
+  /** Schema of the server value (`Success` arm / `apply`'s domain). */
+  readonly output: Schema.Schema<A, any>
+  readonly error?: Schema.Schema<E, any>
+  /** Whether the query can be disabled (drives the `Idle` arm). */
+  readonly gated: boolean
+  /** The mutation vocabulary — intent event tags, reflectable without running logic. */
+  readonly intents: ReadonlyArray<string>
+}
+
+export interface RemoteStateClass<
+  out N extends string,
+  out Inputs extends ReadonlyArray<AnySource>,
+  in out Intents extends ReadonlyArray<Event.AnyEvent>,
+  in out A,
+  in out E,
+  in out Gated extends boolean,
+> extends Effect.Effect<AsyncData<A, E, Gated>, never, Store<AsyncData<A, E, Gated>>> {
+  new (): {}
+  readonly manifest: RemoteStateManifest<N, A, E>
+  /** The OVERLAID view (`pending.reduce(apply, truth)`) — what `yield*` reads. */
+  readonly store: Context.Tag<Store<AsyncData<A, E, Gated>>, Store<AsyncData<A, E, Gated>>>
+  /** The name, so the class doubles as a `Source` input to another calc. */
+  readonly name: N
+  /** Marker data read by `RemoteState.live`. */
+  readonly inputs: Inputs
+  /** The intent event definitions (marker data; read by `RemoteState.live`). */
+  readonly intents: Intents
+  /** Runtime mirror of `Gated`: whether `disabled` is honored / `Idle` can occur. */
+  readonly gated: Gated
+  /** The un-overlaid query lifecycle — for chrome that must show server truth. */
+  readonly truth: StateToken<`${N}/truth`, AsyncData<A, E, Gated>>
+  /**
+   * The pending queue as a read-only `Source` (badges, "saving…" chrome). Not a
+   * `StateClass`, so no user reducer can target it — the hidden queue reducer
+   * is its sole writer.
+   */
+  readonly pending: StateToken<
+    `${N}/pending`,
+    ReadonlyArray<PendingIntent<Event.EventType<Intents[number]>>>
+  >
+  /** Public fact: a send failed; its intent left the queue and the view reverted. */
+  readonly Failed: Event.EventClass<`${N}/Failed`, FailedIntent<Event.EventType<Intents[number]>>>
+}
+
+export interface RemoteStateConfig<
+  Inputs extends ReadonlyArray<AnySource>,
+  Intents extends ReadonlyArray<Event.AnyEvent>,
+  A,
+  E,
+  AlwaysOn extends boolean,
+> {
+  readonly inputs: Inputs
+  /** Schema of the server value. */
+  readonly output: Schema.Schema<A, any>
+  /** Schema of the query failure. Omitted ⇒ infallible query, no `Error` arm. */
+  readonly error?: Schema.Schema<E, any>
+  /** `true` ⇒ the query is always on: no `Idle` arm and `disabled` is rejected on `.live`. */
+  readonly alwaysOn?: AlwaysOn
+  /** The mutation vocabulary: ordinary `Event.make` definitions. */
+  readonly intents: Intents
+}
+
+// Intent payloads are typed by the definition's `Intents`, but `Intents` is an
+// open type parameter inside `make`/`live`, so the runtime schemas can only be
+// structural (`Schema.Unknown` in the intent slot). Event schemas are
+// reflective metadata — never decoded on the dispatch path — so the typed view
+// is granted here once (the `narrowStore`/`narrowHandled` style; `any`
+// short-circuits the schema's invariance, no value is cast).
+const looseSchema = <P>(schema: Schema.Schema<any, any>): Schema.Schema<P, any> => schema
+
+/**
+ * Define a remote state: a query (like `AsyncCalc.make`) plus the intent
+ * events that mutate it. `yield* TheClass` reads the overlaid view;
+ * `TheClass.truth` / `TheClass.pending` / `TheClass.Failed` expose the rest of
+ * the surface. The query/send/apply logic is supplied by `RemoteState.live`.
+ */
+export const make = <
+  const N extends string,
+  const Inputs extends ReadonlyArray<AnySource>,
+  const Intents extends ReadonlyArray<Event.AnyEvent>,
+  A,
+  E = never,
+  const AlwaysOn extends boolean = false,
+>(
+  name: N,
+  config: RemoteStateConfig<Inputs, Intents, A, E, AlwaysOn>,
+): RemoteStateClass<N, Inputs, Intents, A, E, GatedOf<AlwaysOn>> => {
+  type I = Event.EventType<Intents[number]>
+  const store = Context.GenericTag<Store<AsyncData<A, E, GatedOf<AlwaysOn>>>>(
+    `reform/remoteState/${name}`,
+  )
+  const truthTag = Context.GenericTag<Store<AsyncData<A, E, GatedOf<AlwaysOn>>>>(
+    `reform/remoteState/${name}/truth`,
+  )
+  const pendingTag = Context.GenericTag<Store<ReadonlyArray<PendingIntent<I>>>>(
+    `reform/remoteState/${name}/pending`,
+  )
+  const gated = gatedFlag(config.alwaysOn)
+  const manifest: RemoteStateManifest<N, A, E> = {
+    kind: 'RemoteState',
+    name,
+    output: config.output,
+    gated,
+    intents: config.intents.map((event) => event.tag),
+    ...(config.error !== undefined ? { error: config.error } : {}),
+  }
+  // Annotated consts so the template literal expressions keep their literal
+  // types (contextual typing) — the statics must match the interface exactly.
+  const truthName: `${N}/truth` = `${name}/truth`
+  const pendingName: `${N}/pending` = `${name}/pending`
+  const failedName: `${N}/Failed` = `${name}/Failed`
+  const read = Effect.flatMap(store, readTracked)
+  return yieldableClass(read, {
+    manifest,
+    store,
+    name,
+    inputs: config.inputs,
+    intents: config.intents,
+    gated,
+    truth: new StateToken(truthName, truthTag),
+    pending: new StateToken(pendingName, pendingTag),
+    Failed: Event.make(
+      failedName,
+      looseSchema<FailedIntent<I>>(
+        Schema.Struct({ intent: Schema.Unknown, error: Schema.Unknown }),
+      ),
+    ),
+  })
+}
+
+/**
+ * The `.live` config: the query (same contract as `AsyncCalc.live`), the
+ * delivery effect, and the pure per-intent fold.
+ */
+export type RemoteStateLive<
+  Inputs extends ReadonlyArray<AnySource>,
+  Intents extends ReadonlyArray<Event.AnyEvent>,
+  A,
+  E,
+  Gated extends boolean,
+  R,
+  R2,
+> = {
+  readonly query: (inputs: InputsObject<Inputs>) => Effect.Effect<A, E, R>
+  /**
+   * Deliver one intent to the server. ANY failure (typed failure or defect)
+   * settles the intent and dispatches `Failed`; the result value is ignored —
+   * truth comes back through the invalidated query, never through the response.
+   */
+  readonly send: (intent: Event.EventType<Intents[number]>) => Effect.Effect<unknown, unknown, R2>
+  /**
+   * The pure per-intent fold over the server value (typically one
+   * `Match.exhaustive` over the intent union). MUST be idempotent against
+   * truth that already carries the intent — see the module doc.
+   */
+  readonly apply: (value: A, intent: Event.EventType<Intents[number]>) => A
+  /** The send lane. Default: a generated `${name}/sends` merge channel. */
+  readonly channel?: Channel.ChannelClass
+  readonly invalidateBy?: InvalidateBy<Inputs>
+  /** Extra refetch triggers (realtime pushes, unrelated mutations) — `AsyncCalc`'s sugar. */
+  readonly invalidateOn?: ReadonlyArray<Event.AnyEvent>
+  /** Refetch conciliation — see `AsyncCalc.live`. Mutation bursts favor `'trailing'`. */
+  readonly coalesce?: 'switch' | 'trailing'
+  /** Structural sharing across refetches AND overlay recomputes — see `AsyncCalc.live`. */
+  readonly reuse?: boolean
+} & (Gated extends true
+  ? { readonly disabled?: (inputs: InputsObject<Inputs>) => boolean }
+  : { readonly disabled?: never })
+
+/** The seam between the send procedure and the query driver (module-private). */
+interface SettleLink {
+  /** The driver's highest REQUESTED run generation (see `QueryDriver.requested`). */
+  readonly requested: () => number
+  /** Settle `opId` when a run with generation ≥ `waitFor` lands `Success`. */
+  readonly register: (opId: string, waitFor: number) => void
+}
+
+/**
+ * Wire a remote state: the query driver (truth), the overlay (visible view),
+ * the hidden queue reducer, the send procedure, and the settle link between
+ * them — one layer. Hidden names minted per call, namespaced by the remote
+ * state's name: events `…/Queued`/`…/Acked`/`…/Settled`/`…/Invalidated`, state
+ * `…/revision`, reducers `…/pending`/`…/revision`, procedure `…/send`, default
+ * channel `…/sends`.
+ */
+export const live = <
+  N extends string,
+  Inputs extends ReadonlyArray<AnySource>,
+  Intents extends ReadonlyArray<Event.AnyEvent>,
+  A,
+  E,
+  Gated extends boolean,
+  R,
+  R2,
+>(
+  remote: RemoteStateClass<N, Inputs, Intents, A, E, Gated>,
+  config: RemoteStateLive<Inputs, Intents, A, E, Gated, R, R2>,
+): Layer.Layer<
+  | Store<AsyncData<A, E, Gated>>
+  | Store<ReadonlyArray<PendingIntent<Event.EventType<Intents[number]>>>>,
+  never,
+  | InputStores<Inputs>
+  | R
+  | R2
+  | Reducers
+  | Channel.Procedures
+  | Channel.Channels
+  | Bus
+> => {
+  type I = Event.EventType<Intents[number]>
+  const name = remote.manifest.name
+  const truthTag = remote.truth.store
+  const pendingTag = remote.pending.store
+
+  // The hidden event vocabulary. `Queued` carries the intent (the queue
+  // reducer's only source of it); `Acked`/`Settled` name the op; `Invalidated`
+  // bumps the hidden revision exactly like an `invalidateOn` event.
+  const Queued = Event.make(
+    `${name}/Queued`,
+    looseSchema<{ readonly opId: string; readonly intent: I }>(
+      Schema.Struct({ opId: Schema.String, intent: Schema.Unknown }),
+    ),
+  )
+  const Acked = Event.make(`${name}/Acked`, Schema.Struct({ opId: Schema.String }))
+  const Settled = Event.make(`${name}/Settled`, Schema.Struct({ opId: Schema.String }))
+  const Invalidated = Event.make(`${name}/Invalidated`, Schema.Struct({}))
+
+  // The hidden revision pair (the `invalidateOn` machinery, unconditional here:
+  // `Invalidated` always drives it; user `invalidateOn` events join the same fold).
+  const revisionState = State.make(`${name}/revision`, RevisionSchema)
+  const revisionReducer = Reducer.make(`${name}/revision`, {
+    states: [revisionState],
+    events: [Invalidated, ...(config.invalidateOn ?? [])],
+  })
+
+  // The settle link, keyed per live so two remote states never cross-resolve.
+  const linkTag = Context.GenericTag<SettleLink>(`reform/remoteState/${name}/link`)
+
+  // ── 1. Driver + link: the truth store and the generation bookkeeping. ──────
+  const driverLayer = Layer.scopedContext(
+    Effect.gen(function* () {
+      // `disabled` is rejected at the type level for non-gated definitions
+      // (erased to `never` there); read it through a loose view for the runtime.
+      const cfg = config as {
+        readonly query: (inputs: InputsObject<Inputs>) => Effect.Effect<A, E, R>
+        readonly invalidateBy?: InvalidateBy<Inputs>
+        readonly disabled?: (inputs: InputsObject<Inputs>) => boolean
+        readonly coalesce?: 'switch' | 'trailing'
+        readonly reuse?: boolean
+      }
+      // Requirement-free read (`serviceOption`): the assembly below always
+      // provides the revision store alongside this driver.
+      const revision = Option.getOrUndefined(yield* Effect.serviceOption(revisionState.store))
+      const runtime = yield* Effect.runtime<Bus>()
+
+      // Settle waiters: a plain registry, not fibers parked per intent — so the
+      // settle path is independent of the user channel's policy (`latest`/
+      // `exclusive` lanes can't orphan a pending entry by cancelling its fiber).
+      const waiters = MutableRef.make<
+        ReadonlyArray<{ readonly opId: string; readonly waitFor: number }>
+      >([])
+      const onSettled = (generation: number) => {
+        const due = MutableRef.get(waiters).filter((waiter) => waiter.waitFor <= generation)
+        if (due.length === 0) return
+        MutableRef.update(waiters, (all) => all.filter((waiter) => waiter.waitFor > generation))
+        // Dispatch synchronously (`publish` only enqueues on the unbounded bus):
+        // the settle is enqueued in the same flush as the converged value write.
+        for (const waiter of due) {
+          Runtime.runSync(runtime)(
+            publish('Normal', Event.construct(Settled, { opId: waiter.opId })),
+          )
+        }
+      }
+
+      const driver = yield* makeQueryDriver({
+        name,
+        label: 'RemoteState',
+        gated: remote.gated,
+        inputs: remote.inputs,
+        query: cfg.query,
+        invalidateBy: cfg.invalidateBy,
+        disabled: cfg.disabled,
+        coalesce: cfg.coalesce,
+        reuse: cfg.reuse,
+        extraKey:
+          revision === undefined
+            ? undefined
+            : {
+                read: () => revision.getSnapshot(),
+                subscribe: (listener) => revision.subscribe(listener),
+              },
+        onSettled,
+      })
+      const link: SettleLink = {
+        requested: driver.requested,
+        register: (opId, waitFor) =>
+          MutableRef.update(waiters, (all) => [...all, { opId, waitFor }]),
+      }
+      return Context.make(truthTag, narrowStore<A, E, Gated>(driver.store)).pipe(
+        Context.add(linkTag, link),
+      )
+    }),
+  )
+
+  // ── 2. Overlay: visible = pending.reduce(apply, truth). ────────────────────
+  const overlayLayer = Layer.scoped(
+    remote.store,
+    Effect.gen(function* () {
+      const scheduler = yield* resolveScheduler
+      // Widened so the arm dispatch below is a plain tag union (read-only view).
+      const feedStore = widenStore<A, E, Gated>(yield* truthTag)
+      const queueStore = yield* pendingTag
+      const memo = MutableRef.make<
+        { readonly key: ReadonlyArray<unknown>; readonly output: AnyAsyncData<A, E> } | undefined
+      >(undefined)
+      const recompute = (): AnyAsyncData<A, E> => {
+        const feed = feedStore.getSnapshot()
+        const pending = queueStore.getSnapshot()
+        const key = [feed, pending]
+        const prev = MutableRef.get(memo)
+        if (prev !== undefined && sameKey(key, prev.key)) return prev.output
+        // `apply` runs over every `Success` — including `refetching: true`, so
+        // queued intents stay visible while the server converges; the other
+        // arms pass through by reference.
+        const overlaid: AnyAsyncData<A, E> =
+          feed._tag === 'Success'
+            ? AsyncData.success(
+                pending.reduce((value, entry) => config.apply(value, entry.intent), feed.value),
+                feed.refetching,
+              )
+            : feed
+        // With `reuse`, also reconcile consecutive overlay outputs: the fold
+        // rebuilds the value per recompute, so untouched subtrees would
+        // otherwise lose identity every time the queue moves.
+        const output =
+          config.reuse === true &&
+          prev !== undefined &&
+          prev.output._tag === 'Success' &&
+          overlaid._tag === 'Success'
+            ? AsyncData.success(shareStructure(prev.output.value, overlaid.value), overlaid.refetching)
+            : overlaid
+        MutableRef.set(memo, { key, output })
+        return output
+      }
+      const subscribe = (listener: () => void): (() => void) => {
+        const offFeed = feedStore.subscribe(listener)
+        const offQueue = queueStore.subscribe(listener)
+        return () => {
+          offFeed()
+          offQueue()
+        }
+      }
+      const derived = makeDerivedStore(recompute, subscribe, scheduler)
+      yield* Effect.addFinalizer(() => Effect.sync(derived.unsubscribe))
+      return narrowStore<A, E, Gated>(derived.store)
+    }),
+  )
+
+  // ── 3. Queue reducer: the pending queue's SOLE writer. ─────────────────────
+  // Assembled directly against the registry rather than through `Reducer.live`,
+  // whose parameter types are conditionals TS keeps deferred while `Intents` is
+  // an open type parameter (user code instantiates the public surface
+  // concretely, so this is the one generic caller).
+  const queueReducerName = `${name}/pending`
+  const queueHandles: ReadonlySet<string> = new Set([Queued.tag, Acked.tag, Settled.tag])
+  const foldQueue = (
+    queue: ReadonlyArray<PendingIntent<I>>,
+    event: { readonly _tag: string; readonly opId: string; readonly intent?: I },
+  ): ReadonlyArray<PendingIntent<I>> =>
+    // `Queued` is the arm carrying the intent (the `undefined` guard is for the
+    // type only — every `Queued` carries one). An ack/settle for an id that is
+    // absent (or already confirmed) keeps the same reference — a true no-op.
+    event._tag === Queued.tag
+      ? event.intent === undefined
+        ? queue
+        : [...queue, { opId: event.opId, intent: event.intent, status: 'sending' }]
+      : event._tag === Acked.tag
+        ? queue.some((entry) => entry.opId === event.opId && entry.status === 'sending')
+          ? queue.map((entry) =>
+              entry.opId === event.opId ? { ...entry, status: 'confirmed' as const } : entry,
+            )
+          : queue
+        : queue.some((entry) => entry.opId === event.opId)
+          ? queue.filter((entry) => entry.opId !== event.opId)
+          : queue
+  const queueReducerLayer = Layer.scopedDiscard(
+    Effect.gen(function* () {
+      const reducers = yield* Reducers
+      if (reducers.entries.some((entry) => entry.name === queueReducerName)) {
+        yield* Effect.logWarning(`reform: duplicate reducer name '${queueReducerName}' registered`)
+      }
+      const store = yield* pendingTag
+      const entry: ReducerEntry = {
+        name: queueReducerName,
+        handles: queueHandles,
+        // The loop only invokes `apply` for events in `handles`; `narrowHandled`
+        // restores that typed view from the erased envelope.
+        apply: (event) => store.set(foldQueue(store.get(), narrowHandled(event))),
+      }
+      yield* Effect.acquireRelease(Effect.sync(() => reducers.register(entry)), () =>
+        Effect.sync(() => reducers.unregister(entry)),
+      )
+    }),
+  )
+
+  // ── 4. Send procedure: intent dispatch → deliver → ack/settle bookkeeping. ─
+  // Hand-assembled `ProcedureEntry` for the same deferred-conditional reason as
+  // the queue reducer (the `Procedure.live` internals, verbatim).
+  const channel = config.channel ?? Channel.make(`${name}/sends`, { policy: { _tag: 'merge' } })
+  const procedureName = `${name}/send`
+  const sendHandles: ReadonlySet<string> = new Set(remote.intents.map((event) => event.tag))
+  const sendProcedureLayer = Layer.scopedDiscard(
+    Effect.gen(function* () {
+      const procedures = yield* Channel.Procedures
+      if (procedures.entries.some((entry) => entry.name === procedureName)) {
+        yield* Effect.logWarning(`reform: duplicate procedure name '${procedureName}' registered`)
+      }
+      const link = yield* linkTag
+      // Snapshot the body's full context (Bus + the send's R2) so `run` is total.
+      const runtime = yield* Effect.runtime<Bus | R2>()
+      const deliver = (intent: I): Effect.Effect<void, never, Bus | R2> =>
+        Effect.gen(function* () {
+          const opId = yield* Effect.sync(() => crypto.randomUUID())
+          yield* Event.dispatch(Queued, { opId, intent })
+          const outcome = yield* config.send(intent).pipe(
+            // A defect in `send` is a bug, but it must not strand the entry:
+            // fold it into the failure arm so the intent settles and `Failed`
+            // fires (the channel would otherwise swallow it after logging).
+            Effect.catchAllDefect((defect) => Effect.fail(defect)),
+            Effect.either,
+            // A cancelled send (a `latest`/`exclusive` user channel tearing the
+            // run down) settles too: the overlay reverts, and if the request
+            // did reach the server the next refetch shows it as truth.
+            Effect.onInterrupt(() => Event.dispatch(Settled, { opId })),
+          )
+          yield* Either.match(outcome, {
+            onLeft: (error) =>
+              Effect.zipRight(
+                Event.dispatch(remote.Failed, { intent, error }),
+                Event.dispatch(Settled, { opId }),
+              ),
+            onRight: () =>
+              // Register the waiter BEFORE the invalidation bump: `Invalidated`
+              // routes through the drain loop later, so the run it triggers is
+              // necessarily requested after `requested()` here — the waiter can
+              // never be satisfied by a refetch that predates the ack.
+              Effect.sync(() => link.register(opId, link.requested() + 1)).pipe(
+                Effect.zipRight(Event.dispatch(Acked, { opId })),
+                Effect.zipRight(Event.dispatch(Invalidated, {})),
+              ),
+          })
+        })
+      const entry: Channel.ProcedureEntry = {
+        name: procedureName,
+        channelName: channel.manifest.name,
+        handles: sendHandles,
+        run: (event) => Effect.provide(deliver(narrowHandled<I>(event)), runtime),
+      }
+      yield* Effect.acquireRelease(Effect.sync(() => procedures.register(entry)), () =>
+        Effect.sync(() => procedures.unregister(entry)),
+      )
+    }),
+  )
+
+  // ── Assembly. ───────────────────────────────────────────────────────────────
+  // The pending store backs both the overlay and the queue reducer; the hidden
+  // revision store feeds both the driver (`extraKey`) and its reducer; the
+  // channel `.live` is idempotent by name+policy, so a user channel shared with
+  // other procedures wires up exactly once.
+  const pendingStoreLayer = Layer.effect(
+    pendingTag,
+    Effect.map(resolveScheduler, (scheduler) =>
+      makeStore<ReadonlyArray<PendingIntent<I>>>([], scheduler),
+    ),
+  )
+  return Layer.mergeAll(
+    overlayLayer,
+    queueReducerLayer,
+    Reducer.live(revisionReducer, bumpRevision),
+    sendProcedureLayer,
+    Channel.live(channel),
+  ).pipe(
+    Layer.provideMerge(driverLayer),
+    Layer.provide(State.live(revisionState, revisionZero)),
+    Layer.provideMerge(pendingStoreLayer),
+  )
+}

package/{dist/cjs/runtime/bus.js → src/runtime/bus.ts}

@@ -1,7 +1,10 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.publish = exports.busLayer = exports.Bus = exports.narrowHandled = void 0;
-const effect_1 = require("effect");
+import { Context, Effect, Layer, PubSub } from 'effect'
+
+/** A dispatched event: a tagged data record (`{ _tag, ...payload }`). */
+export interface Tagged {
+  readonly _tag: string
+}
+
 /**
  * Re-narrow an erased `Tagged` envelope to a handler's declared event union. The
  * loop and channels only route events whose tag is in a handler's `handles`, so
@@ -9,17 +12,25 @@ const effect_1 = require("effect");
  * generic `Tagged`, and this restores the typed view. The one documented home
  * for that boundary cast, shared by `Reducer.live` and `Procedure.live`.
  */
-const narrowHandled = (event) => event;
-exports.narrowHandled = narrowHandled;
-/** The single dispatch bus: an unbounded PubSub fanned out to the loop and procedures. */
-class Bus extends effect_1.Context.Tag('reform/Bus')() {
+export const narrowHandled = <E>(event: Tagged): E => event as never
+
+/** UI-originated events are High; procedure-emitted follow-ups are Normal (DESIGN #46). */
+export type Priority = 'High' | 'Normal'
+
+export interface Envelope {
+  readonly priority: Priority
+  readonly event: Tagged
 }
-exports.Bus = Bus;
+
+/** The single dispatch bus: an unbounded PubSub fanned out to the loop and procedures. */
+export class Bus extends Context.Tag('reform/Bus')<Bus, PubSub.PubSub<Envelope>>() {}
+
 // Unbounded so `publish` never suspends: UI triggers dispatch synchronously
 // (`Runtime.runSync`, no fiber fork per event), and an event storm can't apply
 // backpressure to the UI thread. The single drain loop empties the bus every
 // microtask, so it does not accumulate. Swap to `PubSub.dropping(N)` if bounded
 // memory is preferred over never dropping (publish stays synchronous either way).
-exports.busLayer = effect_1.Layer.scoped(Bus, effect_1.PubSub.unbounded());
-const publish = (priority, event) => effect_1.Effect.flatMap(Bus, (bus) => effect_1.PubSub.publish(bus, { priority, event }));
-exports.publish = publish;
+export const busLayer = Layer.scoped(Bus, PubSub.unbounded<Envelope>())
+
+export const publish = (priority: Priority, event: Tagged): Effect.Effect<void, never, Bus> =>
+  Effect.flatMap(Bus, (bus) => PubSub.publish(bus, { priority, event }))