@playfast/reform 1.0.1 → 1.2.0

package/src/remote/remoteState.ts

@@ -1,5 +1,24 @@
-import { Context, Effect, Either, Layer, MutableRef, Option, Runtime, Schema } from 'effect'
-import { type AnyAsyncData, AsyncData, narrowStore, widenStore } from '../calc/asyncData'
+import {
+  Context,
+  Effect,
+  Either,
+  Equal,
+  Iterable,
+  Layer,
+  MutableRef,
+  Option,
+  Runtime,
+  Schema,
+} from 'effect'
+import type { Effect as EffectType } from 'effect/Effect'
+import {
+  type AnyAsyncData,
+  AsyncData,
+  type AsyncError,
+  type AsyncSuccess,
+  narrowStore,
+  widenStore,
+} from '../calc/asyncData'
 import * as Channel from '../channel/channel'
 import { type Manifest, yieldableClass } from '../definition/definition'
 import * as Event from '../event/event'
@@ -8,192 +27,171 @@ import {
   type GatedOf,
   gatedFlag,
   makeQueryDriver,
+  type QueryCodec,
   RevisionSchema,
   revisionZero,
 } from '../internal/queryDriver'
+import { inspectable } from '../internal/inspect'
 import { reuse as shareStructure } from '../internal/reuse'
-import { resolveScheduler } from '../internal/scheduler'
+import { resolveScheduler, type Scheduler } from '../internal/scheduler'
 import {
   type InputsObject,
   type InputStores,
   type InvalidateBy,
   sameKey,
 } from '../internal/sources'
