@playfast/reform-proof 1.1.1 → 1.2.1

package/README.md

@@ -13,7 +13,7 @@ Drive a scene's compositions and assert on what they compute — deterministical
 
 ---
 
-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.
+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
 
@@ -39,27 +39,27 @@ const CounterScene = scene(Counter, { provide: [CounterLive] })
 class Bumps extends ProductRequirement.make(Counter, 'bumps the count') {}
 
 const bumps = Proof.implement(Bumps, CounterScene, function* (app) {
-  yield* app.actions.bump({})         // dispatch a contract event, settle
-  const props = yield* app.props      // read what the composition computed
+  yield* app.actions.bump({}) // dispatch a contract event, settle
+  const props = yield* app.props // read what the composition computed
   yield* expect(props.count).toBe(1)
 })
 
 const product = Product.make(Counter, { requirements: [Bumps] })
 const suite = Proof.suite(product, { proofs: [bumps] })
 
-const result = await Proof.run(suite)  // { product, results, ok }
+const result = await Proof.run(suite) // { product, results, ok }
 ```
 
 ## The workflow
 
-| step | API |
-| --- | --- |
-| Declare a requirement | `ProductRequirement.make(composition, statement)` |
-| Group requirements | `Product.make(composition, { requirements })` |
-| Implement a proof | `Proof.implement(requirement, scene, function* (app) { … })` |
-| Compose a suite | `Proof.suite(product, { proofs })` |
-| Run it | `Proof.run(suite) → Promise<SuiteResult>` |
-| Step it (for tooling) | `Proof.driver(suite) → ProofDriver[]` |
+| step                  | API                                                          |
+| --------------------- | ------------------------------------------------------------ |
+| Declare a requirement | `ProductRequirement.make(composition, statement)`            |
+| Group requirements    | `Product.make(composition, { requirements })`                |
+| Implement a proof     | `Proof.implement(requirement, scene, function* (app) { … })` |
+| Compose a suite       | `Proof.suite(product, { proofs })`                           |
+| Run it                | `Proof.run(suite) → Promise<SuiteResult>`                    |
+| Step it (for tooling) | `Proof.driver(suite) → ProofDriver[]`                        |
 
 The `statement` is a string-literal type, matched at `Proof.implement` so a requirement's name and its proof can never drift apart.
 

package/package.json

@@ -1,35 +1,37 @@
 {
   "name": "@playfast/reform-proof",
-  "playbook": "./playbook",
-  "version": "1.1.1",
-  "type": "module",
+  "version": "1.2.1",
   "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": [
-    "reform",
     "effect",
-    "testing",
     "headless",
-    "proof"
+    "proof",
+    "reform",
+    "testing"
   ],
+  "bugs": {
+    "url": "https://github.com/playfast/reform/issues"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/playfast/reform.git",
     "directory": "packages/proof"
   },
-  "bugs": {
-    "url": "https://github.com/playfast/reform/issues"
-  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "type": "module",
   "sideEffects": false,
   "exports": {
     "./package.json": "./package.json",
     ".": "./src/index.ts",
     "./*": "./src/*.ts"
   },
-  "files": [
-    "src",
-    "README.md"
-  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "clean": "rm -rf dist .tsbuildinfo",
     "check": "tsc --noEmit",
@@ -41,11 +43,9 @@
     "lint:fix": "oxlint --fix src"
   },
   "peerDependencies": {
+    "@playfast/reform": "*",
     "effect": "*",
-    "react": "^19.0.0",
-    "@playfast/reform": "*"
+    "react": "^19.0.0"
   },
-  "publishConfig": {
-    "access": "public"
-  }
+  "playbook": "./playbook"
 }

package/src/{assertions.ts → assert.ts}

@@ -1,13 +1,13 @@
 import { Array as Arr, Effect, Option, Record as Rec } from 'effect'
 import { AssertionFailed } from './errors'
+import { formatFingerprint } from './fingerprint'
 
 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 show = (subject: unknown): string => formatFingerprint(subject)
 
 const deepEqual = ({ left, right }: ComparePair): boolean =>
   Object.is(left, right) || show(left) === show(right)
@@ -34,7 +34,7 @@ export const expect = <A>(actual: A) => ({
   },
 })
 
-const isRecord = (candidate: unknown): candidate is Record<string, unknown> =>
+export const isRecord = (candidate: unknown): candidate is Record<string, unknown> =>
   typeof candidate === 'object' && candidate !== null
 
 interface MatchInput {

package/src/engine.ts

@@ -1,8 +1,285 @@
-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'
+import { Cause, Effect, Option, Record as Rec, Ref } from 'effect'
+import { yieldWrapGet } from 'effect/Utils'
+import {
+  type CapturedScene,
+  type CompositionClass,
+  makeAppRuntime,
+  sceneInstrumentation,
+  type UiContract,
+} from '@playfast/reform'
+import { type AnyComposition, type AnyScene } from '@playfast/reform/internal'
+import {
+  invalidCompositionProps,
+  type HostRuntime,
+  makeSink,
+  messageOf,
+  type RenderRuntime,
+  type Sink,
+} from './engineSink'
+import { childComposition, readRuntimeSlotChild, slotsOf } from './engineTree'
+import type { RuntimeTreeFacade } from './engineTreeTypes'
+import { makeRuntimeTreeFacade } from './engineTreeFacade'
+import type { ProofCase, ProofResult } from './proofCase'
+import type { PumpStep } from './engineTree'
+import type { DriveResult, StepFrame } from './index'
+import type { ProductComposition } from './product'
+import type { Proof } from './index'
+
+export { makeSink } from './engineSink'
+export type { Sink } from './engineSink'
+export { proofLayer } from './engineTree'
+export { makeFacade, makeProofFacade, makeRuntimeHandleFacade } from './engineMounted'
+export type {
+  MountedFacade,
+  MountedSlotFacade,
+  MountedSlotFacadesOf,
+} from './engineSink'
+export { makeRuntimeTreeFacade } from './engineTreeFacade'
+export type { RuntimeTreeFacade } from './engineTreeTypes'
+
+const proofRootProps = <
+  P,
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  N extends string,
+  Identity,
+>(
+  composition: CompositionClass<P, C, S, N, Identity>,
+): Effect.Effect<P, never, never> =>
+  Option.match(composition.parseProps({}), {
+    onNone: () => Effect.dieMessage(invalidCompositionProps(composition)),
+    onSome: Effect.succeed,
+  })
+
+const withProofRuntimeTree = <
+  A,
+  E,
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  Services,
+  P,
+  N extends string,
+  Identity,
+>(
+  scene: CapturedScene<C, S, Services, P, N, Identity>,
+  sink: Sink,
+  dispatched: Set<string>,
+  use: (runtime: HostRuntime, tree: RuntimeTreeFacade<C>) => Effect.Effect<A, E, never>,
+): Effect.Effect<A, E, never> =>
+  Effect.acquireUseRelease(
+    Effect.sync(() => makeAppRuntime(scene)),
+    (runtime) =>
+      Effect.acquireUseRelease(
+        Effect.gen(function* () {
+          const rootProps = yield* proofRootProps(scene.composition)
+          yield* Effect.sync(() => runtime.boot())
+          return makeRuntimeTreeFacade(runtime, scene.composition, rootProps, sink, dispatched)
+        }),
+        (tree) => use(runtime, tree),
+        (tree) => Effect.sync(tree.dispose),
+      ),
+    (runtime) => Effect.sync(runtime.dispose),
+  )
+
+const missingCoverage = (
+  proof: Pick<Proof, 'requirement'>,
+  dispatched: Set<string>,
+): ReadonlyArray<string> =>
+  Option.match(proof.requirement.manifest.events, {
+    onNone: () => [],
+    onSome: (declared) => declared.map(String).filter((event) => !dispatched.has(event)),
+  })
+
+interface ProofPlacement {
+  readonly requirement: Proof['requirement']
+  readonly placement: 'Root' | 'Slot'
+}
+
+const compositionIdentity = (composition: AnyComposition): symbol =>
+  composition.capture<symbol>((exact) => exact.identity)
+
+const verifyProofPlacement = (
+  proof: ProofPlacement,
+  scene: AnyScene,
+  runtime: RenderRuntime,
+): Effect.Effect<void, never, never> => {
+  const expected = proof.requirement.manifest.composition
+  if (
+    proof.placement === 'Root' &&
+    Object.is(compositionIdentity(scene.composition), compositionIdentity(expected))
+  ) {
+    return Effect.void
+  }
+  if (proof.placement === 'Slot') {
+    const matches = Rec.values(slotsOf(scene.composition)).some((slotClass) => {
+      const child = childComposition(
+        readRuntimeSlotChild({
+          runtime,
+          slotDefinition: slotClass,
+          parent: scene.composition,
+        }),
+      )
+      return Object.is(compositionIdentity(child), compositionIdentity(expected))
+    })
+    if (matches) {
+      return Effect.void
+    }
+  }
+  const location = proof.placement === 'Root' ? 'scene root' : 'direct scene slot'
+  return Effect.dieMessage(
+    `reform-proof: requirement composition ${expected.manifest.name} is not the ${location} by definition identity`,
+  )
+}
+
+const executeProofWithSink = Effect.fn('executeProofWithSink')(function* <
+  Comp extends ProductComposition,
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  Services,
+  P,
+  N extends string,
+  Identity,
+>(
+  proof: ProofCase<Comp, C, S, Services, P, N, Identity>,
+  scene: CapturedScene<C, S, Services, P, N, Identity>,
+  sink: Sink,
+): Effect.fn.Return<ProofResult, never, never> {
+  const dispatched = new Set<string>()
+  const statement = proof.requirement.manifest.statement
+  const runGenerator = Effect.fn('runProofGenerator')(function* (
+    generator: ReturnType<typeof proof.body>,
+    input: unknown,
+    settleEffect: Effect.Effect<void, never, never>,
+  ): Effect.fn.Return<void, unknown, never> {
+    const next = generator.next(input)
+    if (next.done === true) {
+      return
+    }
+    const output = yield* yieldWrapGet(next.value)
+    yield* settleEffect
+    yield* runGenerator(generator, output, settleEffect)
+  })
+  return yield* withProofRuntimeTree(scene, sink, dispatched, (runtime, tree) =>
+    Effect.gen(function* () {
+      yield* verifyProofPlacement(proof, scene, runtime)
+      yield* tree.settle
+      yield* runGenerator(proof.body(tree.facade), undefined, tree.settle)
+      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, error: undefined }
+    }),
+  ).pipe(
+    Effect.catchAllCause((cause) =>
+      Effect.succeed({
+        requirement: statement,
+        ok: false,
+        error: messageOf(Cause.squash(cause)),
+      }),
+    ),
+  )
+})
+
+export const executeProofEffect = (proof: Proof): Effect.Effect<ProofResult, never, never> =>
+  proof.capture(
+    <
+      Comp extends ProductComposition,
+      C extends UiContract,
+      S extends ReadonlyArray<unknown>,
+      Services,
+      P,
+      N extends string,
+      Identity,
+    >(
+      exact: ProofCase<Comp, C, S, Services, P, N, Identity>,
+    ): Effect.Effect<ProofResult, never, never> => {
+      const sink = makeSink(sceneInstrumentation(exact.scene))
+      return executeProofWithSink<Comp, C, S, Services, P, N, Identity>(exact, exact.scene, sink)
+    },
+  )
+
+export const executeProof = (proof: Proof): Promise<ProofResult> =>
+  Effect.runPromise(executeProofEffect(proof))
+
+const driveProofWithSink = Effect.fn('driveProofWithSink')(function* <
+  Comp extends ProductComposition,
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  Services,
+  P,
+  N extends string,
+  Identity,
+>(
+  proof: ProofCase<Comp, C, S, Services, P, N, Identity>,
+  scene: CapturedScene<C, S, Services, P, N, Identity>,
+  sink: Sink,
+): Effect.fn.Return<DriveResult, never, never> {
+  const frames = yield* Ref.make<ReadonlyArray<StepFrame>>([])
+  const statement = proof.requirement.manifest.statement
+  // Driving tracks dispatches for the facade without enforcing coverage.
+  const dispatched = new Set<string>()
+  const record = (index: number): Effect.Effect<void> =>
+    Ref.update(frames, (current) => [...current, { index, captures: [...sink.captures] }])
+  const pump = Effect.fn('pump')(function* (
+    generator: ReturnType<typeof proof.body>,
+    step: PumpStep,
+    settleEffect: Effect.Effect<void, never, never>,
+  ): Effect.fn.Return<void, unknown, never> {
+    const next = generator.next(step.input)
+    if (next.done === true) {
+      return
+    }
+    const output = yield* yieldWrapGet(next.value)
+    yield* settleEffect
+    yield* record(step.index)
+    yield* pump(generator, { input: output, index: step.index + 1 }, settleEffect)
+  })
+  return yield* withProofRuntimeTree(scene, sink, dispatched, (runtime, tree) =>
+    Effect.gen(function* () {
+      yield* verifyProofPlacement(proof, scene, runtime)
+      yield* tree.settle
+      yield* record(0)
+      yield* pump(proof.body(tree.facade), { input: undefined, index: 1 }, tree.settle)
+      return {
+        requirement: statement,
+        frames: yield* Ref.get(frames),
+        ok: true,
+        error: undefined,
+      }
+    }),
+  ).pipe(
+    Effect.catchAllCause((cause) =>
+      Ref.get(frames).pipe(
+        Effect.map((collected) => ({
+          requirement: statement,
+          frames: collected,
+          ok: false,
+          error: messageOf(Cause.squash(cause)),
+        })),
+      ),
+    ),
+  )
+})
+
+export const driveProofEffect = (proof: Proof): Effect.Effect<DriveResult, never, never> =>
+  proof.capture(
+    <
+      Comp extends ProductComposition,
+      C extends UiContract,
+      S extends ReadonlyArray<unknown>,
+      Services,
+      P,
+      N extends string,
+      Identity,
+    >(
+      exact: ProofCase<Comp, C, S, Services, P, N, Identity>,
+    ): Effect.Effect<DriveResult, never, never> => {
+      const sink = makeSink(sceneInstrumentation(exact.scene))
+      return driveProofWithSink<Comp, C, S, Services, P, N, Identity>(exact, exact.scene, sink)
+    },
+  )
+
+export const driveProof = (proof: Proof): Promise<DriveResult> =>
+  Effect.runPromise(driveProofEffect(proof))
+