@playfast/reform-proof 0.0.7 → 0.0.9

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@playfast/reform-proof",
   "playbook": "./playbook",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "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": [
@@ -27,7 +27,7 @@
     "./*": "./src/*.ts"
   },
   "files": [
-    "dist",
+    "src",
     "README.md"
   ],
   "scripts": {

package/src/engine.ts

@@ -0,0 +1,452 @@
+import { Effect, Layer, Match, ManagedRuntime } from 'effect'
+import { yieldWrapGet } from 'effect/Utils'
+import { AssertionFailed, UnknownAction, UnknownSlot } from './errors'
+import {
+  Bus,
+  CaptureSink,
+  type CaptureSinkApi,
+  Composition,
+  type CompositionClass,
+  type CompositionService,
+  isFeatureBinding,
+  isStructure,
+  publish,
+  type RenderEnv,
+  type Scene,
+  type SlotChild,
+  type SlotClass,
+  type SlotFill,
+  type Structure,
+  type Trigger,
+  type UiCapture,
+  type UiContract,
+} from '@playfast/reform'
+import { matchProps } from './index'
+import type { Action, DriveResult, Facade, Proof, ProofResult, SlotFacade, StepFrame } from './index'
+
+// reform-proof engine — the headless renderer the proof system runs on. It drives the
+// real reduce loop through a capturing FACADE: no DOM, no React, no view eval — each
+// composition returns a `Structure`, and the engine reads props/events/fills off the
+// data. `executeProof`/`driveProof` are the two seams the `ProofRunner` layer exposes
+// (see ./runner): run a proof to completion, or step it a frame at a time.
+
+/** An erased facade — the runtime shape before the contract type is re-attached. */
+type AnyFacade = Facade<UiContract>
+type AnySlotFacade = SlotFacade<UiContract>
+
+// The drain loop, channels, RPC, and reducers run on forked fibers, so a
+// dispatched event takes an unknown number of ticks to flow through. Each poll
+// first drains COOPERATIVELY — a burst of `yieldNow` lets those forked fibers
+// cascade (event → channel → procedure → in-memory RPC → fact → reducer) with no
+// real time — so a synchronous flow reaches its final state within one poll. A
+// real-time `sleep` is still paid each poll to remain the correctness authority
+// for a genuinely time-delayed client (the cooperative drain alone could read a
+// flow waiting on a real timer as falsely "stable" and settle early). The render
+// then re-runs until the captured tree stops changing, bounded so a stuck flow
+// fails fast instead of hanging.
+const SETTLE_DRAIN = 30
+const SETTLE_STEP = '1 milli'
+const SETTLE_MAX_RENDERS = 100
+
+/** Cooperatively run forked engine fibers to a fixpoint without advancing real time. */
+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)) })
+}
+
+const uiNameOf = (comp: CompositionClass<unknown>): string => comp.manifest.ui.manifest.name
+
+// The event triggers a `Structure` frame carries (plan 03b). At the erased
+// `UiContract` boundary the contract's event map is `Record<never, never>`, so
+// 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 ?? {}))
+
+interface Sink {
+  readonly api: CaptureSinkApi
+  readonly captures: ReadonlyArray<UiCapture>
+  reset(): void
+}
+
+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) },
+    get captures() {
+      return state.captures
+    },
+    reset: () => {
+      state.captures = []
+    },
+  }
+}
+
+type RuntimeServices = CompositionService | SlotChild | Bus
+
+/**
+ * Build a proof's runtime layer: the scene's closed wiring with the capture sink
+ * merged in, so `Ui`'s `serviceOption(CaptureSink)` finds it and records each
+ * render (absent in production, the same layer renders to React). The scene's
+ * `provide` is typed to the host-read subset (`MountedServices`); a proof also
+ * resolves slot-binding tags (`CompositionClass`), which the same closed layer
+ * supplies at runtime — restate that broader `RuntimeServices` surface here. This
+ * is the one erasure boundary, the same seam the react host crosses when it reads
+ * a slot tag with the requirement erased.
+ */
+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>
+  return Layer.provideMerge(sceneLayer, Layer.succeed(CaptureSink, sink.api))
+}
+
+/** A composition queued to render, with the props its parent handed it. On the
+ *  structure path it also carries the slot-fill `key` it was mounted under, so the
+ *  facade can select a child by key (`byKey`); the legacy Node path omits it. */
+interface Mounted {
+  readonly comp: CompositionClass<unknown>
+  readonly props: unknown
+  readonly key?: string
+}
+
+const makeFacade = (
+  runtime: ManagedRuntime.ManagedRuntime<RuntimeServices, never>,
+  root: CompositionClass<unknown>,
+  sink: Sink,
+  // Records every event name dispatched through the facade, so a proof's
+  // requirement-declared event coverage can be verified after the body runs.
+  dispatched: Set<string>,
+): { readonly facade: AnyFacade; readonly settle: Effect.Effect<void, never, CompositionService> } => {
+  // Slot bindings (`provide(slot, composition)`) are static, so resolve the
+  // whole child tree once, up front — keeping `renderTree` and slot navigation
+  // synchronous (no nested runtime drive).
+  const bindings = new Map<SlotClass, CompositionClass<unknown>>()
+  // A slot's child is a plain composition or a `FeatureBinding`. A proof drives the
+  // composition the feature mounts; for a `default` feature that composition's logic
+  // is already live (its eager `.live` was merged into the scene by `provide`), so
+  // unwrapping is all that's needed. (Driving a `lazy` feature — load gap +
+  // placeholders — is the proof host's Part B increment; until then a scene wires
+  // 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)
+      }
+    })
+  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)
+      }
+      yield* renderLevel(next)
+    })
+
+  // Consume a `Structure` frame: record the node's computed props (the structure
+  // value already holds them — the proof never derives them from a view) AND the
+  // event triggers it carries on `structure.events` (plan 03b), then enqueue one
+  // child per slot fill with the per-item props the fill carries. Recording the
+  // events into the capture the same way the view path does means `triggerOf` /
+  // `app.actions` resolve identically for Structure frames; the index-keyed enqueue
+  // order matches the legacy node walk.
+  const driveStructure = (
+    comp: CompositionClass<unknown>,
+    structure: Structure<UiContract>,
+    next: Array<Mounted>,
+    key: string | undefined,
+  ): void => {
+    sink.api.record({
+      name: uiNameOf(comp),
+      props: structure.props,
+      events: eventsOf(structure),
+      ...(key !== undefined ? { key } : {}),
+    })
+    const fills: Record<string, SlotFill<unknown>> = structure.slots
+    for (const [slotName, fill] of Object.entries(fills)) {
+      const slotClass = comp.manifest.slots?.[slotName]
+      const child = slotClass && bindings.get(slotClass)
+      if (child === undefined) continue
+      enqueueFill(slotName, fill, child, next)
+    }
+  }
+
+  // Expand one slot fill into the children to render next. `Each` mounts one
+  // child per keyed item with that item's props and key; `One` mounts a single
+  // child under a synthesized singleton key; `Absent` mounts nothing (the
+  // data-driven `cond && …`). The key rides each `Mounted` so the child's capture
+  // can record it, letting the facade select by key (`byKey`).
+  const enqueueFill = (
+    slotName: string,
+    fill: SlotFill<unknown>,
+    child: CompositionClass<unknown>,
+    next: Array<Mounted>,
+  ): void => {
+    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.exhaustive,
+    )
+  }
+
+  const renderTree: Effect.Effect<void, never, CompositionService> = Effect.gen(function* () {
+    sink.reset()
+    yield* renderLevel([{ comp: root, props: {} }])
+  })
+
+  const capturesFor = (name: string): ReadonlyArray<UiCapture> =>
+    sink.captures.filter((capture) => capture.name === name)
+
+  // 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 =>
+    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
+      yield* settleDrain
+      yield* Effect.sleep(SETTLE_STEP)
+      yield* renderTree
+      const current = fingerprint()
+      if (current === previous) return
+      yield* settleFrom(current, remaining - 1)
+    })
+  const settle: Effect.Effect<void, never, CompositionService> = Effect.gen(function* () {
+    yield* settleDrain
+    yield* renderTree
+    yield* settleFrom(fingerprint(), 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 propsFor = (name: string, index: number): Effect.Effect<unknown, never, CompositionService> =>
+    Effect.map(renderTree, () => capturesFor(name)[index]?.props)
+
+  const nodeFacade = (name: string, index: number, comp: CompositionClass<unknown>): AnyFacade => ({
+    props: propsFor(name, index),
+    // Assert the computed props match a typed subset. Reuses the same partial-match
+    // logic as `expect(...).toMatchObject`; throws `AssertionFailed` on mismatch.
+    expectProps: (partial) =>
+      propsFor(name, index).pipe(
+        Effect.flatMap((props) => {
+          const mismatch = matchProps(props, partial)
+          return mismatch === undefined
+            ? Effect.void
+            : Effect.sync(() => {
+                throw new AssertionFailed({ detail: mismatch })
+              })
+        }),
+      ),
+    // `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).
+    actions: keyed(
+      (event): Action =>
+        (payload) =>
+          renderTree.pipe(
+            Effect.flatMap(() =>
+              Effect.sync(() => {
+                dispatched.add(event)
+                triggerOf(name, index, event)(payload)
+              }),
+            ),
+            Effect.flatMap(() => settle),
+            Effect.flatMap(() => propsFor(name, index)),
+          ),
+    ) as AnyFacade['actions'],
+    slots: keyed((slotName) => slotFacade(comp, slotName)) as AnyFacade['slots'],
+    frame: settle,
+  })
+
+  const slotFacade = (parent: CompositionClass<unknown>, slotName: string): AnySlotFacade => {
+    const slotClass = parent.manifest.slots?.[slotName]
+    const child = slotClass && bindings.get(slotClass)
+    if (child === undefined) {
+      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)
+    // 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
+    }
+    return {
+      first: at(0),
+      at,
+      all: Effect.map(renderTree, () =>
+        capturesFor(childName).map((_capture, index) => nodeFacade(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)),
+      // 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)] : [],
+          ),
+        ),
+      // How many children this slot mounted this frame — the fill length.
+      count: Effect.map(renderTree, () => capturesFor(childName).length),
+      // Used directly, a slot behaves as its first instance.
+      props: first.props,
+      expectProps: first.expectProps,
+      actions: first.actions,
+      slots: first.slots,
+      frame: first.frame,
+    }
+  }
+
+  return { facade: nodeFacade(uiNameOf(root), 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))
+}
+
+/**
+ * Run one proof against a fresh runtime, returning its pass/fail result. Each
+ * proof gets its own isolated environment, so nothing leaks between proofs. Boots
+ * the scene as the host would, settles, then runs the proof body to completion.
+ */
+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 { 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),
+      ),
+    )
+    await runtime.runPromise(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()
+  }
+}
+
+/**
+ * Drive one proof a step at a time, recording a `StepFrame` after each yielded
+ * effect settles. Reuses the same makeFacade runtime/facade/settle as
+ * `executeProof`, but instead of handing the body to `Effect.gen` (which runs it
+ * to completion), it pumps the generator by hand — `gen.next(value)` yields the
+ * next effect, we run it on the live runtime, snapshot the sink, and feed the
+ * result back. So the editor gets the per-step timeline with no change to the
+ * proof authoring API.
+ */
+export const driveProof = async (proof: Proof): Promise<DriveResult> => {
+  const sink = makeSink()
+  const runtime = ManagedRuntime.make(proofLayer(proof.scene, sink))
+  const frames: Array<StepFrame> = []
+  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 { 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),
+      ),
+    )
+    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()
+  }
+}

