@playfast/reform-proof 1.1.1 → 1.2.0

package/src/fingerprint.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest'
+import { formatFingerprint } from './fingerprint'
+
+describe('proof render fingerprints', () => {
+  it('distinguishes bigint props from strings without throwing', () => {
+    expect(formatFingerprint({ sequence: 1n })).not.toBe(formatFingerprint({ sequence: '1' }))
+  })
+
+  it('stabilizes equivalent cyclic render props', () => {
+    const left: Array<unknown> = []
+    left.push(left)
+    const right: Array<unknown> = []
+    right.push(right)
+
+    expect(formatFingerprint(left)).toBe(formatFingerprint(right))
+  })
+
+  it('tracks Map and Set contents', () => {
+    expect(formatFingerprint(new Map([['feature', 'home']]))).not.toBe(
+      formatFingerprint(new Map([['feature', 'tasks']])),
+    )
+    expect(formatFingerprint(new Set(['home']))).not.toBe(formatFingerprint(new Set(['tasks'])))
+  })
+})

package/src/fingerprint.ts

@@ -0,0 +1,73 @@
+import * as Option from 'effect/Option'
+
+const readPropertyOption = Option.liftThrowable((target: object, key: PropertyKey): unknown =>
+  Reflect.get(target, key),
+)
+
+const readProperty = (target: object, key: PropertyKey): unknown =>
+  Option.getOrElse(readPropertyOption(target, key), () => '[Property read threw]')
+
+const propertyKeyFingerprint = (key: PropertyKey): string =>
+  typeof key === 'symbol'
+    ? `symbol:${String(key.description)}`
+    : typeof key === 'number'
+      ? `number-key:${String(key)}`
+      : `key:${key.length}:${key}`
+
+const valueFingerprint = (candidate: unknown, seen: WeakSet<object>): string => {
+  if (typeof candidate === 'bigint') {
+    return `bigint:${String(candidate)}`
+  }
+  if (typeof candidate === 'boolean') {
+    return candidate ? 'boolean:true' : 'boolean:false'
+  }
+  if (typeof candidate === 'function') {
+    return `function:${String(candidate)}`
+  }
+  if (typeof candidate === 'number') {
+    return `number:${String(candidate)}`
+  }
+  if (typeof candidate === 'string') {
+    return `string:${candidate.length}:${candidate}`
+  }
+  if (typeof candidate === 'symbol') {
+    return `symbol:${String(candidate.description)}`
+  }
+  if (typeof candidate === 'undefined') {
+    return 'undefined'
+  }
+  if (candidate === null) {
+    return 'null'
+  }
+  if (seen.has(candidate)) {
+    return '[Circular]'
+  }
+  seen.add(candidate)
+  if (Array.isArray(candidate)) {
+    return `[${candidate.map((arrayEntry) => valueFingerprint(arrayEntry, seen)).join(',')}]`
+  }
+  if (candidate instanceof Date) {
+    return `date:${String(candidate.getTime())}`
+  }
+  if (candidate instanceof Map) {
+    return `map:[${Array.from(
+      candidate,
+      ([mapKey, mapEntry]) =>
+        `${valueFingerprint(mapKey, seen)}=>${valueFingerprint(mapEntry, seen)}`,
+    ).join(',')}]`
+  }
+  if (candidate instanceof Set) {
+    return `set:[${Array.from(candidate, (setEntry) => valueFingerprint(setEntry, seen)).join(
+      ',',
+    )}]`
+  }
+  return `{${Reflect.ownKeys(candidate)
+    .map(
+      (key) =>
+        `${propertyKeyFingerprint(key)}:${valueFingerprint(readProperty(candidate, key), seen)}`,
+    )
+    .join(',')}}`
+}
+
+export const formatFingerprint = (fingerprintInput: unknown): string =>
+  valueFingerprint(fingerprintInput, new WeakSet())

package/src/index.ts

