@camcima/finita 4.1.0 → 4.3.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;
@@ -133,6 +135,8 @@ declare class State implements StateInterface {
      */
     _initTransitions(key: InternalConstructionKey, transitions: Iterable<TransitionInterface>): void;
     getName(): string;
+    /** Snapshot — the graph is shared by every machine built from the
+     *  process, so callers must never receive the collection itself. */
     getTransitions(): Iterable<TransitionInterface>;
     getEventNames(): string[];
     hasEvent(name: string): boolean;
@@ -187,7 +191,9 @@ declare class ProcessBuilder<TSubject = unknown> {
     private findInitialStateName;
     private validateTransitionEndpoints;
     /** Transition identity: (fromState, eventName, toState). Used by both the
-     *  conflict check and the build-time dedup — keep them in lockstep. */
+     *  conflict check and the build-time dedup — keep them in lockstep.
+     *  Encoded as a JSON tuple, not a delimiter join: names may contain any
+     *  character, so no delimiter can keep distinct tuples distinct. */
     private static transitionKey;
     private validateNoConflictingDuplicates;
     private collectEventNamesByState;
@@ -349,8 +355,11 @@ interface StatemachineOptions<TSubject = unknown> {
      * 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.
+     * The hook may be async. It is not awaited, and both exceptions it throws
+     * and rejections of the promise it returns are swallowed — it must not be
+     * able to break the machine's drain loop or surface as an unhandled
+     * rejection. (The return type stays `void`, which already admits async
+     * functions, so callbacks returning incidental values keep compiling.)
      */
     onChainedOperationError?: (error: unknown, info: {
         eventName: string;
@@ -372,7 +381,8 @@ interface StatemachineOptions<TSubject = unknown> {
      * 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.
+     * behavior. The hook may be async; it is not awaited, and both exceptions
+     * it throws and rejections of the promise it returns are swallowed.
      */
     onReleaseError?: (error: unknown) => void;
 }
@@ -391,6 +401,8 @@ declare class Statemachine<TSubject = unknown> implements StatemachineInterface<
     private running;
     private idleWaiters;
     private inSyncCallback;
+    /** Set when releasing a held lock fails; see LockOwnershipUncertainError. */
+    private ownershipUncertainty;
     private readonly beforeObservers;
     private readonly afterObservers;
     private readonly onChainedOperationError?;
@@ -402,11 +414,24 @@ 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.
+     *
+     * A failed release of a held lock makes every later operation reject with
+     * LockOwnershipUncertainError; a successful call here is how to recover.
+     */
     releaseLock(): Promise<void>;
     isLockAcquired(): boolean;
     isAutoreleaseLock(): boolean;
@@ -419,6 +444,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 +463,33 @@ 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.
+     *
+     * A failure while the mutex claimed to hold the lock leaves ownership
+     * uncertain and blocks later operations; a success clears that state. A
+     * failed release of a lock the mutex did not claim (a defensive manual
+     * release) is still reported but changes nothing.
+     *
+     * @returns null on success, or the failure wrapped for the caller to raise.
+     */
+    private releaseMutex;
+    /**
+     * Runs a user diagnostic hook in isolation. Neither a synchronous throw nor
+     * a rejection of a returned promise may reach the drain loop or the host:
+     * an unavailable telemetry backend must not fail an operation or, via an
+     * unhandled rejection, terminate the process. A returned promise is
+     * deliberately not awaited — a slow reporter must not stall the runner.
+     */
+    private callDiagnosticHook;
     private resolveEvent;
     /**
      * Drive transitions starting from the current state, following automatic
@@ -480,11 +537,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>;
@@ -532,34 +589,45 @@ declare abstract class CompositeCondition<TSubject = unknown> implements Conditi
     constructor(joinWord: string, condition: ConditionInterface<TSubject>);
     protected addCondition(condition: ConditionInterface<TSubject>): this;
     getName(): string;
-    abstract checkCondition(subject: TSubject, context: Map<string, unknown>): Promise<boolean>;
+    abstract checkCondition(subject: TSubject, context: Map<string, unknown>): MaybePromise<boolean>;
+    /**
+     * Evaluates children in order, stopping at the first whose result equals
+     * `shortCircuitOn`. A child that returns a plain boolean is consumed
+     * synchronously; only a returned promise is awaited. Awaiting plain values
+     * would yield between children and end the machine's synchronous
+     * re-entrancy guard, so a re-entrant later child would deadlock instead of
+     * throwing ReentrancyError. For the same reason the composite itself
+     * returns a plain boolean when every child it evaluated did.
+     */
+    protected evaluate(subject: TSubject, context: Map<string, unknown>, shortCircuitOn: boolean): MaybePromise<boolean>;
 }
 
 declare class AndComposite<TSubject = unknown> extends CompositeCondition<TSubject> {
     constructor(condition: ConditionInterface<TSubject>);
     addAnd(condition: ConditionInterface<TSubject>): this;
-    checkCondition(subject: TSubject, context: Map<string, unknown>): Promise<boolean>;
+    checkCondition(subject: TSubject, context: Map<string, unknown>): MaybePromise<boolean>;
 }
 
 declare class OrComposite<TSubject = unknown> extends CompositeCondition<TSubject> {
     constructor(condition: ConditionInterface<TSubject>);
     addOr(condition: ConditionInterface<TSubject>): this;
-    checkCondition(subject: TSubject, context: Map<string, unknown>): Promise<boolean>;
+    checkCondition(subject: TSubject, context: Map<string, unknown>): MaybePromise<boolean>;
 }
 
 declare class Not<TSubject = unknown> implements ConditionInterface<TSubject> {
     private readonly condition;
     constructor(condition: ConditionInterface<TSubject>);
     getName(): string;
-    checkCondition(subject: TSubject, context: Map<string, unknown>): Promise<boolean>;
+    /** Stays synchronous for a synchronous child — see CompositeCondition. */
+    checkCondition(subject: TSubject, context: Map<string, unknown>): MaybePromise<boolean>;
 }
 
 /**
- * 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 +734,20 @@ 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.
+     *
+     * The clearing is attached to the attempt only after it is stored: an
+     * adapter that throws synchronously settles the attempt before the
+     * assignment would otherwise run, and clearing inside the attempt itself
+     * would then leave the rejected promise cached forever.
+     */
     acquireLock(): Promise<boolean>;
     releaseLock(): Promise<boolean>;
     isAcquired(): boolean;
@@ -681,6 +762,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 +778,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;
@@ -754,7 +852,7 @@ declare class GraphBuilder {
 
 declare abstract class FinitaError extends Error {
     abstract readonly code: string;
-    constructor(message?: string);
+    constructor(message?: string, options?: ErrorOptions);
 }
 
 declare class WrongEventForStateError extends FinitaError {
@@ -769,6 +867,37 @@ 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);
+}
+
+/**
+ * A lock release failed earlier, so the machine can no longer tell whether it
+ * still holds the lock: the unlock may have taken effect remotely with its
+ * reply lost, or may never have happened. Running further operations on the
+ * old ownership flag could violate mutual exclusion, so every operation is
+ * rejected with this error until a manual Statemachine.releaseLock()
+ * succeeds.
+ *
+ * `cause` carries the release failure. When the release cannot be confirmed
+ * — typically because the lock was in fact already freed — discard the
+ * machine and build a new one from persisted state.
+ */
+declare class LockOwnershipUncertainError extends FinitaError {
+    readonly code = "lockOwnershipUncertain";
+    constructor(cause: unknown);
+}
+
 declare class DuplicateStateError extends FinitaError {
     readonly code = "duplicateState";
     readonly stateName: string;
@@ -831,10 +960,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 +992,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, LockOwnershipUncertainError, 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;
@@ -133,6 +135,8 @@ declare class State implements StateInterface {
      */
     _initTransitions(key: InternalConstructionKey, transitions: Iterable<TransitionInterface>): void;
     getName(): string;
+    /** Snapshot — the graph is shared by every machine built from the
+     *  process, so callers must never receive the collection itself. */
     getTransitions(): Iterable<TransitionInterface>;
     getEventNames(): string[];
     hasEvent(name: string): boolean;
@@ -187,7 +191,9 @@ declare class ProcessBuilder<TSubject = unknown> {
     private findInitialStateName;
     private validateTransitionEndpoints;
     /** Transition identity: (fromState, eventName, toState). Used by both the
-     *  conflict check and the build-time dedup — keep them in lockstep. */
+     *  conflict check and the build-time dedup — keep them in lockstep.
+     *  Encoded as a JSON tuple, not a delimiter join: names may contain any
+     *  character, so no delimiter can keep distinct tuples distinct. */
     private static transitionKey;
     private validateNoConflictingDuplicates;
     private collectEventNamesByState;
@@ -349,8 +355,11 @@ interface StatemachineOptions<TSubject = unknown> {
      * 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.
+     * The hook may be async. It is not awaited, and both exceptions it throws
+     * and rejections of the promise it returns are swallowed — it must not be
+     * able to break the machine's drain loop or surface as an unhandled
+     * rejection. (The return type stays `void`, which already admits async
+     * functions, so callbacks returning incidental values keep compiling.)
      */
     onChainedOperationError?: (error: unknown, info: {
         eventName: string;
@@ -372,7 +381,8 @@ interface StatemachineOptions<TSubject = unknown> {
      * 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.
+     * behavior. The hook may be async; it is not awaited, and both exceptions
+     * it throws and rejections of the promise it returns are swallowed.
      */
     onReleaseError?: (error: unknown) => void;
 }
@@ -391,6 +401,8 @@ declare class Statemachine<TSubject = unknown> implements StatemachineInterface<
     private running;
     private idleWaiters;
     private inSyncCallback;
+    /** Set when releasing a held lock fails; see LockOwnershipUncertainError. */
+    private ownershipUncertainty;
     private readonly beforeObservers;
     private readonly afterObservers;
     private readonly onChainedOperationError?;
@@ -402,11 +414,24 @@ 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.
+     *
+     * A failed release of a held lock makes every later operation reject with
+     * LockOwnershipUncertainError; a successful call here is how to recover.
+     */
     releaseLock(): Promise<void>;
     isLockAcquired(): boolean;
     isAutoreleaseLock(): boolean;
@@ -419,6 +444,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 +463,33 @@ 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.
+     *
+     * A failure while the mutex claimed to hold the lock leaves ownership
+     * uncertain and blocks later operations; a success clears that state. A
+     * failed release of a lock the mutex did not claim (a defensive manual
+     * release) is still reported but changes nothing.
+     *
+     * @returns null on success, or the failure wrapped for the caller to raise.
+     */
+    private releaseMutex;
+    /**
+     * Runs a user diagnostic hook in isolation. Neither a synchronous throw nor
+     * a rejection of a returned promise may reach the drain loop or the host:
+     * an unavailable telemetry backend must not fail an operation or, via an
+     * unhandled rejection, terminate the process. A returned promise is
+     * deliberately not awaited — a slow reporter must not stall the runner.
+     */
+    private callDiagnosticHook;
     private resolveEvent;
     /**
      * Drive transitions starting from the current state, following automatic
@@ -480,11 +537,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>;
@@ -532,34 +589,45 @@ declare abstract class CompositeCondition<TSubject = unknown> implements Conditi
     constructor(joinWord: string, condition: ConditionInterface<TSubject>);
     protected addCondition(condition: ConditionInterface<TSubject>): this;
     getName(): string;
-    abstract checkCondition(subject: TSubject, context: Map<string, unknown>): Promise<boolean>;
+    abstract checkCondition(subject: TSubject, context: Map<string, unknown>): MaybePromise<boolean>;
+    /**
+     * Evaluates children in order, stopping at the first whose result equals
+     * `shortCircuitOn`. A child that returns a plain boolean is consumed
+     * synchronously; only a returned promise is awaited. Awaiting plain values
+     * would yield between children and end the machine's synchronous
+     * re-entrancy guard, so a re-entrant later child would deadlock instead of
+     * throwing ReentrancyError. For the same reason the composite itself
+     * returns a plain boolean when every child it evaluated did.
+     */
+    protected evaluate(subject: TSubject, context: Map<string, unknown>, shortCircuitOn: boolean): MaybePromise<boolean>;
 }
 
 declare class AndComposite<TSubject = unknown> extends CompositeCondition<TSubject> {
     constructor(condition: ConditionInterface<TSubject>);
     addAnd(condition: ConditionInterface<TSubject>): this;
-    checkCondition(subject: TSubject, context: Map<string, unknown>): Promise<boolean>;
+    checkCondition(subject: TSubject, context: Map<string, unknown>): MaybePromise<boolean>;
 }
 
 declare class OrComposite<TSubject = unknown> extends CompositeCondition<TSubject> {
     constructor(condition: ConditionInterface<TSubject>);
     addOr(condition: ConditionInterface<TSubject>): this;
-    checkCondition(subject: TSubject, context: Map<string, unknown>): Promise<boolean>;
+    checkCondition(subject: TSubject, context: Map<string, unknown>): MaybePromise<boolean>;
 }
 
 declare class Not<TSubject = unknown> implements ConditionInterface<TSubject> {
     private readonly condition;
     constructor(condition: ConditionInterface<TSubject>);
     getName(): string;
-    checkCondition(subject: TSubject, context: Map<string, unknown>): Promise<boolean>;
+    /** Stays synchronous for a synchronous child — see CompositeCondition. */
+    checkCondition(subject: TSubject, context: Map<string, unknown>): MaybePromise<boolean>;
 }
 
 /**
- * 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 +734,20 @@ 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.
+     *
+     * The clearing is attached to the attempt only after it is stored: an
+     * adapter that throws synchronously settles the attempt before the
+     * assignment would otherwise run, and clearing inside the attempt itself
+     * would then leave the rejected promise cached forever.
+     */
     acquireLock(): Promise<boolean>;
     releaseLock(): Promise<boolean>;
     isAcquired(): boolean;
@@ -681,6 +762,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 +778,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;
@@ -754,7 +852,7 @@ declare class GraphBuilder {
 
 declare abstract class FinitaError extends Error {
     abstract readonly code: string;
-    constructor(message?: string);
+    constructor(message?: string, options?: ErrorOptions);
 }
 
 declare class WrongEventForStateError extends FinitaError {
@@ -769,6 +867,37 @@ 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);
+}
+
+/**
+ * A lock release failed earlier, so the machine can no longer tell whether it
+ * still holds the lock: the unlock may have taken effect remotely with its
+ * reply lost, or may never have happened. Running further operations on the
+ * old ownership flag could violate mutual exclusion, so every operation is
+ * rejected with this error until a manual Statemachine.releaseLock()
+ * succeeds.
+ *
+ * `cause` carries the release failure. When the release cannot be confirmed
+ * — typically because the lock was in fact already freed — discard the
+ * machine and build a new one from persisted state.
+ */
+declare class LockOwnershipUncertainError extends FinitaError {
+    readonly code = "lockOwnershipUncertain";
+    constructor(cause: unknown);
+}
+
 declare class DuplicateStateError extends FinitaError {
     readonly code = "duplicateState";
     readonly stateName: string;
@@ -831,10 +960,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 +992,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, LockOwnershipUncertainError, 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 };