@mantaq/core 0.0.3 → 0.2.0

package/README.md

@@ -10,18 +10,19 @@ npm install @mantaq/core
 
 ## Quick Reference
 
-| Pattern         | Correct                            | Anti-pattern                           |
-| --------------- | ---------------------------------- | -------------------------------------- |
-| Type context    | `context: {} as MyContext`         | casting in every handler               |
-| Type events     | `event("ID")<Payload>()`           | `event("ID")()` without generic        |
-| Send events     | `actor.send(event.create(data))`   | raw `{ id: "ID", ... }` objects        |
-| Effect data     | Use state payload                  | Depend on `event` in effect            |
-| Error handling  | Emit internal event                | Throw in effect or transition          |
-| Internal events | Declare in `internal: [...]`       | Put user events in internal            |
-| Signal check    | `if (signal.aborted) return`       | Skip abort check in async work         |
-| Regions         | Child outputs in parent `internal` | Forget to declare child outputs        |
-| Snapshot        | Save path + context manually       | Expect `snapshot()` to include context |
-| Any handler     | Universal events only (CANCEL)     | State-specific logic in `onAny`        |
+| Pattern         | Correct                                       | Anti-pattern                          |
+| --------------- | --------------------------------------------- | ------------------------------------- |
+| Type context    | `context: {} as MyContext`                    | casting in every handler              |
+| Write context   | `context.set({ ...context.get() })`           | mutate without `set()`                |
+| Type events     | `event("ID")<Payload>()`                      | `event("ID")()` without generic       |
+| Send events     | `actor.send(signInEvent.create(data))`        | raw `{ type: "ID", payload }` objects |
+| Effect data     | Use state payload                             | Depend on `event` in effect           |
+| Error handling  | Emit internal event                           | Throw in effect or transition         |
+| Internal events | Declare in `internal: [...]`                  | Put user events in internal           |
+| Signal check    | `if (signal.aborted) return`                  | Skip abort check in async work        |
+| Regions         | Child outputs in parent `internal`            | Forget to declare child outputs       |
+| Snapshot        | `snapshot()` carries path + context + payload | Re-serialize context by hand          |
+| Any handler     | Universal events only (CANCEL)                | State-specific logic in `onAny`       |
 
 ## Contents
 
