@playfast/reform-proof 1.2.0 → 1.3.0

package/src/engineSink.ts

@@ -0,0 +1,195 @@
+import { Clock, type Context, type Duration, Effect, MutableRef, Option } from 'effect'
+import { AssertionFailed } from './errors'
+import {
+  Composition,
+  type CompositionClass,
+  type CompositionService,
+  isStructure,
+  type RuntimeHandle,
+  type Structure,
+  type Trigger,
+  type UiContract,
+} from '@playfast/reform'
+import {
+  type AnyComposition,
+  type CapturedRender,
+  type CaptureSinkApi,
+  type Instrumentation,
+  noopInstrumentation,
+} from '@playfast/reform/internal'
+import { matchProps } from './assert'
+import type { Facade, SlotFacade, SlotFacadesOf } from './facade'
+
+export type RenderRuntime = Pick<RuntimeHandle, 'dispatch' | 'instrumentation' | 'readOption'>
+
+export type HostRuntime = Pick<
+  RuntimeHandle,
+  'dispatch' | 'instrumentation' | 'mountAnyFeature' | 'readOption'
+>
+
+export type RuntimeRootComposition<
+  Identifier,
+  P,
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  N extends string,
+  Identity,
+> = CompositionClass<P, C, S, N, Identity> & {
+  readonly tag: Context.Tag<Identifier, CompositionService<P, C>>
+}
+
+export interface MountedFacadeErasure {
+  readonly props: Effect.Effect<unknown, never, never>
+  readonly expectProps: (partial: unknown) => Effect.Effect<void, never, never>
+  readonly actions: Readonly<
+    Record<string, (payload: unknown) => Effect.Effect<unknown, never, never>>
+  >
+  readonly slots: Readonly<Record<string, MountedSlotFacadeErasure>>
+  readonly frame: Effect.Effect<void, never, never>
+  readonly advance: (duration: Duration.DurationInput) => Effect.Effect<void, never, never>
+}
+
+export interface MountedSlotFacadeErasure extends MountedFacadeErasure {
+  readonly first: Effect.Effect<MountedFacadeErasure, never, never>
+  readonly at: (index: number) => Effect.Effect<MountedFacadeErasure, never, never>
+  readonly all: Effect.Effect<ReadonlyArray<MountedFacadeErasure>, never, never>
+  readonly byKey: (key: string) => Effect.Effect<MountedFacadeErasure, never, never>
+  readonly where: (
+    predicate: (props: unknown) => boolean,
+  ) => Effect.Effect<ReadonlyArray<MountedFacadeErasure>, never, never>
+  readonly count: Effect.Effect<number, never, never>
+}
+
+export interface MountedFacadeHandleErasure {
+  readonly facade: {
+    readonly props: Effect.Effect<unknown, never, never>
+    readonly expectProps: (partial: never) => Effect.Effect<void, never, never>
+    readonly actions: object
+    readonly slots: object
+    readonly frame: Effect.Effect<void, never, never>
+    readonly advance: (duration: Duration.DurationInput) => Effect.Effect<void, never, never>
+  }
+  readonly settle: Effect.Effect<void, never, never>
+}
+
+export type Settlement = Effect.Effect<void, never, never>
+export type SettleBoundary = (settlement: Settlement) => Settlement
+
+export const directSettle: SettleBoundary = (settlement) => settlement
+
+// Cooperative yields flush synchronous fibers; the real-time sleep prevents a
+// genuinely delayed flow from looking stable between renders.
+export const SETTLE_DRAIN = 30
+export const SETTLE_STEP = '1 milli'
+export const SETTLE_MAX_RENDERS = 100
+
+export const settleDrain: Effect.Effect<void> = Effect.yieldNow().pipe(Effect.repeatN(SETTLE_DRAIN))
+
+// The drain's own pacing is harness time, and harness time is always real. A scene
+// may install `Proof.withTestClock` to freeze PRODUCT time, and the proof body runs
+// on that same runtime — so an unpinned sleep here would freeze with it and the
+// settle loop would never make progress. Pinning it to a real clock is what lets the
+// two clocks coexist: the harness keeps advancing while the product's timers hold
+// still until `app.advance(...)` moves them.
+export const settleStep: Effect.Effect<void> = Effect.sleep(SETTLE_STEP).pipe(Effect.withClock(Clock.make()))
+
+export const keyed = <V>(get: (key: string) => V): Record<string, V> => {
+  const target: Record<string, V> = Object.create(null)
+  return new Proxy(target, { get: (_target, key) => get(String(key)) })
+}
+
+export const messageOf = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error)
+
+export const uiNameOf = (comp: AnyComposition): string => comp.manifest.ui.manifest.name
+
+// UiContract erases event values to never, so this boundary needs no assertion.
+export const eventsOf = (structure: Structure<UiContract>): Record<string, Trigger<unknown>> => ({
+  ...structure.events,
+})
+
+export interface ExpectedProps {
+  readonly actual: unknown
+  readonly expected: unknown
+}
+
+export const expectMatchingProps = ({
+  actual,
+  expected,
+}: ExpectedProps): Effect.Effect<void, never, never> =>
+  Option.match(Option.fromNullable(matchProps({ actual, expected })), {
+    onNone: () => Effect.void,
+    onSome: (detail) => Effect.dieMessage(new AssertionFailed({ detail }).message),
+  })
+
+export const invalidCompositionProps = (composition: AnyComposition): string =>
+  `reform-proof: invalid props for composition ${composition.manifest.name}`
+
+export const renderCompositionRuntime = (
+  runtime: RenderRuntime,
+  composition: AnyComposition,
+  props: unknown,
+): Structure<UiContract> =>
+  composition.capture(
+    <P, C extends UiContract, S extends ReadonlyArray<unknown>, N extends string, Identity>(
+      exact: CompositionClass<P, C, S, N, Identity>,
+    ): Structure<UiContract> => {
+      const resolved = Option.flatMap(exact.parseProps(props), (parsed) =>
+        Option.map(runtime.readOption(exact.tag), (service) => ({
+          parsed,
+          service,
+        })),
+      )
+      return Option.match(resolved, {
+        onNone: () => Effect.runSync(Effect.dieMessage(invalidCompositionProps(composition))),
+        onSome: ({ parsed, service }) => {
+          const frame = Effect.runSync(
+            Composition.render(service, {
+              props: parsed,
+              tracker: { add: () => {} },
+            }),
+          )
+          if (isStructure(frame)) {
+            return frame
+          }
+          return Effect.runSync(
+            Effect.dieMessage(
+              `reform-proof: composition ${composition.manifest.name} did not return a Structure`,
+            ),
+          )
+        },
+      })
+    },
+  )
+
+export interface Sink {
+  readonly api: CaptureSinkApi
+  readonly captures: ReadonlyArray<CapturedRender>
+  readonly instrumentation: Instrumentation
+  reset(): void
+}
+
+export const makeSink = (instrumentation: Instrumentation = noopInstrumentation): Sink => {
+  // CaptureSink.record is synchronous, so this uses MutableRef rather than Ref.
+  const captures = MutableRef.make<CapturedRender[]>([])
+  return {
+    api: {
+      record: (capture) => {
+        MutableRef.update(captures, (current) => [...current, capture])
+      },
+    },
+    get captures() {
+      return MutableRef.get(captures)
+    },
+    instrumentation,
+    reset: () => {
+      MutableRef.set(captures, [])
+    },
+  }
+}
+
+export type MountedSlotFacadesOf<C extends UiContract> = SlotFacadesOf<C, never>
+
+export type MountedFacade<C extends UiContract> = Facade<C, never>
+
+export type MountedSlotFacade<C extends UiContract> = SlotFacade<C, never>

