@playfast/reform 1.0.1 → 1.2.0

package/src/feature/feature.typecheck.ts

@@ -1,13 +1,17 @@
-// Type-level proofs enforced by `tsc --noEmit` over `src` (not a vitest file).
-// These guard the cast-free seam: if a guarantee regresses, a `@ts-expect-error`
-// goes unused or an assignment fails, and `tsc` breaks.
-
-import { Layer, Schema as S } from 'effect'
-import type { Store } from '../internal/store'
+import { Context, Layer, Schema as S } from 'effect'
 import * as Composition from '../compose/composition'
 import { provide } from '../compose/provide'
-import { type SlotChild, type SlotClass, slot } from '../compose/slot'
+import {
+  type ContractOfSlotTarget,
+  type FeatureSlotTarget,
+  type PropsOfSlotTarget,
+  type SlotChild,
+  type SlotService,
+  slot,
+} from '../compose/slot'
+import { mount } from '../compose/structure'
 import { type Contract, type UiClass, ui } from '../compose/ui'
+import { scene } from '../scene/scene'
 import * as State from '../state/state'
 import * as StateGroup from '../state/stateGroup'
 import { type EngineServices, type FeatureModule, featureModule, lazyImport } from './feature'
@@ -21,88 +25,289 @@ const TodosStatesBase: StateGroup.StateGroupClass<readonly [typeof FeedState, ty
   StateGroup.make(FeedState, FilterState)
 class TodosStates extends TodosStatesBase {}
 
-// --- featureModule: the covariant-RIn bound (cast-free requirement honesty) ---
+interface ClockService {
+  readonly now: () => number
+}
+const ClockBase: Context.TagClass<Clock, 'feature.typecheck.Clock', ClockService> = Context.Tag(
+  'feature.typecheck.Clock',
+)<Clock, ClockService>()
+class Clock extends ClockBase {}
+
+declare const readsFeed: Layer.Layer<
+  { readonly _out: true },
+  never,
+  State.StateStore<'feed', string> | EngineServices
+>
 
-// A feature layer that reads FeedState's store and the shared engine — nothing else.
-declare const readsFeed: Layer.Layer<{ readonly _out: true }, never, Store<string> | EngineServices>
+declare const readsTodos: Layer.Layer<
+  { readonly _out: true },
+  never,
+  State.StateStore<'feed', string> | State.StateStore<'filter', string> | EngineServices
+>
 
-// POSITIVE: declaring the State it reads in `requires` covers the read — compiles.
-export const okState: FeatureModule<{ readonly _out: true }, readonly [typeof FeedState]> =
-  featureModule([FeedState], readsFeed)
+const okState: FeatureModule<{ readonly _out: true }, readonly [typeof FeedState]> = featureModule(
+  [FeedState],
+  readsFeed,
+)
 
-// POSITIVE: a StateGroup contributes its members' stores via `ProvidedBy` — compiles.
-export const okGroup: FeatureModule<{ readonly _out: true }, readonly [typeof TodosStates]> =
-  featureModule([TodosStates], readsFeed)
+const okGroup: FeatureModule<{ readonly _out: true }, readonly [typeof TodosStates]> =
+  featureModule([TodosStates], readsTodos)
 
-// NEGATIVE: empty `requires` provides only the engine, not Store<string>; covariant
-// `RIn` makes the layer unassignable to the declared bound.
-export const badEmpty: FeatureModule<{ readonly _out: true }, readonly []> =
+const badEmpty =
   // @ts-expect-error feature layer reads a store it does not declare in `requires`
   featureModule([], readsFeed)
 
-// --- provide(slot, Feature): RIn surfacing + composition match ---
+declare const readsClock: Layer.Layer<{ readonly _clock: true }, never, Clock | EngineServices>
+
+const okService: FeatureModule<{ readonly _clock: true }, readonly [typeof Clock]> = featureModule(
+  [Clock],
+  readsClock,
+)
+
+const badService =
+  // @ts-expect-error feature layer reads an ordinary Context service it did not declare
+  featureModule([], readsClock)
 
-const AppUiBase: UiClass<{ props: { readonly a: string }; events: {} }> = ui('AppUi')<{
+const AppUiBase: UiClass<{ props: { readonly a: string }; events: {} }, 'AppUi'> = ui('AppUi')<{
   props: { readonly a: string }
   events: {}
 }>()
 class AppUi extends AppUiBase {}
-const AppCompBase: Composition.CompositionClass<{ readonly a: string }, Contract<typeof AppUi>> =
-  Composition.make('AppComp', {
-    title: 'App',
-    props: S.Struct({ a: S.String }),
-    ui: AppUi,
-  })
-class AppComp extends AppCompBase {}
-const AppSlotBase: SlotClass<typeof AppComp> = slot('App')<typeof AppComp>()
-class AppSlot extends AppSlotBase {}
-
-const AppFeatureBase: Feature.FeatureClass<
-  { readonly a: string },
-  Contract<typeof AppUi>,
-  never,
+class AppComp extends Composition.make('AppComp', {
+  title: 'App',
+  props: S.Struct({ a: S.String }),
+  ui: AppUi,
+})<AppComp>() {}
+const AppLive = Composition.live(AppComp, function* () {
+  const props = yield* AppComp.props
+  return mount({ props: { a: props.a }, slots: {} })
+})
+declare const FailedPlaceholder: Composition.AnyComposition &
+  Composition.CompositionPropsReceiver<Feature.FailedProps>
+
+class AppFeature extends Feature.make('appFeature', {
+  loadingStrategy: 'lazy',
+  composition: AppComp,
+  load: lazyImport(async () => ({ default: featureModule([], AppLive) })),
+  placeholder: { loading: AppComp, failed: FailedPlaceholder },
+}) {}
+type AppFeatureTarget = FeatureSlotTarget<typeof AppFeature>
+class AppFeatureSlot extends slot('AppFeature')<AppFeatureSlot, AppFeatureTarget>() {}
+
+class EmptyAppFeature extends Feature.make('emptyAppFeature', {
+  composition: AppComp,
+  // @ts-expect-error Layer.empty does not provide CompositionId<'AppComp'>
+  module: featureModule([], Layer.empty),
+}) {}
+
+declare const exactUnionModule: FeatureModule<
+  Composition.CompositionId<'AppComp', AppComp> | Clock,
+  readonly []
+>
+
+class ExactUnionAppFeature extends Feature.make('exactUnionAppFeature', {
+  composition: AppComp,
+  module: exactUnionModule,
+}) {}
+
+declare const unknownRootModule: FeatureModule<unknown, readonly []>
+class UnknownRootAppFeature extends Feature.make('unknownRootAppFeature', {
+  composition: AppComp,
+  // @ts-expect-error unknown output does not prove the exact root composition service
+  module: unknownRootModule,
+}) {}
+
+declare const broadRootModule: FeatureModule<
+  Composition.CompositionId<string, unknown>,
   readonly []
-> = Feature.make('appFeature', {
+>
+class BroadRootAppFeature extends Feature.make('broadRootAppFeature', {
+  composition: AppComp,
+  // @ts-expect-error a broad identifier does not prove the exact root identity
+  module: broadRootModule,
+}) {}
+
+declare const exactUnionLayer: Layer.Layer<
+  Composition.CompositionId<'AppComp', AppComp> | Clock,
+  never,
+  never
+>
+
+const exactUnionScene = scene(AppComp, { provide: [exactUnionLayer] })
+
+declare const unknownRootLayer: Layer.Layer<unknown, never, never>
+// @ts-expect-error unknown services do not prove the exact scene root
+const unknownRootScene = scene(AppComp, { provide: [unknownRootLayer] })
+
+declare const broadRootLayer: Layer.Layer<Composition.CompositionId<string, unknown>, never, never>
+// @ts-expect-error a broad composition identifier does not prove the exact scene root
+const broadRootScene = scene(AppComp, { provide: [broadRootLayer] })
+
+declare const privateEngine: Layer.Layer<EngineServices, never, EngineServices>
+// @ts-expect-error a Feature module cannot provide its own Engine services
+const invalidPrivateEngine = featureModule([], privateEngine)
+
+const wired = provide(AppFeatureSlot, AppFeature)
+
+type Equal<Left, Right> =
+  (<Value>() => Value extends Left ? 1 : 2) extends <Value>() => Value extends Right ? 1 : 2
+    ? true
+    : false
+type Assert<Condition extends true> = Condition
+type WiredRequirementsAreExact = Assert<Equal<Layer.Layer.Context<typeof wired>, EngineServices>>
+type WiredOutputIsOnlySummary = Assert<
+  Equal<
+    Layer.Layer.Success<typeof wired>,
+    SlotService<'AppFeature', AppFeatureSlot, typeof AppFeature.summary>
+  >
+>
+type FeatureTargetSummaryIsExact = Assert<
+  Equal<AppFeatureTarget['summary'], typeof AppFeature.summary>
+>
+type FeatureTargetPropsAreExact = Assert<
+  Equal<PropsOfSlotTarget<AppFeatureTarget>, { readonly a: string }>
+>
+type FeatureTargetContractIsExact = Assert<
+  Equal<ContractOfSlotTarget<AppFeatureTarget>, Contract<typeof AppUi>>
+>
+type FeatureTargetCannotOpenTree = Assert<
+  Equal<AppFeatureTarget extends Feature.FeatureTreeCarrier ? true : false, false>
+>
+const appNative = Feature.tree<typeof AppFeature>(AppFeature.token)
+type AppNative = typeof appNative
+type ExactTreeComposition = Assert<Equal<AppNative['composition'], typeof AppComp>>
+type NoDirectNativeFields = Assert<
+  Equal<
+    Extract<
+      'composition' | 'binding' | 'load' | 'eagerModule' | 'supportModule' | 'tree',
+      keyof typeof AppFeature
+    >,
+    never
+  >
+>
+
+class AppFeatureTwin extends Feature.make('appFeature', {
   loadingStrategy: 'lazy',
   composition: AppComp,
-  load: lazyImport(async () => ({ default: featureModule([], Layer.empty) })),
-  placeholder: { loading: AppComp, failed: AppComp },
-})
-class AppFeature extends AppFeatureBase {}
+  load: lazyImport(async () => ({ default: featureModule([], AppLive) })),
+  placeholder: { loading: AppComp, failed: FailedPlaceholder },
+}) {}
+type SameCompositionTokenIsInterchangeable = Assert<
+  Equal<typeof AppFeatureTwin.token extends typeof AppFeature.token ? true : false, true>
+>
+type BroadFeatureIdentityIsRejected = Assert<
+  Equal<
+    Feature.FeatureIdentityToken<unknown> extends Feature.FeatureIdentityToken<AppComp>
+      ? true
+      : false,
+    false
+  >
+>
+
+class AppCompositionSlot extends slot('AppComposition')<AppCompositionSlot, typeof AppComp>() {}
+
+// @ts-expect-error composition slots accept the Composition value, not a Feature
+provide(AppCompositionSlot, AppFeature)
+
+class SupportedAppFeature extends Feature.make('supportedAppFeature', {
+  loadingStrategy: 'lazy',
+  composition: AppComp,
+  load: lazyImport(async () => ({ default: featureModule([], AppLive) })),
+  eager: okService,
+  placeholder: { loading: AppComp, failed: FailedPlaceholder },
+}) {}
+type SupportedAppFeatureTarget = FeatureSlotTarget<typeof SupportedAppFeature>
+class SupportedAppFeatureSlot extends slot('SupportedAppFeature')<
+  SupportedAppFeatureSlot,
+  SupportedAppFeatureTarget
+>() {}
 
-// POSITIVE: the wired layer's open `RIn` is exactly `EngineServices` (requires=[]),
-// so a scene must provide `Core` — surfaced cast-free by the overload.
-export const wired: Layer.Layer<SlotChild, never, EngineServices> = provide(AppSlot, AppFeature)
+const wiredWithSupport = provide(SupportedAppFeatureSlot, SupportedAppFeature)
+type SupportedRequirementsAreExact = Assert<
+  Equal<Layer.Layer.Context<typeof wiredWithSupport>, EngineServices | Clock>
+>
+type SupportedOutputIsOnlySummary = Assert<
+  Equal<
+    Layer.Layer.Success<typeof wiredWithSupport>,
+    SlotService<'SupportedAppFeature', SupportedAppFeatureSlot, typeof SupportedAppFeature.summary>
+  >
+>
 
-// A feature over a DIFFERENT contract must not fill `AppSlot`.
-const OtherUiBase: UiClass<{ props: { readonly n: number }; events: {} }> = ui('OtherUi')<{
+const OtherUiBase: UiClass<{ props: { readonly n: number }; events: {} }, 'OtherUi'> = ui(
+  'OtherUi',
+)<{
   props: { readonly n: number }
   events: {}
 }>()
 class OtherUi extends OtherUiBase {}
-const OtherCompBase: Composition.CompositionClass<{ readonly n: number }, Contract<typeof OtherUi>> =
-  Composition.make('OtherComp', {
-    title: 'Other',
-    props: S.Struct({ n: S.Number }),
-    ui: OtherUi,
-  })
-class OtherComp extends OtherCompBase {}
-const OtherFeatureBase: Feature.FeatureClass<
-  { readonly n: number },
-  Contract<typeof OtherUi>,
-  never,
-  readonly []
-> = Feature.make('otherFeature', {
+class OtherComp extends Composition.make('OtherComp', {
+  title: 'Other',
+  props: S.Struct({ n: S.Number }),
+  ui: OtherUi,
+})<OtherComp>() {}
+const OtherLive = Composition.live(OtherComp, function* () {
+  const props = yield* OtherComp.props
+  return mount({ props, slots: {} })
+})
+class OtherFeature extends Feature.make('otherFeature', {
   loadingStrategy: 'lazy',
   composition: OtherComp,
-  load: lazyImport(async () => ({ default: featureModule([], Layer.empty) })),
-  placeholder: { loading: OtherComp, failed: OtherComp },
-})
-class OtherFeature extends OtherFeatureBase {}
+  load: lazyImport(async () => ({ default: featureModule([], OtherLive) })),
+  placeholder: { loading: OtherComp, failed: FailedPlaceholder },
+}) {}
 
-// NEGATIVE: OtherFeature's composition props don't match AppSlot's child composition.
-// @ts-expect-error feature composition does not match the slot's child type
-export const mismatched: Layer.Layer<SlotChild, never, EngineServices> = provide(
-  AppSlot,
-  OtherFeature,
-)
+type OtherFeatureIsRejectedByAppTarget = Assert<
+  Equal<typeof OtherFeature extends AppFeatureTarget ? true : false, false>
+>
+type DifferentCompositionTokenIsRejected = Assert<
+  Equal<typeof OtherFeature.token extends typeof AppFeature.token ? true : false, false>
+>
+const otherNative = Feature.tree<typeof OtherFeature>(OtherFeature.token)
+type OtherNative = typeof otherNative
+type DifferentCompositionBindingIsRejected = Assert<
+  Equal<OtherNative['binding'] extends SlotChild<AppFeatureTarget> ? true : false, false>
+>
+
+// @ts-expect-error OtherFeature.token does not belong to AppFeature
+Feature.tree<typeof AppFeature>(OtherFeature.token)
+
+// @ts-expect-error AppFeatureSlot accepts only features over AppComp
+provide(AppFeatureSlot, OtherFeature)
+
+type FeatureTypeProofs = [
+  WiredRequirementsAreExact,
+  WiredOutputIsOnlySummary,
+  FeatureTargetSummaryIsExact,
+  FeatureTargetPropsAreExact,
+  FeatureTargetContractIsExact,
+  FeatureTargetCannotOpenTree,
+  ExactTreeComposition,
+  NoDirectNativeFields,
+  SameCompositionTokenIsInterchangeable,
+  BroadFeatureIdentityIsRejected,
+  DifferentCompositionTokenIsRejected,
+  DifferentCompositionBindingIsRejected,
+  SupportedRequirementsAreExact,
+  SupportedOutputIsOnlySummary,
+  OtherFeatureIsRejectedByAppTarget,
+]
+declare const featureTypeProofs: FeatureTypeProofs
+
+void featureTypeProofs
+void appNative
+void otherNative
+void AppFeatureTwin
+void okState
+void okGroup
+void badEmpty
+void badService
+void EmptyAppFeature
+void ExactUnionAppFeature
+void UnknownRootAppFeature
+void BroadRootAppFeature
+void exactUnionScene
+void unknownRootScene
+void broadRootScene
+void invalidPrivateEngine
+
+export {}