@@ -41,6 +42,7 @@ npm install @mantaq/core
   - [Any Handler](#any-handler)
   - [Testing with VirtualClock](#testing-with-virtualclock)
 - [Development](#development)
+- [Testing](#testing)
 - [License](#license)
 
 ## Quick Start
@@ -94,20 +96,34 @@ const actor = new Actor({
   context: {} as AuthContext,
   setup: (m) => {
     m.on(idleState, signInEvent, (event, opts) => {
-      opts!.context.phoneNumber = event.phoneNumber; // ✅ typed
+      // ✅ typed — context.get()/set() flow the constructor type
+      opts!.context.set({ ...opts!.context.get(), phoneNumber: event.payload.phoneNumber });
       return { state: signingInState };
     });
   },
 });
 ```
 
+`set()` is the write signal — always call it to write, even when the new value is the same reference. Any `set()` triggers `change`. Spread the current value:
+
+```ts
+opts.context.set({ ...opts.context.get(), phoneNumber: event.payload.phoneNumber });
+```
+
+**Never mutate in place:**
+
+```ts
+// ❌ mutation without set() — never signals; subscribers and persistence stay silent
+opts!.context.phoneNumber = event.payload.phoneNumber;
+```
+
 **Anti-pattern — casting in every handler:**
 
 ```ts
 setup: (m) => {
   m.on(idleState, signInEvent, (event, opts) => {
     const c = opts!.context as AuthContext; // ❌ unnecessary — already typed
-    c.phoneNumber = event.phoneNumber;
+    c.set({ ...c.get(), phoneNumber: event.payload.phoneNumber });
     return { state: signingInState };
   });
 },
@@ -132,7 +148,7 @@ Handlers receive the correct payload type:
 ```ts
 setup: (m) => {
   m.on(idleState, signInEvent, (event) => {
-    event.phoneNumber; // ✅ string
+    event.payload.phoneNumber; // ✅ string
     return { state: signingInState };
   });
 },
@@ -155,12 +171,12 @@ const goodEvent = event("SIGN_IN")<{ phoneNumber: string }>();
 actor.send(signInEvent.create({ phoneNumber: "+1234567890" }));
 
 // ❌ bypasses type checking
-actor.send({ id: "SIGN_IN", phoneNumber: "+1234567890" });
+actor.send({ type: "SIGN_IN", payload: { phoneNumber: "+1234567890" } });
 ```
 
 ### Effects and Event Typing
 
-Effects run when entering a state. The `event` parameter in effects is typed as the union of all possible events (`Inputs[number] | Internal[number]`) — not the specific event that triggered the transition. This is by design: effects live on states, not transitions. Multiple transitions can lead to the same state, so the effect cannot know which event caused entry.
+Effects run when entering a state. The `event` parameter in effects is typed `InternalEvent` — `{ type, payload? }` with `payload: unknown` — not the specific event that triggered the transition. This is by design: effects live on states, not transitions. Multiple transitions can lead to the same state, so the effect cannot know which event caused entry.
 
 **Pass data to effects via state payload.** Set the payload in the transition return, read it from `state.payload` in the effect.
 
@@ -184,7 +200,7 @@ const actor = new Actor({
       });
     });
     m.on(idleState, fetchEvent, (event) => {
-      return { state: loadingState.create({ url: event.url }) };
+      return { state: loadingState.create({ url: event.payload.url }) };
     });
     m.on(loadingState, doneEvent, () => ({ state: loadedState }));
   },
@@ -195,10 +211,10 @@ const actor = new Actor({
 
 ```ts
 // ✅ state payload — scoped to this state entry
-return { state: loadingState.create({ url: event.url }) };
+return { state: loadingState.create({ url: event.payload.url }) };
 
 // ⚠️ context — works but shared across all states
-opts!.context.url = event.url;
+opts!.context.set({ ...opts!.context.get(), url: event.payload.url });
 return { state: loadingState };
 ```
 
@@ -206,9 +222,8 @@ return { state: loadingState };
 
 ```ts
 m.effect(loadingState, ({ event, emit }) => {
-  // ❌ event is the union type, not the specific triggering event
-  // event.url doesn't exist on the union
-  emit(doneEvent.create()); // fine — but event.url would be a type error
+  // ❌ event is InternalEvent — payload is unknown, not the triggering event's payload
+  emit(doneEvent.create()); // fine — but event.payload.url would be a type error
 });
 ```
 
@@ -289,7 +304,10 @@ function createActor() {
       m.on(idleState, startEvent, () => ({ state: workingState }));
       m.on(workingState, doneEvent, () => ({ state: doneState }));
       m.on(workingState, failedEvent, (_event, opts) => {
-        opts!.context.retryCount++;
+        opts!.context.set({
+          ...opts!.context.get(),
+          retryCount: opts!.context.get().retryCount + 1,
+        });
         return { state: errorState };
       });
     },
@@ -320,45 +338,29 @@ m.effect(workingState, ({ signal, emit, clock }) => {
 
 ### Snapshot & Restore
 
-`actor.snapshot()` returns a serializable `Snapshot` — `{ path, regions, done? }`. It does **not** include context. Use it to save/restore actor state across sessions.
+`actor.snapshot()` returns a `Snapshot` — `{ path, context, payload?, regions, done?, error? }`. Context is included; `payload` is the payload the current state was entered with (present only when the transition carried one). Use it to save/restore actor state across sessions.
 
 ```ts
-interface SerializedActor {
-  path: string[];
-  regions: Record<string, unknown>;
-  context: Record<string, unknown>;
-}
-
-function saveActor(actor: { snapshot(): Snapshot; context: unknown }): SerializedActor {
-  return {
-    ...actor.snapshot(),
-    context: { ...(actor.context as Record<string, unknown>) },
-  };
-}
-
-// Usage
-const saved = saveActor(actor);
+// Snapshot carries path, context, and regions — serialize it directly
+const saved = actor.snapshot();
 localStorage.setItem("actor", JSON.stringify(saved));
 
 const raw = localStorage.getItem("actor");
 if (raw) {
-  const data = JSON.parse(raw) as SerializedActor;
-  // restore from data.path and data.context
+  const data = JSON.parse(raw) as Snapshot;
+  // rebuild the actor from data.path (re-seed context from data.context if needed)
 }
 ```
 
-**Anti-pattern — trying to snapshot context via `snapshot()`:**
+**Anti-pattern — re-serializing context by hand:**
 
 ```ts
-// ❌ snapshot() only returns path + regions, not context
+// ❌ snapshot() already includes context — no manual step needed
 const snap = actor.snapshot();
-snap.context; // doesn't exist
+snap.context; // exists
 
-// ✅ serialize context yourself
-const stateData = {
-  path: actor.snapshot().path,
-  context: { ...actor.context },
-};
+// ✅ save the snapshot as-is
+const stateData = actor.snapshot();
 ```
 
 ### Dynamic Children (Regions)
@@ -374,10 +376,10 @@ const healthMonitor = new Actor({
   initial: unknownState,
   setup: (m) => {
     m.on(unknownState, healthCheckResult, (event) => ({
-      state: event.healthy ? healthyState : degradedState,
+      state: event.payload.healthy ? healthyState : degradedState,
     }));
     m.on(healthyState, healthCheckResult, (event) => ({
-      state: event.healthy ? healthyState : degradedState,
+      state: event.payload.healthy ? healthyState : degradedState,
     }));
   },
 });
@@ -391,7 +393,7 @@ const manager = new Actor({
   setup: (m) => {
     m.on(connectedState, healthCheckResult, (event, opts) => {
       // access child via actor.regions
-      manager.regions.health.send(healthCheckResult.create({ healthy: event.healthy }));
+      manager.regions.health.send(healthCheckResult.create({ healthy: event.payload.healthy }));
       return {};
     });
   },
@@ -424,7 +426,23 @@ const parent = new Actor({
 
 ### Error Handling
 
-Never throw from effects or transitions. Emit an error as an internal event and let a transition handle it. Errors thrown inside a handler or effect have no subscriber — the machine just stops applying it.
+Never throw from effects or transitions. Emit an error as an internal event and let a transition handle it. If user code throws anyway, the machine does **not** misbehave silently: it dies into a built-in terminal `__error` state, records `snapshot().error` (the thrown value, the state/context at the point of failure, the bad event), drops remaining events, and ignores later `send`s. Errors never escape `send()` and the machine stays deterministic — same inputs, same trace.
+
+```ts
+const snap = actor.snapshot();
+if (snap.error) {
+  snap.error.reason; // "transition" | "effect" | "budget" | "output" | "internal" | "async" | "unhandled"
+  snap.error.state.name; // the state at the point of failure
+  snap.error.event.type; // the bad event
+}
+```
+
+Two deliberate exceptions to "every failure is loud":
+
+- **Subscribers only watch.** They read snapshots and never change the machine, so a throwing `on("change")`/`on("done")`/`on("transition")` callback is swallowed — the machine and its callers are unaffected.
+- **Unhandled external events are ignored.** An event with no handler in the current state is dropped by design (broadcast fan-out, cross-state sends). An **internal** event with no handler, however, is a machine-authoring bug and routes to the error state (`reason: "unhandled"`).
+
+A dead machine can be manually resumed with `actor.recover({ state, context })` — an explicit, **inherently dangerous** escape hatch (the caller injects state and context, so determinism no longer holds). Effects are not re-run and timers are not re-armed; processing resumes on the next event. Prefer fixing the root cause and recreating the actor.
 
 Catch errors inside effects and emit recovery events:
 
@@ -448,7 +466,7 @@ setup: (m) => {
   m.on(workingState, doneEvent, () => ({ state: doneState }));
   m.on(workingState, failedEvent, (event) => {
     // handle error in transition, not in effect
-    return { state: errorState.create({ error: event.error }) };
+    return { state: errorState.create({ error: event.payload.error }) };
   });
 },
 ```
@@ -460,7 +478,7 @@ try {
   const result = riskyOperation();
   emit(doneEvent.create());
 } catch (err) {
-  throw err; // ❌ throw in effect — no handler, machine misbehaves
+  throw err; // ❌ throw in effect — the machine dies into __error
 }
 ```
 
@@ -468,7 +486,7 @@ try {
 
 ```ts
 m.on(idleState, submitEvent, (event) => {
-  if (!event.data) throw new Error("missing data"); // ❌ breaks the machine
+  if (!event.payload.data) throw new Error("missing data"); // ❌ kills the machine
   return { state: doneState };
 });
 ```
@@ -477,8 +495,8 @@ Prefer storing the error in context and transitioning to an error state:
 
 ```ts
 m.on(idleState, submitEvent, (event, opts) => {
-  if (!event.data) {
-    opts!.context.error = "missing data";
+  if (!event.payload.data) {
+    opts!.context.set({ ...opts!.context.get(), error: "missing data" });
     return { state: errorState };
   }
   return { state: doneState };
@@ -493,7 +511,7 @@ Use `onAny` to intercept events across all states — useful for universal error
 setup: (m) => {
   // CANCEL works from any state
   m.onAny(cancelEvent, (_event, opts) => {
-    opts!.context.cancelled = true;
+    opts!.context.set({ ...opts!.context.get(), cancelled: true });
     return { state: cancelledState };
   });
   // State-specific handlers still run for their state
@@ -507,13 +525,13 @@ setup: (m) => {
 setup: (m) => {
   // ❌ state-specific logic in onAny defeats the purpose
   m.onAny(submitBasicInfoEvent, (event, opts) => {
-    opts!.context.basicInfo = event; // wrong — only makes sense in basicInfo state
+    opts!.context.set({ ...opts!.context.get(), basicInfo: event }); // wrong — only makes sense in basicInfo state
     return { state: shippingAddressState };
   });
 
   // ✅ keep state-specific logic in state handlers
   m.on(basicInfoState, submitBasicInfoEvent, (event, opts) => {
-    opts!.context.basicInfo = event;
+    opts!.context.set({ ...opts!.context.get(), basicInfo: event });
     return { state: shippingAddressState };
   });
 },
@@ -652,6 +670,25 @@ vp test
 vp pack
 ```
 
+## Testing
+
+The package ships with a full test suite you can run and audit:
+
+```bash
+vp test          # feature + error + property tests
+vp check         # format, lint, typecheck (includes type-level contract tests)
+vp run mutation:core   # mutation score must stay ≥ 90
+```
+
+**Test contract.** Behavior is pinned by four kinds of tests, split by filename:
+
+- `*.test.ts` — features and happy paths, hand-maintained.
+- `*.error.test.ts` — failure paths: warnings, budgets, abort, unregistered, the `__error` state.
+- `*.property.test.ts` — property-based invariants against a reference model (fast-check, replayable via `MANTAQ_SEED`).
+- `*.mutation.test.ts` — directed tests that kill specific mutants; regenerable and thrown away between stryker runs.
+
+Coverage is analyzed per test (stryker `perTest` coverage analysis) so every mutant is attributed to the test that pins it. The mutation break threshold is 90 — a change that drops the score below 90 fails the build.
+
 ## License
 
 MIT

package/dist/actor-internal-B4iAxUG_.d.mts

@@ -0,0 +1,152 @@
+//#region src/state.d.ts
+declare function state<const T extends string>(id: T): <Payload = unknown>() => StateRef<T, Payload, false>;
+type AnyStateRef = StateRef<string, unknown, boolean>;
+interface RegionOptions {
+  initial: string;
+  states: Record<string, AnyStateRef>;
+}
+type RegionsOptions = Record<string, RegionOptions>;
+declare class StateRef<T extends string, Payload = unknown, IsFinal extends boolean = false> {
+  readonly name: T;
+  readonly isFinal: IsFinal;
+  /** @internal */ _regions: RegionsOptions | undefined;
+  constructor(name: T, isFinal: IsFinal);
+  regions(options: RegionsOptions): this;
+  final(): StateRef<T, Payload, true>;
+  create(payload: Payload): {
+    state: StateRef<T, Payload, IsFinal>;
+    payload: Payload;
+  };
+}
+//#endregion
+//#region src/event.d.ts
+declare function event<const T extends string>(type: T): <Payload extends object | void = void>() => EventRef<T, Payload>;
+type AnyEventRef = EventRef<string, object | void>;
+type InternalEvent = {
+  type: string;
+  payload?: unknown;
+};
+type CreatedOfEvent<T extends string, P> = P extends void ? {
+  type: T;
+} : {
+  type: T;
+  payload: P;
+};
+declare class EventRef<const T extends string, Payload extends object | void = void> {
+  readonly type: T;
+  constructor(type: T);
+  is(anyEvent: unknown): anyEvent is CreatedOfEvent<T, Payload>;
+  create(): Payload extends void ? {
+    type: T;
+  } : void;
+  create(payload: Payload): Payload extends void ? {
+    type: T;
+  } : {
+    type: T;
+    payload: Payload;
+  };
+}
+//#endregion
+//#region src/clock.d.ts
+interface Clock {
+  setTimeout(ms: number, cb: () => void, options?: {
+    signal?: AbortSignal;
+    eventName?: string;
+  }): number;
+  clearTimeout(id: number): void;
+  setInterval(ms: number, cb: () => void, options?: {
+    signal?: AbortSignal;
+  }): number;
+  clearInterval(id: number): void;
+  now(): number;
+  /** Optional hook for draining queues after clock advances (VirtualClock). */
+  setDrain?(fn: () => void): void;
+}
+//#endregion
+//#region src/context.d.ts
+declare class Context<T> {
+  #private;
+  constructor(get: () => T, set: (value: T) => void);
+  get(): T;
+  set(value: T): void;
+}
+//#endregion
+//#region src/actor-types.d.ts
+type CreatedOf<E extends AnyEventRef> = E extends EventRef<infer Type, infer P> ? CreatedOfEvent<Type, P> : never;
+type NonFinalStateRef<States extends AnyStateRef[]> = Extract<States[number], {
+  isFinal: false;
+}>;
+interface EffectInput<ActorContext, Payload = unknown> {
+  signal: AbortSignal;
+  state: {
+    name: string;
+    payload: Payload;
+  };
+  event: InternalEvent;
+  context: Context<ActorContext>;
+  emit: (event: InternalEvent) => void;
+  clock: Clock;
+}
+type EffectFn<ActorContext, Payload = unknown> = (input: EffectInput<ActorContext, Payload>) => void | Promise<void>;
+type ErrorReason = "transition" | "effect" | "budget" | "output" | "internal" | "async" | "unhandled";
+interface ErrorInfo {
+  error: unknown;
+  state: AnyStateRef;
+  context: unknown;
+  event: InternalEvent;
+  reason: ErrorReason;
+}
+interface TransitionInfo {
+  event: InternalEvent;
+  from: string;
+  to: string;
+  transitioned: boolean;
+}
+type ErrorState = StateRef<"__error", unknown, true>;
+type TransitionResult<AllowedState extends AnyStateRef = AnyStateRef, AllowedEmit extends string = string> = {
+  state?: AllowedState | {
+    state: AllowedState;
+    payload?: unknown;
+  };
+  payload?: unknown;
+  emit?: Array<{
+    type: AllowedEmit;
+    payload?: unknown;
+  }>;
+};
+//#endregion
+//#region src/actor-internal.d.ts
+interface Snapshot<C = unknown> {
+  path: string[];
+  context: C;
+  payload?: unknown;
+  regions: Record<string, Snapshot<unknown>>;
+  done?: boolean;
+  error?: ErrorInfo;
+}
+interface AnyActor<C = Record<string, unknown>> {
+  state: AnyStateRef;
+  clock: Clock;
+  regions: Record<string, AnyActor>;
+  send(event: AnyEventRef | InternalEvent): void;
+  snapshot(): Snapshot<C>;
+  on(event: "change", fn: (snapshot: Snapshot<C>, prev: Snapshot<C>) => void): () => void;
+  on(event: "done", fn: () => void): () => void;
+  on(event: "transition", fn: (info: TransitionInfo) => void): () => void;
+  recover(target: {
+    state: AnyStateRef;
+    context: C;
+  }): void;
+  settled(): Promise<void>;
+  context?: C;
+  options?: {
+    transitions?: Record<string, Record<string, unknown>>;
+    effects?: Record<string, unknown[]>;
+    states?: ReadonlyArray<{
+      name: string;
+      isFinal: boolean;
+    }>;
+  };
+}
+//#endregion
+export { InternalEvent as _, EffectInput as a, StateRef as b, ErrorState as c, TransitionResult as d, Context as f, EventRef as g, CreatedOfEvent as h, EffectFn as i, NonFinalStateRef as l, AnyEventRef as m, Snapshot as n, ErrorInfo as o, Clock as p, CreatedOf as r, ErrorReason as s, AnyActor as t, TransitionInfo as u, event as v, state as x, AnyStateRef as y };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { a as CreatedOfEvent, c as event, d as state, i as AnyEventRef, l as AnyStateRef, n as Snapshot, o as EventRef, r as Clock, s as InternalEvent, t as AnyActor, u as StateRef } from "./actor-internal-CBU_EDPZ.mjs";
+import { _ as InternalEvent, a as EffectInput, b as StateRef, c as ErrorState, d as TransitionResult, f as Context, g as EventRef, h as CreatedOfEvent, i as EffectFn, l as NonFinalStateRef, m as AnyEventRef, n as Snapshot, o as ErrorInfo, p as Clock, r as CreatedOf, s as ErrorReason, t as AnyActor, u as TransitionInfo, v as event, x as state, y as AnyStateRef } from "./actor-internal-B4iAxUG_.mjs";
 //#region src/real-clock.d.ts
 declare class RealClock implements Clock {
   #private;
@@ -38,44 +38,8 @@ declare class VirtualClock implements Clock {
   setDrain(fn: () => void): void;
 }
 //#endregion
-//#region src/context.d.ts
-declare class Context<T> {
-  #private;
-  constructor(get: () => T, set: (value: T) => void);
-  get(): T;
-  set(value: T): void;
-}
-//#endregion
-//#region src/actor-types.d.ts
-type CreatedOf<E extends AnyEventRef> = E extends EventRef<infer Id, infer P> ? CreatedOfEvent<Id, P> : never;
-type NonFinalStateRef<States extends AnyStateRef[]> = Extract<States[number], {
-  isFinal: false;
-}>;
-interface EffectInput<ActorContext, Payload = unknown> {
-  signal: AbortSignal;
-  state: {
-    name: string;
-    payload: Payload;
-  };
-  event: InternalEvent;
-  context: Context<ActorContext>;
-  emit: (event: InternalEvent) => void;
-  clock: Clock;
-}
-type EffectFn<ActorContext, Payload = unknown> = (input: EffectInput<ActorContext, Payload>) => void;
-type TransitionResult<AllowedState extends AnyStateRef = AnyStateRef, AllowedEmit extends string = string> = {
-  state?: AllowedState | {
-    state: AllowedState;
-    payload?: unknown;
-  };
-  payload?: unknown;
-  emit?: Array<{
-    id: AllowedEmit;
-  }>;
-};
-//#endregion
 //#region src/builder.d.ts
-type EventIdOf<E extends AnyEventRef> = E extends EventRef<infer Id, object | void> ? Id : never;
+type EventTypeOf<E extends AnyEventRef> = E extends EventRef<infer Type, object | void> ? Type : never;
 type PayloadOf<S extends AnyStateRef> = S extends StateRef<infer _Name, infer Payload, infer _IsFinal> ? Payload : never;
 type TransitionHandler<States extends readonly AnyStateRef[], ActorContext> = (event: InternalEvent, opts: {
   context: Context<ActorContext>;
@@ -87,25 +51,21 @@ interface BuiltMaps<States extends readonly AnyStateRef[], ActorContext> {
 }
 declare class ActorBuilder<States extends readonly AnyStateRef[], Inputs extends readonly AnyEventRef[], Internal extends readonly AnyEventRef[], Outputs extends readonly AnyEventRef[], ActorContext> {
   #private;
-  on<S extends States[number], E extends Inputs[number] | Internal[number]>(stateRef: S, eventRef: E, fn: (event: E extends EventRef<infer Id, infer P> ? CreatedOfEvent<Id, P> : never, opts: {
+  on<S extends States[number], E extends Inputs[number] | Internal[number]>(stateRef: S, eventRef: E, fn: (event: E extends EventRef<infer Type, infer P> ? CreatedOfEvent<Type, P> : never, opts: {
     context: Context<ActorContext>;
     actor: AnyActor;
-  }) => TransitionResult<States[number], EventIdOf<Outputs[number]>>): this;
-  onAny<E extends Inputs[number] | Internal[number]>(eventRef: E, fn: (event: E extends EventRef<infer Id, infer P> ? CreatedOfEvent<Id, P> : never, opts: {
+  }) => TransitionResult<States[number], EventTypeOf<Outputs[number]>>): this;
+  onAny<E extends Inputs[number] | Internal[number]>(eventRef: E, fn: (event: E extends EventRef<infer Type, infer P> ? CreatedOfEvent<Type, P> : never, opts: {
     context: Context<ActorContext>;
     actor: AnyActor;
-  }) => TransitionResult<States[number], EventIdOf<Outputs[number]>>): this;
+  }) => TransitionResult<States[number], EventTypeOf<Outputs[number]>>): this;
   effect<S extends States[number]>(stateRef: S, fn: EffectFn<ActorContext, PayloadOf<S>>): this;
   /** @internal */ build(): BuiltMaps<States, ActorContext>;
 }
 type SetupFn<States extends readonly AnyStateRef[], Inputs extends readonly AnyEventRef[], Internal extends readonly AnyEventRef[], Outputs extends readonly AnyEventRef[], ActorContext> = (m: ActorBuilder<States, Inputs, Internal, Outputs, ActorContext>) => void;
 //#endregion
 //#region src/actor.d.ts
-type CreatedOf$1<E extends AnyEventRef> = E extends EventRef<infer Id, infer P> ? (P extends void ? {
-  id: Id;
-} : P & {
-  id: Id;
-}) : never;
+type CreatedOf$1<E extends AnyEventRef> = E extends EventRef<infer Type, infer P> ? CreatedOfEvent<Type, P> : never;
 type InitialState<S extends AnyStateRef> = S extends StateRef<infer _N extends string, infer P> ? [unknown] extends [P] ? S | {
   state: S;
   payload?: P;
@@ -125,18 +85,9 @@ interface ActorOptions<States extends readonly AnyStateRef[], Inputs extends rea
   setup: SetupFn<States, Inputs, Internal, Outputs, ActorContext>;
   regions?: Record<string, AnyActor>;
 }
-interface InternalActorOptions<States extends readonly AnyStateRef[], Inputs extends readonly AnyEventRef[], Internal extends readonly AnyEventRef[], Outputs extends readonly AnyEventRef[], ActorContext = Record<string, unknown>> {
-  inputs: Inputs;
-  outputs?: Outputs;
-  internal?: Internal;
-  states: States;
-  context?: ActorContext;
-  initial: InitialState<States[number]>;
-  clock?: Clock;
-  internalBudget?: number;
+interface InternalActorOptions<States extends readonly AnyStateRef[], Inputs extends readonly AnyEventRef[], Internal extends readonly AnyEventRef[], Outputs extends readonly AnyEventRef[], ActorContext = Record<string, unknown>> extends Omit<ActorOptions<States, Inputs, Internal, Outputs, ActorContext>, "setup"> {
   transitions: TransitionDispatch<States, ActorContext>;
   effects: Record<string, Array<EffectFn<ActorContext>>>;
-  regions?: Record<string, AnyActor>;
 }
 type TransitionDispatch<States extends readonly AnyStateRef[], ActorContext> = Record<string, Record<string, ((event: InternalEvent, options: {
   context: Context<ActorContext>;
@@ -144,7 +95,7 @@ type TransitionDispatch<States extends readonly AnyStateRef[], ActorContext> = R
 }) => TransitionResult<States[number], string>) | undefined>>;
 declare class Actor<const States extends readonly AnyStateRef[], const Inputs extends readonly AnyEventRef[], const Internal extends readonly AnyEventRef[] = readonly [], const Outputs extends readonly AnyEventRef[] = readonly [], ActorContext = Record<string, unknown>> {
   #private;
-  state: States[number];
+  state: States[number] | ErrorState;
   readonly clock: Clock;
   get context(): ActorContext;
   get regions(): Record<string, AnyActor>;
@@ -152,9 +103,20 @@ declare class Actor<const States extends readonly AnyStateRef[], const Inputs ex
   constructor(options: ActorOptions<States, Inputs, Internal, Outputs, ActorContext>);
   on(event: "change", fn: (snapshot: Snapshot<ActorContext>, prev: Snapshot<ActorContext>) => void): () => void;
   on(event: "done", fn: () => void): () => void;
+  on(event: "transition", fn: (info: TransitionInfo) => void): () => void;
   settled(): Promise<void>;
   send(event: CreatedOf$1<Inputs[number]>): void;
+  /**
+   * Manually restore the actor to a live state after a fatal `__error`.
+   * DANGER: the caller supplies state and context, so the trajectory is no
+   * longer deterministic ("same inputs, same trace"). Effects are not re-run
+   * and timers are not re-armed — processing resumes on the next event.
+   */
+  recover(target: {
+    state: States[number];
+    context: ActorContext;
+  }): void;
   snapshot(): Snapshot<ActorContext>;
 }
 //#endregion
-export { Actor, type ActorBuilder, type AnyActor, type AnyEventRef, type AnyStateRef, type Clock, Context, type CreatedOf, type CreatedOfEvent, type EffectFn, type EffectInput, EventRef, type InternalEvent, type NonFinalStateRef, RealClock, type SetupFn, type Snapshot, StateRef, VirtualClock, event, state };
+export { Actor, type ActorBuilder, type ActorOptions, type AnyActor, type AnyEventRef, type AnyStateRef, type BuiltMaps, type Clock, Context, type CreatedOf, type CreatedOfEvent, type EffectFn, type EffectInput, type ErrorInfo, type ErrorReason, type ErrorState, EventRef, type EventTypeOf, type InitialState, type InternalEvent, type NonFinalStateRef, type PayloadOf, RealClock, type SetupFn, type Snapshot, StateRef, type TransitionHandler, type TransitionInfo, type TransitionResult, VirtualClock, event, state };

package/dist/index.mjs

@@ -1,4 +1,5 @@
 import { registerActor, setOutputHandler } from "./internal.mjs";
+import { Either } from "@mantaq/utils";
 //#region src/state.ts
 function state(id) {
 	return () => new StateRef(id, false);
@@ -85,13 +86,23 @@ var VirtualClock = class {
 	now() {
 		return this.#now;
 	}
+	/**
+	* Delay normalization: NaN and ±Infinity throw (programmer error); negative
+	* and 0 clamp to 0 for timeouts like the platform, to a 1ms floor for
+	* intervals (a 0ms interval would spin the synchronous advance loop
+	* forever). Finite positive values schedule at their real deadline.
+	*/
+	#delay(ms, method, interval) {
+		if (!Number.isFinite(ms)) throw new RangeError(`[VirtualClock] invalid ${method} ms value: ${ms}`);
+		return ms <= 0 ? interval ? 1 : 0 : ms;
+	}
 	setTimeout(ms, cb, options) {
 		const signal = options?.signal;
 		if (signal?.aborted) return -1;
 		const id = this.#nextId++;
 		const onAbort = trackAbort(signal, id, this.#timers);
 		this.#timers.set(id, {
-			deadline: this.#now + ms,
+			deadline: this.#now + this.#delay(ms, "setTimeout", false),
 			cb,
 			signal,
 			onAbort,
@@ -111,9 +122,10 @@ var VirtualClock = class {
 		if (signal?.aborted) return -1;
 		const id = this.#nextId++;
 		const onAbort = trackAbort(signal, id, this.#intervals);
+		const d = this.#delay(ms, "setInterval", true);
 		this.#intervals.set(id, {
-			ms,
-			next: this.#now + ms,
+			ms: d,
+			next: this.#now + d,
 			cb,
 			signal,
 			onAbort
@@ -164,7 +176,8 @@ var VirtualClock = class {
 		}
 	}
 	advance(ms) {
-		const target = this.#now + ms;
+		if (!Number.isFinite(ms)) throw new RangeError(`[VirtualClock] invalid advance ms value: ${ms}`);
+		const target = this.#now + Math.max(0, ms);
 		while (true) {
 			const deadline = this.#findEarliestDeadline(target);
 			if (deadline === null) break;
@@ -203,9 +216,6 @@ var InternalQueue = class {
 	get length() {
 		return this.#queue.length - this.#index;
 	}
-	get isProcessing() {
-		return this.#processing;
-	}
 	push(...events) {
 		if (this.#stopped) return;
 		this.#queue.push(...events);
@@ -216,12 +226,6 @@ var InternalQueue = class {
 			this.#settledResolvers.push(resolve);
 		});
 	}
-	process(processEvent) {
-		this.#process((event) => {
-			processEvent(event);
-			return true;
-		});
-	}
 	processCancellable(processEvent) {
 		this.#process(processEvent);
 	}
@@ -254,35 +258,48 @@ var InternalQueue = class {
 var Subscribers = class {
 	change = /* @__PURE__ */ new Set();
 	done = /* @__PURE__ */ new Set();
+	transition = /* @__PURE__ */ new Set();
 	#last = null;
 	seed(snapshot) {
 		this.#last = snapshot;
 	}
 	addChange(fn) {
 		this.change.add(fn);
-		if (this.#last) fn(this.#last, this.#last);
+		const last = this.#last;
+		if (last) this.#safe(() => fn(last, last));
 		return () => this.change.delete(fn);
 	}
 	addDone(fn) {
 		this.done.add(fn);
 		return () => this.done.delete(fn);
 	}
+	addTransition(fn) {
+		this.transition.add(fn);
+		return () => this.transition.delete(fn);
+	}
 	emitChange(snapshot) {
 		const prev = this.#last ?? snapshot;
 		this.#last = snapshot;
-		for (const fn of this.change) fn(snapshot, prev);
+		for (const fn of this.change) this.#safe(() => fn(snapshot, prev));
 	}
 	emitDone() {
-		for (const fn of this.done) fn();
+		for (const fn of this.done) this.#safe(fn);
+	}
+	emitTransition(info) {
+		for (const fn of this.transition) this.#safe(() => fn(info));
 	}
 	clear() {
 		this.change.clear();
 		this.done.clear();
+		this.transition.clear();
+	}
+	#safe(fn) {
+		Either.from(fn);
 	}
 };
 //#endregion
 //#region src/snapshot.ts
-function buildSnapshot(s, regions, context) {
+function buildSnapshot(s, regions, context, opts = {}) {
 	const path = [s.name];
 	const regionSnapshots = {};
 	for (const [regionName, child] of Object.entries(regions)) regionSnapshots[regionName] = child.snapshot();
@@ -291,28 +308,41 @@ function buildSnapshot(s, regions, context) {
 		context,
 		regions: regionSnapshots
 	};
+	if (opts.payload !== void 0) snap.payload = opts.payload;
 	if (s.isFinal) snap.done = true;
+	if (opts.error !== void 0) snap.error = opts.error;
 	return snap;
 }
 //#endregion
 //#region src/effects.ts
 function runEffects(options) {
-	if (options.state.isFinal) return null;
+	const pending = [];
 	const list = options.effects[options.state.name];
-	if (!list || list.length === 0) return null;
-	const abort = new AbortController();
-	for (const effectFn of list) effectFn({
-		signal: abort.signal,
-		state: {
-			name: options.state.name,
-			payload: options.statePayload
-		},
-		event: options.event,
-		context: options.context,
-		emit: options.emit,
-		clock: options.clock
-	});
-	return abort;
+	if (!list) return { pending };
+	for (const effectFn of list) {
+		if (options.abort.signal.aborted) break;
+		const attempt = Either.from(() => effectFn({
+			signal: options.abort.signal,
+			state: {
+				name: options.state.name,
+				payload: options.statePayload
+			},
+			event: options.event,
+			context: options.context,
+			emit: options.emit,
+			clock: options.clock
+		}));
+		if (attempt[0] !== void 0) {
+			options.onError(attempt[0], options.lastGood);
+			break;
+		}
+		const out = attempt[1];
+		if (out instanceof Promise) pending.push(out.catch((error) => {
+			if (options.abort.signal.aborted) return;
+			options.onError(error, options.lastGood);
+		}));
+	}
+	return { pending };
 }
 //#endregion
 //#region src/dispatch.ts
@@ -350,13 +380,13 @@ var ActorBuilder = class {
 	#effects = {};
 	on(stateRef, eventRef, fn) {
 		const sName = stateRef.name;
-		const eId = eventRef.id;
-		(this.#transitions[sName] ??= {})[eId] = fn;
+		const eType = eventRef.type;
+		(this.#transitions[sName] ??= {})[eType] = fn;
 		return this;
 	}
 	onAny(eventRef, fn) {
-		const eId = eventRef.id;
-		(this.#transitions["Any"] ??= {})[eId] = fn;
+		const eType = eventRef.type;
+		(this.#transitions["Any"] ??= {})[eType] = fn;
 		return this;
 	}
 	effect(stateRef, fn) {
@@ -372,11 +402,8 @@ var ActorBuilder = class {
 };
 //#endregion
 //#region src/actor.ts
-function pickState(initial) {
-	return initial instanceof StateRef ? initial : initial.state;
-}
 function resolveInitial(initial) {
-	return pickState(initial);
+	return initial instanceof StateRef ? initial : initial.state;
 }
 var Actor = class {
 	state;
@@ -412,7 +439,7 @@ var Actor = class {
 			setOutputHandler: (fn) => {
 				this.#outputHandler = fn;
 			},
-			pushInternal: (event) => this.#pushEvent(event),
+			pushInternal: (event) => this.#queue.push(event),
 			drainInternal: () => this.#drainInternal(),
 			abortEffects: () => this.#abortEffects()
 		});
@@ -424,47 +451,73 @@ var Actor = class {
 			transitions: built.transitions,
 			effects: built.effects
 		};
-		this.#internalIds = new Set((options.internal ?? []).map((e) => e.id));
-		this.#inputIds = new Set(options.inputs.map((e) => e.id));
+		this.#internalIds = new Set((options.internal ?? []).map((e) => e.type));
+		this.#inputIds = new Set(options.inputs.map((e) => e.type));
 		this.#internalBudget = options.internalBudget ?? 1e4;
 		this.clock = options.clock ?? new RealClock();
 		this.clock.setDrain?.(() => this.#drainInternal());
 		const initState = resolveInitial(options.initial);
 		const stateNames = new Set(options.states.map((s) => s.name));
-		if (!stateNames.has(initState.name)) console.warn(`[Actor] initial state "${initState.name}" not found in declared states [${[...stateNames].join(", ")}]`);
+		if (!stateNames.has(initState.name)) throw new Error(`[Actor] initial state "${initState.name}" not found in declared states [${[...stateNames].join(", ")}]`);
 		this.state = initState;
+		this.#statePayload = options.initial instanceof StateRef ? void 0 : options.initial.payload;
 		this.#context = options.context ?? {};
 		this.#lastState = initState;
 		this.#contextHandle = new Context(() => this.#context, (value) => {
 			this.#context = value;
 			this.#contextWritten = true;
 		});
-		this.#subs.seed(this.snapshot());
 		if (options.regions) for (const [key, child] of Object.entries(options.regions)) {
 			this.#regions[key] = child;
 			const result = setOutputHandler(child, (event) => {
 				this.#queue.push(event);
 				this.#drainInternal();
 			});
-			if (result[0] !== void 0) console.error(result[0].message);
+			if (result[0] !== void 0) throw new Error(result[0].message);
 			this.#children.set(key, child);
 		}
+		this.#runEffects({ type: "__init" }, this.#statePayload);
+		this.#subs.seed(this.snapshot());
 	}
 	on(event, fn) {
 		if (event === "change") {
 			const cb = fn;
 			return this.#subs.addChange(cb);
 		}
+		if (event === "done") {
+			const cb = fn;
+			return this.#subs.addDone(cb);
+		}
 		const cb = fn;
-		return this.#subs.addDone(cb);
+		return this.#subs.addTransition(cb);
 	}
 	settled() {
-		return this.#queue.settled();
+		return Promise.all([this.#queue.settled(), ...this.#pendingEffects]).then(() => void 0);
 	}
 	send(event) {
 		this.#dispatch(event);
 		this.#emitChangeIfDirty();
 	}
+	/**
+	* Manually restore the actor to a live state after a fatal `__error`.
+	* DANGER: the caller supplies state and context, so the trajectory is no
+	* longer deterministic ("same inputs, same trace"). Effects are not re-run
+	* and timers are not re-armed — processing resumes on the next event.
+	*/
+	recover(target) {
+		if (this.#error === null) return;
+		this.#error = null;
+		this.#queue = new InternalQueue();
+		this.#effectAbort = null;
+		this.state = target.state;
+		this.#statePayload = void 0;
+		this.#context = target.context;
+		this.#lastState = target.state;
+		this.#contextWritten = false;
+		this.#entry = null;
+		this.#pendingEffects = [];
+		this.#subs.emitChange(this.snapshot());
+	}
 	#emitChangeIfDirty() {
 		if (this.state === this.#lastState && !this.#contextWritten) return;
 		this.#lastState = this.state;
@@ -472,120 +525,240 @@ var Actor = class {
 		this.#subs.emitChange(this.snapshot());
 	}
 	#dispatch(event) {
-		if (this.state.isFinal) return;
-		const transitions = this.#options.transitions;
-		const stateTransition = transitions[this.state.name]?.[event.id];
-		const anyTransition = transitions["Any"]?.[event.id];
-		const transitionApplied = stateTransition ? this.#applyStateStep(event, stateTransition) : false;
-		if ((anyTransition ? this.#applyAnyStep(event, anyTransition, !transitionApplied) : false) || this.#queue.length > 0) this.#drainInternal();
-		else if (!stateTransition && !anyTransition) console.warn(`[Actor] no transition for event "${event.id}" in state "${this.state.name}". Event dropped.`);
+		if (this.#error !== null || this.state.isFinal) return;
+		const normalized = {
+			...event,
+			payload: event.payload ?? {}
+		};
+		const from = this.state.name;
+		const prev = this.#entry;
+		this.#entry = {
+			state: this.state,
+			context: this.#context
+		};
+		try {
+			const transitions = this.#options.transitions;
+			const stateTransition = transitions[this.state.name]?.[event.type];
+			const anyTransition = transitions["Any"]?.[event.type];
+			const result = this.#step(normalized, stateTransition, anyTransition);
+			this.#maybeEmitTransition(normalized, from, Boolean(stateTransition || anyTransition), result);
+			if (result.emitted || this.#queue.length > 0) this.#drainInternal();
+			else if (!stateTransition && !anyTransition) {
+				if (this.#internalIds.has(event.type)) this.#enterError("unhandled", event, /* @__PURE__ */ new Error(`[Actor] internal event "${event.type}" emitted but no handler in state "${this.state.name}"`));
+			}
+		} finally {
+			this.#entry = prev;
+		}
+	}
+	#step(normalized, stateTransition, anyTransition) {
+		const stateOutcome = stateTransition ? this.#applyStateStep(normalized, stateTransition) : { applied: false };
+		if (this.#error === null) {
+			const anyOutcome = this.#applyAnyStep(normalized, anyTransition, !stateOutcome.applied);
+			return {
+				emitted: anyOutcome.emitted,
+				transitioned: stateOutcome.applied || anyOutcome.transitioned,
+				target: stateOutcome.target ?? anyOutcome.target
+			};
+		}
+		return {
+			emitted: false,
+			transitioned: false
+		};
+	}
+	#maybeEmitTransition(event, from, handled, outcome) {
+		if (this.#error !== null) return;
+		if (!handled) return;
+		this.#subs.emitTransition({
+			event,
+			from,
+			to: outcome.target ?? this.state.name,
+			transitioned: outcome.transitioned
+		});
 	}
 	#applyStateStep(event, transition) {
-		const step = transition(event, {
-			context: this.#contextHandle,
-			actor: this
+		let applied = false;
+		let target;
+		this.#safe("transition", event, () => {
+			const step = transition(event, {
+				context: this.#contextHandle,
+				actor: this
+			});
+			if (step.emit) this.#queue.push(...step.emit);
+			if (step.state) {
+				target = this.#applyTransition(event, step);
+				applied = true;
+			}
 		});
-		if (step.emit) this.#queue.push(...step.emit);
-		if (step.state) {
-			this.#applyTransition(event, step);
-			return true;
-		}
-		return false;
+		return {
+			applied,
+			target
+		};
 	}
 	#applyAnyStep(event, transition, allowTransition) {
-		const step = transition(event, {
-			context: this.#contextHandle,
-			actor: this
+		if (transition === void 0) return {
+			emitted: false,
+			transitioned: false
+		};
+		let emitted = false;
+		let transitioned = false;
+		let target;
+		this.#safe("transition", event, () => {
+			const step = transition(event, {
+				context: this.#contextHandle,
+				actor: this
+			});
+			if (step.state && allowTransition) {
+				target = this.#applyTransition(event, step);
+				transitioned = true;
+			}
+			if (step.emit) {
+				this.#queue.push(...step.emit);
+				emitted = true;
+			}
 		});
-		if (step.state && allowTransition) this.#applyTransition(event, step);
-		if (step.emit) {
-			this.#queue.push(...step.emit);
-			return true;
-		}
-		return false;
+		return {
+			emitted,
+			transitioned,
+			target
+		};
 	}
 	snapshot() {
-		return buildSnapshot(this.state, this.#regions, this.#context);
-	}
-	#pushEvent(event) {
-		this.#queue.push(event);
+		return buildSnapshot(this.state, this.#regions, this.#context, {
+			error: this.#error ?? void 0,
+			payload: this.#statePayload
+		});
 	}
 	#abortEffects() {
 		this.#effectAbort?.abort();
 		this.#subs.clear();
 	}
 	#applyTransition(event, step) {
-		if (!step.state) return;
-		this.#effectAbort?.abort();
+		if (this.#error !== null || !step.state) return void 0;
 		const resolved = parseTarget(step);
-		if (!resolved) return;
+		if (!resolved) return void 0;
+		if (!(resolved.state instanceof StateRef)) {
+			this.#enterError("transition", event, /* @__PURE__ */ new Error("invalid transition target"));
+			return;
+		}
+		this.#effectAbort?.abort();
 		this.state = resolved.state;
+		const target = this.state.name;
+		this.#statePayload = resolved.payload;
+		this.#entry = {
+			state: this.state,
+			context: this.#context
+		};
 		this.#runEffects(event, resolved.payload);
-		if (this.state.isFinal) this.#subs.emitDone();
+		if (resolved.state.isFinal && this.#error === null) this.#subs.emitDone();
+		return target;
 	}
 	#runEffects(event, statePayload) {
 		const list = this.#options.effects[this.state.name];
-		if (!list || list.length === 0) {
+		if (!list) {
 			this.#effectAbort = null;
 			return;
 		}
-		const abort = runEffects({
+		const abort = new AbortController();
+		this.#effectAbort = abort;
+		const lastGood = this.#entry ?? {
+			state: this.state,
+			context: this.#context
+		};
+		const result = runEffects({
 			effects: { [this.state.name]: list },
 			state: this.state,
 			statePayload,
 			event,
 			context: this.#contextHandle,
 			emit: (e) => {
+				if (this.#error !== null || abort.signal.aborted) return;
 				this.#queue.push(e);
 				this.#drainInternal();
 			},
-			clock: this.clock
+			clock: this.clock,
+			abort,
+			lastGood,
+			onError: (error) => this.#enterError("effect", event, error, lastGood)
 		});
-		this.#effectAbort = abort;
+		this.#pendingEffects.push(...result.pending);
 	}
 	#drainInternal() {
 		if (this.#draining) return;
 		this.#draining = true;
-		let budgetExceeded = false;
 		try {
 			const budget = this.#internalBudget;
 			let count = 0;
 			this.#queue.processCancellable((event) => {
+				if (this.#error !== null) return false;
 				if (count >= budget) {
-					budgetExceeded = true;
-					this.#abortEffects();
+					this.#enterError("budget", event, /* @__PURE__ */ new Error("internal event budget exceeded"));
 					return false;
 				}
 				count++;
-				if (this.#internalIds.has(event.id) || this.#inputIds.has(event.id)) this.#dispatch(event);
-				else if (this.#outputHandler) this.#outputHandler(event);
+				if (this.#internalIds.has(event.type) || this.#inputIds.has(event.type)) this.#dispatch(event);
+				else {
+					const outputHandler = this.#outputHandler;
+					if (outputHandler) {
+						if (!this.#safe("output", event, () => outputHandler(event))) return false;
+					}
+				}
 				return true;
 			});
 		} finally {
 			this.#draining = false;
 			this.#emitChangeIfDirty();
 		}
-		if (budgetExceeded) console.warn(`[Actor] internal event budget (${this.#internalBudget}) exceeded — possible emit loop. Actor halting.`);
+	}
+	#statePayload;
+	#pendingEffects = [];
+	#errorState = new StateRef("__error", true);
+	#error = null;
+	#entry = null;
+	#safe(reason, event, fn) {
+		const attempt = Either.from(fn);
+		if (attempt[0] === void 0) return true;
+		this.#enterError(reason, event, attempt[0]);
+		return false;
+	}
+	#enterError(reason, event, error, lastGood) {
+		if (this.#error !== null) return;
+		const entry = lastGood ?? this.#entry ?? {
+			state: this.state,
+			context: this.#context
+		};
+		this.#error = {
+			error,
+			state: entry.state,
+			context: entry.context,
+			event,
+			reason
+		};
+		this.#effectAbort?.abort();
+		this.state = this.#errorState;
+		this.#statePayload = void 0;
+		this.#lastState = this.#errorState;
+		this.#contextWritten = false;
+		this.#subs.emitChange(this.snapshot());
+		this.#subs.emitDone();
 	}
 };
 //#endregion
 //#region src/event.ts
-function event(id) {
-	return () => new EventRef(id);
+function event(type) {
+	return () => new EventRef(type);
 }
 var EventRef = class {
-	id;
-	constructor(id) {
-		this.id = id;
+	type;
+	constructor(type) {
+		this.type = type;
 	}
 	is(anyEvent) {
-		return !!anyEvent && typeof anyEvent === "object" && "id" in anyEvent && anyEvent.id === this.id;
+		return !!anyEvent && typeof anyEvent === "object" && "type" in anyEvent && anyEvent.type === this.type;
 	}
 	create(payload) {
-		if (payload === void 0) return { id: this.id };
-		return {
-			...payload,
-			id: this.id
+		return payload === void 0 ? { type: this.type } : {
+			type: this.type,
+			payload
 		};
 	}
 };

package/dist/internal.d.mts

@@ -1,4 +1,4 @@
-import { s as InternalEvent, t as AnyActor } from "./actor-internal-CBU_EDPZ.mjs";
+import { _ as InternalEvent, t as AnyActor } from "./actor-internal-B4iAxUG_.mjs";
 import { Either } from "@mantaq/utils";
 //#region src/internal-registry.d.ts
 interface ActorInternal {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mantaq/core",
-  "version": "0.0.3",
+  "version": "0.2.0",
   "description": "State machine runtime with actor model, event system, state hierarchy, effects, and virtual clock.",
   "license": "MIT",
   "repository": {
@@ -21,7 +21,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@mantaq/utils": "0.0.1"
+    "@mantaq/utils": "0.0.2"
   },
   "devDependencies": {
     "@stryker-mutator/core": "^9",

package/dist/actor-internal-CBU_EDPZ.d.mts

@@ -1,90 +0,0 @@
-//#region src/state.d.ts
-declare function state<const T extends string>(id: T): <Payload = unknown>() => StateRef<T, Payload, false>;
-type AnyStateRef = StateRef<string, unknown, boolean>;
-interface RegionOptions {
-  initial: string;
-  states: Record<string, AnyStateRef>;
-}
-type RegionsOptions = Record<string, RegionOptions>;
-declare class StateRef<T extends string, Payload = unknown, IsFinal extends boolean = false> {
-  readonly name: T;
-  readonly isFinal: IsFinal;
-  /** @internal */ _regions: RegionsOptions | undefined;
-  constructor(name: T, isFinal: IsFinal);
-  regions(options: RegionsOptions): this;
-  final(): StateRef<T, Payload, true>;
-  create(payload: Payload): {
-    state: StateRef<T, Payload, IsFinal>;
-    payload: Payload;
-  };
-}
-//#endregion
-//#region src/event.d.ts
-declare function event<const T extends string>(id: T): <Payload extends object | void = void>() => EventRef<T, Payload>;
-type AnyEventRef = EventRef<string, object | void>;
-type InternalEvent = {
-  id: string;
-} & Record<string, unknown>;
-type CreatedOfEvent<Id extends string, P> = P extends void ? {
-  id: Id;
-} : P & {
-  id: Id;
-};
-declare class EventRef<const T extends string, Payload extends object | void = void> {
-  readonly id: T;
-  constructor(id: T);
-  is(anyEvent: unknown): anyEvent is CreatedOfEvent<T, Payload>;
-  create(): Payload extends void ? {
-    id: T;
-  } : void;
-  create(payload: Payload): Payload extends void ? {
-    id: T;
-  } : Payload & {
-    id: T;
-  };
-}
-//#endregion
-//#region src/clock.d.ts
-interface Clock {
-  setTimeout(ms: number, cb: () => void, options?: {
-    signal?: AbortSignal;
-    eventName?: string;
-  }): number;
-  clearTimeout(id: number): void;
-  setInterval(ms: number, cb: () => void, options?: {
-    signal?: AbortSignal;
-  }): number;
-  clearInterval(id: number): void;
-  now(): number;
-  /** Optional hook for draining queues after clock advances (VirtualClock). */
-  setDrain?(fn: () => void): void;
-}
-//#endregion
-//#region src/actor-internal.d.ts
-interface Snapshot<C = unknown> {
-  path: string[];
-  context: C;
-  regions: Record<string, Snapshot<unknown>>;
-  done?: boolean;
-}
-interface AnyActor<C = Record<string, unknown>> {
-  state: AnyStateRef;
-  clock: Clock;
-  regions: Record<string, AnyActor>;
-  send(event: AnyEventRef | InternalEvent): void;
-  snapshot(): Snapshot<C>;
-  on(event: "change", fn: (snapshot: Snapshot<C>, prev: Snapshot<C>) => void): () => void;
-  on(event: "done", fn: () => void): () => void;
-  settled(): Promise<void>;
-  context?: C;
-  options?: {
-    transitions?: Record<string, Record<string, unknown>>;
-    effects?: Record<string, unknown[]>;
-    states?: ReadonlyArray<{
-      name: string;
-      isFinal: boolean;
-    }>;
-  };
-}
-//#endregion
-export { CreatedOfEvent as a, event as c, state as d, AnyEventRef as i, AnyStateRef as l, Snapshot as n, EventRef as o, Clock as r, InternalEvent as s, AnyActor as t, StateRef as u };