@playfast/reform 1.3.0 → 1.4.0

package/src/remote/remoteState.intent-key-stamp.test.ts

@@ -0,0 +1,207 @@
+import { expect, it } from '@effect/vitest'
+import { Deferred, Effect, Layer, Match, Schema as S } from 'effect'
+import { Channel, Engine, Event, Reducer, RemoteState, State } from '../index'
+import { until } from '../testkit/flight.testkit'
+
+// ---------------------------------------------------------------------------
+// A pending intent is stamped with the input key it was issued against, so the
+// overlay never applies it to another key's truth (pendingQueue.foldFor,
+// SettleLink.key). The stamp is taken in the `Queued` reducer
+// (remoteStateSend.ts:44-56) — "the same frame the intent was issued in, so it
+// records the key the user was actually looking at".
+//
+// It is not. `Queued` is dispatched by the *send procedure*, which runs on the
+// intent's Channel — an arbitrary time after the intent left the bus. Anything
+// the channel's policy makes the send wait for (a single-flight `exclusive`
+// lane, a `debounce` window, a busy `throttle` bucket) is a window in which the
+// input key can move; the intent is then stamped with, and applied to, a key it
+// was never issued against.
+// ---------------------------------------------------------------------------
+
+const Row = S.Struct({ id: S.String, name: S.String })
+type Row = typeof Row.Type
+
+class HuntAdded extends Event.make('HuntAdded', S.Struct({ id: S.String, name: S.String })) {}
+class HuntRemoved extends Event.make('HuntRemoved', S.Struct({ id: S.String })) {}
+type HuntIntent = Event.EventType<typeof HuntAdded> | Event.EventType<typeof HuntRemoved>
+
+// the navigation the user performs *after* issuing the intent — an ordinary
+// event, so it is ordered against the intent by the bus, not by the test.
+class HuntGoTo extends Event.make('HuntGoTo', S.Struct({ page: S.Number })) {}
+
+const applyIntent = (rows: ReadonlyArray<Row>, intent: HuntIntent): ReadonlyArray<Row> =>
+  Match.value(intent).pipe(
+    Match.tag('HuntAdded', ({ id, name }) =>
+      rows.some((row) => row.id === id) ? rows : [...rows, { id, name }],
+    ),
+    Match.tag('HuntRemoved', ({ id }) => rows.filter((row) => row.id !== id)),
+    Match.exhaustive,
+  )
+
+const ids = (rows: ReadonlyArray<Row>): ReadonlyArray<string> => rows.map((row) => row.id)
+
+it.live(
+  'an intent held by its channel is stamped with the key it landed on, not the key it was issued on',
+  () => {
+    class Page extends State.make('huntPage', S.Number) {}
+    class Nav extends Reducer.make('huntNav', { states: [Page], events: [HuntGoTo] }) {}
+    class Items extends RemoteState.make('HuntItems', {
+      inputs: [Page],
+      output: S.Array(Row),
+      intents: [HuntAdded, HuntRemoved],
+      alwaysOn: true,
+    }) {}
+
+    const gateA = Effect.runSync(Deferred.make<void>())
+    const gateB = Effect.runSync(Deferred.make<void>())
+    // one send at a time: the framework, not the test, holds the second intent back
+    const sends = Channel.make('hunt/sends', { policy: { _tag: 'exclusive' } })
+
+    const ItemsLive = RemoteState.live(Items, {
+      query: ({ huntPage }) => Effect.succeed([{ id: `p${huntPage}`, name: `page-${huntPage}` }]),
+      send: (intent) => Deferred.await(intent.id === 'a' ? gateA : gateB),
+      apply: applyIntent,
+      channel: sends,
+    })
+    const TestLayer = Layer.mergeAll(
+      ItemsLive,
+      Reducer.live(Nav, (_, event) => event.page),
+    ).pipe(Layer.provideMerge(State.live(Page, 1)), Layer.provideMerge(Engine))
+
+    return Effect.gen(function* () {
+      const view = yield* Items.store
+      const truth = yield* Items.truth.store
+      const queue = yield* Items.pending.store
+
+      yield* until(
+        () => truth.get(),
+        (v) => v._tag === 'Success' && v.refetching === false && v.value[0]?.id === 'p1',
+      )
+
+      // 'a' is issued on page 1 and reaches the channel immediately; its send parks.
+      yield* Event.dispatch(HuntAdded, { id: 'a', name: 'a' })
+      yield* until(
+        () => queue.get(),
+        (q) => q.length === 1,
+      )
+      const onPageOne = view.get()
+      expect(onPageOne._tag).toBe('Success')
+      if (onPageOne._tag === 'Success') expect(ids(onPageOne.value)).toEqual(['p1', 'a'])
+
+      // 'b' is ALSO issued on page 1 — but the single-flight channel is busy with
+      // 'a', so its send (and its `Queued`) wait. THEN the user navigates.
+      yield* Event.dispatch(HuntAdded, { id: 'b', name: 'b' })
+      yield* Event.dispatch(HuntGoTo, { page: 2 })
+      yield* until(
+        () => truth.get(),
+        (v) => v._tag === 'Success' && v.refetching === false && v.value[0]?.id === 'p2',
+      )
+
+      // precondition: 'b' has still not been queued — the channel is holding it
+      expect(queue.get().map((entry) => entry.intent.id)).toEqual(['a'])
+
+      // CONTROL: 'a' was stamped on page 1, so page 2's truth is untouched by it.
+      // Same machinery, same assertion shape — it passes.
+      const control = view.get()
+      expect(control._tag).toBe('Success')
+      if (control._tag === 'Success') expect(ids(control.value)).toEqual(['p2'])
+
+      // release 'a'; the channel is now free and 'b' finally reaches the queue
+      yield* Deferred.succeed(gateA, undefined)
+      yield* until(
+        () => queue.get(),
+        (q) => q.some((entry) => entry.intent.id === 'b'),
+      )
+      yield* until(
+        () => truth.get(),
+        (v) => v._tag === 'Success' && v.refetching === false && v.value[0]?.id === 'p2',
+      )
+
+      const visible = view.get()
+      expect(visible._tag).toBe('Success')
+      if (visible._tag === 'Success') {
+        // 'b' was issued while the user was on page 1 — page 2 never carried it
+        expect(ids(visible.value)).toEqual(['p2'])
+      }
+
+      yield* Deferred.succeed(gateB, undefined)
+    }).pipe(Effect.provide(TestLayer))
+  },
+)
+
+it.live('a held optimistic delete erases a row from the input key it never targeted', () => {
+  class Page extends State.make('huntErasePage', S.Number) {}
+  class Nav extends Reducer.make('huntEraseNav', { states: [Page], events: [HuntGoTo] }) {}
+  class Items extends RemoteState.make('HuntEraseItems', {
+    inputs: [Page],
+    output: S.Array(Row),
+    intents: [HuntAdded, HuntRemoved],
+    alwaysOn: true,
+  }) {}
+
+  const gateHold = Effect.runSync(Deferred.make<void>())
+  const gateErase = Effect.runSync(Deferred.make<void>())
+  const sends = Channel.make('huntErase/sends', { policy: { _tag: 'exclusive' } })
+
+  const ItemsLive = RemoteState.live(Items, {
+    query: ({ huntErasePage }) => Effect.succeed([{ id: 'x', name: `x-on-${huntErasePage}` }]),
+    send: (intent) => Deferred.await(intent._tag === 'HuntAdded' ? gateHold : gateErase),
+    apply: applyIntent,
+    channel: sends,
+  })
+  const TestLayer = Layer.mergeAll(
+    ItemsLive,
+    Reducer.live(Nav, (_, event) => event.page),
+  ).pipe(Layer.provideMerge(State.live(Page, 1)), Layer.provideMerge(Engine))
+
+  return Effect.gen(function* () {
+    const view = yield* Items.store
+    const truth = yield* Items.truth.store
+    const queue = yield* Items.pending.store
+
+    yield* until(
+      () => truth.get(),
+      (v) => v._tag === 'Success' && v.refetching === false && v.value[0]?.name === 'x-on-1',
+    )
+
+    // occupy the single-flight channel with an unrelated intent issued on page 1
+    yield* Event.dispatch(HuntAdded, { id: 'hold', name: 'hold' })
+    yield* until(
+      () => queue.get(),
+      (q) => q.length === 1,
+    )
+
+    // the user deletes page 1's row 'x', then navigates away
+    yield* Event.dispatch(HuntRemoved, { id: 'x' })
+    yield* Event.dispatch(HuntGoTo, { page: 2 })
+    yield* until(
+      () => truth.get(),
+      (v) => v._tag === 'Success' && v.refetching === false && v.value[0]?.name === 'x-on-2',
+    )
+
+    // precondition + CONTROL: the *stamped* pending Added is correctly withheld
+    expect(queue.get().map((entry) => entry.intent.id)).toEqual(['hold'])
+    const control = view.get()
+    expect(control._tag).toBe('Success')
+    if (control._tag === 'Success') expect(ids(control.value)).toEqual(['x'])
+
+    yield* Deferred.succeed(gateHold, undefined)
+    yield* until(
+      () => queue.get(),
+      (q) => q.some((entry) => entry.intent._tag === 'HuntRemoved'),
+    )
+    yield* until(
+      () => truth.get(),
+      (v) => v._tag === 'Success' && v.refetching === false && v.value[0]?.name === 'x-on-2',
+    )
+
+    const visible = view.get()
+    expect(visible._tag).toBe('Success')
+    if (visible._tag === 'Success') {
+      // the delete targeted page 1's row; page 2's row must survive
+      expect(ids(visible.value)).toEqual(['x'])
+    }
+
+    yield* Deferred.succeed(gateErase, undefined)
+  }).pipe(Effect.provide(TestLayer))
+})

