@playfast/reform 0.1.0 → 1.1.1

package/src/feature/feature.ts

@@ -1,94 +1,84 @@
-import { type Context, Effect, Layer, Option, type Scope } from 'effect'
+import { Context, Effect, Layer, Option, type Scope } from 'effect'
 import { type Engine } from '../runtime/loop'
 import { type StoresOf } from '../internal/sources'
 import { FeatureLoadFailed } from '../internal/errors'
-import { type Manifest, definitionClass } from '../definition/definition'
+import { definitionClass } from '../definition/definition'
 import { type CompositionClass } from '../compose/composition'
 import { type UiContract } from '../compose/ui'
 import { publish, type Tagged } from '../runtime/bus'
+import type { AnyValue } from '../internal/variance'
+import {
+  type FeatureBinding,
+  FeatureBindingTypeId,
+  type FeatureManifest,
+} from './featureBinding'
+export {
+  type FailedProps,
+  type FeatureBinding,
+  FeatureBindingTypeId,
+  type FeatureManifest,
+  isFeatureBinding,
+  type LoadedModule,
+} from './featureBinding'
+export type { FeatureBindingTypeId as FeatureBindingType } from './featureBinding'
 
-// A `Feature` is the unit of lazy code-split, ownership, reflection, and proof.
-// It splits on the seam Reform already has: definitions (manifests, schemas, the
-// composition class, placeholders) stay eager and reflectable; the heavy `.live`
-// layer loads on demand. The whole-app *shape* stays inspectable with no chunk
-// loaded. Everything here is additive — `provide(slot, Composition)` and eager
-// scenes are unchanged. See `LAZY.md` for the design rationale and variance proof.
-
-/**
- * The always-on engine services a feature builds against: the shared event `Bus`
- * plus the reducer/channel/procedure registries. Derived from the `Engine`
- * layer's output (`runtime/loop.ts`) so it never drifts. A feature layer may name
- * these only as OPEN requirements (its `RIn`) and must never *provide* them — that
- * is what keeps the engine single and shared across every lazily-mounted feature.
- */
+// Features must only name EngineServices as open RIn — never provide them (shared engine)
 export type EngineServices = Layer.Layer.Success<typeof Engine>
 
-/**
- * A shared-state carrier a feature may declare in `requires`: a `State`,
- * `StateFamily`, `Calc`, or `AsyncCalc` (each carrying a `store` tag), or a
- * `StateGroup` (carrying `members`, each with its own `store`). Per the design,
- * a feature depends on shared state/calc only — never on another feature.
- */
+const FeatureInputBase: Context.TagClass<FeatureInput, 'reform/FeatureInput', unknown> = Context.Tag(
+  'reform/FeatureInput',
+)<FeatureInput, unknown>()
+export class FeatureInput extends FeatureInputBase {}
+
 export type RequireCarrier =
-  | { readonly store: Context.Tag<any, any> }
-  | { readonly members: ReadonlyArray<{ readonly store: Context.Tag<any, any> }> }
+  | { readonly store: Context.Tag<AnyValue, AnyValue> }
+  | { readonly members: ReadonlyArray<{ readonly store: Context.Tag<AnyValue, AnyValue> }> }
 
