effect-machine 0.11.0 → 0.13.0

package/dist/schema.js

@@ -38,6 +38,7 @@ import { Schema } from "effect";
 *
 * @module
 */
+const ReplySchemaSymbol = Symbol.for("effect-machine/ReplySchema");
 /**
 * Build a schema-first definition from a record of tag -> fields
 */
@@ -45,9 +46,14 @@ const RESERVED_DERIVE_KEYS = new Set(["_tag"]);
 const buildMachineSchema = (definition) => {
 	const variants = {};
 	const constructors = {};
+	const replySchemas = /* @__PURE__ */ new Map();
 	for (const tag of Object.keys(definition)) {
 		const fields = definition[tag];
 		if (fields === void 0) continue;
+		if (ReplySchemaSymbol in fields) {
+			const rs = fields[ReplySchemaSymbol];
+			if (rs !== void 0) replySchemas.set(tag, rs);
+		}
 		variants[tag] = Schema.TaggedStruct(tag, fields);
 		const fieldNames = new Set(Object.keys(fields));
 		if (fieldNames.size > 0) {
@@ -72,7 +78,7 @@ const buildMachineSchema = (definition) => {
 		};
 	}
 	const variantArray = Object.values(variants);
-	if (variantArray.length === 0) throw new InvalidSchemaError({});
+	if (variantArray.length === 0) throw new InvalidSchemaError({ message: "Schema must have at least one variant" });
 	const unionSchema = variantArray.length === 1 ? variantArray[0] : Schema.Union(variantArray);
 	const $is = (tag) => (u) => typeof u === "object" && u !== null && "_tag" in u && u._tag === tag;
 	const $match = (valueOrCases, maybeCases) => {
@@ -94,6 +100,7 @@ const buildMachineSchema = (definition) => {
 		variants,
 		constructors,
 		_definition: definition,
+		replySchemas,
 		$is,
 		$match
 	};
@@ -103,10 +110,11 @@ const buildMachineSchema = (definition) => {
 * Builds the schema object with variants, constructors, $is, and $match.
 */
 const createMachineSchema = (definition) => {
-	const { schema, variants, constructors, _definition, $is, $match } = buildMachineSchema(definition);
+	const { schema, variants, constructors, _definition, replySchemas, $is, $match } = buildMachineSchema(definition);
 	return Object.assign(Object.create(schema), {
 		variants,
 		_definition,
+		_replySchemas: replySchemas,
 		$is,
 		$match,
 		...constructors
@@ -149,19 +157,40 @@ const State = (definition) => createMachineSchema(definition);
 * accidental use of constructors from different event schemas
 * (unless they have identical definitions).
 *
+* Use `Event.reply(fields, replySchema)` to define events that support
+* typed `ask()` replies.
+*
 * @example
 * ```ts
-* const OrderEvent = MachineSchema.Event({
+* const OrderEvent = Event({
 *   Ship: { trackingId: Schema.String },
 *   Cancel: {},
+*   GetTotal: Event.reply({}, Schema.Number),
 * })
 *
 * type OrderEvent = typeof OrderEvent.Type
 *
 * // Construct
 * const e = OrderEvent.Ship({ trackingId: "abc" })
+*
+* // Typed ask
+* const total = yield* actor.ask(OrderEvent.GetTotal) // number
 * ```
 */
-const Event = (definition) => createMachineSchema(definition);
+const EventImpl = (definition) => createMachineSchema(definition);
+/**
+* Annotate event fields with a reply schema.
+* Events defined with `Event.reply(fields, replySchema)` enable typed `ask()`.
+*/
+const replyFieldsFn = (fields, replySchema) => {
+	const annotated = { ...fields };
+	Object.defineProperty(annotated, ReplySchemaSymbol, {
+		value: replySchema,
+		enumerable: false,
+		writable: false
+	});
+	return annotated;
+};
+const Event = Object.assign(EventImpl, { reply: replyFieldsFn });
 //#endregion
 export { Event, State };

package/dist/supervision.d.ts

@@ -0,0 +1,97 @@
+import { Cause, Duration, Schedule } from "effect";
+
+//#region src/supervision.d.ts
+/**
+ * Where in the actor lifecycle a defect occurred.
+ *
+ * - `transition` — during event handler execution
+ * - `spawn` — during state spawn effect execution
+ * - `background` — in a background effect fiber
+ * - `initial-spawn` — during initial state spawn effects (before event loop)
+ */
+type DefectPhase = "transition" | "spawn" | "background" | "initial-spawn";
+/**
+ * Terminal exit reason for an actor generation.
+ *
+ * - `Final` — machine reached a final state normally
+ * - `Stopped` — explicit `actor.stop` or `actor.drain`
+ * - `Defect` — unhandled error in the runtime
+ */
+type ActorExit<S> = {
+  readonly _tag: "Final";
+  readonly state: S;
+} | {
+  readonly _tag: "Stopped";
+} | {
+  readonly _tag: "Defect";
+  readonly cause: Cause.Cause<unknown>;
+  readonly phase: DefectPhase;
+};
+/** Constructors for ActorExit */
+declare const ActorExit: {
+  readonly Final: <S>(state: S) => ActorExit<S>;
+  readonly Stopped: ActorExit<never>;
+  readonly Defect: <S = never>(cause: Cause.Cause<unknown>, phase: DefectPhase) => ActorExit<S>;
+};
+/**
+ * Phase state for supervised actors. Serializes concurrent stop/restart/drain.
+ *
+ * Transitions:
+ * - `Running` → crash → `Restarting` → new runtime → `Running`
+ * - `Running` → explicit stop/drain → `Stopping` → `Terminated`
+ * - `Restarting` → explicit stop → `Stopping` → `Terminated`
+ *
+ * @internal
+ */
+type CellPhase<S> = {
+  readonly _tag: "Running";
+  readonly generation: number;
+} | {
+  readonly _tag: "Restarting";
+  readonly generation: number;
+} | {
+  readonly _tag: "Stopping";
+} | {
+  readonly _tag: "Terminated";
+  readonly exit: ActorExit<S>;
+};
+declare namespace Supervision {
+  /**
+   * Supervision policy for actor restart behavior.
+   *
+   * `schedule` controls restart timing and budget — schedule exhaustion means terminal stop.
+   * `shouldRestart` optionally classifies defects — return `false` to stop immediately
+   * without consuming the schedule.
+   */
+  interface Policy {
+    /** Schedule that controls restart timing. Exhaustion = terminal stop. */
+    readonly schedule: Schedule.Schedule<unknown>;
+    /**
+     * Optional classifier: given a defect exit, decide whether to restart or stop immediately.
+     * Default: always restart (let schedule handle budget).
+     */
+    readonly shouldRestart?: (exit: Extract<ActorExit<unknown>, {
+      readonly _tag: "Defect";
+    }>) => boolean;
+  }
+  /** No supervision — crashes are terminal. */
+  const none: Policy;
+  /**
+   * Restart on defect with max restarts within a window, optional backoff.
+   *
+   * @example
+   * ```ts
+   * Supervision.restart() // unlimited restarts, no backoff
+   * Supervision.restart({ maxRestarts: 3 }) // 3 restarts then terminal
+   * Supervision.restart({ maxRestarts: 3, within: "1 minute" }) // 3 within 1 min
+   * Supervision.restart({ backoff: Schedule.exponential("100 millis") })
+   * ```
+   */
+  const restart: (options?: {
+    readonly maxRestarts?: number;
+    readonly within?: Duration.Input;
+    readonly backoff?: Schedule.Schedule<unknown>;
+  }) => Policy;
+}
+//#endregion
+export { ActorExit, CellPhase, DefectPhase, Supervision };

package/dist/supervision.js

@@ -0,0 +1,42 @@
+import { Schedule } from "effect";
+//#region src/supervision.ts
+/**
+* Supervision types for actor lifecycle management.
+*
+* Core concepts:
+* - `ActorExit<S>` — why an actor stopped (final, explicit stop, or defect)
+* - `DefectPhase` — where in the lifecycle a defect occurred
+* - `Supervision.Policy` — Schedule-based restart policy
+* - `CellPhase<S>` — internal phase machine for serializing stop/restart/drain
+*
+* @module
+*/
+/** Constructors for ActorExit */
+const ActorExit = {
+	Final: (state) => ({
+		_tag: "Final",
+		state
+	}),
+	Stopped: { _tag: "Stopped" },
+	Defect: (cause, phase) => ({
+		_tag: "Defect",
+		cause,
+		phase
+	})
+};
+let Supervision;
+(function(_Supervision) {
+	_Supervision.none = { schedule: Schedule.recurs(0) };
+	_Supervision.restart = (options) => {
+		let schedule = Schedule.forever;
+		if (options?.maxRestarts !== void 0) {
+			const recurs = Schedule.recurs(options.maxRestarts);
+			if (options.within !== void 0) schedule = Schedule.both(recurs, Schedule.windowed(options.within));
+			else schedule = recurs;
+		}
+		if (options?.backoff !== void 0) schedule = Schedule.both(schedule, options.backoff);
+		return { schedule };
+	};
+})(Supervision || (Supervision = {}));
+//#endregion
+export { ActorExit, Supervision };

package/dist/testing.d.ts

@@ -1,11 +1,10 @@
-import { EffectsDef, GuardsDef, MachineContext } from "./slot.js";
 import { AssertionError } from "./errors.js";
-import { BuiltMachine, Machine, MachineRef } from "./machine.js";
+import { EffectsDef, GuardsDef, MachineContext } from "./slot.js";
+import { Machine, MachineRef } from "./machine.js";
 import { Effect, SubscriptionRef } from "effect";
 
 //#region src/testing.d.ts
-/** Accept either Machine or BuiltMachine for testing utilities. */
-type MachineInput<S, E, R, GD extends GuardsDef, EFD extends EffectsDef> = Machine<S, E, R, any, any, GD, EFD> | BuiltMachine<S, E, R>;
+type MachineInput<S, E, R, GD extends GuardsDef, EFD extends EffectsDef> = Machine<S, E, R, any, any, GD, EFD>;
 /**
  * Result of simulating events through a machine
  */
@@ -37,7 +36,9 @@ declare const simulate: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: MachineInput<S, E, R, GD, EFD>, events: readonly E[]) => Effect.Effect<{
+}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: MachineInput<S, E, R, GD, EFD>, events: readonly E[], options?: {
+  slots?: Record<string, any>;
+} | undefined) => Effect.Effect<{
   states: S[];
   finalState: S;
 }, never, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
@@ -48,7 +49,9 @@ declare const assertReaches: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: MachineInput<S, E, R, GD, EFD>, events: readonly E[], expectedTag: string) => Effect.Effect<S, AssertionError, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
+}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: MachineInput<S, E, R, GD, EFD>, events: readonly E[], expectedTag: string, options?: {
+  slots?: Record<string, any>;
+} | undefined) => Effect.Effect<S, AssertionError, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
 /**
  * Assert that a machine follows a specific path of state tags
  *
@@ -65,7 +68,9 @@ declare const assertPath: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: MachineInput<S, E, R, GD, EFD>, events: readonly E[], expectedPath: readonly string[]) => Effect.Effect<{
+}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: MachineInput<S, E, R, GD, EFD>, events: readonly E[], expectedPath: readonly string[], options?: {
+  slots?: Record<string, any>;
+} | undefined) => Effect.Effect<{
   states: S[];
   finalState: S;
 }, AssertionError, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
@@ -86,7 +91,9 @@ declare const assertNeverReaches: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: MachineInput<S, E, R, GD, EFD>, events: readonly E[], forbiddenTag: string) => Effect.Effect<{
+}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: MachineInput<S, E, R, GD, EFD>, events: readonly E[], forbiddenTag: string, options?: {
+  slots?: Record<string, any>;
+} | undefined) => Effect.Effect<{
   states: S[];
   finalState: S;
 }, AssertionError, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
@@ -107,6 +114,8 @@ interface TestHarnessOptions<S, E> {
    * Useful for logging or spying on transitions.
    */
   readonly onTransition?: (from: S, event: E, to: S) => void;
+  /** Slot handler implementations for machines with guards/effects. */
+  readonly slots?: Record<string, any>;
 }
 /**
  * Create a test harness for step-by-step testing.

package/dist/testing.js

@@ -1,9 +1,18 @@
 import { stubSystem } from "./internal/utils.js";
-import { AssertionError } from "./errors.js";
-import { BuiltMachine } from "./machine.js";
 import { executeTransition, shouldPostpone } from "./internal/transition.js";
+import { AssertionError } from "./errors.js";
+import { materializeMachine } from "./machine.js";
 import { Effect, SubscriptionRef } from "effect";
 //#region src/testing.ts
+const makeDummySelf = (label) => {
+	const dummySend = Effect.fn(label)((_event) => Effect.void);
+	return {
+		send: dummySend,
+		cast: dummySend,
+		spawn: () => Effect.die(`spawn not supported in ${label}`),
+		reply: () => Effect.succeed(false)
+	};
+};
 /**
 * Simulate a sequence of events through a machine without running an actor.
 * Useful for testing state transitions in isolation.
@@ -24,14 +33,9 @@ import { Effect, SubscriptionRef } from "effect";
 * expect(result.states).toHaveLength(3) // Idle -> Loading -> Success
 * ```
 */
-const simulate = Effect.fn("effect-machine.simulate")(function* (input, events) {
-	const machine = input instanceof BuiltMachine ? input._inner : input;
-	const dummySend = Effect.fn("effect-machine.testing.simulate.send")((_event) => Effect.void);
-	const dummySelf = {
-		send: dummySend,
-		cast: dummySend,
-		spawn: () => Effect.die("spawn not supported in simulation")
-	};
+const simulate = Effect.fn("effect-machine.simulate")(function* (input, events, options) {
+	const machine = materializeMachine(input, options?.slots);
+	const dummySelf = makeDummySelf("effect-machine.testing.simulate");
 	let currentState = machine.initial;
 	const states = [currentState];
 	const hasPostponeRules = machine.postponeRules.length > 0;
@@ -73,8 +77,8 @@ const simulate = Effect.fn("effect-machine.simulate")(function* (input, events)
 /**
 * Assert that a machine can reach a specific state given a sequence of events
 */
-const assertReaches = Effect.fn("effect-machine.assertReaches")(function* (input, events, expectedTag) {
-	const result = yield* simulate(input, events);
+const assertReaches = Effect.fn("effect-machine.assertReaches")(function* (input, events, expectedTag, options) {
+	const result = yield* simulate(input, events, options);
 	if (result.finalState._tag !== expectedTag) return yield* new AssertionError({ message: `Expected final state "${expectedTag}" but got "${result.finalState._tag}". States visited: ${result.states.map((s) => s._tag).join(" -> ")}` });
 	return result.finalState;
 });
@@ -90,8 +94,8 @@ const assertReaches = Effect.fn("effect-machine.assertReaches")(function* (input
 * )
 * ```
 */
-const assertPath = Effect.fn("effect-machine.assertPath")(function* (input, events, expectedPath) {
-	const result = yield* simulate(input, events);
+const assertPath = Effect.fn("effect-machine.assertPath")(function* (input, events, expectedPath, options) {
+	const result = yield* simulate(input, events, options);
 	const actualPath = result.states.map((s) => s._tag);
 	if (actualPath.length !== expectedPath.length) return yield* new AssertionError({ message: `Path length mismatch. Expected ${expectedPath.length} states but got ${actualPath.length}.\nExpected: ${expectedPath.join(" -> ")}\nActual:   ${actualPath.join(" -> ")}` });
 	for (let i = 0; i < expectedPath.length; i++) if (actualPath[i] !== expectedPath[i]) return yield* new AssertionError({ message: `Path mismatch at position ${i}. Expected "${expectedPath[i]}" but got "${actualPath[i]}".\nExpected: ${expectedPath.join(" -> ")}\nActual:   ${actualPath.join(" -> ")}` });
@@ -110,8 +114,8 @@ const assertPath = Effect.fn("effect-machine.assertPath")(function* (input, even
 * )
 * ```
 */
-const assertNeverReaches = Effect.fn("effect-machine.assertNeverReaches")(function* (input, events, forbiddenTag) {
-	const result = yield* simulate(input, events);
+const assertNeverReaches = Effect.fn("effect-machine.assertNeverReaches")(function* (input, events, forbiddenTag, options) {
+	const result = yield* simulate(input, events, options);
 	const visitedIndex = result.states.findIndex((s) => s._tag === forbiddenTag);
 	if (visitedIndex !== -1) return yield* new AssertionError({ message: `Machine reached forbidden state "${forbiddenTag}" at position ${visitedIndex}.\nStates visited: ${result.states.map((s) => s._tag).join(" -> ")}` });
 	return result;
@@ -138,13 +142,8 @@ const assertNeverReaches = Effect.fn("effect-machine.assertNeverReaches")(functi
 * ```
 */
 const createTestHarness = Effect.fn("effect-machine.createTestHarness")(function* (input, options) {
-	const machine = input instanceof BuiltMachine ? input._inner : input;
-	const dummySend = Effect.fn("effect-machine.testing.harness.send")((_event) => Effect.void);
-	const dummySelf = {
-		send: dummySend,
-		cast: dummySend,
-		spawn: () => Effect.die("spawn not supported in test harness")
-	};
+	const machine = materializeMachine(input, options?.slots);
+	const dummySelf = makeDummySelf("effect-machine.testing.harness");
 	const stateRef = yield* SubscriptionRef.make(machine.initial);
 	const hasPostponeRules = machine.postponeRules.length > 0;
 	const postponed = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect-machine",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/cevr/effect-machine.git"
@@ -56,20 +56,20 @@
     "release": "bun run build && changeset publish"
   },
   "dependencies": {
-    "effect": "4.0.0-beta.35"
+    "effect": "4.0.0-beta.42"
   },
   "devDependencies": {
     "@changesets/changelog-github": "^0.6.0",
     "@changesets/cli": "^2.30.0",
-    "@effect/language-service": "^0.82.0",
+    "@effect/language-service": "^0.84.2",
     "@types/bun": "1.3.11",
     "concurrently": "^9.2.1",
     "effect-bun-test": "0.3.0",
     "effect-v3": "npm:effect@^3.21.0",
     "lefthook": "^2.1.4",
-    "oxfmt": "^0.41.0",
-    "oxlint": "^1.56.0",
-    "tsdown": "^0.21.4",
+    "oxfmt": "^0.42.0",
+    "oxlint": "^1.57.0",
+    "tsdown": "^0.21.7",
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
@@ -81,6 +81,6 @@
     }
   },
   "overrides": {
-    "effect": "4.0.0-beta.35"
+    "effect": "4.0.0-beta.42"
   }
 }

package/v3/dist/actor.d.ts

@@ -1,29 +1,15 @@
-import { EffectsDef, GuardsDef, MachineContext } from "./slot.js";
+import { ActorExit, Supervision } from "./supervision.js";
+import { ExtractReply, ReplyTypeBrand } from "./internal/brands.js";
 import { ActorStoppedError, DuplicateActorError, NoReplyError } from "./errors.js";
+import { EffectsDef, GuardsDef } from "./slot.js";
 import { ProcessEventError, ProcessEventHooks, ProcessEventResult, processEventCore, resolveTransition, runSpawnEffects } from "./internal/transition.js";
-import { BuiltMachine, Machine, MachineRef } from "./machine.js";
+import { Machine } from "./machine.js";
+import { RuntimeQueuedEvent } from "./internal/runtime.js";
 import { Context, Deferred, Effect, Layer, Option, PubSub, Queue, Ref, Scope, Stream, SubscriptionRef } from "effect";
-import * as effect_dist_dts_Tracer_js0 from "effect/dist/dts/Tracer.js";
 
 //#region src/actor.d.ts
-/** Discriminated mailbox request */
-type QueuedEvent<E> = {
-  readonly _tag: "send";
-  readonly event: E;
-} | {
-  readonly _tag: "call";
-  readonly event: E;
-  readonly reply: Deferred.Deferred<ProcessEventResult<{
-    readonly _tag: string;
-  }>, ActorStoppedError>;
-} | {
-  readonly _tag: "ask";
-  readonly event: E;
-  readonly reply: Deferred.Deferred<unknown, NoReplyError | ActorStoppedError>;
-};
-/**
- * Reference to a running actor.
- */
+/** Discriminated mailbox request — alias for RuntimeQueuedEvent */
+type QueuedEvent<E> = RuntimeQueuedEvent<E>;
 /**
  * Sync projection of ActorRef for non-Effect boundaries (React hooks, framework callbacks).
  */
@@ -59,11 +45,11 @@ interface ActorRef<State extends {
    */
   readonly call: (event: Event) => Effect.Effect<ProcessEventResult<State>>;
   /**
-   * Typed request-reply. Event is processed through the queue; caller gets
-   * the domain value returned by the handler's `reply` field.
+   * Typed request-reply. Accepts only events with a reply schema
+   * (defined via `Event.reply()`). Return type is inferred from the schema.
    * Fails with NoReplyError if the handler doesn't provide a reply.
    */
-  readonly ask: <R>(event: Event) => Effect.Effect<R, NoReplyError | ActorStoppedError>;
+  readonly ask: <E extends Event & ReplyTypeBrand<unknown>>(event: E) => Effect.Effect<ExtractReply<E>, NoReplyError | ActorStoppedError>;
   /** Observable state. */
   readonly state: SubscriptionRef.SubscriptionRef<State>;
   /** Stop the actor gracefully. */
@@ -103,6 +89,25 @@ interface ActorRef<State extends {
   };
   /** Subscribe to state changes (sync callback). Returns unsubscribe function. */
   readonly subscribe: (fn: (state: State) => void) => () => void;
+  /**
+   * Wait for this actor's terminal exit. Resolves with the exit reason.
+   * Set exactly once when the actor terminates (final, stop, drain, or defect).
+   */
+  readonly awaitExit: Effect.Effect<ActorExit<State>>;
+  /**
+   * Watch another actor. Returns an Effect that resolves with the exit reason
+   * when the watched actor terminally stops. Ignores restarts.
+   * Built on the other actor's exitDeferred — authoritative, not system events.
+   */
+  readonly watch: (other: {
+    readonly id: string;
+    readonly awaitExit: Effect.Effect<ActorExit<unknown>>;
+  }) => Effect.Effect<ActorExit<unknown>>;
+  /**
+   * Drain: process all remaining events in the queue, then stop.
+   * Unlike `stop` (which interrupts immediately), `drain` lets the actor finish its work.
+   */
+  readonly drain: Effect.Effect<void>;
   /** Sync helpers for non-Effect boundaries. */
   readonly sync: ActorRefSync<State, Event>;
   /** The actor system this actor belongs to. */
@@ -121,10 +126,17 @@ type SystemEvent = {
   readonly _tag: "ActorSpawned";
   readonly id: string;
   readonly actor: ActorRef<AnyState, unknown>;
+} | {
+  readonly _tag: "ActorRestarted";
+  readonly id: string;
+  readonly actor: ActorRef<AnyState, unknown>;
+  readonly generation: number;
+  readonly exit: ActorExit<unknown>;
 } | {
   readonly _tag: "ActorStopped";
   readonly id: string;
   readonly actor: ActorRef<AnyState, unknown>;
+  readonly exit: ActorExit<unknown>;
 };
 /**
  * Listener callback for system events.
@@ -136,18 +148,15 @@ type SystemEventListener = (event: SystemEvent) => void;
 interface ActorSystem {
   /**
    * Spawn a new actor with the given machine.
-   *
-   * @example
-   * ```ts
-   * const built = machine.build({ fetchData: ... })
-   * const actor = yield* system.spawn("my-actor", built);
-   * ```
    */
   readonly spawn: <S extends {
     readonly _tag: string;
   }, E extends {
     readonly _tag: string;
-  }, R>(id: string, machine: BuiltMachine<S, E, R>) => Effect.Effect<ActorRef<S, E>, DuplicateActorError, R>;
+  }, R>(id: string, machine: Machine<S, E, R, any, any, any, any>, options?: {
+    slots?: Record<string, any>;
+    supervision?: Supervision.Policy;
+  }) => Effect.Effect<ActorRef<S, E>, DuplicateActorError, R>;
   /**
    * Get an existing actor by ID
    */
@@ -183,15 +192,16 @@ type Listeners<S> = Set<(state: S) => void>;
  */
 declare const notifyListeners: <S>(listeners: Listeners<S>, state: S) => void;
 /**
- * Build core ActorRef methods shared between regular and persistent actors.
+ * Build core ActorRef methods.
  */
 declare const buildActorRefCore: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, GD extends GuardsDef, EFD extends EffectsDef>(id: string, machine: Machine<S, E, R, any, any, GD, EFD>, stateRef: SubscriptionRef.SubscriptionRef<S>, eventQueue: Queue.Queue<QueuedEvent<E>>, stoppedRef: Ref.Ref<boolean>, listeners: Listeners<S>, stop: Effect.Effect<void>, system: ActorSystem, childrenMap: ReadonlyMap<string, ActorRef<AnyState, unknown>>, pendingReplies: Set<Deferred.Deferred<unknown, unknown>>, transitionsPubSub?: PubSub.PubSub<TransitionInfo<S, E>>) => ActorRef<S, E>;
+}, R, GD extends GuardsDef, EFD extends EffectsDef>(id: string, machine: Machine<S, E, R, any, any, GD, EFD>, stateRef: SubscriptionRef.SubscriptionRef<S>, eventQueueRef: Ref.Ref<Queue.Queue<QueuedEvent<E>>>, stoppedRef: Ref.Ref<boolean>, listeners: Listeners<S>, stop: Effect.Effect<void>, system: ActorSystem, childrenMap: ReadonlyMap<string, ActorRef<AnyState, unknown>>, pendingReplies: Set<Deferred.Deferred<unknown, unknown>>, transitionsPubSub: PubSub.PubSub<TransitionInfo<S, E>> | undefined, exitDeferred: Deferred.Deferred<ActorExit<S>, never>) => ActorRef<S, E>;
 /**
- * Create and start an actor for a machine
+ * Create and start an actor for a machine.
+ * Uses the shared runtime kernel with lifecycle hooks for actor-specific concerns.
  */
 declare const createActor: <S extends {
   readonly _tag: string;
@@ -199,12 +209,19 @@ declare const createActor: <S extends {
   readonly _tag: string;
 }, R, GD extends GuardsDef, EFD extends EffectsDef>(id: string, machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>, options?: {
   initialState?: S;
-} | undefined) => Effect.Effect<ActorRef<S, E>, never, Exclude<R, MachineContext<S, E, MachineRef<E>>> | Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, effect_dist_dts_Tracer_js0.ParentSpan> | Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope> | Exclude<Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope>, effect_dist_dts_Tracer_js0.ParentSpan>>;
+  supervision?: Supervision.Policy; /** @internal Called by system after each restart — emits ActorRestarted system event */
+  onRestart?: (generation: number, exit: ActorExit<unknown>) => Effect.Effect<void>;
+} | undefined) => Effect.Effect<ActorRef<S, E>, never, never>;
 /** Fail all pending call/ask Deferreds with ActorStoppedError. Safe to call multiple times. */
 declare const settlePendingReplies: (pendingReplies: Set<Deferred.Deferred<unknown, unknown>>, actorId: string) => Effect.Effect<void, never, never>;
+/**
+ * Create an ActorSystem instance. Must be run in a Scope.
+ * @internal — use Default layer for normal usage
+ */
+declare const makeSystem: () => Effect.Effect<ActorSystem, never, Scope.Scope>;
 /**
  * Default ActorSystem layer
  */
-declare const Default: Layer.Layer<ActorSystem, never, never>;
+declare const Default: Layer.Layer<ActorSystem, never, Scope.Scope>;
 //#endregion
-export { ActorRef, ActorRefSync, ActorSystem, Default, Listeners, type ProcessEventError, type ProcessEventHooks, type ProcessEventResult, QueuedEvent, SystemEvent, SystemEventListener, TransitionInfo, buildActorRefCore, createActor, notifyListeners, processEventCore, resolveTransition, runSpawnEffects, settlePendingReplies };
+export { ActorRef, ActorRefSync, ActorSystem, Default, Listeners, type ProcessEventError, type ProcessEventHooks, type ProcessEventResult, QueuedEvent, SystemEvent, SystemEventListener, TransitionInfo, buildActorRefCore, createActor, makeSystem, notifyListeners, processEventCore, resolveTransition, runSpawnEffects, settlePendingReplies };