@playfast/reform-proof 0.0.8 → 0.0.10

package/package.json

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

package/src/engine.ts

@@ -1,7 +1,6 @@
-import { Effect, Layer, ManagedRuntime } from 'effect'
+import { Effect, Layer, Match, ManagedRuntime } from 'effect'
 import { yieldWrapGet } from 'effect/Utils'
-import { isValidElement } from 'react'
-import { UnknownAction, UnknownSlot } from './errors'
+import { AssertionFailed, UnknownAction, UnknownSlot } from './errors'
 import {
   Bus,
   CaptureSink,
@@ -10,26 +9,26 @@ import {
   type CompositionClass,
   type CompositionService,
   isFeatureBinding,
-  type Node,
+  isStructure,
   publish,
   type RenderEnv,
   type Scene,
   type SlotChild,
   type SlotClass,
-  type SlotHost,
+  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 reconciler, no
-// text matching. A proof never renders through React — props are recorded by
-// reform's Effect composition logic, and the only view code this engine runs is the
-// pure `(props, slots, events) => Node` body. `executeProof`/`driveProof` are the
-// two seams the `ProofRunner` layer exposes (see ./runner): one runs a proof to
-// completion, the other steps it a frame at a time for the editor's timeline.
+// 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>
@@ -60,13 +59,23 @@ const keyed = <V>(get: (key: string) => V): Record<string, V> => {
 
 const uiNameOf = (comp: CompositionClass<unknown>): string => comp.manifest.ui.manifest.name
 
-interface Sink {
+// 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 ?? {}))
+
+// 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
 }
 
-const makeSink = (): Sink => {
+export const makeSink = (): Sink => {
   // A const holder whose array we swap on reset (no reassigned binding).
   const state: { captures: UiCapture[] } = { captures: [] }
   return {
@@ -80,7 +89,7 @@ const makeSink = (): Sink => {
   }
 }
 
-type RuntimeServices = CompositionService | SlotChild | Bus
+export type RuntimeServices = CompositionService | SlotChild | Bus
 
 /**
  * Build a proof's runtime layer: the scene's closed wiring with the capture sink
@@ -92,45 +101,29 @@ type RuntimeServices = CompositionService | SlotChild | Bus
  * 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> => {
+export const proofLayer = (scene: Scene, sink: Sink): Layer.Layer<RuntimeServices, never, never> => {
   const sceneLayer = scene.provide.reduce((a, b) =>
     Layer.merge(a, b),
   ) as unknown as Layer.Layer<RuntimeServices, never, never>
   return Layer.provideMerge(sceneLayer, Layer.succeed(CaptureSink, sink.api))
 }
 
-/** A composition queued to render, with the props its parent handed it. */
+/** 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
 }
 
-/**
- * Walk a rendered node tree and invoke any slot components it contains (JSX
- * defers them to the host; headless we drive them ourselves), enqueuing the
- * child each stands for. Slot components are matched by identity, so this never
- * calls — and never needs hooks from — ordinary components.
- */
-const drive = (node: Node, enqueueBy: Map<Function, (props: unknown) => void>): void => {
-  if (Array.isArray(node)) {
-    for (const child of node) drive(child, enqueueBy)
-    return
-  }
-  if (!isValidElement<{ readonly children?: Node }>(node)) return
-  if (node.type instanceof Function) {
-    const enqueue = enqueueBy.get(node.type)
-    if (enqueue !== undefined) {
-      enqueue(node.props)
-      return
-    }
-  }
-  drive(node.props.children, enqueueBy)
-}
-
-const makeFacade = (
+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
@@ -164,27 +157,76 @@ const makeFacade = (
     Effect.gen(function* () {
       if (frontier.length === 0) return
       const next: Array<Mounted> = []
-      for (const { comp, props } of frontier) {
+      for (const { comp, props, key } of frontier) {
         const service = yield* comp.tag
-        // A slot renders to a deferred component (JSX `<slots.Item/>`); map each
-        // back to the child it stands for so the tree walk can enqueue it.
-        const enqueueBy = new Map<Function, (childProps: unknown) => void>()
-        const slots: SlotHost = {
-          slot: (name) => {
-            const slotClass = comp.manifest.slots?.[name]
-            const child = slotClass && bindings.get(slotClass)
-            const component: (childProps: unknown) => Node = () => null
-            if (child) enqueueBy.set(component, (childProps) => next.push({ comp: child, props: childProps }))
-            return component
-          },
+        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`,
+          )
         }
-        const env: RenderEnv = { props, tracker: { add: () => {} }, slots }
-        const node = yield* Composition.render(service, env)
-        drive(node, enqueueBy)
+        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: {} }])
@@ -226,18 +268,41 @@ const makeFacade = (
     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: Effect.map(renderTree, () => capturesFor(name)[index]?.props),
+    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.
+    // 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(() => triggerOf(name, index, event)(payload))),
+            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'],
@@ -254,14 +319,39 @@ const makeFacade = (
     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,
@@ -271,6 +361,13 @@ const makeFacade = (
   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
@@ -279,14 +376,23 @@ const makeFacade = (
 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)
+    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 {
@@ -313,8 +419,11 @@ export const driveProof = async (proof: Proof): Promise<DriveResult> => {
   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)
+    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),

package/src/index.ts

@@ -26,6 +26,12 @@ import type {
 export { ProofRunner, proofRunnerLayer, withProofRunner }
 export type { ProofRunnerApi }
 
+// Engine SPI consumed by @playfast/reform-drive — the no-ceremony scene driver builds
+// on the same facade engine. Re-exported from the package index (not the engine
+// subpath) so consumers load the package in its normal init order.
+export { makeFacade, makeSink, proofLayer } from './engine'
+export type { RuntimeServices, Sink } from './engine'
+
 // ---------------------------------------------------------------------------
 // Definitions: ProductRequirement + Product
 // ---------------------------------------------------------------------------
@@ -40,6 +46,13 @@ export interface RequirementManifest<Comp extends AnyComposition, Statement exte
   readonly statement: Statement
   /** The composition this requirement specifies — its contract types the facade. */
   readonly composition: Comp
+  /**
+   * Optional: the contract events this requirement exercises. Typed to the
+   * composition's event names, and verified at run — a proof that never
+   * dispatches a declared event fails, so the requirement and its proof can't
+   * silently drift (the definition→implementation link past the statement string).
+   */
+  readonly events?: ReadonlyArray<keyof EventsOf<ContractOf<Comp>>>
 }
 
 export interface RequirementClass<Comp extends AnyComposition, Statement extends string> {
@@ -67,9 +80,16 @@ export interface ProductClass<Comp extends AnyComposition = AnyComposition> {
 const makeRequirement = <Comp extends AnyComposition, const Statement extends string>(
   composition: Comp,
   statement: Statement,
+  options?: { readonly events?: ReadonlyArray<keyof EventsOf<ContractOf<Comp>>> },
 ): RequirementClass<Comp, Statement> =>
   Object.assign(class {}, {
-    manifest: { kind: 'ProductRequirement' as const, name: statement, statement, composition },
+    manifest: {
+      kind: 'ProductRequirement' as const,
+      name: statement,
+      statement,
+      composition,
+      ...(options?.events !== undefined ? { events: options.events } : {}),
+    },
   })
 
 export const ProductRequirement: { readonly make: typeof makeRequirement } = {
@@ -120,8 +140,39 @@ export const expect = <A>(actual: A) => ({
     Array.isArray(actual) && actual.some((item) => deepEqual(item, expected))
       ? Effect.void
       : fail(`expected ${JSON.stringify(actual)} to contain ${JSON.stringify(expected)}`),
+  toMatchObject: (expected: Partial<A>): Effect.Effect<void> => {
+    const mismatch = matchPartial(actual, expected)
+    return mismatch === undefined ? Effect.void : fail(mismatch)
+  },
 })
 
+/**
+ * Deep-match every key of `expected` against `actual`; returns an error message
+ * naming the first failing key, or `undefined` on a full match. Shared by
+ * `expect(...).toMatchObject` and the facade's `expectProps`.
+ */
+const matchPartial = (actual: unknown, expected: unknown): string | undefined => {
+  if (typeof expected !== 'object' || expected === null) {
+    return deepEqual(actual, expected)
+      ? undefined
+      : `expected ${JSON.stringify(actual)} to match ${JSON.stringify(expected)}`
+  }
+  if (typeof actual !== 'object' || actual === null) {
+    return `expected ${JSON.stringify(actual)} to be an object matching ${JSON.stringify(expected)}`
+  }
+  const actualRecord = actual as Record<string, unknown>
+  const expectedRecord = expected as Record<string, unknown>
+  for (const key of Object.keys(expectedRecord)) {
+    if (!deepEqual(actualRecord[key], expectedRecord[key])) {
+      return `expected key ${JSON.stringify(key)} to match ${JSON.stringify(expectedRecord[key])}, got ${JSON.stringify(actualRecord[key])}`
+    }
+  }
+  return undefined
+}
+
+/** Internal: the facade's `expectProps` reuses the same partial-match logic. */
+export const matchProps: (actual: unknown, expected: unknown) => string | undefined = matchPartial
+
 // ---------------------------------------------------------------------------
 // Facade — a headless view over the live composition tree
 // ---------------------------------------------------------------------------
@@ -139,19 +190,24 @@ export type ContractOf<Comp> = Comp extends CompositionClass<any, infer C> ? C :
 /** The child contract a slot stands for — the contract of the composition it holds. */
 type ContractOfSlot<S> = S extends SlotInstance<infer Comp> ? ContractOf<Comp> : never
 
-/** The contract's events as facade actions: payload in, dispatch-and-settle Effect out. */
+/**
+ * The contract's events as facade actions: payload in, dispatch-and-settle Effect
+ * out. The Effect resolves to the props this node computed *after* the dispatch
+ * settled — the proof analog of chat-tests' `emitToolCall → ToolOutput`: in a
+ * fire-and-forget reduce loop the typed "result" of an event is the next state.
+ */
 export type ActionsOf<C extends UiContract> = {
   readonly [K in keyof EventsOf<C>]: (
     payload: PayloadOf<EventsOf<C>[K]>,
-  ) => Effect.Effect<void, never, CompositionService>
+  ) => Effect.Effect<C['props'], never, CompositionService>
 }
 /** The contract's slots as child facades, each typed by the child's own contract. */
 export type SlotFacadesOf<C extends UiContract> = {
   readonly [K in keyof SlotsOf<C>]: SlotFacade<ContractOfSlot<SlotsOf<C>[K]>>
 }
 
-/** The Effect a facade action returns: dispatch the event, then settle. */
-export type Action = (payload: unknown) => Effect.Effect<void, never, CompositionService>
+/** The Effect a facade action returns: dispatch the event, settle, read props. */
+export type Action = (payload: unknown) => Effect.Effect<unknown, never, CompositionService>
 
 /**
  * The handle a proof drives — the same surface the production UI receives, fully
@@ -162,6 +218,12 @@ export type Action = (payload: unknown) => Effect.Effect<void, never, Compositio
 export interface Facade<C extends UiContract> {
   /** Re-render the tree and read the props this node last computed. */
   readonly props: Effect.Effect<C['props'], never, CompositionService>
+  /**
+   * Re-render and assert the computed props match `partial` (a subset, deep).
+   * Typed from the contract, so a mistyped or unknown prop key is a compile
+   * error — unlike reading `props` and comparing a free-form object.
+   */
+  readonly expectProps: (partial: Partial<C['props']>) => Effect.Effect<void, never, CompositionService>
   /** The contract's events as callables; calling one dispatches and settles. */
   readonly actions: ActionsOf<C>
   /** Child composition facades, keyed by slot name. */
@@ -175,6 +237,22 @@ export interface SlotFacade<C extends UiContract> extends Facade<C> {
   readonly first: Effect.Effect<Facade<C>, never, CompositionService>
   readonly at: (index: number) => Effect.Effect<Facade<C>, never, CompositionService>
   readonly all: Effect.Effect<ReadonlyArray<Facade<C>>, never, CompositionService>
+  /**
+   * Select the one child mounted under `key` — the `each` item key the structure
+   * carried (the SINGLE source of the wire key and the per-item family key, so it
+   * can't drift from what the view places). The returned facade is itself typed by
+   * the child contract `C`, so `.slots` keeps descending type-safely:
+   * `app.slots.List.slots.Item.byKey('todo-1').slots…`. Fails the proof
+   * (`UnknownSlot`) when no fill carries the key.
+   */
+  readonly byKey: (key: string) => Effect.Effect<Facade<C>, never, CompositionService>
+  /** Every child whose computed props satisfy `predicate` — the structure-driven
+   *  analog of a query, resolved against this frame's fills (props typed by `C`). */
+  readonly where: (
+    predicate: (props: C['props']) => boolean,
+  ) => Effect.Effect<ReadonlyArray<Facade<C>>, never, CompositionService>
+  /** How many children this slot mounted this frame (the fill length). */
+  readonly count: Effect.Effect<number, never, CompositionService>
 }
 
 // ---------------------------------------------------------------------------

package/src/structure-events.test.ts

@@ -0,0 +1,74 @@
+import { Layer, Schema as S } from 'effect'
+import {
+  Composition,
+  Engine,
+  Event,
+  mount,
+  provide,
+  Reducer,
+  scene,
+  State,
+  StateGroup,
+  type Trigger,
+  Ui,
+  ui,
+} from '@playfast/reform'
+import { describe, expect, test } from 'vitest'
+import { Product, Proof, ProductRequirement, expect as proofExpect } from './index'
+
+// Plan 03b — events ride ON the structure. A composition whose `live` body returns
+// `mount({ props, events })` never calls its view, so the event triggers it acquires
+// (`yield* Event.trigger(Bumped)`) are NOT captured by a view's CaptureSink — they
+// travel with the frame on `structure.events`. The proof engine's `driveStructure`
+// records them into the same capture the view path uses, so `app.actions.bump()`
+// resolves and settles identically for a Structure frame. This file is the only
+// runtime exercise of the structure EVENT path; the view path stays covered by
+// typed-seams.test.ts.
+
+class CountState extends State.make('scount', S.Number) {}
+class MiniStates extends StateGroup.make(CountState) {}
+class Bumped extends Event.make('SBumped', S.Struct({})) {}
+class BumpReducer extends Reducer.make('SBumpReducer', { states: [CountState], events: [Bumped] }) {}
+const BumpReducerLive = Reducer.live(BumpReducer, (n) => n + 1)
+
+class CounterUi extends ui('SCounter')<{
+  props: { count: number }
+  events: { bump: Trigger<Record<string, never>> }
+}>() {}
+class Counter extends Composition.make('SCounter', {
+  title: 'SCounter',
+  states: [MiniStates],
+  events: [Bumped],
+  ui: CounterUi,
+}) {}
+// Body returns a STRUCTURE carrying the bump trigger on `events` — the view is never
+// called, so the trigger must ride on the frame for the proof to resolve it.
+const CounterLive = Composition.live(Counter, function* () {
+  const count = yield* StateGroup.select(MiniStates, 'scount')
+  const bump = yield* Event.trigger(Bumped)
+  return mount({ props: { count }, slots: {}, events: { bump } })
+})
+
+const presentations = provide(CounterUi, Ui.make(CounterUi, () => null))
+const Views = CounterLive.pipe(Layer.provideMerge(presentations))
+const Logic = BumpReducerLive.pipe(
+  Layer.provideMerge(Layer.mergeAll(Engine, StateGroup.live(MiniStates, { scount: 5 }))),
+)
+const MiniApp = Views.pipe(Layer.provideMerge(Logic))
+
+const CounterScene = scene(Counter, { provide: [MiniApp] })
+
+class Bumps extends ProductRequirement.make(Counter, 'bumps the count', { events: ['bump'] }) {}
+class CounterProduct extends Product.make(Counter, { requirements: [Bumps] }) {}
+
+describe('events ride on a Structure frame (plan 03b)', () => {
+  test('app.actions.x() dispatches and settles for a mount(...)-returning body', async () => {
+    const proof = Proof.implement(Bumps, CounterScene, function* (app) {
+      yield* proofExpect((yield* app.props).count).toBe(5)
+      const next = yield* app.actions.bump({})
+      yield* proofExpect(next.count).toBe(6)
+    })
+    const result = await Proof.run(Proof.suite(CounterProduct, { proofs: [proof] }))
+    expect(result.ok).toBe(true)
+  })
+})

package/src/structure-locators.test.ts

@@ -0,0 +1,137 @@
+import { Layer, Schema as S } from 'effect'
+import {
+  Composition,
+  Engine,
+  each,
+  mount,
+  Props,
+  provide,
+  scene,
+  slot,
+  State,
+  StateGroup,
+  Ui,
+  ui,
+} from '@playfast/reform'
+import { describe, expect, test } from 'vitest'
+import { type Facade, Product, Proof, ProductRequirement, expect as proofExpect } from './index'
+
+// Plan 06 — typed recursive proof navigation. A list parent returns a STRUCTURE
+// whose `Item` slot is filled with `each`, so each child rides a stable `key` (the
+// SINGLE source of the wire key + family key). The proof facade selects a child by
+// that key (`byKey`), filters by computed props (`where`), and reads the fill length
+// (`count`) — all against the structure tree, no view evaluated. `byKey` returns a
+// facade still typed by the child contract, so `.expectProps` checks the CHILD's
+// props and `.slots` would keep descending type-safely.
+
+// A list of todos lives in state; the parent computes its props + the `each` fill.
+class TodosState extends State.make(
+  'locTodos',
+  S.Array(S.Struct({ id: S.String, done: S.Boolean })),
+) {}
+class TodoStates extends StateGroup.make(TodosState) {}
+
+class ItemUi extends ui('LocItem')<{ props: { id: string; done: boolean } }>() {}
+class Item extends Composition.make('LocItem', {
+  title: 'LocItem',
+  props: S.Struct({ id: S.String, done: S.Boolean }),
+  ui: ItemUi,
+}) {}
+class ItemSlot extends slot('LocItem')<typeof Item>() {}
+
+class ListUi extends ui('LocList')<{
+  props: { total: number }
+  slots: { Item: ItemSlot }
+}>() {}
+class List extends Composition.make('LocList', {
+  title: 'LocList',
+  states: [TodoStates],
+  slots: { Item: ItemSlot },
+  ui: ListUi,
+}) {}
+
+// The parent body returns pure data: its own props, and the `Item` slot filled with
+// one keyed child per todo. No `.map`, no JSX — `each` owns multiplicity + key.
+const ListLive = Composition.live(List, function* () {
+  const todos = yield* StateGroup.select(TodoStates, 'locTodos')
+  return mount({
+    props: { total: todos.length },
+    slots: {
+      Item: each(todos, { key: (t) => t.id, props: (t) => ({ id: t.id, done: t.done }) }),
+    },
+  })
+})
+// A leaf child in structure-as-data echoes the props its parent's `each` fed it
+// (read via the `Props` service), so the recorded capture carries the per-item
+// props `byKey`/`where`/`expectProps` assert against. No view, hook-free.
+const ItemLive = Composition.live(Item, function* () {
+  const props: { id: string; done: boolean } = yield* Props
+  return mount({ props, slots: {} })
+})
+
+const presentations = Layer.mergeAll(
+  provide(ListUi, Ui.make(ListUi, () => null)),
+  provide(ItemUi, Ui.make(ItemUi, () => null)),
+)
+const wiring = provide(ItemSlot, Item)
+const Views = Layer.mergeAll(ListLive, ItemLive, wiring).pipe(Layer.provideMerge(presentations))
+const Logic = Layer.mergeAll(
+  Engine,
+  StateGroup.live(TodoStates, {
+    locTodos: [
+      { id: 'todo-1', done: false },
+      { id: 'todo-2', done: true },
+      { id: 'todo-3', done: false },
+    ],
+  }),
+)
+const ListApp = Views.pipe(Layer.provideMerge(Logic))
+const ListScene = scene(List, { provide: [ListApp] })
+
+class Locates extends ProductRequirement.make(List, 'locates list children by key/props') {}
+class ListProduct extends Product.make(List, { requirements: [Locates] }) {}
+
+describe('typed recursive proof navigation (plan 06)', () => {
+  test('byKey / where / count resolve children from the structure tree', async () => {
+    const proof = Proof.implement(Locates, ListScene, function* (app) {
+      // The parent's computed props.
+      yield* proofExpect((yield* app.props).total).toBe(3)
+      // count = the fill length.
+      yield* proofExpect(yield* app.slots.Item.count).toBe(3)
+      // byKey selects the one child mounted under that `each` key; the facade is
+      // typed by the CHILD contract, so `expectProps` checks the child's props.
+      const second = yield* app.slots.Item.byKey('todo-2')
+      yield* second.expectProps({ id: 'todo-2', done: true })
+      const first = yield* app.slots.Item.byKey('todo-1')
+      yield* first.expectProps({ id: 'todo-1', done: false })
+      // where filters children by their computed props (predicate typed by the
+      // CHILD contract — `p.done` is known).
+      const doneItems = yield* app.slots.Item.where((p) => p.done)
+      yield* proofExpect(doneItems.length).toBe(1)
+      yield* doneItems[0]!.expectProps({ id: 'todo-2' })
+    })
+    const result = await Proof.run(Proof.suite(ListProduct, { proofs: [proof] }))
+    expect(result.ok).toBe(true)
+  })
+
+  test('byKey on a missing key fails the proof', async () => {
+    const proof = Proof.implement(Locates, ListScene, function* (app) {
+      yield* app.slots.Item.byKey('nope')
+    })
+    const result = await Proof.run(Proof.suite(ListProduct, { proofs: [proof] }))
+    expect(result.ok).toBe(false)
+  })
+})
+
+// Type-only: the `byKey`-selected facade is typed by the Item CHILD contract
+// (`{ id, done }`) — recursive typed selection. A wrong prop key in `expectProps`
+// is a compile error. Non-exported, never called; exists only to be typechecked.
+const _negativeTypeCheck = (app: Facade<Ui.Contract<typeof ListUi>>): void => {
+  Proof.implement(Locates, ListScene, function* () {
+    const child = yield* app.slots.Item.byKey('todo-1')
+    yield* child.expectProps({ id: 'x', done: true })
+    // @ts-expect-error 'nope' is not a key of the Item child contract props
+    yield* child.expectProps({ nope: 1 })
+  })
+}
+void _negativeTypeCheck

package/src/typed-seams.test.ts

@@ -0,0 +1,166 @@
+import { Layer, Schema as S } from 'effect'
+import {
+  Composition,
+  Engine,
+  Event,
+  mount,
+  one,
+  provide,
+  Reducer,
+  scene,
+  seedScene,
+  slot,
+  State,
+  StateGroup,
+  type Trigger,
+  ui,
+} from '@playfast/reform'
+import { describe, expect, test } from 'vitest'
+import { Product, Proof, ProductRequirement, expect as proofExpect } from './index'
+
+// Exercises the four type-safety seams closed in this change, each against a
+// self-contained mini Counter (the same fixture shape as the stepper test):
+//   #1 typed seeds       — seedScene is keyed/valued by the state tuple
+//   #2 action results    — an action resolves to the settled next props
+//   #4 typed assertions  — app.expectProps is a contract-typed subset match
+//   #5 event coverage     — a requirement's declared events must be dispatched
+// Negative cases are compile-time (`@ts-expect-error`) — the whole point is that
+// the bad input never reaches runtime.
+
+class CountState extends State.make('count', S.Number) {}
+class MiniStates extends StateGroup.make(CountState) {}
+class Bumped extends Event.make('Bumped', S.Struct({})) {}
+class BumpReducer extends Reducer.make('BumpReducer', { states: [CountState], events: [Bumped] }) {}
+const BumpReducerLive = Reducer.live(BumpReducer, (n) => n + 1)
+
+// A trivial slot child: a proof runtime resolves slot-bound compositions, so the
+// app needs at least one slot for the suite's provide layer to type-close.
+class LabelUi extends ui('Label')<{ props: { text: string } }>() {}
+class Label extends Composition.make('Label', { title: 'Label', ui: LabelUi }) {}
+const LabelLive = Composition.live(Label, function* () {
+  return mount({ props: { text: 'count' }, slots: {} })
+})
+class LabelSlot extends slot('Label')<typeof Label>() {}
+
+class CounterUi extends ui('Counter')<{
+  props: { count: number }
+  slots: { Label: LabelSlot }
+  events: { bump: Trigger<Record<string, never>> }
+}>() {}
+class Counter extends Composition.make('Counter', {
+  title: 'Counter',
+  states: [MiniStates],
+  events: [Bumped],
+  slots: { Label: LabelSlot },
+  ui: CounterUi,
+}) {}
+const CounterLive = Composition.live(Counter, function* () {
+  const count = yield* StateGroup.select(MiniStates, 'count')
+  const bump = yield* Event.trigger(Bumped)
+  return mount({
+    props: { count },
+    slots: { Label: one({}) },
+    events: { bump },
+  })
+})
+
+const presentations = provide(LabelSlot, Label)
+const Views = Layer.mergeAll(CounterLive, LabelLive).pipe(Layer.provideMerge(presentations))
+const Logic = Layer.mergeAll(BumpReducerLive).pipe(
+  Layer.provideMerge(Layer.mergeAll(Engine, StateGroup.live(MiniStates, { count: 5 }))),
+)
+const MiniApp = Views.pipe(Layer.provideMerge(Logic))
+
+const CounterScene = scene(Counter, { provide: [MiniApp] })
+
+class Bumps extends ProductRequirement.make(Counter, 'bumps the count') {}
+class CounterProduct extends Product.make(Counter, { requirements: [Bumps] }) {}
+
+describe('#1 typed seeds', () => {
+  test('seedScene overrides the authored seed, typed by the state tuple', async () => {
+    const seeded = seedScene(CounterScene, { count: 9 })
+    const boots = Proof.implement(Bumps, seeded, function* (app) {
+      const props = yield* app.props
+      yield* proofExpect(props.count).toBe(9)
+    })
+    const result = await Proof.run(Proof.suite(CounterProduct, { proofs: [boots] }))
+    expect(result.ok).toBe(true)
+  })
+
+  test('an unknown key or mistyped value is a compile error', () => {
+    // @ts-expect-error 'other' is not a state member of Counter
+    seedScene(CounterScene, { other: 1 })
+    // @ts-expect-error 'count' is a number, not a string
+    seedScene(CounterScene, { count: 'nope' })
+    expect(true).toBe(true)
+  })
+})
+
+describe('#2 actions return post-settle props', () => {
+  test('dispatching an event resolves to the settled next props', async () => {
+    const bumps = Proof.implement(Bumps, CounterScene, function* (app) {
+      const props = yield* app.actions.bump({})
+      yield* proofExpect(props.count).toBe(6)
+    })
+    const result = await Proof.run(Proof.suite(CounterProduct, { proofs: [bumps] }))
+    expect(result.ok).toBe(true)
+  })
+})
+
+describe('#4 contract-typed prop assertions', () => {
+  test('expectProps matches a typed subset of the computed props', async () => {
+    const matches = Proof.implement(Bumps, CounterScene, function* (app) {
+      yield* app.expectProps({ count: 5 })
+      yield* app.actions.bump({})
+      yield* app.expectProps({ count: 6 })
+    })
+    const result = await Proof.run(Proof.suite(CounterProduct, { proofs: [matches] }))
+    expect(result.ok).toBe(true)
+  })
+
+  test('a non-matching expectProps fails the proof', async () => {
+    const wrong = Proof.implement(Bumps, CounterScene, function* (app) {
+      yield* app.expectProps({ count: 999 })
+    })
+    const result = await Proof.run(Proof.suite(CounterProduct, { proofs: [wrong] }))
+    expect(result.ok).toBe(false)
+  })
+
+  test('a typo’d prop key is a compile error', () => {
+    Proof.implement(Bumps, CounterScene, function* (app) {
+      // @ts-expect-error 'cuont' is not a prop of Counter
+      yield* app.expectProps({ cuont: 5 })
+    })
+    expect(true).toBe(true)
+  })
+})
+
+describe('#5 requirement-bound event coverage', () => {
+  class CoveredBump extends ProductRequirement.make(Counter, 'bumps via the bump event', {
+    events: ['bump'],
+  }) {}
+  class CoveredProduct extends Product.make(Counter, { requirements: [CoveredBump] }) {}
+
+  test('passes when the declared event is dispatched', async () => {
+    const proof = Proof.implement(CoveredBump, CounterScene, function* (app) {
+      yield* app.actions.bump({})
+    })
+    const result = await Proof.run(Proof.suite(CoveredProduct, { proofs: [proof] }))
+    expect(result.ok).toBe(true)
+  })
+
+  test('fails, naming the event, when a declared event is never dispatched', async () => {
+    const proof = Proof.implement(CoveredBump, CounterScene, function* (app) {
+      yield* app.props
+    })
+    const result = await Proof.run(Proof.suite(CoveredProduct, { proofs: [proof] }))
+    expect(result.ok).toBe(false)
+    expect(result.results[0]?.error).toContain('bump')
+  })
+
+  test('an event name outside the contract is a compile error', () => {
+    // @ts-expect-error 'nope' is not an event of Counter
+    ProductRequirement.make(Counter, 'invalid coverage', { events: ['nope'] })
+    expect(true).toBe(true)
+  })
+})