@camcima/finita 4.0.0 → 4.2.0

package/dist/index.d.cts

@@ -53,6 +53,8 @@ declare class Event implements EventInterface {
     attach(observer: Observer): void;
     detach(observer: Observer): void;
     notify(args?: readonly unknown[]): Promise<void>;
+    /** Snapshot — detaching later does not change an already-returned list,
+     *  and mutating it does not change the event's registrations. */
     getObservers(): Iterable<Observer>;
     getMetadata(): Record<string, unknown>;
     getMetadataValue(key: string): unknown;
@@ -287,6 +289,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 +324,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 +347,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 +388,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;
@@ -353,17 +404,40 @@ declare class Statemachine<TSubject = unknown> implements StatemachineInterface<
     getProcess(): ProcessInterface;
     attachBefore(observer: BeforeTransitionObserver<TSubject>): void;
     detachBefore(observer: BeforeTransitionObserver<TSubject>): void;
+    /** Snapshot — detaching later does not change an already-returned list,
+     *  and mutating it does not change the machine's registrations. */
     getBeforeObservers(): Iterable<BeforeTransitionObserver<TSubject>>;
     attachAfter(observer: AfterTransitionObserver<TSubject>): void;
     detachAfter(observer: AfterTransitionObserver<TSubject>): void;
+    /** Snapshot — see getBeforeObservers. */
     getAfterObservers(): Iterable<AfterTransitionObserver<TSubject>>;
     acquireLock(): Promise<boolean>;
+    /**
+     * Releases the mutex. A failed release — whether the mutex throws or
+     * returns false — is reported to the onReleaseError hook; it is not thrown,
+     * so manual lock management keeps its existing control flow. Inspect
+     * isLockAcquired() (or the hook) to learn whether the lock was actually
+     * freed.
+     */
     releaseLock(): Promise<void>;
     isLockAcquired(): boolean;
     isAutoreleaseLock(): boolean;
     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.
+     *
+     * Like triggerEvent/checkTransitions, this may not be called from inside an
+     * observer or condition of the same machine: the machine cannot reach idle
+     * while the runner is blocked on that very callback, so awaiting it there
+     * always deadlocks.
+     */
+    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
@@ -376,6 +450,20 @@ declare class Statemachine<TSubject = unknown> implements StatemachineInterface<
     private enqueueOperation;
     private runIfIdle;
     private runOperation;
+    /**
+     * Releases the mutex, normalizing its two failure modes into one result: a
+     * thrown error, and a false return — the failure signal MutexInterface /
+     * LockAdapterInterface define (a PostgreSQL advisory unlock that returns
+     * false, a Redis DEL that removed nothing). A false return means the lock
+     * may still be held, so it must never be mistaken for a successful release.
+     *
+     * Every failure is surfaced through the diagnostic hook — when the
+     * operation also failed, the rejection carries the operation error and this
+     * hook is the only place the release error appears.
+     *
+     * @returns null on success, or the failure wrapped for the caller to raise.
+     */
+    private releaseMutex;
     private resolveEvent;
     /**
      * Drive transitions starting from the current state, following automatic
@@ -423,11 +511,11 @@ interface LastStateHasChangedDateInterface {
     getLastStateHasChangedDate(): Date;
 }
 
-/** @deprecated No longer used internally; will be removed in v4. */
+/** @deprecated No longer used internally; will be removed in v5. */
 interface CallbackInterface {
     invoke(): MaybePromise<void>;
 }
-/** @deprecated No longer used internally; will be removed in v4. */
+/** @deprecated No longer used internally; will be removed in v5. */
 interface DispatcherInterface extends CallbackInterface {
     dispatch(event: EventInterface, args?: unknown[]): void;
     invoke(): Promise<void>;
@@ -498,11 +586,11 @@ declare class Not<TSubject = unknown> implements ConditionInterface<TSubject> {
 }
 
 /**
- * Legacy Observer for Event observers (commands attached to specific events).
+ * Observer for Event observers (commands attached to specific events).
  *
- * In v3 this is no longer used as a Statemachine observer. To run a
- * callback after every transition, implement AfterTransitionObserver
- * directly or compose a small wrapper.
+ * This is not a Statemachine observer. To run a callback after every
+ * transition, implement AfterTransitionObserver directly or compose a small
+ * wrapper.
  */
 declare class CallbackObserver implements Observer {
     private readonly callback;
@@ -609,7 +697,15 @@ declare class LockAdapterMutex implements MutexInterface {
     private readonly lockAdapter;
     private readonly resourceName;
     private acquired;
+    private pendingAcquire;
     constructor(lockAdapter: LockAdapterInterface, resourceName: string);
+    /**
+     * Overlapping calls share one underlying acquire: the `acquired` flag is
+     * only set after the adapter resolves, so without this both callers would
+     * pass the check and acquire twice on a non-idempotent adapter (database
+     * advisory locks, redis SET NX). The pending promise is cleared once it
+     * settles, so a failed acquire can still be retried.
+     */
     acquireLock(): Promise<boolean>;
     releaseLock(): Promise<boolean>;
     isAcquired(): boolean;
@@ -624,6 +720,15 @@ declare class MutexFactory<TSubject = unknown> implements MutexFactoryInterface<
     createMutex(subject: TSubject): MutexInterface;
 }
 
+/**
+ * Engine options applied to every machine the factory creates.
+ *
+ * `initialStateName`, `mutex` and `transitionSelector` are excluded: the
+ * factory derives them per subject from the state-name detector, the mutex
+ * factory and setTransitionSelector, so a template value could only
+ * contradict them.
+ */
+type FactoryStatemachineOptions<TSubject = unknown> = Omit<StatemachineOptions<TSubject>, "initialStateName" | "mutex" | "transitionSelector">;
 declare class Factory<TSubject = unknown> implements FactoryInterface<TSubject> {
     private readonly processDetector;
     private readonly stateNameDetector;
@@ -631,7 +736,15 @@ declare class Factory<TSubject = unknown> implements FactoryInterface<TSubject>
     private readonly afterObservers;
     private transitionSelector;
     private mutexFactory;
-    constructor(processDetector: ProcessDetectorInterface<TSubject>, stateNameDetector?: StateNameDetectorInterface<TSubject> | null);
+    private readonly options;
+    /**
+     * @param options Engine options applied to every machine this factory
+     * creates — back-pressure (maxQueueLength), the automatic-hop bound, lock
+     * autorelease, and the onChainedOperationError / onReleaseError diagnostic
+     * sinks. Without them, factory-created machines would silently run on
+     * defaults, which is precisely where those sinks matter most.
+     */
+    constructor(processDetector: ProcessDetectorInterface<TSubject>, stateNameDetector?: StateNameDetectorInterface<TSubject> | null, options?: FactoryStatemachineOptions<TSubject>);
     setMutexFactory(factory: MutexFactoryInterface<TSubject> | null): void;
     setTransitionSelector(selector: TransitionSelectorInterface<TSubject>): void;
     attachBeforeObserver(observer: BeforeTransitionObserver<TSubject>): void;
@@ -674,11 +787,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;
@@ -711,6 +825,20 @@ declare class LockCanNotBeAcquiredError extends FinitaError {
     constructor(message?: string);
 }
 
+/**
+ * The mutex reported a failed release by returning false, as
+ * LockAdapterInterface specifies (e.g. a PostgreSQL advisory unlock that
+ * returns false, or a Redis DEL that removed nothing).
+ *
+ * The lock must be assumed to still be held: the engine surfaces this so a
+ * failed release can never be mistaken for a successful one, which would let
+ * every later operation piggyback on — and never release — a stuck lock.
+ */
+declare class LockCanNotBeReleasedError extends FinitaError {
+    readonly code = "lockCanNotBeReleased";
+    constructor(message?: string);
+}
+
 declare class DuplicateStateError extends FinitaError {
     readonly code = "duplicateState";
     readonly stateName: string;
@@ -723,7 +851,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>>;
@@ -773,10 +901,19 @@ declare class InvalidSubjectError extends FinitaError {
     constructor(expectedInterface: string, missingMembers: Iterable<string>);
 }
 
+/** One of the simultaneously-active transitions that caused the ambiguity. */
+interface AmbiguousTransitionCandidate {
+    targetStateName: string;
+    eventName: string | null;
+    conditionName: string | null;
+    weight: number;
+}
 declare class AmbiguousTransitionError extends FinitaError {
     readonly code = "ambiguousTransition";
     readonly activeCount: number;
-    constructor(activeCount: number);
+    /** The competing transitions — what you need to resolve the ambiguity. */
+    readonly candidates: readonly Readonly<AmbiguousTransitionCandidate>[];
+    constructor(activeCount: number, candidates?: Iterable<AmbiguousTransitionCandidate>);
 }
 
 declare class AutomaticTransitionCycleError extends FinitaError {
@@ -791,4 +928,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, type AmbiguousTransitionCandidate, 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, type FactoryStatemachineOptions, FilterStateByEvent, FilterStateByFinalState, FilterStateByTransition, FilterTransitionByEvent, FinitaError, type Graph, GraphBuilder, type GraphDirection, type GraphEdge, type GraphNode, type GraphValidationCode, GraphValidationError, InvalidSubjectError, type LastStateHasChangedDateInterface, type LockAdapterInterface, LockAdapterMutex, LockCanNotBeAcquiredError, LockCanNotBeReleasedError, 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

@@ -53,6 +53,8 @@ declare class Event implements EventInterface {
     attach(observer: Observer): void;
     detach(observer: Observer): void;
     notify(args?: readonly unknown[]): Promise<void>;
+    /** Snapshot — detaching later does not change an already-returned list,
+     *  and mutating it does not change the event's registrations. */
     getObservers(): Iterable<Observer>;
     getMetadata(): Record<string, unknown>;
     getMetadataValue(key: string): unknown;
@@ -287,6 +289,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 +324,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 +347,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 +388,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;
@@ -353,17 +404,40 @@ declare class Statemachine<TSubject = unknown> implements StatemachineInterface<
     getProcess(): ProcessInterface;
     attachBefore(observer: BeforeTransitionObserver<TSubject>): void;
     detachBefore(observer: BeforeTransitionObserver<TSubject>): void;
+    /** Snapshot — detaching later does not change an already-returned list,
+     *  and mutating it does not change the machine's registrations. */
     getBeforeObservers(): Iterable<BeforeTransitionObserver<TSubject>>;
     attachAfter(observer: AfterTransitionObserver<TSubject>): void;
     detachAfter(observer: AfterTransitionObserver<TSubject>): void;
+    /** Snapshot — see getBeforeObservers. */
     getAfterObservers(): Iterable<AfterTransitionObserver<TSubject>>;
     acquireLock(): Promise<boolean>;
+    /**
+     * Releases the mutex. A failed release — whether the mutex throws or
+     * returns false — is reported to the onReleaseError hook; it is not thrown,
+     * so manual lock management keeps its existing control flow. Inspect
+     * isLockAcquired() (or the hook) to learn whether the lock was actually
+     * freed.
+     */
     releaseLock(): Promise<void>;
     isLockAcquired(): boolean;
     isAutoreleaseLock(): boolean;
     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.
+     *
+     * Like triggerEvent/checkTransitions, this may not be called from inside an
+     * observer or condition of the same machine: the machine cannot reach idle
+     * while the runner is blocked on that very callback, so awaiting it there
+     * always deadlocks.
+     */
+    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
@@ -376,6 +450,20 @@ declare class Statemachine<TSubject = unknown> implements StatemachineInterface<
     private enqueueOperation;
     private runIfIdle;
     private runOperation;
+    /**
+     * Releases the mutex, normalizing its two failure modes into one result: a
+     * thrown error, and a false return — the failure signal MutexInterface /
+     * LockAdapterInterface define (a PostgreSQL advisory unlock that returns
+     * false, a Redis DEL that removed nothing). A false return means the lock
+     * may still be held, so it must never be mistaken for a successful release.
+     *
+     * Every failure is surfaced through the diagnostic hook — when the
+     * operation also failed, the rejection carries the operation error and this
+     * hook is the only place the release error appears.
+     *
+     * @returns null on success, or the failure wrapped for the caller to raise.
+     */
+    private releaseMutex;
     private resolveEvent;
     /**
      * Drive transitions starting from the current state, following automatic
@@ -423,11 +511,11 @@ interface LastStateHasChangedDateInterface {
     getLastStateHasChangedDate(): Date;
 }
 
-/** @deprecated No longer used internally; will be removed in v4. */
+/** @deprecated No longer used internally; will be removed in v5. */
 interface CallbackInterface {
     invoke(): MaybePromise<void>;
 }
-/** @deprecated No longer used internally; will be removed in v4. */
+/** @deprecated No longer used internally; will be removed in v5. */
 interface DispatcherInterface extends CallbackInterface {
     dispatch(event: EventInterface, args?: unknown[]): void;
     invoke(): Promise<void>;
@@ -498,11 +586,11 @@ declare class Not<TSubject = unknown> implements ConditionInterface<TSubject> {
 }
 
 /**
- * Legacy Observer for Event observers (commands attached to specific events).
+ * Observer for Event observers (commands attached to specific events).
  *
- * In v3 this is no longer used as a Statemachine observer. To run a
- * callback after every transition, implement AfterTransitionObserver
- * directly or compose a small wrapper.
+ * This is not a Statemachine observer. To run a callback after every
+ * transition, implement AfterTransitionObserver directly or compose a small
+ * wrapper.
  */
 declare class CallbackObserver implements Observer {
     private readonly callback;
@@ -609,7 +697,15 @@ declare class LockAdapterMutex implements MutexInterface {
     private readonly lockAdapter;
     private readonly resourceName;
     private acquired;
+    private pendingAcquire;
     constructor(lockAdapter: LockAdapterInterface, resourceName: string);
+    /**
+     * Overlapping calls share one underlying acquire: the `acquired` flag is
+     * only set after the adapter resolves, so without this both callers would
+     * pass the check and acquire twice on a non-idempotent adapter (database
+     * advisory locks, redis SET NX). The pending promise is cleared once it
+     * settles, so a failed acquire can still be retried.
+     */
     acquireLock(): Promise<boolean>;
     releaseLock(): Promise<boolean>;
     isAcquired(): boolean;
@@ -624,6 +720,15 @@ declare class MutexFactory<TSubject = unknown> implements MutexFactoryInterface<
     createMutex(subject: TSubject): MutexInterface;
 }
 
+/**
+ * Engine options applied to every machine the factory creates.
+ *
+ * `initialStateName`, `mutex` and `transitionSelector` are excluded: the
+ * factory derives them per subject from the state-name detector, the mutex
+ * factory and setTransitionSelector, so a template value could only
+ * contradict them.
+ */
+type FactoryStatemachineOptions<TSubject = unknown> = Omit<StatemachineOptions<TSubject>, "initialStateName" | "mutex" | "transitionSelector">;
 declare class Factory<TSubject = unknown> implements FactoryInterface<TSubject> {
     private readonly processDetector;
     private readonly stateNameDetector;
@@ -631,7 +736,15 @@ declare class Factory<TSubject = unknown> implements FactoryInterface<TSubject>
     private readonly afterObservers;
     private transitionSelector;
     private mutexFactory;
-    constructor(processDetector: ProcessDetectorInterface<TSubject>, stateNameDetector?: StateNameDetectorInterface<TSubject> | null);
+    private readonly options;
+    /**
+     * @param options Engine options applied to every machine this factory
+     * creates — back-pressure (maxQueueLength), the automatic-hop bound, lock
+     * autorelease, and the onChainedOperationError / onReleaseError diagnostic
+     * sinks. Without them, factory-created machines would silently run on
+     * defaults, which is precisely where those sinks matter most.
+     */
+    constructor(processDetector: ProcessDetectorInterface<TSubject>, stateNameDetector?: StateNameDetectorInterface<TSubject> | null, options?: FactoryStatemachineOptions<TSubject>);
     setMutexFactory(factory: MutexFactoryInterface<TSubject> | null): void;
     setTransitionSelector(selector: TransitionSelectorInterface<TSubject>): void;
     attachBeforeObserver(observer: BeforeTransitionObserver<TSubject>): void;
@@ -674,11 +787,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;
@@ -711,6 +825,20 @@ declare class LockCanNotBeAcquiredError extends FinitaError {
     constructor(message?: string);
 }
 
+/**
+ * The mutex reported a failed release by returning false, as
+ * LockAdapterInterface specifies (e.g. a PostgreSQL advisory unlock that
+ * returns false, or a Redis DEL that removed nothing).
+ *
+ * The lock must be assumed to still be held: the engine surfaces this so a
+ * failed release can never be mistaken for a successful one, which would let
+ * every later operation piggyback on — and never release — a stuck lock.
+ */
+declare class LockCanNotBeReleasedError extends FinitaError {
+    readonly code = "lockCanNotBeReleased";
+    constructor(message?: string);
+}
+
 declare class DuplicateStateError extends FinitaError {
     readonly code = "duplicateState";
     readonly stateName: string;
@@ -723,7 +851,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>>;
@@ -773,10 +901,19 @@ declare class InvalidSubjectError extends FinitaError {
     constructor(expectedInterface: string, missingMembers: Iterable<string>);
 }
 
+/** One of the simultaneously-active transitions that caused the ambiguity. */
+interface AmbiguousTransitionCandidate {
+    targetStateName: string;
+    eventName: string | null;
+    conditionName: string | null;
+    weight: number;
+}
 declare class AmbiguousTransitionError extends FinitaError {
     readonly code = "ambiguousTransition";
     readonly activeCount: number;
-    constructor(activeCount: number);
+    /** The competing transitions — what you need to resolve the ambiguity. */
+    readonly candidates: readonly Readonly<AmbiguousTransitionCandidate>[];
+    constructor(activeCount: number, candidates?: Iterable<AmbiguousTransitionCandidate>);
 }
 
 declare class AutomaticTransitionCycleError extends FinitaError {
@@ -791,4 +928,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, type AmbiguousTransitionCandidate, 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, type FactoryStatemachineOptions, FilterStateByEvent, FilterStateByFinalState, FilterStateByTransition, FilterTransitionByEvent, FinitaError, type Graph, GraphBuilder, type GraphDirection, type GraphEdge, type GraphNode, type GraphValidationCode, GraphValidationError, InvalidSubjectError, type LastStateHasChangedDateInterface, type LockAdapterInterface, LockAdapterMutex, LockCanNotBeAcquiredError, LockCanNotBeReleasedError, 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 };