@playfast/reform 1.2.1 → 1.4.0

package/src/internal/queryDriver-defect-attribution.test.ts

@@ -0,0 +1,107 @@
+// ADVERSARIAL AUDIT of the identity/attribution fix diff.
+//
+// Every test below asserts the behaviour the *fixed* code is supposed to have;
+// each one FAILS on the working tree as of this writing. Nothing here fixes
+// anything — no source file and no existing test file is touched.
+//
+// Five further findings were proved during this audit and are NOT in this file
+// because the working tree was edited concurrently and they no longer reproduce:
+//   * stateFamily `forget` + `evictWhenUnused` — a woken subscriber's re-subscribe
+//     was undone by the old subscription's release, evicting the live store
+//     (since fixed by per-instance counts + `stamps`).
+//   * scheduler — a listener subscribing after a write was woken by it, and was
+//     delivered ahead of an earlier store's listener (since fixed by snapshotting
+//     members at schedule time and intersecting with the live source at flush).
+//   * `isLoading` contradicted `toAsyncData` under `keepPreviousData` (since fixed
+//     by carrying `keepPreviousData` on `QueryState`).
+//   * RemoteState's overlay folded intents by `link.key()` while subscribing only to
+//     feed + queue, so a key change that wrote nothing to the feed changed the
+//     visible value with no wake (since fixed by `SettleLink.subscribeKey`).
+//   * `connect()`'s re-attachable subscription never re-baselined, so a `Delete`
+//     frame missed while detached left a permanent phantom node (since fixed by
+//     keeping the subscription for the binding's life and adding `close()`).
+import { expect, it } from '@effect/vitest'
+import { Data, Effect, Layer, Option, Schema as S } from 'effect'
+import { AsyncCalc, Engine, State, StateGroup } from '../index'
+import type { QueryState } from '../calc/queryState'
+import { Queries } from '../runtime/queries'
+import { until } from '../testkit/flight.testkit'
+
+class Torn extends Data.TaggedError('audit/Torn')<{ readonly reason: string }> {}
+
+// A negative wait: long enough that a missing transition would have landed,
+// short enough that the assertion — not a timeout — reports the failure.
+const settleRounds = 40
+
+// ---------------------------------------------------------------------------
+// FINDING (retargeted) — claim 4 (`settleDefect` retracts only its own flight).
+//
+// The audit read this as a regression: a run that dies right after a key change
+// leaves `data = Some(previous key)`, `isPreviousKey = true`, `isFetching = false`,
+// which projects as a spinner that never resolves. Probed against the claim: an
+// `alwaysOn` query whose FIRST run dies — no key change anywhere, no retained
+// payload — is `Loading` forever too. `gatedFlag(alwaysOn: true)` is `gated: false`,
+// and `unsettled` has no Idle to return for an ungated query, so a query that will
+// never answer has no state to be in. The stranding is real and pre-dates the key
+// work; it is a missing `AsyncData` arm for "this query is broken", not a
+// misattribution, and inventing one is a contract change for its owner to make.
+//
+// What the key work does owe is retraction in the raw state: a defect on the
+// NEWEST run must stop advertising a flight, must not retract a successor's, and
+// must not re-credit the retained payload to the key that failed.
+// queryDriverSettle.ts:75-81.
+// ---------------------------------------------------------------------------
+it.live('a defect retracts the flight it was issued for without re-crediting the payload', () => {
+  class Kid extends State.make('auditStrandKey', S.String) {}
+  class Inputs extends StateGroup.make(Kid) {}
+  const kid = StateGroup.select(Inputs, 'auditStrandKey')
+
+  class Dying extends AsyncCalc.make('audit/strand-dying', {
+    inputs: [kid],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+
+  const TestLayer = AsyncCalc.live(Dying, {
+    query: ({ auditStrandKey: key }): Effect.Effect<number> =>
+      key === 'a' ? Effect.succeed(1) : Effect.die(new Torn({ reason: key })),
+  }).pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { auditStrandKey: 'a' })),
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    const source = yield* kid.store
+    const dying = yield* Dying.store
+    const registry = yield* Queries
+    yield* until(
+      () => dying.get(),
+      (v) => v._tag === 'Success',
+    )
+    const snapshot = () =>
+      Option.map(Option.fromNullable(registry.byName.get('audit/strand-dying')), (query) =>
+        query.snapshot(),
+      )
+
+    const reads = (predicate: (state: QueryState<unknown, unknown>) => boolean) => () =>
+      Option.match(snapshot(), { onNone: () => false, onSome: predicate })
+
+    source.set('b')
+    // First the key move registers: a flight is open and the retained payload is
+    // credited to the key it answered…
+    yield* until(
+      reads((state) => state.isFetching && state.isPreviousKey),
+      (raised) => raised,
+    )
+    // …then the run dies and that flight — and only that flight — is retracted.
+    yield* until(
+      reads((state) => !state.isFetching),
+      (retracted) => retracted,
+      settleRounds,
+    )
+    // The run is over, so nothing claims to be in flight…
+    expect(Option.map(snapshot(), (state) => state.isFetching)).toStrictEqual(Option.some(false))
+    // …and key 'a' answer is still credited to key 'a', not silently to 'b'.
+    expect(Option.map(snapshot(), (state) => state.isPreviousKey)).toStrictEqual(Option.some(true))
+  }).pipe(Effect.provide(TestLayer))
+})

