@playfast/reform 1.3.0 → 1.4.0

package/src/calc/asyncCalcTypes.ts

@@ -109,6 +109,11 @@ export type AsyncCalcLive<
   readonly coalesce?: 'switch' | 'trailing'
   // oxlint-disable-next-line reform-rules/no-optional-fields -- caller-omitted option built at the asyncCalc/remoteState construction site; Option<T> would change that call shape
   readonly reuse?: boolean
+  // Keep showing the previous key's result while the new key loads. Off by default:
+  // a retained payload is not an answer to the key being asked. Turn it on only when
+  // the payload is displayed, never when fields are read off it.
+  // oxlint-disable-next-line reform-rules/no-optional-fields -- caller-omitted option built at the asyncCalc/remoteState construction site; Option<T> would change that call shape
+  readonly keepPreviousData?: boolean
   // oxlint-disable-next-line reform-rules/no-optional-fields -- caller-omitted option built at the asyncCalc/remoteState construction site; Option<T> would change that call shape
   readonly persist?:
     | boolean
@@ -133,6 +138,7 @@ export interface AsyncCalcLiveView<Inputs extends ReadonlyArray<AnySource>, A, E
   readonly disabled?: (inputs: InputsObject<Inputs>) => boolean
   readonly coalesce?: 'switch' | 'trailing'
   readonly reuse?: boolean
+  readonly keepPreviousData?: boolean
   readonly persist?:
     | boolean
     | { readonly key?: string | ((inputs: InputsObject<Inputs>) => string) }

package/src/calc/calcFamily.ts

@@ -7,6 +7,7 @@ import {
   sameKey,
   wireSources,
 } from '../internal/sources'
+import { makeKeyCanonicalizer } from '../internal/familyKeys'
 import { resolveScheduler } from '../internal/scheduler'
 import { resolveInstrumentation, stateUpdateHook } from '../runtime/instrumentation'
 import { reuse } from '../internal/reuse'
@@ -14,6 +15,7 @@ import { makeDerivedStore, type Store } from '../internal/store'
 import { readTracked } from '../internal/track'
 import { type FamilyOptions, type FamilyStore } from '../state/stateFamily'
 import { type AnySource } from '../state/token'
+import { microtask } from '../internal/platform'
 
 export interface CalcFamilySchemaReflection {
   readonly ast: Schema.Schema<unknown, unknown, unknown>['ast']
@@ -111,8 +113,39 @@ export const live = <N extends string, Inputs extends ReadonlyArray<AnySource>,
       const onOutputChange = stateUpdateHook(instrumentation, family.manifest.name)
       const sources = yield* wireSources(family.inputs, options.invalidateBy)
       const entries = new Map<K, { readonly store: Store<Out>; readonly unsubscribe: () => void }>()
+      const keys = makeKeyCanonicalizer<K>()
       const evictWhenUnused = options.evictWhenUnused === true
-      const subscribers = new Map<K, number>()
+      // Stamps identify a member *instance*, not a key: `forget` lets one key hold a
+      // succession of members, and a stale unsubscribe from an earlier one must not
+      // decrement — or evict — the one that replaced it.
+      const stamps = new Map<K, number>()
+      const nextStamp = MutableRef.make(0)
+
+      // A forgotten key's member is orphaned — `at(key)` mints a fresh one — so its
+      // subscribers must be woken to re-read, or they hold a store nothing recomputes
+      // again and never hear about the key another way.
+      const wakers = new Map<K, Set<() => void>>()
+      const wakersFor = (key: K): Set<() => void> => {
+        const existing = wakers.get(key)
+        if (existing !== undefined) {
+          return existing
+        }
+        const created = new Set<() => void>()
+        wakers.set(key, created)
+        return created
+      }
+      const wakeable = (key: K, store: Store<Out>): Store<Out> => ({
+        ...store,
+        subscribe: (listener) => {
+          const registered = wakersFor(key)
+          registered.add(listener)
+          const off = store.subscribe(listener)
+          return () => {
+            registered.delete(listener)
+            off()
+          }
+        },
+      })
 
       const dropEntry = (key: K): void => {
         const entry = entries.get(key)
@@ -120,7 +153,13 @@ export const live = <N extends string, Inputs extends ReadonlyArray<AnySource>,
           entry.unsubscribe()
         }
         entries.delete(key)
-        subscribers.delete(key)
+        stamps.delete(key)
+        keys.release(key)
+        const woken = wakers.get(key)
+        wakers.delete(key)
+        if (woken !== undefined && woken.size > 0) {
+          scheduler.schedule(woken)
+        }
       }
 
       const createMember = (
@@ -148,51 +187,59 @@ export const live = <N extends string, Inputs extends ReadonlyArray<AnySource>,
         return makeDerivedStore(recompute, sources.subscribe, scheduler, onOutputChange)
       }
 
