actor-ts 0.9.0

package/dist/fsm/PersistentFSM.d.ts

@@ -0,0 +1,230 @@
+import { PersistentActor } from '../persistence/PersistentActor.js';
+/**
+ * Persistent finite-state machine (#52) — the durable counterpart to
+ * {@link FSM}.  Combines:
+ *
+ *   - **State machine semantics** — a small named state set, a
+ *     transition table, and pure event-application.
+ *   - **Event sourcing** — every transition is a persisted event;
+ *     recovery replays them through `applyEvent` to rebuild both
+ *     the state name and the domain data.
+ *
+ * Natural fit for order workflows, reservation flows, payment
+ * adjudication, claim pipelines — anything that's "current state +
+ * transition events" instead of "current state + arbitrary mutation".
+ *
+ *   type State = 'pending' | 'paid' | 'shipped' | 'cancelled';
+ *   type Event = { kind: 'paid' } | { kind: 'shipped' } | { kind: 'cancelled' };
+ *   type Cmd   = { kind: 'pay' } | { kind: 'ship' } | { kind: 'cancel' };
+ *   interface Data { items: string[]; total: number }
+ *
+ *   class OrderFsm extends PersistentFSM<Cmd, Event, State, Data> {
+ *     readonly persistenceId = 'order-1';
+ *     initialFsmState() { return 'pending' as const; }
+ *     initialData(): Data { return { items: [], total: 0 }; }
+ *
+ *     transitions = {
+ *       pending: {
+ *         pay:    { event: { kind: 'paid' } as const,      next: 'paid' as const },
+ *         cancel: { event: { kind: 'cancelled' } as const, next: 'cancelled' as const },
+ *       },
+ *       paid: {
+ *         ship: { event: { kind: 'shipped' } as const, next: 'shipped' as const },
+ *       },
+ *     };
+ *
+ *     applyEvent(state: State, data: Data, e: Event) {
+ *       if (e.kind === 'paid')      return { state: 'paid' as State,      data };
+ *       if (e.kind === 'shipped')   return { state: 'shipped' as State,   data };
+ *       if (e.kind === 'cancelled') return { state: 'cancelled' as State, data };
+ *       return { state, data };
+ *     }
+ *   }
+ *
+ * **What the base class does for you.**
+ *
+ *   - On a command, looks up `transitions[currentFsmState][cmd.kind]`.
+ *     If no entry: **invalid transition** — logged at warn, no event
+ *     persisted, no state change.
+ *   - If the entry has a `guard` and the guard returns false: same
+ *     outcome — logged at debug, no event persisted.
+ *   - Otherwise, evaluates the entry's `event` (literal or function),
+ *     persists it, and applies it via `applyEvent`.
+ *   - `applyEvent` is the source of truth for state + data updates;
+ *     it runs both at command time and during recovery, so the FSM
+ *     is rebuilt deterministically.
+ *
+ * **State timeouts (#65).**  An entry may declare a special
+ * `_timeout: { afterMs, event, next, guard? }` field that arms a
+ * one-shot timer when the FSM enters the state.  If `afterMs` elapses
+ * before any command transitions out, the FSM auto-fires the timeout
+ * event through the same persist-then-apply pipeline.  See
+ * {@link FsmStateTimeout}.  Fresh-armed on every state transition;
+ * cancelled when the FSM transitions away (or stops).  Recovery
+ * re-arms the timer relative to the wall-clock at recovery
+ * completion — i.e., a long-stopped FSM gets a fresh `afterMs`
+ * window after restart, deliberately conservative to avoid spurious
+ * "already-expired" fires.
+ *
+ * **Snapshots / event adapter / encryption.**  Inherited from
+ * `PersistentActor` — override `snapshotPolicy`, `eventAdapter`,
+ * `compression`, etc. exactly as you would on a plain
+ * `PersistentActor`.  The combined `{ state, data }` is what gets
+ * snapshotted.
+ *
+ * **Out of scope (per issue).**
+ *
+ *   - Multiple events per command — drop down to overriding
+ *     `onCommand` directly and call `persistAll([...])`.
+ *   - Per-transition timeouts (the timeout is a per-state property,
+ *     not a per-transition one).
+ */
+/** Combined state held by the underlying `PersistentActor`. */
+export interface FsmStateData<S extends string, D> {
+    readonly state: S;
+    readonly data: D;
+}
+/** One entry in the transition table. */
+export interface FsmTransition<SName extends string, Cmd, Event, Data> {
+    /**
+     * Event(s) to persist when this transition fires.  Three shapes:
+     *
+     *   - **Literal** — `{ kind: 'paid' }`: a single event persisted
+     *     atomically as one journal entry.
+     *   - **Array** — `[evtA, evtB]`: multiple events persisted in
+     *     one `persistAll` call (#66) so they share a logical
+     *     transaction; `applyEvent` runs once per event and the
+     *     post-apply final state is checked against `next`.  An
+     *     empty array is treated as a no-op transition (no events
+     *     persisted, no state change) — use a `guard` instead if
+     *     "skip on this condition" is the actual intent.
+     *   - **Function** — `(cmd, data) => Event | Event[]`: lazily
+     *     evaluated when the transition fires; otherwise behaves
+     *     exactly like the literal / array forms above.
+     */
+    readonly event: Event | Event[] | ((cmd: Cmd, data: Data) => Event | Event[]);
+    /**
+     * State name the FSM moves to after every event applies.  When
+     * `event` is an array, only the **final** post-replay state is
+     * compared against `next` — intermediate transitions inside the
+     * array don't have to match.  Mainly informational; `applyEvent`
+     * is what actually drives the transition.
+     */
+    readonly next: SName;
+    /**
+     * Optional pre-check — if it returns `false`, the transition
+     * is skipped (no event persisted, no state change).  Use for
+     * conditional dispatch like "pay only if amount > 0".  Logged
+     * at debug.
+     */
+    readonly guard?: (cmd: Cmd, data: Data) => boolean;
+}
+/**
+ * Time-based transition for a state (#65).  Declared under the magic
+ * `_timeout` key in a state's transition map; cannot collide with a
+ * real command kind because `kind: '_timeout'` is reserved.
+ *
+ * On entering the state the FSM arms a one-shot timer for `afterMs`.
+ * If the timer fires while still in the state (no command transitioned
+ * the FSM out in the meantime, and the optional `guard` accepts), the
+ * declared `event` is persisted and `applyEvent` runs as if a real
+ * command had triggered it.
+ */
+export interface FsmStateTimeout<SName extends string, Event, Data> {
+    /** How long to wait before auto-firing the event.  Required. */
+    readonly afterMs: number;
+    /**
+     * Event(s) to persist when the timer fires.  Same shape as a
+     * regular transition (#66) — single literal, array, or function
+     * returning either.  An empty array is a no-op fire (timer
+     * cancelled, no transition, no events persisted).
+     */
+    readonly event: Event | Event[] | ((data: Data) => Event | Event[]);
+    /** Target state.  Verified against `applyEvent`'s output, like {@link FsmTransition}. */
+    readonly next: SName;
+    /** Optional pre-fire guard — `false` cancels the timeout silently. */
+    readonly guard?: (data: Data) => boolean;
+}
+/** Reserved key under which {@link FsmStateTimeout} lives in a state's config. */
+export declare const FSM_TIMEOUT_KEY: "_timeout";
+/**
+ * Transition table — `state` × `cmd.kind` → transition entry.  The
+ * mapped type narrows `Cmd` to the matching variant inside each
+ * entry so the entry's callbacks see the right command shape.  An
+ * optional `_timeout` field declares the per-state timeout (#65).
+ */
+export type FsmTransitionMap<SName extends string, Cmd extends {
+    readonly kind: string;
+}, Event, Data> = {
+    readonly [state in SName]?: {
+        readonly [K in Cmd['kind']]?: FsmTransition<SName, Extract<Cmd, {
+            kind: K;
+        }>, Event, Data>;
+    } & {
+        readonly _timeout?: FsmStateTimeout<SName, Event, Data>;
+    };
+};
+export declare abstract class PersistentFSM<Cmd extends {
+    readonly kind: string;
+}, Event, SName extends string, Data> extends PersistentActor<Cmd, Event, FsmStateData<SName, Data>> {
+    /** Starting state name when no events have been replayed. */
+    abstract initialFsmState(): SName;
+    /** Starting data when no events have been replayed. */
+    abstract initialData(): Data;
+    /**
+     * Pure event-application — updates both state name and data.
+     * Runs at persist-time (forward) AND at recovery-time (replay),
+     * so it MUST be deterministic and free of side effects.
+     */
+    abstract applyEvent(state: SName, data: Data, event: Event): FsmStateData<SName, Data>;
+    /**
+     * Transition table.  Implementations typically declare it as a
+     * class field so the type-narrowing in `FsmTransitionMap` works
+     * at the call site (`transitions[state][cmdKind]`).
+     */
+    abstract transitions: FsmTransitionMap<SName, Cmd, Event, Data>;
+    /**
+     * Hook invoked when a command has no matching transition for the
+     * current state.  Default: warn + drop (no event persisted).
+     * Override to throw, send a reply, etc.
+     */
+    protected onInvalidTransition(state: SName, cmd: Cmd): void | Promise<void>;
+    /**
+     * Hook invoked when a transition's `guard` returns false.  Default
+     * is a debug log + drop.
+     */
+    protected onGuardRejected(state: SName, cmd: Cmd): void | Promise<void>;
+    /** Current FSM state name.  Reliable after recovery. */
+    protected get currentFsmState(): SName;
+    /** Current FSM data.  Reliable after recovery. */
+    protected get currentData(): Data;
+    /** Currently-armed timer, if any.  Cancelled on transition or stop. */
+    private _timeoutTimer;
+    initialState(): FsmStateData<SName, Data>;
+    onEvent(curr: FsmStateData<SName, Data>, event: Event): FsmStateData<SName, Data>;
+    onRecoveryComplete(_state: FsmStateData<SName, Data>): void | Promise<void>;
+    postStop(): Promise<void>;
+    /**
+     * Intercept the internal `__fsm_state_timeout__` self-tell that the
+     * armed timer routes through the mailbox.  Real user commands
+     * delegate straight to `super.onReceive` (which handles recovery
+     * stash + persist gating + dispatch to {@link onCommand}).
+     */
+    onReceive(message: Cmd): Promise<void>;
+    onCommand(curr: FsmStateData<SName, Data>, cmd: Cmd): Promise<void>;
+    /**
+     * Cancel any in-flight timer and, if the current state has a
+     * `_timeout` config, arm a fresh one.  Called after every state
+     * transition (forward, recovery, and timeout-driven).
+     */
+    private armTimerForCurrentState;
+    private cancelTimer;
+    /**
+     * Apply a `_timeout` transition: re-validate state (no-op if a
+     * command already transitioned the FSM out), evaluate the event,
+     * persist + re-arm.  Same shape as {@link onCommand}'s persist
+     * dance — keeps the post-apply state-name verification.
+     */
+    private fireTimeoutTransition;
+}
+//# sourceMappingURL=PersistentFSM.d.ts.map

