effect-machine 0.15.2 → 0.17.0

package/v3/dist/actor.js

@@ -19,6 +19,16 @@ import { Cause, Context, Deferred, Effect, Exit, Fiber, Layer, MutableHashMap, O
 */
 const ActorSystem = Context.GenericTag("@effect/machine/ActorSystem");
 /**
+* Explicit scope for actor lifecycle management.
+*
+* When present in context, actors attach cleanup finalizers to this scope.
+* This replaces ambient `Scope.Scope` detection which caused bugs where
+* unrelated scopes would tear down actors unexpectedly.
+*
+* Provide via `Machine.scoped` or `Effect.provideService(ActorScope, scope)`.
+*/
+const ActorScope = Context.GenericTag("@effect/machine/ActorScope");
+/**
 * Notify all listeners of state change.
 */
 const notifyListeners = (listeners, state) => {
@@ -40,11 +50,19 @@ const buildActorRefCore = (id, machine, stateRef, eventQueueRef, stoppedRef, lis
 	});
 	const call = Effect.fn("effect-machine.actor.call")(function* (event) {
 		if (yield* Ref.get(stoppedRef)) {
+			yield* Effect.logWarning("effect-machine.actor.call.stopped").pipe(Effect.annotateLogs({
+				actorId: id,
+				eventTag: event._tag
+			}));
 			const currentState = yield* SubscriptionRef.get(stateRef);
 			return {
 				newState: currentState,
 				previousState: currentState,
 				transitioned: false,
+				hasReply: false,
+				deferReply: false,
+				reply: void 0,
+				postponed: false,
 				lifecycleRan: false,
 				isFinal: machine.finalStates.has(currentState._tag)
 			};
@@ -61,6 +79,10 @@ const buildActorRefCore = (id, machine, stateRef, eventQueueRef, stoppedRef, lis
 			newState: currentState,
 			previousState: currentState,
 			transitioned: false,
+			hasReply: false,
+			deferReply: false,
+			reply: void 0,
+			postponed: false,
 			lifecycleRan: false,
 			isFinal: machine.finalStates.has(currentState._tag)
 		})))));
@@ -469,7 +491,7 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
 			id,
 			actor: actorRef
 		});
