@camcima/finita 4.0.0 → 4.1.0

package/dist/index.d.cts

@@ -287,6 +287,12 @@ interface StatemachineInterface<TSubject = unknown> {
     getProcess(): ProcessInterface;
     triggerEvent(name: string, context?: Map<string, unknown>): Promise<void>;
     checkTransitions(context?: Map<string, unknown>): Promise<void>;
+    /**
+     * Resolves once the operation queue is empty and the runner is idle,
+     * including operations chained via EnqueueContext.enqueue(). Resolves
+     * immediately if the machine is already idle.
+     */
+    whenIdle(): Promise<void>;
     attachBefore(observer: BeforeTransitionObserver<TSubject>): void;
     detachBefore(observer: BeforeTransitionObserver<TSubject>): void;
     getBeforeObservers(): Iterable<BeforeTransitionObserver<TSubject>>;
@@ -316,7 +322,16 @@ interface StatemachineOptions<TSubject = unknown> {
     initialStateName?: string;
     /** Defaults to OneOrNoneActiveTransition. */
     transitionSelector?: TransitionSelectorInterface<TSubject>;
-    /** Defaults to NullMutex (no cross-process serialization). */
+    /**
+     * Defaults to NullMutex (no cross-process serialization).
+     *
+     * Must be exclusive to this machine — never share one MutexInterface
+     * instance between machines: the engine reads isAcquired() as "this
+     * machine holds the lock", so a shared instance silently disables mutual
+     * exclusion. To coordinate machines, share the underlying
+     * LockAdapterInterface (same resource name) and construct one mutex per
+     * machine, as MutexFactory does.
+     */
     mutex?: MutexInterface;
     /** When true, the engine releases the mutex at the end of each top-level operation. Defaults to true. */
     autoreleaseLock?: boolean;
@@ -330,6 +345,36 @@ interface StatemachineOptions<TSubject = unknown> {
      * Defaults to 100.
      */
     maxAutomaticHops?: number;
+    /**
+     * Called when an operation chained via EnqueueContext.enqueue() fails.
+     * Chained operations are not awaited by the caller whose transition
+     * enqueued them, so without this hook their errors are discarded.
+     * Exceptions thrown by the hook itself are swallowed — it must not be
+     * able to break the machine's drain loop.
+     */
+    onChainedOperationError?: (error: unknown, info: {
+        eventName: string;
+    }) => void;
+    /**
+     * Maximum number of operations that may wait in the queue (the running
+     * operation does not count). When the limit is reached, further
+     * triggerEvent/checkTransitions calls reject with
+     * QueueLimitExceededError, and EnqueueContext.enqueue() throws it into
+     * the enqueuing after-observer's error path. In that case the original
+     * caller's promise rejects even though its transition already
+     * committed — check the machine's state, not just the rejection, before
+     * retrying. Must be a positive integer when set. Defaults to Infinity
+     * (unbounded, the previous behavior).
+     */
+    maxQueueLength?: number;
+    /**
+     * Diagnostic hook called whenever the automatic post-operation lock
+     * release throws — including when the operation itself also failed, in
+     * which case the caller's rejection carries the operation error and the
+     * release error would otherwise be discarded. Does not change rejection
+     * behavior. Exceptions thrown by the hook itself are swallowed.
+     */
+    onReleaseError?: (error: unknown) => void;
 }
 
 declare class Statemachine<TSubject = unknown> implements StatemachineInterface<TSubject> {
@@ -341,11 +386,15 @@ declare class Statemachine<TSubject = unknown> implements StatemachineInterface<
     private lastState;
     private autoreleaseLock;
     private readonly maxAutomaticHops;
+    private readonly maxQueueLength;
     private readonly queue;
     private running;
+    private idleWaiters;
     private inSyncCallback;
     private readonly beforeObservers;
     private readonly afterObservers;
+    private readonly onChainedOperationError?;
+    private readonly onReleaseError?;
     constructor(subject: TSubject, process: ProcessInterface, options?: StatemachineOptions<TSubject>);
     getCurrentState(): StateInterface;
     getLastState(): StateInterface | null;
@@ -364,6 +413,14 @@ declare class Statemachine<TSubject = unknown> implements StatemachineInterface<
     setAutoreleaseLock(autorelease: boolean): void;
     triggerEvent(name: string, context?: Map<string, unknown>): Promise<void>;
     checkTransitions(context?: Map<string, unknown>): Promise<void>;
+    /**
+     * Resolves once the operation queue is empty and the runner is idle —
+     * i.e. every operation enqueued so far, including operations chained via
+     * EnqueueContext.enqueue(), has completed. Resolves immediately if the
+     * machine is already idle. Note this is a quiescence point, not a
+     * receipt: work scheduled later (e.g. from a timer) starts a new drain.
+     */
+    whenIdle(): Promise<void>;
     /** Runs fn with the re-entrancy flag set for its SYNCHRONOUS portion only:
      *  the flag is cleared as soon as fn returns (before any promise it returned
      *  is awaited), so concurrent external callers are never affected. This
@@ -674,11 +731,12 @@ interface Graph {
     nodes: GraphNode[];
     edges: GraphEdge[];
 }
+type GraphDirection = "TB" | "BT" | "LR" | "RL";
 interface DotOptions {
-    rankdir?: string;
+    rankdir?: GraphDirection;
 }
 interface MermaidOptions {
-    direction?: string;
+    direction?: GraphDirection;
 }
 declare class GraphBuilder {
     private readonly nodes;
@@ -723,7 +781,7 @@ declare class ProcessFinalizedError extends FinitaError {
     constructor(processName: string);
 }
 
-type GraphValidationCode = "unknownTarget" | "unknownSource" | "missingInitialState" | "multipleInitialStates" | "invalidStateName" | "invalidEventName" | "invalidConditionName" | "orphanState";
+type GraphValidationCode = "unknownTarget" | "unknownSource" | "missingInitialState" | "multipleInitialStates" | "invalidStateName" | "invalidEventName" | "invalidConditionName" | "invalidTransitionWeight" | "orphanState";
 declare class GraphValidationError extends FinitaError {
     readonly code: GraphValidationCode;
     readonly details: Readonly<Record<string, unknown>>;
@@ -791,4 +849,9 @@ declare class ReentrancyError extends FinitaError {
     constructor(operation: string);
 }
 
-export { AbstractNamedProcessDetector, ActiveTransitionFilter, type AddStateOptions, type AddTransitionOptions, type AfterTransitionObserver, AmbiguousTransitionError, AndComposite, AutomaticTransitionCycleError, type BeforeTransitionObserver, type BuildOptions, CallbackCondition, type CallbackInterface, CallbackObserver, type ConditionCallbackFn, type ConditionInterface, Contradiction, type DispatcherInterface, type DotOptions, DuplicateStateError, type DuplicateTransitionConflict, DuplicateTransitionError, type EnqueueContext, Event, type EventInterface, Factory, type FactoryInterface, FilterStateByEvent, FilterStateByFinalState, FilterStateByTransition, FilterTransitionByEvent, FinitaError, type Graph, GraphBuilder, type GraphEdge, type GraphNode, type GraphValidationCode, GraphValidationError, InvalidSubjectError, type LastStateHasChangedDateInterface, type LockAdapterInterface, LockAdapterMutex, LockCanNotBeAcquiredError, type LoggerInterface, type MaybePromise, type MermaidOptions, type Metadata, MutexFactory, type MutexFactoryInterface, type MutexInterface, type Named, Not, NullMutex, type ObservableSubject, type Observer, OnEnterObserver, OneOrNoneActiveTransition, OrComposite, Process, ProcessBuilder, type ProcessDetectorInterface, ProcessFinalizedError, type ProcessInterface, ProcessNotFoundError, type ProposedTransitionFrame, ReentrancyError, ScoreTransition, SingleProcessDetector, State, type StateCollectionInterface, StateEventNotFoundError, type StateInterface, type StateNameDetectorInterface, StateNotFoundError, type StatefulInterface, StatefulStateNameDetector, StatefulStatusChanger, Statemachine, type StatemachineInterface, type StatemachineOptions, type StringConverter, Tautology, Timeout, Transition, type TransitionFrame, type TransitionInterface, TransitionLogger, type TransitionSelectorInterface, WeightTransition, type Weighted, WrongEventForStateError };
+declare class QueueLimitExceededError extends FinitaError {
+    readonly code = "queueLimitExceeded";
+    constructor(limit: number, eventName: string | null);
+}
+
+export { AbstractNamedProcessDetector, ActiveTransitionFilter, type AddStateOptions, type AddTransitionOptions, type AfterTransitionObserver, AmbiguousTransitionError, AndComposite, AutomaticTransitionCycleError, type BeforeTransitionObserver, type BuildOptions, CallbackCondition, type CallbackInterface, CallbackObserver, type ConditionCallbackFn, type ConditionInterface, Contradiction, type DispatcherInterface, type DotOptions, DuplicateStateError, type DuplicateTransitionConflict, DuplicateTransitionError, type EnqueueContext, Event, type EventInterface, Factory, type FactoryInterface, FilterStateByEvent, FilterStateByFinalState, FilterStateByTransition, FilterTransitionByEvent, FinitaError, type Graph, GraphBuilder, type GraphDirection, type GraphEdge, type GraphNode, type GraphValidationCode, GraphValidationError, InvalidSubjectError, type LastStateHasChangedDateInterface, type LockAdapterInterface, LockAdapterMutex, LockCanNotBeAcquiredError, type LoggerInterface, type MaybePromise, type MermaidOptions, type Metadata, MutexFactory, type MutexFactoryInterface, type MutexInterface, type Named, Not, NullMutex, type ObservableSubject, type Observer, OnEnterObserver, OneOrNoneActiveTransition, OrComposite, Process, ProcessBuilder, type ProcessDetectorInterface, ProcessFinalizedError, type ProcessInterface, ProcessNotFoundError, type ProposedTransitionFrame, QueueLimitExceededError, ReentrancyError, ScoreTransition, SingleProcessDetector, State, type StateCollectionInterface, StateEventNotFoundError, type StateInterface, type StateNameDetectorInterface, StateNotFoundError, type StatefulInterface, StatefulStateNameDetector, StatefulStatusChanger, Statemachine, type StatemachineInterface, type StatemachineOptions, type StringConverter, Tautology, Timeout, Transition, type TransitionFrame, type TransitionInterface, TransitionLogger, type TransitionSelectorInterface, WeightTransition, type Weighted, WrongEventForStateError };

package/dist/index.d.ts

@@ -287,6 +287,12 @@ interface StatemachineInterface<TSubject = unknown> {
     getProcess(): ProcessInterface;
     triggerEvent(name: string, context?: Map<string, unknown>): Promise<void>;
     checkTransitions(context?: Map<string, unknown>): Promise<void>;
+    /**
+     * Resolves once the operation queue is empty and the runner is idle,
+     * including operations chained via EnqueueContext.enqueue(). Resolves
+     * immediately if the machine is already idle.
+     */
+    whenIdle(): Promise<void>;
     attachBefore(observer: BeforeTransitionObserver<TSubject>): void;
     detachBefore(observer: BeforeTransitionObserver<TSubject>): void;
     getBeforeObservers(): Iterable<BeforeTransitionObserver<TSubject>>;
@@ -316,7 +322,16 @@ interface StatemachineOptions<TSubject = unknown> {
     initialStateName?: string;
     /** Defaults to OneOrNoneActiveTransition. */
     transitionSelector?: TransitionSelectorInterface<TSubject>;
-    /** Defaults to NullMutex (no cross-process serialization). */
+    /**
+     * Defaults to NullMutex (no cross-process serialization).
+     *
+     * Must be exclusive to this machine — never share one MutexInterface
+     * instance between machines: the engine reads isAcquired() as "this
+     * machine holds the lock", so a shared instance silently disables mutual
+     * exclusion. To coordinate machines, share the underlying
+     * LockAdapterInterface (same resource name) and construct one mutex per
+     * machine, as MutexFactory does.
+     */
     mutex?: MutexInterface;
     /** When true, the engine releases the mutex at the end of each top-level operation. Defaults to true. */
     autoreleaseLock?: boolean;
@@ -330,6 +345,36 @@ interface StatemachineOptions<TSubject = unknown> {
      * Defaults to 100.
      */
     maxAutomaticHops?: number;
+    /**
+     * Called when an operation chained via EnqueueContext.enqueue() fails.
+     * Chained operations are not awaited by the caller whose transition
+     * enqueued them, so without this hook their errors are discarded.
+     * Exceptions thrown by the hook itself are swallowed — it must not be
+     * able to break the machine's drain loop.
+     */
+    onChainedOperationError?: (error: unknown, info: {
+        eventName: string;
+    }) => void;
+    /**
+     * Maximum number of operations that may wait in the queue (the running
+     * operation does not count). When the limit is reached, further
+     * triggerEvent/checkTransitions calls reject with
+     * QueueLimitExceededError, and EnqueueContext.enqueue() throws it into
+     * the enqueuing after-observer's error path. In that case the original
+     * caller's promise rejects even though its transition already
+     * committed — check the machine's state, not just the rejection, before
+     * retrying. Must be a positive integer when set. Defaults to Infinity
+     * (unbounded, the previous behavior).
+     */
+    maxQueueLength?: number;
+    /**
+     * Diagnostic hook called whenever the automatic post-operation lock
+     * release throws — including when the operation itself also failed, in
+     * which case the caller's rejection carries the operation error and the
+     * release error would otherwise be discarded. Does not change rejection
+     * behavior. Exceptions thrown by the hook itself are swallowed.
+     */
+    onReleaseError?: (error: unknown) => void;
 }
 
 declare class Statemachine<TSubject = unknown> implements StatemachineInterface<TSubject> {
@@ -341,11 +386,15 @@ declare class Statemachine<TSubject = unknown> implements StatemachineInterface<
     private lastState;
     private autoreleaseLock;
     private readonly maxAutomaticHops;
+    private readonly maxQueueLength;
     private readonly queue;
     private running;
+    private idleWaiters;
     private inSyncCallback;
     private readonly beforeObservers;
     private readonly afterObservers;
+    private readonly onChainedOperationError?;
+    private readonly onReleaseError?;
     constructor(subject: TSubject, process: ProcessInterface, options?: StatemachineOptions<TSubject>);
     getCurrentState(): StateInterface;
     getLastState(): StateInterface | null;
@@ -364,6 +413,14 @@ declare class Statemachine<TSubject = unknown> implements StatemachineInterface<
     setAutoreleaseLock(autorelease: boolean): void;
     triggerEvent(name: string, context?: Map<string, unknown>): Promise<void>;
     checkTransitions(context?: Map<string, unknown>): Promise<void>;
+    /**
+     * Resolves once the operation queue is empty and the runner is idle —
+     * i.e. every operation enqueued so far, including operations chained via
+     * EnqueueContext.enqueue(), has completed. Resolves immediately if the
+     * machine is already idle. Note this is a quiescence point, not a
+     * receipt: work scheduled later (e.g. from a timer) starts a new drain.
+     */
+    whenIdle(): Promise<void>;
     /** Runs fn with the re-entrancy flag set for its SYNCHRONOUS portion only:
      *  the flag is cleared as soon as fn returns (before any promise it returned
      *  is awaited), so concurrent external callers are never affected. This
@@ -674,11 +731,12 @@ interface Graph {
     nodes: GraphNode[];
     edges: GraphEdge[];
 }
+type GraphDirection = "TB" | "BT" | "LR" | "RL";
 interface DotOptions {
-    rankdir?: string;
+    rankdir?: GraphDirection;
 }
 interface MermaidOptions {
-    direction?: string;
+    direction?: GraphDirection;
 }
 declare class GraphBuilder {
     private readonly nodes;
@@ -723,7 +781,7 @@ declare class ProcessFinalizedError extends FinitaError {
     constructor(processName: string);
 }
 
-type GraphValidationCode = "unknownTarget" | "unknownSource" | "missingInitialState" | "multipleInitialStates" | "invalidStateName" | "invalidEventName" | "invalidConditionName" | "orphanState";
+type GraphValidationCode = "unknownTarget" | "unknownSource" | "missingInitialState" | "multipleInitialStates" | "invalidStateName" | "invalidEventName" | "invalidConditionName" | "invalidTransitionWeight" | "orphanState";
 declare class GraphValidationError extends FinitaError {
     readonly code: GraphValidationCode;
     readonly details: Readonly<Record<string, unknown>>;
@@ -791,4 +849,9 @@ declare class ReentrancyError extends FinitaError {
     constructor(operation: string);
 }
 
-export { AbstractNamedProcessDetector, ActiveTransitionFilter, type AddStateOptions, type AddTransitionOptions, type AfterTransitionObserver, AmbiguousTransitionError, AndComposite, AutomaticTransitionCycleError, type BeforeTransitionObserver, type BuildOptions, CallbackCondition, type CallbackInterface, CallbackObserver, type ConditionCallbackFn, type ConditionInterface, Contradiction, type DispatcherInterface, type DotOptions, DuplicateStateError, type DuplicateTransitionConflict, DuplicateTransitionError, type EnqueueContext, Event, type EventInterface, Factory, type FactoryInterface, FilterStateByEvent, FilterStateByFinalState, FilterStateByTransition, FilterTransitionByEvent, FinitaError, type Graph, GraphBuilder, type GraphEdge, type GraphNode, type GraphValidationCode, GraphValidationError, InvalidSubjectError, type LastStateHasChangedDateInterface, type LockAdapterInterface, LockAdapterMutex, LockCanNotBeAcquiredError, type LoggerInterface, type MaybePromise, type MermaidOptions, type Metadata, MutexFactory, type MutexFactoryInterface, type MutexInterface, type Named, Not, NullMutex, type ObservableSubject, type Observer, OnEnterObserver, OneOrNoneActiveTransition, OrComposite, Process, ProcessBuilder, type ProcessDetectorInterface, ProcessFinalizedError, type ProcessInterface, ProcessNotFoundError, type ProposedTransitionFrame, ReentrancyError, ScoreTransition, SingleProcessDetector, State, type StateCollectionInterface, StateEventNotFoundError, type StateInterface, type StateNameDetectorInterface, StateNotFoundError, type StatefulInterface, StatefulStateNameDetector, StatefulStatusChanger, Statemachine, type StatemachineInterface, type StatemachineOptions, type StringConverter, Tautology, Timeout, Transition, type TransitionFrame, type TransitionInterface, TransitionLogger, type TransitionSelectorInterface, WeightTransition, type Weighted, WrongEventForStateError };
+declare class QueueLimitExceededError extends FinitaError {
+    readonly code = "queueLimitExceeded";
+    constructor(limit: number, eventName: string | null);
+}
+
+export { AbstractNamedProcessDetector, ActiveTransitionFilter, type AddStateOptions, type AddTransitionOptions, type AfterTransitionObserver, AmbiguousTransitionError, AndComposite, AutomaticTransitionCycleError, type BeforeTransitionObserver, type BuildOptions, CallbackCondition, type CallbackInterface, CallbackObserver, type ConditionCallbackFn, type ConditionInterface, Contradiction, type DispatcherInterface, type DotOptions, DuplicateStateError, type DuplicateTransitionConflict, DuplicateTransitionError, type EnqueueContext, Event, type EventInterface, Factory, type FactoryInterface, FilterStateByEvent, FilterStateByFinalState, FilterStateByTransition, FilterTransitionByEvent, FinitaError, type Graph, GraphBuilder, type GraphDirection, type GraphEdge, type GraphNode, type GraphValidationCode, GraphValidationError, InvalidSubjectError, type LastStateHasChangedDateInterface, type LockAdapterInterface, LockAdapterMutex, LockCanNotBeAcquiredError, type LoggerInterface, type MaybePromise, type MermaidOptions, type Metadata, MutexFactory, type MutexFactoryInterface, type MutexInterface, type Named, Not, NullMutex, type ObservableSubject, type Observer, OnEnterObserver, OneOrNoneActiveTransition, OrComposite, Process, ProcessBuilder, type ProcessDetectorInterface, ProcessFinalizedError, type ProcessInterface, ProcessNotFoundError, type ProposedTransitionFrame, QueueLimitExceededError, ReentrancyError, ScoreTransition, SingleProcessDetector, State, type StateCollectionInterface, StateEventNotFoundError, type StateInterface, type StateNameDetectorInterface, StateNotFoundError, type StatefulInterface, StatefulStateNameDetector, StatefulStatusChanger, Statemachine, type StatemachineInterface, type StatemachineOptions, type StringConverter, Tautology, Timeout, Transition, type TransitionFrame, type TransitionInterface, TransitionLogger, type TransitionSelectorInterface, WeightTransition, type Weighted, WrongEventForStateError };

package/dist/index.js

@@ -184,6 +184,7 @@ var State = class {
       throw new Error(`State "${this.name}" transitions already set`);
     }
     this._transitions = new Set(transitions);
+    Object.freeze(this);
   }
   getName() {
     return this.name;
@@ -234,6 +235,7 @@ var Transition = class {
     this.eventName = eventName;
     this.condition = condition;
     this.weight = weight;
+    Object.freeze(this);
   }
   getTargetState() {
     return this.targetState;
@@ -368,12 +370,20 @@ var ProcessBuilder = class _ProcessBuilder {
         { fromState, toState, conditionName }
       );
     }
+    const weight = options.weight ?? 1;
+    if (!Number.isFinite(weight)) {
+      throw new GraphValidationError(
+        "invalidTransitionWeight",
+        `addTransition from "${fromState}" to "${toState}": weight must be a finite number; got ${String(weight)}`,
+        { fromState, toState, eventName, weight }
+      );
+    }
     this.transitionSpecs.push({
       fromState,
       toState,
       eventName,
       condition: options.condition ?? null,
-      weight: options.weight ?? 1
+      weight
     });
     return this;
   }
@@ -381,7 +391,6 @@ var ProcessBuilder = class _ProcessBuilder {
     if (this.built) {
       throw new ProcessFinalizedError(this.processName);
     }
-    this.built = true;
     this.validateInitialState();
     this.validateTransitionEndpoints();
     this.validateNoConflictingDuplicates();
@@ -392,6 +401,7 @@ var ProcessBuilder = class _ProcessBuilder {
       this.validateOrphans(finalStates, initialName);
     }
     const initialState = finalStates.get(initialName);
+    this.built = true;
     return new Process(
       INTERNAL_CONSTRUCTION_KEY,
       this.processName,
@@ -636,6 +646,9 @@ var OperationQueue = class {
   isEmpty() {
     return this.items.length === 0;
   }
+  size() {
+    return this.items.length;
+  }
 };
 
 // src/filter/ActiveTransitionFilter.ts
@@ -700,6 +713,17 @@ var ReentrancyError = class extends FinitaError {
   }
 };
 
+// src/error/QueueLimitExceededError.ts
+var QueueLimitExceededError = class extends FinitaError {
+  code = "queueLimitExceeded";
+  constructor(limit, eventName) {
+    super(
+      `${eventName === null ? "checkTransitions()" : `triggerEvent("${eventName}")`} rejected: the operation queue already holds ${limit} pending operation(s) (maxQueueLength = ${limit}).`
+    );
+    this.name = "QueueLimitExceededError";
+  }
+};
+
 // src/Statemachine.ts
 var Statemachine = class {
   subject;
@@ -710,11 +734,15 @@ var Statemachine = class {
   lastState = null;
   autoreleaseLock;
   maxAutomaticHops;
+  maxQueueLength;
   queue = new OperationQueue();
   running = false;
+  idleWaiters = [];
   inSyncCallback = false;
   beforeObservers = [];
   afterObservers = [];
+  onChainedOperationError;
+  onReleaseError;
   constructor(subject, process, options = {}) {
     this.subject = subject;
     this.process = process;
@@ -729,6 +757,15 @@ var Statemachine = class {
       );
     }
     this.maxAutomaticHops = hops;
+    const maxQueue = options.maxQueueLength ?? Infinity;
+    if (maxQueue !== Infinity && (!Number.isInteger(maxQueue) || maxQueue < 1)) {
+      throw new RangeError(
+        `maxQueueLength must be a positive integer; got ${String(options.maxQueueLength)}`
+      );
+    }
+    this.maxQueueLength = maxQueue;
+    this.onChainedOperationError = options.onChainedOperationError;
+    this.onReleaseError = options.onReleaseError;
   }
   // --- public getters ---
   getCurrentState() {
@@ -745,6 +782,7 @@ var Statemachine = class {
   }
   // --- public observer attach/detach ---
   attachBefore(observer) {
+    if (this.beforeObservers.includes(observer)) return;
     this.beforeObservers.push(observer);
   }
   detachBefore(observer) {
@@ -755,6 +793,7 @@ var Statemachine = class {
     return this.beforeObservers;
   }
   attachAfter(observer) {
+    if (this.afterObservers.includes(observer)) return;
     this.afterObservers.push(observer);
   }
   detachAfter(observer) {
@@ -793,6 +832,21 @@ var Statemachine = class {
       this.enqueueOperation(null, context, resolve, reject);
     });
   }
+  /**
+   * Resolves once the operation queue is empty and the runner is idle —
+   * i.e. every operation enqueued so far, including operations chained via
+   * EnqueueContext.enqueue(), has completed. Resolves immediately if the
+   * machine is already idle. Note this is a quiescence point, not a
+   * receipt: work scheduled later (e.g. from a timer) starts a new drain.
+   */
+  whenIdle() {
+    if (!this.running && this.queue.isEmpty()) {
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      this.idleWaiters.push(resolve);
+    });
+  }
   /** Runs fn with the re-entrancy flag set for its SYNCHRONOUS portion only:
    *  the flag is cleared as soon as fn returns (before any promise it returned
    *  is awaited), so concurrent external callers are never affected. This
@@ -814,6 +868,9 @@ var Statemachine = class {
   }
   /** Single entry point to the operation queue — every enqueue kicks the runner. */
   enqueueOperation(eventName, context, resolve, reject, ifStateName) {
+    if (this.queue.size() >= this.maxQueueLength) {
+      throw new QueueLimitExceededError(this.maxQueueLength, eventName);
+    }
     this.queue.enqueue({
       eventName,
       context: context ?? /* @__PURE__ */ new Map(),
@@ -834,6 +891,11 @@ var Statemachine = class {
       }
     } finally {
       this.running = false;
+      if (this.queue.isEmpty() && this.idleWaiters.length > 0) {
+        const waiters = this.idleWaiters;
+        this.idleWaiters = [];
+        for (const waiter of waiters) waiter();
+      }
     }
   }
   async runOperation(op) {
@@ -859,6 +921,10 @@ var Statemachine = class {
         try {
           await this.mutex.releaseLock();
         } catch (err) {
+          try {
+            this.onReleaseError?.(err);
+          } catch {
+          }
           if (!failure) failure = { err };
         }
       }
@@ -939,7 +1005,13 @@ var Statemachine = class {
               chainedCtx,
               () => {
               },
-              () => {
+              (err) => {
+                try {
+                  this.onChainedOperationError?.(err, {
+                    eventName: chainedEventName
+                  });
+                } catch {
+                }
               },
               ifStateName
             );
@@ -1304,6 +1376,11 @@ var WeightTransition = class {
   innerSelector;
   epsilon;
   constructor(innerSelector, epsilon = 1e-3) {
+    if (!Number.isFinite(epsilon) || epsilon <= 0) {
+      throw new RangeError(
+        `WeightTransition epsilon must be a finite number greater than 0; got ${String(epsilon)}`
+      );
+    }
     this.innerSelector = innerSelector ?? new OneOrNoneActiveTransition();
     this.epsilon = epsilon;
   }
@@ -1312,6 +1389,11 @@ var WeightTransition = class {
     let maxWeight = Number.NEGATIVE_INFINITY;
     for (const transition of all) {
       const weight = transition.getWeight();
+      if (!Number.isFinite(weight)) {
+        throw new RangeError(
+          `WeightTransition: transition weights must be finite numbers; got ${String(weight)}`
+        );
+      }
       if (weight > maxWeight) maxWeight = weight;
     }
     const best = all.filter(
@@ -1486,6 +1568,14 @@ function toMermaidId(name) {
 function escapeMermaidLabel(str) {
   return str.replace(/\\/g, "#92;").replace(/"/g, "#quot;");
 }
+var VALID_DIRECTIONS = /* @__PURE__ */ new Set(["TB", "BT", "LR", "RL"]);
+function assertDirection(value, optionName) {
+  if (!VALID_DIRECTIONS.has(value)) {
+    throw new RangeError(
+      `${optionName} must be one of "TB", "BT", "LR", "RL"; got ${JSON.stringify(value)}`
+    );
+  }
+}
 var GraphBuilder = class {
   nodes = /* @__PURE__ */ new Map();
   edges = [];
@@ -1561,6 +1651,7 @@ var GraphBuilder = class {
   toDot(options) {
     const graph = this.getGraph();
     const rankdir = options?.rankdir ?? "LR";
+    assertDirection(rankdir, "rankdir");
     const lines = [];
     lines.push("digraph {");
     lines.push(`  rankdir=${rankdir};`);
@@ -1580,6 +1671,7 @@ var GraphBuilder = class {
   toMermaid(options) {
     const graph = this.getGraph();
     const direction = options?.direction ?? "LR";
+    assertDirection(direction, "direction");
     const lines = [];
     lines.push(`stateDiagram-v2`);
     lines.push(`  direction ${direction}`);
@@ -1634,6 +1726,7 @@ export {
   ProcessBuilder,
   ProcessFinalizedError,
   ProcessNotFoundError,
+  QueueLimitExceededError,
   ReentrancyError,
   ScoreTransition,
   SingleProcessDetector,