-import { makeDerivedStore, makeStore, type Store } from '../internal/store'
+import { makeDerivedStore, 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. */
+import { type AnySource, type SourceCapture, StateToken } from '../state/token'
+
+// An intent acked at generation g settles only on Success with generation > g.
+// `apply` must be idempotent while refetched truth and the pending intent overlap.
+
 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.
+export type RemoteStateSettled<A, E> = AsyncSuccess<A> | AsyncError<E>
+
+export const RemoteStateVisibleStoreTypeId: unique symbol = Symbol.for(
+  'reform/RemoteStateVisibleStore',
+)
+export type RemoteStateVisibleStoreTypeId = typeof RemoteStateVisibleStoreTypeId
+
+export interface RemoteStateVisibleStore<N extends string> {
+  readonly [RemoteStateVisibleStoreTypeId]: N
+}
+
+export const RemoteStateTruthStoreTypeId: unique symbol = Symbol.for('reform/RemoteStateTruthStore')
+export type RemoteStateTruthStoreTypeId = typeof RemoteStateTruthStoreTypeId
+
+export interface RemoteStateTruthStore<N extends string> {
+  readonly [RemoteStateTruthStoreTypeId]: N
+}
+
+export const RemoteStatePendingStoreTypeId: unique symbol = Symbol.for(
+  'reform/RemoteStatePendingStore',
+)
+export type RemoteStatePendingStoreTypeId = typeof RemoteStatePendingStoreTypeId
+
+export interface RemoteStatePendingStore<N extends string> {
+  readonly [RemoteStatePendingStoreTypeId]: N
+}
+
+type EventPayload<Ev extends Event.AnyEvent> =
+  Ev extends Event.EventClass<string, infer P> ? P : never
+
+// ExternalApi: optional `intent` only on Queued envelopes.
 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 {
+export interface RemoteStateSchemaReflection {
+  readonly ast: Schema.Schema<unknown, unknown, unknown>['ast']
+}
+
+export interface RemoteStateManifestExternalApi<N extends string> 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 output: RemoteStateSchemaReflection
+  readonly error?: RemoteStateSchemaReflection
   readonly gated: boolean
-  /** The mutation vocabulary — intent event tags, reflectable without running logic. */
   readonly intents: ReadonlyArray<string>
 }
 
 export interface RemoteStateClass<
-  out N extends string,
+  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>>> {
+> extends EffectType<AsyncData<A, E, Gated>, never, RemoteStateVisibleStore<N>> {
   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 manifest: RemoteStateManifestExternalApi<N>
+  readonly codec: QueryCodec<A>
+  readonly store: Context.Tag<RemoteStateVisibleStore<N>, Store<AsyncData<A, E, Gated>>>
   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 capture: <Result>(visit: SourceCapture<Result>) => Result
+  readonly truth: StateToken<`${N}/truth`, AsyncData<A, E, Gated>, RemoteStateTruthStore<N>>
+  // pending is a Source, not a StateClass, so user reducers cannot target it.
   readonly pending: StateToken<
     `${N}/pending`,
-    ReadonlyArray<PendingIntent<Event.EventType<Intents[number]>>>
+    ReadonlyArray<PendingIntent<Event.EventType<Intents[number]>>>,
+    RemoteStatePendingStore<N>
   >
-  /** 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,
+  OutputSchema extends Schema.Schema.AnyNoContext,
+  ErrorSchema extends Schema.Schema.AnyNoContext | undefined,
   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 output: OutputSchema
+  readonly error?: ErrorSchema
   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`.
- */
+// Schema.Unknown is structural because Intents is open at make-time; the declaration preserves its authored payload type.
+const looseSchema = <P>(schema: Schema.Schema.AnyNoContext): Schema.Schema<P, P, never> =>
+  Schema.declare((input): input is P => Schema.is(schema)(input))
+
 export const make = <
   const N extends string,
   const Inputs extends ReadonlyArray<AnySource>,
   const Intents extends ReadonlyArray<Event.AnyEvent>,
-  A,
-  E = never,
+  OutputSchema extends Schema.Schema.AnyNoContext,
+  ErrorSchema extends Schema.Schema.AnyNoContext | undefined = undefined,
   const AlwaysOn extends boolean = false,
 >(
   name: N,
-  config: RemoteStateConfigExternalApi<Inputs, Intents, A, E, AlwaysOn>,
-): RemoteStateClass<N, Inputs, Intents, A, E, GatedOf<AlwaysOn>> => {
+  config: RemoteStateConfigExternalApi<Inputs, Intents, OutputSchema, ErrorSchema, AlwaysOn>,
+): RemoteStateClass<
+  N,
+  Inputs,
+  Intents,
+  Schema.Schema.Type<OutputSchema>,
+  ErrorSchema extends Schema.Schema.AnyNoContext ? Schema.Schema.Type<ErrorSchema> : never,
+  GatedOf<AlwaysOn>
+> => {
+  type A = Schema.Schema.Type<OutputSchema>
+  type E = ErrorSchema extends Schema.Schema.AnyNoContext ? Schema.Schema.Type<ErrorSchema> : never
   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 store = Context.GenericTag<
+    RemoteStateVisibleStore<N>,
+    Store<AsyncData<A, E, GatedOf<AlwaysOn>>>
+  >(`reform/remoteState/${name}`)
+  const truthTag = Context.GenericTag<
+    RemoteStateTruthStore<N>,
+    Store<AsyncData<A, E, GatedOf<AlwaysOn>>>
+  >(`reform/remoteState/${name}/truth`)
+  const pendingTag = Context.GenericTag<
+    RemoteStatePendingStore<N>,
+    Store<ReadonlyArray<PendingIntent<I>>>
+  >(`reform/remoteState/${name}/pending`)
   const gated = gatedFlag(config.alwaysOn)
-  const manifest: RemoteStateManifestExternalApi<N, A, E> = {
+  const manifest: RemoteStateManifestExternalApi<N> = {
     kind: 'RemoteState',
     name,
     output: config.output,
@@ -201,34 +199,39 @@ export const make = <
     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 codec: QueryCodec<A> = {
+    encode: Schema.encode(config.output),
+    decode: Schema.decodeUnknown(config.output),
+  }
+  // Annotations preserve template-literal types for the public statics.
   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 }),
+  const remote: RemoteStateClass<N, Inputs, Intents, A, E, GatedOf<AlwaysOn>> = yieldableClass(
+    read,
+    {
+      manifest,
+      codec,
+      store,
+      name,
+      inputs: config.inputs,
+      intents: config.intents,
+      gated,
+      capture: <Result>(visit: SourceCapture<Result>): Result => visit(remote),
+      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 }),
+        ),
       ),
-    ),
-  })
+    },
+  )
+  return remote
 }
 
