@playfast/reform 1.1.1 → 1.2.0

package/src/graph/closure.ts

@@ -0,0 +1,403 @@
+import { Layer } from 'effect'
+import { CompositionIdTypeId } from '../compose/composition'
+import type { UiContract } from '../compose/ui'
+import { SlotServiceTypeId } from '../compose/slot'
+import type { FeatureInput, FeatureRequirement, ProvidedBy } from '../feature/feature'
+import type { EngineServices } from '../runtime/loop'
+import type { StateStore } from '../state/state'
+import type { StateFamilyStore } from '../state/stateFamily'
+
+export const FeatureGraphValidTypeId: unique symbol = Symbol.for('reform/FeatureGraphValid')
+export type FeatureGraphValidTypeId = typeof FeatureGraphValidTypeId
+
+export const FeatureModuleGraphValidTypeId: unique symbol = Symbol.for(
+  'reform/FeatureModuleGraphValid',
+)
+export type FeatureModuleGraphValidTypeId = typeof FeatureModuleGraphValidTypeId
+
+export const FeatureChildSummaryTypeId: unique symbol = Symbol.for('reform/FeatureChildSummary')
+export type FeatureChildSummaryTypeId = typeof FeatureChildSummaryTypeId
+
+export const FeatureGraphSummaryTypeId: unique symbol = Symbol.for('reform/FeatureGraphSummary')
+export type FeatureGraphSummaryTypeId = typeof FeatureGraphSummaryTypeId
+
+export const SlotBindingSummaryTypeId: unique symbol = Symbol.for('reform/SlotBindingSummary')
+export type SlotBindingSummaryTypeId = typeof SlotBindingSummaryTypeId
+
+export interface SlotBindingSummary {
+  readonly [SlotBindingSummaryTypeId]: SlotBindingSummaryTypeId
+}
+
+/**
+ * The constant-size proof published after a Feature's current module has passed
+ * graph validation. Type-only facts use empty-or-singleton tuples so the runtime
+ * summary stays compact while direct indexed access recovers their exact types.
+ */
+export interface FeatureGraphSummary<
+  out FeatureIdentity,
+  out MountProps,
+  out CompositionProps,
+  out C extends UiContract,
+  out S extends ReadonlyArray<unknown>,
+  out N extends string,
+  out CompositionIdentity,
+  out OpenServices,
+  out SupportOpenServices,
+  out UsesInput extends boolean,
+  out Input,
+> extends SlotBindingSummary {
+  readonly [FeatureGraphSummaryTypeId]: {
+    readonly featureIdentity: readonly [] | readonly [FeatureIdentity]
+    readonly mountProps: readonly [] | readonly [MountProps]
+    readonly compositionProps: readonly [] | readonly [CompositionProps]
+    readonly contract: readonly [] | readonly [C]
+    readonly states: readonly [] | readonly [S]
+    readonly name: N
+    readonly compositionIdentity: readonly [] | readonly [CompositionIdentity]
+    readonly openServices: readonly [] | readonly [OpenServices]
+    readonly supportOpenServices: readonly [] | readonly [SupportOpenServices]
+    readonly usesInput: readonly [] | readonly [UsesInput]
+    readonly input: readonly [] | readonly [Input]
+    readonly validated: FeatureModuleGraphValidTypeId
+  }
+  readonly [FeatureChildSummaryTypeId]: {
+    readonly featureIdentity: readonly [] | readonly [FeatureIdentity]
+    readonly compositionIdentity: readonly [] | readonly [CompositionIdentity]
+  }
+}
+
+export type FeatureChildSummary<
+  FeatureIdentity,
+  MountProps,
+  CompositionProps,
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  N extends string,
+  CompositionIdentity,
+  OpenServices,
+  SupportOpenServices,
+  UsesInput extends boolean,
+  Input,
+> = FeatureGraphSummary<
+  FeatureIdentity,
+  MountProps,
+  CompositionProps,
+  C,
+  S,
+  N,
+  CompositionIdentity,
+  OpenServices,
+  SupportOpenServices,
+  UsesInput,
+  Input
+>
+
+export type AnyFeatureGraphSummary = FeatureGraphSummary<
+  unknown,
+  unknown,
+  unknown,
+  UiContract,
+  ReadonlyArray<unknown>,
+  string,
+  unknown,
+  unknown,
+  unknown,
+  boolean,
+  unknown
+>
+
+export type FeatureSummaryIdentity<Summary extends AnyFeatureGraphSummary> =
+  Summary[FeatureGraphSummaryTypeId]['featureIdentity'][number]
+export type FeatureSummaryMountProps<Summary extends AnyFeatureGraphSummary> =
+  Summary[FeatureGraphSummaryTypeId]['mountProps'][number]
+export type FeatureSummaryCompositionProps<Summary extends AnyFeatureGraphSummary> =
+  Summary[FeatureGraphSummaryTypeId]['compositionProps'][number]
+export type FeatureSummaryContract<Summary extends AnyFeatureGraphSummary> =
+  Summary[FeatureGraphSummaryTypeId]['contract'][number]
+export type FeatureSummaryStates<Summary extends AnyFeatureGraphSummary> =
+  Summary[FeatureGraphSummaryTypeId]['states'][number]
+export type FeatureSummaryName<Summary extends AnyFeatureGraphSummary> =
+  Summary[FeatureGraphSummaryTypeId]['name']
+export type FeatureSummaryCompositionIdentity<Summary extends AnyFeatureGraphSummary> =
+  Summary[FeatureGraphSummaryTypeId]['compositionIdentity'][number]
+export type FeatureSummaryOpenServices<Summary extends AnyFeatureGraphSummary> =
+  Summary[FeatureGraphSummaryTypeId]['openServices'][number]
+export type FeatureSummarySupportOpenServices<Summary extends AnyFeatureGraphSummary> =
+  Summary[FeatureGraphSummaryTypeId]['supportOpenServices'][number]
+export type FeatureSummaryUsesInput<Summary extends AnyFeatureGraphSummary> =
+  Summary[FeatureGraphSummaryTypeId]['usesInput'][number]
+export type FeatureSummaryInput<Summary extends AnyFeatureGraphSummary> =
+  Summary[FeatureGraphSummaryTypeId]['input'][number]
+
+export const CompositionChildSummaryTypeId: unique symbol = Symbol.for(
+  'reform/CompositionChildSummary',
+)
+export type CompositionChildSummaryTypeId = typeof CompositionChildSummaryTypeId
+
+export interface CompositionChildSummary<out CompositionIdentity> extends SlotBindingSummary {
+  readonly [CompositionChildSummaryTypeId]: {
+    readonly compositionIdentity: CompositionIdentity
+  }
+}
+
+type IsAny<Value> = 0 extends 1 & Value ? true : false
+
+type IsErased<Value> = IsAny<Value> extends true ? true : unknown extends Value ? true : false
+
+type ExactStateStoreName<Service> =
+  IsAny<Service> extends true
+    ? never
+    : Service extends StateStore<infer Name, infer _Value>
+      ? string extends Name
+        ? never
+        : Name
+      : never
+
+type ExactStateFamilyStoreName<Service> =
+  IsAny<Service> extends true
+    ? never
+    : Service extends StateFamilyStore<infer Name, infer _Key, infer _Value>
+      ? string extends Name
+        ? never
+        : Name
+      : never
+
+type ServiceIsProvided<Required, Provided> =
+  IsErased<Provided> extends true
+    ? false
+    : Required extends StateStore<infer Name, infer _Value>
+      ? Name extends ExactStateStoreName<Provided>
+        ? true
+        : false
+      : Required extends StateFamilyStore<infer Name, infer _Key, infer _Value>
+        ? Name extends ExactStateFamilyStoreName<Provided>
+          ? true
+          : false
+        : [Required] extends [Provided]
+          ? true
+          : false
+
+/**
+ * Remove only services the provider can satisfy by their runtime Context tag.
+ * Named State/StateFamily identifiers intentionally do not collapse into their
+ * structurally broader Store/FamilyStore service APIs.
+ */
+export type ExactServiceExclude<Required, Provided> = Required extends unknown
+  ? ServiceIsProvided<Required, Provided> extends true
+    ? never
+    : Required
+  : never
+
+type ExactServiceExtract<Required, Provided> = Required extends unknown
+  ? ServiceIsProvided<Required, Provided> extends true
+    ? Required
+    : never
+  : never
+
+type GraphValidationPassed = object
+
+type ExactIdentity<Identity> = IsErased<Identity> extends true ? never : Identity
+
+type InputService<UsesInput extends boolean> = UsesInput extends true ? FeatureInput : never
+
+export type OpenServicesFromFeatureSlotWitnesses<Services> = Services extends {
+  readonly [SlotServiceTypeId]: {
+    readonly binding: FeatureChildSummary<
+      infer _FeatureIdentity,
+      infer _MountProps,
+      infer _CompositionProps,
+      infer _Contract,
+      infer _States,
+      infer _Name,
+      infer _CompositionIdentity,
+      infer OpenServices,
+      infer SupportOpenServices,
+      infer _UsesInput,
+      infer _Input
+    >
+  }
+}
+  ? OpenServices | SupportOpenServices
+  : never
+
+export type DescendantOpenServices<L extends Layer.Layer.Any> =
+  OpenServicesFromFeatureSlotWitnesses<Layer.Layer.Success<L>>
+
+export type ModuleOpenServices<L extends Layer.Layer.Any, UsesInput extends boolean> = Exclude<
+  Layer.Layer.Context<L>,
+  EngineServices | InputService<UsesInput>
+>
+
+type LayerErrorIsNever<L extends Layer.Layer.Any> =
+  IsErased<Layer.Layer.Error<L>> extends true
+    ? {
+        readonly featureLayerErrorMustBeNever: 'A feature layer error channel cannot be erased'
+      }
+    : [Layer.Layer.Error<L>] extends [never]
+      ? GraphValidationPassed
+      : {
+          readonly featureLayerErrorMustBeNever: 'A feature layer must have an error channel of exactly never'
+        }
+
+type LayerOutputsAreExact<L extends Layer.Layer.Any> =
+  IsErased<Layer.Layer.Success<L>> extends true
+    ? {
+        readonly featureLayerOutputsMustBeExact: 'A feature layer output cannot be erased'
+      }
+    : GraphValidationPassed
+
+type DescendantOpenServicesAreExact<L extends Layer.Layer.Any> =
+  IsErased<DescendantOpenServices<L>> extends true
+    ? {
+        readonly featureDescendantOpenServicesMustBeExact: "A child feature's open services cannot be erased"
+      }
+    : GraphValidationPassed
+
+type UnexpectedOpenServices<
+  L extends Layer.Layer.Any,
+  DirectRequires extends ReadonlyArray<FeatureRequirement>,
+  UsesInput extends boolean,
+> = ExactServiceExclude<
+  Layer.Layer.Context<L>,
+  EngineServices | InputService<UsesInput> | ProvidedBy<DirectRequires> | DescendantOpenServices<L>
+>
+
+type OpenServicesAreDeclared<
+  L extends Layer.Layer.Any,
+  DirectRequires extends ReadonlyArray<FeatureRequirement>,
+  UsesInput extends boolean,
+> =
+  IsErased<Layer.Layer.Context<L>> extends true
+    ? {
+        readonly featureLayerContextMustBeExact: 'A feature layer context cannot be erased'
+      }
+    : [UnexpectedOpenServices<L, DirectRequires, UsesInput>] extends [never]
+      ? GraphValidationPassed
+      : {
+          readonly undeclaredFeatureOpenServices: UnexpectedOpenServices<
+            L,
+            DirectRequires,
+            UsesInput
+          >
+        }
+
+type MissingDirectRequirements<
+  L extends Layer.Layer.Any,
+  DirectRequires extends ReadonlyArray<FeatureRequirement>,
+> = ExactServiceExclude<ProvidedBy<DirectRequires>, Layer.Layer.Context<L>>
+
+type DirectRequirementsAreOpen<
+  L extends Layer.Layer.Any,
+  DirectRequires extends ReadonlyArray<FeatureRequirement>,
+> = [MissingDirectRequirements<L, DirectRequires>] extends [never]
+  ? GraphValidationPassed
+  : {
+      readonly unusedDirectFeatureRequirements: MissingDirectRequirements<L, DirectRequires>
+    }
+
+type PrivateEngineOutputs<L extends Layer.Layer.Any> = Extract<
+  Layer.Layer.Success<L>,
+  EngineServices
+>
+
+type EngineOutputsAreShared<L extends Layer.Layer.Any> = [PrivateEngineOutputs<L>] extends [never]
+  ? GraphValidationPassed
+  : {
+      readonly featureCannotProvideEngineServices: PrivateEngineOutputs<L>
+    }
+
+type SelfRequiredOutputs<L extends Layer.Layer.Any> = ExactServiceExtract<
+  Layer.Layer.Context<L>,
+  Layer.Layer.Success<L>
+>
+
+type OutputsAreNotSelfRequired<L extends Layer.Layer.Any> = [SelfRequiredOutputs<L>] extends [never]
+  ? GraphValidationPassed
+  : {
+      readonly featureCannotRequireItsOwnOutputs: SelfRequiredOutputs<L>
+    }
+
+type SlotIdentity<Descriptor> =
+  // Erased descriptors must FAIL validation: `unknown` never matches a bound
+  // identity, so it surfaces in `unboundFeatureSlotIdentities`.
+  IsErased<Descriptor> extends true
+    ? unknown
+    : Descriptor extends ReadonlyArray<infer Entry>
+      ? SlotIdentity<Entry>
+      : Descriptor extends {
+            readonly [SlotServiceTypeId]: {
+              readonly identity: infer Identity
+            }
+          }
+        ? Identity
+        : Descriptor
+
+type RequiredSlotIdentities<Services> = Services extends {
+  readonly [CompositionIdTypeId]: {
+    readonly requiredSlots: infer RequiredSlots
+  }
+}
+  ? SlotIdentity<RequiredSlots>
+  : never
+
+type BoundSlotIdentities<Services> = Services extends {
+  readonly [SlotServiceTypeId]: {
+    readonly identity: infer Identity
+  }
+}
+  ? ExactIdentity<Identity>
+  : never
+
+type MissingSlotBindings<L extends Layer.Layer.Any> = Exclude<
+  RequiredSlotIdentities<Layer.Layer.Success<L>>,
+  BoundSlotIdentities<Layer.Layer.Success<L>>
+>
+
+type RequiredSlotsAreBound<L extends Layer.Layer.Any> = [MissingSlotBindings<L>] extends [never]
+  ? GraphValidationPassed
+  : {
+      readonly unboundFeatureSlotIdentities: MissingSlotBindings<L>
+    }
+
+type PlainChildCompositionIdentities<Services> = Services extends {
+  readonly [SlotServiceTypeId]: {
+    readonly binding: CompositionChildSummary<infer CompositionIdentity>
+  }
+}
+  ? CompositionIdentity
+  : never
+
+type LiveCompositionIdentities<Services> = Services extends {
+  readonly [CompositionIdTypeId]: {
+    readonly identity: infer Identity
+  }
+}
+  ? ExactIdentity<Identity>
+  : never
+
+type MissingPlainChildCompositions<L extends Layer.Layer.Any> = Exclude<
+  PlainChildCompositionIdentities<Layer.Layer.Success<L>>,
+  LiveCompositionIdentities<Layer.Layer.Success<L> | Layer.Layer.Context<L>>
+>
+
+type PlainChildrenAreLive<L extends Layer.Layer.Any> = [MissingPlainChildCompositions<L>] extends [
+  never,
+]
+  ? GraphValidationPassed
+  : {
+      readonly missingPlainChildCompositions: MissingPlainChildCompositions<L>
+    }
+
+export type ValidateFeatureGraphLayer<
+  L extends Layer.Layer.Any,
+  DirectRequires extends ReadonlyArray<FeatureRequirement>,
+  UsesInput extends boolean,
+> = LayerErrorIsNever<L> &
+  LayerOutputsAreExact<L> &
+  DescendantOpenServicesAreExact<L> &
+  OpenServicesAreDeclared<L, DirectRequires, UsesInput> &
+  DirectRequirementsAreOpen<L, DirectRequires> &
+  EngineOutputsAreShared<L> &
+  OutputsAreNotSelfRequired<L> &
+  RequiredSlotsAreBound<L> &
+  PlainChildrenAreLive<L>