@playfast/reform 1.2.1 → 1.4.0

package/src/internal/queryState-and-scheduler-audit.test.ts

@@ -0,0 +1,170 @@
+import { expect, it } from '@effect/vitest'
+import * as Arr from 'effect/Array'
+import { Data, Effect, Layer, Match, Option, Schema as S } from 'effect'
+import { AsyncCalc, State, StateGroup } from '../index'
+import { mount, structureEquals } from '../compose/structure'
+import type { UiContract } from '../compose/ui'
+import { isLoading, type QueryState, toAsyncData } from '../calc/queryState'
+import { makeScheduler } from './scheduler'
+import { makeFlightGate, until } from '../testkit/flight.testkit'
+
+/**
+ * Adversarial audit of the key-attribution / identity fix set. Every assertion
+ * below states the behaviour the fixed code is *supposed* to have; each test
+ * fails on the current working tree.
+ */
+
+// ---------------------------------------------------------------------------
+// 1. calc/queryState.ts — a previous key's ERROR is still republished.
+//
+// `toAsyncData` withholds a superseded result unless `keepPreviousData` AND a
+// payload is present. That payload check is what is supposed to guarantee "a
+// previous key's error is never republished" — but a query holding *both* (an
+// older key's payload and a newer key's failure) passes the guard, and past the
+// guard the error branch is read before the data branch. The failure of a key
+// nobody is asking about then gates the key now in flight.
+// ---------------------------------------------------------------------------
+
+it('toAsyncData: a superseded error is withheld even when a previous payload is kept', () => {
+  // Reachable state: key A settled Success; key B settled Error (settleQueryError
+  // spreads the previous state, so `data` survives the failure); key C is now in
+  // flight and `markFetching(changedKey)` has raised `isPreviousKey`.
+  const carried: QueryState<string, string> = {
+    data: Option.some('payload-answering-key-A'),
+    error: Option.some('failure-answering-key-B'),
+    isFetching: true,
+    isStale: false,
+    isPreviousKey: true,
+    keepPreviousData: true,
+  }
+  // Control: `isLoading` already reports "there is something to show" here, so
+  // the two readers only agree if `toAsyncData` shows the kept *payload* — never
+  // the superseded failure.
+  expect(isLoading(carried)).toBe(false)
+  expect(toAsyncData(carried, true)._tag).not.toBe('Error')
+})
+
+class Boom extends Data.TaggedError('AuditBoom')<{ readonly chatId: string }> {}
+
+const Chat = S.Struct({ chatId: S.String, canWrite: S.Boolean })
+
+class AuditChatId extends State.make('audit2ChatId', S.String) {}
+class AuditInputs extends StateGroup.make(AuditChatId) {}
+const auditChatId = StateGroup.select(AuditInputs, 'audit2ChatId')
+const seededAtA = StateGroup.live(AuditInputs, { audit2ChatId: 'A' })
+
+it.live('keepPreviousData: a previous key’s error must not gate the key now in flight', () => {
+  class History extends AsyncCalc.make('AuditKeptHistory', {
+    inputs: [auditChatId],
+    output: Chat,
+    error: S.instanceOf(Boom),
+    alwaysOn: true,
+  }) {}
+  const gate = makeFlightGate()
+  const answer = (id: string): Effect.Effect<typeof Chat.Type, Boom> =>
+    Match.value(id).pipe(
+      Match.when('A', () => Effect.succeed({ chatId: 'A', canWrite: true })),
+      Match.when('B', () => Effect.fail(new Boom({ chatId: 'B' }))),
+      Match.orElse(() => gate.through(Effect.succeed({ chatId: id, canWrite: false }))),
+    )
+  const HistoryLive = AsyncCalc.live(History, {
+    query: ({ audit2ChatId: id }) => answer(id),
+    keepPreviousData: true,
+  })
+  const TestLayer = HistoryLive.pipe(Layer.provideMerge(seededAtA))
+
+  return Effect.gen(function* () {
+    const source = yield* auditChatId.store
+    const store = yield* History.store
+
+    // A answers, so there is a payload for `keepPreviousData` to keep.
+    yield* until(
+      () => store.get(),
+      (view) => view._tag === 'Success',
+    )
+
+    // B fails. That failure *is* B's own answer, so publishing it here is right.
+    source.set('B')
+    yield* until(
+      () => store.get(),
+      (view) => view._tag === 'Error',
+    )
+
+    // C is the question now. B's failure says nothing about C, and A's payload is
+    // the thing `keepPreviousData` promised to keep showing meanwhile. The store
+    // instead reports Error(Boom about 'B') with refetching: true.
+    yield* gate.hold
+    source.set('C')
+    yield* gate.awaitEntry(1)
+
+    expect(store.get()._tag).not.toBe('Error')
+  }).pipe(Effect.provide(TestLayer))
+})
+
+// ---------------------------------------------------------------------------
+// 2. compose/structure.ts — `deepEquals` stopped looking inside Effect values.
+//
+// Restricting the structural walk to plain records is right for Map/Set/RegExp,
+// but the `Equal.equals` fallback is not a deep comparison: `Option` compares its
+// payload with `Equal.equals` too, so `Option.some({ id })` is unequal to an
+// identical `Option.some({ id })`. An Option-valued prop is not an edge case —
+// the house rules require it in place of `T | null`, and it encodes over the wire
+// fine. Before this change `deepEquals` walked into the Option and answered true.
+// ---------------------------------------------------------------------------
+
+interface RowContract extends UiContract {
+  readonly props: {
+    readonly label: string
+    readonly selected: Option.Option<{ readonly id: string }>
+  }
+}
+
+const rowFrame = (selected: Option.Option<{ readonly id: string }>) =>
+  mount<RowContract>({ props: { label: 'row', selected }, slots: {} })
+
+it('structureEquals: value-equal frames carrying an Option of a record compare equal', () => {
+  // Controls: Option support in general is intact, and a genuinely different
+  // payload still reports a change.
+  expect(structureEquals(rowFrame(Option.none()), rowFrame(Option.none()))).toBe(true)
+  expect(
+    structureEquals(rowFrame(Option.some({ id: 'x' })), rowFrame(Option.some({ id: 'y' }))),
+  ).toBe(false)
+
+  expect(
+    structureEquals(rowFrame(Option.some({ id: 'a' })), rowFrame(Option.some({ id: 'a' }))),
+  ).toBe(true)
+})
+
+// ---------------------------------------------------------------------------
+// 3. internal/scheduler.ts — the liveness re-read happens once per drain.
+//
+// A write now queues `{ source, members }` so the live source can be re-read at
+// flush and anyone who unsubscribed in between dropped. But `new Set(source)` is
+// taken once, before any listener runs, so a listener that an earlier listener in
+// the same flush unsubscribes is still woken — the exact condition the re-read
+// exists to prevent. Re-reading `source` per listener costs nothing extra.
+// ---------------------------------------------------------------------------
+
+const drainMicrotasks = (turns = 5): Promise<void> =>
+  Arr.range(1, turns).reduce<Promise<void>>(
+    (chain) => chain.then(() => new Promise<void>((resolve) => queueMicrotask(resolve))),
+    Promise.resolve(),
+  )
+
+it('scheduler: a listener unsubscribed during the flush is not woken', async () => {
+  const scheduler = makeScheduler()
+  const listeners = new Set<() => void>()
+  const woken: Array<string> = []
+  const second = (): void => void woken.push('second')
+  const first = (): void => {
+    woken.push('first')
+    // A teardown reached from another listener's wake: a composition unmounting,
+    // a scope closing, a family key being forgotten.
+    listeners.delete(second)
+  }
+  listeners.add(first)
+  listeners.add(second)
+  scheduler.schedule(listeners)
+  await drainMicrotasks()
+  expect(woken).toEqual(['first'])
+})

