@playfast/reform 0.0.9 → 0.0.11

package/src/calc/queryState.ts

@@ -0,0 +1,52 @@
+import { Option } from 'effect'
+import { type AnyAsyncData, AsyncData } from './asyncData'
+
+// `QueryState` is the data-oriented value an `AsyncCalc` is driven by: the four
+// axes of a query, stored *flat and independent* so each can move on its own.
+// `data`/`error` survive a refetch (stale-while-revalidate for free); `isFetching`
+// (activity) and `isStale` (freshness) are orthogonal to both — which is exactly
+// what lets `invalidate` (flip `isStale`) and `refetch` (drive `isFetching`) be
+// separate operations. The matchable `AsyncData` union is *derived* from this
+// (`toAsyncData`), so view code and `RemoteState` keep their arm dispatch.
+
+export interface QueryState<A, E> {
+  /** Last resolved value — kept across a refetch. */
+  readonly data: Option.Option<A>
+  /** Last failure — kept across a refetch. */
+  readonly error: Option.Option<E>
+  /** Activity axis: a run is in flight. */
+  readonly isFetching: boolean
+  /** Freshness axis: the value has been marked invalid (drives auto-refetch). */
+  readonly isStale: boolean
+}
+
+/** The empty cell. `fetching` seeds the first-kick `Loading` for an enabled query. */
+export const empty = (fetching: boolean): QueryState<never, never> => ({
+  data: Option.none(),
+  error: Option.none(),
+  isFetching: fetching,
+  isStale: false,
+})
+
+/**
+ * Project the flat state onto the public `AsyncData` union (the view contract) —
+ * the single `Match`-able view of a query, so call sites keep `Match.tag`-ing the
+ * arms. `error` wins over `data` so a failed refetch surfaces the `Error` arm,
+ * matching the pre-`QueryState` driver; `isFetching` becomes the arm's
+ * `refetching` flag. The data-less case is `Loading` while fetching (or for a
+ * non-gated query, which always fetches) and `Idle` only for a switched-off
+ * gateable query.
+ */
+export const toAsyncData = <A, E>(state: QueryState<A, E>, gated: boolean): AnyAsyncData<A, E> =>
+  Option.match(state.error, {
+    onSome: (error) => AsyncData.error(error, state.isFetching),
+    onNone: () =>
+      Option.match(state.data, {
+        onSome: (payload) => AsyncData.success(payload, state.isFetching),
+        onNone: () => (state.isFetching || !gated ? AsyncData.loading : AsyncData.idle),
+      }),
+  })
+
+/** `Loading` in the React-Query sense: fetching with nothing to show yet. */
+export const isLoading = <A, E>(state: QueryState<A, E>): boolean =>
+  state.isFetching && Option.isNone(state.data)

package/src/channel/channel.ts

@@ -1,6 +1,5 @@
-import { Chunk, Context, type Duration, Effect, Layer, Match, Queue, Stream } from 'effect'
+import { Chunk, Context, type Duration, Effect, Layer, Match, Option, Queue, Stream } from 'effect'
 import { type Manifest, definitionClass } from '../definition/definition'
-import { DuplicateRegistration } from '../internal/errors'
 import type { Tagged } from '../runtime/bus'
 
 /**
@@ -22,9 +21,9 @@ export type ChannelPolicy =
       readonly _tag: 'throttle'
       readonly units: number
       readonly duration: Duration.DurationInput
-      readonly cost?: number
-      readonly burst?: number
-      readonly strategy?: 'enforce' | 'shape'
+      readonly cost: Option.Option<number>
+      readonly burst: Option.Option<number>
+      readonly strategy: Option.Option<'enforce' | 'shape'>
     }
   | { readonly _tag: 'exclusive' }
 
@@ -91,56 +90,71 @@ export class Procedures extends ProceduresBase {}
 /** Get a map entry, creating and inserting it on first access (avoids `let`). */
 const getOrCreate = <K, V>(map: Map<K, V>, key: K, make: () => V): V => {
   const existing = map.get(key)
-  if (existing !== undefined) return existing
+  if (existing !== undefined) {
+    return existing
+  }
   const created = make()
   map.set(key, created)
   return created
 }
 
 /** Drop an item from a `Map<K, Array>` bucket, pruning the key when it empties. */