package/dist/fsm/PersistentFSM.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PersistentFSM.d.ts","sourceRoot":"","sources":["../../src/fsm/PersistentFSM.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+EG;AAEH,+DAA+D;AAC/D,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC;IAC/C,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;CAClB;AAED,yCAAyC;AACzC,MAAM,WAAW,aAAa,CAC5B,KAAK,SAAS,MAAM,EACpB,GAAG,EACH,KAAK,EACL,IAAI;IAEJ;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,KAAK,EACV,KAAK,GACL,KAAK,EAAE,GACP,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,KAAK,KAAK,GAAG,KAAK,EAAE,CAAC,CAAC;IAChD;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC;CACpD;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,eAAe,CAAC,KAAK,SAAS,MAAM,EAAE,KAAK,EAAE,IAAI;IAChE,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,KAAK,KAAK,GAAG,KAAK,EAAE,CAAC,CAAC;IACpE,yFAAyF;IACzF,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,sEAAsE;IACtE,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC;CAC1C;AAED,kFAAkF;AAClF,eAAO,MAAM,eAAe,EAAG,UAAmB,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,CAC1B,KAAK,SAAS,MAAM,EACpB,GAAG,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EACrC,KAAK,EACL,IAAI,IACF;IACF,QAAQ,EAAE,KAAK,IAAI,KAAK,CAAC,CAAC,EAAE;QAC1B,QAAQ,EAAE,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,aAAa,CAAC,KAAK,EAAE,OAAO,CAAC,GAAG,EAAE;YAAE,IAAI,EAAE,CAAC,CAAA;SAAE,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC;KAC3F,GAAG;QACF,QAAQ,CAAC,QAAQ,CAAC,EAAE,eAAe,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;KACzD;CACF,CAAC;AAkBF,8BAAsB,aAAa,CACjC,GAAG,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EACrC,KAAK,EACL,KAAK,SAAS,MAAM,EACpB,IAAI,CACJ,SAAQ,eAAe,CAAC,GAAG,EAAE,KAAK,EAAE,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAC9D,6DAA6D;IAC7D,QAAQ,CAAC,eAAe,IAAI,KAAK;IAEjC,uDAAuD;IACvD,QAAQ,CAAC,WAAW,IAAI,IAAI;IAE5B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CACjB,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,GACrC,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC;IAE5B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;IAEhE;;;;OAIG;IACH,SAAS,CAAC,mBAAmB,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAM3E;;;OAGG;IACH,SAAS,CAAC,eAAe,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAQvE,wDAAwD;IACxD,SAAS,KAAK,eAAe,IAAI,KAAK,CAA6B;IAEnE,kDAAkD;IAClD,SAAS,KAAK,WAAW,IAAI,IAAI,CAA4B;IAI7D,uEAAuE;IACvE,OAAO,CAAC,aAAa,CAA4B;IAIjD,YAAY,IAAI,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC;IAIzC,OAAO,CAAC,IAAI,EAAE,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,GAAG,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC;IAIxE,kBAAkB,CAAC,MAAM,EAAE,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAQrE,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxC;;;;;OAKG;IACY,SAAS,CAAC,OAAO,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAS/C,SAAS,CAAC,IAAI,EAAE,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IA+CzE;;;;OAIG;IACH,OAAO,CAAC,uBAAuB;IAqB/B,OAAO,CAAC,WAAW;IAOnB;;;;;OAKG;YACW,qBAAqB;CAwCpC"}

