@playfast/reform-proof 0.0.7 → 0.0.9

package/src/index.ts

@@ -0,0 +1,373 @@
+import { Effect } from 'effect'
+import type { YieldWrap } from 'effect/Utils'
+import { AssertionFailed } from './errors'
+import { ProofRunner, type ProofRunnerApi, proofRunnerLayer, withProofRunner } from './runner'
+import type {
+  CompositionClass,
+  CompositionService,
+  Scene,
+  SlotInstance,
+  Trigger,
+  UiCapture,
+  UiContract,
+} from '@playfast/reform'
+
+// reform-proof — the stability story for AI authorship. Product behaviour is
+// declared as human-readable requirements (the definition) and proven by tests
+// (the implementation), the same split as the rest of reform. A proof drives the
+// real reduce loop through a headless FACADE: no DOM, no text matching. It reads
+// the props each composition computed and calls the contract's events as
+// callbacks — exactly what the production UI receives. HOW a proof runs is the
+// injectable `ProofRunner` layer (./runner); the headless engine (./engine) is its
+// default. `Proof.run`/`Proof.driver` resolve that layer, so the vitest adapter
+// can drive the very same proofs as native tests.
+
+// The injectable execution seam is re-exported so adapters can resolve it.
+export { ProofRunner, proofRunnerLayer, withProofRunner }
+export type { ProofRunnerApi }
+
+// ---------------------------------------------------------------------------
+// Definitions: ProductRequirement + Product
+// ---------------------------------------------------------------------------
+
+/** Any composition, used where the contract type is irrelevant. */
+type AnyComposition = CompositionClass<any, any>
+
+export interface RequirementManifest<Comp extends AnyComposition, Statement extends string> {
+  readonly kind: 'ProductRequirement'
+  readonly name: Statement
+  /** The human-readable behavioural statement; doubles as the manifest name. */
+  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> {
+  new (): {}
+  readonly manifest: RequirementManifest<Comp, Statement>
+}
+
+export interface ProductManifest<Comp extends AnyComposition> {
+  readonly kind: 'Product'
+  readonly name: string
+  readonly composition: Comp
+  readonly requirements: ReadonlyArray<RequirementClass<Comp, string>>
+}
+
+export interface ProductClass<Comp extends AnyComposition = AnyComposition> {
+  new (): {}
+  readonly manifest: ProductManifest<Comp>
+}
+
+/**
+ * A named, human-readable behavioural statement bound to the composition it
+ * specifies. The composition types the proof facade; the statement's literal
+ * type is re-stated (and enforced) at `Proof.implement`.
+ */
+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,
+      ...(options?.events !== undefined ? { events: options.events } : {}),
+    },
+  })
+
+export const ProductRequirement: { readonly make: typeof makeRequirement } = {
+  make: makeRequirement,
+}
+
+/**
+ * Group a composition with the full list of requirements that specify it. The
+ * shared `Comp` type-checks that every requirement targets this composition.
+ */
+const makeProduct = <Comp extends AnyComposition>(
+  composition: Comp,
+  config: { readonly requirements: ReadonlyArray<RequirementClass<Comp, string>> },
+): ProductClass<Comp> =>
+  Object.assign(class {}, {
+    manifest: {
+      kind: 'Product' as const,
+      name: composition.manifest.name,
+      composition,
+      requirements: config.requirements,
+    },
+  })
+
+export const Product: { readonly make: typeof makeProduct } = { make: makeProduct }
+
+// ---------------------------------------------------------------------------
+// Assertions — Effect-returning matchers; a failed match fails the proof.
+// ---------------------------------------------------------------------------
+
+const deepEqual = (a: unknown, b: unknown): boolean =>
+  Object.is(a, b) || JSON.stringify(a) === JSON.stringify(b)
+
+const fail = (message: string): Effect.Effect<never> =>
+  Effect.sync(() => {
+    throw new AssertionFailed({ detail: message })
+  })
+
+export const expect = <A>(actual: A) => ({
+  toBe: (expected: A): Effect.Effect<void> =>
+    Object.is(actual, expected)
+      ? Effect.void
+      : fail(`expected ${JSON.stringify(actual)} to be ${JSON.stringify(expected)}`),
+  toEqual: (expected: A): Effect.Effect<void> =>
+    deepEqual(actual, expected)
+      ? Effect.void
+      : fail(`expected ${JSON.stringify(actual)} to equal ${JSON.stringify(expected)}`),
+  toContain: (expected: A extends ReadonlyArray<infer E> ? E : unknown): Effect.Effect<void> =>
+    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
+// ---------------------------------------------------------------------------
+
+// --- Contract projection: derive the facade's exact shape from a UI contract ---
+
+/** The event payloads of a contract, keyed by event name. */
+type EventsOf<C extends UiContract> = C extends { events: infer E } ? E : Record<never, never>
+/** The slot instances of a contract, keyed by slot name. */
+type SlotsOf<C extends UiContract> = C extends { slots: infer S } ? S : Record<never, never>
+/** The payload a trigger accepts. */
+type PayloadOf<T> = T extends Trigger<infer P> ? P : never
+/** The UI contract a composition resolves. */
+export type ContractOf<Comp> = Comp extends CompositionClass<any, infer C> ? C : never
+/** 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 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<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, 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
+ * typed from the composition's contract `C`: read state (`props`), trigger events
+ * (`actions`), reach children (`slots`), and wait for the next frame (`frame`).
+ * Each access yields a real Effect/SlotFacade against the running engine.
+ */
+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. */
+  readonly slots: SlotFacadesOf<C>
+  /** Settle the engine and re-render — wait for the next stable frame. */
+  readonly frame: Effect.Effect<void, never, CompositionService>
+}
+
+/** A slot may hold many instances (a list); it is also usable as its first one. */
+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>
+}
+
+// ---------------------------------------------------------------------------
+// Proofs + suite
+// ---------------------------------------------------------------------------
+
+/** The generator a proof body produces — its yielded effects run on the engine. */
+type ProofGenerator = Generator<
+  YieldWrap<Effect.Effect<unknown, unknown, CompositionService>>,
+  void,
+  unknown
+>
+
+/** An erased facade — the runtime shape before the contract type is re-attached. */
+type AnyFacade = Facade<UiContract>
+
+/** The erased body stored on a `Proof` value; `implement` types the contract in. */
+export type ProofBody = (app: AnyFacade) => ProofGenerator
+
+export interface Proof {
+  readonly requirement: RequirementClass<AnyComposition, string>
+  /** The scene this proof runs against: its closed wiring + boot events. */
+  readonly scene: Scene
+  readonly body: ProofBody
+}
+
+export interface ProofSuite {
+  /** Brand so adapters can duck-type a suite among a module's exports. */
+  readonly kind: 'ProofSuite'
+  readonly product: ProductClass
+  readonly proofs: ReadonlyArray<Proof>
+}
+
+export interface ProofResult {
+  readonly requirement: string
+  readonly ok: boolean
+  readonly error?: string
+}
+
+export interface SuiteResult {
+  readonly product: string
+  readonly results: ReadonlyArray<ProofResult>
+  readonly ok: boolean
+}
+
+/**
+ * Implement (prove) a requirement by driving the facade against a scene. A proof
+ * is a VALUE. The scene supplies the runtime (its closed `provide` + `boot`) and
+ * the composition that types the facade; its contract must equal the
+ * requirement's composition contract, so a scene for the wrong composition — or
+ * one whose contract has drifted — is a compile error. The `app` facade is fully
+ * typed from that contract.
+ */
+const implement = <Comp extends AnyComposition>(
+  requirement: RequirementClass<Comp, string>,
+  scene: Scene<ContractOf<Comp>>,
+  body: (app: Facade<ContractOf<Comp>>) => ProofGenerator,
+): Proof => ({ requirement, scene, body: body as ProofBody })
+
+/** Compose proofs with the product whose requirements they prove. */
+const suite = (
+  product: ProductClass,
+  config: { readonly proofs: ReadonlyArray<Proof> },
+): ProofSuite => ({ kind: 'ProofSuite', product, proofs: config.proofs })
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null
+
+/** Duck-type a `ProofSuite` among arbitrary module exports (the adapter's seam). */
+export const isProofSuite = (value: unknown): value is ProofSuite =>
+  isRecord(value) && value['kind'] === 'ProofSuite' && Array.isArray(value['proofs'])
+
+/**
+ * Run every proof against a fresh runtime, returning per-requirement results.
+ * Each proof gets its own environment, so nothing leaks between proofs. Execution
+ * goes through the injected `ProofRunner` (the headless engine by default).
+ */
+const run = (proofSuite: ProofSuite): Promise<SuiteResult> =>
+  withProofRunner(async (runner: ProofRunnerApi) => {
+    const results: ProofResult[] = []
+    for (const proof of proofSuite.proofs) {
+      results.push(await runner.executeProof(proof))
+    }
+    return { product: proofSuite.product.manifest.name, results, ok: results.every((r) => r.ok) }
+  })
+
+// ---------------------------------------------------------------------------
+// Driver: step a proof for the editor's Test-play timeline
+// ---------------------------------------------------------------------------
+
+/** One step of a driven proof: the rendered tree captured right after the
+ *  proof's i-th yielded effect settled. Index 0 is the booted, pre-drive tree. */
+export interface StepFrame {
+  readonly index: number
+  readonly captures: ReadonlyArray<UiCapture>
+}
+
+export interface DriveResult {
+  readonly requirement: string
+  readonly frames: ReadonlyArray<StepFrame>
+  readonly ok: boolean
+  readonly error?: string
+}
+
+export interface ProofDriver {
+  readonly requirement: string
+  /** Run the proof, snapshotting the captured tree after each yielded step. */
+  readonly run: () => Promise<DriveResult>
+}
+
+/** A driver per proof in the suite — the editor's Test-play entry point. Each
+ *  `run` resolves the same `ProofRunner` layer and steps that proof. */
+const driver = (proofSuite: ProofSuite): ReadonlyArray<ProofDriver> =>
+  proofSuite.proofs.map((proof) => ({
+    requirement: proof.requirement.manifest.statement,
+    run: () => withProofRunner((runner: ProofRunnerApi) => runner.driveProof(proof)),
+  }))
+
+export const Proof: {
+  readonly implement: typeof implement
+  readonly suite: typeof suite
+  readonly run: typeof run
+  readonly driver: typeof driver
+} = { implement, suite, run, driver }

