Adopt synchronous machine transitions

Author: SandroMaglione

.changeset/fast-machines-enqueue.md

@@ -0,0 +1,13 @@
+---
+"@typeonce/effect-machine": minor
+---
+
+Replace Effectful state transition, lifecycle, choice, history, and initial
+callbacks with a synchronous `(state, event) => [nextState, commands]` core.
+Callbacks may enqueue only typed `raise`, `emit`, `sendTo`, and `stop`
+operations; asynchronous work remains available through invoked Effects,
+actors, and child machines.
+
+Remove `Machine.action`, `Machine.runtime`, and `Machine.runActions`. Planning
+now returns closed actor `commands`, while managed runtimes execute those
+commands around state publication and typed emission delivery.

README.md

@@ -423,8 +423,8 @@ BufferReady: ;
 ```
 
 All non-conflicting handlers selected together observe the same captured
-snapshot. An Effectful handler keeps that value; it does not read mutable live
-runtime state later. `snapshot` is intentionally absent from entry, exit,
+snapshot. Handlers are synchronous and cannot read mutable live runtime state
+later. `snapshot` is intentionally absent from entry, exit,
 invoke, and choice contexts. In particular, startup and chained choices may run
 before a complete stable snapshot containing their pseudo-source exists.
 
@@ -442,25 +442,25 @@ Schema-less choice and history nodes accept only descriptive `title`,
 `description`, and `documentation` annotations. Titles may be used as display
 labels, but structural paths remain the only identity and targeting mechanism.
 
-## Planning Effects and staged actions
+## Synchronous transitions and actor commands
 
-An Effect returned by a transition handler is part of planning. Use it to read
-services, choose a target, raise an event, or emit an event. Wrap external side
-effects in `Machine.action`; actions are staged during planning and run by the
-managed runtime before it publishes the next state.
+Transition, entry, exit, choice, initial, and history callbacks are synchronous.
+They select state and may enqueue only explicit statechart or actor operations:
+raise an internal event, emit to the parent, send to an invoked child, or stop a
+child. Arbitrary Effects are not accepted at this boundary.
 
 ```ts
 const handlers = {
-  Save: ({ target }) => Machine.action(writeAuditLog, target.local.Saving.from())
+  Save: ({ target }, enqueue) => {
+    enqueue.emit(new SaveRequested({}))
+    return target.local.Saving.from()
+  }
 }
 ```
 
-The one-argument form returns `void` after staging. The two-argument form
-returns its second argument, which avoids a generator when an action and the
-next target are the whole transition.
-
-If an action fails, the runtime keeps the previously published state and
-suppresses emissions from that plan.
+Use `Machine.invokeEffect`, `Machine.invoke`, or an invoked child machine for
+asynchronous work. Their results return to the parent as typed events, keeping
+the transition core deterministic and synchronous.
 
 `Machine.plan` and `Machine.planInitial` return a `done` discriminator. When
 `done` is `true`, `output` is the schema-derived structural terminal union;

docs/agent-guide.md

@@ -65,8 +65,8 @@ class methods or nominal class identity.
   transport boundary.
 - Return snapshots or typed target-builder results from transitions. Do not
   return raw decoded state values.
-- Effects returned by handlers are planning Effects. Wrap external effects in
-  `Machine.action`.
+- Transition and lifecycle callbacks are synchronous. Put asynchronous work in
+  an invoked Effect, actor, or child machine and map its result to an event.
 - Put data on the narrowest state where it is valid. Put data shared by sibling
   phases on their compound parent.
 - Declare finality only in the state definition. Do not put `type: "final"` in
@@ -101,9 +101,8 @@ its extra control is required:
   `Machine.childAddress<Event>(id)` for a low-level process address. An
   invocation is addressable only when `Machine.invoke` receives that address
   explicitly.
-- Stage external effects with `Machine.action`; its optional second argument is
-  the same operation with a returned transition value, not a separate action
-  API.
+- Use the callback's `enqueue` argument for `raise`, `emit`, `sendTo`, and
+  `stop`. These operations record closed actor commands and do not run Effects.
 
 ## Atomic, compound, parallel, and history states
 
@@ -389,8 +388,8 @@ BufferReady: ({ snapshot, target }) =>
 
 Use the existing `States.matches`, `States.get`, `States.getWithParents`, and
 `States.getSnapshot` helpers for cross-region reads. Parallel transitions
-selected in one microstep receive the same capture. Effectful handlers retain
-that captured value rather than consulting live runtime state.
+selected in one microstep receive the same capture. Synchronous handlers use
+that captured value and cannot consult live runtime state later.
 
 Do not expect `snapshot` in entry, exit, invoke, initializer, history-default,
 or choice contexts. Choice is an important soundness boundary: a startup or
@@ -423,30 +422,25 @@ it through every phase.
 
 ## Planning, actions, raised events, and emissions
 
-A transition may return a target directly or compute it in an Effect:
+A transition returns a target synchronously:
 
 ```ts
