@playfast/reform 1.2.1 → 1.4.0

package/src/runtime/loop.ts

@@ -14,6 +14,10 @@ export interface ReducerEntry {
 }
 
 export interface ReducerRegistry {
+  // Captured where the drain captures it, so the synchronous trigger path and the
+  // drain report to the same profiler even though triggers are built later, at mount,
+  // outside the scene's `Layer.locally(CurrentInstrumentation, ...)` scope.
+  readonly instrumentation: Instrumentation
   readonly entries: Array<ReducerEntry>
   readonly byName: Map<string, Set<ReducerEntry>>
   readonly byTag: Map<string, Set<ReducerEntry>>
@@ -38,7 +42,7 @@ const dropFromBuckets = <T>(map: Map<string, Set<T>>, key: string, target: T): v
   }
 }
 
-const makeReducerRegistry = (): ReducerRegistry => {
+const makeReducerRegistry = (instrumentation: Instrumentation): ReducerRegistry => {
   const entries = new Set<ReducerEntry>()
   const byName = new Map<string, Set<ReducerEntry>>()
   const byTag = new Map<string, Set<ReducerEntry>>()
@@ -47,6 +51,7 @@ const makeReducerRegistry = (): ReducerRegistry => {
     value: Option.some([]),
   }
   return {
+    instrumentation,
     get entries() {
       return Option.getOrElse(snapshot.value, () => {
         const current = Array.from(entries)
@@ -108,7 +113,26 @@ const isolateApply = (
   )
 }
 
-export const reducersLayer: Layer.Layer<Reducers> = Layer.sync(Reducers, makeReducerRegistry)
+export interface ApplyReducersInput {
+  readonly registry: ReducerRegistry
+  readonly event: Tagged
+}
+
+export interface ReducerFailure {
+  readonly event: Tagged
+  readonly error: unknown
+}
+
+/** Run every reducer registered for one event. A defect in one must not skip the rest. */
+export const applyReducers = (input: ApplyReducersInput): ReadonlyArray<ReducerFailure> =>
+  Arr.filterMap(input.registry.tagged(input.event._tag), (reducer) =>
+    isolateApply(reducer, input.event, input.registry.instrumentation),
+  )
+
+export const reducersLayer: Layer.Layer<Reducers> = Layer.effect(
+  Reducers,
+  Effect.map(resolveInstrumentation, makeReducerRegistry),
+)
 
 // Partitioning keeps dispatch order stable within each priority.
 const rank = (priority: Envelope['priority']): number => (priority === 'High' ? 0 : 1)
@@ -145,10 +169,9 @@ const drain = Effect.gen(function* () {
             instrumentation.eventDispatched(envelope.event._tag, envelope.priority),
           )
           const collected = Arr.flatMap(ordered, (envelope) =>
-            // A reducer defect must not abandon the remaining frame.
-            Arr.filterMap(reducers.tagged(envelope.event._tag), (reducer) =>
-              isolateApply(reducer, envelope.event, instrumentation),
-            ),
+            envelope.reduced
+              ? []
+              : applyReducers({ registry: reducers, event: envelope.event }),
           )
           ordered.forEach((envelope) => {
             // channelsFor is distinct; per-procedure offers would double-run shared channels.

package/src/runtime/mount-inflight-ownership.test.ts

@@ -0,0 +1,361 @@
+import { Context, Deferred, Effect, Layer, Option } from 'effect'
+import { expect, it, test } from '@effect/vitest'
+import * as Composition from '../compose/composition'
+import { provide } from '../compose/provide'
+import { mount } from '../compose/structure'
+import * as Ui from '../compose/ui'
+import { ui } from '../compose/ui'
+import * as Feature from '../feature/feature'
+import { featureModule } from '../feature/feature'
+import { scene } from '../scene/scene'
+import { makeScheduler } from '../internal/scheduler'
+import { flush, until } from '../testkit/flight.testkit'
+import { Engine } from './loop'
+import { makeAppRuntime } from './appRuntime'
+
+/**
+ * Round-5 adversarial audit — `reform`'s half of the mount-ownership /
+ * scheduler fix set.
+ *
+ * Under audit:
+ *   * `runtime/featureMount.ts` `forkMountScope` / `startMount` — a mount whose
+ *     owner scope has already closed is refused.
+ *   * `runtime/capturedAppRuntime.ts` — every mount is forked from one parallel
+ *     `rootScope`.
+ *   * `internal/scheduler.ts` `isLive` — flush-time membership.
+ *
+ * Only findings that survived an attempt to refute them are filed. Each test
+ * states the behaviour the FIXED code is supposed to have, fails on the current
+ * working tree, and carries a passing CONTROL in the same body. Every handler is
+ * attached before anything is awaited; nothing waits a fixed duration.
+ */
+
+// `until`'s poll budget, same as the round-4 hunt: 40 rounds x 10ms.
+const ROUNDS = 40
+
+// ---------------------------------------------------------------------------
+// Shared scene / feature definitions
+// ---------------------------------------------------------------------------
+
+interface LifecycleProbeService {
+  readonly acquired: Array<string>
+  readonly released: Array<string>
+}
+
+const LifecycleProbeBase: Context.TagClass<
+  LifecycleProbe,
+  'audit5.LifecycleProbe',
+  LifecycleProbeService
+> = Context.Tag('audit5.LifecycleProbe')<LifecycleProbe, LifecycleProbeService>()
+class LifecycleProbe extends LifecycleProbeBase {}
+
+const makeProbe = (): LifecycleProbeService => ({ acquired: [], released: [] })
+
+class AuditUi extends ui('audit5.AuditUi')<{ props: {} }>() {}
+class AuditComp extends Composition.make('audit5.AuditComp', {
+  title: 'Audit',
+  ui: AuditUi,
+})<AuditComp>() {}
+const AuditLive = Composition.live(AuditComp, function* () {
+  return mount({ props: {}, slots: {} })
+})
+
+class AuditRootUi extends ui('audit5.AuditRootUi')<{ props: {} }>() {}
+class AuditRootComp extends Composition.make('audit5.AuditRootComp', {
+  title: 'AuditRoot',
+  ui: AuditRootUi,
+})<AuditRootComp>() {}
+const AuditRootLive = Composition.live(AuditRootComp, function* () {
+  return mount({ props: {}, slots: {} })
+})
+
+const auditRootViews = AuditRootLive.pipe(
+  Layer.provideMerge(
+    provide(
+      AuditRootUi,
+      Ui.make(AuditRootUi, () => null),
+    ),
+  ),
+)
+
+const auditScene = (probe: LifecycleProbeService) =>
+  scene(AuditRootComp, {
+    provide: [
+      auditRootViews.pipe(
+        Layer.provideMerge(Layer.succeed(LifecycleProbe, probe)),
+        Layer.provideMerge(Engine),
+      ),
+    ],
+  })
+
+// A scoped marker: `acquired` records that the layer built, `released` that its
+// scope closed.
+const scopedMark = (label: string): Layer.Layer<never, never, LifecycleProbe> =>
+  Layer.scopedDiscard(
+    Effect.gen(function* () {
+      const probe = yield* LifecycleProbe
+      yield* Effect.acquireRelease(
+        Effect.sync(() => probe.acquired.push(label)),
+        () => Effect.sync(() => probe.released.push(label)),
+      )
+    }),
+  )
+
+// The same marker, but the module parks BEFORE it acquires anything: a module
+// that awaits a socket, a config fetch, a lazy `import()`, a DB handshake. The
+// mount is in flight and owns nothing yet.
+const gatedMark = (
+  label: string,
+  gate: Deferred.Deferred<void>,
+): Layer.Layer<never, never, LifecycleProbe> =>
+  Layer.scopedDiscard(
+    Effect.gen(function* () {
+      const probe = yield* LifecycleProbe
+      yield* Deferred.await(gate)
+      yield* Effect.acquireRelease(
+        Effect.sync(() => probe.acquired.push(label)),
+        () => Effect.sync(() => probe.released.push(label)),
+      )
+    }),
+  )
+
+const runOption = (candidate: Option.Option<() => void>): void =>
+  Option.match(candidate, { onNone: () => undefined, onSome: (run) => run() })
+
+// ---------------------------------------------------------------------------
+// FINDING 3 — `runtime/featureMount.ts:96-125`.
+//
+// `forkMountScope` refuses a mount whose owner is closed AT FORK TIME, and the
+// doc comment states the contract absolutely: "A mount reported live over
+// finalized services is worse than no mount, so that case is refused."
+//
+// The probe is a snapshot, and the thing it guards is not synchronous. The mount
+// runs on `host.runFork`, which is `ManagedRuntime.runFork` — always deferred,
+// because it must first await the runtime effect. Nothing on the mount path
+// registers the mount fiber with the scope it was forked from, so once the fork
+// has happened the owner closing NO LONGER stops the mount: the mount scope is
+// closed underneath the running fiber, `Layer.build` against a closed scope
+// still succeeds (`Scope.addFinalizer` on a closed scope runs the finalizer
+// there and then), and `onLive` is called with a context whose finalizers have
+// already run — the exact outcome the comment says is refused, reached by the
+// other ordering of the same two events.
+//
+// The window is not a microtask: it is however long the mount takes. Any module
+// that awaits anything — a lazy `import()`, a socket, a config read — holds it
+// open across a whole route change or panel close.
+//
+// A fix that closes it: register the mount fiber with the scope it is forked
+// from (`Scope.addFinalizer(scope, Fiber.interrupt(fiber))`) so closing the
+// owner interrupts an in-flight mount. `forkFeatureMount` already treats
+// `Cause.isInterruptedOnly` as cancellation, so that path stays silent — no
+// `onLive`, no `onFailed`, and nothing acquired.
+// ---------------------------------------------------------------------------
+
+class OwnerFeature extends Feature.make('audit5.owner', {
+  composition: AuditComp,
+  module: featureModule([LifecycleProbe], Layer.merge(AuditLive, scopedMark('owner'))),
+}) {}
+const OwnerNative = Feature.tree<typeof OwnerFeature>(OwnerFeature.token)
+
+class ControlChildFeature extends Feature.make('audit5.controlChild', {
+  composition: AuditComp,
+  module: featureModule([LifecycleProbe], Layer.merge(AuditLive, scopedMark('control-child'))),
+}) {}
+const ControlChildNative = Feature.tree<typeof ControlChildFeature>(ControlChildFeature.token)
+
+const inFlightFeature = (gate: Deferred.Deferred<void>) =>
+  class InFlightChildFeature extends Feature.make('audit5.inFlightChild', {
+    composition: AuditComp,
+    module: featureModule(
+      [LifecycleProbe],
+      Layer.merge(AuditLive, gatedMark('in-flight-child', gate)),
+    ),
+  }) {}
+
+it.scopedLive(
+  'a feature mount whose owner scope closes while it is still in flight is not reported live',
+  () =>
+    Effect.gen(function* () {
+      const probe = makeProbe()
+      const app = makeAppRuntime(auditScene(probe))
+      yield* Effect.addFinalizer(() => Effect.sync(() => app.dispose()))
+
+      const gate = yield* Deferred.make<void>()
+      const InFlightChild = inFlightFeature(gate)
+      const InFlightChildNative = Feature.tree<typeof InFlightChild>(InFlightChild.token)
+
+      // Every handler attached before anything is awaited.
+      const owner = { live: 0, failed: 0 }
+      const control = { live: 0, failed: 0 }
+      const inFlight = { live: 0, failed: 0 }
+      const mounts = {
+        control: Option.none<() => void>(),
+        inFlight: Option.none<() => void>(),
+      }
+
+      const disposeOwner = app.mountFeature(OwnerNative.binding, {
+        onLive: (ownerRuntime) => {
+          owner.live += 1
+          mounts.control = Option.some(() => {
+            ownerRuntime.mountFeature(ControlChildNative.binding, {
+              onLive: () => {
+                control.live += 1
+              },
+              onFailed: () => {
+                control.failed += 1
+              },
+            })
+          })
+          mounts.inFlight = Option.some(() => {
+            ownerRuntime.mountFeature(InFlightChildNative.binding, {
+              onLive: () => {
+                inFlight.live += 1
+              },
+              onFailed: () => {
+                inFlight.failed += 1
+              },
+            })
+          })
+        },
+        onFailed: () => {
+          owner.failed += 1
+        },
+      })
+
+      yield* until(
+        () => owner.live + owner.failed,
+        (n) => n >= 1,
+        ROUNDS,
+      )
+      expect(owner).toEqual({ live: 1, failed: 0 })
+
+      // ---- CONTROL — the same handle, the same mount path, a module that does
+      // not park. It goes live, acquires, and holds its resource. This proves the
+      // scene, the probe, the child-mount path and the handle all work.
+      runOption(mounts.control)
+      yield* until(
+        () => control.live + control.failed,
+        (n) => n >= 1,
+        ROUNDS,
+      )
+      expect(control).toEqual({ live: 1, failed: 0 })
+      expect(probe.acquired).toContain('control-child')
+      expect(probe.released).toEqual([])
+
+      // ---- THE DEFECT — start a mount whose module parks before it acquires
+      // anything, so the mount is genuinely in flight and owns nothing yet...
+      runOption(mounts.inFlight)
+      yield* flush()
+      expect(probe.acquired).not.toContain('in-flight-child')
+
+      // ...then close the owner. Its scope, and every mount scope forked from it,
+      // is now closed — including the in-flight one.
+      disposeOwner()
+      yield* until(
+        () => probe.released.length,
+        (n) => n >= 2,
+        ROUNDS,
+      )
+      yield* flush()
+      expect(probe.released.slice().sort()).toEqual(['control-child', 'owner'])
+
+      // The module finishes what it was waiting for, after its owner is gone.
+      yield* Deferred.succeed(gate, undefined)
+      yield* until(
+        () => inFlight.live + inFlight.failed + probe.acquired.length,
+        (n) => n >= 3,
+        ROUNDS,
+      )
+      yield* flush()
+
+      // A mount the runtime can no longer own must not acquire resources it
+      // releases in the same breath...
+      // Actual today: 'in-flight-child' appears in BOTH lists — acquired against
+      // an already-closed scope, so its finalizer ran at the instant it was added.
+      expect(probe.acquired).not.toContain('in-flight-child')
+      // ...and must not be reported live over them.
+      // Actual today: 1.
+      expect(inFlight.live).toBe(0)
+    }),
+)
+
+// ---------------------------------------------------------------------------
+// FINDING 4 — `internal/scheduler.ts:36-37`.
+//
+//     const isLive = (queued, listener) =>
+//       Predicate.isSet(queued.source) ? queued.source.has(listener)
+//                                      : queued.members.includes(listener)
+//
+// Round-3 established the invariant the code still states one comment further
+// down: "a listener that has since unsubscribed must not be woken". Round-4
+// found that re-reading a ONE-SHOT iterable drops every wake, and round-5 fixed
+// that by keeping a schedule-time snapshot. But the new answer for "anything
+// that is not a Set" is the snapshot for ALL non-Set sources, including the ones
+// that are perfectly re-readable — an `Array`, or any custom collection a
+// first-party Source keeps its subscribers in.
+//
+// `Scheduler` is exported from `@playfast/reform/internal` as part of the
+// primitive-authoring toolkit and its parameter is typed `Iterable<() => void>`,
+// so an Array-backed subscriber list is a supported caller. For that caller the
+// round-3 invariant silently no longer holds: an earlier listener in the same
+// flush can tear a later one down — a scope closing, a family key forgotten, a
+// composition unmounting — and the torn-down listener is woken anyway, reading a
+// store whose finalizers have run.
+//
+// The distinction the code needs is re-readable vs one-shot, not Set vs
+// everything else: `Predicate.isSet(source) || Array.isArray(source)` re-reads,
+// everything else falls back to the snapshot.
+//
+// No in-repo caller passes a mutable non-Set today — `store.ts`, `pendingQueue`,
+// `stateFamily` and `reform-profiler/recorder` all pass Sets, and `boundary`,
+// `event` and `remoteState` pass single-element array LITERALS, which are never
+// mutated and so behave identically either way. This is a latent SPI regression,
+// filed at that severity.
+// ---------------------------------------------------------------------------
+
+const drainMicrotasks = async (turns = 5): Promise<void> => {
+  await Array.from({ length: turns }).reduce<Promise<void>>(
+    (chain) => chain.then(() => new Promise<void>((resolve) => queueMicrotask(resolve))),
+    Promise.resolve(),
+  )
+}
+
+test('scheduler: a listener dropped from a re-readable source mid-flush is not woken', async () => {
+  // ---- CONTROL — a Set source. `first` unsubscribes `second` while the flush is
+  // running and `second` is correctly dropped. Same scheduler, same two
+  // listeners, same mutation: only the container type differs.
+  const controlScheduler = makeScheduler()
+  const controlWoken: Array<string> = []
+  const controlSource = new Set<() => void>()
+  const controlSecond = (): void => {
+    controlWoken.push('second')
+  }
+  const controlFirst = (): void => {
+    controlWoken.push('first')
+    controlSource.delete(controlSecond)
+  }
+  controlSource.add(controlFirst)
+  controlSource.add(controlSecond)
+
+  // ---- DEFECT — an Array source, re-readable, mutated exactly the same way by
+  // exactly the same listener.
+  const scheduler = makeScheduler()
+  const woken: Array<string> = []
+  const source: Array<() => void> = []
+  const second = (): void => {
+    woken.push('second')
+  }
+  const first = (): void => {
+    woken.push('first')
+    source.splice(source.indexOf(second), 1)
+  }
+  source.push(first, second)
+
+  controlScheduler.schedule(controlSource)
+  scheduler.schedule(source)
+  await drainMicrotasks()
+
+  expect(controlWoken).toEqual(['first'])
+  // Actual today: ['first', 'second'] — the unsubscribed listener is woken.
+  expect(woken).toEqual(['first'])
+})