@playfast/reform 1.0.1 → 1.2.0

package/src/internal.ts

@@ -0,0 +1,222 @@
+// Quarantined surface for first-party hosts and companion packages
+// (`@playfast/reform-*`): reflection/manifest types, TypeIds, erased `Any*`
+// forms, capture callbacks, and runtime seams. Importable as
+// `@playfast/reform/internal`; not part of the app-facing API and not covered
+// by its stability expectations.
+
+export {
+  type AnyState,
+  type StateCapture,
+  type StateDefinition,
+  type StateManifest,
+  type StateName,
+  type StateSchemaReflection,
+  StateStoreTypeId,
+} from './state/state'
+export {
+  type AnyFamily,
+  type FamilyName,
+  type FamilySchemaReflection,
+  type FamilyStore,
+  type StateFamilyCapture,
+  type StateFamilyManifest,
+  StateFamilyStoreTypeId,
+} from './state/stateFamily'
+export { StateToken } from './state/token'
+export type {
+  AnySource,
+  Source,
+  SourceCapture,
+  SourceIdentifier,
+  SourceName,
+  SourceValue,
+} from './state/token'
+export type {
+  AnyEvent,
+  EventCapture,
+  EventManifest,
+  EventName,
+  EventReflection,
+  EventSchemaReflection,
+  EventType,
+} from './event/event'
+export { CalcStoreTypeId } from './calc/calc'
+export { CalcFamilyStoreTypeId } from './calc/calcFamily'
+export { AsyncCalcStoreTypeId } from './calc/asyncCalc'
+export { sameKey, type WiredSources, wireSources } from './internal/sources'
+// Optional host seams an `AsyncCalc` consults — persistence and lifecycle signals.
+// Concrete implementations live in edge packages (e.g. `@playfast/reform-query-browser`).
+export {
+  noopQueryStore,
+  QueryStore,
+  type QueryStoreApi,
+  resolveQueryStore,
+} from './internal/queryStore'
+export {
+  noopQueryEvents,
+  QueryEvents,
+  type QueryEventsApi,
+  resolveQueryEvents,
+} from './internal/queryEvents'
+export {
+  RemoteStatePendingStoreTypeId,
+  RemoteStateTruthStoreTypeId,
+  RemoteStateVisibleStoreTypeId,
+} from './remote/remoteState'
+export { SyncedStoreIdentifierTypeId } from './synced/syncedStore'
+export { BoundaryStoreTypeId } from './boundary/boundary'
+export type {
+  AnyProcedure,
+  ProcedureCapture,
+  ProcedureManifest,
+  ProcedureReflection,
+} from './procedure/procedure'
+export {
+  type ChannelRuntime,
+  Channels,
+  channelsLayer,
+  type ProcedureEntry,
+  Procedures,
+  proceduresLayer,
+} from './channel/channel'
+export { CompositionIdTypeId } from './compose/composition'
+export type {
+  AnyComposition,
+  CompositionCapture,
+  CompositionManifest,
+  CompositionPropsReceiver,
+  CompositionReflection,
+  CompositionTag,
+  HasExactCompositionId,
+  RequiredSlotIdentities,
+  SlotClassesOf,
+} from './compose/composition'
+export { StructureTypeId } from './compose/structure'
+export { type PropsId, PropsIdTypeId, type PropsTag, propsTag } from './compose/props'
+export {
+  type AnySlot,
+  type AnySlotChild,
+  type AnySlotInstance,
+  type SlotCapture,
+  type SlotChild,
+  type SlotManifest,
+  SlotServiceTypeId,
+  SlotTypeId,
+} from './compose/slot'
+export type { SlotRenderer } from './compose/host'
+export {
+  type AnyMadeView,
+  type AnyUi,
+  type MadeViewCapture,
+  type UiCapture,
+  type UiManifest,
+  type UiName,
+  type UiReflection,
+  type UiSchemaReflection,
+  UiServiceTypeId,
+  UiTypeId,
+  type WiredUi,
+  type WiredUiManifest,
+  type WireSchemas,
+} from './compose/ui'
+
+// Wire: the serializable rendered-tree model + pure diff/apply the remote
+// transport sends over the wire and the client folds back. See REMOTE_UI.md §3.
+export * as Wire from './wire/tree'
+export type { WireNode, WirePatch, WireProp, WireTree } from './wire/tree'
+// Triggers: the server-side handle registry bridging client trigger invocations
+// back to live triggers, decoding payloads via the event schema. See REMOTE_UI.md §4.
+export * as Triggers from './wire/triggers'
+export {
+  type TriggerHandle,
+  TriggerRegistry,
+  type TriggerRegistryApi,
+  UnknownTrigger,
+} from './wire/triggers'
+
+export {
+  type AnyFeatureBinding,
+  type AnyLoadedModule,
+  type CapturedFeatureBinding,
+  type FeatureBinding,
+  type FeatureBindingCapture,
+  FeatureBindingTypeId,
+  type FeatureDefinition,
+  FeatureGraphValidTypeId,
+  type FeatureIdentityToken,
+  FeatureInput,
+  type FeatureManifest,
+  featureModuleFromInput,
+  type FeatureMountProps,
+  type FeatureOpenServices,
+  type FeatureRequirement,
+  type FeatureSupportOpenServices,
+  type FeatureToken,
+  type FeatureTreeCarrier,
+  type LoadedModule,
+  type LoadedModuleCapture,
+  mountFeature,
+  type ProvideableFeature,
+  type ProvidedBy,
+  type RequireCarrier,
+} from './feature/feature'
+export {
+  type CompositionChildSummary,
+  CompositionChildSummaryTypeId,
+  type DescendantOpenServices,
+  type FeatureChildSummary,
+  FeatureChildSummaryTypeId,
+  type ModuleOpenServices,
+  type OpenServicesFromFeatureSlotWitnesses,
+  type SlotBindingSummary,
+  SlotBindingSummaryTypeId,
+  type ValidateFeatureGraphLayer,
+} from './graph/closure'
+export { type AnyScene, type AnySceneCapture, type SceneCapture, seedAnyScene } from './scene/scene'
+export { Bus, busLayer, type Envelope, type Tagged } from './runtime/bus'
+export {
+  type AnyFeatureMountHandlers,
+  type CapturedFeatureMountHandlers,
+  type FeatureMountHandlersExternalApi,
+  type UnspecifiedRuntimeServices,
+  UnspecifiedRuntimeServicesTypeId,
+} from './runtime/appRuntime'
+export {
+  EngineRequirements,
+  type EngineServices,
+  type ReducerEntry,
+  Reducers,
+  reducersLayer,
+} from './runtime/loop'
+export { CurrentEventBudget, defaultEventBudget, resolveEventBudget } from './runtime/eventBudget'
+// The profiler SPI: synchronous hooks the engine calls on its hot paths, plus
+// the FiberRef seam `@playfast/reform-profiler` writes through (`profiledScene`).
+export {
+  CurrentInstrumentation,
+  type Instrumentation,
+  noopInstrumentation,
+  resolveInstrumentation,
+  type SpanEnd,
+} from './runtime/instrumentation'
+// The runtime-wide registry of live query handles. `AsyncCalc.invalidate` /
+// `AsyncCalc.refetch` and provider layers act on a query by name through it.
+export { Queries, queriesLayer, type QueryHandle, type QueryRegistry } from './runtime/queries'
+export { CurrentTracker, readTracked, type Subscribable, type Tracker } from './internal/track'
+export { type CapturedRender, CaptureSink, type CaptureSinkApi } from './internal/capture'
+// Notification scheduler: hosts that need per-runtime isolation (concurrent SSR,
+// multiple mounted roots) provide `Notifications` upstream of their state layers;
+// everything else coalesces on the process-wide default.
+export {
+  defaultScheduler,
+  makeScheduler,
+  Notifications,
+  notificationsLayer,
+  resolveScheduler,
+  type Scheduler,
+} from './internal/scheduler'
+export { makeStore, type Store } from './internal/store'
+// Primitive-authoring toolkit — for first-party companion packages
+// (e.g. `@playfast/reform-db`, `@playfast/reform-resource`) that build their own
+// first-class `Source`s which must participate in dependency tracking and
+// reflection exactly like a `Calc`.
+export { type Kind, type Manifest, yieldableClass } from './definition/definition'

