effect-machine 0.7.1 → 0.8.0

package/dist/actor.js

@@ -2,8 +2,8 @@ import { Inspector } from "./inspection.js";
 import { INTERNAL_INIT_EVENT } from "./internal/utils.js";
 import { DuplicateActorError } from "./errors.js";
 import { isPersistentMachine } from "./persistence/persistent-machine.js";
-import { processEventCore, resolveTransition, runSpawnEffects } from "./internal/transition.js";
 import { emitWithTimestamp } from "./internal/inspection.js";
+import { processEventCore, resolveTransition, runSpawnEffects } from "./internal/transition.js";
 import { PersistenceAdapterTag, PersistenceError } from "./persistence/adapter.js";
 import { createPersistentActor, restorePersistentActor } from "./persistence/persistent-actor.js";
 import { Cause, Deferred, Effect, Exit, Fiber, Layer, MutableHashMap, Option, PubSub, Queue, Ref, Scope, Semaphore, ServiceMap, Stream, SubscriptionRef } from "effect";
@@ -144,6 +144,7 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 	const backgroundFibers = [];
 	const initEvent = { _tag: INTERNAL_INIT_EVENT };
 	const ctx = {
+		actorId: id,
 		state: machine.initial,
 		event: initEvent,
 		self,
@@ -152,6 +153,7 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 	const { effects: effectSlots } = machine._slots;
 	for (const bg of machine.backgroundEffects) {
 		const fiber = yield* Effect.forkDetach(bg.handler({
+			actorId: id,
 			state: machine.initial,
 			event: initEvent,
 			self,
@@ -222,7 +224,7 @@ const processEvent = Effect.fn("effect-machine.actor.processEvent")(function* (m
 		event,
 		timestamp
 	}));
-	const result = yield* processEventCore(machine, currentState, event, self, stateScopeRef, system, inspector === void 0 ? void 0 : {
+	const result = yield* processEventCore(machine, currentState, event, self, stateScopeRef, system, actorId, inspector === void 0 ? void 0 : {
 		onSpawnEffect: (state) => emitWithTimestamp(inspector, (timestamp) => ({
 			type: "@machine.effect",
 			actorId,
@@ -283,7 +285,7 @@ const runSpawnEffectsWithInspection = Effect.fn("effect-machine.actor.spawnEffec
 		state,
 		timestamp
 	}));
-	yield* runSpawnEffects(machine, state, event, self, stateScope, system, inspector === void 0 ? void 0 : (info) => emitWithTimestamp(inspector, (timestamp) => ({
+	yield* runSpawnEffects(machine, state, event, self, stateScope, system, actorId, inspector === void 0 ? void 0 : (info) => emitWithTimestamp(inspector, (timestamp) => ({
 		type: "@machine.error",
 		actorId,
 		phase: info.phase,

package/dist/cluster/entity-machine.js

@@ -14,7 +14,7 @@ import { Entity } from "effect/unstable/cluster";
 * Returns the new state after processing.
 */
 const processEvent = Effect.fn("effect-machine.cluster.processEvent")(function* (machine, stateRef, event, self, stateScopeRef, system, hooks) {
-	const result = yield* processEventCore(machine, yield* Ref.get(stateRef), event, self, stateScopeRef, system, hooks);
+	const result = yield* processEventCore(machine, yield* Ref.get(stateRef), event, self, stateScopeRef, system, "*", hooks);
 	if (result.transitioned) yield* Ref.set(stateRef, result.newState);
 	return result.newState;
 });
@@ -63,7 +63,7 @@ const EntityMachine = { layer: (entity, machine, options) => {
 		};
 		const stateRef = yield* Ref.make(initialState);
 		const stateScopeRef = { current: yield* Scope.make() };
-		yield* runSpawnEffects(machine, initialState, { _tag: "$init" }, self, stateScopeRef.current, system, options?.hooks?.onError);
+		yield* runSpawnEffects(machine, initialState, { _tag: "$init" }, self, stateScopeRef.current, system, entityId, options?.hooks?.onError);
 		const runInternalEvent = Effect.fn("effect-machine.cluster.internalEvent")(function* () {
 			yield* processEvent(machine, stateRef, yield* Queue.take(internalQueue), self, stateScopeRef, system, options?.hooks);
 		});

package/dist/index.d.ts

@@ -6,8 +6,8 @@ import { PersistentActorRef, createPersistentActor, restorePersistentActor } fro
 import { ActorMetadata, PersistedEvent, PersistenceAdapter, PersistenceAdapterTag, PersistenceError, RestoreFailure, RestoreResult, Snapshot, VersionConflictError } from "./persistence/adapter.js";
 import { InMemoryPersistenceAdapter, makeInMemoryPersistenceAdapter } from "./persistence/adapters/in-memory.js";
 import "./persistence/index.js";
-import { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, PersistOptions, ProvideHandlers, SpawnEffect, StateHandlerContext, Transition, machine_d_exports } from "./machine.js";
+import { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, PersistOptions, ProvideHandlers, SpawnEffect, StateHandlerContext, TaskOptions, Transition, machine_d_exports } from "./machine.js";
 import { ActorRef, ActorSystem, Default, SystemEvent, SystemEventListener } from "./actor.js";
 import { SimulationResult, TestHarness, TestHarnessOptions, assertNeverReaches, assertPath, assertReaches, createTestHarness, simulate } from "./testing.js";
-import { AnyInspectionEvent, EffectEvent, ErrorEvent, EventReceivedEvent, InspectionEvent, Inspector, SpawnEvent, StopEvent, TransitionEvent, collectingInspector, consoleInspector, makeInspector } from "./inspection.js";
-export { type ActorMetadata, type ActorRef, type ActorSystem, Default as ActorSystemDefault, ActorSystem as ActorSystemService, type AnyInspectionEvent, AssertionError, type BackgroundEffect, type BuiltMachine, DuplicateActorError, type EffectEvent, type EffectSlots, type EffectsDef, type EffectsSchema, type ErrorEvent, Event, type EventReceivedEvent, type GuardHandlers, type GuardSlot, type GuardSlots, type GuardsDef, type GuardsSchema, type HandlerContext, InMemoryPersistenceAdapter, type InspectionEvent, type Inspector, Inspector as InspectorService, InvalidSchemaError, machine_d_exports as Machine, type MachineContext, type MachineEventSchema, type MachineRef, type MachineStateSchema, type Machine as MachineType, type MakeConfig, MissingMatchHandlerError, MissingSchemaError, type PersistOptions, type PersistedEvent, type PersistenceAdapter, PersistenceAdapterTag, type PersistenceConfig, PersistenceError, type PersistentActorRef, type PersistentMachine, type ProvideHandlers, ProvisionValidationError, type RestoreFailure, type RestoreResult, type SimulationResult, Slot, type EffectHandlers as SlotEffectHandlers, type EffectSlot as SlotEffectSlot, SlotProvisionError, type Snapshot, type SpawnEffect, type SpawnEvent, State, type StateHandlerContext, type StopEvent, type SystemEvent, type SystemEventListener, type TestHarness, type TestHarnessOptions, type Transition, type TransitionEvent, UnprovidedSlotsError, VersionConflictError, assertNeverReaches, assertPath, assertReaches, collectingInspector, consoleInspector, createPersistentActor, createTestHarness, isPersistentMachine, makeInMemoryPersistenceAdapter, makeInspector, restorePersistentActor, simulate };
+import { AnyInspectionEvent, EffectEvent, ErrorEvent, EventReceivedEvent, InspectionEvent, Inspector, InspectorHandler, SpawnEvent, StopEvent, TaskEvent, TracingInspectorOptions, TransitionEvent, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, tracingInspector } from "./inspection.js";
+export { type ActorMetadata, type ActorRef, type ActorSystem, Default as ActorSystemDefault, ActorSystem as ActorSystemService, type AnyInspectionEvent, AssertionError, type BackgroundEffect, type BuiltMachine, DuplicateActorError, type EffectEvent, type EffectSlots, type EffectsDef, type EffectsSchema, type ErrorEvent, Event, type EventReceivedEvent, type GuardHandlers, type GuardSlot, type GuardSlots, type GuardsDef, type GuardsSchema, type HandlerContext, InMemoryPersistenceAdapter, type InspectionEvent, type Inspector, type InspectorHandler, Inspector as InspectorService, InvalidSchemaError, machine_d_exports as Machine, type MachineContext, type MachineEventSchema, type MachineRef, type MachineStateSchema, type Machine as MachineType, type MakeConfig, MissingMatchHandlerError, MissingSchemaError, type PersistOptions, type PersistedEvent, type PersistenceAdapter, PersistenceAdapterTag, type PersistenceConfig, PersistenceError, type PersistentActorRef, type PersistentMachine, type ProvideHandlers, ProvisionValidationError, type RestoreFailure, type RestoreResult, type SimulationResult, Slot, type EffectHandlers as SlotEffectHandlers, type EffectSlot as SlotEffectSlot, SlotProvisionError, type Snapshot, type SpawnEffect, type SpawnEvent, State, type StateHandlerContext, type StopEvent, type SystemEvent, type SystemEventListener, type TaskEvent, type TaskOptions, type TestHarness, type TestHarnessOptions, type TracingInspectorOptions, type Transition, type TransitionEvent, UnprovidedSlotsError, VersionConflictError, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createPersistentActor, createTestHarness, isPersistentMachine, makeInMemoryPersistenceAdapter, makeInspector, makeInspectorEffect, restorePersistentActor, simulate, tracingInspector };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { Inspector, collectingInspector, consoleInspector, makeInspector } from "./inspection.js";
+import { Inspector, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, tracingInspector } from "./inspection.js";
 import { AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, ProvisionValidationError, SlotProvisionError, UnprovidedSlotsError } from "./errors.js";
 import { isPersistentMachine } from "./persistence/persistent-machine.js";
 import { Slot } from "./slot.js";
@@ -11,4 +11,4 @@ import { assertNeverReaches, assertPath, assertReaches, createTestHarness, simul
 import { InMemoryPersistenceAdapter, makeInMemoryPersistenceAdapter } from "./persistence/adapters/in-memory.js";
 import "./persistence/index.js";
 
-export { Default as ActorSystemDefault, ActorSystem as ActorSystemService, AssertionError, DuplicateActorError, Event, InMemoryPersistenceAdapter, Inspector as InspectorService, InvalidSchemaError, machine_exports as Machine, MissingMatchHandlerError, MissingSchemaError, PersistenceAdapterTag, PersistenceError, ProvisionValidationError, Slot, SlotProvisionError, State, UnprovidedSlotsError, VersionConflictError, assertNeverReaches, assertPath, assertReaches, collectingInspector, consoleInspector, createPersistentActor, createTestHarness, isPersistentMachine, makeInMemoryPersistenceAdapter, makeInspector, restorePersistentActor, simulate };
+export { Default as ActorSystemDefault, ActorSystem as ActorSystemService, AssertionError, DuplicateActorError, Event, InMemoryPersistenceAdapter, Inspector as InspectorService, InvalidSchemaError, machine_exports as Machine, MissingMatchHandlerError, MissingSchemaError, PersistenceAdapterTag, PersistenceError, ProvisionValidationError, Slot, SlotProvisionError, State, UnprovidedSlotsError, VersionConflictError, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createPersistentActor, createTestHarness, isPersistentMachine, makeInMemoryPersistenceAdapter, makeInspector, makeInspectorEffect, restorePersistentActor, simulate, tracingInspector };

package/dist/inspection.d.ts

@@ -1,4 +1,4 @@
-import { Schema, ServiceMap } from "effect";
+import { Effect, Schema, ServiceMap } from "effect";
 
 //#region src/inspection.d.ts
 /**
@@ -45,6 +45,15 @@ interface EffectEvent<S> {
   readonly state: S;
   readonly timestamp: number;
 }
+interface TaskEvent<S> {
+  readonly type: "@machine.task";
+  readonly actorId: string;
+  readonly state: S;
+  readonly taskName?: string;
+  readonly phase: "start" | "success" | "failure" | "interrupt";
+  readonly error?: string;
+  readonly timestamp: number;
+}
 /**
  * Event emitted when a transition handler or spawn effect fails with a defect
  */
@@ -69,7 +78,7 @@ interface StopEvent<S> {
 /**
  * Union of all inspection events
  */
-type InspectionEvent<S, E> = SpawnEvent<S> | EventReceivedEvent<S, E> | TransitionEvent<S, E> | EffectEvent<S> | ErrorEvent<S, E> | StopEvent<S>;
+type InspectionEvent<S, E> = SpawnEvent<S> | EventReceivedEvent<S, E> | TransitionEvent<S, E> | EffectEvent<S> | TaskEvent<S> | ErrorEvent<S, E> | StopEvent<S>;
 /**
  * Convenience alias for untyped inspection events.
  * Useful for general-purpose inspectors that don't need specific state/event types.
@@ -84,8 +93,9 @@ type AnyInspectionEvent = InspectionEvent<{
 /**
  * Inspector interface for observing machine behavior
  */
+type InspectorHandler<S, E> = (event: InspectionEvent<S, E>) => void | Effect.Effect<void, never, never>;
 interface Inspector<S, E> {
-  readonly onInspect: (event: InspectionEvent<S, E>) => void;
+  readonly onInspect: InspectorHandler<S, E>;
 }
 /**
  * Inspector service tag - optional service for machine introspection
@@ -104,7 +114,23 @@ declare const makeInspector: <S = {
   readonly _tag: string;
 }, E = {
   readonly _tag: string;
-}>(onInspect: (event: InspectionEvent<ResolveType<S>, ResolveType<E>>) => void) => Inspector<ResolveType<S>, ResolveType<E>>;
+}>(onInspect: InspectorHandler<ResolveType<S>, ResolveType<E>>) => Inspector<ResolveType<S>, ResolveType<E>>;
+declare const makeInspectorEffect: <S = {
+  readonly _tag: string;
+}, E = {
+  readonly _tag: string;
+}>(onInspect: (event: InspectionEvent<ResolveType<S>, ResolveType<E>>) => Effect.Effect<void, never, never>) => Inspector<ResolveType<S>, ResolveType<E>>;
+declare const combineInspectors: <S, E>(...inspectors: ReadonlyArray<Inspector<S, E>>) => Inspector<S, E>;
+interface TracingInspectorOptions<S, E> {
+  readonly spanName?: string | ((event: InspectionEvent<S, E>) => string);
+  readonly attributes?: (event: InspectionEvent<S, E>) => Readonly<Record<string, string | number | boolean>>;
+  readonly eventName?: (event: InspectionEvent<S, E>) => string;
+}
+declare const tracingInspector: <S extends {
+  readonly _tag: string;
+}, E extends {
+  readonly _tag: string;
+}>(options?: TracingInspectorOptions<S, E>) => Inspector<S, E>;
 /**
  * Console inspector that logs events in a readable format
  */
@@ -122,4 +148,4 @@ declare const collectingInspector: <S extends {
   readonly _tag: string;
 }>(events: InspectionEvent<S, E>[]) => Inspector<S, E>;
 //#endregion
-export { AnyInspectionEvent, EffectEvent, ErrorEvent, EventReceivedEvent, InspectionEvent, Inspector, SpawnEvent, StopEvent, TransitionEvent, collectingInspector, consoleInspector, makeInspector };
+export { AnyInspectionEvent, EffectEvent, ErrorEvent, EventReceivedEvent, InspectionEvent, Inspector, InspectorHandler, SpawnEvent, StopEvent, TaskEvent, TracingInspectorOptions, TransitionEvent, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, tracingInspector };

package/dist/inspection.js

@@ -1,4 +1,4 @@
-import { ServiceMap } from "effect";
+import { Effect, Option, ServiceMap } from "effect";
 
 //#region src/inspection.ts
 /**
@@ -15,6 +15,95 @@ const Inspector = ServiceMap.Service("@effect/machine/Inspector");
 * - `makeInspector<typeof MyState, typeof MyEvent>(cb)` — schema constructors (auto-extracts `.Type`)
 */
 const makeInspector = (onInspect) => ({ onInspect });
+const makeInspectorEffect = (onInspect) => ({ onInspect });
+const inspectionEffect = (inspector, event) => {
+	const result = inspector.onInspect(event);
+	return Effect.isEffect(result) ? result : Effect.void;
+};
+const combineInspectors = (...inspectors) => ({ onInspect: (event) => Effect.forEach(inspectors, (inspector) => inspectionEffect(inspector, event).pipe(Effect.catchCause(() => Effect.void)), {
+	concurrency: "unbounded",
+	discard: true
+}) });
+const inspectionSpanName = (event) => {
+	switch (event.type) {
+		case "@machine.spawn": return `Machine.inspect ${event.initialState._tag}`;
+		case "@machine.event": return `Machine.inspect ${event.event._tag}`;
+		case "@machine.transition": return `Machine.inspect ${event.fromState._tag}->${event.toState._tag}`;
+		case "@machine.effect": return `Machine.inspect ${event.effectType}`;
+		case "@machine.task": return `Machine.inspect task:${event.phase}`;
+		case "@machine.error": return `Machine.inspect ${event.phase}`;
+		case "@machine.stop": return `Machine.inspect ${event.finalState._tag}`;
+	}
+};
+const inspectionTraceName = (event) => {
+	switch (event.type) {
+		case "@machine.spawn": return `machine.spawn ${event.initialState._tag}`;
+		case "@machine.event": return `machine.event ${event.event._tag}`;
+		case "@machine.transition": return `machine.transition ${event.fromState._tag}->${event.toState._tag}`;
+		case "@machine.effect": return `machine.effect ${event.effectType}`;
+		case "@machine.task": return `machine.task ${event.phase}${event.taskName === void 0 ? "" : ` ${event.taskName}`}`;
+		case "@machine.error": return `machine.error ${event.phase}`;
+		case "@machine.stop": return `machine.stop ${event.finalState._tag}`;
+	}
+};
+const inspectionAttributes = (event) => {
+	const shared = {
+		"machine.actor.id": event.actorId,
+		"machine.inspection.type": event.type
+	};
+	switch (event.type) {
+		case "@machine.spawn": return {
+			...shared,
+			"machine.state.initial": event.initialState._tag
+		};
+		case "@machine.event": return {
+			...shared,
+			"machine.state.current": event.state._tag,
+			"machine.event.tag": event.event._tag
+		};
+		case "@machine.transition": return {
+			...shared,
+			"machine.state.from": event.fromState._tag,
+			"machine.state.to": event.toState._tag,
+			"machine.event.tag": event.event._tag
+		};
+		case "@machine.effect": return {
+			...shared,
+			"machine.state.current": event.state._tag,
+			"machine.effect.kind": event.effectType
+		};
+		case "@machine.task": return {
+			...shared,
+			"machine.state.current": event.state._tag,
+			"machine.task.phase": event.phase,
+			...event.taskName === void 0 ? {} : { "machine.task.name": event.taskName }
+		};
+		case "@machine.error": return {
+			...shared,
+			"machine.phase": event.phase,
+			"machine.state.current": event.state._tag
+		};
+		case "@machine.stop": return {
+			...shared,
+			"machine.state.final": event.finalState._tag
+		};
+	}
+};
+const tracingInspector = (options) => ({ onInspect: (event) => {
+	const spanName = typeof options?.spanName === "function" ? options.spanName(event) : options?.spanName;
+	const traceName = options?.eventName?.(event) ?? inspectionTraceName(event);
+	const attributes = {
+		...inspectionAttributes(event),
+		...options?.attributes?.(event) ?? {}
+	};
+	return Effect.gen(function* () {
+		const currentSpan = yield* Effect.option(Effect.currentSpan);
+		if (Option.isSome(currentSpan)) currentSpan.value.event(traceName, BigInt(event.timestamp) * 1000000n, {
+			actorId: event.actorId,
+			inspectionType: event.type
+		});
+	}).pipe(Effect.withSpan(spanName ?? inspectionSpanName(event), { attributes }));
+} });
 /**
 * Console inspector that logs events in a readable format
 */
@@ -33,6 +122,9 @@ const consoleInspector = () => makeInspector((event) => {
 		case "@machine.effect":
 			console.log(prefix, event.effectType, "effect in", event.state._tag);
 			break;
+		case "@machine.task":
+			console.log(prefix, "task", event.phase, event.taskName ?? "<unnamed>", "in", event.state._tag);
+			break;
 		case "@machine.error":
 			console.log(prefix, "error in", event.phase, event.state._tag, "-", event.error);
 			break;
@@ -44,7 +136,9 @@ const consoleInspector = () => makeInspector((event) => {
 /**
 * Collecting inspector that stores events in an array for testing
 */
-const collectingInspector = (events) => ({ onInspect: (event) => events.push(event) });
+const collectingInspector = (events) => ({ onInspect: (event) => {
+	events.push(event);
+} });
 
 //#endregion
-export { Inspector, collectingInspector, consoleInspector, makeInspector };
+export { Inspector, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, tracingInspector };

package/dist/internal/inspection.js

@@ -7,12 +7,15 @@ import { Clock, Effect } from "effect";
 */
 const emitWithTimestamp = Effect.fn("effect-machine.emitWithTimestamp")(function* (inspector, makeEvent) {
 	if (inspector === void 0) return;
-	const timestamp = yield* Clock.currentTimeMillis;
-	yield* Effect.sync(() => {
+	const event = makeEvent(yield* Clock.currentTimeMillis);
+	const result = yield* Effect.sync(() => {
 		try {
-			inspector.onInspect(makeEvent(timestamp));
-		} catch {}
+			return inspector.onInspect(event);
+		} catch {
+			return;
+		}
 	});
+	if (Effect.isEffect(result)) yield* result.pipe(Effect.catchCause(() => Effect.void));
 });
 
 //#endregion

package/dist/internal/transition.d.ts

@@ -29,7 +29,7 @@ declare const runTransitionHandler: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, GD extends GuardsDef, EFD extends EffectsDef>(machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>, transition: Transition<S, E, GD, EFD, R>, state: S, event: E, self: MachineRef<E>, system: ActorSystem) => Effect.Effect<S, never, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
+}, R, GD extends GuardsDef, EFD extends EffectsDef>(machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>, transition: Transition<S, E, GD, EFD, R>, state: S, event: E, self: MachineRef<E>, system: ActorSystem, actorId: string) => Effect.Effect<S, never, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
 /**
  * Execute a transition for a given state and event.
  * Handles transition resolution, handler invocation, and guard/effect slot creation.
@@ -45,7 +45,7 @@ declare const executeTransition: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, GD extends GuardsDef, EFD extends EffectsDef>(machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>, currentState: S, event: E, self: MachineRef<E>, system: ActorSystem) => Effect.Effect<{
+}, R, GD extends GuardsDef, EFD extends EffectsDef>(machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>, currentState: S, event: E, self: MachineRef<E>, system: ActorSystem, actorId: string) => Effect.Effect<{
   newState: S;
   transitioned: boolean;
   reenter: boolean;
@@ -103,7 +103,7 @@ declare const processEventCore: <S extends {
   readonly _tag: string;
 }, R, GD extends GuardsDef, EFD extends EffectsDef>(machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>, currentState: S, event: E, self: MachineRef<E>, stateScopeRef: {
   current: Scope.Closeable;
-}, system: ActorSystem, hooks?: ProcessEventHooks<S, E> | undefined) => Effect.Effect<{
+}, system: ActorSystem, actorId: string, hooks?: ProcessEventHooks<S, E> | undefined) => Effect.Effect<{
   newState: S;
   previousState: S;
   transitioned: boolean;
@@ -119,7 +119,7 @@ declare const runSpawnEffects: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, GD extends GuardsDef, EFD extends EffectsDef>(machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>, state: S, event: E, self: MachineRef<E>, stateScope: Scope.Closeable, system: ActorSystem, onError?: ((info: ProcessEventError<S, E>) => Effect.Effect<void>) | undefined) => Effect.Effect<void, never, Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope>>;
+}, R, GD extends GuardsDef, EFD extends EffectsDef>(machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>, state: S, event: E, self: MachineRef<E>, stateScope: Scope.Closeable, system: ActorSystem, actorId: string, onError?: ((info: ProcessEventError<S, E>) => Effect.Effect<void>) | undefined) => Effect.Effect<void, never, Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope>>;
 /**
  * Resolve which transition should fire for a given state and event.
  * Uses indexed O(1) lookup. First matching transition wins.

package/dist/internal/transition.js

@@ -23,8 +23,9 @@ import { Cause, Effect, Exit, Scope } from "effect";
 *
 * @internal
 */
-const runTransitionHandler = Effect.fn("effect-machine.runTransitionHandler")(function* (machine, transition, state, event, self, system) {
+const runTransitionHandler = Effect.fn("effect-machine.runTransitionHandler")(function* (machine, transition, state, event, self, system, actorId) {
 	const ctx = {
+		actorId,
 		state,
 		event,
 		self,
@@ -51,7 +52,7 @@ const runTransitionHandler = Effect.fn("effect-machine.runTransitionHandler")(fu
 *
 * @internal
 */
-const executeTransition = Effect.fn("effect-machine.executeTransition")(function* (machine, currentState, event, self, system) {
+const executeTransition = Effect.fn("effect-machine.executeTransition")(function* (machine, currentState, event, self, system, actorId) {
 	const transition = resolveTransition(machine, currentState, event);
 	if (transition === void 0) return {
 		newState: currentState,
@@ -59,7 +60,7 @@ const executeTransition = Effect.fn("effect-machine.executeTransition")(function
 		reenter: false
 	};
 	return {
-		newState: yield* runTransitionHandler(machine, transition, currentState, event, self, system),
+		newState: yield* runTransitionHandler(machine, transition, currentState, event, self, system, actorId),
 		transitioned: true,
 		reenter: transition.reenter === true
 	};
@@ -76,8 +77,8 @@ const executeTransition = Effect.fn("effect-machine.executeTransition")(function
 *
 * @internal
 */
-const processEventCore = Effect.fn("effect-machine.processEventCore")(function* (machine, currentState, event, self, stateScopeRef, system, hooks) {
-	const result = yield* executeTransition(machine, currentState, event, self, system).pipe(Effect.catchCause((cause) => {
+const processEventCore = Effect.fn("effect-machine.processEventCore")(function* (machine, currentState, event, self, stateScopeRef, system, actorId, hooks) {
+	const result = yield* executeTransition(machine, currentState, event, self, system, actorId).pipe(Effect.catchCause((cause) => {
 		if (Cause.hasInterruptsOnly(cause)) return Effect.interrupt;
 		const onError = hooks?.onError;
 		if (onError === void 0) return Effect.failCause(cause).pipe(Effect.orDie);
@@ -102,7 +103,7 @@ const processEventCore = Effect.fn("effect-machine.processEventCore")(function*
 		stateScopeRef.current = yield* Scope.make();
 		if (hooks?.onTransition !== void 0) yield* hooks.onTransition(currentState, newState, event);
 		if (hooks?.onSpawnEffect !== void 0) yield* hooks.onSpawnEffect(newState);
-		yield* runSpawnEffects(machine, newState, { _tag: INTERNAL_ENTER_EVENT }, self, stateScopeRef.current, system, hooks?.onError);
+		yield* runSpawnEffects(machine, newState, { _tag: INTERNAL_ENTER_EVENT }, self, stateScopeRef.current, system, actorId, hooks?.onError);
 	}
 	return {
 		newState,
@@ -117,9 +118,10 @@ const processEventCore = Effect.fn("effect-machine.processEventCore")(function*
 *
 * @internal
 */
-const runSpawnEffects = Effect.fn("effect-machine.runSpawnEffects")(function* (machine, state, event, self, stateScope, system, onError) {
+const runSpawnEffects = Effect.fn("effect-machine.runSpawnEffects")(function* (machine, state, event, self, stateScope, system, actorId, onError) {
 	const spawnEffects = findSpawnEffects(machine, state._tag);
 	const ctx = {
+		actorId,
 		state,
 		event,
 		self,
@@ -129,6 +131,7 @@ const runSpawnEffects = Effect.fn("effect-machine.runSpawnEffects")(function* (m
 	const reportError = onError;
 	for (const spawnEffect of spawnEffects) {
 		const effect = spawnEffect.handler({
+			actorId,
 			state,
 			event,
 			self,

package/dist/machine.d.ts

@@ -11,7 +11,7 @@ import { Cause, Effect, Schedule, Schema, Scope, ServiceMap } from "effect";
 
 //#region src/machine.d.ts
 declare namespace machine_d_exports {
-  export { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, PersistOptions, PersistenceConfig, PersistentMachine, ProvideHandlers, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, Transition, TransitionHandler, findTransitions, make, spawn };
+  export { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, PersistOptions, PersistenceConfig, PersistentMachine, ProvideHandlers, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, Transition, TransitionHandler, findTransitions, make, spawn };
 }
 /**
  * Self reference for sending events back to the machine
@@ -37,6 +37,7 @@ interface HandlerContext<State, Event, GD extends GuardsDef, ED extends EffectsD
  * Handler context passed to state effect handlers (onEnter, spawn, background)
  */
 interface StateHandlerContext<State, Event, ED extends EffectsDef> {
+  readonly actorId: string;
   readonly state: State;
   readonly event: Event;
   readonly self: MachineRef<Event>;
@@ -81,6 +82,11 @@ interface PersistOptions {
   readonly journalEvents: boolean;
   readonly machineType?: string;
 }
+interface TaskOptions<State, Event, ED extends EffectsDef, A, E1, ES, EF> {
+  readonly onSuccess: (value: A, ctx: StateHandlerContext<State, Event, ED>) => ES;
+  readonly onFailure?: (cause: Cause.Cause<E1>, ctx: StateHandlerContext<State, Event, ED>) => EF;
+  readonly name?: string;
+}
 type IsAny<T> = 0 extends 1 & T ? true : false;
 type IsUnknown<T> = unknown extends T ? ([T] extends [unknown] ? true : false) : false;
 type NormalizeR<T> = IsAny<T> extends true ? T : IsUnknown<T> extends true ? never : T;
@@ -174,6 +180,10 @@ declare class Machine<State, Event, R = never, _SD extends Record<string, Schema
   get effectsSchema(): EffectsSchema<EFD> | undefined;
   /** @internal */
   constructor(initial: State, stateSchema?: Schema.Schema<State>, eventSchema?: Schema.Schema<Event>, guardsSchema?: GuardsSchema<GD>, effectsSchema?: EffectsSchema<EFD>);
+  from<NS extends VariantsUnion<_SD> & BrandedState, R1>(state: TaggedOrConstructor<NS>, build: (scope: TransitionScope<State, Event, R, _SD, _ED, GD, EFD, NS>) => R1): Machine<State, Event, R, _SD, _ED, GD, EFD>;
+  from<NS extends ReadonlyArray<TaggedOrConstructor<VariantsUnion<_SD> & BrandedState>>, R1>(states: NS, build: (scope: TransitionScope<State, Event, R, _SD, _ED, GD, EFD, NS[number] extends TaggedOrConstructor<infer S extends VariantsUnion<_SD> & BrandedState> ? S : never>) => R1): Machine<State, Event, R, _SD, _ED, GD, EFD>;
+  /** @internal */
+  scopeTransition<NS extends VariantsUnion<_SD> & BrandedState, NE extends VariantsUnion<_ED> & BrandedEvent, RS extends VariantsUnion<_SD> & BrandedState>(states: ReadonlyArray<TaggedOrConstructor<NS>>, event: TaggedOrConstructor<NE>, handler: TransitionHandler<NS, NE, RS, GD, EFD, never>, reenter: boolean): Machine<State, Event, R, _SD, _ED, GD, EFD>;
   /** Register transition for a single state */
   on<NS extends VariantsUnion<_SD> & BrandedState, NE extends VariantsUnion<_ED> & BrandedEvent, RS extends VariantsUnion<_SD> & BrandedState>(state: TaggedOrConstructor<NS>, event: TaggedOrConstructor<NE>, handler: TransitionHandler<NS, NE, RS, GD, EFD, never>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
   /** Register transition for multiple states (handler receives union of state types) */
@@ -220,10 +230,7 @@ declare class Machine<State, Event, R = never, _SD extends Record<string, Schema
    * State-scoped task that runs on entry and sends success/failure events.
    * Interrupts do not emit failure events.
    */
-  task<NS extends VariantsUnion<_SD> & BrandedState, A, E1, ES extends VariantsUnion<_ED> & BrandedEvent, EF extends VariantsUnion<_ED> & BrandedEvent>(state: TaggedOrConstructor<NS>, run: (ctx: StateHandlerContext<NS, VariantsUnion<_ED> & BrandedEvent, EFD>) => Effect.Effect<A, E1, Scope.Scope>, options: {
-    readonly onSuccess: (value: A, ctx: StateHandlerContext<NS, VariantsUnion<_ED> & BrandedEvent, EFD>) => ES;
-    readonly onFailure?: (cause: Cause.Cause<E1>, ctx: StateHandlerContext<NS, VariantsUnion<_ED> & BrandedEvent, EFD>) => EF;
-  }): Machine<State, Event, R, _SD, _ED, GD, EFD>;
+  task<NS extends VariantsUnion<_SD> & BrandedState, A, E1, ES extends VariantsUnion<_ED> & BrandedEvent, EF extends VariantsUnion<_ED> & BrandedEvent>(state: TaggedOrConstructor<NS>, run: (ctx: StateHandlerContext<NS, VariantsUnion<_ED> & BrandedEvent, EFD>) => Effect.Effect<A, E1, Scope.Scope>, options: TaskOptions<NS, VariantsUnion<_ED> & BrandedEvent, EFD, A, E1, ES, EF>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
   /**
    * Machine-lifetime effect that is forked on actor spawn and runs until the actor stops.
    * Use effect slots defined via `Slot.Effects` for the actual work.
@@ -261,6 +268,13 @@ declare class Machine<State, Event, R = never, _SD extends Record<string, Schema
   }, R>;
   static make<SD extends Record<string, Schema.Struct.Fields>, ED extends Record<string, Schema.Struct.Fields>, S extends BrandedState, E extends BrandedEvent, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(config: MakeConfig<SD, ED, S, E, GD, EFD>): Machine<S, E, never, SD, ED, GD, EFD>;
 }
+declare class TransitionScope<State, Event, R, _SD extends Record<string, Schema.Struct.Fields>, _ED extends Record<string, Schema.Struct.Fields>, GD extends GuardsDef, EFD extends EffectsDef, SelectedState extends VariantsUnion<_SD> & BrandedState> {
+  private readonly machine;
+  private readonly states;
+  constructor(machine: Machine<State, Event, R, _SD, _ED, GD, EFD>, states: ReadonlyArray<TaggedOrConstructor<SelectedState>>);
+  on<NE extends VariantsUnion<_ED> & BrandedEvent, RS extends VariantsUnion<_SD> & BrandedState>(event: TaggedOrConstructor<NE>, handler: TransitionHandler<SelectedState, NE, RS, GD, EFD, never>): TransitionScope<State, Event, R, _SD, _ED, GD, EFD, SelectedState>;
+  reenter<NE extends VariantsUnion<_ED> & BrandedEvent, RS extends VariantsUnion<_SD> & BrandedState>(event: TaggedOrConstructor<NE>, handler: TransitionHandler<SelectedState, NE, RS, GD, EFD, never>): TransitionScope<State, Event, R, _SD, _ED, GD, EFD, SelectedState>;
+}
 declare const make: typeof Machine.make;
 declare const spawn: {
   <S extends {
@@ -275,4 +289,4 @@ declare const spawn: {
   }, R>(machine: BuiltMachine<S, E, R>, id: string): Effect.Effect<ActorRef<S, E>, never, R>;
 };
 //#endregion
-export { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, PersistOptions, type PersistenceConfig, type PersistentMachine, ProvideHandlers, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, Transition, TransitionHandler, findTransitions, machine_d_exports, make, spawn };
+export { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, PersistOptions, type PersistenceConfig, type PersistentMachine, ProvideHandlers, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, Transition, TransitionHandler, findTransitions, machine_d_exports, make, spawn };

package/dist/machine.js

@@ -1,7 +1,9 @@
 import { __exportAll } from "./_virtual/_rolldown/runtime.js";
+import { Inspector } from "./inspection.js";
 import { getTag } from "./internal/utils.js";
 import { ProvisionValidationError, SlotProvisionError } from "./errors.js";
 import { persist } from "./persistence/persistent-machine.js";
+import { emitWithTimestamp } from "./internal/inspection.js";
 import { MachineContextTag } from "./slot.js";
 import { findTransitions, invalidateIndex } from "./internal/transition.js";
 import { createActor } from "./actor.js";
@@ -15,6 +17,15 @@ var machine_exports = /* @__PURE__ */ __exportAll({
 	make: () => make,
 	spawn: () => spawn
 });
+const emitTaskInspection = (input) => Effect.flatMap(Effect.serviceOption(Inspector), (inspector) => Option.isNone(inspector) ? Effect.void : emitWithTimestamp(inspector.value, (timestamp) => ({
+	type: "@machine.task",
+	actorId: input.actorId,
+	state: input.state,
+	taskName: input.taskName,
+	phase: input.phase,
+	error: input.error,
+	timestamp
+})));
 /**
 * A finalized machine ready for spawning.
 *
@@ -121,6 +132,15 @@ var Machine = class Machine {
 			})) : {}
 		};
 	}
+	from(stateOrStates, build) {
+		build(new TransitionScope(this, Array.isArray(stateOrStates) ? stateOrStates : [stateOrStates]));
+		return this;
+	}
+	/** @internal */
+	scopeTransition(states, event, handler, reenter) {
+		for (const state of states) this.addTransition(state, event, handler, reenter);
+		return this;
+	}
 	on(stateOrStates, event, handler) {
 		const states = Array.isArray(stateOrStates) ? stateOrStates : [stateOrStates];
 		for (const s of states) this.addTransition(s, event, handler, false);
@@ -195,14 +215,41 @@ var Machine = class Machine {
 	*/
 	task(state, run, options) {
 		const handler = Effect.fn("effect-machine.task")(function* (ctx) {
+			yield* emitTaskInspection({
+				actorId: ctx.actorId,
+				state: ctx.state,
+				taskName: options.name,
+				phase: "start"
+			});
 			const exit = yield* Effect.exit(run(ctx));
 			if (Exit.isSuccess(exit)) {
+				yield* emitTaskInspection({
+					actorId: ctx.actorId,
+					state: ctx.state,
+					taskName: options.name,
+					phase: "success"
+				});
 				yield* ctx.self.send(options.onSuccess(exit.value, ctx));
 				yield* Effect.yieldNow;
 				return;
 			}
 			const cause = exit.cause;
-			if (Cause.hasInterruptsOnly(cause)) return;
+			if (Cause.hasInterruptsOnly(cause)) {
+				yield* emitTaskInspection({
+					actorId: ctx.actorId,
+					state: ctx.state,
+					taskName: options.name,
+					phase: "interrupt"
+				});
+				return;
+			}
+			yield* emitTaskInspection({
+				actorId: ctx.actorId,
+				state: ctx.state,
+				taskName: options.name,
+				phase: "failure",
+				error: Cause.pretty(cause)
+			});
 			if (options.onFailure !== void 0) {
 				yield* ctx.self.send(options.onFailure(cause, ctx));
 				yield* Effect.yieldNow;
@@ -282,6 +329,20 @@ var Machine = class Machine {
 		return new Machine(config.initial, config.state, config.event, config.guards, config.effects);
 	}
 };
+var TransitionScope = class {
+	constructor(machine, states) {
+		this.machine = machine;
+		this.states = states;
+	}
+	on(event, handler) {
+		this.machine.scopeTransition(this.states, event, handler, false);
+		return this;
+	}
+	reenter(event, handler) {
+		this.machine.scopeTransition(this.states, event, handler, true);
+		return this;
+	}
+};
 const make = Machine.make;
 /**
 * Spawn an actor directly without ActorSystem ceremony.

package/dist/persistence/persistent-actor.js

@@ -1,7 +1,7 @@
 import { Inspector } from "../inspection.js";
 import { INTERNAL_INIT_EVENT, stubSystem } from "../internal/utils.js";
-import { processEventCore, resolveTransition, runSpawnEffects, runTransitionHandler } from "../internal/transition.js";
 import { emitWithTimestamp } from "../internal/inspection.js";
+import { processEventCore, resolveTransition, runSpawnEffects, runTransitionHandler } from "../internal/transition.js";
 import { PersistenceAdapterTag } from "./adapter.js";
 import { ActorSystem, buildActorRefCore, notifyListeners } from "../actor.js";
 import { Cause, Clock, Effect, Exit, Fiber, Option, Queue, Ref, Schedule, Scope, SubscriptionRef } from "effect";
@@ -20,7 +20,7 @@ const replayEvents = Effect.fn("effect-machine.persistentActor.replayEvents")(fu
 	for (const persistedEvent of events) {
 		if (stopVersion !== void 0 && persistedEvent.version > stopVersion) break;
 		const transition = resolveTransition(machine, state, persistedEvent.event);
-		if (transition !== void 0) state = yield* runTransitionHandler(machine, transition, state, persistedEvent.event, self, stubSystem);
+		if (transition !== void 0) state = yield* runTransitionHandler(machine, transition, state, persistedEvent.event, self, stubSystem, "restore");
 		version = persistedEvent.version;
 	}
 	return {
@@ -146,6 +146,7 @@ const createPersistentActor = Effect.fn("effect-machine.persistentActor.spawn")(
 	const backgroundFibers = [];
 	const initEvent = { _tag: INTERNAL_INIT_EVENT };
 	const initCtx = {
+		actorId: id,
 		state: resolvedInitial,
 		event: initEvent,
 		self,
@@ -154,6 +155,7 @@ const createPersistentActor = Effect.fn("effect-machine.persistentActor.spawn")(
 	const { effects: effectSlots } = typedMachine._slots;
 	for (const bg of typedMachine.backgroundEffects) {
 		const fiber = yield* Effect.forkDetach(bg.handler({
+			actorId: id,
 			state: resolvedInitial,
 			event: initEvent,
 			self,
@@ -238,7 +240,7 @@ const persistentEventLoop = Effect.fn("effect-machine.persistentActor.eventLoop"
 			event,
 			timestamp
 		}));
-		const result = yield* processEventCore(typedMachine, currentState, event, self, stateScopeRef, system, hooks);
+		const result = yield* processEventCore(typedMachine, currentState, event, self, stateScopeRef, system, id, hooks);
 		if (!result.transitioned) continue;
 		const newVersion = currentVersion + 1;
 		yield* Ref.set(versionRef, newVersion);
@@ -286,7 +288,7 @@ const runSpawnEffectsWithInspection = Effect.fn("effect-machine.persistentActor.
 		state,
 		timestamp
 	}));
-	yield* runSpawnEffects(machine, state, event, self, stateScope, system, inspector === void 0 ? void 0 : (info) => emitWithTimestamp(inspector, (timestamp) => ({
+	yield* runSpawnEffects(machine, state, event, self, stateScope, system, actorId, inspector === void 0 ? void 0 : (info) => emitWithTimestamp(inspector, (timestamp) => ({
 		type: "@machine.error",
 		actorId,
 		phase: info.phase,

package/dist/schema.js

@@ -42,6 +42,7 @@ import { Schema } from "effect";
 /**
 * Build a schema-first definition from a record of tag -> fields
 */
+const RESERVED_DERIVE_KEYS = new Set(["_tag"]);
 const buildMachineSchema = (definition) => {
 	const variants = {};
 	const constructors = {};
@@ -59,7 +60,10 @@ const buildMachineSchema = (definition) => {
 			constructor.derive = (source, partial) => {
 				const result = { _tag: tag };
 				for (const key of fieldNames) if (key in source) result[key] = source[key];
-				if (partial !== void 0) for (const [key, value] of Object.entries(partial)) result[key] = value;
+				if (partial !== void 0) for (const [key, value] of Object.entries(partial)) {
+					if (RESERVED_DERIVE_KEYS.has(key)) continue;
+					result[key] = value;
+				}
 				return result;
 			};
 			constructors[tag] = constructor;

package/dist/slot.d.ts

@@ -43,6 +43,7 @@ type EffectSlots<D extends EffectsDef> = { readonly [K in keyof D & string]: Eff
  * Shared across all machines via MachineContextTag.
  */
 interface MachineContext<State, Event, Self> {
+  readonly actorId: string;
   readonly state: State;
   readonly event: Event;
   readonly self: Self;

package/dist/testing.js

@@ -34,7 +34,7 @@ const simulate = Effect.fn("effect-machine.simulate")(function* (input, events)
 	let currentState = machine.initial;
 	const states = [currentState];
 	for (const event of events) {
-		const result = yield* executeTransition(machine, currentState, event, dummySelf, stubSystem);
+		const result = yield* executeTransition(machine, currentState, event, dummySelf, stubSystem, "simulation");
 		if (!result.transitioned) continue;
 		currentState = result.newState;
 		states.push(currentState);
@@ -123,7 +123,7 @@ const createTestHarness = Effect.fn("effect-machine.createTestHarness")(function
 		state: stateRef,
 		send: Effect.fn("effect-machine.testHarness.send")(function* (event) {
 			const currentState = yield* SubscriptionRef.get(stateRef);
-			const result = yield* executeTransition(machine, currentState, event, dummySelf, stubSystem);
+			const result = yield* executeTransition(machine, currentState, event, dummySelf, stubSystem, "test-harness");
 			if (!result.transitioned) return currentState;
 			const newState = result.newState;
 			yield* SubscriptionRef.set(stateRef, newState);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect-machine",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/cevr/effect-machine.git"
@@ -55,7 +55,7 @@
     "release": "bun run build && changeset publish"
   },
   "dependencies": {
-    "effect": "4.0.0-beta.21"
+    "effect": "4.0.0-beta.35"
   },
   "devDependencies": {
     "@changesets/changelog-github": "^0.5.2",
@@ -80,6 +80,6 @@
     }
   },
   "overrides": {
-    "effect": "4.0.0-beta.21"
+    "effect": "4.0.0-beta.35"
   }
 }