package/dist/fsm/PersistentFSM.js

@@ -0,0 +1,170 @@
+import { PersistentActor } from '../persistence/PersistentActor.js';
+/** Reserved key under which {@link FsmStateTimeout} lives in a state's config. */
+export const FSM_TIMEOUT_KEY = '_timeout';
+/* ============================== base class ============================== */
+export class PersistentFSM extends PersistentActor {
+    /**
+     * Hook invoked when a command has no matching transition for the
+     * current state.  Default: warn + drop (no event persisted).
+     * Override to throw, send a reply, etc.
+     */
+    onInvalidTransition(state, cmd) {
+        this.log.warn(`PersistentFSM: no transition for cmd '${cmd.kind}' in state '${state}' — dropped`);
+    }
+    /**
+     * Hook invoked when a transition's `guard` returns false.  Default
+     * is a debug log + drop.
+     */
+    onGuardRejected(state, cmd) {
+        this.log.debug(`PersistentFSM: guard rejected cmd '${cmd.kind}' in state '${state}' — dropped`);
+    }
+    /* --------------------------- read-only views -------------------------- */
+    /** Current FSM state name.  Reliable after recovery. */
+    get currentFsmState() { return this.state.state; }
+    /** Current FSM data.  Reliable after recovery. */
+    get currentData() { return this.state.data; }
+    /* ----------------------- internal: timeout state ---------------------- */
+    /** Currently-armed timer, if any.  Cancelled on transition or stop. */
+    _timeoutTimer = null;
+    /* --------------- PersistentActor hooks (implemented for you) --------------- */
+    initialState() {
+        return { state: this.initialFsmState(), data: this.initialData() };
+    }
+    onEvent(curr, event) {
+        return this.applyEvent(curr.state, curr.data, event);
+    }
+    onRecoveryComplete(_state) {
+        // Arm the timer fresh after recovery — we deliberately don't try
+        // to recompute "remaining time" from the original state-entry
+        // moment.  Restarted FSMs get a fresh `afterMs` window; spurious
+        // immediate-fires are worse than a slightly-extended timeout.
+        this.armTimerForCurrentState();
+    }
+    async postStop() {
+        this.cancelTimer();
+    }
+    /**
+     * Intercept the internal `__fsm_state_timeout__` self-tell that the
+     * armed timer routes through the mailbox.  Real user commands
+     * delegate straight to `super.onReceive` (which handles recovery
+     * stash + persist gating + dispatch to {@link onCommand}).
+     */
+    async onReceive(message) {
+        const tagged = message;
+        if (tagged.kind === '__fsm_state_timeout__') {
+            await this.fireTimeoutTransition(tagged.stateAtArm);
+            return;
+        }
+        await super.onReceive(message);
+    }
+    async onCommand(curr, cmd) {
+        const stateEntry = this.transitions[curr.state];
+        const transition = stateEntry?.[cmd.kind];
+        if (!transition) {
+            await this.onInvalidTransition(curr.state, cmd);
+            return;
+        }
+        if (transition.guard && !transition.guard(cmd, curr.data)) {
+            await this.onGuardRejected(curr.state, cmd);
+            return;
+        }
+        const evaluated = typeof transition.event === 'function'
+            ? transition.event(cmd, curr.data)
+            : transition.event;
+        const events = Array.isArray(evaluated) ? evaluated : [evaluated];
+        if (events.length === 0) {
+            // Empty array → no events to persist, no state change.  Treat
+            // as a "guard returned false" outcome from the user's POV.
+            this.log.debug(`PersistentFSM: cmd '${cmd.kind}' in state '${curr.state}' produced an empty event array — dropped`);
+            return;
+        }
+        await this.persistAll(events, (next) => {
+            // Sanity check: the user's `applyEvent` and the table's `next`
+            // should agree on the target state after the FINAL event.  A
+            // mismatch is almost always a bug — surface it loud rather
+            // than silently letting the FSM drift away from its declared
+            // graph.  Intermediate states (events[0]..[N-2] applied) are
+            // not checked.
+            if (next.state !== transition.next) {
+                this.log.warn(`PersistentFSM: applyEvent for cmd '${cmd.kind}' in state '${curr.state}' `
+                    + `produced state '${next.state}' but transition declared 'next: ${transition.next}'`);
+            }
+            // Re-arm the timer for the new state — cancels any previously-
+            // armed timer first, schedules the new one if the new state
+            // has a `_timeout` entry.
+            this.armTimerForCurrentState();
+        });
+    }
+    /* ---------------------- internal: timer plumbing ---------------------- */
+    /**
+     * Cancel any in-flight timer and, if the current state has a
+     * `_timeout` config, arm a fresh one.  Called after every state
+     * transition (forward, recovery, and timeout-driven).
+     */
+    armTimerForCurrentState() {
+        this.cancelTimer();
+        const state = this.currentFsmState;
+        const timeout = this.transitions[state]?.[FSM_TIMEOUT_KEY];
+        if (!timeout)
+            return;
+        const stateAtArm = state;
+        this._timeoutTimer = this.system.scheduler.scheduleOnceFn(timeout.afterMs, () => {
+            this._timeoutTimer = null;
+            // Route through the mailbox so the fire interleaves cleanly
+            // with regular commands — `onReceive` intercepts it.
+            const fire = {
+                kind: '__fsm_state_timeout__',
+                stateAtArm,
+            };
+            this.self.tell(fire);
+        });
+    }
+    cancelTimer() {
+        if (this._timeoutTimer) {
+            this._timeoutTimer.cancel();
+            this._timeoutTimer = null;
+        }
+    }
+    /**
+     * Apply a `_timeout` transition: re-validate state (no-op if a
+     * command already transitioned the FSM out), evaluate the event,
+     * persist + re-arm.  Same shape as {@link onCommand}'s persist
+     * dance — keeps the post-apply state-name verification.
+     */
+    async fireTimeoutTransition(stateAtArm) {
+        const curr = this.state;
+        if (curr.state !== stateAtArm) {
+            // A command transitioned us out before the timer message landed
+            // in the mailbox — the user's command takes precedence.  Re-arm
+            // for the new state (in case the new state itself has a timeout
+            // and we're catching up after a flurry of late mailbox traffic).
+            this.armTimerForCurrentState();
+            return;
+        }
+        const timeout = this.transitions[curr.state]?.[FSM_TIMEOUT_KEY];
+        if (!timeout)
+            return;
+        if (timeout.guard && !timeout.guard(curr.data)) {
+            this.log.debug(`PersistentFSM: state-timeout guard rejected fire in state '${curr.state}' — dropped`);
+            this.armTimerForCurrentState();
+            return;
+        }
+        const evaluated = typeof timeout.event === 'function'
+            ? timeout.event(curr.data)
+            : timeout.event;
+        const events = Array.isArray(evaluated) ? evaluated : [evaluated];
+        if (events.length === 0) {
+            this.log.debug(`PersistentFSM: state-timeout in state '${curr.state}' produced an empty event array — dropped`);
+            this.armTimerForCurrentState();
+            return;
+        }
+        await this.persistAll(events, (next) => {
+            if (next.state !== timeout.next) {
+                this.log.warn(`PersistentFSM: applyEvent for state-timeout in state '${curr.state}' `
+                    + `produced state '${next.state}' but timeout declared 'next: ${timeout.next}'`);
+            }
+            this.armTimerForCurrentState();
+        });
+    }
+}
+//# sourceMappingURL=PersistentFSM.js.map