package/src/errors.ts

@@ -0,0 +1,56 @@
+import { type Cause, Data } from 'effect'
+
+/**
+ * Tagged errors for the proof harness. A failed assertion or a malformed proof
+ * navigation throws one of these — tagged and structured, never a bare `Error` —
+ * so a runner can distinguish an assertion failure from a harness misuse.
+ */
+
+/**
+ * The constructor shape `Data.TaggedError(tag)<A>` produces, named so the
+ * generated `.d.ts` can describe the `extends` base under `isolatedDeclarations`
+ * (which forbids an inferred expression in an extends clause).
+ */
+type TaggedErrorClass<Tag extends string, A extends Record<string, unknown>> = new (
+  args: A,
+) => Cause.YieldableError & { readonly _tag: Tag } & Readonly<A>
+
+const AssertionFailedBase: TaggedErrorClass<
+  'reform-proof/AssertionFailed',
+  { readonly detail: string }
+> = Data.TaggedError('reform-proof/AssertionFailed')<{ readonly detail: string }>
+
+/** An `expect(...)` matcher did not hold. */
+export class AssertionFailed extends AssertionFailedBase {
+  override get message(): string {
+    return `reform-proof: assertion failed — ${this.detail}`
+  }
+}
+
+const UnknownActionBase: TaggedErrorClass<
+  'reform-proof/UnknownAction',
+  { readonly composition: string; readonly action: string; readonly rendered: number }
+> = Data.TaggedError('reform-proof/UnknownAction')<{
+  readonly composition: string
+  readonly action: string
+  readonly rendered: number
+}>
+
+/** A proof referenced an action the rendered composition never exposed. */
+export class UnknownAction extends UnknownActionBase {
+  override get message(): string {
+    return `reform-proof: '${this.composition}' has no action '${this.action}' (rendered ${this.rendered} instance(s))`
+  }
+}
+
+const UnknownSlotBase: TaggedErrorClass<
+  'reform-proof/UnknownSlot',
+  { readonly parent: string; readonly slot: string }
+> = Data.TaggedError('reform-proof/UnknownSlot')<{ readonly parent: string; readonly slot: string }>
+
+/** A proof navigated into a slot the parent composition does not declare. */
+export class UnknownSlot extends UnknownSlotBase {
+  override get message(): string {
+    return `reform-proof: '${this.parent}' has no slot '${this.slot}'`
+  }
+}