@playfast/reform-proof 1.0.1 → 1.1.1

package/src/engine.ts

@@ -1,589 +1,8 @@
-import {
-  Array as Arr,
-  Cause,
-  Effect,
-  Layer,
-  ManagedRuntime,
-  Match,
-  MutableRef,
-  Option,
-  Record as Rec,
-  Ref,
-} from 'effect'
-import { yieldWrapGet } from 'effect/Utils'
-import { AssertionFailed, UnknownAction, UnknownSlot } from './errors'
-import {
-  Bus,
-  CaptureSink,
-  type CaptureSinkApi,
-  Composition,
-  type CompositionClass,
-  type CompositionService,
-  type Instrumentation,
-  isFeatureBinding,
-  isStructure,
-  noopInstrumentation,
-  publish,
-  type RenderEnv,
-  type Scene,
-  sceneInstrumentation,
-  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>
-  /** The scene's profiling hooks — render spans record here (noop unless `profileScene`d). */
-  readonly instrumentation: Instrumentation
-  reset(): void
-}
-
-export const makeSink = (instrumentation: Instrumentation = noopInstrumentation): Sink => {
-  // CaptureSink.record is synchronous, so this uses MutableRef rather than Ref.
-  const captures = MutableRef.make<UiCapture[]>([])
-  return {
-    api: {
-      record: (capture) => {
-        MutableRef.update(captures, (current) => [...current, capture])
-      },
-    },
-    get captures() {
-      return MutableRef.get(captures)
-    },
-    instrumentation,
-    reset: () => {
-      MutableRef.set(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, remaining renders, and early-stop state. */
-interface SettleProgress {
-  readonly previous: string
-  readonly remaining: number
-  readonly stable: boolean
-}
-
-/** 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
-}
-
-// 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
-
-/** A composition's declared slot map, defaulting to an empty record when it declares none. */
-const slotsOf = (comp: CompositionClass<unknown>): Record<string, SlotClass> =>
-  Option.getOrElse(Option.fromNullable(comp.manifest.slots), () => ({}))
-
-// Narrow an erased slot value to a `SlotFill` by its discriminant. `Structure<
-// UiContract>` erases its per-slot fill types at this boundary, so recover them
-// structurally before traversing.
-const isSlotFill = (candidate: unknown): candidate is SlotFill<unknown> =>
-  typeof candidate === 'object' &&
-  candidate !== null &&
-  '_tag' in candidate &&
-  (candidate._tag === 'Each' || candidate._tag === 'One' || candidate._tag === 'Absent')
-
-const structureFills = (structure: Structure<UiContract>): Record<string, SlotFill<unknown>> =>
-  Rec.fromEntries(
-    Rec.toEntries(structure.slots).flatMap(([slotName, fillValue]) =>
-      isSlotFill(fillValue) ? [[slotName, fillValue] as const] : [],
-    ),
-  )
-
-// 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 collectBindings = Effect.fn('collectBindings')(function* (
-  root: CompositionClass<unknown>,
-): Effect.fn.Return<Map<SlotClass, CompositionClass<unknown>>, never, SlotChild> {
-  const bindings = new Map<SlotClass, CompositionClass<unknown>>()
-  const walk: (comp: CompositionClass<unknown>) => Effect.Effect<void, never, SlotChild> = Effect.fn(
-    'collectBindings.walk',
-  )(function* (comp: CompositionClass<unknown>): Effect.fn.Return<void, never, SlotChild> {
-    yield* Effect.forEach(Rec.values(slotsOf(comp)), (slotClass) =>
-      Effect.gen(function* () {
-        if (bindings.has(slotClass)) {
-          return
-        }
-        const child = childComposition(yield* slotClass.tag)
-        bindings.set(slotClass, child)
-        yield* walk(child)
-      }),
-    )
-  })
-  yield* walk(root)
-  return bindings
-})
-
-// 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.
-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,
-  )
-
-// Consume a `Structure` frame: record computed props and event triggers, then
-// enqueue one child per slot fill with the per-item props the fill carries.
-const driveStructure = (
-  comp: CompositionClass<unknown>,
-  structure: Structure<UiContract>,
-  key: Option.Option<string>,
-  sink: Sink,
-  bindings: ReadonlyMap<SlotClass, CompositionClass<unknown>>,
-): ReadonlyArray<Mounted> => {
-  sink.api.record({
-    name: uiNameOf(comp),
-    props: structure.props,
-    events: eventsOf(structure),
-    ...(Option.isSome(key) ? { key: key.value } : {}),
-  })
-  const fills = structureFills(structure)
-  return Rec.toEntries(slotsOf(comp)).flatMap(([slotName, slotClass]) => {
-    const child = bindings.get(slotClass)
-    const fill = fills[slotName]
-    return child === undefined || fill === undefined ? [] : enqueueFill(slotName, fill, child)
-  })
-}
-
-// 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).
-const renderMounted = Effect.fn('renderMounted')(function* (
-  mounted: Mounted,
-  bindings: ReadonlyMap<SlotClass, CompositionClass<unknown>>,
-  sink: Sink,
-): Effect.fn.Return<ReadonlyArray<Mounted>, never, CompositionService> {
-  const service = yield* mounted.comp.tag
-  const env: RenderEnv = { props: mounted.props, tracker: { add: () => {} } }
-  const endRenderSpan = sink.instrumentation.uiRendered(uiNameOf(mounted.comp))
-  const frame = yield* Composition.render(service, env)
-  endRenderSpan()
-  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, sink, bindings)
-})
-
-// 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.
-const renderLevel: (
-  frontier: ReadonlyArray<Mounted>,
-  bindings: ReadonlyMap<SlotClass, CompositionClass<unknown>>,
-  sink: Sink,
-) => Effect.Effect<void, never, CompositionService> = Effect.fn('renderLevel')(function* (
-  frontier: ReadonlyArray<Mounted>,
-  bindings: ReadonlyMap<SlotClass, CompositionClass<unknown>>,
-  sink: Sink,
-): Effect.fn.Return<void, never, CompositionService> {
-  if (frontier.length === 0) {
-    return
-  }
-  const levels = yield* Effect.forEach(frontier, (mounted) => renderMounted(mounted, bindings, sink))
-  yield* renderLevel(levels.flat(), bindings, sink)
-})
-
-const renderTree = Effect.fn('renderTree')(function* (
-  root: CompositionClass<unknown>,
-  bindings: ReadonlyMap<SlotClass, CompositionClass<unknown>>,
-  sink: Sink,
-): Effect.fn.Return<void, never, CompositionService> {
-  sink.reset()
-  yield* renderLevel([{ comp: root, props: {}, key: Option.none() }], bindings, sink)
-})
-
-const capturesFor = (sink: Sink, 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 = (sink: Sink): 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]))
-
-const settleTree = Effect.fn('settleTree')(function* (
-  root: CompositionClass<unknown>,
-  bindings: ReadonlyMap<SlotClass, CompositionClass<unknown>>,
-  sink: Sink,
-): Effect.fn.Return<void, never, CompositionService> {
-  yield* settleDrain
-  yield* renderTree(root, bindings, sink)
-  yield* Effect.iterate(
-    { previous: fingerprint(sink), remaining: SETTLE_MAX_RENDERS, stable: false },
-    {
-      while: (progress: SettleProgress) => !progress.stable && progress.remaining > 0,
-      body: (progress) =>
-        Effect.gen(function* () {
-          yield* settleDrain
-          yield* Effect.sleep(SETTLE_STEP)
-          yield* renderTree(root, bindings, sink)
-          const current = fingerprint(sink)
-          return {
-            previous: current,
-            remaining: progress.remaining - 1,
-            stable: current === progress.previous,
-          }
-        }),
-    },
-  )
-})
-
-const makeFacadeEffect = Effect.fn('makeFacadeEffect')(function* (
-  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>,
-): Effect.fn.Return<
-  { readonly facade: AnyFacade; readonly settle: Effect.Effect<void, never, CompositionService> },
-  never,
-  SlotChild
-> {
-  const bindings = yield* collectBindings(root)
-  const settle = settleTree(root, bindings, sink)
-  const rerender = renderTree(root, bindings, sink)
-
-  const triggerOf = (ref: NodeRef, event: string): Effect.Effect<Trigger<unknown>> =>
-    Option.match(Option.fromNullable(capturesFor(sink, ref.name)[ref.index]?.events[event]), {
-      onNone: () =>
-        Effect.dieMessage(
-          new UnknownAction({
-            composition: ref.name,
-            action: event,
-            rendered: capturesFor(sink, ref.name).length,
-          }).message,
-        ),
-      onSome: Effect.succeed,
-    })
-
-  const propsFor = (ref: NodeRef): Effect.Effect<unknown, never, CompositionService> =>
-    Effect.map(rerender, () => capturesFor(sink, 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) =>
-          rerender.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 = slotsOf(parent)[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(rerender, 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(sink, childName), (capture) => capture.key === key)
-    return {
-      first: atIndex(0),
-      at: atIndex,
-      all: Effect.map(rerender, () =>
-        capturesFor(sink, 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(rerender, () =>
-          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(rerender, () =>
-          capturesFor(sink, 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(rerender, () => capturesFor(sink, 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 }
-})
-
-export const makeFacade = (
-  runtime: ManagedRuntime.ManagedRuntime<RuntimeServices, never>,
-  root: CompositionClass<unknown>,
-  sink: Sink,
-  dispatched: Set<string>,
-): { readonly facade: AnyFacade; readonly settle: Effect.Effect<void, never, CompositionService> } =>
-  runtime.runSync(makeFacadeEffect(root, sink, dispatched))
-
-/** 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)),
-  })
-
-const bootScene = (scene: Scene): Effect.Effect<void, never, Bus> =>
-  Effect.forEach(
-    Option.getOrElse(Option.fromNullable(scene.boot), () => []),
-    (event) => publish('High', event),
-  ).pipe(Effect.asVoid)
-
-const executeProofEffect = Effect.fn('executeProofEffect')(function* (
-  proof: Proof,
-  sink: Sink,
-): Effect.fn.Return<ProofResult, never, RuntimeServices> {
-  const dispatched = new Set<string>()
-  const statement = proof.requirement.manifest.statement
-  return yield* Effect.gen(function* () {
-    const { facade, settle } = yield* makeFacadeEffect(proof.scene.composition, sink, dispatched)
-    yield* bootScene(proof.scene)
-    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)) }),
-    ),
-  )
-})
-
-/**
- * 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(sceneInstrumentation(proof.scene))
-  return Effect.runPromise(executeProofEffect(proof, sink).pipe(Effect.provide(proofLayer(proof.scene, sink))))
-}
-
-/**
- * Drive one proof a step at a time, recording a `StepFrame` after each yielded
- * effect settles. Reuses the same facade/settle engine 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, the
- * active proof layer runs it, then the driver snapshots the sink and feeds the
- * result back. So the editor gets the per-step timeline with no change to the
- * proof authoring API.
- */
-const driveProofEffect = Effect.fn('driveProofEffect')(function* (
-  proof: Proof,
-  sink: Sink,
-): Effect.fn.Return<DriveResult, never, RuntimeServices> {
-  const frames = yield* Ref.make<ReadonlyArray<StepFrame>>([])
-  const statement = proof.requirement.manifest.statement
-  // The driver's per-frame timeline does not enforce coverage; collect into a
-  // throwaway set so `makeFacadeEffect`'s contract is satisfied.
-  const dispatched = new Set<string>()
-  const record = (index: number): Effect.Effect<void> =>
-    Ref.update(frames, (current) => [...current, { 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* record(step.index)
-    yield* pump(generator, { input: output, index: step.index + 1 })
-  })
-  return yield* Effect.gen(function* () {
-    const { facade, settle } = yield* makeFacadeEffect(proof.scene.composition, sink, dispatched)
-    yield* bootScene(proof.scene)
-    yield* settle
-    yield* record(0)
-    yield* pump(proof.body(facade), { input: undefined, index: 1 })
-    return { requirement: statement, frames: yield* Ref.get(frames), ok: true }
-  }).pipe(
-    Effect.catchAllCause((cause) =>
-      Ref.get(frames).pipe(
-        Effect.map((collected) => ({
-          requirement: statement,
-          frames: collected,
-          ok: false,
-          error: messageOf(Cause.squash(cause)),
-        })),
-      ),
-    ),
-  )
-})
-
-export const driveProof = async (proof: Proof): Promise<DriveResult> => {
-  const sink = makeSink(sceneInstrumentation(proof.scene))
-  return Effect.runPromise(driveProofEffect(proof, sink).pipe(Effect.provide(proofLayer(proof.scene, sink))))
-}
+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}'`