-/**
- * 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>,
@@ -237,38 +240,22 @@ export type RemoteStateLiveExternalApi<
   Gated extends boolean,
   R,
   R2,
+  SettledEvent extends Event.AnyEvent,
 > = {
   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.
-   */
+  // Any failure settles and emits Failed; truth comes only from the invalidated query.
   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 settled?: {
+    readonly event: SettledEvent
+    readonly payload: (result: RemoteStateSettled<A, E>) => EventPayload<SettledEvent>
+  }
+  // Only settled server truth is persisted; the optimistic overlay is a separate store.
   readonly persist?:
     | boolean
     | { readonly key?: string | ((inputs: InputsObject<Inputs>) => string) }
@@ -276,36 +263,156 @@ export type RemoteStateLiveExternalApi<
   ? { 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
 }
 
-/**
- * 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`.
- */
+interface WaiterRegistration {
+  readonly opId: string
+  readonly waitFor: number
+}
+
+interface PendingNode<I> {
+  readonly entry: MutableRef.MutableRef<PendingIntent<I>>
+}
+
+// Duplicate opIds retain every node so indexed updates preserve the old map semantics.
+interface PendingOpEntry<I> {
+  readonly nodes: Set<PendingNode<I>>
+}
+
+interface PendingQueue<I> {
+  readonly store: Store<ReadonlyArray<PendingIntent<I>>>
+  readonly revision: () => number
+  readonly fold: <B>(initial: B, combine: (accumulator: B, entry: PendingIntent<I>) => B) => B
+  readonly append: (entry: PendingIntent<I>) => void
+  readonly ack: (opId: string) => void
+  readonly settle: (opId: string) => void
+}
+
+const makePendingQueue = <I>(scheduler: Scheduler): PendingQueue<I> => {
+  // Set insertion order preserves dispatch/apply order while allowing O(1) updates.
+  const ordered = new Set<PendingNode<I>>()
+  const byOpId = new Map<string, PendingOpEntry<I>>()
+  const listeners = new Set<() => void>()
+  const revision = MutableRef.make(0)
+  const initial: ReadonlyArray<PendingIntent<I>> = []
+  const snapshot = MutableRef.make<Option.Option<ReadonlyArray<PendingIntent<I>>>>(
+    Option.some(initial),
+  )
+
+  const materialize = (): ReadonlyArray<PendingIntent<I>> => {
+    const cached = MutableRef.get(snapshot)
+    if (Option.isSome(cached)) {
+      return cached.value
+    }
+    const current = Array.from(ordered, (node) => MutableRef.get(node.entry))
+    MutableRef.set(snapshot, Option.some(current))
+    return current
+  }
+
+  const announce = (next: Option.Option<ReadonlyArray<PendingIntent<I>>>): void => {
+    MutableRef.set(snapshot, next)
+    MutableRef.update(revision, (current) => current + 1)
+    scheduler.schedule(listeners)
+  }
+
+  const link = (entry: PendingIntent<I>): void => {
+    const node: PendingNode<I> = {
+      entry: MutableRef.make(entry),
+    }
+    ordered.add(node)
+    const indexed = byOpId.get(entry.opId)
+    if (indexed === undefined) {
+      byOpId.set(entry.opId, { nodes: new Set([node]) })
+    } else {
+      indexed.nodes.add(node)
+    }
+  }
+
+  const clear = (): void => {
+    ordered.clear()
+    byOpId.clear()
+  }
+
+  const fold = <B>(initialValue: B, combine: (accumulator: B, entry: PendingIntent<I>) => B): B => {
+    const folded = MutableRef.make(initialValue)
+    ordered.forEach((node) => {
+      MutableRef.update(folded, (accumulator) => combine(accumulator, MutableRef.get(node.entry)))
+    })
+    return MutableRef.get(folded)
+  }
+
+  const append = (entry: PendingIntent<I>): void => {
+    link(entry)
+    announce(Option.none())
+  }
+
+  const ack = (opId: string): void => {
+    const indexed = byOpId.get(opId)
+    if (indexed === undefined) {
+      return
+    }
+    const stillSending = MutableRef.make(false)
+    indexed.nodes.forEach((node) => {
+      if (MutableRef.get(node.entry).status === 'sending') {
+        MutableRef.set(stillSending, true)
+      }
+    })
+    if (!MutableRef.get(stillSending)) {
+      return
+    }
+    // Rebuild every duplicate once one is sending, matching the former array map.
+    indexed.nodes.forEach((node) => {
+      MutableRef.update(node.entry, (entry) => ({ ...entry, status: 'confirmed' as const }))
+    })
+    announce(Option.none())
+  }
+
+  const settle = (opId: string): void => {
+    const indexed = byOpId.get(opId)
+    if (indexed === undefined) {
+      return
+    }
+    indexed.nodes.forEach((node) => {
+      ordered.delete(node)
+    })
+    byOpId.delete(opId)
+    announce(Option.none())
+  }
+
+  const store: Store<ReadonlyArray<PendingIntent<I>>> = {
+    get: materialize,
+    getSnapshot: materialize,
+    getVersion: () => MutableRef.get(revision),
+    set: (next) => {
+      if (Equal.equals(materialize(), next)) {
+        return
+      }
+      clear()
+      next.forEach(link)
+      announce(Option.some(next))
+    },
+    subscribe: (listener) => {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+    ...inspectable(() => ({ _id: 'reform/Store', value: materialize() })),
+  }
+
+  return {
+    store,
+    revision: () => MutableRef.get(revision),
+    fold,
+    append,
+    ack,
+    settle,
+  }
+}
+
 export const live = <
   N extends string,
   Inputs extends ReadonlyArray<AnySource>,
@@ -315,29 +422,23 @@ 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]>>>>,
+  RemoteStateVisibleStore<N> | RemoteStateTruthStore<N> | RemoteStatePendingStore<N>,
   never,
