@playfast/reform 1.2.0 → 1.3.0

package/src/remote/remoteStateMake.ts

@@ -0,0 +1,97 @@
+import { Context, Effect, Schema } from 'effect'
+import type { AsyncData } from '../calc/asyncData'
+import { yieldableClass } from '../definition/definition'
+import * as Event from '../event/event'
+import { type GatedOf, gatedFlag, type QueryCodec } from '../internal/queryDriver'
+import type { Store } from '../internal/store'
+import { readTracked } from '../internal/track'
+import { type AnySource, type SourceCapture, StateToken } from '../state/token'
+import type {
+  FailedIntent,
+  PendingIntent,
+  RemoteStateClass,
+  RemoteStateConfigExternalApi,
+  RemoteStateManifestExternalApi,
+  RemoteStatePendingStore,
+  RemoteStateTruthStore,
+  RemoteStateVisibleStore,
+} from './remoteStateTypes'
+
+// Schema.Unknown is structural because Intents is open at make-time; the declaration preserves its authored payload type.
+export 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>,
+  OutputSchema extends Schema.Schema.AnyNoContext,
+  ErrorSchema extends Schema.Schema.AnyNoContext | undefined = undefined,
+  const AlwaysOn extends boolean = false,
+>(
+  name: N,
+  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<
+    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> = {
+    kind: 'RemoteState',
+    name,
+    output: config.output,
+    gated,
+    intents: config.intents.map((event) => event.tag),
+    ...(config.error !== undefined ? { error: config.error } : {}),
+  }
+  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)
+  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
+}

package/src/remote/remoteStateSend.ts

@@ -0,0 +1,122 @@
+import { Context, Effect, Either, Layer } 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'
+
+export interface IntentEvents<I> {
+  readonly queued: Event.EventClass<string, { readonly opId: string; readonly intent: I }>
+  readonly acked: Event.EventClass<string, { readonly opId: string }>
+  readonly settled: Event.EventClass<string, { readonly opId: string }>
+  readonly invalidated: Event.EventClass<string, {}>
+}
+
+interface QueueReducerOptions<I> {
+  readonly name: string
+  readonly queueTag: Context.Tag<PendingQueue<I>, PendingQueue<I>>
+  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.scopedDiscard(
+    Effect.gen(function* () {
+      const reducers = yield* Reducers
+      if (reducers.entries.some((entry) => entry.name === options.name)) {
+        yield* Effect.logWarning(`reform: duplicate reducer name '${options.name}' registered`)
+      }
+      const queue = yield* options.queueTag
+      const entry: ReducerEntry = {
+        name: options.name,
+        handles: new Set([
+          options.events.queued.tag,
+          options.events.acked.tag,
+          options.events.settled.tag,
+        ]),
+        apply: (event) => {
+          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',
+              })
+            }
+            return
+          }
+          if (handled._tag === options.events.acked.tag) {
+            queue.ack(handled.opId)
+            return
+          }
+          queue.settle(handled.opId)
+        },
+      }
+      yield* Effect.acquireRelease(
+        Effect.sync(() => reducers.register(entry)),
+        () => Effect.sync(() => reducers.unregister(entry)),
+      )
+    }),
+  )
+
+interface SendProcedureOptions<I, R2> {
+  readonly name: string
+  readonly channel: Channel.ChannelClass
+  readonly handles: ReadonlySet<string>
+  readonly linkTag: Context.Tag<SettleLink, SettleLink>
+  readonly failed: Event.EventClass<string, { readonly intent: I; readonly error: unknown }>
+  readonly send: (intent: I) => Effect.Effect<unknown, unknown, R2>
+  readonly events: IntentEvents<I>
+}
+
+export const sendProcedureLayer = <I, R2>(
+  options: SendProcedureOptions<I, R2>,
+): Layer.Layer<never, never, Channel.Procedures | Bus | R2 | SettleLink> =>
+  Layer.scopedDiscard(
+    Effect.gen(function* () {
+      const procedures = yield* Channel.Procedures
+      if (procedures.entries.some((entry) => entry.name === options.name)) {
+        yield* Effect.logWarning(`reform: duplicate procedure name '${options.name}' registered`)
+      }
+      const link = yield* options.linkTag
+      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(options.events.queued, { opId, intent })
+        const outcome = yield* options.send(intent).pipe(
+          Effect.catchAllDefect((defect) => Effect.fail(defect)),
+          Effect.either,
+          Effect.onInterrupt(() => Event.dispatch(options.events.settled, { opId })),
+        )
+        yield* Either.match(outcome, {
+          onLeft: (error) =>
+            Effect.zipRight(
+              Event.dispatch(options.failed, { intent, error }),
+              Event.dispatch(options.events.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(options.events.acked, { opId })),
+              Effect.zipRight(Event.dispatch(options.events.invalidated, {})),
+            ),
+        })
+      })
+      const entry: Channel.ProcedureEntry = {
+        name: options.name,
+        channelName: options.channel.manifest.name,
+        handles: options.handles,
+        run: (event) => Effect.provide(deliver(narrowHandled<I>(event)), runtime),
+      }
+      yield* Effect.acquireRelease(
+        Effect.sync(() => procedures.register(entry)),
+        () => Effect.sync(() => procedures.unregister(entry)),
+      )
+    }),
+  )

