@camcima/finita 4.1.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;
@@ -402,11 +404,21 @@ 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;
@@ -419,6 +431,11 @@ declare class Statemachine<TSubject = unknown> implements StatemachineInterface<
      * 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:
@@ -433,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
@@ -480,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>;
@@ -555,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;
@@ -666,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;
@@ -681,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;
@@ -688,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;
@@ -769,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;
@@ -831,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 {
@@ -854,4 +933,4 @@ declare class QueueLimitExceededError extends FinitaError {
     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 };
+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;
@@ -402,11 +404,21 @@ 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;
@@ -419,6 +431,11 @@ declare class Statemachine<TSubject = unknown> implements StatemachineInterface<
      * 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:
@@ -433,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
@@ -480,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>;
@@ -555,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;
@@ -666,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;
@@ -681,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;
@@ -688,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;
@@ -769,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;
@@ -831,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 {
@@ -854,4 +933,4 @@ declare class QueueLimitExceededError extends FinitaError {
     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 };
+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.js

@@ -31,8 +31,10 @@ var Event = class {
       await observer.update(this, args);
     }
   }
+  /** Snapshot — detaching later does not change an already-returned list,
+   *  and mutating it does not change the event's registrations. */
   getObservers() {
-    return this.observers;
+    return [...this.observers];
   }
   getMetadata() {
     return Object.fromEntries(this.metadata);
@@ -593,12 +595,30 @@ var ProcessBuilder = class _ProcessBuilder {
 var AmbiguousTransitionError = class extends FinitaError {
   code = "ambiguousTransition";
   activeCount;
-  constructor(activeCount) {
-    super(`More than one transition is active! (active count: ${activeCount})`);
+  /** The competing transitions — what you need to resolve the ambiguity. */
+  candidates;
+  constructor(activeCount, candidates = []) {
+    const list = Array.from(candidates, (c) => Object.freeze({ ...c }));
+    const detail = list.length > 0 ? ` Candidates: ${list.map(describeCandidate).join("; ")}.` : "";
+    super(
+      `More than one transition is active! (active count: ${activeCount})${detail}`
+    );
     this.name = "AmbiguousTransitionError";
     this.activeCount = activeCount;
+    this.candidates = Object.freeze(list);
   }
 };
+function describeCandidate(candidate) {
+  const parts = [`-> "${candidate.targetStateName}"`];
+  parts.push(
+    candidate.eventName === null ? "on <automatic>" : `on event "${candidate.eventName}"`
+  );
+  if (candidate.conditionName !== null) {
+    parts.push(`if ${candidate.conditionName}`);
+  }
+  parts.push(`weight ${candidate.weight}`);
+  return parts.join(" ");
+}
 
 // src/selector/OneOrNoneActiveTransition.ts
 var OneOrNoneActiveTransition = class {
@@ -610,7 +630,15 @@ var OneOrNoneActiveTransition = class {
       case 1:
         return arr[0];
       default:
-        throw new AmbiguousTransitionError(arr.length);
+        throw new AmbiguousTransitionError(
+          arr.length,
+          arr.map((transition) => ({
+            targetStateName: transition.getTargetState().getName(),
+            eventName: transition.getEventName(),
+            conditionName: transition.getConditionName(),
+            weight: transition.getWeight()
+          }))
+        );
     }
   }
 };
@@ -687,6 +715,15 @@ var LockCanNotBeAcquiredError = class extends FinitaError {
   }
 };
 
+// src/error/LockCanNotBeReleasedError.ts
+var LockCanNotBeReleasedError = class extends FinitaError {
+  code = "lockCanNotBeReleased";
+  constructor(message = "Lock can not be released! releaseLock() returned false; the lock may still be held.") {
+    super(message);
+    this.name = "LockCanNotBeReleasedError";
+  }
+};
+
 // src/error/AutomaticTransitionCycleError.ts
 var AutomaticTransitionCycleError = class extends FinitaError {
   code = "automaticTransitionCycle";
@@ -789,8 +826,10 @@ var Statemachine = class {
     const idx = this.beforeObservers.indexOf(observer);
     if (idx >= 0) this.beforeObservers.splice(idx, 1);
   }
+  /** Snapshot — detaching later does not change an already-returned list,
+   *  and mutating it does not change the machine's registrations. */
   getBeforeObservers() {
-    return this.beforeObservers;
+    return [...this.beforeObservers];
   }
   attachAfter(observer) {
     if (this.afterObservers.includes(observer)) return;
@@ -800,15 +839,23 @@ var Statemachine = class {
     const idx = this.afterObservers.indexOf(observer);
     if (idx >= 0) this.afterObservers.splice(idx, 1);
   }
+  /** Snapshot — see getBeforeObservers. */
   getAfterObservers() {
-    return this.afterObservers;
+    return [...this.afterObservers];
   }
   // --- public locking ---
   async acquireLock() {
     return this.mutex.acquireLock();
   }
+  /**
+   * 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.
+   */
   async releaseLock() {
-    await this.mutex.releaseLock();
+    await this.releaseMutex();
   }
   isLockAcquired() {
     return this.mutex.isAcquired();
@@ -838,8 +885,14 @@ var Statemachine = class {
    * 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() {
+    this.assertNotReentrant("whenIdle()");
     if (!this.running && this.queue.isEmpty()) {
       return Promise.resolve();
     }
@@ -918,15 +971,8 @@ var Statemachine = class {
       failure = { err };
     } finally {
       if (acquiredHere && this.autoreleaseLock) {
-        try {
-          await this.mutex.releaseLock();
-        } catch (err) {
-          try {
-            this.onReleaseError?.(err);
-          } catch {
-          }
-          if (!failure) failure = { err };
-        }
+        const releaseFailure = await this.releaseMutex();
+        if (releaseFailure && !failure) failure = releaseFailure;
       }
     }
     if (failure) {
@@ -935,6 +981,36 @@ var Statemachine = class {
       op.resolve();
     }
   }
+  /**
+   * 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.
+   */
+  async releaseMutex() {
+    let failure = null;
+    try {
+      if (!await this.mutex.releaseLock()) {
+        failure = { err: new LockCanNotBeReleasedError() };
+      }
+    } catch (err) {
+      failure = { err };
+    }
+    if (failure) {
+      try {
+        this.onReleaseError?.(failure.err);
+      } catch {
+      }
+    }
+    return failure;
+  }
   resolveEvent(name) {
     if (!this.currentState.hasEvent(name)) {
       throw new WrongEventForStateError(this.currentState.getName(), name);
@@ -1408,15 +1484,31 @@ var LockAdapterMutex = class {
   lockAdapter;
   resourceName;
   acquired = false;
+  pendingAcquire = null;
   constructor(lockAdapter, resourceName) {
     this.lockAdapter = lockAdapter;
     this.resourceName = resourceName;
   }
+  /**
+   * 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.
+   */
   async acquireLock() {
-    if (!this.acquired) {
-      this.acquired = await this.lockAdapter.acquireLock(this.resourceName);
-    }
-    return this.acquired;
+    if (this.acquired) {
+      return true;
+    }
+    this.pendingAcquire ??= (async () => {
+      try {
+        this.acquired = await this.lockAdapter.acquireLock(this.resourceName);
+        return this.acquired;
+      } finally {
+        this.pendingAcquire = null;
+      }
+    })();
+    return this.pendingAcquire;
   }
   async releaseLock() {
     if (this.acquired) {
@@ -1460,9 +1552,18 @@ var Factory = class {
   afterObservers = /* @__PURE__ */ new Set();
   transitionSelector = null;
   mutexFactory = null;
-  constructor(processDetector, stateNameDetector) {
+  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, stateNameDetector, options = {}) {
     this.processDetector = processDetector;
     this.stateNameDetector = stateNameDetector ?? null;
+    this.options = { ...options };
   }
   setMutexFactory(factory) {
     this.mutexFactory = factory;
@@ -1487,6 +1588,7 @@ var Factory = class {
     const stateName = this.stateNameDetector ? this.stateNameDetector.detectCurrentStateName(subject) : void 0;
     const mutex = this.mutexFactory ? await this.mutexFactory.createMutex(subject) : void 0;
     const sm = new Statemachine(subject, process, {
+      ...this.options,
       initialStateName: stateName ?? void 0,
       transitionSelector: this.transitionSelector ?? void 0,
       mutex: mutex ?? void 0
@@ -1716,6 +1818,7 @@ export {
   InvalidSubjectError,
   LockAdapterMutex,
   LockCanNotBeAcquiredError,
+  LockCanNotBeReleasedError,
   MutexFactory,
   Not,
   NullMutex,