-      const refCounted = (key: K, store: Store<Out>): Store<Out> => ({
-        ...store,
-        subscribe: (listener) => {
-          const priorCount = subscribers.get(key)
-          subscribers.set(key, (priorCount === undefined ? 0 : priorCount) + 1)
-          const off = store.subscribe(listener)
-          const released = { done: false }
-          return () => {
-            if (released.done) {
-              return
-            }
-            released.done = true
-            off()
-            const remaining = (subscribers.get(key) ?? 1) - 1
-            if (remaining > 0) {
-              subscribers.set(key, remaining)
-              return
-            }
-            subscribers.delete(key)
-            queueMicrotask(() => {
-              const liveCount = subscribers.get(key)
-              if (liveCount === undefined || liveCount === 0) {
-                dropEntry(key)
+      const refCounted = (key: K, store: Store<Out>, stamp: number): Store<Out> => {
+        const count = MutableRef.make(0)
+        return {
+          ...store,
+          subscribe: (listener) => {
+            MutableRef.update(count, (current) => current + 1)
+            const off = store.subscribe(listener)
+            const released = { done: false }
+            return () => {
+              if (released.done) {
+                return
               }
-            })
-          }
-        },
-      })
+              released.done = true
+              off()
+              MutableRef.update(count, (current) => Math.max(0, current - 1))
+              if (MutableRef.get(count) > 0) {
+                return
+              }
+              microtask(() => {
+                // Still unused, and still the member this key holds.
+                if (MutableRef.get(count) === 0 && stamps.get(key) === stamp) {
+                  dropEntry(key)
+                }
+              })
+            }
+          },
+        }
+      }
 
       const familyStore: FamilyStore<K, Out> = {
-        at: (key) => {
+        at: (rawKey) => {
+          const key = keys.canonical(rawKey)
           const existing = entries.get(key)
           if (existing !== undefined) {
             return existing.store
           }
           const member = createMember(key)
-          const created = evictWhenUnused
-            ? { store: refCounted(key, member.store), unsubscribe: member.unsubscribe }
-            : member
+          const stamp = MutableRef.updateAndGet(nextStamp, (current) => current + 1)
+          const created = {
+            store: wakeable(
+              key,
+              evictWhenUnused ? refCounted(key, member.store, stamp) : member.store,
+            ),
+            unsubscribe: member.unsubscribe,
+          }
           entries.set(key, created)
+          stamps.set(key, stamp)
           return created.store
         },
-        forget: dropEntry,
+        forget: (key) => dropEntry(keys.canonical(key)),
         clear: () => {
           ;[...entries.keys()].forEach((key) => dropEntry(key))
+          keys.reset()
         },
         size: () => entries.size,
       }

package/src/calc/family-identity.test.ts

@@ -0,0 +1,231 @@
+/**
+ * Bug hunt — `CalcFamily.live`'s per-member lifecycle (`calc/calcFamily.ts`).
+ *
+ * `StateFamily` treats a family key as holding a *succession* of store
+ * instances. `state/stateFamily.ts` stamps each instance so "a stale
+ * unsubscribe from an earlier one must not decrement — or evict — the one that
+ * replaced it", and wakes a forgotten key's subscribers so they do not "hold a
+ * store nothing writes to again and never hear about the key another way".
+ *
+ * `CalcFamily.live` re-implements that same lifecycle — its `subscribers:
+ * Map<K, number>` / `remaining` / `queueMicrotask` block is line-for-line what
+ * `stateFamily.ts` looked like before those two guards were added — and it got
+ * neither. The ref-count is credited to the KEY, not to the instance that
+ * earned it, and `dropEntry` severs a member's upstream subscription without
+ * telling the listeners still attached to it.
+ *
+ * Both tests run the *working* half of the same scenario first, in the same
+ * body, so a failure cannot be blamed on the harness. Every listener is
+ * attached before anything is awaited. Neither test waits a duration: `flush`
+ * drains microtask turns, which is the exact lane the scheduler and the
+ * eviction `queueMicrotask` both run on.
+ */
+import { expect, it } from '@effect/vitest'
+import { Data, Effect, Equal, Layer, Schema as S } from 'effect'
+import {
+  CalcFamily,
+  Engine,
+  Event,
+  publish,
+  Reducer,
+  State,
+  StateFamily,
+  StateGroup,
+} from '../index'
+import { flush, until } from '../testkit/flight.testkit'
+
+const Board = S.Record({ key: S.String, value: S.Number })
+
+// ---------------------------------------------------------------------------
+// FINDING 1 — `calc/calcFamily.ts:115` + `:151-178`: the eviction ref-count is credited
+// to the KEY, not to the store instance that earned it.
+//
+// `subscribers: Map<K, number>` is shared by every store a key ever holds, and
+// `dropEntry` deletes the key's slot outright. So once `forget(key)` has minted
+// a replacement, the *forgotten* member's release decrements — and then evicts —
+// the live replacement, tearing down its upstream subscription. That is exactly
+// the hazard `stateFamily.ts` closes with per-instance counts + `stamps`.
+// ---------------------------------------------------------------------------
+it.live('calcFamily: a forgotten member stale release evicts its live replacement', () => {
+  class Feed extends State.make('hunt-evict-feed', Board) {}
+  class Inputs extends StateGroup.make(Feed) {}
+  class Slice extends CalcFamily.make('HuntEvictSlice', {
+    key: S.String,
+    inputs: [StateGroup.select(Inputs, 'hunt-evict-feed')],
+    output: S.Number,
+  }) {}
+  const SliceLive = CalcFamily.live(
+    Slice,
+    (key) =>
+      ({ 'hunt-evict-feed': feed }) =>
+        feed[key] ?? 0,
+    { evictWhenUnused: true },
+  )
+  const TestLayer = SliceLive.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { 'hunt-evict-feed': { control: 1, victim: 1 } })),
+  )
+
+  return Effect.gen(function* () {
+    const feed = yield* StateGroup.select(Inputs, 'hunt-evict-feed').store
+    const family = yield* Slice.store
+    const wakes = { control: 0, victim: 0 }
+
+    // CONTROL — key `control`: subscribe, forget, subscribe the replacement.
+    // The forgotten subscription's release is simply never called, so nothing
+    // stale is in play.
+    family.at('control').subscribe(() => {})
+    family.forget('control')
+    family.at('control').subscribe(() => {
+      wakes.control += 1
+    })
+
+    // DEFECT — key `victim`: the identical sequence, except the forgotten
+    // member's release runs after the replacement is already live.
+    const staleRelease = family.at('victim').subscribe(() => {})
+    family.forget('victim')
+    family.at('victim').subscribe(() => {
+      wakes.victim += 1
+    })
+    staleRelease()
+
+    yield* flush()
+    const membersAfterStaleRelease = family.size()
+
+    feed.set({ control: 2, victim: 2 })
+    yield* flush()
+
+    // The control proves the harness: forget + re-subscribe keeps a live member.
+    expect(wakes.control).toBe(1)
+    // Observed 1: only `control` survived — the stale release dropped `victim`.
+    expect(membersAfterStaleRelease).toBe(2)
+    // Observed 0: `victim`'s live subscriber is never woken again.
+    expect(wakes.victim).toBe(1)
+  }).pipe(Effect.provide(TestLayer))
+})
+
+// ---------------------------------------------------------------------------
+// FINDING 2 — `calc/calcFamily.ts:117-124`: `dropEntry` orphans a member's
+// subscribers silently.
+//
+// `forget(key)` severs the member's upstream subscription and drops it from
+// `entries`, but never wakes the listeners still attached to that store. They
+// keep a handle whose `getVersion()` can never move again — and that version is
+// exactly what `@playfast/reform-react`'s `Compose` compares to decide whether
+// to repaint — so the view shows a value that is no longer true, permanently.
+// `stateFamily.ts` wakes a forgotten key's subscribers for precisely this reason.
+// ---------------------------------------------------------------------------
+it.live('calcFamily: forget silently orphans a member subscribers', () => {
+  class Feed extends State.make('hunt-orphan-feed', Board) {}
+  class Inputs extends StateGroup.make(Feed) {}
+  class Slice extends CalcFamily.make('HuntOrphanSlice', {
+    key: S.String,
+    inputs: [StateGroup.select(Inputs, 'hunt-orphan-feed')],
+    output: S.Number,
+  }) {}
+  const SliceLive = CalcFamily.live(
+    Slice,
+    (key) =>
+      ({ 'hunt-orphan-feed': feed }) =>
+        feed[key] ?? 0,
+  )
+  const TestLayer = SliceLive.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { 'hunt-orphan-feed': { control: 1, orphan: 1 } })),
+  )
+
+  return Effect.gen(function* () {
+    const feed = yield* StateGroup.select(Inputs, 'hunt-orphan-feed').store
+    const family = yield* Slice.store
+    const wakes = { control: 0, orphan: 0 }
+
+    family.at('control').subscribe(() => {
+      wakes.control += 1
+    })
+    family.at('orphan').subscribe(() => {
+      wakes.orphan += 1
+    })
+
+    // CONTROL — both members are live, and both wake on a shared-input move.
+    feed.set({ control: 2, orphan: 2 })
+    yield* flush()
+    expect(wakes.control).toBe(1)
+    expect(wakes.orphan).toBe(1)
+
+    // DEFECT — only `orphan` is forgotten. Its subscriber is neither woken by
+    // the forget itself nor reached by any later input move.
+    family.forget('orphan')
+    feed.set({ control: 3, orphan: 3 })
+    yield* flush()
+
+    // The control proves the harness: the untouched member still wakes.
+    expect(wakes.control).toBe(2)
+    // Observed 1: the forgotten member's subscriber went permanently silent.
+    expect(wakes.orphan).toBeGreaterThan(1)
+  }).pipe(Effect.provide(TestLayer))
+})
+
+// ---------------------------------------------------------------------------
+// FINDING 3 — `state/stateFamily.ts:30` (and `calc/calcFamily.ts:113`): a family
+// indexes its members in a plain `Map<K, …>`, i.e. by SameValueZero reference
+// identity, while every other equality in reform is `Equal.equals`
+// (`internal/store.ts:28`, `internal/sources.ts:45`).
+//
+// So a composite key that is `Equal.equals`-equal — the Effect-canonical way to
+// have a value-typed key, `Schema.Data` / `Data.struct` — resolves to a DIFFERENT
+// store on every lookup. Through the family reducer path that is unconditional,
+// not a caller mistake: `reducer/reducer.ts:131-141` re-decodes the key with
+// `family.validateKeySync(...)`, which mints a fresh object for a struct schema,
+// so `family.at(key)` can never hit the entry the previous event wrote. The fold
+// reads the seed forever, each event strands a new store, and nothing warns.
+// ---------------------------------------------------------------------------
+it.live('stateFamily: an Equal-equal composite key resolves to a different member', () => {
+  const RowKey = S.Data(S.Struct({ board: S.String, row: S.Number }))
+  class Flat extends StateFamily.make('hunt-flat-tally', S.String, S.Number) {}
+  class Keyed extends StateFamily.make('hunt-keyed-tally', RowKey, S.Number) {}
+  class Bumped extends Event.make('HuntBumped', S.Struct({ board: S.String, row: S.Number })) {}
+  class FlatReducer extends Reducer.make('HuntFlatReducer', {
+    family: Flat,
+    keyOf: (event) => `${event.board}:${event.row}`,
+    events: [Bumped],
+  }) {}
+  class KeyedReducer extends Reducer.make('HuntKeyedReducer', {
+    family: Keyed,
+    keyOf: (event) => Data.struct({ board: event.board, row: event.row }),
+    events: [Bumped],
+  }) {}
+  const TestLayer = Layer.mergeAll(
+    Reducer.live(FlatReducer, (count) => count + 1),
+    Reducer.live(KeyedReducer, (count) => count + 1),
+  ).pipe(
+    Layer.provideMerge(
+      Layer.mergeAll(StateFamily.live(Flat, 0), StateFamily.live(Keyed, 0), Engine),
+    ),
+  )
+
+  return Effect.gen(function* () {
+    const flat = yield* Flat.store
+    const keyed = yield* Keyed.store
+    const lookup = Data.struct({ board: 'b', row: 1 })
+    const twin = Data.struct({ board: 'b', row: 1 })
+
+    // Both keys are `Equal.equals`-equal — the premise the family violates.
+    expect(Equal.equals(lookup, twin)).toBe(true)
+
+    yield* publish('High', Event.construct(Bumped, { board: 'b', row: 1 }))
+    yield* publish('High', Event.construct(Bumped, { board: 'b', row: 1 }))
+    yield* publish('High', Event.construct(Bumped, { board: 'b', row: 1 }))
+
+    // CONTROL — the string-keyed twin of the same reducer, same events, same
+    // fold. Gating on it also proves all three events were folded.
+    yield* until(
+      () => flat.at('b:1').get(),
+      (count) => count === 3,
+    )
+    expect(flat.at('b:1').get()).toBe(3)
+    expect(flat.size()).toBe(1)
+
+    // Observed 0: every fold read the seed and wrote into a brand-new store.
+    expect(keyed.at(lookup).get()).toBe(3)
+    // Observed 4: three stranded members plus the one this lookup just minted.
+    expect(keyed.size()).toBe(1)
+  }).pipe(Effect.provide(TestLayer))
+})