package/src/internal/queryDriver-persist-key.test.ts

@@ -0,0 +1,118 @@
+import { expect, it } from '@effect/vitest'
+import { Effect, Layer, Logger, ManagedRuntime, Option, Schema as S } from 'effect'
+import { AsyncCalc, Engine, State, StateGroup } from '../index'
+import { QueryStore, type QueryStoreApi } from './queryStore'
+import { flush, until } from '../testkit/flight.testkit'
+
+// The persisted cache is the one place a query's answer outlives the process that
+// asked the question, so it is the one place the driver cannot re-derive the input
+// key an entry belongs to — it has to have been written down. `persistCacheKey`
+// (queryDriverPersist.ts:10) writes down whatever `persist.key` says, and the
+// default `persist.key` (asyncCalc.ts, remoteState.ts) is the query's *name*.
+//
+// One slot per definition is the DOCUMENTED contract, not an oversight:
+// remoteState.test.ts pins `persist: true` keying by name, and its neighbour pins
+// the function-key form as the way to get a slot per input key. What follows pins
+// the consequence of that default — because it really does hand one input key's
+// answer to another — and the warning that now says so out loud, so nobody meets it
+// only after a reload paints the wrong row.
+
+const Profile = S.Struct({ chatId: S.String, canWrite: S.Boolean })
+type Profile = S.Schema.Type<typeof Profile>
+
+class ChatId extends State.make('chatId', S.String) {}
+class Inputs extends StateGroup.make(ChatId) {}
+const chatId = StateGroup.select(Inputs, 'chatId')
+
+class ChatProfile extends AsyncCalc.make('persist-key/ChatProfile', {
+  inputs: [chatId],
+  output: Profile,
+  alwaysOn: true,
+}) {}
+
+type PersistTarget = true | { readonly key: (inputs: { readonly chatId: string }) => string }
+
+const answer = ({ chatId: id }: { readonly chatId: string }): Effect.Effect<Profile> =>
+  Effect.succeed({ chatId: id, canWrite: id === 'A' })
+
+// A process boundary in miniature: one `QueryStore` outlives two runtimes. The
+// first asks about A, then about B; the second comes back up asking about A with
+// its query parked, so the only thing that can paint is the cache.
+const acrossSessions = async (persist: PersistTarget) => {
+  const entries = new Map<string, unknown>()
+  const warnings: Array<string> = []
+  const captureWarnings = Logger.replace(
+    Logger.defaultLogger,
+    Logger.make(({ message }) => {
+      warnings.push(String(message))
+    }),
+  )
+  const storeApi: QueryStoreApi = {
+    get: (key) => Effect.sync(() => Option.fromNullable(entries.get(key))),
+    set: (key, value) => Effect.sync(() => void entries.set(key, value)),
+    remove: (key) => Effect.sync(() => void entries.delete(key)),
+  }
+  const session = (query: (inputs: { readonly chatId: string }) => Effect.Effect<Profile>) =>
+    ManagedRuntime.make(
+      AsyncCalc.live(ChatProfile, { query, persist }).pipe(
+        Layer.provideMerge(StateGroup.live(Inputs, { chatId: 'A' })),
+        Layer.provideMerge(Layer.succeed(QueryStore, storeApi)),
+        Layer.provideMerge(Engine),
+        Layer.provideMerge(captureWarnings),
+      ),
+    )
+
+  const first = session(answer)
+  const firstView = await first.runPromise(ChatProfile.store)
+  const source = await first.runPromise(chatId.store)
+  await first.runPromise(
+    until(
+      () => firstView.get(),
+      (view) => view._tag === 'Success' && view.refetching === false,
+    ),
+  )
+  source.set('B')
+  const asked = await first.runPromise(
+    until(
+      () => firstView.get(),
+      (view) => view._tag === 'Success' && view.refetching === false && view.value.chatId === 'B',
+    ),
+  )
+  expect(asked).toMatchObject({ _tag: 'Success', value: { chatId: 'B', canWrite: false } })
+  await first.dispose()
+
+  // Second process. `Effect.never` keeps the fresh answer out of the way, so
+  // whatever shows is exactly what hydration decided to paint.
+  const second = session(() => Effect.never)
+  const secondView = await second.runPromise(ChatProfile.store)
+  await second.runPromise(flush(8))
+  const hydrated = secondView.get()
+  await second.dispose()
+  return { hydrated, slots: [...entries.keys()], warnings }
+}
+
+it('an input-keyed persist target gives each input key its own slot', async () => {
+  const keyed = await acrossSessions({ key: (inputs) => `persist-key/Chat:${inputs.chatId}` })
+  expect(keyed.slots).toHaveLength(2)
+  // A asked, A answered — across a process boundary, from cache alone.
+  expect(keyed.hydrated).toMatchObject({
+    _tag: 'Success',
+    value: { chatId: 'A', canWrite: true },
+    refetching: true,
+  })
+})
+
+it("a shared persist slot hydrates another input key's answer, and says so", async () => {
+  const defaulted = await acrossSessions(true)
+  // One slot for both keys, so B's answer is the last write…
+  expect(defaulted.slots).toEqual(['persist-key/ChatProfile'])
+  // …and the session that asked about A reads it back as its own, `canWrite` and
+  // all. `isPreviousKey` cannot catch this: hydration is a fresh publish in a fresh
+  // process, with nothing left to say which key the payload answered.
+  expect(defaulted.hydrated).toMatchObject({
+    _tag: 'Success',
+    value: { chatId: 'B', canWrite: false },
+  })
+  // Which is why building it warns rather than doing it quietly.
+  expect(defaulted.warnings.join(' ')).toContain('single cache slot')
+})