package/src/namespace/namespace.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest'
+import { Match, Schema as S } from 'effect'
+import * as Event from '../event/event'
+import * as Namespace from './namespace'
+
+describe('Namespace.make', () => {
+  const ns = Namespace.make('demoFeature')
+
+  it('prefixes every definition kind', () => {
+    class Saved extends ns.Event('Saved', S.Struct({})) {}
+    class Lane extends ns.Channel('Lane', { policy: { _tag: 'latest' } }) {}
+    class Count extends ns.State('count', S.Number) {}
+    class Doubled extends ns.Calc('Doubled', { inputs: [Count], output: S.Number }) {}
+    class Feed extends ns.AsyncCalc('Feed', { inputs: [Count], output: S.Number }) {}
+    class Rows extends ns.RemoteState('Rows', {
+      inputs: [Count],
+      output: S.Number,
+      intents: [],
+    }) {}
+
+    expect(Saved.tag).toBe('demoFeature.Saved')
+    expect(Lane.manifest.name).toBe('demoFeature.Lane')
+    expect(Count.manifest.name).toBe('demoFeature.count')
+    expect(Doubled.manifest.name).toBe('demoFeature.Doubled')
+    expect(Feed.manifest.name).toBe('demoFeature.Feed')
+    expect(Rows.manifest.name).toBe('demoFeature.Rows')
+  })
+
+  it('keeps the tag literal type for Match.tags folds', () => {
+    class Opened extends ns.Event('Opened', S.Struct({})) {}
+    class Closed extends ns.Event('Closed', S.Struct({ reason: S.String })) {}
+    type Folded = Event.EventType<typeof Opened> | Event.EventType<typeof Closed>
+
+    const fold = (event: Folded): string =>
+      Match.value(event).pipe(
+        Match.tags({
+          'demoFeature.Opened': () => 'open',
+          'demoFeature.Closed': ({ reason }) => reason,
+        }),
+        Match.exhaustive,
+      )
+
+    expect(fold(Event.construct(Opened, {}))).toBe('open')
+    expect(fold(Event.construct(Closed, { reason: 'done' }))).toBe('done')
+  })
+})