package/src/remote/remoteStateTypes.ts

@@ -0,0 +1,155 @@
+import type { Context, Effect, Schema } from 'effect'
+import type { Effect as EffectType } from 'effect/Effect'
+import type { AsyncData, AsyncError, AsyncSuccess } from '../calc/asyncData'
+import type * as Channel from '../channel/channel'
+import type { Manifest } from '../definition/definition'
+import type * as Event from '../event/event'
+import type { QueryCodec } from '../internal/queryDriver'
+import type { InputsObject, InvalidateBy } from '../internal/sources'
+import type { Store } from '../internal/store'
+import type { AnySource, 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
+  readonly intent: I
+  readonly status: 'sending' | 'confirmed'
+}
+
+export interface FailedIntent<I> {
+  readonly intent: I
+  readonly error: unknown
+}
+
+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
+}
+
+export type EventPayload<Ev extends Event.AnyEvent> =
+  Ev extends Event.EventClass<string, infer P> ? P : never
+
+// ExternalApi: optional `intent` only on Queued envelopes.
+export interface QueueFoldEventExternalApi<I> {
+  readonly _tag: string
+  readonly opId: string
+  readonly intent?: I
+}
+
+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
+  readonly output: RemoteStateSchemaReflection
+  readonly error?: RemoteStateSchemaReflection
+  readonly gated: boolean
+  readonly intents: ReadonlyArray<string>
+}
+
+export interface RemoteStateClass<
+  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 EffectType<AsyncData<A, E, Gated>, never, RemoteStateVisibleStore<N>> {
+  new (): {}
+  readonly manifest: RemoteStateManifestExternalApi<N>
+  readonly codec: QueryCodec<A>
+  readonly store: Context.Tag<RemoteStateVisibleStore<N>, Store<AsyncData<A, E, Gated>>>
+  readonly name: N
+  readonly inputs: Inputs
+  readonly intents: Intents
+  readonly gated: Gated
+  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]>>>,
+    RemoteStatePendingStore<N>
+  >
+  readonly Failed: Event.EventClass<`${N}/Failed`, FailedIntent<Event.EventType<Intents[number]>>>
+}
+
+export interface RemoteStateConfigExternalApi<
+  Inputs extends ReadonlyArray<AnySource>,
+  Intents extends ReadonlyArray<Event.AnyEvent>,
+  OutputSchema extends Schema.Schema.AnyNoContext,
+  ErrorSchema extends Schema.Schema.AnyNoContext | undefined,
+  AlwaysOn extends boolean,
+> {
+  readonly inputs: Inputs
+  readonly output: OutputSchema
+  readonly error?: ErrorSchema
+  readonly alwaysOn?: AlwaysOn
+  readonly intents: Intents
+}
+export type RemoteStateLiveExternalApi<
+  Inputs extends ReadonlyArray<AnySource>,
+  Intents extends ReadonlyArray<Event.AnyEvent>,
+  A,
+  E,
+  Gated extends boolean,
+  R,
+  R2,
+  SettledEvent extends Event.AnyEvent,
+> = {
+  readonly query: (inputs: InputsObject<Inputs>) => Effect.Effect<A, E, R>
+  // 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>
+  readonly apply: (value: A, intent: Event.EventType<Intents[number]>) => A
+  readonly channel?: Channel.ChannelClass
+  readonly invalidateBy?: InvalidateBy<Inputs>
+  readonly invalidateOn?: ReadonlyArray<Event.AnyEvent>
+  readonly coalesce?: 'switch' | 'trailing'
+  readonly reuse?: boolean
+  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) }
+} & (Gated extends true
+  ? { readonly disabled?: (inputs: InputsObject<Inputs>) => boolean }
+  : { readonly disabled?: never })
+
+export interface SettleLink {
+  readonly requested: () => number
+  readonly register: (opId: string, waitFor: number) => void
+}
+
+export interface WaiterRegistration {
+  readonly opId: string
+  readonly waitFor: number
+}