-const dropFrom = <K, T>(map: Map<K, Array<T>>, key: K, item: T): void => {
+const dropFrom = <K, T>(map: Map<K, Array<T>>, key: K, target: T): void => {
   const bucket = map.get(key)
-  if (bucket === undefined) return
-  const next = bucket.filter((value) => value !== item)
-  if (next.length === 0) map.delete(key)
-  else map.set(key, next)
+  if (bucket === undefined) {
+    return
+  }
+  const next = bucket.filter((candidate) => candidate !== target)
+  if (next.length === 0) {
+    map.delete(key)
+  } else {
+    map.set(key, next)
+  }
 }
 
 const makeProcedureRegistry = (): ProcedureRegistry => {
-  const entries: Array<ProcedureEntry> = []
+  // `entries` is reassigned immutably (new array per change) rather than mutated
+  // in place, so the holder keeps a stable reference the getter reads through.
+  const state: { entries: Array<ProcedureEntry> } = { entries: [] }
   const byTag = new Map<string, Array<ProcedureEntry>>()
   const channelsByTag = new Map<string, Array<string>>()
   const byChannelTag = new Map<string, Map<string, Array<ProcedureEntry>>>()
   return {
-    entries,
+    get entries() {
+      return state.entries
+    },
     byTag,
     channelsByTag,
     byChannelTag,
     register: (entry) => {
-      entries.push(entry)
-      for (const tag of entry.handles) {
-        getOrCreate(byTag, tag, () => []).push(entry)
+      state.entries = [...state.entries, entry]
+      entry.handles.forEach((tag) => {
+        byTag.set(tag, [...getOrCreate(byTag, tag, () => []), entry])
         const channels = getOrCreate(channelsByTag, tag, () => [])
-        if (!channels.includes(entry.channelName)) channels.push(entry.channelName)
-        getOrCreate(getOrCreate(byChannelTag, entry.channelName, () => new Map()), tag, () => []).push(
-          entry,
-        )
-      }
+        if (!channels.includes(entry.channelName)) {
+          channelsByTag.set(tag, [...channels, entry.channelName])
+        }
+        const channelMap = getOrCreate(byChannelTag, entry.channelName, () => new Map())
+        channelMap.set(tag, [...getOrCreate(channelMap, tag, () => []), entry])
+      })
     },
     unregister: (entry) => {
-      const index = entries.indexOf(entry)
-      if (index >= 0) entries.splice(index, 1)
-      for (const tag of entry.handles) {
+      state.entries = state.entries.filter((existing) => existing !== entry)
+      entry.handles.forEach((tag) => {
         dropFrom(byTag, tag, entry)
         const channelMap = byChannelTag.get(entry.channelName)
         if (channelMap !== undefined) {
           dropFrom(channelMap, tag, entry)
           // If no procedure on this channel still handles the tag, drop the
           // channel from `channelsByTag[tag]` so the loop stops offering to it.
-          if (channelMap.get(tag) === undefined) dropFrom(channelsByTag, tag, entry.channelName)
-          if (channelMap.size === 0) byChannelTag.delete(entry.channelName)
+          if (channelMap.get(tag) === undefined) {
+            dropFrom(channelsByTag, tag, entry.channelName)
+          }
+          if (channelMap.size === 0) {
+            byChannelTag.delete(entry.channelName)
+          }
         }
-      }
+      })
     },
   }
 }
@@ -194,7 +208,11 @@ export const live = (channel: ChannelClass): Layer.Layer<never, never, Channels
         // name is a silent footgun — the second policy would be dropped — so
         // reject it loudly instead.
         if (existing.policy !== channel.policy) {
-          throw new DuplicateRegistration({ kind: 'Channel', name })
+          // A different channel reusing a live name is a programmer footgun, not a
+          // recoverable failure — surface it as a defect to keep the layer E = never.
+          yield* Effect.dieMessage(
+            `reform: channel '${name}' is already live with a different policy`,
+          )
         }
         return
       }