-		const maybeScope = yield* Effect.serviceOption(Scope.Scope);
+		const maybeScope = yield* Effect.serviceOption(ActorScope);
 		if (Option.isSome(maybeScope)) yield* Scope.addFinalizer(maybeScope.value, Effect.gen(function* () {
 			if (MutableHashMap.has(actorsMap, id)) {
 				yield* emitSystemEvent({
@@ -552,4 +574,4 @@ const makeSystem = make;
 */
 const Default = Layer.scoped(ActorSystem, make());
 //#endregion
-export { ActorSystem, Default, buildActorRefCore, createActor, makeSystem, notifyListeners, processEventCore, resolveTransition, runSpawnEffects, settlePendingReplies };
+export { ActorScope, ActorSystem, Default, buildActorRefCore, createActor, makeSystem, notifyListeners, processEventCore, resolveTransition, runSpawnEffects, settlePendingReplies };

package/v3/dist/cluster/entity-machine.d.ts

@@ -43,7 +43,7 @@ interface EntityMachineOptions<S, E> {
    * Retry policy for defects (schedule for restarting after defect).
    * Forwarded to Entity.toLayer.
    */
-  readonly defectRetryPolicy?: Schedule.Schedule<any, unknown>;
+  readonly defectRetryPolicy?: Schedule.Schedule<any>;
   /**
    * Persistence configuration. When set, requires PersistenceAdapter in R.
    */

package/v3/dist/cluster/entity-machine.js

@@ -3,7 +3,7 @@ import { replay } from "../machine.js";
 import { createRuntime } from "../internal/runtime.js";
 import { ActorSystem } from "../actor.js";
 import { PersistenceAdapter } from "./persistence.js";
-import { Effect, Option, Ref } from "effect";
+import { Clock, Effect, Option, Ref } from "effect";
 import { Entity } from "@effect/cluster";
 //#region src/cluster/entity-machine.ts
 /**
@@ -56,10 +56,11 @@ const EntityMachine = { layer: (entity, machine, options) => {
 			yield* Effect.addFinalizer(() => Effect.gen(function* () {
 				const state = yield* runtime.getState;
 				const version = yield* Ref.get(versionRef);
+				const now = yield* Clock.currentTimeMillis;
 				yield* pAdapter.saveSnapshot(key, {
 					state,
 					version,
-					timestamp: Date.now()
+					timestamp: now
 				});
 			}).pipe(Effect.catchAll(() => Effect.void)));
 		}
@@ -153,7 +154,7 @@ const persistEvent = (adapter, key, versionRef, event) => Effect.gen(function* (
 	const persisted = {
 		event,
 		version: newVersion,
-		timestamp: Date.now()
+		timestamp: yield* Clock.currentTimeMillis
 	};
 	yield* adapter.appendEvents(key, [persisted], expectedVersion);
 	yield* Ref.set(versionRef, newVersion);

package/v3/dist/cluster/to-entity.d.ts

@@ -1,5 +1,6 @@
 import { Machine } from "../machine.js";
 import { Schema } from "effect";
+import { Entity } from "@effect/cluster";
 import { Rpc } from "@effect/rpc";
 
 //#region src/cluster/to-entity.d.ts
@@ -21,9 +22,9 @@ interface ToEntityOptions {
  */
 type EntityRpcs<StateSchema extends Schema.Schema.Any, EventSchema extends Schema.Schema.Any> = readonly [Rpc.Rpc<"Send", Schema.Struct<{
   readonly event: EventSchema;
-}>, StateSchema, typeof Schema.Never, never>, Rpc.Rpc<"Ask", Schema.Struct<{
+}>, StateSchema, typeof Schema.Never>, Rpc.Rpc<"Ask", Schema.Struct<{
   readonly event: EventSchema;
-}>, typeof Schema.Unknown, typeof Schema.Never, never>, Rpc.Rpc<"GetState", typeof Schema.Void, StateSchema, typeof Schema.Never, never>];
+}>, typeof Schema.Unknown, typeof Schema.Never>, Rpc.Rpc<"GetState", typeof Schema.Void, StateSchema, typeof Schema.Never>];
 /**
  * Generate an Entity definition from a machine.
  *
@@ -59,6 +60,10 @@ declare const toEntity: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R>(machine: Machine<S, E, R, any, any, any>, options: ToEntityOptions) => any;
+}, R>(machine: Machine<S, E, R, any, any, any>, options: ToEntityOptions) => Entity.Entity<string, Rpc.Rpc<"Send", Schema.Struct<{
+  event: Schema.Schema<E, E, never>;
+}>, Schema.Schema<S, S, never>, typeof Schema.Never, never> | Rpc.Rpc<"Ask", Schema.Struct<{
+  event: Schema.Schema<E, E, never>;
+}>, typeof Schema.Unknown, typeof Schema.Never, never> | Rpc.Rpc<"GetState", typeof Schema.Void, Schema.Schema<S, S, never>, typeof Schema.Never, never>>;
 //#endregion
 export { EntityRpcs, ToEntityOptions, toEntity };

package/v3/dist/index.d.ts

@@ -5,7 +5,7 @@ import { HasSlotKeys, MachineContext, ProvideSlots, Slot, SlotCall, SlotCalls, S
 import { ActorExit, CellPhase, DefectPhase, Supervision } from "./supervision.js";
 import { ProcessEventResult } from "./internal/transition.js";
 import { BackgroundEffect, Durability, DurabilityCommit, HandlerContext, Lifecycle, Machine, MachineRef, MakeConfig, Recovery, RecoveryContext, SpawnEffect, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, machine_d_exports } from "./machine.js";
-import { ActorRef, ActorRefSync, ActorSystem, Default, SystemEvent, SystemEventListener, TransitionInfo } from "./actor.js";
+import { ActorRef, ActorRefSync, ActorScope, ActorSystem, Default, SystemEvent, SystemEventListener, TransitionInfo } from "./actor.js";
 import { SimulationResult, TestHarness, TestHarnessOptions, assertNeverReaches, assertPath, assertReaches, createTestHarness, simulate } from "./testing.js";
 import { AnyInspectionEvent, EffectEvent, ErrorEvent, EventReceivedEvent, InspectionEvent, Inspector, InspectorHandler, SpawnEvent, StopEvent, TaskEvent, TracingInspectorOptions, TransitionEvent, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, tracingInspector } from "./inspection.js";
-export { ActorExit, type ActorRef, type ActorRefSync, ActorStoppedError, type ActorSystem, Default as ActorSystemDefault, ActorSystem as ActorSystemService, type AnyInspectionEvent, AssertionError, type BackgroundEffect, type CellPhase, type DefectPhase, type DeferReplyResult, DuplicateActorError, type Durability, type DurabilityCommit, type EffectEvent, type ErrorEvent, Event, type EventReceivedEvent, type HandlerContext, type HasSlotKeys, type InspectionEvent, type Inspector, type InspectorHandler, Inspector as InspectorService, InvalidSchemaError, type Lifecycle, machine_d_exports as Machine, type MachineContext, type MachineEventSchema, type MachineRef, type MachineStateSchema, type Machine as MachineType, type MakeConfig, MissingMatchHandlerError, MissingSchemaError, NoReplyError, PersistenceError, type ProcessEventResult, type ProvideSlots, ProvisionValidationError, type Recovery, type RecoveryContext, type ReplyFields, type ReplyResult, type SimulationResult, Slot, type SlotCall, type SlotCalls, SlotCodecError, type SlotFnDef, type SlotHandler, type SlotInvocation, SlotProvisionError, type SlotRequest, type SlotResult, type SlotsDef, type SlotsSchema, type SpawnEffect, type SpawnEvent, State, type StateHandlerContext, type StopEvent, Supervision, type SystemEvent, type SystemEventListener, type TaskEvent, type TaskOptions, type TestHarness, type TestHarnessOptions, type TimeoutConfig, type TracingInspectorOptions, type Transition, type TransitionEvent, type TransitionInfo, VersionConflictError, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createTestHarness, makeInspector, makeInspectorEffect, simulate, tracingInspector };
+export { ActorExit, type ActorRef, type ActorRefSync, ActorScope, ActorStoppedError, type ActorSystem, Default as ActorSystemDefault, ActorSystem as ActorSystemService, type AnyInspectionEvent, AssertionError, type BackgroundEffect, type CellPhase, type DefectPhase, type DeferReplyResult, DuplicateActorError, type Durability, type DurabilityCommit, type EffectEvent, type ErrorEvent, Event, type EventReceivedEvent, type HandlerContext, type HasSlotKeys, type InspectionEvent, type Inspector, type InspectorHandler, Inspector as InspectorService, InvalidSchemaError, type Lifecycle, machine_d_exports as Machine, type MachineContext, type MachineEventSchema, type MachineRef, type MachineStateSchema, type Machine as MachineType, type MakeConfig, MissingMatchHandlerError, MissingSchemaError, NoReplyError, PersistenceError, type ProcessEventResult, type ProvideSlots, ProvisionValidationError, type Recovery, type RecoveryContext, type ReplyFields, type ReplyResult, type SimulationResult, Slot, type SlotCall, type SlotCalls, SlotCodecError, type SlotFnDef, type SlotHandler, type SlotInvocation, SlotProvisionError, type SlotRequest, type SlotResult, type SlotsDef, type SlotsSchema, type SpawnEffect, type SpawnEvent, State, type StateHandlerContext, type StopEvent, Supervision, type SystemEvent, type SystemEventListener, type TaskEvent, type TaskOptions, type TestHarness, type TestHarnessOptions, type TimeoutConfig, type TracingInspectorOptions, type Transition, type TransitionEvent, type TransitionInfo, VersionConflictError, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createTestHarness, makeInspector, makeInspectorEffect, simulate, tracingInspector };

package/v3/dist/index.js

@@ -3,7 +3,7 @@ import { Inspector, collectingInspector, combineInspectors, consoleInspector, ma
 import { Slot } from "./slot.js";
 import { machine_exports } from "./machine.js";
 import { ActorExit, Supervision } from "./supervision.js";
-import { ActorSystem, Default } from "./actor.js";
+import { ActorScope, ActorSystem, Default } from "./actor.js";
 import { Event, State } from "./schema.js";
 import { assertNeverReaches, assertPath, assertReaches, createTestHarness, simulate } from "./testing.js";
-export { ActorExit, ActorStoppedError, Default as ActorSystemDefault, ActorSystem as ActorSystemService, AssertionError, DuplicateActorError, Event, Inspector as InspectorService, InvalidSchemaError, machine_exports as Machine, MissingMatchHandlerError, MissingSchemaError, NoReplyError, PersistenceError, ProvisionValidationError, Slot, SlotCodecError, SlotProvisionError, State, Supervision, VersionConflictError, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createTestHarness, makeInspector, makeInspectorEffect, simulate, tracingInspector };
+export { ActorExit, ActorScope, ActorStoppedError, Default as ActorSystemDefault, ActorSystem as ActorSystemService, AssertionError, DuplicateActorError, Event, Inspector as InspectorService, InvalidSchemaError, machine_exports as Machine, MissingMatchHandlerError, MissingSchemaError, NoReplyError, PersistenceError, ProvisionValidationError, Slot, SlotCodecError, SlotProvisionError, State, Supervision, VersionConflictError, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createTestHarness, makeInspector, makeInspectorEffect, simulate, tracingInspector };

package/v3/dist/inspection.d.ts

@@ -93,7 +93,7 @@ type AnyInspectionEvent = InspectionEvent<{
 /**
  * Inspector interface for observing machine behavior
  */
-type InspectorHandler<S, E> = (event: InspectionEvent<S, E>) => void | Effect.Effect<void, never, never>;
+type InspectorHandler<S, E> = (event: InspectionEvent<S, E>) => void | Effect.Effect<void>;
 interface Inspector<S, E> {
   readonly onInspect: InspectorHandler<S, E>;
 }
@@ -119,7 +119,7 @@ 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>>;
+}>(onInspect: (event: InspectionEvent<ResolveType<S>, ResolveType<E>>) => Effect.Effect<void>) => 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);

package/v3/dist/inspection.js

@@ -106,30 +106,16 @@ const tracingInspector = (options) => ({ onInspect: (event) => {
 /**
 * Console inspector that logs events in a readable format
 */
-const consoleInspector = () => makeInspector((event) => {
+const consoleInspector = () => makeInspectorEffect((event) => {
 	const prefix = `[${event.actorId}]`;
 	switch (event.type) {
-		case "@machine.spawn":
-			console.log(prefix, "spawned →", event.initialState._tag);
-			break;
-		case "@machine.event":
-			console.log(prefix, "received", event.event._tag, "in", event.state._tag);
-			break;
-		case "@machine.transition":
-			console.log(prefix, event.fromState._tag, "→", event.toState._tag);
-			break;
-		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;
-		case "@machine.stop":
-			console.log(prefix, "stopped in", event.finalState._tag);
-			break;
+		case "@machine.spawn": return Effect.log(`${prefix} spawned -> ${event.initialState._tag}`);
+		case "@machine.event": return Effect.log(`${prefix} received ${event.event._tag} in ${event.state._tag}`);
+		case "@machine.transition": return Effect.log(`${prefix} ${event.fromState._tag} -> ${event.toState._tag}`);
+		case "@machine.effect": return Effect.log(`${prefix} ${event.effectType} effect in ${event.state._tag}`);
+		case "@machine.task": return Effect.log(`${prefix} task ${event.phase} ${event.taskName ?? "<unnamed>"} in ${event.state._tag}`);
+		case "@machine.error": return Effect.log(`${prefix} error in ${event.phase} ${event.state._tag} - ${String(event.error)}`);
+		case "@machine.stop": return Effect.log(`${prefix} stopped in ${event.finalState._tag}`);
 	}
 });
 /**

package/v3/dist/internal/runtime.d.ts

@@ -1,8 +1,8 @@
 import { NoReplyError } from "../errors.js";
-import { MachineContext, SlotsDef } from "../slot.js";
+import { SlotsDef } from "../slot.js";
 import { ActorExit } from "../supervision.js";
 import { ProcessEventHooks, ProcessEventResult } from "./transition.js";
-import { Machine, MachineRef } from "../machine.js";
+import { Machine } from "../machine.js";
 import { ActorSystem } from "../actor.js";
 import { Deferred, Effect, Queue, Ref, Scope, SubscriptionRef } from "effect";
 
@@ -27,7 +27,7 @@ type RuntimeQueuedEvent<E> = {
   readonly reply: Deferred.Deferred<unknown, NoReplyError>;
 } | {
   readonly _tag: "drain";
-  readonly done: Deferred.Deferred<void, never>;
+  readonly done: Deferred.Deferred<void>;
 };
 /**
  * Resources owned by the actor cell (stable across generations).
@@ -69,7 +69,7 @@ interface RuntimeHandle<S, E> {
    * Exit deferred — set exactly once with the exit reason when the runtime stops.
    * Final state → ActorExit.Final, explicit stop → ActorExit.Stopped, defect → ActorExit.Defect.
    */
-  readonly exitDeferred: Deferred.Deferred<ActorExit<S>, never>;
+  readonly exitDeferred: Deferred.Deferred<ActorExit<S>>;
   /**
    * Actor scope — owns background fibers for this generation.
    * Closing this scope interrupts all background fibers.
@@ -145,7 +145,7 @@ declare const createRuntime: <S extends {
   readonly _tag: string;
 }, R, SD extends SlotsDef>(machine: Machine<S, E, R, any, any, SD>, system: ActorSystem, config: RuntimeConfig<S, E>) => Effect.Effect<{
   stop: Effect.Effect<void, never, never>;
-  start: Effect.Effect<void, unknown, Exclude<R, MachineContext<S, E, MachineRef<E>>> | Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope>>;
+  start: Effect.Effect<void, unknown, unknown>;
   send: (event: E) => Effect.Effect<void>;
   sendWait: (event: E) => Effect.Effect<void, unknown>;
   ask: (event: E) => Effect.Effect<unknown, NoReplyError>;

package/v3/dist/internal/runtime.js

@@ -105,15 +105,13 @@ const createRuntime = Effect.fn("effect-machine.runtime.create")(function* (mach
 		}
 		if (lifecycle?.onInitialSpawnEffects !== void 0) yield* lifecycle.onInitialSpawnEffects(machine.initial);
 		const initialSpawnDefectSignal = (cause) => Deferred.succeed(exitDeferred, ActorExit.Defect(cause, "initial-spawn")).pipe(Effect.andThen(Ref.set(stoppedRef, true)), Effect.andThen(Effect.suspend(() => loopFiberRef.current !== void 0 ? Fiber.interrupt(loopFiberRef.current) : Effect.void)), Effect.asVoid);
-		yield* runSpawnEffects(machine, machine.initial, initEvent, self, stateScopeRef.current, system, actorId, hooks?.onError, initialSpawnDefectSignal).pipe(Effect.catchAllCause((cause) => {
-			return Effect.gen(function* () {
-				yield* Ref.set(stoppedRef, true);
-				yield* Scope.close(stateScopeRef.current, Exit.void);
-				yield* Scope.close(actorScope, Exit.void);
-				yield* Deferred.succeed(exitDeferred, ActorExit.Defect(cause, "initial-spawn"));
-				return yield* Effect.failCause(cause);
-			});
-		}));
+		yield* runSpawnEffects(machine, machine.initial, initEvent, self, stateScopeRef.current, system, actorId, hooks?.onError, initialSpawnDefectSignal).pipe(Effect.catchAllCause((cause) => Effect.gen(function* () {
+			yield* Ref.set(stoppedRef, true);
+			yield* Scope.close(stateScopeRef.current, Exit.void);
+			yield* Scope.close(actorScope, Exit.void);
+			yield* Deferred.succeed(exitDeferred, ActorExit.Defect(cause, "initial-spawn"));
+			return yield* Effect.failCause(cause);
+		})));
 		if (machine.finalStates.has(machine.initial._tag)) {
 			if (lifecycle?.onFinal !== void 0) yield* lifecycle.onFinal(machine.initial);
 			yield* Ref.set(stoppedRef, true);
@@ -262,13 +260,10 @@ const runtimeEventLoop = Effect.fn("effect-machine.runtime.eventLoop")(function*
 				if (result.hasReply) {
 					const replySchema = machine._replySchemas?.get(event._tag);
 					if (replySchema !== void 0) {
-						let decoded;
-						try {
-							decoded = Schema.decodeUnknownSync(replySchema)(result.reply);
-						} catch (decodeError) {
+						const decoded = yield* Schema.decodeUnknown(replySchema)(result.reply).pipe(Effect.catchAll((decodeError) => Effect.gen(function* () {
 							yield* Deferred.die(queued.reply, decodeError);
 							return yield* Effect.die(decodeError);
-						}
+						})));
 						yield* Deferred.succeed(queued.reply, decoded);
 					} else yield* Deferred.succeed(queued.reply, result.reply);
 				} else if (result.deferReply && deferredReplyRef !== void 0) deferredReplyRef.current = queued.reply;

package/v3/dist/machine.d.ts

@@ -10,7 +10,7 @@ import { Cause, Context, Duration, Effect, Option, Schema, Scope } from "effect"
 
 //#region src/machine.d.ts
 declare namespace machine_d_exports {
-  export { BackgroundEffect, DeferReplyResult, Durability, DurabilityCommit, HandlerContext, Lifecycle, Machine, MachineRef, MakeConfig, Recovery, RecoveryContext, ReplyResult, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, deferReply, findTransitions, make, materializeMachine, replay, reply, spawn };
+  export { BackgroundEffect, DeferReplyResult, Durability, DurabilityCommit, HandlerContext, Lifecycle, Machine, MachineRef, MakeConfig, Recovery, RecoveryContext, ReplyResult, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, deferReply, findTransitions, make, materializeMachine, replay, reply, scoped, spawn };
 }
 /**
  * Self reference for sending events back to the machine
@@ -362,6 +362,26 @@ declare const spawn: <S extends {
   supervision?: Supervision.Policy;
   lifecycle?: Lifecycle<S, E>;
 }) => Effect.Effect<ActorRef<S, E>, never, R>;
+/**
+ * Wrap an effect to provide an `ActorScope` from the current `Scope`.
+ *
+ * Actors spawned inside will attach cleanup finalizers to this scope,
+ * so they are automatically stopped when the scope closes.
+ *
+ * @example
+ * ```ts
+ * yield* Effect.scoped(
+ *   Machine.scoped(
+ *     Effect.gen(function* () {
+ *       const actor = yield* Machine.spawn(machine);
+ *       yield* actor.start;
+ *       // actor auto-stopped when scope closes
+ *     }),
+ *   ),
+ * );
+ * ```
+ */
+declare const scoped: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R | Scope.Scope>;
 declare const replay: {
   <S extends {
     readonly _tag: string;
@@ -375,4 +395,4 @@ declare const replay: {
 declare const reply: <State, Reply>(state: State, reply: Reply) => ReplyResult<State, Reply>;
 declare const deferReply: <State>(state: State) => DeferReplyResult<State>;
 //#endregion
-export { BackgroundEffect, type DeferReplyResult, Durability, DurabilityCommit, HandlerContext, Lifecycle, Machine, MachineRef, MakeConfig, Recovery, RecoveryContext, type ReplyResult, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, deferReply, findTransitions, machine_d_exports, make, materializeMachine, replay, reply, spawn };
+export { BackgroundEffect, type DeferReplyResult, Durability, DurabilityCommit, HandlerContext, Lifecycle, Machine, MachineRef, MakeConfig, Recovery, RecoveryContext, type ReplyResult, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, deferReply, findTransitions, machine_d_exports, make, materializeMachine, replay, reply, scoped, spawn };

package/v3/dist/machine.js

@@ -5,7 +5,7 @@ import { findTransitions, invalidateIndex, resolveTransition, runTransitionHandl
 import { emitWithTimestamp } from "./internal/inspection.js";
 import { Inspector } from "./inspection.js";
 import { MachineContextTag } from "./slot.js";
-import { createActor } from "./actor.js";
+import { ActorScope, createActor } from "./actor.js";
 import { Cause, Effect, Exit, Option, Random, Schema, Scope } from "effect";
 //#region src/machine.ts
 var machine_exports = /* @__PURE__ */ __exportAll({
@@ -16,6 +16,7 @@ var machine_exports = /* @__PURE__ */ __exportAll({
 	materializeMachine: () => materializeMachine,
 	replay: () => replay,
 	reply: () => reply,
+	scoped: () => scoped,
 	spawn: () => spawn
 });
 const emitTaskInspection = (input) => Effect.flatMap(Effect.serviceOption(Inspector), (inspector) => Option.isNone(inspector) ? Effect.void : emitWithTimestamp(inspector.value, (timestamp) => ({
@@ -177,7 +178,8 @@ var Machine = class Machine {
 		this._slots = this._slotsSchema !== void 0 ? this._slotsSchema._createSlots(resolve) : {};
 	}
 	from(stateOrStates, build) {
-		build(new TransitionScope(this, Array.isArray(stateOrStates) ? stateOrStates : [stateOrStates]));
+		const states = Array.isArray(stateOrStates) ? stateOrStates : [stateOrStates];
+		build(new TransitionScope(this, states));
 		return this;
 	}
 	/** @internal */
@@ -411,10 +413,30 @@ const spawn = Effect.fn("effect-machine.spawn")(function* (machine, idOrOptions)
 		supervision: opts?.supervision,
 		lifecycle: opts?.lifecycle
 	});
-	const maybeScope = yield* Effect.serviceOption(Scope.Scope);
+	const maybeScope = yield* Effect.serviceOption(ActorScope);
 	if (Option.isSome(maybeScope)) yield* Scope.addFinalizer(maybeScope.value, actor.stop);
 	return actor;
 });
+/**
+* Wrap an effect to provide an `ActorScope` from the current `Scope`.
+*
+* Actors spawned inside will attach cleanup finalizers to this scope,
+* so they are automatically stopped when the scope closes.
+*
+* @example
+* ```ts
+* yield* Effect.scoped(
+*   Machine.scoped(
+*     Effect.gen(function* () {
+*       const actor = yield* Machine.spawn(machine);
+*       yield* actor.start;
+*       // actor auto-stopped when scope closes
+*     }),
+*   ),
+* );
+* ```
+*/
+const scoped = (effect) => Effect.flatMap(Scope.Scope, (scope) => Effect.provideService(effect, ActorScope, scope));
 const replay = Effect.fn("effect-machine.replay")(function* (input, events, options) {
 	const machine = materializeMachine(input, options?.slots);
 	let state = options?.from ?? machine.initial;
@@ -462,4 +484,4 @@ const replay = Effect.fn("effect-machine.replay")(function* (input, events, opti
 const reply = makeReply;
 const deferReply = makeDeferReply;
 //#endregion
-export { Machine, deferReply, findTransitions, machine_exports, make, materializeMachine, replay, reply, spawn };
+export { Machine, deferReply, findTransitions, machine_exports, make, materializeMachine, replay, reply, scoped, spawn };

package/v3/dist/schema.d.ts

@@ -49,16 +49,23 @@ type VariantReplyBrand<Fields extends Schema.Struct.Fields> = Fields extends {
  * Empty structs: plain values with `_tag`: `State.Idle`
  * Non-empty structs require args: `State.Loading({ url })`
  *
- * Each variant also has a `derive` method for constructing from a source object.
+ * Each variant also has a `with` method for constructing from a source object,
+ * copying matching fields and overriding with a partial.
  * The source type uses `object` to accept branded state types without index signature issues.
  * Reply-bearing variants carry ReplyTypeBrand<R> for ask() type inference.
  */
 type VariantConstructors<D extends Record<string, Schema.Struct.Fields>, Brand> = { readonly [K in keyof D & string]: IsEmptyFields<D[K]> extends true ? TaggedStructType<K, D[K]> & Brand & VariantReplyBrand<D[K]> & {
-  readonly derive: (source: object) => TaggedStructType<K, D[K]> & Brand;
+  readonly with: (source: object) => TaggedStructType<K, D[K]> & Brand;
 } : ((args: Schema.Struct.Type<PayloadFields<D[K]>>) => TaggedStructType<K, D[K]> & Brand & VariantReplyBrand<D[K]>) & {
-  readonly derive: (source: object, partial?: Partial<Schema.Struct.Type<PayloadFields<D[K]>>>) => TaggedStructType<K, D[K]> & Brand;
+  readonly with: (source: object, partial?: Partial<Schema.Struct.Type<PayloadFields<D[K]>>>) => TaggedStructType<K, D[K]> & Brand;
   readonly _tag: K;
 } };
+/**
+ * Keys present in ALL variants (intersection of field names).
+ * Used by union-level `with` to accept only fields safe to update
+ * regardless of which variant the source is.
+ */
+type SharedKeys<D extends Record<string, Schema.Struct.Fields>> = keyof D[keyof D & string] & string;
 /**
  * Pattern matching cases type
  */
@@ -87,19 +94,23 @@ interface MachineSchemaBase<D extends Record<string, Schema.Struct.Fields>, Bran
     <R>(value: VariantsUnion<D> & Brand, cases: MatchCases<D, R>): R;
   };
   /**
-   * Union-level derive: copies fields from `source` into the same variant,
-   * overriding with `partial`. Preserves the specific variant subtype.
+   * Copy fields from `source` into the same variant, overriding with `partial`.
+   * Preserves the specific variant subtype in the return.
    *
-   * Dispatches to the per-variant `derive` based on `source._tag`.
+   * The partial accepts fields common to all variants, so it works safely
+   * when `S` is a generic type parameter (e.g., `<S extends MyState>`).
    *
    * @example
    * ```ts
-   * // Instead of switching on _tag to call per-variant derive:
-   * const updated = AgentLoopState.derive(state, { queue: newQueue })
-   * // If state is StreamingState, returns StreamingState (not LoopState)
+   * // Per-variant field update
+   * const next = MyState.Streaming.with(state, { draft: newDraft })
+   *
+   * // Cross-variant shared field — works with generic state
+   * const updateQueue = <S extends MyState>(state: S, queue: Queue): S =>
+   *   MyState.with(state, { queue })
    * ```
    */
-  readonly derive: <S extends VariantsUnion<D> & Brand>(source: S, partial?: Partial<Omit<S, "_tag">>) => S;
+  readonly with: <S extends VariantsUnion<D> & Brand>(source: S, partial?: Partial<Record<SharedKeys<D>, unknown>>) => S;
   /**
    * Reply schemas per variant tag. Only populated for event schemas
    * with variants defined via `Event.reply()`.
@@ -116,14 +127,16 @@ interface MachineSchemaBase<D extends Record<string, Schema.Struct.Fields>, Bran
  * The D type parameter captures the definition, creating a unique brand
  * per distinct schema definition shape.
  */
-type MachineStateSchema<D extends Record<string, Schema.Struct.Fields>> = Schema.Schema<VariantsUnion<D> & FullStateBrand<D>, unknown, never> & MachineSchemaBase<D, FullStateBrand<D>> & VariantConstructors<D, FullStateBrand<D>>;
+type MachineStateSchema<D extends Record<string, Schema.Struct.Fields>> = Schema.Schema<VariantsUnion<D> & FullStateBrand<D>, unknown> & MachineSchemaBase<D, FullStateBrand<D>> & VariantConstructors<D, FullStateBrand<D>> & {
+  /** Schema for persistence, config, and registration. */readonly schema: Schema.Schema<VariantsUnion<D> & FullStateBrand<D>>;
+};
 /**
  * Schema-first event definition (same structure as state, different brand)
  *
  * The D type parameter captures the definition, creating a unique brand
  * per distinct schema definition shape.
  */
-type MachineEventSchema<D extends Record<string, Schema.Struct.Fields>> = Schema.Schema<VariantsUnion<D> & FullEventBrand<D>, unknown, never> & MachineSchemaBase<D, FullEventBrand<D>> & VariantConstructors<D, FullEventBrand<D>>;
+type MachineEventSchema<D extends Record<string, Schema.Struct.Fields>> = Schema.Schema<VariantsUnion<D> & FullEventBrand<D>, unknown> & MachineSchemaBase<D, FullEventBrand<D>> & VariantConstructors<D, FullEventBrand<D>>;
 /**
  * Create a schema-first State definition.
  *

package/v3/dist/schema.js

@@ -62,7 +62,7 @@ const buildMachineSchema = (definition) => {
 				_tag: tag
 			});
 			constructor._tag = tag;
-			constructor.derive = (source, partial) => {
+			constructor.with = (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)) {
@@ -75,7 +75,7 @@ const buildMachineSchema = (definition) => {
 			constructors[tag] = constructor;
 		} else constructors[tag] = {
 			_tag: tag,
-			derive: () => ({ _tag: tag })
+			with: () => ({ _tag: tag })
 		};
 	}
 	const variantArray = Object.values(variants);
@@ -112,20 +112,21 @@ const buildMachineSchema = (definition) => {
 */
 const createMachineSchema = (definition) => {
 	const { schema, variants, constructors, _definition, replySchemas, $is, $match } = buildMachineSchema(definition);
-	const derive = (source, partial) => {
+	const withFn = (source, partial) => {
 		const ctor = constructors[source._tag];
 		if (ctor === void 0) throw new MissingMatchHandlerError({ tag: source._tag });
-		const deriveFn = ctor.derive;
-		if (deriveFn === void 0) throw new MissingMatchHandlerError({ tag: source._tag });
-		return deriveFn(source, partial);
+		const fn = ctor.with;
+		if (fn === void 0) throw new MissingMatchHandlerError({ tag: source._tag });
+		return fn(source, partial);
 	};
 	return Object.assign(Object.create(schema), {
 		variants,
 		_definition,
 		_replySchemas: replySchemas,
+		schema,
 		$is,
 		$match,
-		derive,
+		with: withFn,
 		...constructors
 	});
 };

package/v3/dist/slot.d.ts

@@ -40,7 +40,7 @@ interface SlotFnDef<F extends Fields = Fields, _Return = void> {
  */
 declare const fn: {
   <F extends Fields, S extends Schema.Schema.Any>(fields: F, returnSchema: S): SlotFnDef<F, Schema.Schema.Type<S>>;
-  <F extends Fields>(fields: F): SlotFnDef<F, void>;
+  <F extends Fields>(fields: F): SlotFnDef<F>;
 };
 /**
  * Record of slot definitions. Keys are slot names, values are SlotFnDef.
@@ -149,9 +149,10 @@ declare const define: <D extends SlotsDef>(definitions: D) => SlotsSchema<D>;
 declare const Slot: {
   readonly fn: {
     <F extends Fields, S extends Schema.Schema.Any>(fields: F, returnSchema: S): SlotFnDef<F, Schema.Schema.Type<S>>;
-    <F extends Fields>(fields: F): SlotFnDef<F, void>;
+    <F extends Fields>(fields: F): SlotFnDef<F>;
   };
   readonly define: <D extends SlotsDef>(definitions: D) => SlotsSchema<D>;
+  readonly of: <D extends SlotsDef>(slotsSchema: SlotsSchema<D>, provided: ProvideSlots<D>) => SlotCalls<D>;
 };
 //#endregion
 export { HasSlotKeys, MachineContext, MachineContextTag, ProvideSlots, Slot, SlotCall, SlotCalls, SlotFnDef, SlotHandler, SlotInvocation, SlotRequest, SlotResult, SlotsDef, SlotsSchema, define, fn };

package/v3/dist/slot.js

@@ -1,4 +1,4 @@
-import { Context, Schema } from "effect";
+import { Context, Effect, Schema } from "effect";
 //#region src/slot.ts
 /**
 * Slot module — unified, schema-based parameterized slots.
@@ -122,9 +122,44 @@ const define = (definitions) => {
 		}
 	};
 };
+/**
+* Convert raw slot handler implementations into the callable `SlotCalls` form.
+*
+* Handlers that return plain values are wrapped in `Effect.succeed`.
+* Handlers that return Effects are called directly inside `Effect.suspend`.
+*
+* @example
+* ```ts
+* const provided = yield* myExtension.slots(ctx)
+* const slots = Slot.of(slotsSchema, provided)
+* // slots.mySlot({ param: 1 }) returns Effect<ReturnType>
+* ```
+*/
+const of = (slotsSchema, provided) => {
+	const slots = {};
+	for (const name of Object.keys(slotsSchema.definitions)) {
+		const handler = provided[name];
+		if (handler === void 0) continue;
+		const call = (params) => Effect.suspend(() => {
+			const result = handler(params);
+			return Effect.isEffect(result) ? result : Effect.succeed(result);
+		});
+		Object.defineProperty(call, "_tag", {
+			value: "Slot",
+			enumerable: true
+		});
+		Object.defineProperty(call, "name", {
+			value: name,
+			enumerable: true
+		});
+		slots[name] = call;
+	}
+	return slots;
+};
 const Slot = {
 	fn,
-	define
+	define,
+	of
 };
 //#endregion
 export { MachineContextTag, Slot, define, fn };