package/src/calc/queryState.ts

@@ -6,24 +6,55 @@ export interface QueryState<A, E> {
   readonly error: Option.Option<E>
   readonly isFetching: boolean
   readonly isStale: boolean
+  // The settled result answers an input key the sources have since moved past.
+  // Without it a retained payload is indistinguishable from an answer to the key
+  // the consumer actually asked with.
+  readonly isPreviousKey: boolean
+  // Whether a previous key's payload is presentable. Carried on the state rather
+  // than passed per-reader so every reading of one query agrees about what is
+  // showing — `toAsyncData` and `isLoading` used to be able to contradict.
+  readonly keepPreviousData: boolean
 }
 
-export const empty = (fetching: boolean): QueryState<never, never> => ({
+export const empty = (fetching: boolean, keepPreviousData = false): QueryState<never, never> => ({
   data: Option.none(),
   error: Option.none(),
   isFetching: fetching,
   isStale: false,
+  isPreviousKey: false,
+  keepPreviousData,
 })
 
-export const toAsyncData = <A, E>(state: QueryState<A, E>, gated: boolean): AnyAsyncData<A, E> =>
-  Option.match(state.error, {
+const unsettled = <A, E>(state: QueryState<A, E>, gated: boolean): AnyAsyncData<A, E> =>
+  state.isFetching || !gated ? AsyncData.loading : AsyncData.idle
+
+// A result belonging to a superseded key is not an answer to the question being
+// asked, so it reads as unsettled. `keepPreviousData` opts back into showing it —
+// safe when the payload is only displayed, unsafe when fields are read off it.
+export const toAsyncData = <A, E>(state: QueryState<A, E>, gated: boolean): AnyAsyncData<A, E> => {
+  // `keepPreviousData` keeps a *payload*, and only a payload. A previous key's error
+  // is a verdict on a question nobody is asking any more — republishing it gates the
+  // key now in flight behind a failure that is not its own — and a key that produced
+  // only an error has nothing to keep at all.
+  if (state.isPreviousKey) {
+    const kept = state.keepPreviousData ? state.data : Option.none()
+    return Option.match(kept, {
+      onNone: () => unsettled(state, gated),
+      onSome: (payload) => AsyncData.success(payload, state.isFetching),
+    })
+  }
+  return Option.match(state.error, {
     onSome: (error) => AsyncData.error(error, state.isFetching),
     onNone: () =>
       Option.match(state.data, {
         onSome: (payload) => AsyncData.success(payload, state.isFetching),
-        onNone: () => (state.isFetching || !gated ? AsyncData.loading : AsyncData.idle),
+        onNone: () => unsettled(state, gated),
       }),
   })
+}
 
+// True while there is nothing to show for the key being asked. A previous key's
+// payload counts as something to show exactly when the query keeps it.
 export const isLoading = <A, E>(state: QueryState<A, E>): boolean =>
-  state.isFetching && Option.isNone(state.data)
+  state.isFetching &&
+  (Option.isNone(state.data) || (state.isPreviousKey && !state.keepPreviousData))

package/src/channel/channel-throttle-frames.test.ts

@@ -0,0 +1,163 @@
+import { expect, it } from '@effect/vitest'
+import { Clock, Duration, Effect, Layer, Option, Schema as S, TestClock } from 'effect'
+import { Channel, Engine, Event, Procedure } from '../index'
+import { Channels } from './channel'
+
+// The drain loop notifies on the macrotask/microtask queue; draining turns is
+// exact where a duration would be a guess.
+const settle = Effect.yieldNow().pipe(Effect.repeatN(30))
+
+// `runtime/loop.ts` hands a whole frame to a channel as N synchronous `offer`
+// calls:
+//
+//   ordered.forEach((envelope) => {
+//     procedures.channelsFor(envelope.event._tag).forEach((channelName) => {
+//       channels.get(channelName)?.offer(envelope.event)
+//     })
+//   })
+//
+// Reaching the registration is that exact code path — it only removes the
+// scheduling luck of getting N publishes into one `Queue.takeAll`. Everything
+// downstream (the queue, the policy stream, `runMatching`) is untouched.
+const offerFrame = (
+  name: string,
+  events: ReadonlyArray<{ readonly _tag: string }>,
+): Effect.Effect<void, never, Channels> =>
+  Effect.gen(function* () {
+    const channels = yield* Channels
+    yield* Option.match(Option.fromNullable(channels.byName.get(name)), {
+      onNone: () => Effect.dieMessage(`reform: no live channel '${name}'`),
+      onSome: (registration) =>
+        Effect.sync(() => {
+          events.forEach((event) => registration.offer(event))
+        }),
+    })
+  })
+
+const throttlePolicy = (
+  units: number,
+  strategy: Option.Option<'enforce' | 'shape'>,
+): Channel.ChannelPolicy => ({
+  _tag: 'throttle',
+  units,
+  duration: Duration.seconds(1),
+  cost: Option.none(),
+  burst: Option.none(),
+  strategy,
+})
+
+// ---------------------------------------------------------------------------
+// BUG 1 — a throttled lane charges the whole frame as one indivisible chunk,
+// so an `enforce` lane drops events it had the budget to admit.
+//
+// `channel.ts` throttles the raw event stream, which `Stream.fromQueue` emits
+// one chunk per frame. `cost: (chunk) => Chunk.size(chunk) * cost` prices the
+// frame, and `enforce` drops any chunk it cannot pay for *in full*. A lane
+// rated `2 per second` therefore admits 2 of 3 events when they arrive in
+// three frames, and 0 of 3 when the same three arrive in one frame.
+// ---------------------------------------------------------------------------
+it.effect('a throttle lane admits the events a frame has budget for', () => {
+  class Tick extends Event.make('HuntEnforceTick', S.Struct({ n: S.Number })) {}
+  class Spread extends Channel.make('HuntEnforceSpread', {
+    policy: throttlePolicy(2, Option.some('enforce' as const)),
+  }) {}
+  class Burst extends Channel.make('HuntEnforceBurst', {
+    policy: throttlePolicy(2, Option.some('enforce' as const)),
+  }) {}
+  class SpreadWork extends Procedure.make('HuntEnforceSpreadWork', {
+    events: [Tick],
+    channel: Spread,
+  }) {}
+  class BurstWork extends Procedure.make('HuntEnforceBurstWork', {
+    events: [Tick],
+    channel: Burst,
+  }) {}
+
+  const spread: Array<number> = []
+  const burst: Array<number> = []
+  const layer = Layer.mergeAll(
+    Channel.live(Spread),
+    Channel.live(Burst),
+    Procedure.live(SpreadWork, function* (event) {
+      spread.push(event.n)
+    }),
+    Procedure.live(BurstWork, function* (event) {
+      burst.push(event.n)
+    }),
+  ).pipe(Layer.provideMerge(Engine))
+
+  const ticks = [
+    Event.construct(Tick, { n: 1 }),
+    Event.construct(Tick, { n: 2 }),
+    Event.construct(Tick, { n: 3 }),
+  ]
+
+  return Effect.gen(function* () {
+    // Control: the same three events, one per frame, on the same policy.
+    yield* Effect.forEach(ticks, (tick) =>
+      offerFrame('HuntEnforceSpread', [tick]).pipe(Effect.zipRight(settle)),
+    )
+    // The bucket holds 2 units and the clock never moves, so 1 and 2 are
+    // admitted and 3 is dropped. This is what `enforce` is supposed to do.
+    expect(spread).toEqual([1, 2])
+
+    // Same policy, same three events, one frame.
+    yield* offerFrame('HuntEnforceBurst', ticks)
+    yield* settle
+    yield* TestClock.adjust(Duration.seconds(10))
+    yield* settle
+
+    // The lane has the same 2 units of budget, so 1 and 2 must run. Today the
+    // queue hands the parked stream `[1]` and then `[2, 3]`: the second chunk
+    // is priced at 2 against the 1 unit left, cannot be paid for in full, and
+    // is discarded whole — event 2 is dropped even though the lane had exactly
+    // the budget for it, and it never comes back.
+    expect(burst).toEqual([1, 2])
+  }).pipe(Effect.provide(layer))
+})
+
+// ---------------------------------------------------------------------------
+// BUG 2 — the same whole-frame pricing makes the default `shape` strategy
+// stall the head of a frame and then release the frame simultaneously.
+//
+// On a lane rated `1 per second`, three events in one frame produce: no run at
+// t=0 (the frame waits until it can pay for all three) and then three runs
+// starting together at t=2000. Both halves are wrong: the bucket starts full so
+// the first event is owed an immediate run, and three concurrent starts inside
+// one second is the opposite of the rate the policy declares.
+// ---------------------------------------------------------------------------
+it.effect('a throttle lane paces a frame instead of releasing it at once', () => {
+  class Tick extends Event.make('HuntShapeTick', S.Struct({ n: S.Number })) {}
+  class Lane extends Channel.make('HuntShapeLane', {
+    policy: throttlePolicy(1, Option.none()),
+  }) {}
+  class Work extends Procedure.make('HuntShapeWork', { events: [Tick], channel: Lane }) {}
+
+  const startedAt: Array<number> = []
+  const layer = Layer.mergeAll(
+    Channel.live(Lane),
+    Procedure.live(Work, function* () {
+      const now = yield* Clock.currentTimeMillis
+      startedAt.push(now)
+    }),
+  ).pipe(Layer.provideMerge(Engine))
+
+  return Effect.gen(function* () {
+    yield* offerFrame('HuntShapeLane', [
+      Event.construct(Tick, { n: 1 }),
+      Event.construct(Tick, { n: 2 }),
+      Event.construct(Tick, { n: 3 }),
+    ])
+    yield* settle
+
+    // The token bucket starts full, so the head of the frame owes no wait.
+    expect(startedAt).toEqual([0])
+
+    yield* TestClock.adjust(Duration.seconds(10))
+    yield* settle
+
+    expect(startedAt).toHaveLength(3)
+    // A lane rated `1 per second` must never start two runs in the same instant.
+    expect(new Set(startedAt).size).toBe(3)
+  }).pipe(Effect.provide(layer))
+})

package/src/channel/channel.ts

@@ -186,6 +186,11 @@ export const live = (channel: ChannelClass): Layer.Layer<never, never, Channels
         ),
         Match.tag('throttle', (policy) =>
           events.pipe(
+            // One event per chunk. The drain hands a whole frame over as N offers,
+            // which arrives as one chunk; `Stream.throttle` prices a chunk whole and
+            // drops (or delays) any it cannot pay for in full, so a frame of three on
+            // a lane rated `2 per second` loses all three rather than admitting two.
+            Stream.rechunk(1),
             Stream.throttle({
               cost: (chunk) => Chunk.size(chunk) * Option.getOrElse(policy.cost, () => 1),
               units: policy.units,