@@ -1,25 +1,24 @@
-import { Effect, type Schema } from 'effect'
+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 ProductClass, type RequirementClass } from './product'
-import type { ProofDriver } from './driverTypes'
 import type {
-  CompositionClass,
-  CompositionService,
+  CapturedScene,
   Scene,
-  SlotInstance,
+  SlotComposition as ReformSlotComposition,
+  SlotContract as ReformSlotContract,
   Trigger,
   UiContract,
 } from '@playfast/reform'
-
-type AnyValue = Schema.Schema.Type<Schema.Schema.Any>
-type AnyComposition = CompositionClass<AnyValue, AnyValue>
+import type { AnyComposition, AnyScene, CapturedRender } from '@playfast/reform/internal'
 
 export { ProofRunner, proofRunnerLayer, withProofRunner }
 export type { ProofRunnerApi }
 
 export {
   makeFacade,
+  makeProofFacade,
   makeRuntimeHandleFacade,
   makeRuntimeTreeFacade,
   makeSink,
@@ -28,72 +27,272 @@ export {
 export type {
   MountedFacade,
   MountedSlotFacade,
-  RuntimeServices,
+  MountedSlotFacadesOf,
   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>
+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
+}
+
+export type RequirementCapture<Result> = <
+  Comp extends ProductComposition,
+  Statement extends string,
+>(
+  requirement: RequirementClass<Comp, Statement>,
+) => Result
+
+export interface RequirementManifest<Comp extends ProductComposition, Statement extends string> {
+  readonly kind: 'ProductRequirement'
+  readonly name: Statement
+  readonly statement: Statement
+  readonly composition: Comp
+  readonly events: Option.Option<ReadonlyArray<EventNamesOf<ContractOf<Comp>>>>
+}
+
+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 ProductComposition> {
+  readonly kind: 'Product'
+  readonly name: string
+  readonly composition: Comp
+  readonly requirements: ReadonlyArray<AnyRequirementClass>
+}
+
+export interface ProductClass<Comp extends ProductComposition = ProductComposition> {
+  new (): {}
+  readonly manifest: ProductManifest<Comp>
+}
+
+interface MakeRequirementOptionsExternalApi<Comp extends ProductComposition> {
+  readonly events?: ReadonlyArray<EventNamesOf<ContractOf<Comp>>>
+}
+
+const makeRequirement = <Comp extends ProductComposition, 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),
+  }
+  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,
+}
+
+interface MakeProductConfig<Comp extends ProductComposition> {
+  readonly requirements: ReadonlyArray<RequirementClass<Comp, string>>
+}
+
+const makeProduct = <Comp extends ProductComposition>(
+  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,
+}
+
+interface ComparePair {
+  readonly left: unknown
+  readonly right: unknown
+}
+
+const show = (subject: unknown): string => formatFingerprint(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)
+  },
+})
+
+const isRecord = (candidate: unknown): candidate is Record<string, unknown> =>
+  typeof candidate === 'object' && candidate !== null
+
+interface MatchInput {
+  readonly actual: unknown
+  readonly expected: unknown
+}
+
+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])}`,
+  })
+}
+
+export const matchProps: (input: MatchInput) => string | undefined = matchPartial
+
+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 CompositionClass<AnyValue, infer C> ? C : never
-type ContractOfSlot<S> = S extends SlotInstance<infer Comp> ? ContractOf<Comp> : never
+export type ContractOf<Comp> = Comp extends {
+  readonly Contract: infer C extends UiContract
+}
+  ? C
+  : never
+type ContractOfSlot<S> = ReformSlotContract<S>
 
-export type ActionsOf<C extends UiContract> = {
-  readonly [K in keyof EventsOf<C>]: (
-    payload: PayloadOf<EventsOf<C>[K]>,
-  ) => Effect.Effect<C['props'], never, CompositionService>
+export type ActionsOf<C extends UiContract, R = never> = C extends {
+  readonly events: NonNullable<UiContract['events']>
 }
-export type SlotFacadesOf<C extends UiContract> = {
-  readonly [K in keyof SlotsOf<C>]: SlotFacade<ContractOfSlot<SlotsOf<C>[K]>>
+  ? {
+      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>>
 
-export type Action = (payload: unknown) => Effect.Effect<unknown, never, CompositionService>
+export type Action<R = never> = (payload: unknown) => Effect.Effect<unknown, never, R>
 
-export interface Facade<C extends UiContract> {
-  readonly props: Effect.Effect<C['props'], never, CompositionService>
-  readonly expectProps: (partial: Partial<C['props']>) => Effect.Effect<void, never, CompositionService>
-  readonly actions: ActionsOf<C>
-  readonly slots: SlotFacadesOf<C>
-  readonly frame: Effect.Effect<void, never, CompositionService>
+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> 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>
-  readonly byKey: (key: string) => Effect.Effect<Facade<C>, never, CompositionService>
+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>
-  readonly count: Effect.Effect<number, never, CompositionService>
+  ) => Effect.Effect<ReadonlyArray<Facade<C, R>>, never, R>
+  readonly count: Effect.Effect<number, never, R>
 }
 
-type ProofGenerator = Generator<
-  YieldWrap<Effect.Effect<unknown, unknown, CompositionService>>,
-  void,
-  unknown
->
+type ProofGenerator = Generator<YieldWrap<Effect.Effect<unknown, unknown, never>>, void, unknown>
 
-type AnyFacade = Facade<UiContract>
+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
+}
 
-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>
-  readonly scene: Scene
-  readonly body: ProofBody
+  readonly requirement: AnyRequirementClass
+  readonly scene: AnyScene
+  readonly capture: <Result>(visit: ProofCapture<Result>) => Result
 }
 
 export interface ProofSuite {
@@ -102,14 +301,10 @@ export interface ProofSuite {
   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
-  // 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 {
@@ -118,29 +313,78 @@ export interface SuiteResult {
   readonly ok: boolean
 }
 
-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 SlotsHolding<C extends UiContract, Target> = {
-  [K in keyof SlotsOf<C>]: ContractOfSlot<SlotsOf<C>[K]> extends Target ? K : never
-}[keyof SlotsOf<C>]
+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 AnyComposition, C extends UiContract>(
+const implementVia = <
+  Comp extends ProductComposition,
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+>(
   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 }
-}
+  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),
+      }
+    },
+  )
 
 interface MakeSuiteConfig {
   readonly proofs: ReadonlyArray<Proof>
@@ -156,18 +400,38 @@ export const isProofSuite = (candidate: unknown): candidate is ProofSuite =>
   isRecord(candidate) && candidate['kind'] === 'ProofSuite' && Array.isArray(candidate['proofs'])
 
 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),
-    }
-  })
+    })),
+    Effect.provide(proofRunnerLayer),
+  )
+
+export interface StepFrame {
+  readonly index: number
+  readonly captures: ReadonlyArray<CapturedRender>
+}
+
+export interface DriveResult {
+  readonly requirement: string
+  readonly frames: ReadonlyArray<StepFrame>
+  readonly ok: boolean
+  readonly error: string | undefined
+}
+
+export interface ProofDriver {
+  readonly requirement: string
+  readonly run: () => Promise<DriveResult>
+}
 
-export type { DriveResult, ProofDriver, StepFrame } from './driverTypes'
 const driver = (proofSuite: ProofSuite): ReadonlyArray<ProofDriver> =>
   proofSuite.proofs.map((proof) => ({
     requirement: proof.requirement.manifest.statement,
@@ -179,5 +443,6 @@ export const Proof: {
   readonly implementVia: typeof implementVia
   readonly suite: typeof suite
   readonly run: typeof run
+  readonly runEffect: typeof runEffect
   readonly driver: typeof driver
-} = { implement, implementVia, suite, run, driver }
+} = { implement, implementVia, suite, run, runEffect, driver }