@playfast/reform-proof 0.0.10 → 0.1.0

package/README.md

@@ -1,24 +1,24 @@
 <div align="center">
 
-# `@playfast/proof`
+# `@playfast/reform-proof`
 
 **A headless testing toolkit for [reform](https://www.npmjs.com/package/@playfast/reform).**
 Drive a scene's compositions and assert on what they compute — deterministically, with no DOM, no timers, and no text matching.
 
-[![npm](https://img.shields.io/npm/v/@playfast/proof.svg)](https://www.npmjs.com/package/@playfast/proof)
-[![license](https://img.shields.io/npm/l/@playfast/proof.svg)](#license)
+[![npm](https://img.shields.io/npm/v/@playfast/reform-proof.svg)](https://www.npmjs.com/package/@playfast/reform-proof)
+[![license](https://img.shields.io/npm/l/@playfast/reform-proof.svg)](#license)
 [![built with Effect](https://img.shields.io/badge/built%20with-Effect-5a67d8.svg)](https://effect.website)
 
 </div>
 
 ---
 
-A reform *scene* is renderer-neutral, so it can be exercised without a host. `@playfast/proof` runs that same scene against a capturing UI: it dispatches typed events, settles the engine, and lets you assert on the **props a composition computed** — pure data, never rendered markup. The scene you prove is the exact scene `@playfast/react` mounts, so there is no seam between a passing test and production behavior.
+A reform *scene* is renderer-neutral, so it can be exercised without a host. `@playfast/reform-proof` runs that same scene against a capturing UI: it dispatches typed events, settles the engine, and lets you assert on the **props a composition computed** — pure data, never rendered markup. The scene you prove is the exact scene `@playfast/reform-react` renders, so there is no seam between a passing test and production behavior.
 
 ## Install
 
 ```sh
-bun add -d @playfast/proof @playfast/reform effect react
+bun add -d @playfast/reform-proof @playfast/reform effect react
 ```
 
 Peers: `effect`, `react` (`^19`), and `@playfast/reform`.
@@ -80,7 +80,7 @@ There is no real clock. `settle` cooperatively drains forked fibers and loops un
 
 ## The reform family
 
-Core [`@playfast/reform`](https://www.npmjs.com/package/@playfast/reform) · hosts [`@playfast/react`](https://www.npmjs.com/package/@playfast/react) / [`@playfast/react-native`](https://www.npmjs.com/package/@playfast/react-native) · forms [`@playfast/forms`](https://www.npmjs.com/package/@playfast/forms) + [`@playfast/forms-react`](https://www.npmjs.com/package/@playfast/forms-react)
+Core [`@playfast/reform`](https://www.npmjs.com/package/@playfast/reform) · hosts [`@playfast/reform-react`](https://www.npmjs.com/package/@playfast/reform-react) / [`@playfast/reform-react-native`](https://www.npmjs.com/package/@playfast/reform-react-native) · forms [`@playfast/reform-forms`](https://www.npmjs.com/package/@playfast/reform-forms) + [`@playfast/reform-forms-react`](https://www.npmjs.com/package/@playfast/reform-forms-react)
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@playfast/reform-proof",
   "playbook": "./playbook",
-  "version": "0.0.10",
+  "version": "0.1.0",
   "type": "module",
   "description": "Headless testing toolkit for reform — drive a scene's compositions and assert on the props they compute, with no DOM, timers, or text matching.",
   "keywords": [

package/src/engine.ts

@@ -1,4 +1,4 @@
-import { Effect, Layer, Match, ManagedRuntime } from 'effect'
+import { Array as Arr, Cause, Effect, Layer, Match, ManagedRuntime, Option, Record as Rec } from 'effect'
 import { yieldWrapGet } from 'effect/Utils'
 import { AssertionFailed, UnknownAction, UnknownSlot } from './errors'
 import {
@@ -54,9 +54,13 @@ const settleDrain = Effect.yieldNow().pipe(Effect.repeatN(SETTLE_DRAIN))
 // A keyed view backed by a getter — the only place dynamic keys are needed.
 const keyed = <V>(get: (key: string) => V): Record<string, V> => {
   const target: Record<string, V> = Object.create(null)
-  return new Proxy(target, { get: (_t, key) => get(String(key)) })
+  return new Proxy(target, { get: (_target, key) => get(String(key)) })
 }
 
+/** Surface an unknown failure/defect as the message string a result DTO carries. */
+const messageOf = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error)
+
 const uiNameOf = (comp: CompositionClass<unknown>): string => comp.manifest.ui.manifest.name
 
 // The event triggers a `Structure` frame carries (plan 03b). At the erased
@@ -64,8 +68,9 @@ const uiNameOf = (comp: CompositionClass<unknown>): string => comp.manifest.ui.m
 // each value is `never` — assignable to `Trigger<unknown>` without a cast — and an
 // omitted `events` defaults to the empty map. This is the structure-path analog of
 // the view path's `capture.events`.
-const eventsOf = (structure: Structure<UiContract>): Record<string, Trigger<unknown>> =>
-  Object.fromEntries(Object.entries(structure.events ?? {}))
+const eventsOf = (structure: Structure<UiContract>): Record<string, Trigger<unknown>> => ({
+  ...structure.events,
+})
 
 // Engine SPI (Sink/makeSink/RuntimeServices/proofLayer/makeFacade) — exported for
 // @playfast/reform-drive, which builds the no-ceremony scene driver on the same core.
@@ -79,7 +84,11 @@ export const makeSink = (): Sink => {
   // A const holder whose array we swap on reset (no reassigned binding).
   const state: { captures: UiCapture[] } = { captures: [] }
   return {
-    api: { record: (capture) => state.captures.push(capture) },
+    api: {
+      record: (capture) => {
+        state.captures = [...state.captures, capture]
+      },
+    },
     get captures() {
       return state.captures
     },
@@ -102,9 +111,12 @@ export type RuntimeServices = CompositionService | SlotChild | Bus
  * a slot tag with the requirement erased.
  */
 export const proofLayer = (scene: Scene, sink: Sink): Layer.Layer<RuntimeServices, never, never> => {
-  const sceneLayer = scene.provide.reduce((a, b) =>
-    Layer.merge(a, b),
-  ) as unknown as Layer.Layer<RuntimeServices, never, never>
+  // oxlint-disable-next-line reform-rules/no-type-assertion -- the one erasure boundary: the scene's host-read `MountedServices` layer widens to the broader `RuntimeServices` a proof resolves
+  const sceneLayer = scene.provide.reduce((merged, layer) => Layer.merge(merged, layer)) as unknown as Layer.Layer<
+    RuntimeServices,
+    never,
+    never
+  >
   return Layer.provideMerge(sceneLayer, Layer.succeed(CaptureSink, sink.api))
 }
 
@@ -114,7 +126,25 @@ export const proofLayer = (scene: Scene, sink: Sink): Layer.Layer<RuntimeService
 interface Mounted {
   readonly comp: CompositionClass<unknown>
   readonly props: unknown
-  readonly key?: string
+  readonly key: Option.Option<string>
+}
+
+/** A rendered node addressed by its composition ui-name and render index. */
+interface NodeRef {
+  readonly name: string
+  readonly index: number
+}
+
+/** Settle progress: the previous fingerprint and how many renders remain. */
+interface SettleProgress {
+  readonly previous: string
+  readonly remaining: number
+}
+
+/** One step of the driver's generator pump: the value to feed in and the frame index. */
+interface PumpStep {
+  readonly input: unknown
+  readonly index: number
 }
 
 export const makeFacade = (
@@ -137,43 +167,59 @@ export const makeFacade = (
   // features as `default`, the eagerly-resolvable form.)
   const childComposition = (child: SlotChild): CompositionClass<unknown> =>
     isFeatureBinding(child) ? child.composition : child
-  const collect = (comp: CompositionClass<unknown>): Effect.Effect<void, never, SlotChild> =>
-    Effect.gen(function* () {
-      for (const slotClass of Object.values(comp.manifest.slots ?? {})) {
-        if (bindings.has(slotClass)) continue
-        const child = childComposition(yield* slotClass.tag)
-        bindings.set(slotClass, child)
-        yield* collect(child)
-      }
+  const slotClassesOf = (comp: CompositionClass<unknown>): ReadonlyArray<SlotClass> =>
+    Option.fromNullable(comp.manifest.slots).pipe(
+      Option.map((slots) => Object.values(slots)),
+      Option.getOrElse(() => []),
+    )
+  const bindChild = Effect.fn('bindChild')(function* (
+    slotClass: SlotClass,
+  ): Effect.fn.Return<void, never, SlotChild> {
+    const child = childComposition(yield* slotClass.tag)
+    bindings.set(slotClass, child)
+    yield* collect(child)
+  })
+  const collect: (comp: CompositionClass<unknown>) => Effect.Effect<void, never, SlotChild> =
+    Effect.fn('collect')(function* (
+      comp: CompositionClass<unknown>,
+    ): Effect.fn.Return<void, never, SlotChild> {
+      yield* Effect.forEach(slotClassesOf(comp), (slotClass) =>
+        bindings.has(slotClass) ? Effect.void : bindChild(slotClass),
+      )
     })
   runtime.runSync(collect(root))
 
-  // One breadth-first render of the whole tree. Each view reports its
-  // `(props, events)` to the sink; each slot it renders enqueues a child (built
-  // on the next level), so a single sweep renders everything.
-  const renderLevel = (
-    frontier: ReadonlyArray<Mounted>,
-  ): Effect.Effect<void, never, CompositionService> =>
-    Effect.gen(function* () {
-      if (frontier.length === 0) return
-      const next: Array<Mounted> = []
-      for (const { comp, props, key } of frontier) {
-        const service = yield* comp.tag
-        const env: RenderEnv = { props, tracker: { add: () => {} } }
-        const frame = yield* Composition.render(service, env)
-        // Every composition returns a `Structure` (no view is ever executed — the
-        // proof is view-free / React-free): read its computed props straight off the
-        // value, record them + the events it carries into the sink (so the facade,
-        // `triggerOf`, and navigation work uniformly), and walk its slot FILLS to
-        // enqueue children.
-        if (!isStructure(frame)) {
-          return yield* Effect.dieMessage(
-            `reform-proof: composition ${uiNameOf(comp)} did not return a Structure`,
-          )
-        }
-        driveStructure(comp, frame, next, key)
+  // Render one mounted composition, returning the children its fills enqueue. Every
+  // composition returns a `Structure` (no view is ever executed — the proof is
+  // view-free / React-free): read its computed props straight off the value, record
+  // them + the events it carries into the sink (so the facade, `triggerOf`, and
+  // navigation work uniformly), and walk its slot FILLS to enqueue children.
+  const renderMounted = Effect.fn('renderMounted')(function* (
+    mounted: Mounted,
+  ): Effect.fn.Return<ReadonlyArray<Mounted>, never, CompositionService> {
+    const service = yield* mounted.comp.tag
+    const env: RenderEnv = { props: mounted.props, tracker: { add: () => {} } }
+    const frame = yield* Composition.render(service, env)
+    if (!isStructure(frame)) {
+      return yield* Effect.dieMessage(
+        `reform-proof: composition ${uiNameOf(mounted.comp)} did not return a Structure`,
+      )
+    }
+    return driveStructure(mounted.comp, frame, mounted.key)
+  })
+
+  // One breadth-first render of a whole level. Each mounted node reports its
+  // `(props, events)` to the sink and yields the next level of children, so a
+  // single recursive sweep renders everything.
+  const renderLevel: (frontier: ReadonlyArray<Mounted>) => Effect.Effect<void, never, CompositionService> =
+    Effect.fn('renderLevel')(function* (
+      frontier: ReadonlyArray<Mounted>,
+    ): Effect.fn.Return<void, never, CompositionService> {
+      if (frontier.length === 0) {
+        return
       }
-      yield* renderLevel(next)
+      const levels = yield* Effect.forEach(frontier, (mounted) => renderMounted(mounted))
+      yield* renderLevel(levels.flat())
     })
 
   // Consume a `Structure` frame: record the node's computed props (the structure
@@ -186,22 +232,20 @@ export const makeFacade = (
   const driveStructure = (
     comp: CompositionClass<unknown>,
     structure: Structure<UiContract>,
-    next: Array<Mounted>,
-    key: string | undefined,
-  ): void => {
+    key: Option.Option<string>,
+  ): ReadonlyArray<Mounted> => {
     sink.api.record({
       name: uiNameOf(comp),
       props: structure.props,
       events: eventsOf(structure),
-      ...(key !== undefined ? { key } : {}),
+      ...(Option.isSome(key) ? { key: key.value } : {}),
     })
     const fills: Record<string, SlotFill<unknown>> = structure.slots
-    for (const [slotName, fill] of Object.entries(fills)) {
+    return Rec.toEntries(fills).flatMap(([slotName, fill]) => {
       const slotClass = comp.manifest.slots?.[slotName]
       const child = slotClass && bindings.get(slotClass)
-      if (child === undefined) continue
-      enqueueFill(slotName, fill, child, next)
-    }
+      return child === undefined ? [] : enqueueFill(slotName, fill, child)
+    })
   }
 
   // Expand one slot fill into the children to render next. `Each` mounts one
@@ -213,23 +257,25 @@ export const makeFacade = (
     slotName: string,
     fill: SlotFill<unknown>,
     child: CompositionClass<unknown>,
-    next: Array<Mounted>,
-  ): void => {
+  ): ReadonlyArray<Mounted> =>
     Match.value(fill).pipe(
-      Match.when({ _tag: 'Each' }, (each) => {
-        for (const item of each.items) next.push({ comp: child, props: item.props, key: item.key })
-      }),
-      Match.when({ _tag: 'One' }, (oneFill) => {
-        next.push({ comp: child, props: oneFill.props, key: `${slotName}.0` })
-      }),
-      Match.when({ _tag: 'Absent' }, () => {}),
+      Match.when({ _tag: 'Each' }, (each) =>
+        each.items.map((entry) => ({
+          comp: child,
+          props: entry.props,
+          key: Option.some(entry.key),
+        })),
+      ),
+      Match.when({ _tag: 'One' }, (oneFill) => [
+        { comp: child, props: oneFill.props, key: Option.some(`${slotName}.0`) },
+      ]),
+      Match.when({ _tag: 'Absent' }, () => []),
       Match.exhaustive,
     )
-  }
 
   const renderTree: Effect.Effect<void, never, CompositionService> = Effect.gen(function* () {
     sink.reset()
-    yield* renderLevel([{ comp: root, props: {} }])
+    yield* renderLevel([{ comp: root, props: {}, key: Option.none() }])
   })
 
   const capturesFor = (name: string): ReadonlyArray<UiCapture> =>
@@ -238,73 +284,82 @@ export const makeFacade = (
   // A cheap fingerprint of the rendered tree; when two successive renders match,
   // the engine has stopped producing new state and the read is safe.
   const fingerprint = (): string =>
+    // oxlint-disable-next-line reform-rules/no-json-parse-stringify -- structural fixpoint fingerprint of the captured tree; not Schema-typed data
     JSON.stringify(sink.captures.map((capture) => [capture.name, capture.props]))
 
   // Re-render until the tree is stable for two consecutive renders, or give up.
-  const settleFrom = (
-    previous: string,
-    remaining: number,
-  ): Effect.Effect<void, never, CompositionService> =>
-    Effect.gen(function* () {
-      if (remaining === 0) return
+  const settleFrom: (progress: SettleProgress) => Effect.Effect<void, never, CompositionService> =
+    Effect.fn('settleFrom')(function* (
+      progress: SettleProgress,
+    ): Effect.fn.Return<void, never, CompositionService> {
+      if (progress.remaining === 0) {
+        return
+      }
       yield* settleDrain
       yield* Effect.sleep(SETTLE_STEP)
       yield* renderTree
       const current = fingerprint()
-      if (current === previous) return
-      yield* settleFrom(current, remaining - 1)
+      if (current === progress.previous) {
+        return
+      }
+      yield* settleFrom({ previous: current, remaining: progress.remaining - 1 })
     })
   const settle: Effect.Effect<void, never, CompositionService> = Effect.gen(function* () {
     yield* settleDrain
     yield* renderTree
-    yield* settleFrom(fingerprint(), SETTLE_MAX_RENDERS)
+    yield* settleFrom({ previous: fingerprint(), remaining: SETTLE_MAX_RENDERS })
   })
 
-  const triggerOf = (name: string, index: number, event: string): Trigger<unknown> => {
-    const trigger = capturesFor(name)[index]?.events[event]
-    if (trigger === undefined) {
-      throw new UnknownAction({ composition: name, action: event, rendered: capturesFor(name).length })
-    }
-    return trigger
-  }
+  const triggerOf = (ref: NodeRef, event: string): Effect.Effect<Trigger<unknown>> =>
+    Option.match(Option.fromNullable(capturesFor(ref.name)[ref.index]?.events[event]), {
+      onNone: () =>
+        Effect.dieMessage(
+          new UnknownAction({
+            composition: ref.name,
+            action: event,
+            rendered: capturesFor(ref.name).length,
+          }).message,
+        ),
+      onSome: Effect.succeed,
+    })
 
-  const propsFor = (name: string, index: number): Effect.Effect<unknown, never, CompositionService> =>
-    Effect.map(renderTree, () => capturesFor(name)[index]?.props)
+  const propsFor = (ref: NodeRef): Effect.Effect<unknown, never, CompositionService> =>
+    Effect.map(renderTree, () => capturesFor(ref.name)[ref.index]?.props)
 
-  const nodeFacade = (name: string, index: number, comp: CompositionClass<unknown>): AnyFacade => ({
-    props: propsFor(name, index),
+  const nodeFacade = (ref: NodeRef, comp: CompositionClass<unknown>): AnyFacade => ({
+    props: propsFor(ref),
     // Assert the computed props match a typed subset. Reuses the same partial-match
-    // logic as `expect(...).toMatchObject`; throws `AssertionFailed` on mismatch.
+    // logic as `expect(...).toMatchObject`; dies with `AssertionFailed` on mismatch.
     expectProps: (partial) =>
-      propsFor(name, index).pipe(
+      propsFor(ref).pipe(
         Effect.flatMap((props) => {
-          const mismatch = matchProps(props, partial)
+          const mismatch = matchProps({ actual: props, expected: partial })
           return mismatch === undefined
             ? Effect.void
-            : Effect.sync(() => {
-                throw new AssertionFailed({ detail: mismatch })
-              })
+            : Effect.dieMessage(new AssertionFailed({ detail: mismatch }).message)
         }),
       ),
-    // `keyed` resolves event/slot names at runtime; cast the string-keyed proxy
-    // to the contract-typed surface. This is the one reflection boundary, the
-    // same seam as `definitionClass` — every name the proxy serves is a real
-    // contract member, so the cast is sound. The action resolves to the props
-    // this node computed once the dispatch settled (the typed "result" of the event).
+    // `keyed` resolves event/slot names at runtime; the string-keyed proxy is the one
+    // reflection boundary — every name it serves is a real contract member, so reading
+    // it as the contract-typed surface is sound. The action resolves to the props this
+    // node computed once the dispatch settled (the typed "result" of the event).
+    // oxlint-disable-next-line reform-rules/no-type-assertion -- reflection boundary: the string-keyed proxy serves only real contract event names
     actions: keyed(
       (event): Action =>
         (payload) =>
           renderTree.pipe(
-            Effect.flatMap(() =>
+            Effect.flatMap(() => triggerOf(ref, event)),
+            Effect.flatMap((trigger) =>
               Effect.sync(() => {
                 dispatched.add(event)
-                triggerOf(name, index, event)(payload)
+                trigger(payload)
               }),
             ),
             Effect.flatMap(() => settle),
-            Effect.flatMap(() => propsFor(name, index)),
+            Effect.flatMap(() => propsFor(ref)),
           ),
     ) as AnyFacade['actions'],
+    // oxlint-disable-next-line reform-rules/no-type-assertion -- reflection boundary: the string-keyed proxy serves only real contract slot names
     slots: keyed((slotName) => slotFacade(comp, slotName)) as AnyFacade['slots'],
     frame: settle,
   })
@@ -313,38 +368,43 @@ export const makeFacade = (
     const slotClass = parent.manifest.slots?.[slotName]
     const child = slotClass && bindings.get(slotClass)
     if (child === undefined) {
+      // oxlint-disable-next-line reform-rules/no-throw -- proof navigated to an undeclared slot: programmer error surfaced as a defect during generator-time proxy access
       throw new UnknownSlot({ parent: uiNameOf(parent), slot: slotName })
     }
     const childName = uiNameOf(child)
-    const at = (index: number): Effect.Effect<AnyFacade, never, CompositionService> =>
-      Effect.as(renderTree, nodeFacade(childName, index, child))
-    const first = nodeFacade(childName, 0, child)
+    const atIndex = (index: number): Effect.Effect<AnyFacade, never, CompositionService> =>
+      Effect.as(renderTree, nodeFacade({ name: childName, index }, child))
+    const first = nodeFacade({ name: childName, index: 0 }, child)
     // The render index of the child whose structure-fill `key` matches (plan 06).
     // Keys ride on the capture from `each`'s `key` (or a singleton `one` key), so
-    // selection is by stable identity, not render order. Throws `UnknownSlot` (with
-    // the missing key in the slot position) when no fill carries it.
-    const indexOfKey = (key: string): number => {
-      const index = capturesFor(childName).findIndex((capture) => capture.key === key)
-      if (index < 0) {
-        throw new UnknownSlot({ parent: uiNameOf(parent), slot: `${slotName}[key=${key}]` })
-      }
-      return index
-    }
+    // selection is by stable identity, not render order — `none` when no fill carries it.
+    const indexOfKey = (key: string): Option.Option<number> =>
+      Arr.findFirstIndex(capturesFor(childName), (capture) => capture.key === key)
     return {
-      first: at(0),
-      at,
+      first: atIndex(0),
+      at: atIndex,
       all: Effect.map(renderTree, () =>
-        capturesFor(childName).map((_capture, index) => nodeFacade(childName, index, child)),
+        capturesFor(childName).map((_capture, index) => nodeFacade({ name: childName, index }, child)),
       ),
       // Select the one child mounted under `key` (the `each` item key). Re-renders
-      // first so the fill keys reflect the latest frame, then resolves its facade.
-      byKey: (key) => Effect.map(renderTree, () => nodeFacade(childName, indexOfKey(key), child)),
+      // first so the fill keys reflect the latest frame, then resolves its facade;
+      // dies with `UnknownSlot` (key in the slot position) when no fill carries it.
+      byKey: (key) =>
+        Effect.flatMap(renderTree, () =>
+          Option.match(indexOfKey(key), {
+            onNone: () =>
+              Effect.dieMessage(
+                new UnknownSlot({ parent: uiNameOf(parent), slot: `${slotName}[key=${key}]` }).message,
+              ),
+            onSome: (index) => Effect.succeed(nodeFacade({ name: childName, index }, child)),
+          }),
+        ),
       // Every child whose computed props satisfy `predicate`. Re-renders, then maps
       // the matching captures back to their facades by render index.
       where: (predicate) =>
         Effect.map(renderTree, () =>
           capturesFor(childName).flatMap((capture, index) =>
-            predicate(capture.props) ? [nodeFacade(childName, index, child)] : [],
+            predicate(capture.props) ? [nodeFacade({ name: childName, index }, child)] : [],
           ),
         ),
       // How many children this slot mounted this frame — the fill length.
@@ -358,15 +418,15 @@ export const makeFacade = (
     }
   }
 
-  return { facade: nodeFacade(uiNameOf(root), 0, root), settle }
+  return { facade: nodeFacade({ name: uiNameOf(root), index: 0 }, root), settle }
 }
 
 /** Declared-but-never-dispatched events for a proof's requirement (coverage). */
-const missingCoverage = (proof: Proof, dispatched: Set<string>): ReadonlyArray<string> => {
-  const declared = proof.requirement.manifest.events
-  if (declared === undefined) return []
-  return declared.map(String).filter((event) => !dispatched.has(event))
-}
+const missingCoverage = (proof: Proof, dispatched: Set<string>): ReadonlyArray<string> =>
+  Option.match(proof.requirement.manifest.events, {
+    onNone: () => [],
+    onSome: (declared) => declared.map(String).filter((event) => !dispatched.has(event)),
+  })
 
 /**
  * Run one proof against a fresh runtime, returning its pass/fail result. Each
@@ -377,32 +437,28 @@ export const executeProof = async (proof: Proof): Promise<ProofResult> => {
   const sink = makeSink()
   const runtime = ManagedRuntime.make(proofLayer(proof.scene, sink))
   const dispatched = new Set<string>()
-  try {
+  const statement = proof.requirement.manifest.statement
+  const program = Effect.gen(function* () {
     const { facade, settle } = makeFacade(runtime, proof.scene.composition, sink, dispatched)
-    await runtime.runPromise(
-      Effect.forEach(proof.scene.boot ?? [], (event) => publish('High', event)).pipe(
-        Effect.flatMap(() => settle),
-      ),
+    yield* Effect.forEach(
+      Option.getOrElse(Option.fromNullable(proof.scene.boot), () => []),
+      (event) => publish('High', event),
     )
-    await runtime.runPromise(Effect.gen(() => proof.body(facade)))
+    yield* settle
+    yield* Effect.gen(() => proof.body(facade))
     const missing = missingCoverage(proof, dispatched)
-    if (missing.length > 0) {
-      return {
-        requirement: proof.requirement.manifest.statement,
-        ok: false,
-        error: `requirement declares events never dispatched: ${missing.join(', ')}`,
-      }
-    }
-    return { requirement: proof.requirement.manifest.statement, ok: true }
-  } catch (error) {
-    return {
-      requirement: proof.requirement.manifest.statement,
-      ok: false,
-      error: error instanceof Error ? error.message : String(error),
-    }
-  } finally {
-    await runtime.dispose()
-  }
+    const coverageError = `requirement declares events never dispatched: ${missing.join(', ')}`
+    return missing.length > 0
+      ? { requirement: statement, ok: false, error: coverageError }
+      : { requirement: statement, ok: true }
+  }).pipe(
+    Effect.catchAllCause((cause) =>
+      Effect.succeed({ requirement: statement, ok: false, error: messageOf(Cause.squash(cause)) }),
+    ),
+  )
+  const report = await runtime.runPromise(program)
+  await runtime.dispose()
+  return report
 }
 
 /**
@@ -417,38 +473,48 @@ export const executeProof = async (proof: Proof): Promise<ProofResult> => {
 export const driveProof = async (proof: Proof): Promise<DriveResult> => {
   const sink = makeSink()
   const runtime = ManagedRuntime.make(proofLayer(proof.scene, sink))
-  const frames: Array<StepFrame> = []
+  const collected: { frames: ReadonlyArray<StepFrame> } = { frames: [] }
   const statement = proof.requirement.manifest.statement
   // The driver's per-frame timeline does not enforce coverage; collect into a
   // throwaway set so `makeFacade`'s contract is satisfied.
   const dispatched = new Set<string>()
-  try {
+  const record = (index: number): void => {
+    collected.frames = [...collected.frames, { index, captures: [...sink.captures] }]
+  }
+  // Pump the generator: run each yielded effect on the runtime, snapshot, recur.
+  const pump = Effect.fn('pump')(function* (
+    generator: ReturnType<Proof['body']>,
+    step: PumpStep,
+  ): Effect.fn.Return<void, unknown, CompositionService> {
+    const next = generator.next(step.input)
+    if (next.done === true) {
+      return
+    }
+    const output = yield* yieldWrapGet(next.value)
+    yield* Effect.sync(() => record(step.index))
+    yield* pump(generator, { input: output, index: step.index + 1 })
+  })
+  const program = Effect.gen(function* () {
     const { facade, settle } = makeFacade(runtime, proof.scene.composition, sink, dispatched)
-    await runtime.runPromise(
-      Effect.forEach(proof.scene.boot ?? [], (event) => publish('High', event)).pipe(
-        Effect.flatMap(() => settle),
-      ),
+    yield* Effect.forEach(
+      Option.getOrElse(Option.fromNullable(proof.scene.boot), () => []),
+      (event) => publish('High', event),
     )
-    frames.push({ index: 0, captures: [...sink.captures] })
-    const generator = proof.body(facade)
-    // Pump the generator: run each yielded effect on the runtime, snapshot, recur.
-    const pump = async (input: unknown, index: number): Promise<void> => {
-      const step = generator.next(input)
-      if (step.done === true) return
-      const value = await runtime.runPromise(yieldWrapGet(step.value))
-      frames.push({ index, captures: [...sink.captures] })
-      await pump(value, index + 1)
-    }
-    await pump(undefined, 1)
-    return { requirement: statement, frames, ok: true }
-  } catch (error) {
-    return {
-      requirement: statement,
-      frames,
-      ok: false,
-      error: error instanceof Error ? error.message : String(error),
-    }
-  } finally {
-    await runtime.dispose()
-  }
+    yield* settle
+    yield* Effect.sync(() => record(0))
+    yield* pump(proof.body(facade), { input: undefined, index: 1 })
+    return { requirement: statement, frames: collected.frames, ok: true }
+  }).pipe(
+    Effect.catchAllCause((cause) =>
+      Effect.succeed({
+        requirement: statement,
+        frames: collected.frames,
+        ok: false,
+        error: messageOf(Cause.squash(cause)),
+      }),
+    ),
+  )
+  const timeline = await runtime.runPromise(program)
+  await runtime.dispose()
+  return timeline
 }

package/src/index.ts

@@ -1,4 +1,4 @@
-import { Effect } from 'effect'
+import { Array as Arr, Effect, Option, Record as Rec } from 'effect'
 import type { YieldWrap } from 'effect/Utils'
 import { AssertionFailed } from './errors'
 import { ProofRunner, type ProofRunnerApi, proofRunnerLayer, withProofRunner } from './runner'
@@ -52,7 +52,7 @@ export interface RequirementManifest<Comp extends AnyComposition, Statement exte
    * dispatches a declared event fails, so the requirement and its proof can't
    * silently drift (the definition→implementation link past the statement string).
    */
-  readonly events?: ReadonlyArray<keyof EventsOf<ContractOf<Comp>>>
+  readonly events: Option.Option<ReadonlyArray<keyof EventsOf<ContractOf<Comp>>>>
 }
 
 export interface RequirementClass<Comp extends AnyComposition, Statement extends string> {
@@ -77,20 +77,27 @@ export interface ProductClass<Comp extends AnyComposition = AnyComposition> {
  * specifies. The composition types the proof facade; the statement's literal
  * type is re-stated (and enforced) at `Proof.implement`.
  */
+/** Author-facing config for `ProductRequirement.make` — plain JSON the proof author passes. */
+interface MakeRequirementOptionsExternalApi<Comp extends AnyComposition> {
+  readonly events?: ReadonlyArray<keyof EventsOf<ContractOf<Comp>>>
+}
+
 const makeRequirement = <Comp extends AnyComposition, const Statement extends string>(
   composition: Comp,
   statement: Statement,
-  options?: { readonly events?: ReadonlyArray<keyof EventsOf<ContractOf<Comp>>> },
-): RequirementClass<Comp, Statement> =>
-  Object.assign(class {}, {
-    manifest: {
-      kind: 'ProductRequirement' as const,
-      name: statement,
-      statement,
-      composition,
-      ...(options?.events !== undefined ? { events: options.events } : {}),
-    },
-  })
+  options?: MakeRequirementOptionsExternalApi<Comp>,
+): RequirementClass<Comp, Statement> => {
+  const manifest: RequirementManifest<Comp, Statement> = {
+    kind: 'ProductRequirement',
+    name: statement,
+    statement,
+    composition,
+    events: Option.fromNullable(options?.events),
+  }
+  return class {
+    static readonly manifest = manifest
+  }
+}
 
 export const ProductRequirement: { readonly make: typeof makeRequirement } = {
   make: makeRequirement,
@@ -100,18 +107,24 @@ export const ProductRequirement: { readonly make: typeof makeRequirement } = {
  * Group a composition with the full list of requirements that specify it. The
  * shared `Comp` type-checks that every requirement targets this composition.
  */
+interface MakeProductConfig<Comp extends AnyComposition> {
+  readonly requirements: ReadonlyArray<RequirementClass<Comp, string>>
+}
+
 const makeProduct = <Comp extends AnyComposition>(
   composition: Comp,
-  config: { readonly requirements: ReadonlyArray<RequirementClass<Comp, string>> },
-): ProductClass<Comp> =>
-  Object.assign(class {}, {
-    manifest: {
-      kind: 'Product' as const,
-      name: composition.manifest.name,
-      composition,
-      requirements: config.requirements,
-    },
-  })
+  config: MakeProductConfig<Comp>,
+): ProductClass<Comp> => {
+  const manifest: ProductManifest<Comp> = {
+    kind: 'Product',
+    name: composition.manifest.name,
+    composition,
+    requirements: config.requirements,
+  }
+  return class {
+    static readonly manifest = manifest
+  }
+}
 
 export const Product: { readonly make: typeof makeProduct } = { make: makeProduct }
 
@@ -119,59 +132,79 @@ export const Product: { readonly make: typeof makeProduct } = { make: makeProduc
 // Assertions — Effect-returning matchers; a failed match fails the proof.
 // ---------------------------------------------------------------------------
 
-const deepEqual = (a: unknown, b: unknown): boolean =>
-  Object.is(a, b) || JSON.stringify(a) === JSON.stringify(b)
+/** Two values to deep-compare — one options object, not positional primitives. */
+interface ComparePair {
+  readonly left: unknown
+  readonly right: unknown
+}
+
+// Display + structural-compare seam: assertion messages and deep-equality operate on
+// arbitrary `unknown` values, which Schema cannot encode — JSON is the right tool here.
+// oxlint-disable-next-line reform-rules/no-json-parse-stringify -- arbitrary unknown assertion values, not Schema-typed data
+const show = (subject: unknown): string => JSON.stringify(subject)
+
+const deepEqual = ({ left, right }: ComparePair): boolean =>
+  Object.is(left, right) || show(left) === show(right)
 
 const fail = (message: string): Effect.Effect<never> =>
-  Effect.sync(() => {
-    throw new AssertionFailed({ detail: message })
-  })
+  Effect.dieMessage(new AssertionFailed({ detail: message }).message)
 
 export const expect = <A>(actual: A) => ({
   toBe: (expected: A): Effect.Effect<void> =>
     Object.is(actual, expected)
       ? Effect.void
-      : fail(`expected ${JSON.stringify(actual)} to be ${JSON.stringify(expected)}`),
+      : fail(`expected ${show(actual)} to be ${show(expected)}`),
   toEqual: (expected: A): Effect.Effect<void> =>
-    deepEqual(actual, expected)
+    deepEqual({ left: actual, right: expected })
       ? Effect.void
-      : fail(`expected ${JSON.stringify(actual)} to equal ${JSON.stringify(expected)}`),
+      : fail(`expected ${show(actual)} to equal ${show(expected)}`),
   toContain: (expected: A extends ReadonlyArray<infer E> ? E : unknown): Effect.Effect<void> =>
-    Array.isArray(actual) && actual.some((item) => deepEqual(item, expected))
+    Array.isArray(actual) && actual.some((element) => deepEqual({ left: element, right: expected }))
       ? Effect.void
-      : fail(`expected ${JSON.stringify(actual)} to contain ${JSON.stringify(expected)}`),
+      : fail(`expected ${show(actual)} to contain ${show(expected)}`),
   toMatchObject: (expected: Partial<A>): Effect.Effect<void> => {
-    const mismatch = matchPartial(actual, expected)
+    const mismatch = matchPartial({ actual, expected })
     return mismatch === undefined ? Effect.void : fail(mismatch)
   },
 })
 
+/** A non-null object as an indexable record — the narrowing `unknown` doesn't give. */
+const isRecord = (candidate: unknown): candidate is Record<string, unknown> =>
+  typeof candidate === 'object' && candidate !== null
+
+/** The pair `matchPartial`/`matchProps` deep-matches: `actual` against the `expected` subset. */
+interface MatchInput {
+  readonly actual: unknown
+  readonly expected: unknown
+}
+
 /**
  * Deep-match every key of `expected` against `actual`; returns an error message
  * naming the first failing key, or `undefined` on a full match. Shared by
  * `expect(...).toMatchObject` and the facade's `expectProps`.
  */
-const matchPartial = (actual: unknown, expected: unknown): string | undefined => {
-  if (typeof expected !== 'object' || expected === null) {
-    return deepEqual(actual, expected)
+const matchPartial = ({ actual, expected }: MatchInput): string | undefined => {
+  if (!isRecord(expected)) {
+    return deepEqual({ left: actual, right: expected })
       ? undefined
-      : `expected ${JSON.stringify(actual)} to match ${JSON.stringify(expected)}`
+      : `expected ${show(actual)} to match ${show(expected)}`
   }
-  if (typeof actual !== 'object' || actual === null) {
-    return `expected ${JSON.stringify(actual)} to be an object matching ${JSON.stringify(expected)}`
-  }
-  const actualRecord = actual as Record<string, unknown>
-  const expectedRecord = expected as Record<string, unknown>
-  for (const key of Object.keys(expectedRecord)) {
-    if (!deepEqual(actualRecord[key], expectedRecord[key])) {
-      return `expected key ${JSON.stringify(key)} to match ${JSON.stringify(expectedRecord[key])}, got ${JSON.stringify(actualRecord[key])}`
-    }
+  if (!isRecord(actual)) {
+    return `expected ${show(actual)} to be an object matching ${show(expected)}`
   }
-  return undefined
+  const mismatch = Arr.findFirst(
+    Rec.keys(expected),
+    (key) => !deepEqual({ left: actual[key], right: expected[key] }),
+  )
+  return Option.match(mismatch, {
+    onNone: () => undefined,
+    onSome: (key) =>
+      `expected key ${show(key)} to match ${show(expected[key])}, got ${show(actual[key])}`,
+  })
 }
 
 /** Internal: the facade's `expectProps` reuses the same partial-match logic. */
-export const matchProps: (actual: unknown, expected: unknown) => string | undefined = matchPartial
+export const matchProps: (input: MatchInput) => string | undefined = matchPartial
 
 // ---------------------------------------------------------------------------
 // Facade — a headless view over the live composition tree
@@ -289,6 +322,7 @@ export interface ProofSuite {
 export interface ProofResult {
   readonly requirement: string
   readonly ok: boolean
+  // oxlint-disable-next-line reform-rules/no-optional-fields -- serialized result DTO read as `error ?? …` by the vitest adapter (external); optional kept for wire compat
   readonly error?: string
 }
 
@@ -310,20 +344,27 @@ const implement = <Comp extends AnyComposition>(
   requirement: RequirementClass<Comp, string>,
   scene: Scene<ContractOf<Comp>>,
   body: (app: Facade<ContractOf<Comp>>) => ProofGenerator,
-): Proof => ({ requirement, scene, body: body as ProofBody })
+): Proof => {
+  // oxlint-disable-next-line reform-rules/no-type-assertion -- contract erasure seam: Facade<C> → AnyFacade is contravariant, sound by construction
+  const erased = body as ProofBody
+  return { requirement, scene, body: erased }
+}
 
-/** Compose proofs with the product whose requirements they prove. */
-const suite = (
-  product: ProductClass,
-  config: { readonly proofs: ReadonlyArray<Proof> },
-): ProofSuite => ({ kind: 'ProofSuite', product, proofs: config.proofs })
+/** The proofs a `Proof.suite` binds to its product. */
+interface MakeSuiteConfig {
+  readonly proofs: ReadonlyArray<Proof>
+}
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null
+/** Compose proofs with the product whose requirements they prove. */
+const suite = (product: ProductClass, config: MakeSuiteConfig): ProofSuite => ({
+  kind: 'ProofSuite',
+  product,
+  proofs: config.proofs,
+})
 
 /** Duck-type a `ProofSuite` among arbitrary module exports (the adapter's seam). */
-export const isProofSuite = (value: unknown): value is ProofSuite =>
-  isRecord(value) && value['kind'] === 'ProofSuite' && Array.isArray(value['proofs'])
+export const isProofSuite = (candidate: unknown): candidate is ProofSuite =>
+  isRecord(candidate) && candidate['kind'] === 'ProofSuite' && Array.isArray(candidate['proofs'])
 
 /**
  * Run every proof against a fresh runtime, returning per-requirement results.
@@ -332,11 +373,14 @@ export const isProofSuite = (value: unknown): value is ProofSuite =>
  */
 const run = (proofSuite: ProofSuite): Promise<SuiteResult> =>
   withProofRunner(async (runner: ProofRunnerApi) => {
-    const results: ProofResult[] = []
-    for (const proof of proofSuite.proofs) {
-      results.push(await runner.executeProof(proof))
+    const reports = await Effect.runPromise(
+      Effect.forEach(proofSuite.proofs, (proof) => Effect.promise(() => runner.executeProof(proof))),
+    )
+    return {
+      product: proofSuite.product.manifest.name,
+      results: reports,
+      ok: reports.every((report) => report.ok),
     }
-    return { product: proofSuite.product.manifest.name, results, ok: results.every((r) => r.ok) }
   })
 
 // ---------------------------------------------------------------------------
@@ -354,6 +398,7 @@ export interface DriveResult {
   readonly requirement: string
   readonly frames: ReadonlyArray<StepFrame>
   readonly ok: boolean
+  // oxlint-disable-next-line reform-rules/no-optional-fields -- serialized result DTO read as `error ?? …` by the editor timeline (external); optional kept for wire compat
   readonly error?: string
 }