@typeonce/effect-machine 0.31.2 → 0.32.0

package/docs/agent-guide.md

@@ -22,12 +22,12 @@ const CounterState = Schema.TaggedUnion({
   Running: { count: Schema.Number }
 })
 
-export const CounterStates = Machine.states({
+export const CounterStates = Machine.state({ initial: "Idle", states: {
   Idle: {},
   Running: CounterState.cases.Running
-})
+} })
 
-export const CounterEvents = Machine.events(
+export const CounterEvents = Machine.eventsFromSchemas(
   Schema.TaggedUnion({
     Start: {},
     Increment: {},
@@ -37,27 +37,27 @@ export const CounterEvents = Machine.events(
 
 export const CounterMachine = Machine.make({
   id: "Counter",
-  states: CounterStates.states,
+  root: CounterStates,
   events: CounterEvents,
-  initial: (to) => to.Idle()
-}).handle({
+  initialConfiguration: root => root.resolve(({ target }) => target.from(to => to.Idle.from()))
+}).handle({ states: {
   Idle: {
     on: {
-      Start: (to) => to.full.Running().resolve(({ target }) => target.from({ count: 0 }))
+      Start: (to) => to.branch.Running().resolve(({ target }) => target.from({ count: 0 }))
     }
   },
   Running: {
     on: {
-      Increment: (to) => to.full.Running().resolve(({ state, target }) => target.from({ count: state.count + 1 })),
-      Stop: (to) => to.full.Idle()
+      Increment: (to) => to.branch.Running().resolve(({ state, target }) => target.from({ count: state.count + 1 })),
+      Stop: (to) => to.branch.Idle()
     }
   }
-})
+} })
 ```
 
 Each step has one job:
 
-- `Machine.states` declares the state tree and the data owned by each state.
+- `Machine.state` declares the root, its child topology, and state-owned data.
 - `Machine.events` declares the public messages the machine accepts and returns
   typed event constructors.
 - `Machine.make` joins the state tree, event protocol, input, and initial state.
@@ -106,12 +106,12 @@ const RequestState = Schema.TaggedUnion({
   Failed: { message: Schema.String }
 })
 
-const RequestStates = Machine.states({
+const RequestStates = Machine.state({ initial: "Idle", states: {
   Idle: {},
   Loading: {},
   Ready: RequestState.cases.Ready,
   Failed: RequestState.cases.Failed
-})
+} })
 ```
 
 The machine can now be `Loading`, `Ready`, or `Failed`. It cannot construct a
@@ -139,7 +139,7 @@ const DocumentState = Schema.TaggedUnion({
   }
 })
 
-const DocumentStates = Machine.states({
+const DocumentStates = Machine.state({ initial: "Closed", states: {
   Closed: {},
   Open: {
     // Editing, Saving, and SaveFailed all need the document and draft.
@@ -152,7 +152,7 @@ const DocumentStates = Machine.states({
       SaveFailed: DocumentState.cases.SaveFailed
     }
   }
-})
+} })
 ```
 
 Do not copy `documentId` and `draft` into every child. Copies can disagree after
@@ -165,22 +165,22 @@ Hierarchy owns behavior as well as data. Define a transition on the lowest
 compound state whose children share it.
 
 ```ts
-const DocumentEvents = Machine.events(
+const DocumentEvents = Machine.eventsFromSchemas(
   Schema.TaggedUnion({
     Close: {}
   })
 )
 
 const DocumentMachine = Machine.make({
-  states: DocumentStates.states,
+  root: DocumentStates,
   events: DocumentEvents,
   initial: (to) => to.Closed()
-}).handle({
+}).handle({ states: {
   Closed: {},
   Open: {
     on: {
       // All Open children close the document in the same way.
-      Close: (to) => to.full.Closed()
+      Close: (to) => to.branch.Closed()
     },
     states: {
       Editing: {},
@@ -188,7 +188,7 @@ const DocumentMachine = Machine.make({
       SaveFailed: {}
     }
   }
-})
+} })
 ```
 
 The machine checks the deepest active state first, then its ancestors. Put a
@@ -202,7 +202,7 @@ after domain actions and outcomes. Do not expose state setters such as
 `SetLoading` or `SetError`.
 
 ```ts
-export const CheckoutEvents = Machine.events(
+export const CheckoutEvents = Machine.eventsFromSchemas(
   Schema.TaggedUnion({
     Submit: {},
     Cancel: {}
@@ -210,23 +210,23 @@ export const CheckoutEvents = Machine.events(
 )
 
 const CheckoutMachine = Machine.make({
-  states: CheckoutStates.states,
+  root: CheckoutStates,
   events: CheckoutEvents,
   initial: (to) => to.Editing()
-}).handle({
+}).handle({ states: {
   Editing: {
     on: {
-      Submit: (to) => to.full.Submitting()
+      Submit: (to) => to.branch.Submitting()
     }
   },
   Submitting: {
     on: {
       // Cancel has meaning while work is in progress.
-      Cancel: (to) => to.full.Editing()
+      Cancel: (to) => to.branch.Editing()
     }
   },
   Complete: {}
-})
+} })
 ```
 
 The sender requests `Submit`. The machine decides whether `Submit` has a
@@ -243,7 +243,7 @@ child in every region. A parallel model therefore accepts the full product of
 those regions.
 
 ```ts
-const ScreenStates = Machine.states({
+const ScreenStates = Machine.state({ initial: "Screen", states: {
   Screen: {
     type: "parallel",
     states: {
@@ -263,7 +263,7 @@ const ScreenStates = Machine.states({
       }
     }
   }
-})
+} })
 ```
 
 This model permits all four combinations: online with a closed panel, online
@@ -286,29 +286,29 @@ const LoadState = Schema.TaggedUnion({
   Failed: { message: Schema.String }
 })
 
-const LoadStates = Machine.states({
+const LoadStates = Machine.state({ initial: "Idle", states: {
   Idle: {},
   Loading: LoadState.cases.Loading,
   Ready: LoadState.cases.Ready,
   Failed: LoadState.cases.Failed
-})
+} })
 
 const LoadMachine = Machine.make({
-  states: LoadStates.states,
-  events: Machine.events(),
-  initial: (to) => to.Idle()
-}).handle({
+  root: LoadStates,
+  events: Machine.eventsFromSchemas(),
+  initialConfiguration: root => root.resolve(({ target }) => target.from(to => to.Idle.from()))
+}).handle({ states: {
   Idle: {},
   Loading: {
     invoke: (from) =>
       from
         .effect("load-document", ({ state }) => loadDocument(state.documentId))
-        .onDone((to) => to.full.Ready().resolve(({ output, target }) => target.from({ content: output })))
-        .onFailure((to) => to.full.Failed().resolve(({ error, target }) => target.from({ message: String(error) })))
+        .onDone((to) => to.branch.Ready().resolve(({ output, target }) => target.from({ content: output })))
+        .onFailure((to) => to.branch.Failed().resolve(({ error, target }) => target.from({ message: String(error) })))
   },
   Ready: {},
   Failed: {}
-})
+} })
 ```
 
 `loadDocument` may require Effect services. Those requirements remain on the
@@ -356,8 +356,8 @@ Commissioning: {
         { discard: true }
       )
     )
-    .onDone((to) => to.full.Running())
-    .onFailure((to) => to.full.Failed())
+    .onDone((to) => to.branch.Running())
+    .onFailure((to) => to.branch.Failed())
 }
 ```
 
@@ -374,24 +374,24 @@ A transition should choose the next state from the current snapshot and event.
 Use ordinary TypeScript conditions when one event has several valid outcomes.
 
 ```ts
-const ReviewEvents = Machine.events(
+const ReviewEvents = Machine.eventsFromSchemas(
   Schema.TaggedUnion({
     Evaluate: { score: Schema.Number }
   })
 )
 
 const ReviewMachine = Machine.make({
-  states: ReviewStates.states,
+  root: ReviewStates,
   events: ReviewEvents,
   initial: (to) => to.Pending()
-}).handle({
+}).handle({ states: {
   Pending: {
     on: {
       Evaluate: (to) =>
         to
           .branches({
-            accepted: { target: to.full.Accepted() },
-            rejected: { target: to.full.Rejected() }
+            accepted: { target: to.branch.Accepted() },
+            rejected: { target: to.branch.Rejected() }
           })
           .resolve(({ event, select }) =>
             event.score >= 80
@@ -402,7 +402,7 @@ const ReviewMachine = Machine.make({
   },
   Accepted: {},
   Rejected: {}
-})
+} })
 ```
 
 Given the same snapshot and event, the handler should choose the same result.

package/docs/effect-atom-react.md

@@ -39,85 +39,61 @@ Service-free machines can use `AtomMachine.make` directly.
 
 ## Own a machine in one React subtree
 
-Use `useMachineAtom` when a provider, route, dialog, or other React subtree
-owns one machine instance:
+Create a context from a factory. Each Provider owns a fresh bridge in its current
+Atom registry; it does not subscribe to state changes.
 
 ```tsx
-import { useMachineAtom } from "@typeonce/effect-machine-react"
-import { createContext, type ReactNode, useContext } from "react"
-import { AuthMachine, type AuthMachineInput } from "../machines/auth-machine"
+import { createMachineContext } from "@typeonce/effect-machine-react"
+import { AuthMachine } from "../machines/auth-machine"
 import { MachineAtoms } from "../lib/atom-runtime"
 
-const makeAuthMachine = MachineAtoms.factory(AuthMachine)
-type AuthMachineAtom = ReturnType<typeof makeAuthMachine>
-
-const AuthMachineContext = createContext<AuthMachineAtom | null>(null)
-
-export function AuthMachineProvider({
-  children,
-  input
-}: {
-  readonly children: ReactNode
-  readonly input: AuthMachineInput
-}) {
-  const machine = useMachineAtom(() => makeAuthMachine(input))
+export const Auth = createMachineContext(MachineAtoms.factory(AuthMachine))
+export const useAuthMachine = Auth.useMachine
 
+function AuthRoute({ input, attemptId }: Props) {
   return (
-    <AuthMachineContext.Provider value={machine}>
-      {children}
-    </AuthMachineContext.Provider>
+    <Auth.Provider key={attemptId} input={input}>
+      <Suspense fallback={<Loading />}>
+        <AuthCard />
+      </Suspense>
+    </Auth.Provider>
   )
 }
-
-export function useAuthMachine(): AuthMachineAtom {
-  const machine = useContext(AuthMachineContext)
-  if (machine === null) {
-    throw new Error("useAuthMachine must be used inside AuthMachineProvider")
-  }
-  return machine
-}
 ```
 
-The provider strongly owns the complete `MachineAtom`. The hook mounts
-`machine.ref` after React commits the owner, but it does not read `state`,
-`snapshot`, or `result`. Machine updates therefore do not rerender the
-provider.
+Input is startup-only. Send events to update the existing workflow; change the
+Provider's React key to create a new one. Keep the Provider above Suspense so
+suspension does not discard the owner. Supply an Atom RegistryProvider at the
+application boundary. The same factory used by two Providers creates isolated
+machines, even when their inputs are equal.
 
-The factory captures startup input once. A later `input` prop change does not
-replace the running workflow. Send an event when the change belongs to that
-workflow. Change the provider's React key when React should own a new machine:
-
-```tsx
-<AuthMachineProvider key={attemptId} input={input}>
-  <AuthCard />
-</AuthMachineProvider>
-```
-
-Put the owner above a Suspense boundary. React can then retain the same machine
-while a state-reading descendant suspends.
+`useMachineAtom(() => makeMachine(input))` remains available for custom owners.
+It mounts the reference after commit without reading `result` or `snapshot`.
 
 ## Render state-owned data
 
-Subscribe in the smallest component that renders a state path:
+Render a typed path in the smallest component that needs it:
 
 ```tsx
-import { useAtomSuspense } from "@effect/atom-react"
-import { AtomMachine } from "@typeonce/effect-machine/reactivity"
-import { Option } from "effect"
+import { MachineState } from "@typeonce/effect-machine-react"
 
 function EditingFields() {
   const machine = useAuthMachine()
-  const editing = useAtomSuspense(
-    AtomMachine.selectSnapshot(machine, "Editing")
-  ).value
-
-  return Option.match(editing, {
-    onNone: () => null,
-    onSome: ({ value }) => <EmailField email={value.email} />
-  })
+  return (
+    <MachineState machine={machine} path="Editing" inactive={null}>
+      {({ value }) => <EmailField email={value.email} />}
+    </MachineState>
+  )
 }
 ```
 
+`MachineState` subscribes only its renderer. The path determines the callback's
+snapshot type. Startup suspends, failures reach the nearest error boundary,
+and an inactive path renders `inactive` (null by default).
+
+For custom hooks, `useAtomSuspense(AtomMachine.selectSnapshot(machine, path)).value`
+returns an Option of the selected snapshot.
+
 `AtomMachine.select` returns the selected state value.
 `AtomMachine.selectSnapshot` also retains the selected state's child topology.
 Both return `Option.none()` while the path is inactive. Do not replace that
@@ -240,11 +216,7 @@ function AuthScreen() {
   const machine = useAuthMachine()
   const state = useAtomSuspense(machine.result).value
 
-  return AuthStates.match(state, {
-    Editing: (editing) => <EditingScreen state={editing} />,
-    Verification: (verification) => <VerificationScreen state={verification} />,
-    Failed: (failed) => <FailureScreen state={failed} />
-  })
+  return <MachineSummary snapshot={state} />
 }
 ```
 
@@ -320,7 +292,7 @@ export const plantAtoms = AtomMachine.familyChild(CentralMachineAtom, {
   child: (plantId: string) => Plant(plantId),
   atoms: {
     broken: AtomMachine.matchesChild("Broken"),
-    state: (plant) => plant.state,
+    state: (plant) => plant.result,
     send: (plant) => plant.send
   }
 })

package/docs/machine-review.md

@@ -39,12 +39,12 @@ job is returning `target.from()`.
 // Redundant
 const handlers = {
   Start: (to) =>
-    to.full.Running().resolve(({ target }) => target.from())
+    to.branch.Running().resolve(({ target }) => target.from())
 }
 
 // Preferred
 const handlers = {
-  Start: (to) => to.full.Running()
+  Start: (to) => to.branch.Running()
 }
 ```
 
@@ -176,11 +176,11 @@ Model `Submit` as the component-facing event. Let a machine state own the work
 and its lifetime:
 
 ```ts
-machine.handle({
+machine.handle({ states: {
   Editing: {
     on: {
       Submit: (to) =>
-        to.full.Submitting().resolve(({ event, target }) =>
+        to.branch.Submitting().resolve(({ event, target }) =>
           target.from({ order: event.order })
         )
     }
@@ -190,17 +190,17 @@ machine.handle({
       from
         .effect("submit-order", ({ state }) => submitOrder(state.order))
         .onDone((to) =>
-          to.full.Complete().resolve(({ output, target }) =>
+          to.branch.Complete().resolve(({ output, target }) =>
             target.from({ order: output })
           )
         )
         .onFailure((to) =>
-          to.full.Failed().resolve(({ error, target }) =>
+          to.branch.Failed().resolve(({ error, target }) =>
             target.from({ message: String(error) })
           )
         )
   }
-})
+} })
 ```
 
 `submitOrder` can use Effect services for the API request and analytics. The

package/docs/root-api.md

@@ -0,0 +1,214 @@
+# Root machine API
+
+A machine is one explicit root state. The root can own data, child topology,
+both, or neither. There is no separate global context store.
+
+## Events and transitions only
+
+```ts
+import { Machine } from "@typeonce/effect-machine"
+import { Schema } from "effect"
+
+const Events = Machine.events({ Open: {}, Close: {} })
+const Root = Machine.state({
+  initial: "Closed",
+  states: { Closed: {}, Open: {} }
+})
+const Door = Machine.make({ root: Root, events: Events }).handle({
+  states: {
+    Closed: { on: { Open: (to) => to.local.Open() } },
+    Open: { on: { Close: (to) => to.local.Closed() } }
+  }
+})
+```
+
+The root declares the default child once. No startup target, empty schema, or
+resolver is needed. Structural nodes have `value: undefined` in snapshots.
+
+## Root data and child data
+
+```ts
+const Root = Machine.state({
+  fields: { title: Schema.String },
+  initial: "Editing",
+  states: {
+    Editing: { fields: { draft: Schema.String } },
+    Saving: {}
+  }
+})
+const Events = Machine.events({ Rename: { title: Schema.String }, Save: {} })
+const Editor = Machine.make({
+  root: Root,
+  events: Events,
+  initial: (root) => root.from(() => ({ title: "Untitled" }))
+}).handle({
+  initialize: ({ builder, state }) => builder.from({ draft: state.title }),
+  on: {
+    Rename: (to) => to.self.update.from(({ event }) => ({ title: event.title }))
+  },
+  states: {
+    Editing: { on: { Save: (to) => to.local.Saving() } }
+  }
+})
+```
+
+`initialize` constructs the declared child configuration. Required values must
+be supplied before the machine becomes executable. Values whose schema make
+input is optional can use their schema defaults. A parallel owner's initializer
+constructs every required region through the typed builder.
+
+The complete snapshot always includes the root:
+
+```ts
+// While Editing is active:
+{
+  path: "",
+  value: { _tag: "", title: "Untitled" },
+  state: {
+    path: "Editing",
+    value: { _tag: "Editing", draft: "Untitled" }
+  }
+}
+```
+
+Root handlers remain active across child transitions. Child handlers receive
+their own state, typed ancestors, and the complete snapshot. `to.root.update`
+addresses root data from a child. `to.self.update` addresses the handler owner.
+Both replace the entire value; omitted fields are not silently retained.
+Updates preserve the active topology and do not restart scoped work.
+
+Simultaneous transitions retain conflict checking. Two parallel handlers cannot
+silently overwrite the same owner. Use `.updating(owner)` to combine a selected
+destination and a retained owner's value in one atomic transition.
+
+## Schemas and reusable descriptors
+
+Use `fields` for local data or `schema` for an existing tagged schema. They are
+mutually exclusive. A schema preserves class identity, refinements, defaults,
+and transformations; its tag is independent of its mount path.
+
+```ts
+class Ready extends Schema.TaggedClass<Ready>("Ready")("Ready", {
+  name: Schema.String
+}) {}
+
+const Form = Machine.state({
+  initial: "Idle",
+  states: { Idle: {}, Ready: { schema: Ready } }
+})
+const Root = Machine.state({
+  type: "parallel",
+  states: { First: Form, Second: Form }
+})
+```
+
+Each mount has its own path and lifecycle. Descriptors capture their definition
+without retaining caller-owned mutable topology containers. `Machine.make`
+accepts the complete descriptor as `root`; callers do not extract its internals.
+
+`Machine.events({ Save: { title: Schema.String } })` creates a deferred
+`Events.Save({ title })` constructor. The machine validates it when processing
+the event. To reuse tagged classes or a tagged union, use
+`Machine.eventsFromSchemas(...)`. Internal and emitted protocols have distinct
+constructors with the same fields/import distinction. Public sends cannot send
+internal events, and emissions do not become machine input events implicitly.
+
+## Default initialization and explicit configuration
+
+`initial` supplies root values while following the topology's declared child
+defaults. It does not override those defaults. A structural root usually needs
+no initializer.
+
+Use the separately named `initialConfiguration` to select a complete startup
+configuration, for example to start the door open:
+
+```ts
+const DoorOpen = Machine.make({
+  root: Root,
+  events: Events,
+  initialConfiguration: (root) => root.resolve(({ target }) =>
+    target.from((states) => states.Open.from())
+  )
+}).handle({})
+```
+
+This example uses the door root and events from the first section. Every active
+value and region in an explicit configuration must be provided. `initial` and
+`initialConfiguration` cannot be combined. Use `Machine.resume` when restoring
+a validated snapshot, including its completion and history metadata.
+
+## Construction, guards, and branches
+
+A selected target supports a direct callback:
+
+```ts
+Save: (to) => to.local.Saving().from(({ event }) => ({ requestId: event.requestId }))
+```
+
+Use `.decoded(({ state }) => state)` for already decoded schema values. Use
+`.resolve((context, enqueue) => ...)` when constructing child configurations or
+queuing commands; its `context.target.from(...)` and `.decoded(...)` take values
+and explicit child builders.
+
+A guard runs before construction and commands:
+
+```ts
+Save: (to) => to.local.Saving()
+  .guard(({ state }) => state.draft.length > 0)
+  .from(({ state }) => ({ requestId: state.draft }))
+```
+
+A false guard declines this handler, allowing ancestor fallback. Guards are not
+available for mandatory initial resolution or a total choice. `.none` accepts
+an event without changing topology; declining and accepting have different
+semantics. Named branches keep `{ target, title? }`: `target` identifies the
+checked destination and `title` supplies optional presentation metadata.
+
+## Completion and history
+
+A compound root returns its completed direct workflow's output when that child
+has no `onDone` handler. A child with `onDone` first handles its completion.
+Nested compound states retain statechart completion rules: an arbitrary
+completed descendant does not make every ancestor final. Parallel roots
+complete when all required regions complete.
+
+Restoring history beneath the root preserves current root data. Restoring the
+root's own history can restore root-owned data. History fallback builders must
+construct a complete configuration containing the history owner.
+
+## Observation and testing
+
+- `MachineRef.state` reads the complete logical root snapshot.
+- `MachineRef.snapshot` includes runtime status and completion information.
+- `MachineAtom.result` retains asynchronous startup, failure, and the successful
+  logical snapshot. `MachineAtom.snapshot` exposes the runtime snapshot.
+- `AtomMachine.select` selects an optional value; `selectSnapshot` selects an
+  optional subtree. Child inactivity remains `Option.none()`.
+- `MachineState` renders a typed path in React. `createMachineContext(factory)`
+  owns a separate machine per Provider without subscribing the Provider to it.
+
+The Atom bridge and child bridge no longer expose `.state`; use `.result` or a
+path selector. The core `MachineRef.state` contract remains available.
+
+`MachineTest.run` and `MachineTest.probe` accept the same public event inputs as
+production sends, including deferred constructors. Traces and acknowledgements
+record the decoded event that was processed, including ignored events.
+
+## Migration
+
+Replace `Machine.states(tree)` and `Machine.make({ states: States.states })`
+with one `Machine.state({ initial, states: tree })` descriptor and
+`Machine.make({ root })`. Move the old root-level handler map under
+`handle({ states: ... })`; place machine-wide behavior directly in `handle`.
+Use root `fields` to replace a wrapper state introduced only to carry shared data.
+Use `Machine.Snapshot<typeof root>` for the complete logical snapshot. `Machine.StateAccessors` replaces the former `Machine.DefinedStates`
+helper interface; it exposes paths and projections without a public state map.
+
+Replace schema arguments to `Machine.events`, `internalEvents`, and
+`emittedEvents` with field records, or use their explicit `FromSchemas`
+constructors. Replace old Atom `.state` reads with `.result`. Use
+`EmittedEvent`, `EmittedEvents`, `EmittedEventOf`, and `SchemaLessStateAnnotations` in place
+of the removed deprecated type aliases.
+
+Encoded snapshots now use version 2 and include the root at path `""`.
+Version 1 payloads must be explicitly migrated; the decoder rejects them.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeonce/effect-machine",
-  "version": "0.31.2",
+  "version": "0.32.0",
   "description": "Schema-first state machines and statecharts for Effect",
   "author": "Sandro Maglione",
   "repository": {