package/src/runtime/appRuntime.activation.test.ts

@@ -1,9 +1,10 @@
-import { Context, Duration, Effect, Layer, Option, Schema } from 'effect'
+import { Context, Effect, Layer, Option, Schema } from 'effect'
 import { expect, it } from '@effect/vitest'
 import * as Composition from '../compose/composition'
 import { mount } from '../compose/structure'
 import { ui } from '../compose/ui'
 import { scene } from '../scene/scene'
+import { flush, until } from '../testkit/flight.testkit'
 import { Engine } from './loop'
 import { makeAppRuntime } from './appRuntime'
 
@@ -62,7 +63,10 @@ const makeScene = (probe: ActivationProbeService) =>
     ],
   })
 
-const settle = Effect.sleep(Duration.millis(50))
+// Wait for the count, then quiesce: the exact `toEqual` is what proves no extra
+// acquire/release slipped in behind it.
+const settledAt = (read: () => ReadonlyArray<string>, count: number): Effect.Effect<void> =>
+  until(read, (entries) => entries.length >= count).pipe(Effect.zipRight(flush()))
 
 it.scopedLive(
   'keeps activation lazy, scopes sibling mounts independently, and closes them at teardown',
@@ -85,16 +89,16 @@ it.scopedLive(
         Option.getOrThrow(Composition.activation(service, { id: 'first' })),
       )
       app.mountScoped(Option.getOrThrow(Composition.activation(service, { id: 'second' })))
-      yield* settle
+      yield* settledAt(() => probe.acquired, 2)
       expect(probe.acquired).toEqual(['first', 'second'])
 
       first()
       first()
-      yield* settle
+      yield* settledAt(() => probe.released, 1)
       expect(probe.released).toEqual(['first'])
 
       app.dispose()
-      yield* settle
+      yield* settledAt(() => probe.released, 2)
       expect(probe.released).toEqual(['first', 'second'])
     }),
 )

package/src/runtime/appRuntime.test.ts

@@ -1,4 +1,4 @@
-import { Context, Duration, Effect, Layer, Option, Schema as S } from 'effect'
+import { Context, Effect, Layer, Option, Schema as S } from 'effect'
 import { expect, it } from '@effect/vitest'
 import * as Composition from '../compose/composition'
 import { provide } from '../compose/provide'
@@ -11,6 +11,7 @@ import { featureModule } from '../feature/feature'
 import * as Reducer from '../reducer/reducer'
 import { scene } from '../scene/scene'
 import * as State from '../state/state'