package/src/internal/scheduler-multi-source-wake.test.ts

@@ -0,0 +1,111 @@
+import { expect, it } from '@effect/vitest'
+import * as Arr from 'effect/Array'
+import { makeScheduler } from './scheduler'
+
+/**
+ * Round-3 adversarial audit of the key-attribution / identity fix set.
+ *
+ * Only findings that survived an attempt to refute them are filed here. Every
+ * assertion states the behaviour the FIXED code is supposed to have; the test
+ * fails on the current working tree.
+ *
+ * Checked and found sound (no test filed): the read-ticketing in reform-db
+ * (`nextRead`/`applied` are per live query, tickets are strictly monotonic so
+ * `applied` can never drop a genuinely newer read, and `tapErrorCause` unregisters
+ * a refresher whose first read failed); proof's `{identity, event}` coverage
+ * credit (`compositionIdentity` in engine.ts and `compositionIdentityOf` in
+ * engineSink.ts are the same `capture(exact => exact.identity)` read, `Namespace`
+ * never rewraps a composition, and a requirement's declared events are typed as
+ * its OWN contract's action names); `fingerprint.ts`'s memo (`[Circular]` is the
+ * only way `seen` reaches the printed string and it always propagates to every
+ * ancestor, so a print without it cannot depend on the path — a literal
+ * `[Circular]` string in the data only costs a memo entry); `queryState`'s
+ * `toAsyncData`/`isLoading` pair (they differ only for `!gated`, which maps a
+ * settled-nothing state to `Loading` — true before `isPreviousKey` existed too).
+ */
+
+// The scheduler flushes on `queueMicrotask`, so draining turns is exact where a
+// duration would be a guess.
+const drainMicrotasks = (turns = 5): Promise<void> =>
+  Arr.range(1, turns).reduce<Promise<void>>(
+    (chain) => chain.then(() => new Promise<void>((resolve) => queueMicrotask(resolve))),
+    Promise.resolve(),
+  )
+
+// ---------------------------------------------------------------------------
+// internal/scheduler.ts — the per-wake liveness re-check evaluates each listener
+// against ONE source, so a second write's wake is silently dropped.
+//
+// `drain` builds `dueListeners: Map<listener, source>` and keeps only the FIRST
+// queued entry that still holds the listener. A listener that is a member of two
+// sources — the shape `sources.ts` builds for every multi-input query, where one
+// `trigger` is registered into each input store's listener set — therefore gets
+// its liveness answered by whichever store happened to be written first. If an
+// earlier listener in the same flush unsubscribes it from THAT store only, the
+// wake owed by the OTHER store, which it is still subscribed to, is dropped: that
+// write is never delivered and the reader stays stale until something else moves.
+//
+// Dropping a listener that unsubscribed is exactly what the re-check is for; this
+// listener did not unsubscribe from the source whose write is owed to it.
+// ---------------------------------------------------------------------------
+
+it('scheduler: a wake owed by a source the listener is still subscribed to is delivered', async () => {
+  const scheduler = makeScheduler()
+  // Two independent stores' listener sets. `target` reads both — one query
+  // trigger, two inputs.
+  const storeA = new Set<() => void>()
+  const storeB = new Set<() => void>()
+  const woken: Array<string> = []
+  const target = (): void => void woken.push('target')
+  // A teardown reached from another listener's wake: a scope closing, a family key
+  // forgotten, a composition unmounting. It ends `target`'s interest in A only.
+  const tearer = (): void => {
+    woken.push('tearer')
+    storeA.delete(target)
+  }
+  storeA.add(tearer)
+  storeA.add(target)
+  storeB.add(target)
+
+  // Control — with no teardown at all, both writes reach `target` exactly once.
+  const controlScheduler = makeScheduler()
+  const controlStoreA = new Set<() => void>()
+  const controlStoreB = new Set<() => void>()
+  const controlWoken: Array<string> = []
+  const controlTarget = (): void => void controlWoken.push('target')
+  controlStoreA.add(controlTarget)
+  controlStoreB.add(controlTarget)
+  controlScheduler.schedule(controlStoreA)
+  controlScheduler.schedule(controlStoreB)
+  await drainMicrotasks()
+  expect(controlWoken).toEqual(['target'])
+
+  // Control — the same teardown, with B's write queued FIRST. `target` is woken,
+  // which shows the drop below is an artefact of which store was written first,
+  // not a rule the scheduler is applying.
+  const orderScheduler = makeScheduler()
+  const orderStoreA = new Set<() => void>()
+  const orderStoreB = new Set<() => void>()
+  const orderWoken: Array<string> = []
+  const orderTarget = (): void => void orderWoken.push('target')
+  const orderTearer = (): void => {
+    orderWoken.push('tearer')
+    orderStoreA.delete(orderTarget)
+  }
+  orderStoreA.add(orderTearer)
+  orderStoreA.add(orderTarget)
+  orderStoreB.add(orderTarget)
+  orderScheduler.schedule(orderStoreB)
+  orderScheduler.schedule(orderStoreA)
+  await drainMicrotasks()
+  expect(orderWoken).toEqual(['target', 'tearer'])
+
+  // The defect — A is written, then B, in the same frame. `tearer` ends `target`'s
+  // subscription to A during the flush. B's write is still owed to `target`, which
+  // never unsubscribed from B, and is never delivered.
+  scheduler.schedule(storeA)
+  scheduler.schedule(storeB)
+  await drainMicrotasks()
+  expect(storeB.has(target)).toBe(true)
+  expect(woken).toEqual(['tearer', 'target'])
+})