package/dist/fsm/PersistentFSM.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PersistentFSM.js","sourceRoot":"","sources":["../../src/fsm/PersistentFSM.ts"],"names":[],"mappings":"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"}

package/dist/fsm/index.d.ts

@@ -0,0 +1,5 @@
+export { FSM } from './FSM.js';
+export type { Transition, StayTransition, FsmResult, StateHandler, TransitionCallback, } from './FSM.js';
+export { PersistentFSM } from './PersistentFSM.js';
+export type { FsmStateData, FsmTransition, FsmTransitionMap, } from './PersistentFSM.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/fsm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/fsm/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,YAAY,EACV,UAAU,EACV,cAAc,EACd,SAAS,EACT,YAAY,EACZ,kBAAkB,GACnB,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EACV,YAAY,EACZ,aAAa,EACb,gBAAgB,GACjB,MAAM,oBAAoB,CAAC"}

package/dist/fsm/index.js

@@ -0,0 +1,3 @@
+export { FSM } from './FSM.js';
+export { PersistentFSM } from './PersistentFSM.js';
+//# sourceMappingURL=index.js.map

package/dist/fsm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/fsm/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAS/B,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/http/HttpClient.d.ts

@@ -0,0 +1,34 @@
+import type { HttpMethod } from './types.js';
+export interface HttpClientRequest {
+    readonly method: HttpMethod;
+    readonly url: string | URL;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly body?: string | Uint8Array | object | null;
+    /** Abort the request after this many milliseconds. */
+    readonly timeoutMs?: number;
+}
+export interface HttpClientResponse {
+    readonly status: number;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: Uint8Array;
+    /** Decode body as UTF-8 text. */
+    text(): string;
+    /** Decode body as JSON. */
+    json<T = unknown>(): T;
+}
+/**
+ * Thin HTTP client around the global `fetch`.  Returns a uniform response
+ * shape with typed helpers (text, json) so callers don't have to deal
+ * with two Response APIs.
+ */
+export declare class HttpClient {
+    /** Single request — no connection pool.  fetch handles keep-alive under the hood. */
+    singleRequest(req: HttpClientRequest): Promise<HttpClientResponse>;
+    get(url: string | URL, init?: Omit<HttpClientRequest, 'method' | 'url'>): Promise<HttpClientResponse>;
+    post(url: string | URL, init?: Omit<HttpClientRequest, 'method' | 'url'>): Promise<HttpClientResponse>;
+    put(url: string | URL, init?: Omit<HttpClientRequest, 'method' | 'url'>): Promise<HttpClientResponse>;
+    delete(url: string | URL, init?: Omit<HttpClientRequest, 'method' | 'url'>): Promise<HttpClientResponse>;
+    private serialiseBody;
+    private normaliseHeaders;
+}
+//# sourceMappingURL=HttpClient.d.ts.map