package/src/runner.ts

@@ -0,0 +1,42 @@
+import { Context, Effect, Layer } from 'effect'
+import { driveProof, executeProof } from './engine'
+import type { DriveResult, Proof, ProofResult } from './index'
+
+// reform-proof runner — the injectable seam HOW a proof is executed. The proof
+// system depends on this layer rather than calling the engine directly, so the
+// execution strategy can be swapped (the vitest adapter resolves the same layer to
+// run each proof as a native test). The default layer is the headless engine in
+// ./engine; mirrors the Tag + Layer house style of reform's `CaptureSink` and
+// `Notifications` services.
+
+export interface ProofRunnerApi {
+  /** Run a proof to completion, returning its pass/fail result. */
+  readonly executeProof: (proof: Proof) => Promise<ProofResult>
+  /** Step a proof a frame at a time (the editor's Test-play timeline). */
+  readonly driveProof: (proof: Proof) => Promise<DriveResult>
+}
+
+const ProofRunnerBase: Context.TagClass<ProofRunner, 'reform-proof/ProofRunner', ProofRunnerApi> =
+  Context.Tag('reform-proof/ProofRunner')<ProofRunner, ProofRunnerApi>()
+
+/** The service identity for the proof execution strategy. */
+export class ProofRunner extends ProofRunnerBase {}
+
+/** The default runner: the headless engine that drives the real reduce loop. */
+export const proofRunnerLayer: Layer.Layer<ProofRunner> = Layer.succeed(ProofRunner, {
+  executeProof,
+  driveProof,
+})
+
+/**
+ * Resolve the `ProofRunner` from `proofRunnerLayer` and use it — the single seam
+ * the proof system (`Proof.run`/`Proof.driver`) and the vitest adapter both run
+ * through, so every proof executes via the same injectable engine.
+ */
+export const withProofRunner = <A>(use: (runner: ProofRunnerApi) => Promise<A>): Promise<A> =>
+  Effect.runPromise(
+    ProofRunner.pipe(
+      Effect.flatMap((runner) => Effect.promise(() => use(runner))),
+      Effect.provide(proofRunnerLayer),
+    ),
+  )

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