@playfast/reform-proof 1.0.1 → 1.1.1

package/src/index.ts

@@ -1,324 +1,110 @@
-import { Array as Arr, Effect, Option, Record as Rec } from 'effect'
+import { Effect, type Schema } from 'effect'
 import type { YieldWrap } from 'effect/Utils'
-import { AssertionFailed } from './errors'
 import { ProofRunner, type ProofRunnerApi, proofRunnerLayer, withProofRunner } from './runner'
+import { type ProductClass, type RequirementClass } from './product'
+import type { ProofDriver } from './driverTypes'
 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.
+type AnyValue = Schema.Schema.Type<Schema.Schema.Any>
+type AnyComposition = CompositionClass<AnyValue, AnyValue>
 
-// 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
-// ---------------------------------------------------------------------------
-
-/** 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: Option.Option<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`.
- */
-/** Author-facing config for `ProductRequirement.make` — plain JSON the proof author passes. */
-interface MakeRequirementOptionsExternalApi<Comp extends AnyComposition> {
-  readonly events?: ReadonlyArray<keyof EventsOf<ContractOf<Comp>>>
-}
-
-const makeRequirement = <Comp extends AnyComposition, const Statement extends string>(
-  composition: Comp,
-  statement: Statement,
-  options?: MakeRequirementOptionsExternalApi<Comp>,
-): RequirementClass<Comp, Statement> => {
-  const manifest: RequirementManifest<Comp, Statement> = {
-    kind: 'ProductRequirement',
-    name: statement,
-    statement,
-    composition,
-    events: Option.fromNullable(options?.events),
-  }
-  return class {
-    static readonly manifest = manifest
-  }
-}
-
-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> {
-  readonly requirements: ReadonlyArray<RequirementClass<Comp, string>>
-}
-
-const makeProduct = <Comp extends AnyComposition>(
-  composition: Comp,
-  config: MakeProductConfig<Comp>,
-): ProductClass<Comp> => {
-  const manifest: ProductManifest<Comp> = {
-    kind: 'Product',
-    name: composition.manifest.name,
-    composition,
-    requirements: config.requirements,
-  }
-  return class {
-    static readonly manifest = manifest
-  }
-}
-
-export const Product: { readonly make: typeof makeProduct } = { make: makeProduct }
-
-// ---------------------------------------------------------------------------
-// Assertions — Effect-returning matchers; a failed match fails the proof.
-// ---------------------------------------------------------------------------
-
-/** 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 deepEqual = ({ left, right }: ComparePair): boolean =>
-  Object.is(left, right) || show(left) === show(right)
-
-const fail = (message: string): Effect.Effect<never> =>
-  Effect.dieMessage(new AssertionFailed({ detail: message }).message)
-
-export const expect = <A>(actual: A) => ({
-  toBe: (expected: A): Effect.Effect<void> =>
-    Object.is(actual, expected)
-      ? Effect.void
-      : fail(`expected ${show(actual)} to be ${show(expected)}`),
-  toEqual: (expected: A): Effect.Effect<void> =>
-    deepEqual({ left: actual, right: expected })
-      ? Effect.void
-      : fail(`expected ${show(actual)} to equal ${show(expected)}`),
-  toContain: (expected: A extends ReadonlyArray<infer E> ? E : unknown): Effect.Effect<void> =>
-    Array.isArray(actual) && actual.some((element) => deepEqual({ left: element, right: expected }))
-      ? Effect.void
-      : fail(`expected ${show(actual)} to contain ${show(expected)}`),
-  toMatchObject: (expected: Partial<A>): Effect.Effect<void> => {
-    const mismatch = matchPartial({ actual, expected })
-    return mismatch === undefined ? Effect.void : fail(mismatch)
-  },
-})
-
-/** 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 })
-      ? undefined
-      : `expected ${show(actual)} to match ${show(expected)}`
-  }
-  if (!isRecord(actual)) {
-    return `expected ${show(actual)} to be an object matching ${show(expected)}`
-  }
-  const mismatch = Arr.findFirst(
-    Rec.keys(expected),
-    (key) => !deepEqual({ left: actual[key], right: expected[key] }),
-  )
-  return Option.match(mismatch, {
-    onNone: () => undefined,
-    onSome: (key) =>
-      `expected key ${show(key)} to match ${show(expected[key])}, got ${show(actual[key])}`,
-  })
-}
-
-/** 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
-// ---------------------------------------------------------------------------
-
-// --- 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. */
+export {
+  makeFacade,
+  makeRuntimeHandleFacade,
+  makeRuntimeTreeFacade,
+  makeSink,
+  proofLayer,
+} from './engine'
+export type {
+  MountedFacade,
+  MountedSlotFacade,
+  RuntimeServices,
+  RuntimeTreeFacade,
+  Sink,
+} from './engine'
+
+export {
+  Product,
+  type ProductClass,
+  type ProductManifest,
+  ProductRequirement,
+  type RequirementClass,
+  type RequirementManifest,
+} from './product'
+
+export { expect, matchProps } from './assertions'
+
+export type EventsOf<C extends UiContract> = C extends { events: infer E } ? E : Record<never, never>
 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. */
