@typeonce/effect-machine 0.14.1 → 0.16.0

package/src/internal/machine/runtime.ts

@@ -355,6 +355,9 @@ interface ProcessAddress<in Event> {
     source: Inspection.Subject | undefined,
     causedBy: Inspection.Causation | undefined
   ) => Effect.Effect<void, StoppedError>
+  readonly [acknowledgedSend]?: (
+    event: Event
+  ) => Effect.Effect<AcknowledgedDelivery<unknown>, unknown | StoppedError>
 }
 
 const isMachineTarget = (value: unknown): value is MachineTarget<unknown> =>
@@ -843,7 +846,10 @@ class OwnedChildRuntimeImpl implements OwnedChildRuntime {
     private readonly registry: ChildRegistry,
     private readonly self: ProcessAddress<any>,
     private readonly runtime: ProcessRuntime,
-    private readonly services?: Context.Context<any>
+    private readonly services?: Context.Context<any>,
+    private readonly sendAcknowledged?: (
+      event: unknown
+    ) => Effect.Effect<AcknowledgedDelivery<unknown>, unknown | StoppedError>
   ) {}
 
   private has(key: string): boolean {
@@ -886,7 +892,15 @@ class OwnedChildRuntimeImpl implements OwnedChildRuntime {
         ...this.self,
         send: (event) => options.sendParent(isCurrent, event),
         sendInspected: (event, source, causedBy) =>
-          isCurrent() ? sendMachineTarget(this.self, event, source, causedBy) : Effect.void
+          isCurrent() ? sendMachineTarget(this.self, event, source, causedBy) : Effect.void,
+        ...(this.sendAcknowledged === undefined
+          ? undefined
+          : {
+            [acknowledgedSend]: (event: unknown) =>
+              isCurrent()
+                ? this.sendAcknowledged!(event)
+                : Effect.interrupt
+          })
       }
       const startOptions: StartInternalOptions = {
         detached: true,
@@ -1048,7 +1062,10 @@ const childlessRuntime: ChildRuntime = {
 const makeChildRuntimeSync = (
   self: ProcessAddress<any>,
   runtime: ProcessRuntime,
-  services?: Context.Context<any>
+  services?: Context.Context<any>,
+  sendAcknowledged?: (
+    event: unknown
+  ) => Effect.Effect<AcknowledgedDelivery<unknown>, unknown | StoppedError>
 ): ChildRuntime => {
   // Child-registry decisions are synchronous and every access below runs in
   // one Effect.sync / Effect.suspend step. Keep the unobserved representation
@@ -1290,15 +1307,18 @@ const makeChildRuntimeSync = (
     changes,
     sendTo,
     stop,
-    owned: new OwnedChildRuntimeImpl(registry, self, runtime, services)
+    owned: new OwnedChildRuntimeImpl(registry, self, runtime, services, sendAcknowledged)
   }
 }
 
 const makeChildRuntime = (
   self: ProcessAddress<any>,
   runtime: ProcessRuntime,
-  services?: Context.Context<any>
-): Effect.Effect<ChildRuntime> => Effect.sync(() => makeChildRuntimeSync(self, runtime, services))
+  services?: Context.Context<any>,
+  sendAcknowledged?: (
+    event: unknown
+  ) => Effect.Effect<AcknowledgedDelivery<unknown>, unknown | StoppedError>
+): Effect.Effect<ChildRuntime> => Effect.sync(() => makeChildRuntimeSync(self, runtime, services, sendAcknowledged))
 
 // `Machine.logic` permits an arbitrary Effect program, including programs that
 // suspend or supervise their own fibers. Keep its two-fiber worker/supervisor
@@ -1376,6 +1396,23 @@ const startGenericInternal: <
         Effect.tap(() => Effect.sync(() => publishInspectedSent(inspector, subject!, message)))
       )
     })