package/src/internal/scheduler.ts

@@ -1,19 +1,50 @@
-import { Context, Effect, Layer, MutableRef, Option } from 'effect'
+import { Context, Effect, Layer, MutableRef, Option, Predicate } from 'effect'
+import { microtask } from './platform'
 
 export interface Scheduler {
   readonly schedule: (listeners: Iterable<() => void>) => void
 }
 
+/**
+ * Notifications normally coalesce onto a microtask. Inside this window they run
+ * inline instead, because the synchronous trigger path needs subscribers
+ * re-rendered before it returns: React restores a controlled input's DOM value at
+ * the end of the discrete event, and a listener that has not run by then leaves it
+ * restoring stale props over the character the user just typed.
+ *
+ * A module-level flag rather than a method on one Scheduler: stores and triggers
+ * resolve `Notifications` from their own contexts and can legitimately land on
+ * different instances, so flushing "the" scheduler would flush the wrong one.
+ * Nothing awaits inside the window, so it cannot interleave with another trigger.
+ */
+const inlineNotifications = MutableRef.make(false)
+
+export const withInlineNotifications = <A>(run: () => A): A => {
+  const outer = MutableRef.get(inlineNotifications)
+  MutableRef.set(inlineNotifications, true)
+  const ran = run()
+  MutableRef.set(inlineNotifications, outer)
+  return ran
+}
+
 export const makeScheduler = (): Scheduler => {
-  const pending = new Set<() => void>()
+  // Each write queues the members present at that moment, so a listener that
+  // subscribes later is not told about a write that predates it; the live source is
+  // kept alongside and re-read at flush to drop anyone who unsubscribed in between.
+  interface Queued {
+    readonly source: Iterable<() => void>
+    readonly members: ReadonlyArray<() => void>
+  }
+  const pending = new Set<Queued>()
   const armed = MutableRef.make(false)
+  const flushing = MutableRef.make(false)
 
   const runListener = (listener: () => void): void =>
     Effect.runSync(
       Effect.try({ try: listener, catch: (error) => error }).pipe(
         Effect.catchAll((error) =>
           Effect.sync(() =>
-            queueMicrotask(() => {
+            microtask(() => {
               // oxlint-disable-next-line reform-rules/no-throw -- only way to surface a listener defect to the host's global error handler
               throw error
             }),
@@ -22,26 +53,69 @@ export const makeScheduler = (): Scheduler => {
       ),
     )
 
+  // Membership at flush time. A re-readable source — a `Set`, the hot path every store
+  // passes, or an array — is read again so a listener that unsubscribed in between is
+  // dropped. Anything else is judged against the schedule-time snapshot, because an
+  // `Iterable` may be one-shot (`map.values()`, a generator) and taking that snapshot
+  // already drained it.
+  const isLive = (queued: Queued, listener: () => void): boolean => {
+    if (Predicate.isSet(queued.source)) {
+      return queued.source.has(listener)
+    }
+    if (Array.isArray(queued.source)) {
+      return queued.source.includes(listener)
+    }
+    return queued.members.includes(listener)
+  }
+
   const drain = (): void => {
     if (pending.size === 0) {
       return
     }
     const due = [...pending]
     pending.clear()
-    due.forEach(runListener)
+    // One wake per listener, however many writes queued it, in schedule order. Each
+    // write is judged against its OWN source at the moment it would run: an earlier
+    // listener in this same flush can tear a later one down — a scope closing, a
+    // family key forgotten, a composition unmounting — and a listener that has since
+    // unsubscribed must not be woken. A listener registered in several stores is
+    // still owed the wakes of the stores it did not leave, so each queued write gets
+    // its own answer rather than one memoised for the whole drain.
+    const woken = new Set<() => void>()
+    due.forEach((queued) => {
+      queued.members.forEach((listener) => {
+        if (!woken.has(listener) && isLive(queued, listener)) {
+          woken.add(listener)
+          runListener(listener)
+        }
+      })
+    })
     drain()
   }
 
+  // A listener that triggers another event re-enters here; the guard drops the inner
+  // call because `drain` already loops until `pending` is empty, so the outer pass
+  // still runs whatever the listener queued.
   const flush = () => {
+    if (MutableRef.get(flushing)) {
+      return
+    }
+    MutableRef.set(flushing, true)
     MutableRef.set(armed, false)
+    // `runListener` absorbs every listener defect, so `drain` cannot throw past here.
     drain()
+    MutableRef.set(flushing, false)
   }
 
   const schedule = (listeners: Iterable<() => void>) => {
-    ;[...listeners].forEach((listener) => pending.add(listener))
+    pending.add({ source: listeners, members: Array.from(listeners) })
+    if (MutableRef.get(inlineNotifications)) {
+      flush()
+      return
+    }
     if (pending.size > 0 && !MutableRef.get(armed)) {
       MutableRef.set(armed, true)
-      queueMicrotask(flush)
+      microtask(flush)
     }
   }
 

package/src/internal.ts

@@ -220,3 +220,4 @@ export { makeStore, type Store } from './internal/store'
 // first-class `Source`s which must participate in dependency tracking and
 // reflection exactly like a `Calc`.
 export { type Kind, type Manifest, yieldableClass } from './definition/definition'
+export { microtask, operationId } from './internal/platform'

package/src/reducer/reducer.ts

@@ -128,7 +128,7 @@ export function live(
                   // The loop calls entries only for handled events. At this
                   // existential boundary the family's decoders restore the
                   // exact key/value types before either touches its store.
-                  const key = familyDefinition.decodeKeySync(
+                  const key = familyDefinition.validateKeySync(
                     sync(Reflect.apply(config.keyOf, undefined, [narrowHandled(event)])),
                   )
                   const previous = family.at(key).get()
@@ -138,7 +138,7 @@ export function live(
                   } else if (next !== previous) {
                     // Same-reference return means "no change": skip the nominal re-decode,
                     // which would mint a fresh value and repaint every tracker of this slice.
-                    family.at(key).set(familyDefinition.decodeValueSync(next))
+                    family.at(key).set(familyDefinition.validateValueSync(next))
                   }
                 },
               })),
@@ -157,7 +157,7 @@ export function live(
                 if (next === previous) {
                   return
                 }
-                store.set(state.decodeUnknownSync(next))
+                store.set(state.validateSync(next))
               },
             })),
         )

