@playfast/reform-proof 1.2.1 → 1.4.0

package/src/fingerprint.ts

@@ -1,4 +1,6 @@
+import * as Arr from 'effect/Array'
 import * as Option from 'effect/Option'
+import * as Order from 'effect/Order'
 
 const readPropertyOption = Option.liftThrowable((target: object, key: PropertyKey): unknown =>
   Reflect.get(target, key),
@@ -14,7 +16,15 @@ const propertyKeyFingerprint = (key: PropertyKey): string =>
       ? `number-key:${String(key)}`
       : `key:${key.length}:${key}`
 
-const valueFingerprint = (candidate: unknown, seen: WeakSet<object>): string => {
+interface Walk {
+  readonly seen: WeakSet<object>
+  // Printed sub-fingerprints, so a shared reference is walked once. Unwinding `seen`
+  // made the walk follow every *path* rather than every node, which on a DAG that
+  // shares a child two ways doubles the work per level — a deep one hangs.
+  readonly memo: WeakMap<object, string>
+}
+
+const valueFingerprint = (candidate: unknown, walk: Walk): string => {
   if (typeof candidate === 'bigint') {
     return `bigint:${String(candidate)}`
   }
@@ -39,12 +49,32 @@ const valueFingerprint = (candidate: unknown, seen: WeakSet<object>): string =>
   if (candidate === null) {
     return 'null'
   }
-  if (seen.has(candidate)) {
+  if (walk.seen.has(candidate)) {
     return '[Circular]'
   }
-  seen.add(candidate)
+  const remembered = walk.memo.get(candidate)
+  if (remembered !== undefined) {
+    return remembered
+  }
+  // `seen` marks the path currently being walked, not everything ever visited: it
+  // is unwound below. Without that, a value that merely repeats a reference — the
+  // same config object under two keys, a DAG rather than a cycle — reads as
+  // `[Circular]` on its second appearance, so two equal values fingerprint
+  // differently and `toEqual` fails on them.
+  walk.seen.add(candidate)
+  const printed = structuralFingerprint(candidate, walk)
+  walk.seen.delete(candidate)
+  // Only a print that did not depend on where the walk had been is reusable: one
+  // containing `[Circular]` describes this path, not this value.
+  if (!printed.includes('[Circular]')) {
+    walk.memo.set(candidate, printed)
+  }
+  return printed
+}
+
+const structuralFingerprint = (candidate: object, walk: Walk): string => {
   if (Array.isArray(candidate)) {
-    return `[${candidate.map((arrayEntry) => valueFingerprint(arrayEntry, seen)).join(',')}]`
+    return `[${candidate.map((arrayEntry) => valueFingerprint(arrayEntry, walk)).join(',')}]`
   }
   if (candidate instanceof Date) {
     return `date:${String(candidate.getTime())}`
@@ -53,21 +83,26 @@ const valueFingerprint = (candidate: unknown, seen: WeakSet<object>): string =>
     return `map:[${Array.from(
       candidate,
       ([mapKey, mapEntry]) =>
-        `${valueFingerprint(mapKey, seen)}=>${valueFingerprint(mapEntry, seen)}`,
+        `${valueFingerprint(mapKey, walk)}=>${valueFingerprint(mapEntry, walk)}`,
     ).join(',')}]`
   }
   if (candidate instanceof Set) {
-    return `set:[${Array.from(candidate, (setEntry) => valueFingerprint(setEntry, seen)).join(
+    return `set:[${Array.from(candidate, (setEntry) => valueFingerprint(setEntry, walk)).join(
       ',',
     )}]`
   }
-  return `{${Reflect.ownKeys(candidate)
+  // Sorted by key: an object is the same value however its keys were inserted, so
+  // reordering fields in a composition's source must not break a passing proof.
+  return `{${Arr.sortWith(
+    Reflect.ownKeys(candidate).map((key) => ({ key, printed: propertyKeyFingerprint(key) })),
+    (entry) => entry.printed,
+    Order.string,
+  )
     .map(
-      (key) =>
-        `${propertyKeyFingerprint(key)}:${valueFingerprint(readProperty(candidate, key), seen)}`,
+      (entry) => `${entry.printed}:${valueFingerprint(readProperty(candidate, entry.key), walk)}`,
     )
     .join(',')}}`
 }
 
 export const formatFingerprint = (fingerprintInput: unknown): string =>
-  valueFingerprint(fingerprintInput, new WeakSet())
+  valueFingerprint(fingerprintInput, { seen: new WeakSet(), memo: new WeakMap() })

package/src/index.ts

@@ -29,6 +29,7 @@ export {
   proofLayer,
 } from './engine'
 export type {
+  DispatchedAction,
   MountedFacade,
   MountedSlotFacade,
   MountedSlotFacadesOf,
@@ -230,4 +231,3 @@ export const Proof: {
   readonly driver: typeof driver
   readonly withTestClock: typeof withTestClock
 } = { implement, implementVia, suite, run, runEffect, driver, withTestClock }
-

package/src/proof-attribution.test.ts

@@ -0,0 +1,210 @@
+import { expect, it } from '@effect/vitest'
+import { Effect, Layer, Ref, Schema as S } from 'effect'
+import {
+  Composition,
+  each,
+  Engine,
+  Event,
+  mount,
+  provide,
+  Reducer,
+  scene,
+  slot,
+  State,
+  StateGroup,
+  type Trigger,
+  Ui,
+  ui,
+} from '@playfast/reform'
+import { Product, Proof, ProductRequirement, expect as proofExpect } from './index'
+import type { Proof as ProofValue } from './index'
+
+// A list of keyed children, each able to remove itself, over a root that owns its
+// own `bump`. The child contract deliberately exposes an event with the SAME name
+// (`bump`) backed by a DIFFERENT domain event, so "which node was this credited
+// to?" is observable rather than a matter of taste.
+
+const Todo = S.Struct({ id: S.String, label: S.String })
+
+class HuntTodos extends State.make('huntTodos', S.Array(Todo)) {}
+class HuntBumps extends State.make('huntBumps', S.Number) {}
+class HuntStates extends StateGroup.make(HuntTodos, HuntBumps) {}
+
+class HuntRemoved extends Event.make('HuntRemoved', S.Struct({ id: S.String })) {}
+class HuntItemBumped extends Event.make('HuntItemBumped', S.Struct({ id: S.String })) {}
+class HuntRootBumped extends Event.make('HuntRootBumped', S.Struct({})) {}
+
+class HuntRemoveReducer extends Reducer.make('HuntRemoveReducer', {
+  states: [HuntTodos],
+  events: [HuntRemoved],
+}) {}
+const HuntRemoveReducerLive = Reducer.live(HuntRemoveReducer, (todos, event) =>
+  todos.filter((todo) => todo.id !== event.id),
+)
+
+class HuntRootBumpReducer extends Reducer.make('HuntRootBumpReducer', {
+  states: [HuntBumps],
+  events: [HuntRootBumped],
+}) {}
+const HuntRootBumpReducerLive = Reducer.live(HuntRootBumpReducer, (bumps) => bumps + 1)
+
+class HuntItemUi extends ui('HuntItem')<{
+  props: { id: string; label: string }
+  events: { remove: Trigger<{ id: string }>; bump: Trigger<{ id: string }> }
+}>() {}
+class HuntItem extends Composition.make('HuntItem', {
+  title: 'HuntItem',
+  props: S.Struct({ id: S.String, label: S.String }),
+  events: [HuntRemoved, HuntItemBumped],
+  ui: HuntItemUi,
+})<HuntItem>() {}
+const HuntItemLive = Composition.live(HuntItem, function* () {
+  const props = yield* HuntItem.props
+  const remove = yield* Event.trigger(HuntRemoved)
+  const bump = yield* Event.trigger(HuntItemBumped)
+  return mount({ props, slots: {}, events: { remove, bump } })
+})
+class HuntItemSlot extends slot('HuntItem')<HuntItemSlot, typeof HuntItem>() {}
+
+class HuntListUi extends ui('HuntList')<{
+  props: { total: number; bumps: number }
+  slots: { Item: HuntItemSlot }
+  events: { bump: Trigger<Record<string, never>> }
+}>() {}
+class HuntList extends Composition.make('HuntList', {
+  title: 'HuntList',
+  states: [HuntStates],
+  events: [HuntRootBumped],
+  slots: { Item: HuntItemSlot },
+  ui: HuntListUi,
+})<HuntList>() {}
+const HuntListLive = Composition.live(HuntList, function* () {
+  const todos = yield* StateGroup.select(HuntStates, 'huntTodos')
+  const bumps = yield* StateGroup.select(HuntStates, 'huntBumps')
+  const bump = yield* Event.trigger(HuntRootBumped)
+  return mount({
+    props: { total: todos.length, bumps },
+    slots: {
+      Item: each(todos, {
+        key: (todo) => todo.id,
+        props: (todo) => ({ id: todo.id, label: todo.label }),
+      }),
+    },
+    events: { bump },
+  })
+})
+
+const presentations = Layer.mergeAll(
+  provide(
+    HuntListUi,
+    Ui.make(HuntListUi, () => null),
+  ),
+  provide(
+    HuntItemUi,
+    Ui.make(HuntItemUi, () => null),
+  ),
+)
+const Views = Layer.mergeAll(HuntListLive, HuntItemLive, provide(HuntItemSlot, HuntItem)).pipe(
+  Layer.provideMerge(presentations),
+)
+const Logic = Layer.mergeAll(HuntRemoveReducerLive, HuntRootBumpReducerLive).pipe(
+  Layer.provideMerge(
+    Layer.mergeAll(
+      Engine,
+      StateGroup.live(HuntStates, {
+        huntTodos: [
+          { id: 'a', label: 'alpha' },
+          { id: 'b', label: 'beta' },
+          { id: 'c', label: 'gamma' },
+        ],
+        huntBumps: 0,
+      }),
+    ),
+  ),
+)
+const HuntScene = scene(HuntList, { provide: [Views.pipe(Layer.provideMerge(Logic))] })
+
+class CoversListBump extends ProductRequirement.make(HuntList, 'bumps the list itself', {
+  events: ['bump'],
+}) {}
+class HuntProduct extends Product.make(HuntList, { requirements: [CoversListBump] }) {}
+
+const runProof = (proof: ProofValue) =>
+  Effect.promise(() => Proof.run(Proof.suite(HuntProduct, { proofs: [proof] })))
+
+// BUG 1 — engine.ts `missingCoverage` matches a requirement's declared events
+// against a flat Set of event NAMES dispatched anywhere in the tree, so a
+// same-named action on a child composition (a different domain Event entirely)
+// silently satisfies coverage declared on the requirement's own composition.
+it.live('requirement event coverage is not credited to the requirement’s composition', () =>
+  Effect.gen(function* () {
+    // Control A — a genuine dispatch of the list's own `bump` is covered.
+    const rootDispatch = Proof.implement(CoversListBump, HuntScene, function* (app) {
+      const after = yield* app.actions.bump({})
+      yield* proofExpect(after.bumps).toBe(1)
+    })
+    const rootResult = yield* runProof(rootDispatch)
+    expect(rootResult.results[0]?.error).toBeUndefined()
+    expect(rootResult.ok).toBe(true)
+
+    // Control B — dispatching nothing is reported as uncovered.
+    const noDispatch = Proof.implement(CoversListBump, HuntScene, function* (app) {
+      yield* app.expectProps({ bumps: 0 })
+    })
+    const noneResult = yield* runProof(noDispatch)
+    expect(noneResult.ok).toBe(false)
+    expect(noneResult.results[0]?.error).toContain('never dispatched')
+
+    // The defect — only the CHILD's `bump` (HuntItemBumped) is dispatched. The
+    // proof body itself proves the list's `bump` (HuntRootBumped) never fired,
+    // yet the run is reported green with its coverage requirement satisfied.
+    const childOnly = Proof.implement(CoversListBump, HuntScene, function* (app) {
+      const item = yield* app.slots.Item.first
+      yield* item.actions.bump({ id: 'a' })
+      yield* app.expectProps({ bumps: 0 })
+    })
+    const childResult = yield* runProof(childOnly)
+    expect(childResult.ok).toBe(false)
+    expect(childResult.results[0]?.error).toContain('never dispatched')
+  }),
+)
+
+// BUG 2 — engineTreeFacade.ts resolves a slot child's "did this node survive the
+// action?" peek by INDEX, so an action that removes a non-last child reports the
+// successor that slid into that index as if those were the acting node's props.
+it.live('an action on a slot child resolves to that child’s own props', () =>
+  Effect.gen(function* () {
+    const observed = yield* Ref.make<ReadonlyArray<string>>([])
+    const removals = Proof.implement(CoversListBump, HuntScene, function* (app) {
+      yield* app.actions.bump({})
+
+      // [a, b, c] — remove the HEAD via its index locator.
+      const head = yield* app.slots.Item.at(0)
+      const afterHead = yield* head.actions.remove({ id: 'a' })
+      yield* Ref.update(observed, (seen) => [...seen, afterHead.id])
+
+      // [b, c] — remove the TAIL via its index locator (index runs past the end).
+      const tail = yield* app.slots.Item.at(1)
+      const afterTail = yield* tail.actions.remove({ id: 'c' })
+      yield* Ref.update(observed, (seen) => [...seen, afterTail.id])
+
+      // [b] — remove via the key locator.
+      const keyed = yield* app.slots.Item.byKey('b')
+      const afterKeyed = yield* keyed.actions.remove({ id: 'b' })
+      yield* Ref.update(observed, (seen) => [...seen, afterKeyed.id])
+    })
+    const result = yield* runProof(removals)
+    expect(result.results[0]?.error).toBeUndefined()
+
+    const seen = yield* Ref.get(observed)
+    expect(seen.length).toBe(3)
+    // Control A — removing the LAST child leaves nothing at that index, so the
+    // harness correctly reports the acting node's last props.
+    expect(seen[1]).toBe('c')
+    // Control B — the key locator misses after removal, likewise correct.
+    expect(seen[2]).toBe('b')
+    // The defect — removing a NON-last child still finds "something" at index 0,
+    // so the action resolves to sibling `b`'s props instead of `a`'s.
+    expect(seen[0]).toBe('a')
+  }),
+)

package/src/test-clock.test.ts

@@ -66,7 +66,10 @@ const FlashLive = Composition.live(Flash, function* () {
   return mount({ props: { flash }, slots: {}, events: { submit } })
 })
 
-const presentations = provide(FlashUi, Ui.make(FlashUi, () => null))
+const presentations = provide(
+  FlashUi,
+  Ui.make(FlashUi, () => null),
+)
 const Views = FlashLive.pipe(Layer.provideMerge(presentations))
 const Logic = Layer.mergeAll(EndFlashLive, FlashTimerLive, Channel.live(FlashLane)).pipe(
   Layer.provideMerge(Layer.mergeAll(Engine, StateGroup.live(FlashStates, { flash: true }))),
@@ -83,13 +86,20 @@ class FlashProduct extends Product.make(Flash, { requirements: [ClearsFlash] })
 
 describe('Proof.withTestClock', () => {
   test('app.advance elapses a product timer without spending real time', async () => {
+    // An hour of product time, not the 1500ms window. The ratio is what keeps this an
+    // assertion about the clock rather than about the runner: virtual time costs the
+    // same whether it is a second or an hour, so the budget below sits ~15x above what
+    // this harness really spends (measured 370-710ms) and ~360x below what the real
+    // clock would charge. The 750ms budget it replaces sat inside that measured range,
+    // which is why it failed on a loaded runner.
+    const LONG = Duration.hours(1)
     const proof = Proof.implement(ClearsFlash, VirtualScene, function* (app) {
       yield* proofExpect((yield* app.props).flash).toBe(true)
       yield* app.actions.submit({})
       // The timer is armed but no virtual time has passed, so the flash still shows.
       // On the real clock this frame is a race; here it is a fact.
       yield* proofExpect((yield* app.props).flash).toBe(true)
-      yield* app.advance(FLASH)
+      yield* app.advance(LONG)
       yield* proofExpect((yield* app.props).flash).toBe(false)
     })
 
@@ -99,10 +109,10 @@ describe('Proof.withTestClock', () => {
 
     expect(result.results.map((entry) => entry.error)).toEqual([undefined])
     expect(result.ok).toBe(true)
-    // The assertion that matters: 1500ms of product time cost a fraction of it in
-    // real time. Generous enough not to flake on a loaded runner, tight enough that
-    // a regression to the real clock (>= 1500ms) fails here.
-    expect(elapsed).toBeLessThan(750)
+    // The assertion that matters: an hour of product time cost well under a second of
+    // real time. A regression to the real clock cannot squeeze past this — it would
+    // have to finish an hour of sleeping in ten.
+    expect(elapsed).toBeLessThan(10_000)
   })
 
   test('the timer does not fire on its own — only advancing moves it', async () => {