-  | InputStores<Inputs>
-  | R
-  | R2
-  | Reducers
-  | Channel.Procedures
-  | Channel.Channels
-  | Bus
+  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
+  const pendingQueueTag = Context.GenericTag<PendingQueue<I>>(
+    `reform/remoteState/${name}/pendingQueue`,
+  )
 
-  // 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 +449,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,76 +459,93 @@ 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).
-      const waiters = MutableRef.make<
-        ReadonlyArray<{ readonly opId: string; readonly waitFor: number }>
-      >([])
+      // Buckets, not cancellable fibers, keep waiters alive under latest/exclusive policies.
+      // Monotonic waitFor values make insertion order match generation order.
+      const waiters = new Map<number, Set<{ readonly opId: string }>>()
       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.
-        due.forEach((waiter) =>
-          Runtime.runSync(runtime)(
-            publish('Normal', Event.construct(Settled, { opId: waiter.opId })),
-          ),
+        Iterable.forEach(
+          Iterable.takeWhile(waiters, ([waitFor]) => waitFor <= generation),
+          ([waitFor, generationWaiters]) => {
+            waiters.delete(waitFor)
+            // runSync enqueues settles in the same flush as converged truth.
+            generationWaiters.forEach(({ opId }) =>
+              Runtime.runSync(runtime)(publish('Normal', Event.construct(Settled, { opId }))),
+            )
+          },
         )
       }
+      const registerWaiter = ({ opId, waitFor }: WaiterRegistration): void => {
+        const generationWaiters = waiters.get(waitFor)
+        if (generationWaiters === undefined) {
+          waiters.set(waitFor, new Set([{ opId }]))
+        } else {
+          generationWaiters.add({ opId })
+        }
+      }
 
-      // 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).
-      const persistOption = cfg.persist
+      const persistOption = config.persist
       const persistKey =
         persistOption === true || persistOption === undefined || persistOption === false
           ? name
-          : persistOption.key ?? name
+          : (persistOption.key ?? name)
       const persist =
         persistOption === undefined || persistOption === false
           ? undefined
