@playfast/reform-proof 1.0.1 → 1.2.0

package/src/index.ts

@@ -1,88 +1,95 @@
 import { Array as Arr, Effect, Option, Record as Rec } from 'effect'
 import type { YieldWrap } from 'effect/Utils'
 import { AssertionFailed } from './errors'
+import { formatFingerprint } from './fingerprint'
 import { ProofRunner, type ProofRunnerApi, proofRunnerLayer, withProofRunner } from './runner'
 import type {
-  CompositionClass,
-  CompositionService,
+  CapturedScene,
   Scene,
-  SlotInstance,
+  SlotComposition as ReformSlotComposition,
+  SlotContract as ReformSlotContract,
   Trigger,
-  UiCapture,
   UiContract,
 } from '@playfast/reform'
+import type { AnyComposition, AnyScene, CapturedRender } from '@playfast/reform/internal'
 
-// 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 }
 
-// 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
-// ---------------------------------------------------------------------------
+export {
+  makeFacade,
+  makeProofFacade,
+  makeRuntimeHandleFacade,
+  makeRuntimeTreeFacade,
+  makeSink,
+  proofLayer,
+} from './engine'
+export type {
+  MountedFacade,
+  MountedSlotFacade,
+  MountedSlotFacadesOf,
+  RuntimeTreeFacade,
+  Sink,
+} from './engine'
+
+export type ProductComposition = AnyComposition & { readonly identity: symbol }
+
+const RequirementCompositionTypeId: unique symbol = Symbol.for(
+  'reform-proof/RequirementComposition',
+)
+
+export interface AnyRequirementClass {
+  new (): {}
+  readonly manifest: {
+    readonly kind: 'ProductRequirement'
+    readonly name: string
+    readonly statement: string
+    readonly composition: ProductComposition
+    readonly events: Option.Option<ReadonlyArray<PropertyKey>>
+  }
+  readonly capture: <Result>(visit: RequirementCapture<Result>) => Result
+}
 
-/** Any composition, used where the contract type is irrelevant. */
-type AnyComposition = CompositionClass<any, any>
+export type RequirementCapture<Result> = <
+  Comp extends ProductComposition,
+  Statement extends string,
+>(
+  requirement: RequirementClass<Comp, Statement>,
+) => Result
 
-export interface RequirementManifest<Comp extends AnyComposition, Statement extends string> {
+export interface RequirementManifest<Comp extends ProductComposition, 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: Option.Option<ReadonlyArray<keyof EventsOf<ContractOf<Comp>>>>
+  readonly events: Option.Option<ReadonlyArray<EventNamesOf<ContractOf<Comp>>>>
 }
 