+import { until } from '../testkit/flight.testkit'
 import { Engine, Reducers } from './loop'
 import { makeAppRuntime } from './appRuntime'
 
@@ -72,7 +73,6 @@ const rootScene = () =>
     ],
   })
 
-const settle = Effect.sleep(Duration.millis(50))
 const appRuntime = Effect.acquireRelease(
   Effect.sync(() => makeAppRuntime(rootScene())),
   (app) => Effect.sync(() => app.dispose()),
@@ -135,8 +135,29 @@ it.scopedLive(
       })
       // Same-tick dispose (the StrictMode cleanup shape): the fork has not run yet.
       dispose()
-      yield* settle
+      // A probe mount forked behind the cancelled one: once it is live, the
+      // cancelled fork's turn has provably passed.
+      const probe = { live: 0, failed: 0 }
+      const disposeProbe = app.mountFeature(CounterNative.binding, {
+        onLive: () => {
+          probe.live += 1
+        },
+        onFailed: () => {
+          probe.failed += 1
+        },
+      })
+      yield* until(
+        () => probe.live + probe.failed,
+        (n) => n > 0,
+      )
       expect(calls).toEqual({ live: 0, failed: 0 })
+      expect(app.read(Reducers).entries.length).toBe(baseline + 1)
+
+      disposeProbe()
+      yield* until(
+        () => app.read(Reducers).entries.length,
+        (n) => n === baseline,
+      )
       expect(app.read(Reducers).entries.length).toBe(baseline)
       expect(app.read(Reducers).byTag.get('appRuntime.Tick')).toBeUndefined()
     }),
@@ -157,14 +178,17 @@ it.scopedLive(
           calls.failed += 1
         },
       })
-      yield* Effect.sleep(Duration.millis(1)).pipe(
-        Effect.repeat({ until: () => calls.live === 1 }),
-        Effect.timeout(Duration.seconds(2)),
+      yield* until(
+        () => calls.live,
+        (n) => n === 1,
       )
       expect(calls).toEqual({ live: 1, failed: 0 })
       expect(app.read(Reducers).entries.length).toBe(baseline + 1)
       dispose()
-      yield* settle
+      yield* until(
+        () => app.read(Reducers).entries.length,
+        (n) => n === baseline,
+      )
       expect(app.read(Reducers).entries.length).toBe(baseline)
     }),
 )
@@ -190,9 +214,9 @@ it.scopedLive('a nested Feature mounts against its immediate parent context', ()
         },
       }),
     )
-    yield* Effect.sleep(Duration.millis(1)).pipe(
-      Effect.repeat({ until: () => observed.length > 0 }),
-      Effect.timeout(Duration.seconds(2)),
+    yield* until(
+      () => observed.length,
+      (n) => n > 0,
     )
     expect(observed).toEqual(['from-parent'])
   }),
@@ -219,9 +243,9 @@ it.scopedLive(
         },
       })
       yield* Effect.addFinalizer(() => Effect.sync(dispose))
-      yield* Effect.sleep(Duration.millis(1)).pipe(
-        Effect.repeat({ until: () => observed.length > 0 }),
-        Effect.timeout(Duration.seconds(2)),
+      yield* until(
+        () => observed.length,
+        (n) => n > 0,
       )
       expect(observed).toEqual(['from-parent'])
     }),
@@ -240,9 +264,9 @@ it.scopedLive(
         onLive: () => observed.push('live'),
       })
       yield* Effect.addFinalizer(() => Effect.sync(dispose))
-      yield* Effect.sleep(Duration.millis(1)).pipe(
-        Effect.repeat({ until: () => observed.length > 0 }),
-        Effect.timeout(Duration.seconds(2)),
+      yield* until(
+        () => observed.length,
+        (n) => n > 0,
       )
       expect(observed).toEqual(['failed'])
     }),