-          : { key: persistKey, schema: remote.manifest.output }
-      const extraKey =
-        revision === undefined
-          ? undefined
-          : { read: () => revision.getSnapshot(), subscribe: (listener: () => void) => revision.subscribe(listener) }
+          : { key: persistKey, codec: remote.codec }
+      const revisionKey = (source: NonNullable<typeof revision>) => ({
+        read: () => source.getSnapshot(),
+        subscribe: (listener: () => void) => source.subscribe(listener),
+      })
+      const extraKey = revision === undefined ? undefined : revisionKey(revision)
       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,
+        query: config.query,
+        invalidateBy: config.invalidateBy,
+        disabled: config.disabled,
+        coalesce: config.coalesce,
+        reuse: config.reuse,
         persist,
         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',
+                settledConfig.event.buildUnknown(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) =>
-          MutableRef.update(waiters, (all) => [...all, { opId, waitFor }]),
+        register: (opId, waitFor) => registerWaiter({ opId, waitFor }),
       }
       return Context.make(truthTag, narrowStore<A, E, Gated>(driver.store)).pipe(
         Context.add(linkTag, link),
@@ -437,48 +553,46 @@ 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 queue = yield* pendingQueueTag
       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 key = [feed, queue.revision()]
         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.
+        // Full replay preserves observable value identity when apply allocates and reuse is off.
         const applyPending = (base: A): A =>
-          pending.reduce((applied, entry) => config.apply(applied, entry.intent), base)
+          queue.fold(base, (applied, entry) => config.apply(applied, entry.intent))
         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 =
+          feed._tag === 'Success'
+            ? AsyncData.success(applyPending(feed.value), feed.refetching)
+            : feed
+        const reusable =
           config.reuse === true &&
           prev !== undefined &&
           prev.output._tag === 'Success' &&
           overlaid._tag === 'Success'
-            ? AsyncData.success(shareStructure(prev.output.value, overlaid.value), overlaid.refetching)
-            : overlaid
+            ? shareStructure(prev.output.value, overlaid.value)
+            : undefined
+        const output: AnyAsyncData<A, E> =
+          reusable === undefined || overlaid._tag !== 'Success'
+            ? overlaid
+            : AsyncData.success(reusable, overlaid.refetching)
         MutableRef.set(memo, { key, output })
         return output
       }
       const subscribe = (listener: () => void): (() => void) => {
         const offFeed = feedStore.subscribe(listener)
-        const offQueue = queueStore.subscribe(listener)
+        const offQueue = queue.store.subscribe(listener)
         return () => {
           offFeed()
           offQueue()
@@ -490,67 +604,44 @@ export const live = <
     }),
   )
 
-  // ── 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).
+  // Direct registry assembly avoids deferred conditional parameters while Intents is generic.
   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 queue = yield* pendingQueueTag
       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))),
+        apply: (event) => {
+          const handled = narrowHandled<QueueFoldEventExternalApi<I>>(event)
+          if (handled._tag === Queued.tag) {
+            if (handled.intent !== undefined) {
+              queue.append({
+                opId: handled.opId,
+                intent: handled.intent,
+                status: 'sending',
+              })
+            }
+            return
+          }
+          if (handled._tag === Acked.tag) {
+            queue.ack(handled.opId)
+            return
+          }
+          queue.settle(handled.opId)
+        },
       }
-      yield* Effect.acquireRelease(Effect.sync(() => reducers.register(entry)), () =>
-        Effect.sync(() => reducers.unregister(entry)),
+      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))
@@ -561,62 +652,49 @@ export const live = <
         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 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(
+          Effect.catchAllDefect((defect) => Effect.fail(defect)),
+          Effect.either,
+          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 before invalidation so a pre-ack refetch cannot settle this intent.
+            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)),
+      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),
-    ),
+  const pendingStoreLayer = Layer.scopedContext(
+    Effect.map(resolveScheduler, (scheduler) => {
+      const queue = makePendingQueue<I>(scheduler)
+      return Context.make(pendingTag, queue.store).pipe(Context.add(pendingQueueTag, queue))
+    }),
   )
   return Layer.mergeAll(
     overlayLayer,