-export interface RequirementClass<Comp extends AnyComposition, Statement extends string> {
-  new (): {}
+export interface RequirementClass<
+  Comp extends ProductComposition,
+  Statement extends string,
+> extends AnyRequirementClass {
   readonly manifest: RequirementManifest<Comp, Statement>
+  readonly [RequirementCompositionTypeId]: (composition: Comp) => Comp
 }
 
-export interface ProductManifest<Comp extends AnyComposition> {
+export interface ProductManifest<Comp extends ProductComposition> {
   readonly kind: 'Product'
   readonly name: string
   readonly composition: Comp
-  readonly requirements: ReadonlyArray<RequirementClass<Comp, string>>
+  readonly requirements: ReadonlyArray<AnyRequirementClass>
 }
 
-export interface ProductClass<Comp extends AnyComposition = AnyComposition> {
+export interface ProductClass<Comp extends ProductComposition = ProductComposition> {
   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`.
- */
-/** Author-facing config for `ProductRequirement.make` — plain JSON the proof author passes. */
-interface MakeRequirementOptionsExternalApi<Comp extends AnyComposition> {
-  readonly events?: ReadonlyArray<keyof EventsOf<ContractOf<Comp>>>
+interface MakeRequirementOptionsExternalApi<Comp extends ProductComposition> {
+  readonly events?: ReadonlyArray<EventNamesOf<ContractOf<Comp>>>
 }
 
-const makeRequirement = <Comp extends AnyComposition, const Statement extends string>(
+const makeRequirement = <Comp extends ProductComposition, const Statement extends string>(
   composition: Comp,
   statement: Statement,
   options?: MakeRequirementOptionsExternalApi<Comp>,
@@ -94,24 +101,24 @@ const makeRequirement = <Comp extends AnyComposition, const Statement extends st
     composition,
     events: Option.fromNullable(options?.events),
   }
-  return class {
+  class Requirement {
     static readonly manifest = manifest
+    static readonly [RequirementCompositionTypeId] = (exact: Comp): Comp => exact
+    static readonly capture = <Result>(visit: RequirementCapture<Result>): Result =>
+      visit(Requirement)
   }
+  return Requirement
 }
 
 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.
- */
-interface MakeProductConfig<Comp extends AnyComposition> {
+interface MakeProductConfig<Comp extends ProductComposition> {
   readonly requirements: ReadonlyArray<RequirementClass<Comp, string>>
 }
 
-const makeProduct = <Comp extends AnyComposition>(
+const makeProduct = <Comp extends ProductComposition>(
   composition: Comp,
   config: MakeProductConfig<Comp>,
 ): ProductClass<Comp> => {
@@ -126,22 +133,16 @@ const makeProduct = <Comp extends AnyComposition>(
   }
 }
 
-export const Product: { readonly make: typeof makeProduct } = { make: makeProduct }
-
-// ---------------------------------------------------------------------------
-// Assertions — Effect-returning matchers; a failed match fails the proof.
-// ---------------------------------------------------------------------------
+export const Product: { readonly make: typeof makeProduct } = {
+  make: makeProduct,
+}
 
-/** Two values to deep-compare — one options object, not positional primitives. */
 interface ComparePair {
   readonly left: unknown
   readonly right: unknown
 }
 
-// Display + structural-compare seam: assertion messages and deep-equality operate on
-// arbitrary `unknown` values, which Schema cannot encode — JSON is the right tool here.
-// 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)
@@ -168,21 +169,14 @@ export const expect = <A>(actual: A) => ({
   },
 })
 
-/** A non-null object as an indexable record — the narrowing `unknown` doesn't give. */
 const isRecord = (candidate: unknown): candidate is Record<string, unknown> =>
   typeof candidate === 'object' && candidate !== null
 
-/** The pair `matchPartial`/`matchProps` deep-matches: `actual` against the `expected` subset. */
 interface MatchInput {
   readonly actual: unknown
   readonly expected: unknown
 }
 
-/**
- * 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, expected }: MatchInput): string | undefined => {
   if (!isRecord(expected)) {
     return deepEqual({ left: actual, right: expected })
@@ -203,117 +197,105 @@ const matchPartial = ({ actual, expected }: MatchInput): string | undefined => {
   })
 }
 
-/** Internal: the facade's `expectProps` reuses the same partial-match logic. */
 export const matchProps: (input: MatchInput) => string | undefined = matchPartial
 
-// ---------------------------------------------------------------------------
-// Facade — a headless view over the live composition tree
-// ---------------------------------------------------------------------------
+export type EventsOf<C extends UiContract> = C extends {
+  readonly events: infer E extends NonNullable<UiContract['events']>
+}
+  ? E
+  : Readonly<Record<PropertyKey, never>>
+type EventNamesOf<C extends UiContract> = C extends {
+  readonly events: NonNullable<UiContract['events']>
+}
+  ? keyof EventsOf<C>
+  : never
+type SlotsOf<C extends UiContract> = C extends {
+  readonly slots: infer S extends NonNullable<UiContract['slots']>
+}
+  ? S
+  : Readonly<Record<PropertyKey, never>>
+type PayloadOf<T> = T extends Trigger<infer P> ? P : never
+export type ContractOf<Comp> = Comp extends {
+  readonly Contract: infer C extends UiContract
+}
+  ? C
+  : never
+type ContractOfSlot<S> = ReformSlotContract<S>
 
-// --- Contract projection: derive the facade's exact shape from a UI contract ---
+export type ActionsOf<C extends UiContract, R = never> = C extends {
+  readonly events: NonNullable<UiContract['events']>
+}
+  ? {
+      readonly [K in keyof EventsOf<C>]: (
+        payload: PayloadOf<EventsOf<C>[K]>,
+      ) => Effect.Effect<C['props'], never, R>
+    }
+  : Readonly<Record<PropertyKey, never>>
+export type SlotFacadesOf<C extends UiContract, R = never> = C extends {
+  readonly slots: NonNullable<UiContract['slots']>
+}
+  ? {
+      readonly [K in keyof SlotsOf<C>]: SlotFacade<ContractOfSlot<SlotsOf<C>[K]>, R>
+    }
+  : Readonly<Record<PropertyKey, never>>
 
-/** 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`). */
+export type Action<R = never> = (payload: unknown) => Effect.Effect<unknown, never, R>
+
+export interface Facade<C extends UiContract, R = never> {
+  readonly props: Effect.Effect<C['props'], never, R>
+  readonly expectProps: (partial: Partial<C['props']>) => Effect.Effect<void, never, R>
+  readonly actions: ActionsOf<C, R>
+  readonly slots: SlotFacadesOf<C, R>
+  readonly frame: Effect.Effect<void, never, R>
+}
+
+export interface SlotFacade<C extends UiContract, R = never> extends Facade<C, R> {
+  readonly first: Effect.Effect<Facade<C, R>, never, R>
+  readonly at: (index: number) => Effect.Effect<Facade<C, R>, never, R>
+  readonly all: Effect.Effect<ReadonlyArray<Facade<C, R>>, never, R>
+  readonly byKey: (key: string) => Effect.Effect<Facade<C, R>, never, R>
   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>
+  ) => Effect.Effect<ReadonlyArray<Facade<C, R>>, never, R>
+  readonly count: Effect.Effect<number, never, R>
 }
 
-// ---------------------------------------------------------------------------
-// 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>
+type ProofGenerator = Generator<YieldWrap<Effect.Effect<unknown, unknown, never>>, void, unknown>
+
+export interface ProofCase<
+  Comp extends ProductComposition,
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  Services,
+  P,
+  N extends string,
+  Identity,
+> {
+  readonly requirement: RequirementClass<Comp, string>
+  readonly scene: CapturedScene<C, S, Services, P, N, Identity>
+  readonly placement: 'Root' | 'Slot'
+  readonly body: (app: Facade<C, never>) => ProofGenerator
+}
 
-/** The erased body stored on a `Proof` value; `implement` types the contract in. */
-export type ProofBody = (app: AnyFacade) => ProofGenerator
+export type ProofCapture<Result> = <
+  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>,
+) => Result
 
 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
+  readonly requirement: AnyRequirementClass
+  readonly scene: AnyScene
+  readonly capture: <Result>(visit: ProofCapture<Result>) => Result
 }
 
 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>