package/src/namespace/namespace.ts

@@ -0,0 +1,106 @@
+import type { Schema } from 'effect'
+import * as AsyncCalc from '../calc/asyncCalc'
+import * as Calc from '../calc/calc'
+import * as CalcFamily from '../calc/calcFamily'
+import * as Channel from '../channel/channel'
+import * as Event from '../event/event'
+import type { GatedOf } from '../internal/queryDriver'
+import * as RemoteState from '../remote/remoteState'
+import * as State from '../state/state'
+import * as StateFamily from '../state/stateFamily'
+import type { AnySource } from '../state/token'
+
+export interface FeatureNamespace<Prefix extends string> {
+  readonly prefix: Prefix
+  readonly Event: <const N extends string, P, Encoded>(
+    name: N,
+    schema: Schema.Schema<P, Encoded, never>,
+  ) => Event.EventClass<`${Prefix}.${N}`, P>
+  readonly Channel: (name: string, config: Channel.ChannelConfig) => Channel.ChannelClass
+  readonly State: <const N extends string, StateSchema extends Schema.Schema.AnyNoContext>(
+    name: N,
+    schema: StateSchema,
+    options?: State.StateOptions,
+  ) => State.StateDefinition<`${Prefix}.${N}`, Schema.Schema.Type<StateSchema>, StateSchema>
+  readonly StateFamily: <const N extends string, K, KeyEncoded, V, ValueEncoded>(
+    name: N,
+    key: Schema.Schema<K, KeyEncoded, never>,
+    valueSchema: Schema.Schema<V, ValueEncoded, never>,
+    options?: StateFamily.StateFamilyMakeOptionsExternalApi,
+  ) => StateFamily.StateFamilyClass<`${Prefix}.${N}`, K, V>
+  readonly Calc: <
+    const N extends string,
+    const Inputs extends ReadonlyArray<AnySource>,
+    OutputSchema extends Schema.Schema.AnyNoContext,
+  >(
+    name: N,
+    config: Calc.CalcConfig<Inputs, OutputSchema>,
+  ) => Calc.CalcClass<`${Prefix}.${N}`, Inputs, Schema.Schema.Type<OutputSchema>>
+  readonly CalcFamily: <
+    const N extends string,
+    const Inputs extends ReadonlyArray<AnySource>,
+    KeySchema extends Schema.Schema.AnyNoContext,
+    OutputSchema extends Schema.Schema.AnyNoContext,
+  >(
+    name: N,
+    config: CalcFamily.CalcFamilyConfig<Inputs, KeySchema, OutputSchema>,
+  ) => CalcFamily.CalcFamilyClass<
+    `${Prefix}.${N}`,
+    Inputs,
+    Schema.Schema.Type<KeySchema>,
+    Schema.Schema.Type<OutputSchema>
+  >
+  readonly AsyncCalc: <
+    const N extends string,
+    const Inputs extends ReadonlyArray<AnySource>,
+    OutputSchema extends Schema.Schema.AnyNoContext,
+    ErrorSchema extends Schema.Schema.AnyNoContext | undefined = undefined,
+    const AlwaysOn extends boolean = false,
+  >(
+    name: N,
+    config: AsyncCalc.AsyncCalcConfig<Inputs, OutputSchema, ErrorSchema, AlwaysOn>,
+  ) => AsyncCalc.AsyncCalcClass<
+    `${Prefix}.${N}`,
+    Inputs,
+    Schema.Schema.Type<OutputSchema>,
+    ErrorSchema extends Schema.Schema.AnyNoContext ? Schema.Schema.Type<ErrorSchema> : never,
+    GatedOf<AlwaysOn>
+  >
+  readonly RemoteState: <
+    const N extends string,
+    const Inputs extends ReadonlyArray<AnySource>,
+    const Intents extends ReadonlyArray<Event.AnyEvent>,
+    OutputSchema extends Schema.Schema.AnyNoContext,
+    ErrorSchema extends Schema.Schema.AnyNoContext | undefined = undefined,
+    const AlwaysOn extends boolean = false,
+  >(
+    name: N,
+    config: RemoteState.RemoteStateConfigExternalApi<
+      Inputs,
+      Intents,
+      OutputSchema,
+      ErrorSchema,
+      AlwaysOn
+    >,
+  ) => RemoteState.RemoteStateClass<
+    `${Prefix}.${N}`,
+    Inputs,
+    Intents,
+    Schema.Schema.Type<OutputSchema>,
+    ErrorSchema extends Schema.Schema.AnyNoContext ? Schema.Schema.Type<ErrorSchema> : never,
+    GatedOf<AlwaysOn>
+  >
+}
+
+export const make = <const Prefix extends string>(prefix: Prefix): FeatureNamespace<Prefix> => ({
+  prefix,
+  Event: (name, schema) => Event.make(`${prefix}.${name}`, schema),
+  Channel: (name, config) => Channel.make(`${prefix}.${name}`, config),
+  State: (name, schema, options) => State.make(`${prefix}.${name}`, schema, options),
+  StateFamily: (name, key, valueSchema, options) =>
+    StateFamily.make(`${prefix}.${name}`, key, valueSchema, options),
+  Calc: (name, config) => Calc.make(`${prefix}.${name}`, config),
+  CalcFamily: (name, config) => CalcFamily.make(`${prefix}.${name}`, config),
+  AsyncCalc: (name, config) => AsyncCalc.make(`${prefix}.${name}`, config),
+  RemoteState: (name, config) => RemoteState.make(`${prefix}.${name}`, config),
+})