-/**
- * The Context services a `requires` tuple makes available to a feature layer: a
- * `StateGroup` contributes its members' stores (the shared `StoresOf`); every
- * other carrier contributes its own `store` service. This is the upper bound a
- * feature's open `RIn` is checked against. Because `Layer`'s `RIn` is covariant
- * (`Layer.d.ts` — `out RIn`), a layer that reads anything outside
- * `EngineServices | ProvidedBy<requires>` is simply not assignable, so the check
- * is ordinary assignability — no `as`, no `infer` gymnastics in user code.
- */
-export type ProvidedBy<Requires extends ReadonlyArray<RequireCarrier>> = {
-  [I in keyof Requires]: Requires[I] extends {
+export type FeatureRequirement = RequireCarrier | Context.Tag<AnyValue, AnyValue>
+
+// Covariant RIn: layer reading outside EngineServices | ProvidedBy is unassignable
+export type ProvidedBy<Requires extends ReadonlyArray<FeatureRequirement>> = {
+  [I in keyof Requires]: Requires[I] extends Context.Tag<infer Identifier, AnyValue>
+    ? Identifier
+    : Requires[I] extends {
     readonly members: infer M extends ReadonlyArray<unknown>
   }
     ? StoresOf<M>
-    : Requires[I] extends { readonly store: Context.Tag<infer Svc, any> }
+    : Requires[I] extends { readonly store: Context.Tag<infer Svc, AnyValue> }
       ? Svc
       : never
 }[number]
 
-/**
- * A loaded feature's two artifacts. `requires` is the runtime-enumerable list the
- * editor reads (types are erased, so the carriers are kept as values); `layer` is
- * the heavy `.live` half. The bound on `layer`'s `RIn` —
- * `EngineServices | ProvidedBy<Requires>` — makes the runtime list provably equal
- * the layer's real requirement set: list too little and the layer no longer type-
- * checks here. Built by `featureModule`, which is the one sanctioned way to publish
- * a feature's lazy half.
- */
-export interface FeatureModule<ROut, Requires extends ReadonlyArray<RequireCarrier>> {
+export interface FeatureModule<
+  ROut,
+  Requires extends ReadonlyArray<FeatureRequirement>,
+  UsesInput extends boolean = false,
+> {
   readonly requires: Requires
-  readonly layer: Layer.Layer<ROut, never, EngineServices | ProvidedBy<Requires>>
+  readonly usesInput: UsesInput
+  readonly layer: Layer.Layer<
+    ROut,
+    never,
+    | EngineServices
+    | ProvidedBy<Requires>
+    | (UsesInput extends true ? FeatureInput : never)
+  >
 }
 
-/**
- * Publish a feature's lazy half: pair its `requires` (a runtime tuple of shared
- * carriers) with its `layer`. The covariant `RIn` bound does the checking — a
- * layer that reaches for any service outside `EngineServices | ProvidedBy<requires>`
- * is not assignable, so it fails to compile right here, next to the layer, with no
- * cast. Listing an unused carrier is harmless; omitting a needed one is a type error.
- *
- * The bound also forbids a feature from *providing* `EngineServices` (they may only
- * be open `RIn`), structurally enforcing the liveness rule: a feature can never
- * bundle its own engine — it always shares the root's bus and registries.
- */
-export const featureModule = <const Requires extends ReadonlyArray<RequireCarrier>, ROut>(
+export const featureModule = <const Requires extends ReadonlyArray<FeatureRequirement>, ROut>(
   requires: Requires,
   layer: Layer.Layer<ROut, never, EngineServices | ProvidedBy<Requires>>,
-): FeatureModule<ROut, Requires> => ({ requires, layer })
+): FeatureModule<ROut, Requires, false> => ({ requires, usesInput: false, layer })
+
+export const featureModuleFromInput = <
+  const Requires extends ReadonlyArray<FeatureRequirement>,
+  ROut,
+>(
+  requires: Requires,
+  layer: Layer.Layer<ROut, never, EngineServices | ProvidedBy<Requires> | FeatureInput>,
+): FeatureModule<ROut, Requires, true> => ({ requires, usesInput: true, layer })
 
-/**
- * Wrap a dynamic `import()` of a feature's `.live` module as an `Effect` — Reform
- * never exposes a Promise/`await` on the feature surface. The unavoidable thenable
- * is sealed here; a rejected import (missing chunk, network failure, module-eval
- * throw) surfaces as a typed `FeatureLoadFailed` the host hands to
- * `placeholder.failed`. The module's default export is its `FeatureModule`.
- */
+// Seals Promise import as Effect; rejection → FeatureLoadFailed
 export const lazyImport = <M>(
   thunk: () => Promise<{ readonly default: M }>,
 ): Effect.Effect<M, FeatureLoadFailed> =>
@@ -97,105 +87,53 @@ export const lazyImport = <M>(
     catch: (cause) => new FeatureLoadFailed({ cause }),
   }).pipe(Effect.map((module) => module.default))
 
-/** The props the host injects into a lazy feature's `failed` placeholder. */
-export interface FailedProps {
-  readonly error: FeatureLoadFailed
-  readonly retry: () => void
-}
-
-/**
- * The reflectable shape of a feature: its strategy, the composition it mounts,
- * and (when lazy) its placeholder compositions — all as manifests, so the editor
- * route-map renders the whole feature graph with no chunk loaded. `boot` is
- * runtime data and lives on the `FeatureBinding`, not here.
- */
-export interface FeatureManifest extends Manifest {
-  readonly kind: 'Feature'
-  readonly name: string
-  readonly strategy: 'lazy' | 'default'
-  readonly composition: Manifest & { readonly kind: 'Composition' }
-  readonly placeholder: Option.Option<{
-    readonly loading: Manifest & { readonly kind: 'Composition' }
-    readonly failed: Manifest & { readonly kind: 'Composition' }
-  }>
-}
-
-/**
- * A feature's loaded artifacts with type params erased, for the renderer-neutral,
- * strategy-uniform host. The erasure is cast-free *into*: because `Layer`'s `ROut`
- * is contravariant and `RIn` covariant, every `Layer<ROut, never, R>` is assignable
- * to `Layer<never, never, unknown>`, so any `FeatureModule<…>` is a `LoadedModule`.
- * The host re-attaches the concrete root context when it builds `layer` (one
- * documented boundary cast there, mirroring `buildRuntime`).
- */
-export interface LoadedModule {
-  readonly requires: ReadonlyArray<RequireCarrier>
-  readonly layer: Layer.Layer<never, never, unknown>
-}
-
-/** Nominal brand identifying the value a `provide(slot, Feature)` puts under a slot tag. */
-export const FeatureBindingTypeId: unique symbol = Symbol.for('reform/FeatureBinding')
-export type FeatureBindingTypeId = typeof FeatureBindingTypeId
-
-/**
- * What `provide(slot, Feature)` binds under the slot tag — everything the host
- * needs to mount the feature, with types erased (the host is renderer-neutral and
- * strategy-uniform). For `default` the host renders `composition` directly; for
- * `lazy` it drives `load` through an `AsyncData` lifecycle, painting `placeholder`
- * around it. The `composition`/`placeholder` here are the same `CompositionClass`
- * values a normal slot fill carries, so the host's existing `Compose` path renders
- * each.
- */
-export interface FeatureBinding {
-  readonly [FeatureBindingTypeId]: FeatureBindingTypeId
-  readonly manifest: FeatureManifest
-  readonly composition: CompositionClass<unknown>
-  readonly strategy: 'lazy' | 'default'
-  readonly load: Effect.Effect<LoadedModule, FeatureLoadFailed>
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- read at the react host seam via `binding.placeholder === undefined`; an Option here would force a cross-package edit (react host) owned by another agent
-  readonly placeholder?: {
-    readonly loading: CompositionClass<unknown>
-    readonly failed: CompositionClass<unknown>
-  }
-  readonly boot: ReadonlyArray<Tagged>
-}
-
-/** Whether a slot's bound child is a lazy/eager feature (vs a plain composition). */
-export const isFeatureBinding = (candidate: unknown): candidate is FeatureBinding =>
-  typeof candidate === 'object' && candidate !== null && FeatureBindingTypeId in candidate
-
-/**
- * A feature *definition*: a reflectable manifest (`kind: 'Feature'`) that carries
- * the eager half (composition + placeholders) and an Effect `load` for the heavy
- * `.live` half. `Props`/`Contract` flow from the composition; `Requires` is the
- * shared-carrier tuple the loaded module declares. `load` is an `Effect`, never a
- * Promise — consumers `yield* Feature.load`.
- */
 export interface FeatureClass<
   P,
   C extends UiContract,
   ROut,
-  Requires extends ReadonlyArray<RequireCarrier>,
+  Requires extends ReadonlyArray<FeatureRequirement>,
+  SupportRequires extends ReadonlyArray<FeatureRequirement> = readonly [],
 > {
   new (): {}
   readonly manifest: FeatureManifest
-  /** Phantom carrying the mounted composition's props type (for `provide` checks). */
   readonly Props: P
-  /** Phantom carrying the composition's UI contract (for typed reflection consumers). */
   readonly Contract: C
-  /** Phantom carrying the declared shared-carrier tuple. */
+  readonly composition: CompositionClass<P, C>
   readonly Requires: Requires
-  /** Load the feature's module — `yield* Feature.load` → its `FeatureModule`, or `FeatureLoadFailed`. */
-  readonly load: Effect.Effect<FeatureModule<ROut, Requires>, FeatureLoadFailed>
-  /** The value `provide(slot, Feature)` binds under the slot tag. */
+  readonly load: Effect.Effect<FeatureModule<ROut, Requires, boolean>, FeatureLoadFailed>
   readonly binding: FeatureBinding
-  /** The eagerly-available module — present only for `loadingStrategy: 'default'`. */
-  readonly eagerModule: FeatureModule<ROut, Requires> | undefined
+  readonly eagerModule: FeatureModule<ROut, Requires, false> | undefined
+  readonly supportModule: FeatureModule<never, SupportRequires, false> | undefined
 }
 
-export type AnyFeature = FeatureClass<any, any, any, ReadonlyArray<RequireCarrier>>
+export interface EagerFeatureClass<
+  P,
+  C extends UiContract,
+  ROut,
+  Requires extends ReadonlyArray<FeatureRequirement>,
+> extends FeatureClass<P, C, ROut, Requires> {
+  readonly eagerModule: FeatureModule<ROut, Requires, false>
+  readonly supportModule: undefined
+}
+
+export interface LazyFeatureClass<
+  P,
+  C extends UiContract,
+  ROut,
+  Requires extends ReadonlyArray<FeatureRequirement>,
+  SupportRequires extends ReadonlyArray<FeatureRequirement> = readonly [],
+> extends FeatureClass<P, C, ROut, Requires, SupportRequires> {
+  readonly eagerModule: undefined
+}
+
+export type AnyFeature = FeatureClass<
+  AnyValue,
+  AnyValue,
+  AnyValue,
+  ReadonlyArray<FeatureRequirement>,
+  ReadonlyArray<FeatureRequirement>
+>
 
-/** Whether a value is a feature definition (its target shape in `provide(slot, Feature)`). */
 export const isFeature = (candidate: unknown): candidate is AnyFeature =>
   (typeof candidate === 'function' || typeof candidate === 'object') &&
   candidate !== null &&
@@ -205,56 +143,98 @@ export const isFeature = (candidate: unknown): candidate is AnyFeature =>
   'kind' in candidate.manifest &&
   candidate.manifest.kind === 'Feature'
 
-/**
- * The placeholders a lazy feature must ship — both eager compositions (their
- * `.live` is in the eager bundle, so they paint the load gap). `loading` receives
- * the feature's props; `failed` receives `{ error, retry }`. Typed loosely
- * (`CompositionClass<any>`) because the host injects these props directly — they
- * are not schema-decoded inputs.
- */
 export interface Placeholders {
-  readonly loading: CompositionClass<any, UiContract>
-  readonly failed: CompositionClass<any, UiContract>
+  readonly loading: CompositionClass<AnyValue, UiContract>
+  readonly failed: CompositionClass<AnyValue, UiContract>
+}
+
+interface FeatureConfigBaseExternalApi<P, C extends UiContract> {
+  readonly composition: CompositionClass<P, C>
+  readonly boot?: ReadonlyArray<Tagged>
 }
 
-type FeatureConfigExternalApi<
+type EagerFeatureConfigExternalApi<
   P,
   C extends UiContract,
   ROut,
-  Requires extends ReadonlyArray<RequireCarrier>,
-> = {
-  readonly composition: CompositionClass<P, C>
-  readonly boot?: ReadonlyArray<Tagged>
-} & (
-  | {
-      // EAGER: the module is statically present and merged into the runtime at
-      // boot. No load gap, so no placeholder.
-      readonly loadingStrategy?: 'default'
-      readonly module: FeatureModule<ROut, Requires>
-    }
-  | {
-      // LAZY: the module loads on mount via an Effect. Placeholders required.
-      readonly loadingStrategy: 'lazy'
-      readonly load: Effect.Effect<FeatureModule<ROut, Requires>, FeatureLoadFailed>
-      readonly placeholder: Placeholders
-    }
-)
+  Requires extends ReadonlyArray<FeatureRequirement>,
+> = FeatureConfigBaseExternalApi<P, C> & {
+  readonly loadingStrategy?: 'default'
+  readonly module: FeatureModule<ROut, Requires, false>
+}
 
-/**
- * Define a feature. The whole-app shape (this manifest, the composition, the
- * placeholders) stays eager and reflectable; the `.live` layer in `module`/`load`
- * is the deferred chunk. Flip `loadingStrategy` from `'default'` to `'lazy'` and
- * the discriminated config *requires* `placeholder` — the compiler walks you to a
- * complete code-split feature.
- */
-export const make = <P, C extends UiContract, ROut, Requires extends ReadonlyArray<RequireCarrier>>(
+type LazyFeatureConfigExternalApi<
+  P,
+  C extends UiContract,
+  ROut,
+  Requires extends ReadonlyArray<FeatureRequirement>,
+  SupportOut,
+  SupportRequires extends ReadonlyArray<FeatureRequirement>,
+> = FeatureConfigBaseExternalApi<P, C> & {
+  readonly loadingStrategy: 'lazy'
+  readonly load: Effect.Effect<FeatureModule<ROut, Requires, boolean>, FeatureLoadFailed>
+  readonly placeholder: Placeholders
+  readonly eager?: FeatureModule<SupportOut, SupportRequires, false>
+}
+
+export function make<
+  P,
+  C extends UiContract,
+  ROut,
+  Requires extends ReadonlyArray<FeatureRequirement>,
+>(
+  name: string,
+  config: EagerFeatureConfigExternalApi<P, C, ROut, Requires>,
+): EagerFeatureClass<P, C, ROut, Requires>
+export function make<
+  P,
+  C extends UiContract,
+  ROut,
+  Requires extends ReadonlyArray<FeatureRequirement>,
+  SupportOut,
+  SupportRequires extends ReadonlyArray<FeatureRequirement>,
+>(
+  name: string,
+  config: LazyFeatureConfigExternalApi<
+    P,
+    C,
+    ROut,
+    Requires,
+    SupportOut,
+    SupportRequires
+  > & { readonly eager: FeatureModule<SupportOut, SupportRequires, false> },
+): LazyFeatureClass<P, C, ROut, Requires, SupportRequires>
+export function make<
+  P,
+  C extends UiContract,
+  ROut,
+  Requires extends ReadonlyArray<FeatureRequirement>,
+>(
   name: string,
-  config: FeatureConfigExternalApi<P, C, ROut, Requires>,
-): FeatureClass<P, C, ROut, Requires> => {
+  config: LazyFeatureConfigExternalApi<P, C, ROut, Requires, never, readonly []>,
+): LazyFeatureClass<P, C, ROut, Requires>
+export function make(
+  name: string,
+  config:
+    | EagerFeatureConfigExternalApi<
+        AnyValue,
+        UiContract,
+        never,
+        ReadonlyArray<FeatureRequirement>
+      >
+    | LazyFeatureConfigExternalApi<
+        AnyValue,
+        UiContract,
+        never,
+        ReadonlyArray<FeatureRequirement>,
+        never,
+        ReadonlyArray<FeatureRequirement>
+      >,
+): AnyFeature {
   const strategy: 'lazy' | 'default' = config.loadingStrategy ?? 'default'
-  const load: Effect.Effect<FeatureModule<ROut, Requires>, FeatureLoadFailed> =
-    'load' in config ? config.load : Effect.succeed(config.module)
+  const load = 'load' in config ? config.load : Effect.succeed(config.module)
   const eagerModule = 'module' in config ? config.module : undefined
+  const supportModule = 'eager' in config ? config.eager : undefined
   const placeholder = 'placeholder' in config ? config.placeholder : undefined
 
   const manifest: FeatureManifest = {
@@ -275,43 +255,34 @@ export const make = <P, C extends UiContract, ROut, Requires extends ReadonlyArr
     manifest,
     composition: config.composition,
     strategy,
-    // The host is strategy-uniform: `default`'s `load` resolves immediately. The
-    // assignment to the erased `LoadedModule` needs no cast — see `LoadedModule`.
     load,
     ...(placeholder ? { placeholder: { loading: placeholder.loading, failed: placeholder.failed } } : {}),
     boot: Option.getOrElse(Option.fromNullable(config.boot), () => []),
   }
 
-  return definitionClass<FeatureClass<P, C, ROut, Requires>>({ manifest, load, binding, eagerModule })
+  return definitionClass<AnyFeature>({
+    manifest,
+    load,
+    binding,
+    eagerModule,
+    supportModule,
+    composition: config.composition,
+  })
 }
 
-/**
- * Mount a feature against a live engine. The renderer-neutral lifecycle, run on a
- * per-feature `Scope`: load the module (an Effect — lazy = dynamic import; default
- * = immediate), build its `.live` layer against the host's live `engineContext`
- * (so its reducers/procedures register into the SHARED registries and its fibers
- * fork onto this scope), then dispatch the feature's `boot`. Returns the merged
- * context — engine services + the feature's own services — for the host to read
- * the feature's composition and stores. Closing the scope disposes exactly this
- * feature: its fibers stop and its stores are reclaimed.
- *
- * The single boundary cast (mirroring `buildRuntime`): `module.layer` is erased to
- * `LoadedModule` so the host stays strategy- and type-uniform. The feature's real
- * `RIn` was verified cast-free at `provide(slot, Feature)` and scene wiring; here
- * we re-attach the concrete `engineContext` it builds against. `R` is the engine
- * context's service set, supplied by the host.
- */
 // oxlint-disable-next-line reform-rules/prefer-effect-fn -- generic export: Effect.fn's inferred type isn't portable under isolatedDeclarations
 export const mountFeature = <R>(
   binding: FeatureBinding,
   engineContext: Context.Context<R>,
+  props?: unknown,
 ): Effect.Effect<Context.Context<unknown>, FeatureLoadFailed, Scope.Scope> =>
   Effect.gen(function* () {
-    const { layer } = yield* binding.load
+    const module = yield* binding.load
     // oxlint-disable-next-line reform-rules/no-type-assertion -- documented erasure boundary: re-attach the concrete engine context to the type-erased `LoadedModule` layer (mirrors `buildRuntime`); RIn was verified cast-free at `provide`/scene wiring
-    const featureLayer = layer as Layer.Layer<unknown, never, R>
+    const featureLayer = module.layer as Layer.Layer<unknown, never, R | FeatureInput>
+    const featureContext = Context.add(engineContext, FeatureInput, props)
     const context = yield* Layer.build(
-      Layer.provideMerge(featureLayer, Layer.succeedContext(engineContext)),
+      Layer.provideMerge(featureLayer, Layer.succeedContext(featureContext)),
     )
     yield* Effect.forEach(binding.boot, (event) => publish('High', event), { discard: true }).pipe(
       Effect.provide(context),

package/src/feature/feature.typecheck.ts

@@ -1,8 +1,4 @@
-// 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 { Context, Layer, Schema as S } from 'effect'
 import type { Store } from '../internal/store'
 import * as Composition from '../compose/composition'
 import { provide } from '../compose/provide'
@@ -21,26 +17,34 @@ 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 {}
 
-// 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>
 
-// 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)
 
-// POSITIVE: a StateGroup contributes its members' stores via `ProvidedBy` — compiles.
 export const okGroup: FeatureModule<{ readonly _out: true }, readonly [typeof TodosStates]> =
   featureModule([TodosStates], readsFeed)
 
-// 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 []> =
   // @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>
+
+export const okService: FeatureModule<{ readonly _clock: true }, readonly [typeof Clock]> =
+  featureModule([Clock], readsClock)
+
+export const badService: FeatureModule<{ readonly _clock: true }, readonly []> =
+  // @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')<{
   props: { readonly a: string }
@@ -70,11 +74,21 @@ const AppFeatureBase: Feature.FeatureClass<
 })
 class AppFeature extends AppFeatureBase {}
 
-// 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)
 
-// A feature over a DIFFERENT contract must not fill `AppSlot`.
+class SupportedAppFeature extends Feature.make('supportedAppFeature', {
+  loadingStrategy: 'lazy',
+  composition: AppComp,
+  load: lazyImport(async () => ({ default: featureModule([], Layer.empty) })),
+  eager: okService,
+  placeholder: { loading: AppComp, failed: AppComp },
+}) {}
+
+export const wiredWithSupport: Layer.Layer<SlotChild, never, EngineServices | Clock> = provide(
+  AppSlot,
+  SupportedAppFeature,
+)
+
 const OtherUiBase: UiClass<{ props: { readonly n: number }; events: {} }> = ui('OtherUi')<{
   props: { readonly n: number }
   events: {}
@@ -100,7 +114,6 @@ const OtherFeatureBase: Feature.FeatureClass<
 })
 class OtherFeature extends OtherFeatureBase {}
 
-// 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,

package/src/feature/featureBinding.ts

@@ -0,0 +1,48 @@
+import { Effect, Layer, Option } from 'effect'
+import type { Manifest } from '../definition/definition'
+import type { CompositionClass } from '../compose/composition'
+import type { Tagged } from '../runtime/bus'
+import type { FeatureLoadFailed } from '../internal/errors'
+import type { FeatureRequirement } from './feature'
+
+export interface FailedProps {
+  readonly error: FeatureLoadFailed
+  readonly retry: () => void
+}
+
+export interface FeatureManifest extends Manifest {
+  readonly kind: 'Feature'
+  readonly name: string
+  readonly strategy: 'lazy' | 'default'
+  readonly composition: Manifest & { readonly kind: 'Composition' }
+  readonly placeholder: Option.Option<{
+    readonly loading: Manifest & { readonly kind: 'Composition' }
+    readonly failed: Manifest & { readonly kind: 'Composition' }
+  }>
+}
+
+export interface LoadedModule {
+  readonly requires: ReadonlyArray<FeatureRequirement>
+  readonly usesInput: boolean
+  readonly layer: Layer.Layer<never, never, unknown>
+}
+
+export const FeatureBindingTypeId: unique symbol = Symbol.for('reform/FeatureBinding')
+export type FeatureBindingTypeId = typeof FeatureBindingTypeId
+
+export interface FeatureBindingExternalApi {
+  readonly [FeatureBindingTypeId]: FeatureBindingTypeId
+  readonly manifest: FeatureManifest
+  readonly composition: CompositionClass<unknown>
+  readonly strategy: 'lazy' | 'default'
+  readonly load: Effect.Effect<LoadedModule, FeatureLoadFailed>
+  readonly placeholder?: {
+    readonly loading: CompositionClass<unknown>
+    readonly failed: CompositionClass<unknown>
+  }
+  readonly boot: ReadonlyArray<Tagged>
+}
+export type FeatureBinding = FeatureBindingExternalApi
+
+export const isFeatureBinding = (candidate: unknown): candidate is FeatureBinding =>
+  typeof candidate === 'object' && candidate !== null && FeatureBindingTypeId in candidate