@@ -322,8 +304,7 @@ export interface ProofSuite {
 export interface ProofResult {
   readonly requirement: string
   readonly ok: boolean
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- serialized result DTO read as `error ?? …` by the vitest adapter (external); optional kept for wire compat
-  readonly error?: string
+  readonly error: string | undefined
 }
 
 export interface SuiteResult {
@@ -332,84 +313,125 @@ export interface SuiteResult {
   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>(
+const implement = <Comp extends ProductComposition>(
   requirement: RequirementClass<Comp, string>,
-  scene: Scene<ContractOf<Comp>>,
-  body: (app: Facade<ContractOf<Comp>>) => ProofGenerator,
-): Proof => {
-  // oxlint-disable-next-line reform-rules/no-type-assertion -- contract erasure seam: Facade<C> → AnyFacade is contravariant, sound by construction
-  const erased = body as ProofBody
-  return { requirement, scene, body: erased }
+  scene: Scene<ContractOf<NoInfer<Comp>>, NoInfer<Comp>['States']>,
+  body: (app: Facade<ContractOf<Comp>, never>) => ProofGenerator,
+): Proof =>
+  scene.capture(
+    <Services, P, N extends string, Identity>(
+      exactScene: CapturedScene<ContractOf<Comp>, Comp['States'], Services, P, N, Identity>,
+    ): Proof => {
+      const proofCase: ProofCase<
+        Comp,
+        ContractOf<Comp>,
+        Comp['States'],
+        Services,
+        P,
+        N,
+        Identity
+      > = {
+        requirement,
+        scene: exactScene,
+        placement: 'Root',
+        body,
+      }
+      return {
+        requirement,
+        scene: exactScene,
+        capture: (visit) =>
+          visit<Comp, ContractOf<Comp>, Comp['States'], Services, P, N, Identity>(proofCase),
+      }
+    },
+  )
+
+type SlotsHolding<C extends UiContract, Target extends ProductComposition> = C extends {
+  readonly slots: NonNullable<UiContract['slots']>
 }
+  ? {
+      [K in keyof SlotsOf<C>]: [ReformSlotComposition<SlotsOf<C>[K]>] extends [Target] ? K : never
+    }[keyof SlotsOf<C>]
+  : never
+
+type SceneHolding<
+  Comp extends ProductComposition,
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+> = [SlotsHolding<C, Comp>] extends [never] ? never : Scene<C, S>
+
+const implementVia = <
+  Comp extends ProductComposition,
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+>(
+  requirement: RequirementClass<Comp, string>,
+  scene: SceneHolding<NoInfer<Comp>, C, S>,
+  body: (app: Facade<C, never>) => ProofGenerator,
+): Proof =>
+  scene.capture(
+    <Services, P, N extends string, Identity>(
+      exactScene: CapturedScene<C, S, Services, P, N, Identity>,
+    ): Proof => {
+      const proofCase: ProofCase<Comp, C, S, Services, P, N, Identity> = {
+        requirement,
+        scene: exactScene,
+        placement: 'Slot',
+        body,
+      }
+      return {
+        requirement,
+        scene: exactScene,
+        capture: (visit) => visit<Comp, C, S, Services, P, N, Identity>(proofCase),
+      }
+    },
+  )
 
-/** The proofs a `Proof.suite` binds to its product. */
 interface MakeSuiteConfig {
   readonly proofs: ReadonlyArray<Proof>
 }
 
-/** Compose proofs with the product whose requirements they prove. */
 const suite = (product: ProductClass, config: MakeSuiteConfig): ProofSuite => ({
   kind: 'ProofSuite',
   product,
   proofs: config.proofs,
 })
 
-/** Duck-type a `ProofSuite` among arbitrary module exports (the adapter's seam). */
 export const isProofSuite = (candidate: unknown): candidate is ProofSuite =>
   isRecord(candidate) && candidate['kind'] === 'ProofSuite' && Array.isArray(candidate['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 reports = await Effect.runPromise(
-      Effect.forEach(proofSuite.proofs, (proof) => Effect.promise(() => runner.executeProof(proof))),
-    )
-    return {
+  Effect.runPromise(runEffect(proofSuite))
+
+const runEffect = (proofSuite: ProofSuite): Effect.Effect<SuiteResult, never, never> =>
+  ProofRunner.pipe(
+    Effect.flatMap((runner) =>
+      Effect.forEach(proofSuite.proofs, (proof) => runner.executeProofEffect(proof)),
+    ),
+    Effect.map((reports) => ({
       product: proofSuite.product.manifest.name,
       results: reports,
       ok: reports.every((report) => report.ok),
-    }
-  })
-
-// ---------------------------------------------------------------------------
-// Driver: step a proof for the editor's Test-play timeline
-// ---------------------------------------------------------------------------
+    })),
+    Effect.provide(proofRunnerLayer),
+  )
 
-/** 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>
+  readonly captures: ReadonlyArray<CapturedRender>
 }
 
 export interface DriveResult {
   readonly requirement: string
   readonly frames: ReadonlyArray<StepFrame>
   readonly ok: boolean
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- serialized result DTO read as `error ?? …` by the editor timeline (external); optional kept for wire compat
-  readonly error?: string
+  readonly error: string | undefined
 }
 
 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,
@@ -418,7 +440,9 @@ const driver = (proofSuite: ProofSuite): ReadonlyArray<ProofDriver> =>
 
 export const Proof: {
   readonly implement: typeof implement
+  readonly implementVia: typeof implementVia
   readonly suite: typeof suite
   readonly run: typeof run
+  readonly runEffect: typeof runEffect
   readonly driver: typeof driver
-} = { implement, suite, run, driver }
+} = { implement, implementVia, suite, run, runEffect, driver }