package/src/remote/remoteState.key-attribution.test.ts

@@ -0,0 +1,174 @@
+import { expect, it } from '@effect/vitest'
+import { Deferred, Effect, Layer, Match, Schema as S } from 'effect'
+import { Engine, Event, RemoteState, State, StateGroup } from '../index'
+import { until } from '../testkit/flight.testkit'
+
+// ---------------------------------------------------------------------------
+// RemoteState keeps ONE pending queue for the whole definition, but a
+// definition is keyed by its `inputs`. A PendingIntent records `opId`,
+// `intent` and `status` — nothing about the input key the intent was issued
+// against (remoteStateTypes.ts:15). `recompute` therefore folds every pending
+// intent onto whatever truth currently holds, even after the input key moved
+// (remoteState.ts:203-217). Same identity/attribution class as issue #22:
+// state that outlives the input it was derived from.
+// ---------------------------------------------------------------------------
+
+const Row = S.Struct({ id: S.String, name: S.String })
+type Row = typeof Row.Type
+
+class RegressAdded extends Event.make('RegressAdded', S.Struct({ id: S.String, name: S.String })) {}
+class RegressRemoved extends Event.make('RegressRemoved', S.Struct({ id: S.String })) {}
+type RegressIntent = Event.EventType<typeof RegressAdded> | Event.EventType<typeof RegressRemoved>
+
+// idempotent against truth that already carries the intent, per the RemoteState contract
+const applyIntent = (rows: ReadonlyArray<Row>, intent: RegressIntent): ReadonlyArray<Row> =>
+  Match.value(intent).pipe(
+    Match.tag('RegressAdded', ({ id, name }) =>
+      rows.some((row) => row.id === id) ? rows : [...rows, { id, name }],
+    ),
+    Match.tag('RegressRemoved', ({ id }) => rows.filter((row) => row.id !== id)),
+    Match.exhaustive,
+  )
+
+const ids = (rows: ReadonlyArray<Row>): ReadonlyArray<string> => rows.map((row) => row.id)
+
+// ---------------------------------------------------------------------------
+//  — additive leak across a plain input-key change.
+// ---------------------------------------------------------------------------
+it.live('a pending intent for one input key overlays another key truth', () => {
+  class RegressPage extends State.make('regressLeakPage', S.Number) {}
+  class RegressInputs extends StateGroup.make(RegressPage) {}
+  class Items extends RemoteState.make('RegressLeakItems', {
+    inputs: [StateGroup.select(RegressInputs, 'regressLeakPage')],
+    output: S.Array(Row),
+    intents: [RegressAdded, RegressRemoved],
+    alwaysOn: true,
+  }) {}
+
+  // the send never completes, so the intent stays genuinely in flight
+  const inFlight = Effect.runSync(Deferred.make<void>())
+  const ItemsLive = RemoteState.live(Items, {
+    query: ({ regressLeakPage }) =>
+      Effect.succeed([{ id: `p${regressLeakPage}`, name: `page-${regressLeakPage}` }]),
+    send: () => Deferred.await(inFlight),
+    apply: applyIntent,
+  })
+  const TestLayer = ItemsLive.pipe(
+    Layer.provideMerge(StateGroup.live(RegressInputs, { regressLeakPage: 1 })),
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    const view = yield* Items.store
+    const truth = yield* Items.truth.store
+    const queue = yield* Items.pending.store
+    const page = yield* RegressPage.store
+
+    yield* until(
+      () => truth.get(),
+      (v) => v._tag === 'Success' && v.refetching === false && v.value[0]?.id === 'p1',
+    )
+
+    yield* Event.dispatch(RegressAdded, { id: 'ghost', name: 'ghost' })
+    yield* until(
+      () => queue.get(),
+      (q) => q.length === 1,
+    )
+    const optimistic = view.get()
+    expect(optimistic._tag).toBe('Success')
+    if (optimistic._tag === 'Success') expect(ids(optimistic.value)).toEqual(['p1', 'ghost'])
+
+    // move to a different input key and let its truth fully settle
+    page.set(2)
+    yield* until(
+      () => truth.get(),
+      (v) => v._tag === 'Success' && v.refetching === false && v.value[0]?.id === 'p2',
+    )
+    // the send is still parked, so the intent is still pending — for page 1
+    expect(queue.get()).toHaveLength(1)
+
+    const visible = view.get()
+    expect(visible._tag).toBe('Success')
+    if (visible._tag === 'Success') {
+      // page 2's truth is [p2]; 'ghost' was only ever optimistic for page 1
+      expect(ids(visible.value)).toEqual(['p2'])
+    }
+
+    yield* Deferred.succeed(inFlight, undefined)
+  }).pipe(Effect.provide(TestLayer))
+})
+
+// ---------------------------------------------------------------------------
+//  — destructive variant, and it survives a full gated Idle round trip:
+// truth is cleared to Idle and re-fetched for a *different* key, yet the stale
+// intent still erases a row it never targeted. Not "we hold the overlay while
+// the same query revalidates".
+// ---------------------------------------------------------------------------
+it.live('an optimistic delete for one input key erases a row from another key', () => {
+  class RegressPage extends State.make('regressErasePage', S.Number) {}
+  class RegressInputs extends StateGroup.make(RegressPage) {}
+  class Items extends RemoteState.make('RegressEraseItems', {
+    inputs: [StateGroup.select(RegressInputs, 'regressErasePage')],
+    output: S.Array(Row),
+    intents: [RegressAdded, RegressRemoved],
+  }) {}
+
+  const inFlight = Effect.runSync(Deferred.make<void>())
+  const ItemsLive = RemoteState.live(Items, {
+    query: ({ regressErasePage }) =>
+      Effect.succeed([{ id: 'x', name: `x-on-${regressErasePage}` }]),
+    send: () => Deferred.await(inFlight),
+    apply: applyIntent,
+    disabled: ({ regressErasePage }) => regressErasePage < 0,
+  })
+  const TestLayer = ItemsLive.pipe(
+    Layer.provideMerge(StateGroup.live(RegressInputs, { regressErasePage: 1 })),
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    const view = yield* Items.store
+    const truth = yield* Items.truth.store
+    const queue = yield* Items.pending.store
+    const page = yield* RegressPage.store
+
+    yield* until(
+      () => truth.get(),
+      (v) => v._tag === 'Success' && v.value[0]?.name === 'x-on-1',
+    )
+
+    // delete row 'x' *of page 1*, optimistically
+    yield* Event.dispatch(RegressRemoved, { id: 'x' })
+    yield* until(
+      () => queue.get(),
+      (q) => q.length === 1,
+    )
+    const optimistic = view.get()
+    expect(optimistic._tag).toBe('Success')
+    if (optimistic._tag === 'Success') expect(ids(optimistic.value)).toEqual([])
+
+    // gate off: truth drops to Idle and its data is discarded
+    page.set(-1)
+    yield* until(
+      () => view.get(),
+      (v) => v._tag === 'Idle',
+    )
+
+    // come back on a different key — a fresh query, a different row
+    page.set(7)
+    yield* until(
+      () => truth.get(),
+      (v) => v._tag === 'Success' && v.value[0]?.name === 'x-on-7',
+    )
+    expect(queue.get()).toHaveLength(1)
+
+    const visible = view.get()
+    expect(visible._tag).toBe('Success')
+    if (visible._tag === 'Success') {
+      // page 7's row was never targeted by the pending delete
+      expect(ids(visible.value)).toEqual(['x'])
+    }
+
+    yield* Deferred.succeed(inFlight, undefined)
+  }).pipe(Effect.provide(TestLayer))
+})

