@playfast/reform 0.0.7 → 0.0.9

package/src/feature/feature.typecheck.ts

@@ -0,0 +1,108 @@
+// 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 * as Composition from '../compose/composition'
+import { provide } from '../compose/provide'
+import { type SlotChild, type SlotClass, slot } from '../compose/slot'
+import { type Contract, type UiClass, ui } from '../compose/ui'
+import * as State from '../state/state'
+import * as StateGroup from '../state/stateGroup'
+import { type EngineServices, type FeatureModule, featureModule, lazyImport } from './feature'
+import * as Feature from './feature'
+
+const FeedStateBase: State.StateClass<'feed', string> = State.make('feed', S.String)
+class FeedState extends FeedStateBase {}
+const FilterStateBase: State.StateClass<'filter', string> = State.make('filter', S.String)
+class FilterState extends FilterStateBase {}
+const TodosStatesBase: StateGroup.StateGroupClass<readonly [typeof FeedState, typeof FilterState]> =
+  StateGroup.make(FeedState, FilterState)
+class TodosStates extends TodosStatesBase {}
+
+// --- featureModule: the covariant-RIn bound (cast-free requirement honesty) ---
+
+// 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 ---
+
+const AppUiBase: UiClass<{ props: { readonly a: string }; events: {} }> = 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,
+  readonly []
+> = Feature.make('appFeature', {
+  loadingStrategy: 'lazy',
+  composition: AppComp,
+  load: lazyImport(() => Promise.resolve({ default: featureModule([], Layer.empty) })),
+  placeholder: { loading: AppComp, failed: AppComp },
+})
+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`.
+const OtherUiBase: UiClass<{ props: { readonly n: number }; events: {} }> = 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', {
+  loadingStrategy: 'lazy',
+  composition: OtherComp,
+  load: lazyImport(() => Promise.resolve({ default: featureModule([], Layer.empty) })),
+  placeholder: { loading: OtherComp, failed: OtherComp },
+})
+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,
+  OtherFeature,
+)

package/src/index.ts

@@ -0,0 +1,191 @@
+// Reform core — the renderer-neutral primitives and runtime.
+// Definitions (`X.make`) are separate from implementations (`.live`)
+// throughout, and nothing self-registers on import (principle #1, #6).
+
+export * as State from './state/state'
+export * as StateGroup from './state/stateGroup'
+export * as StateFamily from './state/stateFamily'
+export { StateToken } from './state/token'
+export type { AnySource, Source } from './state/token'
+
+export * as Event from './event/event'
+// Direct type re-export alongside the namespace (TS2742 nameability): inferred
+// types of layers built over intent/event unions reference `EventOf`, and the
+// declaration emitter can only name it through a plain export.
+export type { EventOf } from './event/event'
+export * as EventGroup from './event/eventGroup'
+
+export * as Reducer from './reducer/reducer'
+export * as Calc from './calc/calc'
+export * as CalcFamily from './calc/calcFamily'
+export * as AsyncCalc from './calc/asyncCalc'
+export { composeCalcs } from './calc/compose'
+// The inputs-object/key/store types appearing in `AsyncCalc.live` /
+// `RemoteState.live` signatures, exported so app code can annotate
+// query-swapping helpers and layer types without re-spelling them.
+export type { InputsObject, InputStores, InvalidateBy } from './internal/sources'
+export {
+  AsyncData,
+  type AsyncError,
+  type AsyncIdle,
+  type AsyncLoading,
+  type AsyncSuccess,
+} from './calc/asyncData'
+export * as RemoteState from './remote/remoteState'
+// Direct type re-exports alongside the namespace (TS2742 nameability): an app
+// layer's inferred type references these (`Store<ReadonlyArray<PendingIntent<…>>>`),
+// and the declaration emitter can only name them through a plain export.
+export type { FailedIntent, PendingIntent, RemoteStateClass } from './remote/remoteState'
+export * as SyncedStore from './synced/syncedStore'
+// Direct type re-export alongside the namespace (TS2742 nameability): adapters
+// (e.g. `@playfast/reform-db`) annotate the source handed to `SyncedStore.live`.
+export type { SyncedSource, SyncedStoreClass } from './synced/syncedStore'
+export * as Boundary from './boundary/boundary'
+// Direct type re-exports alongside the namespace (same TS2742 nameability
+// reason as the RemoteState types above): app code annotates props with these.
+export type {
+  BoundaryErrored,
+  BoundaryPending,
+  BoundaryReady,
+  BoundaryState,
+} from './boundary/boundary'
+export * as Procedure from './procedure/procedure'
+export * as Channel from './channel/channel'
+
+export * as Composition from './compose/composition'
+export type {
+  CompositionClass,
+  CompositionService,
+  Frame,
+  RenderEnv,
+} from './compose/composition'
+export {
+  absent,
+  each,
+  type EachFill,
+  isStructure,
+  mount,
+  one,
+  type OneFill,
+  type AbsentFill,
+  type SlotFill,
+  type Structure,
+  structureEquals,
+  type StructureSlots,
+  StructureTypeId,
+  when,
+} from './compose/structure'
+export { Props } from './compose/props'
+export {
+  isSlot,
+  type Node,
+  slot,
+  type SlotClass,
+  type SlotInstance,
+  type SlotProps,
+  SlotTypeId,
+} from './compose/slot'
+export { type SlotRenderer } from './compose/host'
+export * as Ui from './compose/ui'
+export {
+  type DerivedContract,
+  isUi,
+  type MadeView,
+  ui,
+  type UiClass,
+  type UiContract,
+  type UiManifest,
+  UiTypeId,
+  UiViewContract,
+  type ViewImpl,
+  type WireSchemas,
+  type WiredUi,
+  type WiredUiManifest,
+} from './compose/ui'
+export { provide } from './compose/provide'
+export type { Trigger } from './ui/trigger'
+
+// 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 {
+  TriggerRegistry,
+  type TriggerHandle,
+  type TriggerRegistryApi,
+  UnknownTrigger,
+} from './wire/triggers'
+
+// Feature: the lazy/eager code-split unit. Definitions stay eager and reflectable;
+// the heavy `.live` layer loads on demand (an Effect, never a Promise). See LAZY.md.
+export * as Feature from './feature/feature'
+export {
+  type EngineServices,
+  type FailedProps,
+  type FeatureBinding,
+  FeatureBindingTypeId,
+  type FeatureClass,
+  type FeatureManifest,
+  featureModule,
+  type FeatureModule,
+  isFeature,
+  isFeatureBinding,
+  lazyImport,
+  type LoadedModule,
+  mountFeature,
+  type Placeholders,
+  type ProvidedBy,
+  type RequireCarrier,
+} from './feature/feature'
+export { type SlotChild } from './compose/slot'
+
+// A scene bundles a composition with the closed wiring that runs it — the single
+// handle the react host, proofs, and the dev tool all consume.
+export { isScene, type MountedServices, type Scene, scene, seedScene } from './scene/scene'
+
+// Runtime surface for hosts (`@reform/react`) and headless tests.
+export { Bus, type Envelope, type Priority, publish, type Tagged } from './runtime/bus'
+export { Engine, type ReducerEntry, Reducers } from './runtime/loop'
+export {
+  type ChannelClass,
+  type ChannelPolicy,
+  type ChannelRuntime,
+  Channels,
+  type ProcedureEntry,
+  Procedures,
+} from './channel/channel'
+export { CurrentTracker, type Subscribable, type Tracker } from './internal/track'
+export { CaptureSink, type CaptureSinkApi, type UiCapture } from './internal/capture'
+export {
+  AsyncReducer,
+  AsyncSceneLayer,
+  DuplicateRegistration,
+  FeatureLoadFailed,
+  forceSync,
+  InvalidProvideTarget,
+  UnknownGroupState,
+} from './internal/errors'
+// 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'
+export type { FamilyStore } from './state/stateFamily'
+// Primitive-authoring toolkit — exported 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'
+export { readTracked } from './internal/track'
+export { sameKey, wireSources, type WiredSources } from './internal/sources'

package/src/internal/capture.ts

@@ -0,0 +1,38 @@
+import { Context } from 'effect'
+import type { Trigger } from '../ui/trigger'
+
+/**
+ * A single rendered UI node's observable surface: which contract rendered, the
+ * props it received, and the event triggers it was handed. This is exactly what
+ * a headless inspector (the proof facade, the dev tool) needs — no DOM, no JSX.
+ */
+export interface UiCapture {
+  readonly name: string
+  readonly props: unknown
+  readonly events: Record<string, Trigger<unknown>>
+  /**
+   * The stable slot-fill key this render was mounted under (an `each` item's
+   * `key`, or a synthesized singleton key for a `one`). Present only on the
+   * structure path — the legacy Node path defers slot expansion to host
+   * components and has no fill key, so it is omitted there. Lets the proof
+   * facade select a child by key (`byKey`) instead of by render index.
+   */
+  readonly key?: string
+}
+
+/** Where captured renders are reported, when a capturing host is present. */
+export interface CaptureSinkApi {
+  record(capture: UiCapture): void
+}
+
+/**
+ * An OPTIONAL service. Core's `ui` read consults it via `serviceOption`: when a
+ * capturing host provides it (proofs, the dev tool), every resolved view reports
+ * its `(props, events)` before rendering, giving a faithful tree without
+ * replacing any presentation. Production never provides it, so nothing is
+ * recorded and there is no cost beyond one `serviceOption` lookup per render.
+ */
+const CaptureSinkBase: Context.TagClass<CaptureSink, 'reform/internal/CaptureSink', CaptureSinkApi> =
+  Context.Tag('reform/internal/CaptureSink')<CaptureSink, CaptureSinkApi>()
+
+export class CaptureSink extends CaptureSinkBase {}

package/{dist/internal/ctx.d.ts → src/internal/ctx.ts}

@@ -1,5 +1,6 @@
-import type { Effect } from 'effect';
-import type { YieldWrap } from 'effect/Utils';
+import type { Effect } from 'effect'
+import type { YieldWrap } from 'effect/Utils'
+
 /**
  * The context (`R`) a generator body requires, recovered from the effects it
  * yields. Shared by `Composition.live` and `Procedure.live`, whose bodies are
@@ -8,5 +9,8 @@ import type { YieldWrap } from 'effect/Utils';
  * A body that never yields (`Eff = never`) requires nothing — guard that case
  * first, or `infer R` resolves to `unknown` and leaks into the layer's `RIn`.
  */
-export type Ctx<Eff> = [Eff] extends [never] ? never : [Eff] extends [YieldWrap<Effect.Effect<any, any, infer R>>] ? R : never;
-//# sourceMappingURL=ctx.d.ts.map
+export type Ctx<Eff> = [Eff] extends [never]
+  ? never
+  : [Eff] extends [YieldWrap<Effect.Effect<any, any, infer R>>]
+    ? R
+    : never

package/src/internal/errors.test.ts

@@ -0,0 +1,33 @@
+import { expect, it } from '@effect/vitest'
+import { Context, Effect, Layer, ManagedRuntime } from 'effect'
+import { AsyncSceneLayer, forceSync } from '../index'
+
+// `forceSync` is the sync-build boundary: reform materialises a scene's layer graph
+// with `runSync` so the first frame renders synchronously (D2). A layer whose acquire
+// suspends makes that `runSync` throw Effect's opaque `AsyncFiberException`; the
+// boundary translates it into `AsyncSceneLayer`, which names the cause and the fix.
+
+class Thing extends Context.Tag('test/Thing')<Thing, number>() {}
+
+it('translates an async layer build into AsyncSceneLayer', () => {
+  // A layer whose acquire suspends — exactly what a consumer trips on.
+  const asyncLayer = Layer.effect(Thing, Effect.as(Effect.sleep('1 millis'), 1))
+  const runtime = ManagedRuntime.make(asyncLayer)
+  expect(() => forceSync(() => runtime.runSync(Effect.context<Thing>()))).toThrow(AsyncSceneLayer)
+})
+
+it('passes a synchronous layer build through unchanged', () => {
+  const syncLayer = Layer.succeed(Thing, 1)
+  const runtime = ManagedRuntime.make(syncLayer)
+  const context = forceSync(() => runtime.runSync(Effect.context<Thing>()))
+  expect(Context.get(context, Thing)).toBe(1)
+})
+
+it('re-throws a non-async error untouched', () => {
+  class Boom extends Error {}
+  expect(() =>
+    forceSync(() => {
+      throw new Boom('nope')
+    }),
+  ).toThrow(Boom)
+})

package/src/internal/errors.ts

@@ -0,0 +1,133 @@
+import { Cause, Data, Option, Runtime } from 'effect'
+
+/**
+ * Tagged errors for the framework's synchronous boundaries. Even when thrown
+ * (React render, layer build, reflection), an error carries a `_tag` and its
+ * structured fields — never a bare `Error` — so callers and tooling can match on
+ * it. `Data.TaggedError` subclasses are real `Error`s, so `throw` still works.
+ */
+
+/**
+ * The constructor shape `Data.TaggedError(tag)<A>` produces, named so the
+ * generated `.d.ts` can describe the `extends` base under `isolatedDeclarations`
+ * (which forbids an inferred expression in an extends clause).
+ */
+type TaggedErrorClass<Tag extends string, A extends Record<string, unknown>> = new (
+  args: A,
+) => Cause.YieldableError & { readonly _tag: Tag } & Readonly<A>
+
+/** The fieldless variant — a `Data.TaggedError(tag)<{}>` constructor. */
+type EmptyTaggedErrorClass<Tag extends string> = new () => Cause.YieldableError & { readonly _tag: Tag }
+
+const InvalidProvideTargetBase: EmptyTaggedErrorClass<'reform/InvalidProvideTarget'> =
+  Data.TaggedError('reform/InvalidProvideTarget')<{}>
+
+/** `provide(target, …)` was handed something that is neither a ui contract nor a slot. */
+export class InvalidProvideTarget extends InvalidProvideTargetBase {
+  override get message(): string {
+    return 'reform: provide target is neither a ui contract nor a slot'
+  }
+}
+
+const UnknownGroupStateBase: TaggedErrorClass<'reform/UnknownGroupState', { readonly name: string }> =
+  Data.TaggedError('reform/UnknownGroupState')<{ readonly name: string }>
+
+/** `StateGroup.select(group, name)` named a state the group does not contain. */
+export class UnknownGroupState extends UnknownGroupStateBase {
+  override get message(): string {
+    return `reform: unknown state '${this.name}' in group`
+  }
+}
+
+const FeatureLoadFailedBase: TaggedErrorClass<'reform/FeatureLoadFailed', { readonly cause: unknown }> =
+  Data.TaggedError('reform/FeatureLoadFailed')<{ readonly cause: unknown }>
+
+/**
+ * A lazy `Feature`'s `load` Effect failed — the dynamic `import()` rejected (a
+ * missing chunk, a network failure, a module-eval throw). Surfaced as a typed
+ * failure the host hands to the feature's `placeholder.failed`, never a bare
+ * rejection. `cause` is the original rejection value.
+ */
+export class FeatureLoadFailed extends FeatureLoadFailedBase {
+  override get message(): string {
+    return `reform: a feature failed to load (${String(this.cause)})`
+  }
+}
+
+const AsyncReducerBase: EmptyTaggedErrorClass<'reform/AsyncReducer'> =
+  Data.TaggedError('reform/AsyncReducer')<{}>
+
+/** A reducer fold returned a thenable — folds must be pure synchronous writes. */
+export class AsyncReducer extends AsyncReducerBase {
+  override get message(): string {
+    return 'reform: a reducer fold must be synchronous (it returned a Promise)'
+  }
+}
+
+const AsyncSceneLayerBase: EmptyTaggedErrorClass<'reform/AsyncSceneLayer'> =
+  Data.TaggedError('reform/AsyncSceneLayer')<{}>
+
+/**
+ * A scene layer performed async work during reform's synchronous layer build.
+ * Reform materialises a scene's layer graph with `runSync` so the first frame
+ * renders synchronously (D2); a `Layer.effect`/`scoped` whose acquire suspends
+ * (HTTP, opening a DB, `Effect.sleep`) makes that `runSync` throw Effect's opaque
+ * `AsyncFiberException`. `forceSync` catches it and rethrows this, which names the
+ * cause and the sanctioned fix instead of pointing at Effect internals.
+ */
+export class AsyncSceneLayer extends AsyncSceneLayerBase {
+  override get message(): string {
+    return (
+      'reform: a scene layer performed async work while building. Reform builds the ' +
+      'scene synchronously so the first frame can render — a layer acquire must be ' +
+      'synchronous (Layer.sync/Layer.succeed). For async setup (open a connection, ' +
+      'fetch config), use Resource.live from @playfast/reform-resource, which builds ' +
+      'synchronously and resolves in the background.'
+    )
+  }
+}
+
+/**
+ * Whether a thrown value is Effect's "ran async under runSync" defect. `runSync`
+ * throws the bare `AsyncFiberException`; a `ManagedRuntime.runSync` whose layer
+ * build suspends instead throws a `FiberFailure` carrying it as a `Die`, so both
+ * shapes are checked.
+ */
+const isAsyncBuildDefect = (error: unknown): boolean => {
+  if (Runtime.isAsyncFiberException(error)) return true
+  if (!Runtime.isFiberFailure(error)) return false
+  const die = Cause.dieOption(error[Runtime.FiberFailureCauseId])
+  return Option.isSome(die) && Runtime.isAsyncFiberException(die.value)
+}
+
+/**
+ * Run a synchronous runtime read (the scene layer build / context capture) and
+ * translate Effect's async-fiber defect into `AsyncSceneLayer`; any other throw
+ * passes through unchanged. The single home for the sync-build boundary, shared by
+ * the React host and the remote server.
+ */
+export const forceSync = <A>(thunk: () => A): A => {
+  try {
+    return thunk()
+  } catch (error) {
+    if (isAsyncBuildDefect(error)) throw new AsyncSceneLayer()
+    throw error
+  }
+}
+
+const DuplicateRegistrationBase: TaggedErrorClass<
+  'reform/DuplicateRegistration',
+  { readonly kind: string; readonly name: string }
+> = Data.TaggedError('reform/DuplicateRegistration')<{ readonly kind: string; readonly name: string }>
+
+/**
+ * Two distinct primitives were registered under one name into the same runtime —
+ * a silent footgun, since names key DI tags and channel lanes. Thrown for a
+ * channel name reused with a different policy (the second would otherwise be
+ * dropped). Reducer/procedure name clashes are warned (logged), not thrown.
+ */
+export class DuplicateRegistration extends DuplicateRegistrationBase {
+  override get message(): string {
+    return `reform: duplicate ${this.kind} registered under name '${this.name}'`
+  }
+}

package/src/internal/inspect.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from '@effect/vitest'
+import { Schema as S } from 'effect'
+import { State } from '../index'
+import { makeStore } from './store'
+
+// Every reform value should print like an Effect value (an `_id`-tagged JSON),
+// not `[object Object]` — via `toJSON`/`toString`/the Node inspect symbol.
+
+describe('Inspectable', () => {
+  it('a Store reports its current value as tagged JSON', () => {
+    const store = makeStore(41)
+    expect(store.toJSON()).toEqual({ _id: 'reform/Store', value: 41 })
+    store.set(42)
+    expect(store.toJSON()).toEqual({ _id: 'reform/Store', value: 42 })
+    // toString and JSON.stringify route through the same toJSON.
+    expect(JSON.parse(JSON.stringify(store))).toEqual({ _id: 'reform/Store', value: 42 })
+    expect(store.toString()).toContain('reform/Store')
+  })
+
+  it('a definition reports its manifest', () => {
+    class Count extends State.make('count', S.Number) {}
+    // Inspectable is attached at runtime (definitions are reflected via their
+    // manifest); reach the method through a typed view.
+    const inspectable = Count as unknown as { toJSON(): unknown }
+    expect(inspectable.toJSON()).toBe(Count.manifest)
+    expect(String(Count)).toContain('"kind": "State"')
+  })
+})

package/src/internal/inspect.ts

@@ -0,0 +1,34 @@
+import { format, type Inspectable, NodeInspectSymbol } from 'effect/Inspectable'
+
+export { type Inspectable, NodeInspectSymbol }
+
+/**
+ * The `Inspectable` trio built around a `toJSON`, so every reform value prints
+ * like an Effect value — `_id`-tagged JSON under `console.log`, Node's
+ * inspector, `JSON.stringify`, and `String(...)` — instead of `[object Object]`.
+ * Mirrors Effect's `BaseProto` / `Inspectable.Class` (`Inspectable.ts:170`).
+ */
+export const inspectable = (toJSON: () => unknown): Inspectable => ({
+  toJSON,
+  toString: () => format(toJSON()),
+  [NodeInspectSymbol]: () => toJSON(),
+})
+
+/**
+ * Attach the `Inspectable` trio to an existing object as *non-enumerable* own
+ * properties (so they don't show up in `Object.keys`/`for…in` over a definition
+ * class). Used where the value is built by other means — the definition classes,
+ * whose statics are merged in separately.
+ */
+export const attachInspectable = <T extends object>(target: T, toJSON: () => unknown): T => {
+  const trio = inspectable(toJSON) as unknown as Record<PropertyKey, unknown>
+  for (const key of Reflect.ownKeys(trio)) {
+    Object.defineProperty(target, key, {
+      value: trio[key],
+      enumerable: false,
+      writable: true,
+      configurable: true,
+    })
+  }
+  return target
+}