package/src/remote/pendingQueue.ts

@@ -1,11 +1,15 @@
 import { Equal, MutableRef, Option } from 'effect'
 import { inspectable } from '../internal/inspect'
 import type { Scheduler } from '../internal/scheduler'
+import { sameKey } from '../internal/sources'
 import type { Store } from '../internal/store'
 import type { PendingIntent } from './remoteStateTypes'
 
 export interface PendingNode<I> {
   readonly entry: MutableRef.MutableRef<PendingIntent<I>>
+  // None for entries linked through `store.set`, which carries no key: those stay
+  // unattributed and always apply, preserving the old behaviour on that path.
+  readonly key: Option.Option<ReadonlyArray<unknown>>
 }
 
 // Duplicate opIds retain every node so indexed updates preserve the old map semantics.
@@ -17,7 +21,13 @@ export 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
+  // Folds only the intents issued against `key` (plus unattributed ones).
+  readonly foldFor: <B>(
+    key: ReadonlyArray<unknown>,
+    initial: B,
+    combine: (accumulator: B, entry: PendingIntent<I>) => B,
+  ) => B
+  readonly append: (entry: PendingIntent<I>, key: Option.Option<ReadonlyArray<unknown>>) => void
   readonly ack: (opId: string) => void
   readonly settle: (opId: string) => void
 }