-Submit: Effect.fn(function* ({ state, target }) {
-  const service = yield* SaveService
-  const canSave = yield* service.validate(state.draft)
-
-  return canSave ? target.local.Saving(new Saving({ draft: state.draft })) : undefined
-})
+Submit: ({ state, target }) =>
+  state.valid ? target.local.Saving(new Saving({ draft: state.draft })) : undefined
 ```
 
-That Effect runs during planning. External side effects must be staged:
+Closed statechart and actor operations use `enqueue`:
 
 ```ts
-Submit: ({ target }) => Machine.action(writeAuditLog, target.local.Saving(new Saving({})))
+Submit: ({ target }, enqueue) => {
+  enqueue.emit(new SaveRequested({}))
+  return target.local.Saving(new Saving({}))
+}
 ```
 
-`Machine.action(effect)` stages the action and returns `void`.
-`Machine.action(effect, next)` stages the same action and returns `next`, which
-is convenient when the transition does not otherwise need an Effect generator.
-
-The managed runtime executes staged actions before publishing the planned
-state. If an action fails, it retains the previous state and suppresses planned
-emissions.
+For asynchronous validation or persistence, invoke an Effect or child machine
+from the state and handle its typed success or failure event in a later
+transition. This keeps `(state, event) => [nextState, commands]` synchronous.
 
 Plans have a discriminated completion result:
 

examples/platformer/src/machine.ts

@@ -1,5 +1,5 @@
 import { Machine } from "@typeonce/effect-machine"
-import { Effect, Schema } from "effect"
+import { Schema } from "effect"
 
 // Domain schemas are shared by state payloads and the public physics protocol.
 export const Axis = Schema.Literals([-1, 0, 1])
@@ -280,15 +280,14 @@ export const CharacterMachine = Machine.make({
                 on: {
                   JumpPressed: {
                     targets: [],
-                    transition: Effect.fn(function*({ event, runtime }) {
-                      const machine = yield* runtime
+                    transition: ({ event }, enqueue) => {
                       const push = awayFrom(event.wall)
-                      yield* machine.raise(
+                      enqueue.raise(
                         push === 0
                           ? InternalEvent.cases.TryAirJump.make({ at: event.at })
                           : InternalEvent.cases.WallJump.make({ at: event.at, push })
                       )
-                    })
+                    }
                   },
                   Landed: {
                     targets: ["Character.locomotion.Playing.Grounded.Landing"],
@@ -386,11 +385,10 @@ export const CharacterMachine = Machine.make({
                         on: {
                           TryAirJump: {
                             targets: ["Character.locomotion.Playing.Airborne.airJump.AirJumpSpent"],
-                            transition: Effect.fn(function*({ event, runtime, target }) {
-                              const machine = yield* runtime
-                              yield* machine.raise(InternalEvent.cases.DoubleJump.make({ at: event.at }))
+                            transition: ({ event, target }, enqueue) => {
+                              enqueue.raise(InternalEvent.cases.DoubleJump.make({ at: event.at }))
                               return target.local.AirJumpSpent(State.cases.AirJumpSpent.make({}))
-                            })
+                            }
                           }
                         }
                       },

examples/pokemon/src/machine.ts

@@ -10,20 +10,44 @@ class ActiveTeam extends Schema.TaggedClass<ActiveTeam>("ActiveTeam")("ActiveTea
   team: Schema.Array(Pokemon)
 }) {}
 
-export const States = Machine.defineStates({ ActiveTeam })
+class Loading extends Schema.TaggedClass<Loading>("Loading")("Loading", {}) {}
+
+class TeamLoaded extends Schema.TaggedClass<TeamLoaded>("TeamLoaded")("TeamLoaded", {
+  team: Schema.Array(Pokemon)
+}) {}
+
+class TeamLoadFailed extends Schema.TaggedClass<TeamLoadFailed>("TeamLoadFailed")("TeamLoadFailed", {}) {}
+
+class Failed extends Schema.TaggedClass<Failed>("Failed")("Failed", {}) {}
+
+export const States = Machine.defineStates({ Loading, ActiveTeam, Failed })
 
 export const SelectionChild = Machine.child("selection", SelectionMachine)
 export const ReplaceChild = Machine.child("replace", ReplaceMachine)
 
+const LoadTeam = Machine.invokeEffect({
+  id: "load-team",
+  effect: Effect.gen(function*() {
+    const service = yield* PokemonService
+    return yield* service.getRandomTeam()
+  }),
+  onSuccess: (team) => new TeamLoaded({ team }),
+  onFailure: () => new TeamLoadFailed({})
+})
+
 const machine = Machine.make({
   states: States.states,
   events: [ReplaceInTeam],
-  initial: Effect.fn(function*() {
-    const pk = yield* PokemonService
-    const team = yield* pk.getRandomTeam()
-    return States.initial.ActiveTeam(new ActiveTeam({ team }))
-  })
+  internalEvents: [TeamLoaded, TeamLoadFailed],
+  initial: () => States.initial.Loading(new Loading({}))
 }).handle({
+  Loading: {
+    invoke: LoadTeam,
+    on: {
+      TeamLoaded: ({ event, target }) => target.full.ActiveTeam(new ActiveTeam({ team: event.team })),
+      TeamLoadFailed: ({ target }) => target.full.Failed(new Failed({}))
+    }
+  },
   ActiveTeam: {
     invoke: [Machine.invokeMachine({ child: SelectionChild }), Machine.invokeMachine({ child: ReplaceChild })],
     on: {
@@ -32,7 +56,8 @@ const machine = Machine.make({
           new ActiveTeam({ team: state.team.map((pokemon) => (pokemon.id === event.id ? event.pokemon : pokemon)) })
         )
     }
-  }
+  },
+  Failed: {}
 })
 
 const atomRuntime = Atom.runtime(PokemonService.layer)

examples/pokemon/src/machines/replace.ts

@@ -52,8 +52,10 @@ export const ReplaceMachine = Machine.make({
   Replacing: {
     invoke: () => ReplaceWithRandomMachine,
     on: {
-      Replaced: ({ event, target, emit, state }) =>
-        emit(new ReplaceInTeam({ id: state.id, pokemon: event.pokemon })).pipe(Effect.as(target.full.Idle(new Idle())))
+      Replaced: ({ event, target, state }, enqueue) => {
+        enqueue.emit(new ReplaceInTeam({ id: state.id, pokemon: event.pokemon }))
+        return target.full.Idle(new Idle())
+      }
     }
   }
 })

examples/pokemon/src/machines/selection.ts

@@ -110,15 +110,13 @@ export const SelectionMachine = Machine.make({
         states: {
           WithPokemon: {
             on: {
-              ReplacePokemon: ({ event, emit, state, target }) =>
-                emit(new ReplaceInTeam({ id: event.id, pokemon: state.pokemon })).pipe(
-                  Effect.as(
-                    target.full.form(new Form(), (form) =>
-                      form
-                        .search(new Search({ searchText: "" }), (search) => search.NoPokemon(new NoPokemon()))
-                        .selection(new Selection(), (selection) => selection.Unselected(new Unselected())))
-                  )
-                )
+              ReplacePokemon: ({ event, state, target }, enqueue) => {
+                enqueue.emit(new ReplaceInTeam({ id: event.id, pokemon: state.pokemon }))
+                return target.full.form(new Form(), (form) =>
+                  form
+                    .search(new Search({ searchText: "" }), (search) => search.NoPokemon(new NoPokemon()))
+                    .selection(new Selection(), (selection) => selection.Unselected(new Unselected())))
+              }
             }
           },
           Searching: {

perf/types/composition.ts

@@ -42,11 +42,7 @@ const handled = machine.handle({
           Editor: {
             states: {
               Editing: {
-                entry: () =>
-                  Effect.flatMap(
-                    CompositionService,
-                    () => Math.random() > 2 ? Effect.fail(new CompositionFailure()) : Effect.void
-                  )
+                entry: () => {}
               },
               Done: {
                 output: ({ state }) => state.value
@@ -81,8 +77,8 @@ const handled = machine.handle({
   }
 })
 
-type ErrorIsExact = Expect<Equal<Machine.Machine.Error<typeof handled>, CompositionFailure>>
-type ServicesAreExact = Expect<Equal<Machine.Machine.Services<typeof handled>, CompositionService>>
+type ErrorIsExact = Expect<Equal<Machine.Machine.Error<typeof handled>, never>>
+type ServicesAreExact = Expect<Equal<Machine.Machine.Services<typeof handled>, never>>
 type OutputIsExact = Expect<
   Equal<
     Machine.Machine.OutputByIdentifier<typeof States.states, "App.Workspace">,

perf/types/exact-channels-control.ts

@@ -1,5 +1,5 @@
 import { Machine } from "@typeonce/effect-machine"
-import { Context, Data, Effect, Schema } from "effect"
+import { Schema } from "effect"
 
 export const Idle = Schema.TaggedStruct("Idle", { value: Schema.Number })
 export const Done = Schema.TaggedStruct("Done", { value: Schema.String })
@@ -8,9 +8,6 @@ export const Loaded = Schema.TaggedStruct("Loaded", { value: Schema.String })
 export const Notice = Schema.TaggedStruct("Notice", { value: Schema.String })
 export const Input = Schema.Struct({ seed: Schema.Number })
 
-export class InitialService extends Context.Service<InitialService, string>()("perf/channels/InitialService") {}
-export class InitialFailure extends Data.TaggedError("InitialFailure")<{}> {}
-
 export const States = Machine.defineStates({
   Idle,
   Done: {
@@ -26,9 +23,5 @@ export const machine = Machine.make({
   internalEvents: [Loaded],
   emits: [Notice],
   input: Input,
-  initial: (input) =>
-    Effect.flatMap(InitialService, () =>
-      input.seed < 0
-        ? Effect.fail(new InitialFailure())
-        : Effect.succeed(States.initial.Idle(Idle.make({ value: input.seed }))))
+  initial: (input) => States.initial.Idle(Idle.make({ value: input.seed }))
 })

perf/types/exact-channels.ts

@@ -1,39 +1,21 @@
 import { Machine } from "@typeonce/effect-machine"
-import { Context, Data, Effect } from "effect"
-import {
-  Done,
-  InitialFailure,
-  InitialService,
-  Loaded,
-  machine,
-  Notice,
-  Start,
-  States
-} from "./exact-channels-control.js"
+import { Effect } from "effect"
+import { Done, Loaded, machine, Notice, Start, States } from "./exact-channels-control.js"
 
 type Equal<Left, Right> = (<Type>() => Type extends Left ? 1 : 2) extends (<Type>() => Type extends Right ? 1 : 2) ?
   true :
   false
 type Expect<Value extends true> = Value
 type IsAny<Value> = 0 extends 1 & Value ? true : false
 
-export class RuntimeService extends Context.Service<RuntimeService, string>()("perf/channels/RuntimeService") {}
-export class ActionService extends Context.Service<ActionService, string>()("perf/channels/ActionService") {}
-export class RuntimeFailure extends Data.TaggedError("RuntimeFailure")<{}> {}
-export class ActionFailure extends Data.TaggedError("ActionFailure")<{}> {}
-
 const complete = machine.handle({
   Idle: {
-    entry: () =>
-      Machine.action(
-        Effect.flatMap(ActionService, () => Math.random() > 2 ? Effect.fail(new ActionFailure()) : Effect.void)
-      ),
+    entry: () => {},
     on: {
-      Start: ({ event, target }) =>
-        Effect.flatMap(RuntimeService, () =>
-          Math.random() > 2
-            ? Effect.fail(new RuntimeFailure())
-            : Effect.succeed(target.full.Done(Done.make({ value: event.value })))),
+      Start: ({ event, target }, enqueue) => {
+        enqueue.emit(Notice.make({ value: event.value }))
+        return target.full.Done(Done.make({ value: event.value }))
+      },
       Loaded: ({ event, target }) => target.full.Done(Done.make({ value: event.value }))
     }
   },
@@ -46,15 +28,10 @@ type InputIsExact = Expect<Equal<Machine.Machine.Input<typeof complete>["Type"],
 type InputEventIsExact = Expect<Equal<Machine.Machine.InputEvent<typeof complete>, typeof Start.Type>>
 type EventIsExact = Expect<Equal<Machine.Machine.Event<typeof complete>, typeof Start.Type | typeof Loaded.Type>>
 type EmitIsExact = Expect<Equal<Machine.Machine.Emit<typeof complete>, typeof Notice.Type>>
-type InitialErrorIsExact = Expect<Equal<Machine.Machine.InitialError<typeof complete>, InitialFailure>>
-type InitialServicesAreExact = Expect<Equal<Machine.Machine.InitialServices<typeof complete>, InitialService>>
-type ErrorIsExact = Expect<Equal<Machine.Machine.Error<typeof complete>, RuntimeFailure>>
-type ServicesAreExact = Expect<
-  Equal<
-    Machine.Machine.Services<typeof complete>,
-    RuntimeService | Machine.ActionRequirement<ActionFailure, ActionService>
-  >
->
+type InitialErrorIsExact = Expect<Equal<Machine.Machine.InitialError<typeof complete>, never>>
+type InitialServicesAreExact = Expect<Equal<Machine.Machine.InitialServices<typeof complete>, never>>
+type ErrorIsExact = Expect<Equal<Machine.Machine.Error<typeof complete>, never>>
+type ServicesAreExact = Expect<Equal<Machine.Machine.Services<typeof complete>, never>>
 type OutputIsExact = Expect<Equal<Machine.Machine.Output<typeof complete>, string>>
 type OutputStatesAreExact = Expect<Equal<Machine.Machine.OutputStates<typeof complete>, "Done">>
 type ErrorIsNotAny = Expect<Equal<IsAny<Machine.Machine.Error<typeof complete>>, false>>