package/src/engineTree.ts

@@ -0,0 +1,298 @@
+import { Array as Arr, Context, Effect, Layer, Match, MutableRef, Option, Record as Rec } from 'effect'
+import {
+  type CapturedScene,
+  isFeatureBinding,
+  isSlot,
+  publish,
+  type SlotFill,
+  type Structure,
+  type UiContract,
+} from '@playfast/reform'
+import {
+  type AnyComposition,
+  type AnySlot,
+  type AnySlotChild,
+  Bus,
+  type CapturedRender,
+  CaptureSink,
+  type Instrumentation,
+} from '@playfast/reform/internal'
+import { formatFingerprint } from './fingerprint'
+import {
+  eventsOf,
+  type RenderRuntime,
+  SETTLE_MAX_RENDERS,
+  type Sink,
+  uiNameOf,
+} from './engineSink'
+
+export const proofLayer = <
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  Services,
+  P,
+  N extends string,
+  Identity,
+>(
+  scene: CapturedScene<C, S, Services, P, N, Identity>,
+  sink: Sink,
+): Layer.Layer<Services | CaptureSink, never, never> => {
+  const sceneLayer = scene.provide.reduce((merged, layer) => Layer.merge(merged, layer))
+  return Layer.merge(sceneLayer, Layer.succeed(CaptureSink, sink.api))
+}
+
+export const missingRuntimeBus = (): never =>
+  Effect.runSync(Effect.dieMessage('reform-proof: scene does not provide Bus'))
+
+export const renderRuntimeFromContext = <Services>(
+  context: Context.Context<Services>,
+  instrumentation: Instrumentation,
+): RenderRuntime => {
+  const bus = Context.getOption(context, Bus)
+  return {
+    dispatch: (priority, event) =>
+      Option.match(bus, {
+        onNone: missingRuntimeBus,
+        onSome: (service) =>
+          Effect.runSync(publish(priority, event).pipe(Effect.provideService(Bus, service))),
+      }),
+    instrumentation,
+    readOption: (tag) => Context.getOption(context, tag),
+  }
+}
+
+export interface Mounted {
+  readonly comp: AnyComposition
+  readonly props: unknown
+  readonly ref: NodeRef
+}
+
+export interface SlotInstanceRef {
+  readonly name: string
+  readonly index: number
+  readonly key: Option.Option<string>
+  readonly keyOccurrence: number
+}
+
+export interface NodeRef {
+  readonly name: string
+  readonly parent: Option.Option<NodeRef>
+  readonly slot: Option.Option<SlotInstanceRef>
+}
+
+export interface NodeCapture {
+  readonly ref: NodeRef
+  readonly capture: CapturedRender
+}
+
+export interface CaptureLookup {
+  readonly captures: ReadonlyArray<NodeCapture>
+  record(ref: NodeRef, capture: CapturedRender): void
+  reset(): void
+}
+
+export const makeCaptureLookup = (): CaptureLookup => {
+  const captures = MutableRef.make<ReadonlyArray<NodeCapture>>([])
+  return {
+    get captures() {
+      return MutableRef.get(captures)
+    },
+    record: (ref, capture) => {
+      MutableRef.update(captures, (current) => [...current, { ref, capture }])
+    },
+    reset: () => {
+      MutableRef.set(captures, [])
+    },
+  }
+}
+
+export const sameSlotInstance = (expected: SlotInstanceRef, actual: SlotInstanceRef): boolean =>
+  expected.name === actual.name &&
+  Option.match(expected.key, {
+    onNone: () => expected.index === actual.index,
+    onSome: (key) =>
+      expected.keyOccurrence === actual.keyOccurrence && Option.contains(actual.key, key),
+  })
+
+export const sameNodeRef = (expected: NodeRef, actual: NodeRef): boolean =>
+  expected.name === actual.name &&
+  Option.match(expected.parent, {
+    onNone: () => Option.isNone(actual.parent) && Option.isNone(actual.slot),
+    onSome: (expectedParent) =>
+      Option.isSome(actual.parent) &&
+      Option.isSome(expected.slot) &&
+      Option.isSome(actual.slot) &&
+      sameNodeRef(expectedParent, actual.parent.value) &&
+      sameSlotInstance(expected.slot.value, actual.slot.value),
+  })
+
+export const rootRef = (root: AnyComposition): NodeRef => ({
+  name: uiNameOf(root),
+  parent: Option.none(),
+  slot: Option.none(),
+})
+
+export const nodeCaptureFor = (lookup: CaptureLookup, ref: NodeRef): Option.Option<CapturedRender> =>
+  Option.map(
+    Arr.findFirst(lookup.captures, (entry) => sameNodeRef(ref, entry.ref)),
+    (entry) => entry.capture,
+  )
+
+export const slotCapturesFor = (
+  lookup: CaptureLookup,
+  parent: NodeRef,
+  slotName: string,
+): ReadonlyArray<NodeCapture> =>
+  lookup.captures.filter(
+    (entry) =>
+      Option.isSome(entry.ref.parent) &&
+      Option.isSome(entry.ref.slot) &&
+      sameNodeRef(parent, entry.ref.parent.value) &&
+      entry.ref.slot.value.name === slotName,
+  )
+
+export interface SettleProgress {
+  readonly previous: string
+  readonly remaining: number
+  readonly stable: boolean
+}
+
+export const ensureSettled = (progress: SettleProgress): Effect.Effect<void, never, never> => {
+  if (progress.stable) {
+    return Effect.void
+  }
+  return Effect.dieMessage(`reform-proof: tree did not settle after ${SETTLE_MAX_RENDERS} renders`)
+}
+
+export interface PumpStep {
+  readonly input: unknown
+  readonly index: number
+}
+
+export const childComposition = (child: AnySlotChild): AnyComposition =>
+  isFeatureBinding(child) ? child.capture<AnyComposition>((binding) => binding.composition) : child
+
+export const isUnknownRecord = (candidate: unknown): candidate is Record<string, unknown> =>
+  typeof candidate === 'object' && candidate !== null && !Array.isArray(candidate)
+
+export const slotsOf = (comp: AnyComposition): Record<string, AnySlot> =>
+  comp.capture<Record<string, AnySlot>>((exact) => {
+    if (!('slots' in exact.manifest)) {
+      return {}
+    }
+    const candidate: unknown = exact.manifest.slots
+    if (!isUnknownRecord(candidate)) {
+      return {}
+    }
+    return Rec.fromEntries(
+      Rec.toEntries(candidate).flatMap(
+        ([name, slotDefinition]): ReadonlyArray<readonly [string, AnySlot]> =>
+          isSlot(slotDefinition) ? [[name, slotDefinition]] : [],
+      ),
+    )
+  })
+
+export interface RuntimeSlotRead {
+  readonly runtime: RenderRuntime
+  readonly slotDefinition: AnySlot
+  readonly parent: AnyComposition
+}
+
+export const readRuntimeSlotChild = ({ runtime, slotDefinition, parent }: RuntimeSlotRead): AnySlotChild =>
+  slotDefinition.capture<AnySlotChild>((exact) =>
+    Option.match(runtime.readOption(exact.provider), {
+      onNone: () =>
+        Effect.runSync(
+          Effect.dieMessage(`reform-proof: slot provider missing in ${uiNameOf(parent)}`),
+        ),
+      onSome: (child) => child,
+    }),
+  )
+
+// UiContract erases per-slot fill types here, so recover them by discriminant.
+export const isSlotFill = (candidate: unknown): candidate is SlotFill<unknown> =>
+  typeof candidate === 'object' &&
+  candidate !== null &&
+  '_tag' in candidate &&
+  (candidate._tag === 'Each' || candidate._tag === 'One' || candidate._tag === 'Absent')
+
+export const structureFills = (structure: Structure<UiContract>): Record<string, SlotFill<unknown>> =>
+  Rec.fromEntries(
+    Rec.toEntries(structure.slots).flatMap(
+      ([slotName, fillValue]): ReadonlyArray<readonly [string, SlotFill<unknown>]> =>
+        isSlotFill(fillValue) ? [[slotName, fillValue]] : [],
+    ),
+  )
+
+export const enqueueFill = (
+  parent: NodeRef,
+  slotName: string,
+  fill: SlotFill<unknown>,
+  child: AnyComposition,
+): ReadonlyArray<Mounted> =>
+  Match.value(fill).pipe(
+    Match.when({ _tag: 'Each' }, (each) =>
+      each.items.map((entry, index) => ({
+        comp: child,
+        props: entry.props,
+        ref: {
+          name: uiNameOf(child),
+          parent: Option.some(parent),
+          slot: Option.some({
+            name: slotName,
+            index,
+            key: Option.some(entry.key),
+            keyOccurrence: each.items
+              .slice(0, index)
+              .filter((candidate) => candidate.key === entry.key).length,
+          }),
+        },
+      })),
+    ),
+    Match.when({ _tag: 'One' }, (oneFill) => [
+      {
+        comp: child,
+        props: oneFill.props,
+        ref: {
+          name: uiNameOf(child),
+          parent: Option.some(parent),
+          slot: Option.some({
+            name: slotName,
+            index: 0,
+            key: Option.some(`${slotName}.0`),
+            keyOccurrence: 0,
+          }),
+        },
+      },
+    ]),
+    Match.when({ _tag: 'Absent' }, () => []),
+    Match.exhaustive,
+  )
+
+export const driveStructure = (
+  comp: AnyComposition,
+  structure: Structure<UiContract>,
+  ref: NodeRef,
+  sink: Sink,
+  lookup: CaptureLookup,
+  bindings: ReadonlyMap<AnySlot, AnyComposition>,
+): ReadonlyArray<Mounted> => {
+  const key = Option.flatMap(ref.slot, (instance) => instance.key)
+  const capture: CapturedRender = {
+    name: uiNameOf(comp),
+    props: structure.props,
+    events: eventsOf(structure),
+    ...(Option.isSome(key) ? { key: key.value } : {}),
+  }
+  sink.api.record(capture)
+  lookup.record(ref, capture)
+  const fills = structureFills(structure)
+  return Rec.toEntries(slotsOf(comp)).flatMap(([slotName, slotClass]) => {
+    const child = bindings.get(slotClass)
+    const fill = fills[slotName]
+    return child === undefined || fill === undefined ? [] : enqueueFill(ref, slotName, fill, child)
+  })
+}
+
+export const fingerprint = (lookup: CaptureLookup): string =>
+  formatFingerprint(lookup.captures.map(({ ref, capture }) => [ref, capture.props]))