@@ -49,9 +59,10 @@ export const makePendingQueue = <I>(scheduler: Scheduler): PendingQueue<I> => {
     scheduler.schedule(listeners)
   }
 
-  const link = (entry: PendingIntent<I>): void => {
+  const link = (entry: PendingIntent<I>, key: Option.Option<ReadonlyArray<unknown>>): void => {
     const node: PendingNode<I> = {
       entry: MutableRef.make(entry),
+      key,
     }
     ordered.add(node)
     const indexed = byOpId.get(entry.opId)
@@ -75,8 +86,26 @@ export const makePendingQueue = <I>(scheduler: Scheduler): PendingQueue<I> => {
     return MutableRef.get(folded)
   }
 
-  const append = (entry: PendingIntent<I>): void => {
-    link(entry)
+  const foldFor = <B>(
+    key: ReadonlyArray<unknown>,
+    initialValue: B,
+    combine: (accumulator: B, entry: PendingIntent<I>) => B,
+  ): B => {
+    const folded = MutableRef.make(initialValue)
+    ordered.forEach((node) => {
+      const applies = Option.match(node.key, {
+        onNone: () => true,
+        onSome: (issuedFor) => sameKey(issuedFor, key),
+      })
+      if (applies) {
+        MutableRef.update(folded, (accumulator) => combine(accumulator, MutableRef.get(node.entry)))
+      }
+    })
+    return MutableRef.get(folded)
+  }
+
+  const append = (entry: PendingIntent<I>, key: Option.Option<ReadonlyArray<unknown>>): void => {
+    link(entry, key)
     announce(Option.none())
   }
 
@@ -122,7 +151,7 @@ export const makePendingQueue = <I>(scheduler: Scheduler): PendingQueue<I> => {
         return
       }
       clear()
-      next.forEach(link)
+      next.forEach((entry) => link(entry, Option.none()))
       announce(Option.some(next))
     },
     subscribe: (listener) => {
@@ -138,6 +167,7 @@ export const makePendingQueue = <I>(scheduler: Scheduler): PendingQueue<I> => {
     store,
     revision: () => MutableRef.get(revision),
     fold,
+    foldFor,
     append,
     ack,
     settle,