package/src/internal/queryDriver.persistence-staleness.test.ts

@@ -0,0 +1,209 @@
+import { expect, it } from '@effect/vitest'
+import { Data, Effect, Layer, ManagedRuntime, MutableRef, Schema as S } from 'effect'
+import { AsyncCalc, Engine, forceSync } from '../index'
+import { QueryStore } from './queryStore'
+import { Queries } from '../runtime/queries'
+import { until } from '../testkit/flight.testkit'
+
+// Class bindings deliberately match their registered names: `AsyncCalc.invalidate`
+// looks a query up by `calc.name`, and a class declaration shadows the static the
+// framework installs. That divergence is its own finding, filed separately — these
+// tests keep the names aligned so they isolate the driver, not the lookup.
+
+const isStale = (name: string): Effect.Effect<boolean, never, Queries> =>
+  Effect.map(Queries, (registry) => registry.byName.get(name)?.snapshot().isStale ?? false)
+
+const controlled = <A>() => {
+  const resolver = MutableRef.make<(value: A) => void>(() => {})
+  const promise = new Promise<A>((resume) => {
+    MutableRef.set(resolver, resume)
+  })
+  return { promise, resolve: (value: A) => MutableRef.get(resolver)(value) }
+}
+
+// `localStorage.setItem` raises QuotaExceededError for real, and the shipped
+// `reform-query-browser` store wraps it in a bare `Effect.sync` — so the throw
+// reaches the driver as a defect, exactly like this fake.
+class QuotaExceeded extends Data.TaggedError('QuotaExceeded')<{ readonly key: string }> {}
+
+const throwingWriteQueryStore = () => {
+  const writes = { attempts: 0 }
+  const layer = Layer.succeed(QueryStore, {
+    get: () => Effect.succeedNone,
+    set: (key: string) =>
+      Effect.sync(() => {
+        writes.attempts += 1
+        throw new QuotaExceeded({ key })
+      }),
+    remove: () => Effect.void,
+  })
+  return { writes, layer }
+}
+
+// `persistWriteTo` ends in `Effect.ignore`, which only swallows *typed* failures.
+// A defect walks straight through it, out of `commitSuccess`, and kills the
+// request consumer forked in `makeQueryDriver` — after which nothing drains the
+// request queue and the query can never run again.
+it('a throwing persist write permanently wedges the query consumer', async () => {
+  const persisted = throwingWriteQueryStore()
+  const runs = { n: 0 }
+  class SupersedeWedgedPersistQ extends AsyncCalc.make('SupersedeWedgedPersistQ', {
+    inputs: [],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  const runtime = ManagedRuntime.make(
+    AsyncCalc.live(SupersedeWedgedPersistQ, {
+      query: () =>
+        Effect.sync(() => {
+          runs.n += 1
+          return runs.n
+        }),
+      persist: true,
+    }).pipe(Layer.provideMerge(persisted.layer), Layer.provideMerge(Engine)),
+  )
+  const view = forceSync(() => runtime.runSync(SupersedeWedgedPersistQ.store))
+
+  await runtime.runPromise(
+    until(
+      () => view.get(),
+      (value) => value._tag === 'Success' && value.refetching === false,
+    ),
+  )
+  expect(runs.n).toBe(1)
+  expect(persisted.writes.attempts).toBe(1)
+
+  // The visible write already landed before persistence was attempted, so a
+  // rejected cache write must not be able to take the driver down with it.
+  await runtime.runPromise(AsyncCalc.refetch(SupersedeWedgedPersistQ))
+  await runtime.runPromise(
+    until(
+      () => runs.n,
+      (n) => n >= 2,
+      40,
+    ),
+  )
+  expect(runs.n).toBe(2)
+  expect(view.get()).toMatchObject({ _tag: 'Success', value: 2, refetching: false })
+
+  await runtime.dispose()
+})
+
+// `settleSuccess` clears `isStale` for whatever result lands next, without asking
+// whether that result's generation actually covers the recorded stale cause. The
+// driver's own rule — `hasCoveringRequest = generation > staleAtGeneration` — says
+// generation N does NOT cover a stale mark taken at generation N: that request was
+// already in flight when the invalidation happened, so its answer predates it.
+it('a success from the invalidated generation erases the stale mark', async () => {
+  const fresh = controlled<number>()
+  const runs = { n: 0 }
+  class SupersedeInFlightInvalidateQ extends AsyncCalc.make('SupersedeInFlightInvalidateQ', {
+    inputs: [],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  const runtime = ManagedRuntime.make(
+    AsyncCalc.live(SupersedeInFlightInvalidateQ, {
+      query: () =>
+        Effect.sync(() => {
+          runs.n += 1
+        }).pipe(Effect.zipRight(Effect.promise(() => fresh.promise))),
+    }).pipe(Layer.provideMerge(Engine)),
+  )
+  const view = forceSync(() => runtime.runSync(SupersedeInFlightInvalidateQ.store))
+
+  // No subscriber yet, so `invalidate` records the mark instead of refetching.
+  await runtime.runPromise(
+    until(
+      () => runs.n,
+      (n) => n > 0,
+    ),
+  )
+  await runtime.runPromise(AsyncCalc.invalidate(SupersedeInFlightInvalidateQ))
+  expect(await runtime.runPromise(isStale('SupersedeInFlightInvalidateQ'))).toBe(true)
+
+  fresh.resolve(7)
+  await runtime.runPromise(
+    until(
+      () => view.get(),
+      (value) => value._tag === 'Success' && value.refetching === false,
+    ),
+  )
+  expect(view.get()).toMatchObject({ _tag: 'Success', value: 7, refetching: false })
+
+  // Generation 1's answer was requested before the invalidation, so it cannot
+  // discharge it: the value stays stale and a fresh reader has to revalidate.
+  expect(await runtime.runPromise(isStale('SupersedeInFlightInvalidateQ'))).toBe(true)
+  const off = view.subscribe(() => {})
+  await runtime.runPromise(
+    until(
+      () => runs.n,
+      (n) => n >= 2,
+      40,
+    ),
+  )
+  expect(runs.n).toBe(2)
+  off()
+
+  await runtime.dispose()
+})
+
+// `invalidate` returns early whenever the state is already stale, so it never
+// advances `staleAtGeneration` and never reaches `maybeAutoRefetch`. An
+// invalidation raised while an earlier one's revalidation is still in flight is
+// dropped whole: nothing re-requests, and the in-flight answer — which predates
+// the second invalidation — settles as if it had covered it. This is the path
+// `RefetchOnFocus` takes on every focus event.
+it('invalidate is a no-op while a revalidation it does not cover is in flight', async () => {
+  const runs = MutableRef.make(0)
+  class SupersedeRepeatInvalidateQ extends AsyncCalc.make('SupersedeRepeatInvalidateQ', {
+    inputs: [],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  const runtime = ManagedRuntime.make(
+    AsyncCalc.live(SupersedeRepeatInvalidateQ, {
+      query: () =>
+        Effect.suspend(() => {
+          const attempt = MutableRef.updateAndGet(runs, (count) => count + 1)
+          return attempt === 1 ? Effect.succeed(1) : Effect.never
+        }),
+    }).pipe(Layer.provideMerge(Engine)),
+  )
+  const view = forceSync(() => runtime.runSync(SupersedeRepeatInvalidateQ.store))
+
+  await runtime.runPromise(
+    until(
+      () => view.get(),
+      (value) => value._tag === 'Success' && value.refetching === false,
+    ),
+  )
+  expect(MutableRef.get(runs)).toBe(1)
+
+  // An active reader is what makes `invalidate` refetch rather than only mark.
+  const off = view.subscribe(() => {})
+  await runtime.runPromise(AsyncCalc.invalidate(SupersedeRepeatInvalidateQ))
+  await runtime.runPromise(
+    until(
+      () => MutableRef.get(runs),
+      (n) => n >= 2,
+    ),
+  )
+  expect(MutableRef.get(runs)).toBe(2)
+  expect(await runtime.runPromise(isStale('SupersedeRepeatInvalidateQ'))).toBe(true)
+
+  // Generation 2 was already in flight when this second invalidation arrived, so
+  // it cannot answer it; a third request has to go out.
+  await runtime.runPromise(AsyncCalc.invalidate(SupersedeRepeatInvalidateQ))
+  await runtime.runPromise(
+    until(
+      () => MutableRef.get(runs),
+      (n) => n >= 3,
+      40,
+    ),
+  )
+  expect(MutableRef.get(runs)).toBe(3)
+  off()
+
+  await runtime.dispose()
+})