+export type ContractOf<Comp> = Comp extends CompositionClass<AnyValue, infer C> ? C : never
 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>
 }
 
+const isRecord = (candidate: unknown): candidate is Record<string, unknown> =>
+  typeof candidate === 'object' && candidate !== null
+
 export interface ProofResult {
   readonly requirement: string
   readonly ok: boolean
@@ -332,14 +118,6 @@ 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>(
   requirement: RequirementClass<Comp, string>,
   scene: Scene<ContractOf<Comp>>,
@@ -350,27 +128,33 @@ const implement = <Comp extends AnyComposition>(
   return { requirement, scene, body: erased }
 }
 
-/** The proofs a `Proof.suite` binds to its product. */
+type SlotsHolding<C extends UiContract, Target> = {
+  [K in keyof SlotsOf<C>]: ContractOfSlot<SlotsOf<C>[K]> extends Target ? K : never
+}[keyof SlotsOf<C>]
+
+const implementVia = <Comp extends AnyComposition, C extends UiContract>(
+  requirement: RequirementClass<Comp, string>,
+  scene: Scene<C> & ([SlotsHolding<C, ContractOf<Comp>>] extends [never] ? never : unknown),
+  body: (app: Facade<C>) => 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 }
+}
+
 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(
@@ -383,33 +167,7 @@ const run = (proofSuite: ProofSuite): Promise<SuiteResult> =>
     }
   })
 
-// ---------------------------------------------------------------------------
-// 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
-  // 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
-}
-
-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. */
+export type { DriveResult, ProofDriver, StepFrame } from './driverTypes'
 const driver = (proofSuite: ProofSuite): ReadonlyArray<ProofDriver> =>
   proofSuite.proofs.map((proof) => ({
     requirement: proof.requirement.manifest.statement,
@@ -418,7 +176,8 @@ 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 driver: typeof driver
-} = { implement, suite, run, driver }
+} = { implement, implementVia, suite, run, driver }

package/src/product.ts

@@ -0,0 +1,77 @@
+import { Option, type Schema } from 'effect'
+import type { CompositionClass } from '@playfast/reform'
+import type { ContractOf, EventsOf } from './index'
+
+type AnyValue = Schema.Schema.Type<Schema.Schema.Any>
+type AnyComposition = CompositionClass<AnyValue, AnyValue>
+
+export interface RequirementManifest<Comp extends AnyComposition, Statement extends string> {
+  readonly kind: 'ProductRequirement'
+  readonly name: Statement
+  readonly statement: Statement
+  readonly composition: Comp
+  readonly events: Option.Option<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>
+}
+
+interface MakeRequirementOptionsExternalApi<Comp extends AnyComposition> {
+  readonly events?: ReadonlyArray<keyof EventsOf<ContractOf<Comp>>>
+}
+
+const makeRequirement = <Comp extends AnyComposition, const Statement extends string>(
+  composition: Comp,
+  statement: Statement,
+  options?: MakeRequirementOptionsExternalApi<Comp>,
+): RequirementClass<Comp, Statement> => {
+  const manifest: RequirementManifest<Comp, Statement> = {
+    kind: 'ProductRequirement',
+    name: statement,
+    statement,
+    composition,
+    events: Option.fromNullable(options?.events),
+  }
+  return class {
+    static readonly manifest = manifest
+  }
+}
+
+export const ProductRequirement: { readonly make: typeof makeRequirement } = {
+  make: makeRequirement,
+}
+
+interface MakeProductConfig<Comp extends AnyComposition> {
+  readonly requirements: ReadonlyArray<RequirementClass<Comp, string>>
+}
+
+const makeProduct = <Comp extends AnyComposition>(
+  composition: Comp,
+  config: MakeProductConfig<Comp>,
+): ProductClass<Comp> => {
+  const manifest: ProductManifest<Comp> = {
+    kind: 'Product',
+    name: composition.manifest.name,
+    composition,
+    requirements: config.requirements,
+  }
+  return class {
+    static readonly manifest = manifest
+  }
+}
+
+export const Product: { readonly make: typeof makeProduct } = { make: makeProduct }

package/src/runner.ts

@@ -1,38 +1,22 @@
 import { Context, Effect, Layer } from 'effect'
-import { driveProof, executeProof } from './engine'
+import { driveProof, executeProof } from './execution'
 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(