@@ -206,11 +224,15 @@ export const live = (channel: ChannelClass): Layer.Layer<never, never, Channels
       // A procedure is expected to model expected failures as events; a leaked
       // defect (a bug in the body) is logged before being isolated, so one
       // procedure's crash never tears down the channel fiber — but is observable.
-      const runMatching = (event: Tagged): Effect.Effect<void> =>
-        Effect.forEach(
-          procedures.byChannelTag.get(name)?.get(event._tag) ?? [],
-          (e) =>
-            e.run(event).pipe(
+      const runMatching = (event: Tagged): Effect.Effect<void> => {
+        const matching = Option.fromNullable(procedures.byChannelTag.get(name)).pipe(
+          Option.flatMapNullable((byTag) => byTag.get(event._tag)),
+          Option.getOrElse((): ReadonlyArray<ProcedureEntry> => []),
+        )
+        return Effect.forEach(
+          matching,
+          (procedure) =>
+            procedure.run(event).pipe(
               Effect.tapErrorCause((cause) =>
                 Effect.logError(`reform: procedure on channel '${name}' failed`, cause),
               ),
@@ -218,6 +240,7 @@ export const live = (channel: ChannelClass): Layer.Layer<never, never, Channels
             ),
           { discard: true, concurrency: 'unbounded' },
         )
+      }
 
       // Map the policy to its scheduling stream. `Match.exhaustive` makes a new
       // policy variant a compile error, and each arm is a self-contained const.
@@ -225,7 +248,7 @@ export const live = (channel: ChannelClass): Layer.Layer<never, never, Channels
       const driven: Stream.Stream<unknown> = Match.value(channel.policy).pipe(
         Match.tag('merge', () => Stream.mapEffect(events, runMatching, { concurrency: 'unbounded' })),
         Match.tag('latest', () =>
-          Stream.flatMap(events, (e) => Stream.fromEffect(runMatching(e)), { switch: true }),
+          Stream.flatMap(events, (event) => Stream.fromEffect(runMatching(event)), { switch: true }),
         ),
         Match.tag('debounce', (policy) =>
           events.pipe(
@@ -236,11 +259,14 @@ export const live = (channel: ChannelClass): Layer.Layer<never, never, Channels
         Match.tag('throttle', (policy) =>
           events.pipe(
             Stream.throttle({
-              cost: (chunk) => Chunk.size(chunk) * (policy.cost ?? 1),
+              cost: (chunk) => Chunk.size(chunk) * Option.getOrElse(policy.cost, () => 1),
               units: policy.units,
               duration: policy.duration,
-              ...(policy.burst !== undefined ? { burst: policy.burst } : {}),
-              strategy: policy.strategy ?? 'shape',
+              ...Option.match(policy.burst, {
+                onNone: () => ({}),
+                onSome: (burst) => ({ burst }),
+              }),
+              strategy: Option.getOrElse(policy.strategy, () => 'shape' as const),
             }),
             Stream.mapEffect(runMatching, { concurrency: 'unbounded' }),
           ),

package/src/compose/composition.ts

@@ -30,15 +30,26 @@ export interface CompositionService {
   readonly render: (env: RenderEnv) => Effect.Effect<Frame, never, never>
 }
 
+// Reflectable manifest/config carrier: only `title` + `ui` are required, and the
+// optional members drive `Config extends { props: … }` / `{ states: … }` inference
+// (PropsOf/StatesOf) plus the ergonomic `Composition.make({ title, ui })` form, so
+// they cannot become `Option<T>` (would break inference and every call site) or be
+// renamed `ExternalApi` (would break external importers of `CompositionConfig`).
 export interface CompositionConfig {
   readonly title: string
+  // oxlint-disable-next-line reform-rules/no-optional-fields -- optional config field on a reflectable manifest carrier (see note above)
   readonly description?: string
   // `any` in the encoded/context slots is required by Schema's variance for
   // branded/Class schemas (e.g. `Todo`); only the decoded type `P` is used.
+  // oxlint-disable-next-line reform-rules/no-optional-fields -- drives `Config extends { props: … }` inference (PropsOf)
   readonly props?: Schema.Schema<any, any>
+  // oxlint-disable-next-line reform-rules/no-optional-fields -- drives `Config extends { states: … }` inference (StatesOf)
   readonly states?: ReadonlyArray<unknown>
+  // oxlint-disable-next-line reform-rules/no-optional-fields -- optional config field on a reflectable manifest carrier (see note above)
   readonly calcs?: ReadonlyArray<unknown>
+  // oxlint-disable-next-line reform-rules/no-optional-fields -- optional config field on a reflectable manifest carrier (see note above)
   readonly events?: ReadonlyArray<unknown>
+  // oxlint-disable-next-line reform-rules/no-optional-fields -- optional config field on a reflectable manifest carrier (see note above)
   readonly slots?: Record<string, SlotClass>
   // The UI contract this composition resolves. Typed as a manifest carrier (not
   // the full `UiClass`, whose invariant `impl` tag would force the contract type
@@ -87,12 +98,19 @@ export interface CompositionClass<
  * (`Composition.live`) is the synchronous body, provided separately and
  * checked against it.
  */
+/** The contract-carrying overlay on a composition config — keeps `C` inferable at
+ *  the `Composition.make` call site while the stored manifest sees only the erased
+ *  `{ manifest }` carrier. */
+interface UiCarrier<C extends UiContract> {
+  readonly ui: UiClass<C>
+}
+
 export const make = <const Config extends CompositionConfig, C extends UiContract>(
   name: string,
   // Constrain `ui` to the full `UiClass<C>` so `C` is inferred here; the stored
   // manifest still sees only the erased `{ manifest }` carrier (CompositionConfig),
   // so the manifest type — and its variance — is unchanged.
-  config: Config & { readonly ui: UiClass<C> },
+  config: Config & UiCarrier<C>,
 ): CompositionClass<PropsOf<Config>, C, StatesOf<Config>> => {
   const tag = Context.GenericTag<CompositionService, CompositionService>(
     `reform/composition/${name}`,
@@ -131,6 +149,7 @@ export const live = <
         // widens the error channel to the body's inferred `E` for a generic body, so
         // narrowing it (and the contract) back to the erased service type needs the
         // `unknown` bridge — the one cast this render boundary has always required.
+        // oxlint-disable-next-line reform-rules/no-type-assertion -- the one documented render-boundary erasure: a fully-provided generic body's Structure<C> narrowed back to the contract-agnostic Frame service type
         logic.pipe(
           Effect.provideService(Props, env.props),
           Effect.provideService(CurrentTracker, env.tracker),

package/src/compose/provide.ts

@@ -45,16 +45,20 @@ export function provide<
     Requires
   >,
 ): Layer.Layer<SlotChild, never, EngineServices | ProvidedBy<Requires>>
+// oxlint-disable-next-line reform-rules/no-multiple-primitive-params -- erased implementation signature of the 2-arg overloaded `provide`; the typed public API is the overloads above
 export function provide(target: unknown, impl: unknown): Layer.Layer<never, never, unknown> {
   // Discriminate the target by its nominal brand, not by which DI-hole property
   // happens to exist: a UI contract provides under its `impl` tag, a slot under
   // its `tag`. Anything else is a wiring mistake. The overloads above pair
   // `impl` with the chosen tag; this implementation sees both erased, so view
   // the tag loosely (the one documented cast) to provide the service under it.
+  // oxlint-disable-next-line reform-rules/no-type-assertion -- erased DI tag widening at the provide seam (Context.Tag is invariant); overloads pair impl with the right tag
   const tag = (isUi(target) ? target.impl : isSlot(target) ? target.tag : undefined) as
     | Context.Tag<unknown, unknown>
     | undefined
-  if (tag === undefined) throw new InvalidProvideTarget()
+  if (tag === undefined) {
+    return Layer.die(new InvalidProvideTarget())
+  }
   if (isFeature(impl)) {
     const eager = impl.eagerModule
     // Lazy: bind the `FeatureBinding`; the host drives load → mount, painting the

package/src/compose/slot.ts

@@ -50,8 +50,10 @@ export interface SlotClass<Comp extends AnyComposition = AnyComposition> {
 }
 
 /** Whether a value is a slot — discriminates a `provide` target by brand. */
-export const isSlot = (u: unknown): u is SlotClass =>
-  (typeof u === 'function' || typeof u === 'object') && u !== null && SlotTypeId in u
+export const isSlot = (candidate: unknown): candidate is SlotClass =>
+  (typeof candidate === 'function' || typeof candidate === 'object') &&
+  candidate !== null &&
+  SlotTypeId in candidate
 
 /** The props a slot renders with — the child composition's external props. */
 export type SlotProps<S> = S extends SlotInstance<infer Comp> ? Comp['Props'] : never

package/src/compose/structure.ts

@@ -1,3 +1,4 @@
+import { Struct } from 'effect'
 import type { SlotProps } from './slot'
 import type { EventsOf, UiContract } from './ui'
 
@@ -62,6 +63,7 @@ export type StructureSlots<C extends UiContract> = C extends {
 export interface Structure<C extends UiContract> {
   readonly props: C['props']
   readonly slots: StructureSlots<C>
+  // oxlint-disable-next-line reform-rules/no-optional-fields -- serializable frame shape; triggers ride optionally and the field is intentionally omitted from structureEquals
   readonly events?: EventsOf<C>
 }
 
@@ -80,6 +82,7 @@ export type StructureTypeId = typeof StructureTypeId
  * empty map when omitted, so a frame always carries an `events` record for hosts.
  */
 export const mount = <C extends UiContract>(structure: Structure<C>): Structure<C> =>
+  // oxlint-disable-next-line reform-rules/no-object-assign -- merge infers the empty `events` default as EventsOf<C>; a spread would force an `as` cast instead
   Object.assign({ [StructureTypeId]: StructureTypeId, events: {} }, structure)
 
 /**
@@ -87,12 +90,17 @@ export const mount = <C extends UiContract>(structure: Structure<C>): Structure<
  * the per-item state family — passing the same id source to both is no longer
  * possible to get wrong. `props` maps each item to the child's external props.
  */
-export const each = <T, P>(
-  collection: Iterable<T>,
-  options: { readonly key: (item: T) => string; readonly props: (item: T) => P },
-): EachFill<P> => ({
+export interface EachOptions<T, P> {
+  readonly key: (item: T) => string
+  readonly props: (item: T) => P
+}
+
+export const each = <T, P>(collection: Iterable<T>, options: EachOptions<T, P>): EachFill<P> => ({
   _tag: 'Each',
-  items: Array.from(collection, (item) => ({ key: options.key(item), props: options.props(item) })),
+  items: Array.from(collection, (element) => ({
+    key: options.key(element),
+    props: options.props(element),
+  })),
 })
 
 /** A singleton slot fill — render one child with these external props. */
@@ -112,23 +120,35 @@ export const isStructure = (frame: unknown): frame is Structure<UiContract> =>
 
 /** Whether a value is a plain record (not an array) — narrows for the deep compare
  *  below without a cast. */
-const isRecord = (u: unknown): u is Record<string, unknown> =>
-  typeof u === 'object' && u !== null && !Array.isArray(u)
+const isRecord = (candidate: unknown): candidate is Record<string, unknown> =>
+  typeof candidate === 'object' && candidate !== null && !Array.isArray(candidate)
+
+interface ValuePair {
+  readonly left: unknown
+  readonly right: unknown
+}
 
 /** Minimal structural deep-equality for serializable shapes (plain JSON — the
  *  UI-contract guarantee). Avoids a heavyweight dep for the settle comparison. */
-const deepEquals = (a: unknown, b: unknown): boolean => {
-  if (Object.is(a, b)) return true
-  if (Array.isArray(a) && Array.isArray(b)) {
-    return a.length === b.length && a.every((item, index) => deepEquals(item, b[index]))
+const deepEquals = ({ left, right }: ValuePair): boolean => {
+  if (Object.is(left, right)) {
+    return true
+  }
+  if (Array.isArray(left) && Array.isArray(right)) {
+    return (
+      left.length === right.length &&
+      left.every((element, index) => deepEquals({ left: element, right: right[index] }))
+    )
   }
-  if (isRecord(a) && isRecord(b)) {
-    const aKeys = Object.keys(a)
-    const bKeys = Object.keys(b)
+  if (isRecord(left) && isRecord(right)) {
+    const leftKeys = Struct.keys(left)
+    const rightKeys = Struct.keys(right)
     return (
-      aKeys.length === bKeys.length &&
-      aKeys.every(
-        (key) => Object.prototype.hasOwnProperty.call(b, key) && deepEquals(a[key], b[key]),
+      leftKeys.length === rightKeys.length &&
+      leftKeys.every(
+        (key) =>
+          Object.prototype.hasOwnProperty.call(right, key) &&
+          deepEquals({ left: left[key], right: right[key] }),
       )
     )
   }
@@ -141,5 +161,9 @@ const deepEquals = (a: unknown, b: unknown): boolean => {
  *  break the settle fixpoint. The `StructureTypeId` brand is a symbol key, so
  *  `Object.keys` skips it. Used by the proof/server settle loop to detect a
  *  two-frame fixpoint. */
-export const structureEquals = (a: Structure<UiContract>, b: Structure<UiContract>): boolean =>
-  deepEquals(a.props, b.props) && deepEquals(a.slots, b.slots)
+export const structureEquals = (
+  left: Structure<UiContract>,
+  right: Structure<UiContract>,
+): boolean =>
+  deepEquals({ left: left.props, right: right.props }) &&
+  deepEquals({ left: left.slots, right: right.slots })

package/src/compose/ui.ts

@@ -6,7 +6,13 @@ import { type Node, type SlotClass, type SlotInstance, type SlotProps } from './
 
 export interface UiContract {
   props: unknown
+  // `slots`/`events` are optional so a local contract literal (`ui('X')<{ props }>()`)
+  // stays terse AND so `C extends { slots: infer S }` / `{ events: infer E }`
+  // discriminates their presence (SlotsOf/EventsOf). Option<T> would break both the
+  // ergonomic authoring form and that conditional-type inference.
+  // oxlint-disable-next-line reform-rules/no-optional-fields -- presence drives `extends {...}` contract inference (see note above)
   slots?: Record<string, SlotInstance<any>>
+  // oxlint-disable-next-line reform-rules/no-optional-fields -- presence drives `extends {...}` contract inference (see note above)
   events?: Record<string, Trigger<any>>
 }
 
@@ -42,6 +48,7 @@ type SlotsOf<C extends UiContract> = C extends { slots: infer S }
       // (`slots.Item.props.length`, a header, layout decisions) and still render them
       // (`<slots.Item/>`); it never DERIVES multiplicity — the engine already fixed it. Read-only.
       readonly [K in keyof S]: FunctionComponent<
+        // oxlint-disable-next-line reform-rules/no-optional-fields -- React/JSX component-prop shape (`<slots.Row slotKey={id} />`); singleton slots omit it, framework-handled
         Partial<SlotProps<S[K]> & { readonly slotKey?: string }>
       > & { readonly props: ReadonlyArray<SlotProps<S[K]>> }
     }
@@ -67,7 +74,11 @@ export interface UiManifest extends Manifest {
   readonly kind: 'Ui'
   // `any` in the encoded/context slots is required by Schema's variance for
   // branded/Class schemas; only the decoded type is ever read off these.
+  // Present only on the wired form, so `extends { props: … }` discriminates the two
+  // authoring forms — Option<T> would erase that wire/type-only distinction.
+  // oxlint-disable-next-line reform-rules/no-optional-fields -- wire manifest field present only on the wired form (see note above)
   readonly props?: Schema.Schema<any, any>
+  // oxlint-disable-next-line reform-rules/no-optional-fields -- wire manifest field present only on the wired form (see note above)
   readonly events?: Readonly<Record<string, Schema.Schema<any, any>>>
 }
 
@@ -108,10 +119,14 @@ export type WiredUi<C extends UiContract> = UiClass<C> & { readonly manifest: Wi
  *  props the client reads AND that renders slot children). */
 export interface WireSchemas {
   readonly props: Schema.Schema<any, any>
+  // `events`/`slots` optional so `Sch extends { events: … }` / `{ slots: … }`
+  // derives the contract's facade only when declared (DerivedEvents/DerivedSlots).
+  // oxlint-disable-next-line reform-rules/no-optional-fields -- presence drives `extends {...}` derivation (DerivedEvents)
   readonly events?: Readonly<Record<string, Schema.Schema<any, any>>>
   // Slots are declared with their slot CLASSES (`slot('X')<typeof Child>()`), the
   // same values `Composition.make({ slots })` takes — NOT `SlotInstance`s. The
   // contract's slot facade is derived from them below.
+  // oxlint-disable-next-line reform-rules/no-optional-fields -- presence drives `extends {...}` derivation (DerivedSlots)
   readonly slots?: Readonly<Record<string, SlotClass>>
 }
 
@@ -140,8 +155,10 @@ export type DerivedContract<Sch extends WireSchemas> = {
 }
 
 /** Whether a value is a UI contract — discriminates a `provide` target by brand. */
-export const isUi = (u: unknown): u is UiClass<UiContract> =>
-  (typeof u === 'function' || typeof u === 'object') && u !== null && UiTypeId in u
+export const isUi = (candidate: unknown): candidate is UiClass<UiContract> =>
+  (typeof candidate === 'function' || typeof candidate === 'object') &&
+  candidate !== null &&
+  UiTypeId in candidate
 
 const buildUi = <C extends UiContract, M extends UiManifest>(
   name: string,
@@ -172,6 +189,7 @@ const buildUi = <C extends UiContract, M extends UiManifest>(
  */
 export function ui(name: string): <C extends UiContract>() => UiClass<C>
 export function ui<const Sch extends WireSchemas>(name: string, schemas: Sch): WiredUi<DerivedContract<Sch>>
+// oxlint-disable-next-line reform-rules/min-var-name -- `ui` is the public framework contract-authoring API; renaming would break every caller across the monorepo
 export function ui(name: string, schemas?: WireSchemas): unknown {
   if (schemas === undefined) {
     return <C extends UiContract>(): UiClass<C> => buildUi<C, UiManifest>(name, { kind: 'Ui', name })
@@ -201,4 +219,5 @@ export type MadeView<C extends UiContract> = ViewImpl<C> & { readonly [UiViewCon
  * remote client presentation. Wire the result with `provide(contract, view)`.
  */
 export const make = <C extends UiContract>(contract: UiClass<C>, view: ViewImpl<C>): MadeView<C> =>
+  // oxlint-disable-next-line reform-rules/no-object-assign -- `view` is a callable function; spread would drop callability, so the brand is attached in place
   Object.assign(view, { [UiViewContract]: contract })

package/src/compose/ui.typecheck.ts

@@ -48,9 +48,9 @@ acceptsWired(LocalUi)
 // none of it written a second time.
 export const derivedView: MadeView<Contract<typeof WiredUiClass>> = make(
   WiredUiClass,
-  ({ n }, _slots, { bump }) => {
-    const _n: number = n
-    bump({ by: _n })
-    return `${_n}`
+  ({ n: count }, _slots, { bump }) => {
+    const numeric: number = count
+    bump({ by: numeric })
+    return `${numeric}`
   },
 )

package/src/definition/definition.ts

@@ -2,7 +2,8 @@ import { Effect } from 'effect'
 import { attachInspectable } from '../internal/inspect'
 
 /** A definition's `toJSON`: its reflectable manifest, else its raw statics. */
-const describe = (statics: object): unknown => (statics as { manifest?: unknown }).manifest ?? statics
+const describe = (statics: object): unknown =>
+  ('manifest' in statics ? Reflect.get(statics, 'manifest') : undefined) ?? statics
 
 /**
  * The reflectable descriptor every primitive carries (principle #6). The editor
@@ -54,12 +55,13 @@ export const yieldableClass = <A, E, R, Statics extends object>(
   // class function (notably `name`, which a `Source`-shaped definition like a
   // Calc carries) and `assign` would throw on those; and `ownKeys` (unlike
   // `entries`) carries symbol-keyed statics — the `TypeId` brands.
-  for (const key of Reflect.ownKeys(statics)) {
-    const value = (statics as Record<PropertyKey, unknown>)[key]
-    Object.defineProperty(Base, key, { value, writable: true, enumerable: true, configurable: true })
-  }
+  Reflect.ownKeys(statics).forEach((key) => {
+    const staticValue = Reflect.get(statics, key)
+    Object.defineProperty(Base, key, { value: staticValue, writable: true, enumerable: true, configurable: true })
+  })
   // Print like an Effect value (the manifest), not `[object Object]`.
   attachInspectable(Base, () => describe(statics))
+  // oxlint-disable-next-line reform-rules/no-type-assertion -- phantom-shaped static side cannot structurally satisfy the yieldable Effect & Statics type
   return Base as never
 }
 
@@ -72,5 +74,16 @@ export const yieldableClass = <A, E, R, Statics extends object>(
  * interface. The one assertion to `Class` lives here, documented, instead of a
  * scattered `as never` / `as unknown as` at every `*.make`.
  */
-export const definitionClass = <Class>(statics: object): Class =>
-  attachInspectable(Object.assign(class {}, statics), () => describe(statics)) as unknown as Class
+export const definitionClass = <Class>(statics: object): Class => {
+  // `defineProperty` over `Reflect.ownKeys`, not `Object.assign`: a static can
+  // shadow a non-writable own property of the class function (notably `name`)
+  // and `assign` would throw, and `ownKeys` carries the symbol-keyed `TypeId`.
+  const Base = class {}
+  Reflect.ownKeys(statics).forEach((key) => {
+    const staticValue = Reflect.get(statics, key)
+    Object.defineProperty(Base, key, { value: staticValue, writable: true, enumerable: true, configurable: true })
+  })
+  attachInspectable(Base, () => describe(statics))
+  // oxlint-disable-next-line reform-rules/no-type-assertion -- the one documented seam: phantom type-only fields mean the assembled class cannot structurally satisfy Class
+  return Base as unknown as Class
+}

package/src/feature/feature.test.ts

@@ -1,4 +1,4 @@
-import { Effect, Layer } from 'effect'
+import { Effect, Layer, Option } from 'effect'
 import { expect, test } from 'vitest'
 import * as Composition from '../compose/composition'
 import { ui } from '../compose/ui'
@@ -30,14 +30,14 @@ test('a lazy feature reflects as a Feature manifest with placeholders, no chunk
   expect(LazyFeature.manifest.name).toBe('lazyFeature')
   expect(LazyFeature.manifest.strategy).toBe('lazy')
   expect(LazyFeature.manifest.composition.name).toBe('TestComp')
-  expect(LazyFeature.manifest.placeholder?.loading.name).toBe('TestComp')
-  expect(LazyFeature.manifest.placeholder?.failed.name).toBe('FailComp')
+  expect(Option.getOrThrow(LazyFeature.manifest.placeholder).loading.name).toBe('TestComp')
+  expect(Option.getOrThrow(LazyFeature.manifest.placeholder).failed.name).toBe('FailComp')
   expect(LazyFeature.eagerModule).toBeUndefined()
 })
 
 test('an eager feature reflects as default strategy with its module available', () => {
   expect(EagerFeature.manifest.strategy).toBe('default')
-  expect(EagerFeature.manifest.placeholder).toBeUndefined()
+  expect(Option.isNone(EagerFeature.manifest.placeholder)).toBe(true)
   expect(EagerFeature.eagerModule).toBe(mod)
 })