package/src/procedure/procedure.ts

@@ -3,86 +3,91 @@ import type { YieldWrap } from 'effect/Utils'
 import { type ChannelClass, type ProcedureEntry, Procedures } from '../channel/channel'
 import { type Manifest, definitionClass } from '../definition/definition'
 import { type AnyEvent, type EventType } from '../event/event'
-import { type Ctx } from '../internal/ctx'
 import { Bus, narrowHandled } from '../runtime/bus'
+import type { AnyValue } from '../internal/variance'
 
-/** The reflectable descriptor a procedure carries. */
 export interface ProcedureManifest extends Manifest {
   readonly kind: 'Procedure'
 }
 
-export interface ProcedureClass<Events extends ReadonlyArray<AnyEvent>> {
+export interface ProcedureReflection<
+  out Events extends ReadonlyArray<AnyEvent> = ReadonlyArray<AnyEvent>,
+> {
   new (): {}
   readonly manifest: ProcedureManifest
-  /** The trigger events (marker data; read by `Procedure.live`). */
   readonly events: Events
-  /** The channel this procedure's runs are scheduled on (marker data). */
   readonly channel: ChannelClass
 }
 
+export type ProcedureCapture<Result> = <Events extends ReadonlyArray<AnyEvent>>(
+  procedure: ProcedureClass<Events>,
+) => Result
+
+export interface AnyProcedure extends ProcedureReflection {
+  readonly capture: <Result>(visit: ProcedureCapture<Result>) => Result
+}
+
+export interface ProcedureClass<
+  Events extends ReadonlyArray<AnyEvent>,
+> extends ProcedureReflection<Events> {
+  readonly capture: <Result>(visit: ProcedureCapture<Result>) => Result
+}
+
 export interface ProcedureConfig<Events extends ReadonlyArray<AnyEvent>> {
   readonly events: Events
-  /** The scheduling lane. Replaces the old `concurrency` option. */
   readonly channel: ChannelClass
 }
 
-export type AnyProcedure = ProcedureClass<ReadonlyArray<AnyEvent>>
-
-/**
- * A cross-event-loop flow. The *definition* declares its trigger events and the
- * channel it runs on; the *implementation* is the effectful body. Procedures no
- * longer subscribe to the bus themselves — the single drain loop routes events
- * to the channel, which runs the registered bodies under its policy.
- */
 export const make = <const Events extends ReadonlyArray<AnyEvent>>(
   name: string,
   config: ProcedureConfig<Events>,
-): ProcedureClass<Events> =>
-  definitionClass<ProcedureClass<Events>>({
+): ProcedureClass<Events> => {
+  const procedure: ProcedureClass<Events> = definitionClass<ProcedureClass<Events>>({
     manifest: { kind: 'Procedure' as const, name } satisfies ProcedureManifest,
     events: config.events,
     channel: config.channel,
+    capture: <Result>(visit: ProcedureCapture<Result>): Result => visit(procedure),
   })
+  return procedure
+}
+
+type GeneratorContext<Eff> = [Eff] extends [never]
+  ? never
+  : [Eff] extends [YieldWrap<Effect.Effect<AnyValue, AnyValue, infer Context>>]
+    ? Context
+    : never
 
-/**
- * Register the flow body into its channel. The body may read state and dispatch
- * events, but never writes state (the core invariant); its context requirements
- * (RPC clients, etc.) are captured here so the channel fiber can run it with no
- * outstanding R.
- */
 export const live = <
   Events extends ReadonlyArray<AnyEvent>,
-  Eff extends YieldWrap<Effect.Effect<any, any, any>>,
+  Eff extends YieldWrap<Effect.Effect<AnyValue, AnyValue, AnyValue>>,
   Done,
 >(
   procedure: ProcedureClass<Events>,
   body: (event: EventType<Events[number]>) => Generator<Eff, Done, never>,
-): Layer.Layer<never, never, Procedures | Bus | Ctx<Eff>> => {
+): Layer.Layer<never, never, Procedures | Bus | GeneratorContext<Eff>> => {
   const name = procedure.manifest.name
   const channelName = procedure.channel.manifest.name
   const handles = new Set(procedure.events.map((event) => event.tag))
-  // Scoped registration (see `Reducer.live`): an eager procedure's scope is the
-  // root runtime's, so behavior is unchanged; a lazy feature's procedure registers
-  // on mount and unregisters on unmount, so it stops running and is reclaimed.
   return Layer.scopedDiscard(
     Effect.gen(function* () {
       const procedures = yield* Procedures
       if (procedures.entries.some((entry) => entry.name === name)) {
         yield* Effect.logWarning(`reform: duplicate procedure name '${name}' registered`)
       }
-      // Snapshot the body's full context (Bus + RPC clients) so `run` is total.
-      const runtime = yield* Effect.runtime<Bus | Ctx<Eff>>()
+      const runtime = yield* Effect.runtime<Bus | GeneratorContext<Eff>>()
       const entry: ProcedureEntry = {
         name,
         channelName,
-        // The channel only routes events whose tag is in `handles`, so at runtime
-        // `event` is always one of `Events`; `narrowHandled` restores the body's
-        // declared event union from the erased `Tagged` envelope.
         handles,
-        run: (event) => Effect.provide(Effect.gen(() => body(narrowHandled(event))), runtime),
+        run: (event) =>
+          Effect.provide(
+            Effect.gen(() => body(narrowHandled(event))),
+            runtime,
+          ),
       }
-      yield* Effect.acquireRelease(Effect.sync(() => procedures.register(entry)), () =>
-        Effect.sync(() => procedures.unregister(entry)),
+      yield* Effect.acquireRelease(
+        Effect.sync(() => procedures.register(entry)),
+        () => Effect.sync(() => procedures.unregister(entry)),
       )
     }),
   )