@typeonce/effect-machine 0.10.0 → 0.12.0

package/dist/unstable/reactivity/AtomMachine.js

@@ -20,8 +20,10 @@ export { NotReadyError } from "../../internal/machine/atom.js";
 export { ChildNotActiveError } from "../../internal/machine/atom.js";
 const ExternalRequirementsTypeId = "~effect/reactivity/AtomMachine/ExternalRequirements";
 /**
- * Observes ephemeral notifications from the actor owned by a machine atom.
- * The stream requires an `AtomRegistry` and does not replay earlier emissions.
+ * Observes ephemeral notifications from the running machine owned by a machine
+ * atom. When this stream activates a fresh bridge, it subscribes before machine
+ * initialization and observes initial-entry emissions. It never replays
+ * emissions from a machine that was already running.
  *
  * @category getters
  * @since 0.10.0

package/dist/unstable/reactivity/AtomMachine.js.map

@@ -1 +1 @@
-{"version":3,"file":"AtomMachine.js","sourceRoot":"","sources":["../../../src/unstable/reactivity/AtomMachine.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,OAAO,KAAK,QAAQ,MAAM,gCAAgC,CAAA;AAK1D;;;;;GAKG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAA;AAE9D;;;;;GAKG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAA;AAMpE,MAAM,0BAA0B,GAAG,qDAAqD,CAAA;AAoIxF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,SAAS,GAE+C,QAAQ,CAAC,SAAS,CAAA;AAEvF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAMvB,QAAQ,CAAC,cAAc,CAAA;AAkJ3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,CAAC,MAAM,MAAM,GASf,QAAQ,CAAC,MAAM,CAAA;AAEnB;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,cAAc,GASvB,QAAQ,CAAC,cAAc,CAAA;AAE3B;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,WAAW,GASpB,QAAQ,CAAC,WAAW,CAAA;AAExB;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAS5B,QAAQ,CAAC,mBAAmB,CAAA;AAEhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,CAAC,MAAM,OAAO,GAUmD,QAAQ,CAAC,OAAO,CAAA;AAEvF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,YAAY,GAMrB,QAAQ,CAAC,YAAY,CAAA;AAEzB,MAAM,uBAAuB,GAAG,kDAAkD,CAAA;AAgHlF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,MAAM,IAAI,GAoDb,QAAQ,CAAC,IAAI,CAAA;AAEjB;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,MAAM,GAQf,QAAQ,CAAC,MAAM,CAAA;AAEnB;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,IAAI,GAEoB,QAAQ,CAAC,IAAI,CAAA"}
+{"version":3,"file":"AtomMachine.js","sourceRoot":"","sources":["../../../src/unstable/reactivity/AtomMachine.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,OAAO,KAAK,QAAQ,MAAM,gCAAgC,CAAA;AAK1D;;;;;GAKG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAA;AAE9D;;;;;GAKG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAA;AAMpE,MAAM,0BAA0B,GAAG,qDAAqD,CAAA;AAoIxF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,SAAS,GAE+C,QAAQ,CAAC,SAAS,CAAA;AAEvF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAMvB,QAAQ,CAAC,cAAc,CAAA;AAkJ3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,CAAC,MAAM,MAAM,GASf,QAAQ,CAAC,MAAM,CAAA;AAEnB;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,cAAc,GASvB,QAAQ,CAAC,cAAc,CAAA;AAE3B;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,WAAW,GASpB,QAAQ,CAAC,WAAW,CAAA;AAExB;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAS5B,QAAQ,CAAC,mBAAmB,CAAA;AAEhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,CAAC,MAAM,OAAO,GAUmD,QAAQ,CAAC,OAAO,CAAA;AAEvF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,YAAY,GAMrB,QAAQ,CAAC,YAAY,CAAA;AAEzB,MAAM,uBAAuB,GAAG,kDAAkD,CAAA;AAgHlF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,MAAM,IAAI,GAoDb,QAAQ,CAAC,IAAI,CAAA;AAEjB;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,MAAM,GAQf,QAAQ,CAAC,MAAM,CAAA;AAEnB;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,IAAI,GAEoB,QAAQ,CAAC,IAAI,CAAA"}

package/docs/agent-guide.md

@@ -4,6 +4,21 @@ This is the model-facing reference for the currently published
 `@typeonce/effect-machine` API. Prefer these patterns over reconstructing the API
 from its internal implementation.
 
+## Design priorities
+
+Prefer, in order: compile-time type safety, explicit and opinionated semantics,
+readable and concise machine models, and alignment with Effect core. Convenience
+must come from builders and inference rather than ambiguous omissions or weaker
+contracts. The package is pre-1.0, so improve or remove an existing API when a
+clearer long-term design replaces it; do not preserve an inferior design with
+aliases by default.
+
+Keep the core machine model local. Before adding a public name or capability,
+check Effect's existing modules and especially Cluster. Distributed identity,
+placement, discovery, transport, routing, delivery, sharding, and remote
+lifecycle belong to Cluster; expose integration through an explicit adapter
+instead of creating a similar local abstraction with different semantics.
+
 ## Public imports
 
 ```ts
@@ -88,7 +103,7 @@ the deferred constructors preserve that identity after decoding.
 - Reuse an exported child descriptor for inline invocation, `sendTo`, and child
   lookup. Independently constructed descriptors are equivalent only when both
   their id and machine identity match.
-- `events` is the public actor-input protocol. `internalEvents` contains
+- `events` is the public machine-input protocol. `internalEvents` contains
   machine-local raised events. `parentEvents` describes the public events a
   child may send to its owner. `emittedEvents` describes outward ephemeral
   notifications and is never delivered implicitly to a parent.
@@ -105,15 +120,16 @@ its extra control is required:
   `AtomMachine.resume(machine, snapshot)` for service-free machines.
 - 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 context and source
-  channels across sibling lifecycle handlers. Use a direct object only when its
-  lifecycle handlers do not need source-derived context.
+  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.
 - 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
   address explicitly.
 - Use the callback's `enqueue` argument for `raise`, `emit`, `sendTo`, and
-  `stop`. These operations record closed actor commands and do not run Effects.
+  `stop`. These operations record closed machine commands and do not run Effects.
 
 ## Atomic, compound, parallel, and history states
 
@@ -320,7 +336,7 @@ the default.
 The machine's readiness type tracks missing defaults and shallow initializers.
 History is an overwriteable register, not a stack: restoration does not consume
 it, and the next parent exit replaces it. Entry actions and invokes run again;
-prior effects, actors, and timers are not rewound.
+prior effects, machine instances, and timers are not rewound.
 
 ## Choosing a target
 
@@ -406,7 +422,7 @@ only schema-backed paths; use `matches` or `getSnapshot` for any active path.
 `context.containingState` is the immediate typed state value (`undefined` at a
 root or when that state is schema-less). `context.ancestors` contains only
 valued structural ancestors. This is separate from `context.parent`, which is
-the owning actor reference or `undefined` for a root actor. Use full state paths
+the owning machine target or `undefined` for a root machine. Use full state paths
 when another ancestor value is needed:
 
 ```ts
@@ -490,7 +506,7 @@ are an upper bound on concrete destinations, not an exhaustive result set.
 `reenter: true` remains meaningful with `target.none()`: the source exits and
 enters again while its logical configuration is retained.
 
-Closed statechart and actor operations use `enqueue`:
+Closed statechart and machine operations use `enqueue`:
 
 ```ts
 Submit: ({ target }, enqueue) => {
@@ -499,7 +515,7 @@ Submit: ({ target }, enqueue) => {
 }
 ```
 
-Declare emission constructors separately from actor inputs:
+Declare emission constructors separately from machine inputs:
 
 ```ts
 const Emissions = Machine.emittedEvents(SaveRequested, AuditRecorded)
@@ -513,12 +529,24 @@ const definition = Machine.make({
 ```
 
 `enqueue.raise(...)` is a same-macrostep input to self. `enqueue.sendTo(...)`
-targets an actor mailbox and is processed later. `enqueue.emit(...)` is neither:
+targets a machine mailbox and is processed later. `enqueue.emit(...)` is neither:
 it publishes a one-off outward notification. Observe it with
-`ref.emissions`, a hot non-replayed `Stream` that completes with the actor.
+`ref.emissions`, a hot non-replayed `Stream` that completes with the machine.
 `ref.changes` is stateful and begins with the current lifecycle snapshot.
-Startup emissions occur before `Machine.start` returns and therefore are not
-visible through the returned ref; use state for facts that must be retained.
+Use `Machine.prepare(machine)` to obtain `changes` and `emissions` before
+initialization. Subscribe to the desired stream and then evaluate
+`prepared.start`. `Machine.start(machine)` remains the one-step convenience
+when startup observation is unnecessary. Emissions are still never retained or
+replayed; state remains the representation for facts that must be retained.
+
+```ts
+const prepared = yield* Machine.prepare(machine)
+yield* prepared.emissions.pipe(
+  Stream.runForEach(handleEmission),
+  Effect.forkScoped({ startImmediately: true })
+)
+const ref = yield* prepared.start
+```
 
 For child-to-parent input, export a public builder protocol and reuse it at both
 composition boundaries:
@@ -551,10 +579,12 @@ const parent = Machine.make({
 Invoking the child under a parent that lacks any required `parentEvents` case
 is a type error. Within child handlers, `parent` accepts only that protocol.
 The same child may run as a root, where `parent` is `undefined`. `self` accepts
-the machine's public inputs. Neither actor reference is a structural state
-value; use `containingState` and `ancestors` for statechart ancestry.
+the machine's public inputs. Both are minimal `MachineTarget<Event>` values,
+provided by the shared `MachineReferences<InputEvents, ParentEvents>` handler
+context. Neither machine target is a structural state value; use
+`containingState` and `ancestors` for statechart ancestry.
 
-Atom-backed actors retain the same transient semantics. Use
+Atom-backed machines retain the same transient semantics. Use
 `AtomMachine.emissions(machineAtom)` for a root and
 `AtomMachine.childEmissions(childAtom)` for the currently active child. Both
 return streams requiring the corresponding `AtomRegistry`; emissions are not
@@ -682,6 +712,33 @@ 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:
+
+```ts
+const definition = Machine.make({
+  events: Commands,
+  internalEvents: InternalEvents,
+  parentEvents: ParentEvents,
+  // ...
+})
+
+const machine = definition.handle({
+  Saving: {
+    invoke: definition.invoke({
+      id: "notify-parent",
+      effect: ({ parent }) =>
+        parent === undefined
+          ? Effect.void
+          : parent.send(ParentEvents.SaveStarted()),
+      onDone: ({ target }) => target.none(),
+      onFailure: ({ target }) => target.none()
+    })
+  }
+})
+```
+
 A direct `invoke: { ... }` object remains available when lifecycle handlers do
 not need source-derived context.
 
@@ -729,9 +786,11 @@ parentRef.child(Editor)
 parentAtom.child(Editor)
 ```
 
-Child emissions are delivered through the parent's internal protocol.
-`onSnapshot`, `onDone`, and `onFailure` are direct parent transitions. Invoked
-child IDs must be unique while simultaneously active.
+Child emissions remain on the child's hot `emissions` stream; they are never
+delivered implicitly to the parent. A child sends an input explicitly with
+`enqueue.sendTo(parent, ParentEvents.Example())`. `onSnapshot`, `onDone`, and
+`onFailure` are direct parent transitions. Invoked child IDs must be unique
+while simultaneously active.
 
 Descriptors with the same id and machine identity address the same child, even
 when independently constructed. The descriptor objects themselves are not

package/package.json

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