Fix invoke owner protocol inference (#134)

Author: SandroMaglione

.changeset/bright-invokes-listen.md

@@ -0,0 +1,7 @@
+---
+"@typeonce/effect-machine": patch
+---
+
+Fix `Machine.invoke(...)` inside `.handle(...)` so invocation sources and lifecycle handlers receive the owning machine's typed `self` and `parent` protocols.
+
+Event protocol examples now pass tagged unions directly to `Machine.events`, `Machine.internalEvents`, and `Machine.emittedEvents`, avoiding throwaway schema bindings.

README.md

@@ -53,14 +53,14 @@ const State = Schema.TaggedUnion({
   Running: { count: Schema.Number }
 })
 
-const Event = Schema.TaggedUnion({
-  Start: {},
-  Increment: {},
-  Stop: {}
-})
-
 const States = Machine.defineStates(State.cases)
-const CounterEvent = Machine.events(Event)
+const CounterEvent = Machine.events(
+  Schema.TaggedUnion({
+    Start: {},
+    Increment: {},
+    Stop: {}
+  })
+)
 
 const CounterDefinition = Machine.make({
   id: "Counter",
@@ -110,13 +110,15 @@ const program = Effect.gen(function*() {
 
 Use this order to preserve inference and keep boundaries explicit:
 
-1. Define domain, state, public-event, internal-event, and emitted-event schemas.
-2. Declare topology with `Machine.defineStates`.
-3. Create public and internal event descriptors with `Machine.events` and
-   `Machine.internalEvents`.
-4. Create the machine protocol and initializer with `Machine.make`.
-5. Implement every active state with `.handle(...)`.
-6. Add runtime, Atom, testing, or cluster adapters at the application boundary.
+1. Define domain schemas used by state and by shared event fields.
+2. Declare topology with `Machine.defineStates`, naming a tagged state union
+   when its `.cases` are reused.
+3. Create event descriptors with `Machine.events`, `Machine.internalEvents`,
+   and `Machine.emittedEvents`, passing tagged unions or tagged classes directly.
+4. Create the machine and implement every active state with
+   `Machine.make({...}).handle({...})`.
+5. Add child descriptors, then runtime, Atom, testing, or cluster adapters at
+   the application boundary.
 
 ### Construct state through builders
 
@@ -178,19 +180,21 @@ belong in `internalEvents`. Ephemeral outward notifications have their own
 `emittedEvents` protocol:
 
 ```ts
-const Command = Schema.TaggedUnion({ Save: {} })
-const Internal = Schema.TaggedUnion({
-  Saved: { id: Schema.String },
-  SaveFailed: { message: Schema.String }
-})
-const Emitted = Schema.TaggedUnion({
-  SaveObserved: { id: Schema.String }
-})
-
-export const CommandEvent = Machine.events(Command)
+export const CommandEvent = Machine.events(
+  Schema.TaggedUnion({ Save: {} })
+)
 export type PublicCommandEvent = Machine.EventOf<typeof CommandEvent>
-const InternalEvent = Machine.internalEvents(Internal)
-const Emissions = Machine.emittedEvents(Emitted)
+const InternalEvent = Machine.internalEvents(
+  Schema.TaggedUnion({
+    Saved: { id: Schema.String },
+    SaveFailed: { message: Schema.String }
+  })
+)
+const Emissions = Machine.emittedEvents(
+  Schema.TaggedUnion({
+    SaveObserved: { id: Schema.String }
+  })
+)
 
 const definition = Machine.make({
   states: States.states,
@@ -446,31 +450,31 @@ invoke: Machine.invoke({
 })
 ```
 
-The standalone `Machine.invoke(...)` constructor does not know the owning
-definition, so its `self` and `parent` references are non-sendable. When an
-invocation callback sends through either reference, construct it through the
-owning definition so those references use its exact public input and
-`parentEvents` protocols:
+Inside `.handle(...)`, `Machine.invoke(...)` receives the owning machine's
+public input and `parentEvents` protocols contextually. Its source and lifecycle
+callbacks can send through `self` and `parent` while retaining the invoked
+Effect's output and error inference:
 
 ```ts
-const definition = Machine.make({
+const machine = Machine.make({
   events: Commands,
   internalEvents: InternalEvents,
   parentEvents: ParentEvents
   // ...
-})
-
-const machine = definition.handle({
+}).handle({
   Saving: {
-    invoke: definition.invoke({
+    invoke: Machine.invoke({
       id: "notify-parent",
-      effect: ({ parent }) =>
-        parent === undefined
-          ? Effect.void
-          : parent.send(ParentEvents.SaveStarted()),
+      effect: () => saveDocument,
       onDone: Machine.transition({
         target: (to) => to.none(),
-        resolve: () => undefined
+        resolve: ({ parent, self }, enqueue) => {
+          enqueue.sendTo(self, Commands.Save())
+          if (parent !== undefined) {
+            enqueue.sendTo(parent, ParentEvents.ChildFinished({ id: "job-1" }))
+          }
+          return undefined
+        }
       }),
       onFailure: Machine.transition({
         target: (to) => to.none(),
@@ -481,6 +485,9 @@ const machine = definition.handle({
 })
 ```
 
+The machine-bound `definition.invoke(...)` form remains equivalent when a
+definition is already named; it is not required for `self` or `parent` typing.
+
 A direct `invoke: { ... }` object is also supported when its lifecycle handlers
 do not need source-derived context. Reuse one exported
 `Machine.child(id, machine)` descriptor for invocation, `sendTo`, and child

docs/agent-guide.md

@@ -35,15 +35,13 @@ currently coupled to the exact Effect peer version listed in its `package.json`.
 Use this order so inference has all schemas available when handlers are
 declared:
 
-1. Domain schemas used by state and event fields.
-2. Tagged schemas for states that own data.
-3. Tagged public-event, internal-event, parent-event, and emitted-event schemas.
-4. `Machine.defineStates`.
-5. `Machine.make`, including input, `events`, `internalEvents`, `parentEvents`,
-   `emittedEvents`, and the initial function.
-6. One or more `.handle(...)` calls.
-7. Child descriptors.
-8. Runtime, Atom, or Cluster adapters.
+1. Domain schemas used by state, and by event fields when they are shared.
+2. `Machine.defineStates`, using a tagged state union and `.cases` when state
+   schemas need to be reused.
+3. `Machine.events`, `Machine.internalEvents`, `Machine.emittedEvents`, and
+   `parentEvents`; pass `Schema.TaggedUnion({...})` or tagged classes directly.
+4. `Machine.make({...}).handle({...})`.
+5. Child descriptors, then runtime, Atom, or Cluster adapters.
 
 `Schema.TaggedUnion` avoids one class declaration per case:
 
@@ -54,22 +52,23 @@ const State = Schema.TaggedUnion({
   Failed: { message: Schema.String }
 })
 
-const Event = Schema.TaggedUnion({
-  Save: {}
-})
-
-const InternalEvent = Schema.TaggedUnion({
-  Saved: { id: Schema.String },
-  SaveFailed: { message: Schema.String }
-})
-
 const States = Machine.defineStates(State.cases)
-const Events = Machine.events(Event)
-const InternalEvents = Machine.internalEvents(InternalEvent)
+export const Event = Machine.events(
+  Schema.TaggedUnion({
+    Save: {}
+  })
+)
+export const Internal = Machine.internalEvents(
+  Schema.TaggedUnion({
+    Saved: { id: Schema.String },
+    SaveFailed: { message: Schema.String }
+  })
+)
 ```
 
-Pass these descriptors to `Machine.make` and export `Events` instead of the raw
-event schema. Construct new state values through the target or initial
+Pass these descriptors to `Machine.make`; the event descriptor is the public
+handle, so do not introduce a tagged-union binding used only by an event helper.
+Construct new state values through the target or initial
 builder's `.from(...)` method. Both event constructors and state `.from(...)`
 defer schema construction until planning, so validation failures remain typed
 machine errors. Use
@@ -121,9 +120,9 @@ its extra control is required:
 - Use one invocation object: `effect` for one-shot work, `after` for a timer,
   `logic` for reusable process logic, and `child` for a complete child
   statechart. `Machine.invoke({...})` preserves owner state and source channels
-  across sibling lifecycle handlers. Use `definition.invoke({...})` when a
-  callback uses `self` or `parent`; the bound constructor preserves the
-  definition's exact public input and `parentEvents` protocols.
+  across sibling lifecycle handlers. Inside `.handle(...)`, `self` and `parent`
+  use the owning definition's exact public input and `parentEvents` protocols.
+  The bound `definition.invoke({...})` form is equivalent, not required.
 - Use `Machine.child(id, machine)` for a complete statechart descriptor and
   `Machine.childAddress<Event>(id)` for a low-level process address. A logic
   invocation is addressable only when `Machine.invoke` receives that
@@ -764,8 +763,17 @@ an event for the parent. Both operations validate their schemas.
 union handled inside the statechart:
 
 ```ts
-const Events = Machine.events(Event)
-const InternalEvents = Machine.internalEvents(InternalEvent)
+const Events = Machine.events(
+  Schema.TaggedUnion({
+    Save: {}
+  })
+)
+const InternalEvents = Machine.internalEvents(
+  Schema.TaggedUnion({
+    Saved: { id: Schema.String },
+    SaveFailed: { message: Schema.String }
+  })
+)
 
 const definition = Machine.make({
   states: States.states,
@@ -871,29 +879,30 @@ invoke: Machine.invoke({
 })
 ```
 
-The standalone constructor cannot know the owning machine's input protocols,
-so its `self` and `parent` references are non-sendable. When a source sends
-through either reference, use the owning definition's bound constructor:
+Inside `.handle(...)`, the constructor receives the owning machine's public
+input and `parentEvents` protocols contextually. Sources and lifecycle handlers
+can send through `self` and `parent` without naming the definition:
 
 ```ts
-const definition = Machine.make({
+const machine = Machine.make({
   events: Commands,
   internalEvents: InternalEvents,
   parentEvents: ParentEvents,
   // ...
-})
-
-const machine = definition.handle({
+}).handle({
   Saving: {
-    invoke: definition.invoke({
+    invoke: Machine.invoke({
       id: "notify-parent",
-      effect: ({ parent }) =>
-        parent === undefined
-          ? Effect.void
-          : parent.send(ParentEvents.SaveStarted()),
+      effect: () => saveDocument,
       onDone: Machine.transition({
         target: (to) => to.none(),
-        resolve: () => undefined
+        resolve: ({ parent, self }, enqueue) => {
+          enqueue.sendTo(self, Commands.Save())
+          if (parent !== undefined) {
+            enqueue.sendTo(parent, ParentEvents.ChildFinished({ id: "job-1" }))
+          }
+          return undefined
+        }
       }),
       onFailure: Machine.transition({
         target: (to) => to.none(),
@@ -904,8 +913,9 @@ const machine = definition.handle({
 })
 ```
 
-A direct `invoke: { ... }` object remains available when lifecycle handlers do
-not need source-derived context.
+The machine-bound `definition.invoke(...)` form remains equivalent when the
+definition is already named. A direct `invoke: { ... }` object remains available
+when lifecycle handlers do not need source-derived context.
 
 A cancellable timer uses the same object:
 

examples/platformer/src/machine.ts

@@ -18,29 +18,30 @@ const State = Schema.TaggedUnion({
 })
 
 // Inputs and physics facts are one runtime-decoded, statically typed protocol.
-const Event = Schema.TaggedUnion({
-  Move: { axis: Axis, at: Schema.Number },
-  JumpPressed: { at: Schema.Number, y: Schema.Number, wall: Axis },
-  WallContact: { wall: Axis },
-  DownPressed: { at: Schema.Number },
-  DownReleased: { axis: Axis, at: Schema.Number },
-  ApexReached: { y: Schema.Number },
-  Landed: { impact: Schema.Number, axis: Axis, at: Schema.Number },
-  Pause: { at: Schema.Number },
-  Resume: {},
-  Reset: {}
-})
-
-const InternalEvent = Schema.TaggedUnion({
-  LandingSettled: {},
-  AirJumpUnlocked: {},
-  TryAirJump: { at: Schema.Number },
-  DoubleJump: { at: Schema.Number },
-  WallJump: { at: Schema.Number, push: Axis }
-})
+export const CharacterEvents = Machine.events(
+  Schema.TaggedUnion({
+    Move: { axis: Axis, at: Schema.Number },
+    JumpPressed: { at: Schema.Number, y: Schema.Number, wall: Axis },
+    WallContact: { wall: Axis },
+    DownPressed: { at: Schema.Number },
+    DownReleased: { axis: Axis, at: Schema.Number },
+    ApexReached: { y: Schema.Number },
+    Landed: { impact: Schema.Number, axis: Axis, at: Schema.Number },
+    Pause: { at: Schema.Number },
+    Resume: {},
+    Reset: {}
+  })
+)
 
-export const CharacterEvents = Machine.events(Event)
-const InternalEvents = Machine.internalEvents(InternalEvent)
+const InternalEvents = Machine.internalEvents(
+  Schema.TaggedUnion({
+    LandingSettled: {},
+    AirJumpUnlocked: {},
+    TryAirJump: { at: Schema.Number },
+    DoubleJump: { at: Schema.Number },
+    WallJump: { at: Schema.Number, push: Axis }
+  })
+)
 
 const awayFrom = (wall: Axis): Axis => (wall === -1 ? 1 : wall === 1 ? -1 : 0)
 
@@ -114,7 +115,7 @@ export const CharacterStates = Machine.defineStates({
   }
 })
 
-const definition = Machine.make({
+export const CharacterMachine = Machine.make({
   id: "PlatformerCharacter",
   states: CharacterStates.states,
   events: CharacterEvents,
@@ -131,9 +132,7 @@ const definition = Machine.make({
           .contact.from((contact) => contact.NoWall.from())
       )
   }
-})
-
-export const CharacterMachine = definition.handle({
+}).handle({
   Character: {
     on: {
       Reset: Machine.transition({
@@ -261,7 +260,7 @@ export const CharacterMachine = definition.handle({
                     }
                   },
                   Landing: {
-                    invoke: definition.invoke({
+                    invoke: Machine.invoke({
                       id: "landing-settle",
                       after: "140 millis",
                       onDone: Machine.transition({