+  const sendAcknowledged:
+    | ((event: Event) => Effect.Effect<AcknowledgedDelivery<State>, Error | StoppedError>)
+    | undefined = logic.execution?._tag !== "Compiled"
+      ? undefined
+      : (event) =>
+        Effect.uninterruptibleMask((restore) =>
+          Deferred.make<AcknowledgedDelivery<unknown>, unknown>().pipe(
+            Effect.flatMap((deferred) => {
+              const offered = inspector === undefined
+                ? offerDirect({ [AcknowledgedMessageTypeId]: true as const, event, deferred })
+                : offerInspected!(event, undefined, undefined, deferred)
+              return offered.pipe(Effect.andThen(restore(Deferred.await(deferred))))
+            }),
+            Effect.map((delivery) => delivery as AcknowledgedDelivery<State>)
+          )
+        ) as Effect.Effect<AcknowledgedDelivery<State>, Error | StoppedError>
+
   const self: ProcessAddress<Event> = {
     id,
     sessionId,
@@ -1396,22 +1433,6 @@ const startGenericInternal: <
       ? undefined
       : { inspectionSubject: subject!, sendInspected: offerInspected! })
   }
-  const sendAcknowledged:
-    | ((event: Event) => Effect.Effect<AcknowledgedDelivery<State>, Error | StoppedError>)
-    | undefined = logic.execution?._tag !== "Compiled"
-      ? undefined
-      : (event) =>
-        Effect.uninterruptibleMask((restore) =>
-          Deferred.make<AcknowledgedDelivery<unknown>, unknown>().pipe(
-            Effect.flatMap((deferred) => {
-              const offered = inspector === undefined
-                ? offerDirect({ [AcknowledgedMessageTypeId]: true as const, event, deferred })
-                : offerInspected!(event, undefined, undefined, deferred)
-              return offered.pipe(Effect.andThen(restore(Deferred.await(deferred))))
-            }),
-            Effect.map((delivery) => delivery as AcknowledgedDelivery<State>)
-          )
-        ) as Effect.Effect<AcknowledgedDelivery<State>, Error | StoppedError>
 
   let {
     changes: childChanges,
@@ -1431,7 +1452,12 @@ const startGenericInternal: <
       sendTo,
       spawn,
       stop: stopChild
-    } = yield* makeChildRuntime(self, runtime))
+    } = yield* makeChildRuntime(
+      self,
+      runtime,
+      undefined,
+      sendAcknowledged === undefined ? undefined : (event) => sendAcknowledged(event as Event)
+    ))
   }
   const cleanupStartupFailure = <A, E>(exit: Exit.Exit<A, E>): Effect.Effect<void> => {
     if (Exit.isSuccess(exit)) return Effect.void
@@ -2227,7 +2253,12 @@ class CompiledProcess implements MachineRef<any, any, any, any> {
   initializeCompiledSync(): Effect.Effect<MachineRef<any, any, any, any>, unknown> {
     this.publishCreated()
     if (!this.execution.childless) {
-      this.childRuntime = makeChildRuntimeSync(this.address, this.options.runtime, this.services)
+      this.childRuntime = makeChildRuntimeSync(
+        this.address,
+        this.options.runtime,
+        this.services,
+        (event) => this.sendAcknowledgedEffect(event)
+      )
     }
     const parent = this.options.parent
     const sendParent = this.options.sendParent ?? (parent === undefined
@@ -2304,7 +2335,12 @@ class CompiledProcess implements MachineRef<any, any, any, any> {
     return Effect.gen(function*() {
       self.publishCreated()
       if (!self.execution.childless) {
-        self.childRuntime = yield* makeChildRuntime(self.address, self.options.runtime, self.services)
+        self.childRuntime = yield* makeChildRuntime(
+          self.address,
+          self.options.runtime,
+          self.services,
+          (event) => self.sendAcknowledgedEffect(event)
+        )
       }
       const parent = self.options.parent
       const sendParent = self.options.sendParent ?? (parent === undefined

package/src/internal/machine/stateDefinition.ts

@@ -18,7 +18,7 @@ export type AllowedStateNodeProperty<Kind extends StateNodeKind> = (typeof State
 
 export type AllowedPseudoStateAnnotationProperty = (typeof PseudoStateAnnotationProperties)[number]
 
-export type StateDefinitionBoundary = "Machine.defineStates" | "Machine.make"
+export type StateDefinitionBoundary = "Machine.state" | "Machine.states" | "Machine.make"
 
 const hasOwn = (value: object, key: PropertyKey): boolean => Object.prototype.hasOwnProperty.call(value, key)
 
@@ -279,3 +279,43 @@ export const validateStateDefinitions = (
   states: unknown,
   boundary: StateDefinitionBoundary
 ): void => validateStateTree(boundary, states, "", false)
+
+const captureAnnotations = (annotations: unknown): unknown =>
+  typeof annotations === "object" && annotations !== null
+    ? Object.freeze({ ...annotations })
+    : annotations
+
+const captureStateTree = (states: Readonly<Record<string, unknown>>): Readonly<Record<string, unknown>> => {
+  const captured: Record<string, unknown> = {}
+  for (const key of Object.keys(states)) {
+    const node = states[key]
+    if (Schema.isSchema(node)) {
+      Object.defineProperty(captured, key, {
+        value: node,
+        enumerable: true,
+        configurable: false,
+        writable: false
+      })
+      continue
+    }
+    const config = node as Readonly<Record<string, unknown>>
+    const copy: Record<string, unknown> = { ...config }
+    if ("states" in config) {
+      copy.states = captureStateTree(config.states as Readonly<Record<string, unknown>>)
+    }
+    if ("annotations" in config) {
+      copy.annotations = captureAnnotations(config.annotations)
+    }
+    Object.defineProperty(captured, key, {
+      value: Object.freeze(copy),
+      enumerable: true,
+      configurable: false,
+      writable: false
+    })
+  }
+  return Object.freeze(captured)
+}
+
+/** Captures caller-owned structural containers while preserving schema identity. */
+export const captureStateDefinitions = <States>(states: States): States =>
+  captureStateTree(states as Readonly<Record<string, unknown>>) as States

package/src/internal/machine/topology.ts

@@ -27,6 +27,8 @@ export const NoTargetTypeId: unique symbol = Symbol("effect/Machine/NoTarget")
 
 export const TargetSelectionTypeId: unique symbol = Symbol("effect/Machine/TargetSelection")
 
+export const SelectedBranchTypeId: unique symbol = Symbol("effect/Machine/SelectedBranch")
+
 interface StateInput {
   readonly [StateInputTypeId]: typeof StateInputTypeId
   readonly input: unknown
@@ -76,6 +78,15 @@ export interface TargetSelection {
   readonly path: string | undefined
 }
 
+/** One branch selection returned by a compiled branching transition. */
+export interface SelectedBranch {
+  readonly [SelectedBranchTypeId]: typeof SelectedBranchTypeId
+  readonly owner: object
+  readonly branchIndex: number
+  readonly branchKey: string
+  readonly result: unknown
+}
+
 export const makeTargetSelection = (
   kind: TargetSelectionKind,
   path?: string,
@@ -90,6 +101,22 @@ export const makeTargetSelection = (
 
 export const isTargetSelection = (u: unknown): u is TargetSelection => hasProperty(u, TargetSelectionTypeId)
 
+export const makeSelectedBranch = (
+  owner: object,
+  branchIndex: number,
+  branchKey: string,
+  result: unknown
+): SelectedBranch =>
+  Object.freeze({
+    [SelectedBranchTypeId]: SelectedBranchTypeId,
+    owner,
+    branchIndex,
+    branchKey,
+    result
+  })
+
+export const isSelectedBranch = (u: unknown): u is SelectedBranch => hasProperty(u, SelectedBranchTypeId)
+
 const noTarget = Object.freeze({
   [NoTargetTypeId]: NoTargetTypeId
 }) as NoTarget
@@ -467,8 +494,10 @@ export const transitionDefinitions = (
       : [config.invoke]
     for (const invoke of invokes) {
       const id = "child" in invoke ? String(invoke.child.id) : String(invoke.id)
-      for (const outcome of ["done", "failure", "snapshot"] as const) {
-        const handler = outcome === "done"
+      for (const outcome of ["element", "done", "failure", "snapshot"] as const) {
+        const handler = outcome === "element"
+          ? invoke.onElement
+          : outcome === "done"
           ? invoke.onDone
           : outcome === "failure"
           ? invoke.onFailure

package/src/internal/testing/machine/finiteModel.ts

@@ -1509,7 +1509,7 @@ export const compileModel = (model: FiniteModel): Machine.Machine.Any => {
   const flattened = validateModel(model)
   const byPath = new Map(flattened.map((state) => [state.path, state]))
   const stateTree = makeStateTree(model.roots, undefined)
-  const defined = Machine.defineStates(stateTree as any)
+  const defined = Machine.states(stateTree as any)
   const eventSchemas = model.events.map((event) => Schema.TaggedStruct(event, {}))
   const initial = byPath.get(model.initial)!
   const machine = Machine.make({

package/src/internal/testing/machine/transitionCoverage.ts

@@ -76,10 +76,12 @@ export const makeTransitionCoverageCollector = <M extends AnyMachine>(
     branchOffsets.push(branches.length)
     const definition = definitions[definitionIndex]!
     definition.branches.forEach((branch, branchIndex) => {
+      const branchKey = branch.type === "branch" ? branch.key : undefined
       branches.push({
-        id: `transition:${definitionIndex}:branch:${branchIndex}`,
+        id: `transition:${definitionIndex}:branch:${branchKey ?? "direct"}`,
         definitionIndex,
         branchIndex,
+        branchKey,
         source: definition.source,
         trigger: definition.trigger,
         reenter: definition.reenter,
@@ -100,9 +102,11 @@ export const makeTransitionCoverageCollector = <M extends AnyMachine>(
         if (definitionIndex === -1) continue
         definitionHits.add(definitionIndex)
         const definition = definitions[definitionIndex]!
+        const branch = definition.branches[retained.branchIndex]
         if (
           Number.isSafeInteger(retained.branchIndex) && retained.branchIndex >= 0 &&
-          retained.branchIndex < definition.branches.length
+          retained.branchIndex < definition.branches.length &&
+          retained.branchKey === (branch?.type === "branch" ? branch.key : undefined)
         ) {
           branchHits.add(branchOffsets[definitionIndex]! + retained.branchIndex)
         }

package/src/internal/testing/machine/verification.ts

@@ -1512,6 +1512,17 @@ export const verify = <M extends AnyMachine>(
       return undefined
     }
     const branch = definition.branches[transition.branchIndex]!
+    const expectedBranchKey = branch.type === "branch" ? branch.key : undefined
+    if (transition.branchKey !== expectedBranchKey) {
+      add(
+        "definitions.branchKey",
+        location,
+        `retained transition from "${transition.source}" selected branch key ` +
+          `"${String(transition.branchKey)}" instead of "${String(expectedBranchKey)}"`,
+        transition.source
+      )
+      return undefined
+    }
     if (!targetWithinSelection(transition.target, branch, byPath)) {
       const expected = branch.selection.kind === "none"
         ? "an explicitly targetless result"

package/src/testing/MachineTest.ts

@@ -227,7 +227,7 @@ export interface Scenarios<M extends AnyMachine> {
  *
  * class Idle extends Schema.TaggedClass<Idle>("Idle")("Idle", {}) {}
  * class Reset extends Schema.TaggedClass<Reset>("Reset")("Reset", {}) {}
- * const States = Machine.defineStates({ Idle })
+ * const States = Machine.states({ Idle })
  * const machine = Machine.make({
  *   states: States.states,
  *   events: Machine.events(Reset),
@@ -488,7 +488,7 @@ export { ProbeUnavailableError } from "../internal/testing/machine/verification.
  * import { MachineTest } from "@typeonce/effect-machine/testing"
  *
  * class Idle extends Schema.TaggedClass<Idle>("Idle")("Idle", {}) {}
- * const States = Machine.defineStates({ Idle })
+ * const States = Machine.states({ Idle })
  * const machine = Machine.make({
  *   states: States.states,
  *   events: Machine.events(),
@@ -1101,7 +1101,7 @@ export const Invariant: {
  * class Count extends Schema.TaggedClass<Count>("Count")("Count", {
  *   value: Schema.Number
  * }) {}
- * const States = Machine.defineStates({ Count })
+ * const States = Machine.states({ Count })
  * const machine = Machine.make({
  *   states: States.states,
  *   events: Machine.events(),
@@ -1436,7 +1436,7 @@ export type ExploreOptions<M extends AnyMachine, Key extends ExplorationKey = Ex
  *   value: Schema.Number
  * }) {}
  * class Increment extends Schema.TaggedClass<Increment>("Increment")("Increment", {}) {}
- * const States = Machine.defineStates({ Count })
+ * const States = Machine.states({ Count })
  * const machine = Machine.make({
  *   states: States.states,
  *   events: Machine.events(Increment),
@@ -1629,7 +1629,7 @@ export type RunServices<M extends AnyMachine> = IsAny<
  * import { MachineTest } from "@typeonce/effect-machine/testing"
  *
  * class Idle extends Schema.TaggedClass<Idle>("Idle")("Idle", {}) {}
- * const States = Machine.defineStates({ Idle })
+ * const States = Machine.states({ Idle })
  * const machine = Machine.make({
  *   states: States.states,
  *   events: Machine.events(),
@@ -1721,6 +1721,7 @@ export interface TransitionBranchCoverageItem<
   readonly id: string
   readonly definitionIndex: number
   readonly branchIndex: number
+  readonly branchKey: string | undefined
   readonly source: SourcePath
   readonly trigger: Machine.Machine.TransitionTrigger<EventTag>
   readonly reenter: boolean
@@ -1893,7 +1894,7 @@ export interface Coverage<M extends AnyMachine> {
  * import { MachineTest } from "@typeonce/effect-machine/testing"
  *
  * class Idle extends Schema.TaggedClass<Idle>("Idle")("Idle", {}) {}
- * const States = Machine.defineStates({ Idle })
+ * const States = Machine.states({ Idle })
  * const machine = Machine.make({
  *   states: States.states,
  *   events: Machine.events(),
@@ -2063,6 +2064,7 @@ export type VerificationLaw =
   | "definitions.initial"
   | "definitions.transition"
   | "definitions.branchIndex"
+  | "definitions.branchKey"
   | "definitions.selection"
   | "definitions.resolution"
 
@@ -2118,7 +2120,7 @@ export interface VerifyOptions {
  * import { MachineTest } from "@typeonce/effect-machine/testing"
  *
  * class Idle extends Schema.TaggedClass<Idle>("Idle")("Idle", {}) {}
- * const States = Machine.defineStates({ Idle })
+ * const States = Machine.states({ Idle })
  * const machine = Machine.make({
  *   states: States.states,
  *   events: Machine.events(),

package/src/unstable/cluster/ClusterMachine.ts

@@ -312,7 +312,7 @@ export const layerMemory: Layer.Layer<Storage> = internal.layerMemory
  * import { ClusterMachine } from "@typeonce/effect-machine/cluster"
  *
  * class Idle extends Schema.TaggedClass<Idle>("Idle")("Idle", {}) {}
- * const States = Machine.defineStates({ Idle })
+ * const States = Machine.states({ Idle })
  * const machine = Machine.make({
  *   states: States.states,
  *   events: Machine.events(),

package/src/unstable/reactivity/AtomMachine.ts

@@ -366,7 +366,7 @@ type ChildState<Child extends Machine.ChildMachine.Any> = RefState<Machine.Child
  * class Count extends Schema.TaggedClass<Count>("Count")("Count", {
  *   value: Schema.Number
  * }) {}
- * const States = Machine.defineStates({ Count })
+ * const States = Machine.states({ Count })
  * const machine = Machine.make({
  *   states: States.states,
  *   events: Machine.events(),
@@ -480,7 +480,7 @@ export const selectSnapshotChild: <
  * import { AtomMachine } from "@typeonce/effect-machine/reactivity"
  *
  * class Idle extends Schema.TaggedClass<Idle>("Idle")("Idle", {}) {}
- * const States = Machine.defineStates({ Idle })
+ * const States = Machine.states({ Idle })
  * const machine = Machine.make({
  *   states: States.states,
  *   events: Machine.events(),
@@ -653,7 +653,7 @@ export interface Bound<Services, RuntimeError = never> {
  * import { AtomMachine } from "@typeonce/effect-machine/reactivity"
  *
  * class Idle extends Schema.TaggedClass<Idle>("Idle")("Idle", {}) {}
- * const States = Machine.defineStates({ Idle })
+ * const States = Machine.states({ Idle })
  * const machine = Machine.make({
  *   states: States.states,
  *   events: Machine.events(),