package/dist/http/HttpClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpClient.d.ts","sourceRoot":"","sources":["../../src/http/HttpClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,IAAI,CAAC;IACpD,sDAAsD;IACtD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,iCAAiC;IACjC,IAAI,IAAI,MAAM,CAAC;IACf,2BAA2B;IAC3B,IAAI,CAAC,CAAC,GAAG,OAAO,KAAK,CAAC,CAAC;CACxB;AAED;;;;GAIG;AACH,qBAAa,UAAU;IACrB,qFAAqF;IAC/E,aAAa,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA+BxE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,iBAAiB,EAAE,QAAQ,GAAG,KAAK,CAAC,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAGrG,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,iBAAiB,EAAE,QAAQ,GAAG,KAAK,CAAC,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAGtG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,iBAAiB,EAAE,QAAQ,GAAG,KAAK,CAAC,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAGrG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,iBAAiB,EAAE,QAAQ,GAAG,KAAK,CAAC,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAIxG,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,gBAAgB;CAWzB"}

package/dist/http/HttpClient.js

@@ -0,0 +1,72 @@
+/**
+ * Thin HTTP client around the global `fetch`.  Returns a uniform response
+ * shape with typed helpers (text, json) so callers don't have to deal
+ * with two Response APIs.
+ */
+export class HttpClient {
+    /** Single request — no connection pool.  fetch handles keep-alive under the hood. */
+    async singleRequest(req) {
+        const controller = new AbortController();
+        let timer = null;
+        if (req.timeoutMs && req.timeoutMs > 0) {
+            timer = setTimeout(() => controller.abort(), req.timeoutMs);
+            timer.unref?.();
+        }
+        try {
+            const body = this.serialiseBody(req.body);
+            const headers = this.normaliseHeaders(req.headers, req.body);
+            const res = await fetch(req.url, {
+                method: req.method,
+                headers,
+                body: body,
+                signal: controller.signal,
+            });
+            const buffer = new Uint8Array(await res.arrayBuffer());
+            const outHeaders = {};
+            res.headers.forEach((v, k) => { outHeaders[k.toLowerCase()] = v; });
+            return {
+                status: res.status,
+                headers: outHeaders,
+                body: buffer,
+                text() { return new TextDecoder().decode(buffer); },
+                json() { return JSON.parse(new TextDecoder().decode(buffer)); },
+            };
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    get(url, init) {
+        return this.singleRequest({ method: 'GET', url, ...init });
+    }
+    post(url, init) {
+        return this.singleRequest({ method: 'POST', url, ...init });
+    }
+    put(url, init) {
+        return this.singleRequest({ method: 'PUT', url, ...init });
+    }
+    delete(url, init) {
+        return this.singleRequest({ method: 'DELETE', url, ...init });
+    }
+    serialiseBody(body) {
+        if (body === undefined || body === null)
+            return undefined;
+        if (typeof body === 'string')
+            return body;
+        if (body instanceof Uint8Array)
+            return body;
+        return JSON.stringify(body);
+    }
+    normaliseHeaders(headers, body) {
+        const out = {};
+        if (headers)
+            for (const [k, v] of Object.entries(headers))
+                out[k.toLowerCase()] = v;
+        if (body && typeof body !== 'string' && !(body instanceof Uint8Array) && !out['content-type']) {
+            out['content-type'] = 'application/json; charset=utf-8';
+        }
+        return out;
+    }
+}
+//# sourceMappingURL=HttpClient.js.map

package/dist/http/HttpClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpClient.js","sourceRoot":"","sources":["../../src/http/HttpClient.ts"],"names":[],"mappings":"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"}

package/dist/http/HttpExtension.d.ts

@@ -0,0 +1,29 @@
+import type { ActorSystem } from '../ActorSystem.js';
+import { type Extension, type ExtensionId } from '../Extension.js';
+import type { HttpServerBackend, ServerBinding } from './backend/HttpServerBackend.js';
+import { HttpClient } from './HttpClient.js';
+import { type Route } from './Route.js';
+export interface ServerBuilder {
+    /** Override the default Fastify backend (or use BunServe / Express). */
+    useBackend(backend: HttpServerBackend): ServerBuilder;
+    /** Register the full route tree and bind.  Returns the ServerBinding. */
+    bind(routes: Route): Promise<ServerBinding>;
+}
+/**
+ * System-wide HTTP extension — entry point for the routing DSL and the
+ * shared HttpClient.  Every ActorSystem gets one HttpClient and a factory
+ * for HTTP servers.  The default server backend is Fastify; swap it per
+ * server via `builder.useBackend(new BunServeBackend())`.
+ */
+export declare class HttpExtension implements Extension {
+    private readonly system;
+    /** Shared HTTP client — uses the global fetch. */
+    readonly client: HttpClient;
+    constructor(system: ActorSystem);
+    /** Start building a new server scope.  Call `bind(routes)` to start it. */
+    newServerAt(host: string, port: number): ServerBuilder;
+    /** Fire-and-forget request via the shared client. */
+    singleRequest: (req: import("./HttpClient.js").HttpClientRequest) => Promise<import("./HttpClient.js").HttpClientResponse>;
+}
+export declare const HttpExtensionId: ExtensionId<HttpExtension>;
+//# sourceMappingURL=HttpExtension.d.ts.map

package/dist/http/HttpExtension.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpExtension.d.ts","sourceRoot":"","sources":["../../src/http/HttpExtension.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAe,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAChF,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAEvF,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAW,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AAGjD,MAAM,WAAW,aAAa;IAC5B,wEAAwE;IACxE,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,aAAa,CAAC;IACtD,yEAAyE;IACzE,IAAI,CAAC,MAAM,EAAE,KAAK,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CAC7C;AAED;;;;;GAKG;AACH,qBAAa,aAAc,YAAW,SAAS;IAIjC,OAAO,CAAC,QAAQ,CAAC,MAAM;IAHnC,kDAAkD;IAClD,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAoB;gBAElB,MAAM,EAAE,WAAW;IAEhD,2EAA2E;IAC3E,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa;IA6CtD,qDAAqD;IACrD,aAAa,8GAA+C;CAC7D;AAED,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,aAAa,CAGtD,CAAC"}

package/dist/http/HttpExtension.js

@@ -0,0 +1,64 @@
+import { extensionId } from '../Extension.js';
+import { FastifyBackend } from './backend/FastifyBackend.js';
+import { HttpClient } from './HttpClient.js';
+import { compile } from './Route.js';
+/**
+ * System-wide HTTP extension — entry point for the routing DSL and the
+ * shared HttpClient.  Every ActorSystem gets one HttpClient and a factory
+ * for HTTP servers.  The default server backend is Fastify; swap it per
+ * server via `builder.useBackend(new BunServeBackend())`.
+ */
+export class HttpExtension {
+    system;
+    /** Shared HTTP client — uses the global fetch. */
+    client = new HttpClient();
+    constructor(system) {
+        this.system = system;
+    }
+    /** Start building a new server scope.  Call `bind(routes)` to start it. */
+    newServerAt(host, port) {
+        let backend = null;
+        const system = this.system;
+        return {
+            useBackend(b) {
+                backend = b;
+                return this;
+            },
+            async bind(routes) {
+                const active = backend ?? new FastifyBackend();
+                const compiled = compile(routes);
+                // Wrap each route's handler with a request log + timing.
+                // Done at the DSL level so backends don't need a Logger
+                // reference — every backend gets the same per-request debug
+                // line uniformly.
+                for (const r of compiled) {
+                    const wrapped = {
+                        ...r,
+                        handler: async (req) => {
+                            const start = Date.now();
+                            system.log.debug(`[http] ${req.method} ${req.path}`);
+                            try {
+                                const out = await r.handler(req);
+                                system.log.debug(`[http] ${req.method} ${req.path} → ${out.status} (${Date.now() - start} ms)`);
+                                return out;
+                            }
+                            catch (err) {
+                                system.log.debug(`[http] ${req.method} ${req.path} → error after ${Date.now() - start} ms: ${err.message}`);
+                                throw err;
+                            }
+                        },
+                    };
+                    active.registerRoute(wrapped);
+                }
+                const binding = await active.listen(host, port);
+                system.log.info(`HTTP server bound on ${binding.host}:${binding.port} (${active.name})`);
+                system.log.debug(`[http] ${compiled.length} route(s) registered`);
+                return binding;
+            },
+        };
+    }
+    /** Fire-and-forget request via the shared client. */
+    singleRequest = this.client.singleRequest.bind(this.client);
+}
+export const HttpExtensionId = extensionId('HttpExtension', (system) => new HttpExtension(system));
+//# sourceMappingURL=HttpExtension.js.map