@playfast/reform-proof 0.1.0 → 1.1.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@playfast/reform-proof",
   "playbook": "./playbook",
-  "version": "0.1.0",
+  "version": "1.1.1",
   "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/assertions.ts

@@ -0,0 +1,65 @@
+import { Array as Arr, Effect, Option, Record as Rec } from 'effect'
+import { AssertionFailed } from './errors'
+
+interface ComparePair {
+  readonly left: unknown
+  readonly right: unknown
+}
+
+// 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.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 ${show(actual)} to be ${show(expected)}`),
+  toEqual: (expected: A): Effect.Effect<void> =>
+    deepEqual({ left: actual, right: expected })
+      ? Effect.void
+      : 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((element) => deepEqual({ left: element, right: expected }))
+      ? Effect.void
+      : fail(`expected ${show(actual)} to contain ${show(expected)}`),
+  toMatchObject: (expected: Partial<A>): Effect.Effect<void> => {
+    const mismatch = matchPartial({ actual, expected })
+    return mismatch === undefined ? Effect.void : fail(mismatch)
+  },
+})
+
+const isRecord = (candidate: unknown): candidate is Record<string, unknown> =>
+  typeof candidate === 'object' && candidate !== null
+
+interface MatchInput {
+  readonly actual: unknown
+  readonly expected: unknown
+}
+
+const matchPartial = ({ actual, expected }: MatchInput): string | undefined => {
+  if (!isRecord(expected)) {
+    return deepEqual({ left: actual, right: expected })
+      ? undefined
+      : `expected ${show(actual)} to match ${show(expected)}`
+  }
+  if (!isRecord(actual)) {
+    return `expected ${show(actual)} to be an object matching ${show(expected)}`
+  }
+  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])}`,
+  })
+}
+
+export const matchProps: (input: MatchInput) => string | undefined = matchPartial

package/src/driverTypes.ts

@@ -0,0 +1,19 @@
+import type { UiCapture } from '@playfast/reform'
+
+export interface StepFrame {
+  readonly index: number
+  readonly captures: ReadonlyArray<UiCapture>
+}
+
+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
+}
+
+export interface ProofDriver {
+  readonly requirement: string
+  readonly run: () => Promise<DriveResult>
+}

package/src/engine.ts

@@ -1,520 +1,8 @@
-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 {
-  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: (_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
-// `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>> => ({
-  ...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.
-export interface Sink {
-  readonly api: CaptureSinkApi
-  readonly captures: ReadonlyArray<UiCapture>
-  reset(): void
-}
-
-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 = [...state.captures, capture]
-      },
-    },
-    get captures() {
-      return state.captures
-    },
-    reset: () => {
-      state.captures = []
-    },
-  }
-}
-
-export 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.
- */
-export const proofLayer = (scene: Scene, sink: Sink): 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))
-}
-
-/** 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: 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 = (
-  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 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))
-
-  // 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
-      }
-      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
-  // 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>,
-    key: Option.Option<string>,
-  ): ReadonlyArray<Mounted> => {
-    sink.api.record({
-      name: uiNameOf(comp),
-      props: structure.props,
-      events: eventsOf(structure),
-      ...(Option.isSome(key) ? { key: key.value } : {}),
-    })
-    const fills: Record<string, SlotFill<unknown>> = structure.slots
-    return Rec.toEntries(fills).flatMap(([slotName, fill]) => {
-      const slotClass = comp.manifest.slots?.[slotName]
-      const child = slotClass && bindings.get(slotClass)
-      return child === undefined ? [] : enqueueFill(slotName, fill, child)
-    })
-  }
-
-  // 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>,
-  ): ReadonlyArray<Mounted> =>
-    Match.value(fill).pipe(
-      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: {}, key: Option.none() }])
-  })
-
-  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 =>
-    // 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: (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 === 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({ previous: fingerprint(), remaining: SETTLE_MAX_RENDERS })
-  })
-
-  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 = (ref: NodeRef): Effect.Effect<unknown, never, CompositionService> =>
-    Effect.map(renderTree, () => capturesFor(ref.name)[ref.index]?.props)
-
-  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`; dies with `AssertionFailed` on mismatch.
-    expectProps: (partial) =>
-      propsFor(ref).pipe(
-        Effect.flatMap((props) => {
-          const mismatch = matchProps({ actual: props, expected: partial })
-          return mismatch === undefined
-            ? Effect.void
-            : Effect.dieMessage(new AssertionFailed({ detail: mismatch }).message)
-        }),
-      ),
-    // `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(() => triggerOf(ref, event)),
-            Effect.flatMap((trigger) =>
-              Effect.sync(() => {
-                dispatched.add(event)
-                trigger(payload)
-              }),
-            ),
-            Effect.flatMap(() => settle),
-            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,
-  })
-
-  const slotFacade = (parent: CompositionClass<unknown>, slotName: string): AnySlotFacade => {
-    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 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 — `none` when no fill carries it.
-    const indexOfKey = (key: string): Option.Option<number> =>
-      Arr.findFirstIndex(capturesFor(childName), (capture) => capture.key === key)
-    return {
-      first: atIndex(0),
-      at: atIndex,
-      all: Effect.map(renderTree, () =>
-        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;
-      // 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({ name: 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({ 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> =>
-  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
- * 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>()
-  const statement = proof.requirement.manifest.statement
-  const program = Effect.gen(function* () {
-    const { facade, settle } = makeFacade(runtime, proof.scene.composition, sink, dispatched)
-    yield* Effect.forEach(
-      Option.getOrElse(Option.fromNullable(proof.scene.boot), () => []),
-      (event) => publish('High', event),
-    )
-    yield* settle
-    yield* Effect.gen(() => proof.body(facade))
-    const missing = missingCoverage(proof, dispatched)
-    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
-}
-
-/**
- * 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 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>()
-  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)
-    yield* Effect.forEach(
-      Option.getOrElse(Option.fromNullable(proof.scene.boot), () => []),
-      (event) => publish('High', event),
-    )
-    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
-}
+export { makeFacade, makeFacadeEffect } from './facade'
+export { makeRuntimeHandleFacade } from './runtimeFacade'
+export type { MountedFacade, MountedSlotFacade } from './runtimeFacade'
+export { makeRuntimeTreeFacade } from './runtimeTreeFacade'
+export type { RuntimeTreeFacade } from './runtimeTreeTypes'
+export { makeSink, proofLayer } from './sink'
+export type { RuntimeServices, Sink } from './sink'
+export { driveProof, executeProof } from './execution'

package/src/errors.ts

@@ -1,16 +1,5 @@
 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>
@@ -20,7 +9,6 @@ const AssertionFailedBase: TaggedErrorClass<
   { 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}`
@@ -36,7 +24,6 @@ const UnknownActionBase: TaggedErrorClass<
   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))`
@@ -48,7 +35,6 @@ const UnknownSlotBase: TaggedErrorClass<
   { 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}'`