@playfast/reform 0.1.0 → 1.1.1

package/src/remote/remoteState.ts

@@ -1,311 +1,58 @@
-import { Context, Effect, Either, Layer, MutableRef, Option, Runtime, Schema } from 'effect'
-import { type AnyAsyncData, AsyncData, narrowStore, widenStore } from '../calc/asyncData'
+import {
+  Context,
+  Effect,
+  Layer,
+  MutableRef,
+  Option,
+  Runtime,
+  Schema,
+} from 'effect'
+import { type 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 { type InputStores } from '../internal/sources'
+import { makeStore, type Store } from '../internal/store'
 import * as Reducer from '../reducer/reducer'
-import { Bus, narrowHandled, publish } from '../runtime/bus'
-import { type ReducerEntry, Reducers } from '../runtime/loop'
+import { Bus, publish } from '../runtime/bus'
+import { 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
-}
-
-// The erased event envelope the queue reducer folds over (bus boundary shape ⇒
-// `ExternalApi` postfix exempts the optional `intent` field). Only `Queued`
-// carries an `intent`; ack/settle envelopes name an op only.
-interface QueueFoldEventExternalApi<I> {
-  readonly _tag: string
-  readonly opId: string
-  readonly intent?: I
-}
-
-// Reflective metadata read by chrome/dev tools (boundary shape ⇒ `ExternalApi`
-// postfix exempts it from `no-optional-fields`).
-export interface RemoteStateManifestExternalApi<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: RemoteStateManifestExternalApi<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]>>>
-}
-
-// Public definition-surface config (boundary shape ⇒ `ExternalApi` postfix
-// exempts the optional option fields from `no-optional-fields`).
-export interface RemoteStateConfigExternalApi<
-  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: RemoteStateConfigExternalApi<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: RemoteStateManifestExternalApi<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 RemoteStateLiveExternalApi<
-  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
-  /**
-   * Persist the converged `Success` truth through the optional host `QueryStore`
-   * — see `AsyncCalc.live`. Only the settled SERVER value is written: the driver's
-   * `persistWrite` runs in the success lane after `settleSuccess`, while the
-   * optimistic overlay lives in a separate downstream store the driver never
-   * sees — so a persisted value can never capture an un-acked mutation. `true`
-   * keys by the remote state's name; `{ key }` overrides (a function of the
-   * inputs for a keyed family). Values (de)serialize through the `output` schema.
-   */
-  readonly persist?:
-    | boolean
-    | { readonly key?: string | ((inputs: InputsObject<Inputs>) => string) }
-} & (Gated extends true
-  ? { readonly disabled?: (inputs: InputsObject<Inputs>) => boolean }
-  : { readonly disabled?: never })
-
-// Loose runtime view: `disabled` is erased to `never` for non-gated definitions
-// at the type level, so the driver reads config back through this (boundary ⇒
-// `ExternalApi` postfix exempts its optional fields).
-type RemoteStateLiveRuntimeExternalApi<Inputs extends ReadonlyArray<AnySource>, A, E, R> = {
-  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
-  readonly persist?:
-    | boolean
-    | { readonly key?: string | ((inputs: InputsObject<Inputs>) => string) }
-}
-
-/** 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
-}
+import { type AnySource } from '../state/token'
+import {
+  looseSchema,
+  type PendingIntent,
+  type RemoteStateClass,
+  type RemoteStateSettled,
+} from './remoteStateDefinition'
+import type {
+  RemoteStateLiveExternalApi,
+  RemoteStateLiveRuntimeExternalApi,
+  SettleLink,
+} from './remoteStateLiveTypes'
+import { makeOverlayLayer, makeQueueReducerLayer } from './remoteStateLayers'
+import { makeSendProcedureLayer } from './remoteStateSend'
+
+// Generation rule: intent acked at gen g settles only on Success with gen > g (no flicker).
+// apply must be idempotent: between refetch landing and settle, intent is applied over truth that already has it.
+
+export {
+  type FailedIntent,
+  make,
+  type PendingIntent,
+  type RemoteStateClass,
+  type RemoteStateConfigExternalApi,
+  type RemoteStateManifestExternalApi,
+  type RemoteStateSettled,
+} from './remoteStateDefinition'
+
+export type { RemoteStateLiveExternalApi } from './remoteStateLiveTypes'
 
-/**
- * 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>,
@@ -315,9 +62,10 @@ export const live = <
   Gated extends boolean,
   R,
   R2,
+  SettledEvent extends Event.AnyEvent = never,
 >(
   remote: RemoteStateClass<N, Inputs, Intents, A, E, Gated>,
-  config: RemoteStateLiveExternalApi<Inputs, Intents, A, E, Gated, R, R2>,
+  config: RemoteStateLiveExternalApi<Inputs, Intents, A, E, Gated, R, R2, SettledEvent>,
 ): Layer.Layer<
   | Store<AsyncData<A, E, Gated>>
   | Store<ReadonlyArray<PendingIntent<Event.EventType<Intents[number]>>>>,
@@ -335,9 +83,6 @@ export const live = <
   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 }>(
@@ -348,8 +93,6 @@ export const live = <
   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 extraInvalidateOn = Option.getOrElse(
     Option.fromNullable(config.invalidateOn),
@@ -360,24 +103,16 @@ export const live = <
     events: [Invalidated, ...extraInvalidateOn],
   })
 
-  // 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.
       // oxlint-disable-next-line reform-rules/no-type-assertion -- type-level erasure seam: `disabled` is `never` for non-gated definitions; read it back through the runtime view
       const cfg = config as RemoteStateLiveRuntimeExternalApi<Inputs, A, E, R>
-      // 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).
+      // Registry (not per-intent fibers): latest/exclusive cancel must not orphan waiters
       const waiters = MutableRef.make<
         ReadonlyArray<{ readonly opId: string; readonly waitFor: number }>
       >([])
@@ -387,8 +122,7 @@ export const live = <
           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.
+        // runSync: settle enqueued in same flush as converged value write
         due.forEach((waiter) =>
           Runtime.runSync(runtime)(
             publish('Normal', Event.construct(Settled, { opId: waiter.opId })),
@@ -396,9 +130,7 @@ export const live = <
         )
       }
 
-      // Persist mirrors `AsyncCalc.live`: only the settled truth reaches the
-      // store (see the `persist` doc above), so it needs no extra success/overlay
-      // guard. `true` keys by name; `{ key }` overrides (a function for a family).
+      // Persist only settled server truth (overlay is a separate store the driver never sees)
       const persistOption = cfg.persist
       const persistKey =
         persistOption === true || persistOption === undefined || persistOption === false
@@ -426,6 +158,31 @@ export const live = <
         extraKey,
         onSettled,
       })
+      const settledConfig = config.settled
+      if (settledConfig !== undefined) {
+        const truth = widenStore<A, E, Gated>(narrowStore<A, E, Gated>(driver.store))
+        const lastSettled = MutableRef.make<RemoteStateSettled<A, E> | undefined>(undefined)
+        const publishSettled = () => {
+          const settledTruth = truth.getSnapshot()
+          if (
+            (settledTruth._tag === 'Success' || settledTruth._tag === 'Error') &&
+            settledTruth.refetching === false &&
+            MutableRef.get(lastSettled) !== settledTruth
+          ) {
+            MutableRef.set(lastSettled, settledTruth)
+            Runtime.runSync(runtime)(
+              publish(
+                'Normal',
+                Event.construct(settledConfig.event, settledConfig.payload(settledTruth)),
+              ),
+            )
+          }
+        }
+        const unsubscribe = truth.subscribe(publishSettled)
+        yield* Effect.addFinalizer(() => Effect.sync(unsubscribe))
+        const scheduler = yield* resolveScheduler
+        scheduler.schedule([publishSettled])
+      }
       const link: SettleLink = {
         requested: driver.requested,
         register: (opId, waitFor) =>
@@ -437,181 +194,37 @@ export const live = <
     }),
   )
 
-  // ── 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 applyPending = (base: A): A =>
-          pending.reduce((applied, entry) => config.apply(applied, entry.intent), base)
-        const overlaid: AnyAsyncData<A, E> =
-          feed._tag === 'Success' ? AsyncData.success(applyPending(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: QueueFoldEventExternalApi<I>,
-  ): ReadonlyArray<PendingIntent<I>> => {
-    // `Queued` is the arm carrying the intent (the `undefined` guard is for the
-    // type only — every `Queued` carries one).
-    if (event._tag === Queued.tag) {
-      if (event.intent === undefined) {
-        return queue
-      }
-      return [...queue, { opId: event.opId, intent: event.intent, status: 'sending' }]
-    }
-    // An ack flips a still-sending op to confirmed; an ack for an id that is
-    // absent (or already confirmed) keeps the same reference — a true no-op.
-    if (event._tag === Acked.tag) {
-      const stillSending = queue.some(
-        (entry) => entry.opId === event.opId && entry.status === 'sending',
-      )
-      if (!stillSending) {
-        return queue
-      }
-      return queue.map((entry) =>
-        entry.opId === event.opId ? { ...entry, status: 'confirmed' as const } : entry,
-      )
-    }
-    // Settle drops the op if present; absent ⇒ same reference, a true no-op.
-    if (!queue.some((entry) => entry.opId === event.opId)) {
-      return queue
-    }
-    return queue.filter((entry) => entry.opId !== event.opId)
-  }
-  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)),
-      )
-    }),
-  )
+  const overlayLayer = makeOverlayLayer<I, A, E, Gated>({
+    apply: config.apply,
+    pendingTag,
+    reuse: config.reuse,
+    storeTag: remote.store,
+    truthTag,
+  })
 
-  // ── 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 queueReducerLayer = makeQueueReducerLayer<I>({
+    ackedTag: Acked.tag,
+    name: `${name}/pending`,
+    pendingTag,
+    queuedTag: Queued.tag,
+    settledTag: Settled.tag,
+  })
   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 = Effect.fn('deliver')(
-        function* (intent: I): Effect.fn.Return<void, never, Bus | R2> {
-          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)),
-      )
-    }),
-  )
+  const sendProcedureLayer = makeSendProcedureLayer<I, R2>({
+    acked: Acked,
+    channel,
+    failed: remote.Failed,
+    handles: sendHandles,
+    invalidated: Invalidated,
+    linkTag,
+    name: procedureName,
+    queued: Queued,
+    send: config.send,
+    settled: Settled,
+  })
 
-  // ── 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) =>