package/src/remote/remoteState.ts

@@ -10,6 +10,7 @@ import {
 } from '../internal/queryDriver'
 import { reuse as shareStructure } from '../internal/reuse'
 import { resolveScheduler } from '../internal/scheduler'
+import { resolvePersistSlot } from '../internal/queryDriverPersistWarn'
 import { type InputStores, sameKey } from '../internal/sources'
 import { makeDerivedStore } from '../internal/store'
 import * as Reducer from '../reducer/reducer'
@@ -128,13 +129,14 @@ export const live = <
         }
       }
 
-      const persistOption = config.persist
-      const persistKey =
-        persistOption === true || persistOption === undefined || persistOption === false
-          ? name
-          : (persistOption.key ?? name)
+      const persistKey = yield* resolvePersistSlot({
+        label: 'RemoteState',
+        name,
+        inputs: remote.inputs.length,
+        option: config.persist,
+      })
       const persist =
-        persistOption === undefined || persistOption === false
+        config.persist === undefined || config.persist === false
           ? undefined
           : { key: persistKey, codec: remote.codec }
       const revisionKey = (source: NonNullable<typeof revision>) => ({
@@ -152,6 +154,7 @@ export const live = <
         disabled: config.disabled,
         coalesce: config.coalesce,
         reuse: config.reuse,
+        keepPreviousData: config.keepPreviousData,
         persist,
         extraKey,
         onSettled,
@@ -184,6 +187,8 @@ export const live = <
       const link: SettleLink = {
         requested: driver.requested,
         register: (opId, waitFor) => registerWaiter({ opId, waitFor }),
+        key: driver.key,
+        subscribeKey: driver.subscribeKey,
       }
       return Context.make(truthTag, narrowStore<A, E, Gated>(driver.store)).pipe(
         Context.add(linkTag, link),
@@ -197,19 +202,24 @@ export const live = <
       const scheduler = yield* resolveScheduler
       const feedStore = widenStore<A, E, Gated>(yield* truthTag)
       const queue = yield* pendingQueueTag
+      const link = yield* linkTag
       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 key = [feed, queue.revision()]
+        const inputKey = link.key()
+        // The input key joins the memo key: which intents apply depends on it.
+        const key = [feed, queue.revision(), ...inputKey]
         const prev = MutableRef.get(memo)
         if (prev !== undefined && sameKey(key, prev.key)) {
           return prev.output
         }
         // Full replay preserves observable value identity when apply allocates and reuse is off.
+        // Only this key's intents: an optimistic write issued on another key is not
+        // about this payload, and applying it injects or deletes rows it never targeted.
         const applyPending = (base: A): A =>
-          queue.fold(base, (applied, entry) => config.apply(applied, entry.intent))
+          queue.foldFor(inputKey, base, (applied, entry) => config.apply(applied, entry.intent))
         const overlaid: AnyAsyncData<A, E> =
           feed._tag === 'Success'
             ? AsyncData.success(applyPending(feed.value), feed.refetching)
@@ -228,12 +238,16 @@ export const live = <
         MutableRef.set(memo, { key, output })
         return output
       }
+      // The key is a third input: it decides which queued intents apply, and it can
+      // move without the feed or the queue writing anything.
       const subscribe = (listener: () => void): (() => void) => {
         const offFeed = feedStore.subscribe(listener)
         const offQueue = queue.store.subscribe(listener)
+        const offKey = link.subscribeKey(listener)
         return () => {
           offFeed()
           offQueue()
+          offKey()
         }
       }
       const derived = makeDerivedStore(recompute, subscribe, scheduler)
@@ -243,21 +257,19 @@ export const live = <
   )
 
   const channel = config.channel ?? Channel.make(`${name}/sends`, { policy: { _tag: 'merge' } })
-  const intentEvents = {
-    queued: Queued,
-    acked: Acked,
-    settled: Settled,
-    invalidated: Invalidated,
-  }
+  const intentEvents = { queued: Queued, acked: Acked, settled: Settled, invalidated: Invalidated }
+  const intentTags = new Set(remote.intents.map((event) => event.tag))
   const pendingReducer = queueReducerLayer({
+    linkTag,
     name: `${name}/pending`,
     queueTag: pendingQueueTag,
+    handles: intentTags,
     events: intentEvents,
   })
   const sendProcedure = sendProcedureLayer({
     name: `${name}/send`,
     channel,
-    handles: new Set(remote.intents.map((event) => event.tag)),
+    handles: intentTags,
     linkTag,
     failed: remote.Failed,
     send: config.send,

package/src/remote/remoteStateSend.ts

@@ -1,10 +1,11 @@
-import { Context, Effect, Either, Layer } from 'effect'
+import { Context, Effect, Either, Layer, Option, Predicate } from 'effect'
 import * as Channel from '../channel/channel'
 import * as Event from '../event/event'
 import { Bus, narrowHandled } from '../runtime/bus'
 import { type ReducerEntry, Reducers } from '../runtime/loop'
 import type { PendingQueue } from './pendingQueue'
 import type { QueueFoldEventExternalApi, SettleLink } from './remoteStateTypes'
+import { operationId } from '../internal/platform'
 
 export interface IntentEvents<I> {
   readonly queued: Event.EventClass<string, { readonly opId: string; readonly intent: I }>
@@ -16,13 +17,15 @@ export interface IntentEvents<I> {
 interface QueueReducerOptions<I> {
   readonly name: string
   readonly queueTag: Context.Tag<PendingQueue<I>, PendingQueue<I>>
+  readonly linkTag: Context.Tag<SettleLink, SettleLink>
+  readonly handles: ReadonlySet<string>
   readonly events: IntentEvents<I>
 }
 
 // Direct registry assembly avoids deferred conditional parameters while Intents is generic.
 export const queueReducerLayer = <I>(
   options: QueueReducerOptions<I>,
-): Layer.Layer<never, never, Reducers | PendingQueue<I>> =>
+): Layer.Layer<never, never, Reducers | PendingQueue<I> | SettleLink> =>
   Layer.scopedDiscard(
     Effect.gen(function* () {
       const reducers = yield* Reducers
@@ -30,22 +33,40 @@ export const queueReducerLayer = <I>(
         yield* Effect.logWarning(`reform: duplicate reducer name '${options.name}' registered`)
       }
       const queue = yield* options.queueTag
+      const link = yield* options.linkTag
+      // `Queued` is dispatched from the send procedure, which runs on the intent's
+      // channel — a `debounce`/`throttle`/`exclusive` policy can hold an intent across
+      // a key change, so the key at that moment is not the key the intent targets.
+      // Reducers run before channels are offered in the same drain frame, so reading
+      // the key here records the one the user was actually looking at.
+      const issuedKeys = new WeakMap<object, ReadonlyArray<unknown>>()
       const entry: ReducerEntry = {
         name: options.name,
         handles: new Set([
+          ...options.handles,
           options.events.queued.tag,
           options.events.acked.tag,
           options.events.settled.tag,
         ]),
         apply: (event) => {
+          if (options.handles.has(event._tag)) {
+            issuedKeys.set(event, link.key())
+            return
+          }
           const handled = narrowHandled<QueueFoldEventExternalApi<I>>(event)
           if (handled._tag === options.events.queued.tag) {
             if (handled.intent !== undefined) {
-              queue.append({
-                opId: handled.opId,
-                intent: handled.intent,
-                status: 'sending',
-              })
+              const issued = Predicate.isObject(handled.intent)
+                ? Option.fromNullable(issuedKeys.get(handled.intent))
+                : Option.none<ReadonlyArray<unknown>>()
+              queue.append(
+                {
+                  opId: handled.opId,
+                  intent: handled.intent,
+                  status: 'sending',
+                },
+                Option.some(Option.getOrElse(issued, () => link.key())),
+              )
             }
             return
           }
@@ -87,7 +108,7 @@ export const sendProcedureLayer = <I, R2>(
       const deliver = Effect.fn('deliver')(function* (
         intent: I,
       ): Effect.fn.Return<void, never, Bus | R2> {
-        const opId = yield* Effect.sync(() => crypto.randomUUID())
+        const opId = yield* Effect.sync(() => operationId())
         yield* Event.dispatch(options.events.queued, { opId, intent })
         const outcome = yield* options.send(intent).pipe(
           Effect.catchAllDefect((defect) => Effect.fail(defect)),

package/src/remote/remoteStateTypes.ts

@@ -132,6 +132,9 @@ export type RemoteStateLiveExternalApi<
   readonly invalidateOn?: ReadonlyArray<Event.AnyEvent>
   readonly coalesce?: 'switch' | 'trailing'
   readonly reuse?: boolean
+  // Keep showing the previous key's truth while the new key loads. Off by default.
+  // oxlint-disable-next-line reform-rules/no-optional-fields -- caller-omitted option built at the remoteState construction site; Option<T> would change that call shape
+  readonly keepPreviousData?: boolean
   readonly settled?: {
     readonly event: SettledEvent
     readonly payload: (result: RemoteStateSettled<A, E>) => EventPayload<SettledEvent>
@@ -147,6 +150,10 @@ export type RemoteStateLiveExternalApi<
 export interface SettleLink {
   readonly requested: () => number
   readonly register: (opId: string, waitFor: number) => void
+  // The input key an intent is issued against, so the overlay never applies it to
+  // another key's truth.
+  readonly key: () => ReadonlyArray<unknown>
+  readonly subscribeKey: (listener: () => void) => () => void
 }
 
 export interface WaiterRegistration {

package/src/runtime/bus.ts

@@ -14,6 +14,11 @@ export type Priority = 'High' | 'Normal'
 export interface Envelope {
   readonly priority: Priority
   readonly event: Tagged
+  /**
+   * Set when the synchronous trigger path already ran this event's reducers, so the
+   * drain contributes only the channel/procedure half and never applies them twice.
+   */
+  readonly reduced: boolean
 }
 
 const BusBase: Context.TagClass<Bus, 'reform/Bus', PubSub.PubSub<Envelope>> = Context.Tag(
@@ -26,4 +31,4 @@ export class Bus extends BusBase {}
 export const busLayer: Layer.Layer<Bus> = 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 }))
+  Effect.flatMap(Bus, (bus) => PubSub.publish(bus, { priority, event, reduced: false }))