@camcima/finita 3.0.1 → 4.1.0

package/dist/index.cjs

@@ -52,6 +52,8 @@ __export(index_exports, {
   ProcessBuilder: () => ProcessBuilder,
   ProcessFinalizedError: () => ProcessFinalizedError,
   ProcessNotFoundError: () => ProcessNotFoundError,
+  QueueLimitExceededError: () => QueueLimitExceededError,
+  ReentrancyError: () => ReentrancyError,
   ScoreTransition: () => ScoreTransition,
   SingleProcessDetector: () => SingleProcessDetector,
   State: () => State,
@@ -74,23 +76,22 @@ var Event = class {
   name;
   observers = /* @__PURE__ */ new Set();
   metadata = /* @__PURE__ */ new Map();
-  invokeArgs = [];
   constructor(name) {
     this.name = name;
   }
   getName() {
     return this.name;
   }
+  /**
+   * @deprecated Always returns []. Invoke args are now passed directly to
+   * Observer.update — reading them from the event was racy when one
+   * Process served multiple Statemachines.
+   */
   getInvokeArgs() {
-    return this.invokeArgs;
+    return [];
   }
   async invoke(...args) {
-    this.invokeArgs = args;
-    try {
-      await this.notify();
-    } finally {
-      this.invokeArgs = [];
-    }
+    await this.notify(args);
   }
   attach(observer) {
     this.observers.add(observer);
@@ -98,9 +99,9 @@ var Event = class {
   detach(observer) {
     this.observers.delete(observer);
   }
-  async notify() {
-    for (const observer of this.observers) {
-      await observer.update(this);
+  async notify(args) {
+    for (const observer of [...this.observers]) {
+      await observer.update(this, args);
     }
   }
   getObservers() {
@@ -256,6 +257,7 @@ var State = class {
       throw new Error(`State "${this.name}" transitions already set`);
     }
     this._transitions = new Set(transitions);
+    Object.freeze(this);
   }
   getName() {
     return this.name;
@@ -306,6 +308,7 @@ var Transition = class {
     this.eventName = eventName;
     this.condition = condition;
     this.weight = weight;
+    Object.freeze(this);
   }
   getTargetState() {
     return this.targetState;
@@ -382,8 +385,9 @@ var DuplicateTransitionError = class extends FinitaError {
     const eventLabel = conflict.eventName ?? "<automatic>";
     const existing = conflict.existingConditionName ?? "<no condition>";
     const incoming = conflict.newConditionName ?? "<no condition>";
+    const weightInfo = conflict.existingWeight !== void 0 && conflict.newWeight !== void 0 && conflict.existingWeight !== conflict.newWeight ? `, existing weight ${conflict.existingWeight} vs new weight ${conflict.newWeight}` : "";
     super(
-      `Conflicting transition declarations from "${conflict.fromState}" to "${conflict.toState}" on event "${eventLabel}": existing condition "${existing}" vs new condition "${incoming}"`
+      `Conflicting transition declarations from "${conflict.fromState}" to "${conflict.toState}" on event "${eventLabel}": existing condition "${existing}" vs new condition "${incoming}"${weightInfo}`
     );
     this.name = "DuplicateTransitionError";
     this.conflict = Object.freeze({ ...conflict });
@@ -391,7 +395,7 @@ var DuplicateTransitionError = class extends FinitaError {
 };
 
 // src/ProcessBuilder.ts
-var ProcessBuilder = class {
+var ProcessBuilder = class _ProcessBuilder {
   processName;
   stateSpecs = /* @__PURE__ */ new Map();
   transitionSpecs = [];
@@ -406,6 +410,9 @@ var ProcessBuilder = class {
     if (this.stateSpecs.has(name)) {
       throw new DuplicateStateError(name);
     }
+    this.validateName("invalidStateName", name, `addState("${name}")`, {
+      stateName: name
+    });
     this.stateSpecs.set(name, {
       name,
       initial: options.initial === true,
@@ -419,32 +426,37 @@ var ProcessBuilder = class {
     }
     let eventName = null;
     if (options.event !== void 0) {
-      const raw = options.event;
-      if (raw.trim() === "" || raw !== raw.trim()) {
-        throw new GraphValidationError(
-          "invalidEventName",
-          `addTransition called with an empty or whitespace-padded event name from "${fromState}" to "${toState}"`,
-          { fromState, toState, eventName: raw }
-        );
-      }
-      eventName = raw;
+      this.validateName(
+        "invalidEventName",
+        options.event,
+        `addTransition called with an invalid event name from "${fromState}" to "${toState}"`,
+        { fromState, toState, eventName: options.event }
+      );
+      eventName = options.event;
     }
     if (options.condition) {
       const conditionName = options.condition.getName();
-      if (conditionName.trim() === "") {
-        throw new GraphValidationError(
-          "invalidConditionName",
-          `addTransition called with an empty/whitespace condition name from "${fromState}" to "${toState}"`,
-          { fromState, toState, conditionName }
-        );
-      }
+      this.validateName(
+        "invalidConditionName",
+        conditionName,
+        `addTransition called with an invalid condition name from "${fromState}" to "${toState}"`,
+        { fromState, toState, conditionName }
+      );
+    }
+    const weight = options.weight ?? 1;
+    if (!Number.isFinite(weight)) {
+      throw new GraphValidationError(
+        "invalidTransitionWeight",
+        `addTransition from "${fromState}" to "${toState}": weight must be a finite number; got ${String(weight)}`,
+        { fromState, toState, eventName, weight }
+      );
     }
     this.transitionSpecs.push({
       fromState,
       toState,
       eventName,
       condition: options.condition ?? null,
-      weight: options.weight ?? 1
+      weight
     });
     return this;
   }
@@ -452,7 +464,6 @@ var ProcessBuilder = class {
     if (this.built) {
       throw new ProcessFinalizedError(this.processName);
     }
-    this.built = true;
     this.validateInitialState();
     this.validateTransitionEndpoints();
     this.validateNoConflictingDuplicates();
@@ -463,6 +474,7 @@ var ProcessBuilder = class {
       this.validateOrphans(finalStates, initialName);
     }
     const initialState = finalStates.get(initialName);
+    this.built = true;
     return new Process(
       INTERNAL_CONSTRUCTION_KEY,
       this.processName,
@@ -471,6 +483,16 @@ var ProcessBuilder = class {
     );
   }
   // --- private helpers ---
+  /** One name rule for every named entity: non-empty, no leading/trailing whitespace. */
+  validateName(code, raw, description, details) {
+    if (raw.trim() === "" || raw !== raw.trim()) {
+      throw new GraphValidationError(
+        code,
+        `${description}: name ${JSON.stringify(raw)} is empty or whitespace-padded`,
+        details
+      );
+    }
+  }
   validateInitialState() {
     const initials = Array.from(this.stateSpecs.values()).filter(
       (s) => s.initial
@@ -522,22 +544,29 @@ var ProcessBuilder = class {
       }
     }
   }
+  /** Transition identity: (fromState, eventName, toState). Used by both the
+   *  conflict check and the build-time dedup — keep them in lockstep. */
+  static transitionKey(t) {
+    return `${t.fromState}\0${t.eventName ?? ""}\0${t.toState}`;
+  }
   validateNoConflictingDuplicates() {
     const seen = /* @__PURE__ */ new Map();
     for (const t of this.transitionSpecs) {
-      const key = `${t.fromState}\0${t.eventName ?? ""}\0${t.toState}`;
+      const key = _ProcessBuilder.transitionKey(t);
       const existing = seen.get(key);
       if (!existing) {
         seen.set(key, t);
         continue;
       }
-      if (existing.condition !== t.condition) {
+      if (existing.condition !== t.condition || existing.weight !== t.weight) {
         throw new DuplicateTransitionError({
           fromState: t.fromState,
           toState: t.toState,
           eventName: t.eventName,
           existingConditionName: existing.condition ? existing.condition.getName() : null,
-          newConditionName: t.condition ? t.condition.getName() : null
+          newConditionName: t.condition ? t.condition.getName() : null,
+          existingWeight: existing.weight,
+          newWeight: t.weight
         });
       }
     }
@@ -581,23 +610,12 @@ var ProcessBuilder = class {
       );
     }
     const dedupSeen = /* @__PURE__ */ new Set();
-    const conditionId = /* @__PURE__ */ new Map();
-    let nextConditionId = 0;
-    const idForCondition = (cond) => {
-      if (cond === null) return "";
-      let id = conditionId.get(cond);
-      if (id === void 0) {
-        id = ++nextConditionId;
-        conditionId.set(cond, id);
-      }
-      return String(id);
-    };
     const transitionsByState = /* @__PURE__ */ new Map();
     for (const spec of this.stateSpecs.values()) {
       transitionsByState.set(spec.name, []);
     }
     for (const tSpec of this.transitionSpecs) {
-      const dedupKey = `${tSpec.fromState}\0${tSpec.eventName ?? ""}\0${tSpec.toState}\0${idForCondition(tSpec.condition)}`;
+      const dedupKey = _ProcessBuilder.transitionKey(tSpec);
       if (dedupSeen.has(dedupKey)) continue;
       dedupSeen.add(dedupKey);
       const targetState = built.get(tSpec.toState);
@@ -689,27 +707,6 @@ var NullMutex = class {
   }
 };
 
-// src/internal/Dispatcher.ts
-var Dispatcher = class {
-  commands = [];
-  ready = false;
-  dispatch(event, args = []) {
-    if (this.ready) {
-      throw new Error("Was already invoked!");
-    }
-    this.commands.push({ event, args });
-  }
-  async invoke() {
-    if (this.ready) {
-      throw new Error("Was already invoked!");
-    }
-    for (const { event, args } of this.commands) {
-      await event.invoke(...args);
-    }
-    this.ready = true;
-  }
-};
-
 // src/internal/OperationQueue.ts
 var OperationQueue = class {
   items = [];
@@ -722,14 +719,18 @@ var OperationQueue = class {
   isEmpty() {
     return this.items.length === 0;
   }
+  size() {
+    return this.items.length;
+  }
 };
 
 // src/filter/ActiveTransitionFilter.ts
 var ActiveTransitionFilter = class {
-  static async filter(transitions, subject, context, event) {
+  static async filter(transitions, subject, context, event, wrap) {
+    const run = wrap ?? ((fn) => fn());
     const active = [];
     for (const transition of transitions) {
-      if (await transition.isActive(subject, context, event)) {
+      if (await run(() => transition.isActive(subject, context, event))) {
         active.push(transition);
       }
     }
@@ -762,16 +763,37 @@ var LockCanNotBeAcquiredError = class extends FinitaError {
 // src/error/AutomaticTransitionCycleError.ts
 var AutomaticTransitionCycleError = class extends FinitaError {
   code = "automaticTransitionCycle";
-  targetStateName;
-  visitedStateNames;
-  constructor(targetStateName, visitedStateNames) {
-    const visited = Array.from(visitedStateNames);
+  stateName;
+  hopLimit;
+  constructor(stateName, hopLimit) {
     super(
-      `Automatic transition cycle detected: state "${targetStateName}" was already visited \u2014 this would cause infinite recursion`
+      `Automatic transitions exceeded ${hopLimit} hops without reaching a quiescent state (last target: "${stateName}") \u2014 the graph is likely looping forever. Raise maxAutomaticHops if the loop is legitimate and bounded. Transitions committed before this error are NOT rolled back.`
     );
     this.name = "AutomaticTransitionCycleError";
-    this.targetStateName = targetStateName;
-    this.visitedStateNames = Object.freeze([...visited]);
+    this.stateName = stateName;
+    this.hopLimit = hopLimit;
+  }
+};
+
+// src/error/ReentrancyError.ts
+var ReentrancyError = class extends FinitaError {
+  code = "reentrancy";
+  constructor(operation) {
+    super(
+      `${operation} was called from inside an observer or condition of the same Statemachine. Awaiting it would deadlock: the machine runs one operation at a time and the runner is blocked on your callback. Where applicable, use the EnqueueContext passed to after-observers to chain events instead; from other callbacks, defer the call out of the synchronous path, e.g. queueMicrotask(() => sm.triggerEvent(...)).`
+    );
+    this.name = "ReentrancyError";
+  }
+};
+
+// src/error/QueueLimitExceededError.ts
+var QueueLimitExceededError = class extends FinitaError {
+  code = "queueLimitExceeded";
+  constructor(limit, eventName) {
+    super(
+      `${eventName === null ? "checkTransitions()" : `triggerEvent("${eventName}")`} rejected: the operation queue already holds ${limit} pending operation(s) (maxQueueLength = ${limit}).`
+    );
+    this.name = "QueueLimitExceededError";
   }
 };
 
@@ -784,17 +806,39 @@ var Statemachine = class {
   currentState;
   lastState = null;
   autoreleaseLock;
+  maxAutomaticHops;
+  maxQueueLength;
   queue = new OperationQueue();
   running = false;
+  idleWaiters = [];
+  inSyncCallback = false;
   beforeObservers = [];
   afterObservers = [];
+  onChainedOperationError;
+  onReleaseError;
   constructor(subject, process, options = {}) {
     this.subject = subject;
     this.process = process;
-    this.currentState = options.initialStateName ? process.getState(options.initialStateName) : process.getInitialState();
+    this.currentState = options.initialStateName !== void 0 ? process.getState(options.initialStateName) : process.getInitialState();
     this.transitionSelector = options.transitionSelector ?? new OneOrNoneActiveTransition();
     this.mutex = options.mutex ?? new NullMutex();
     this.autoreleaseLock = options.autoreleaseLock ?? true;
+    const hops = options.maxAutomaticHops ?? 100;
+    if (!Number.isInteger(hops) || hops < 1) {
+      throw new RangeError(
+        `maxAutomaticHops must be a positive integer; got ${String(options.maxAutomaticHops)}`
+      );
+    }
+    this.maxAutomaticHops = hops;
+    const maxQueue = options.maxQueueLength ?? Infinity;
+    if (maxQueue !== Infinity && (!Number.isInteger(maxQueue) || maxQueue < 1)) {
+      throw new RangeError(
+        `maxQueueLength must be a positive integer; got ${String(options.maxQueueLength)}`
+      );
+    }
+    this.maxQueueLength = maxQueue;
+    this.onChainedOperationError = options.onChainedOperationError;
+    this.onReleaseError = options.onReleaseError;
   }
   // --- public getters ---
   getCurrentState() {
@@ -811,6 +855,7 @@ var Statemachine = class {
   }
   // --- public observer attach/detach ---
   attachBefore(observer) {
+    if (this.beforeObservers.includes(observer)) return;
     this.beforeObservers.push(observer);
   }
   detachBefore(observer) {
@@ -821,6 +866,7 @@ var Statemachine = class {
     return this.beforeObservers;
   }
   attachAfter(observer) {
+    if (this.afterObservers.includes(observer)) return;
     this.afterObservers.push(observer);
   }
   detachAfter(observer) {
@@ -849,28 +895,64 @@ var Statemachine = class {
   // --- public top-level operations ---
   triggerEvent(name, context) {
     return new Promise((resolve, reject) => {
-      this.queue.enqueue({
-        kind: "triggerEvent",
-        eventName: name,
-        context: context ?? /* @__PURE__ */ new Map(),
-        resolve,
-        reject
-      });
-      void this.runIfIdle();
+      this.assertNotReentrant(`triggerEvent("${name}")`);
+      this.enqueueOperation(name, context, resolve, reject);
     });
   }
   checkTransitions(context) {
     return new Promise((resolve, reject) => {
-      this.queue.enqueue({
-        kind: "checkTransitions",
-        eventName: null,
-        context: context ?? /* @__PURE__ */ new Map(),
-        resolve,
-        reject
-      });
-      void this.runIfIdle();
+      this.assertNotReentrant("checkTransitions()");
+      this.enqueueOperation(null, context, resolve, reject);
+    });
+  }
+  /**
+   * Resolves once the operation queue is empty and the runner is idle —
+   * i.e. every operation enqueued so far, including operations chained via
+   * EnqueueContext.enqueue(), has completed. Resolves immediately if the
+   * machine is already idle. Note this is a quiescence point, not a
+   * receipt: work scheduled later (e.g. from a timer) starts a new drain.
+   */
+  whenIdle() {
+    if (!this.running && this.queue.isEmpty()) {
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      this.idleWaiters.push(resolve);
     });
   }
+  /** Runs fn with the re-entrancy flag set for its SYNCHRONOUS portion only:
+   *  the flag is cleared as soon as fn returns (before any promise it returned
+   *  is awaited), so concurrent external callers are never affected. This
+   *  catches triggerEvent/checkTransitions calls made before a callback's first
+   *  await; calls made after a prior await are not detectable without
+   *  AsyncLocalStorage (Node-only) and will still deadlock — a documented gap. */
+  guardSync(fn) {
+    this.inSyncCallback = true;
+    try {
+      return fn();
+    } finally {
+      this.inSyncCallback = false;
+    }
+  }
+  assertNotReentrant(operation) {
+    if (this.inSyncCallback) {
+      throw new ReentrancyError(operation);
+    }
+  }
+  /** Single entry point to the operation queue — every enqueue kicks the runner. */
+  enqueueOperation(eventName, context, resolve, reject, ifStateName) {
+    if (this.queue.size() >= this.maxQueueLength) {
+      throw new QueueLimitExceededError(this.maxQueueLength, eventName);
+    }
+    this.queue.enqueue({
+      eventName,
+      context: context ?? /* @__PURE__ */ new Map(),
+      ifStateName,
+      resolve,
+      reject
+    });
+    void this.runIfIdle();
+  }
   // --- internal runner ---
   async runIfIdle() {
     if (this.running) return;
@@ -882,10 +964,20 @@ var Statemachine = class {
       }
     } finally {
       this.running = false;
+      if (this.queue.isEmpty() && this.idleWaiters.length > 0) {
+        const waiters = this.idleWaiters;
+        this.idleWaiters = [];
+        for (const waiter of waiters) waiter();
+      }
     }
   }
   async runOperation(op) {
+    if (op.ifStateName !== void 0 && this.currentState.getName() !== op.ifStateName) {
+      op.resolve();
+      return;
+    }
     let acquiredHere = false;
+    let failure = null;
     try {
       if (!this.mutex.isAcquired()) {
         if (!await this.mutex.acquireLock()) {
@@ -893,19 +985,28 @@ var Statemachine = class {
         }
         acquiredHere = true;
       }
-      const event = op.kind === "triggerEvent" ? this.resolveEvent(op.eventName) : null;
+      const event = op.eventName !== null ? this.resolveEvent(op.eventName) : null;
       await this.processOperation(event, op.context);
-      op.resolve();
     } catch (err) {
-      op.reject(err);
+      failure = { err };
     } finally {
       if (acquiredHere && this.autoreleaseLock) {
         try {
           await this.mutex.releaseLock();
-        } catch {
+        } catch (err) {
+          try {
+            this.onReleaseError?.(err);
+          } catch {
+          }
+          if (!failure) failure = { err };
         }
       }
     }
+    if (failure) {
+      op.reject(failure.err);
+    } else {
+      op.resolve();
+    }
   }
   resolveEvent(name) {
     if (!this.currentState.hasEvent(name)) {
@@ -920,11 +1021,13 @@ var Statemachine = class {
    */
   async processOperation(initialEvent, context) {
     let event = initialEvent;
-    const automaticVisited = /* @__PURE__ */ new Set();
+    let automaticHops = 0;
     if (event) {
-      const dispatcher = new Dispatcher();
-      dispatcher.dispatch(event, [this.subject, context]);
-      await dispatcher.invoke();
+      const userEvent = event;
+      const invokeArgs = [this.subject, context];
+      for (const observer of [...userEvent.getObservers()]) {
+        await this.guardSync(() => observer.update(userEvent, invokeArgs));
+      }
     }
     while (true) {
       const transitions = this.currentState.getTransitions();
@@ -932,26 +1035,28 @@ var Statemachine = class {
         transitions,
         this.subject,
         context,
-        event ?? void 0
+        event ?? void 0,
+        (fn) => this.guardSync(fn)
       );
-      const selected = this.transitionSelector.selectTransition(
-        active
+      const selected = this.guardSync(
+        () => this.transitionSelector.selectTransition(active)
       );
       if (!selected) {
         return;
       }
       const target = selected.getTargetState();
       if (selected.getEventName() === null) {
-        automaticVisited.add(this.currentState);
-        if (automaticVisited.has(target)) {
+        automaticHops += 1;
+        if (automaticHops > this.maxAutomaticHops) {
           throw new AutomaticTransitionCycleError(
             target.getName(),
-            Array.from(automaticVisited).map((s) => s.getName())
+            this.maxAutomaticHops
           );
         }
       }
       if (this.currentState !== target) {
-        const proposedFrame = Object.freeze({
+        const frame = Object.freeze({
+          subject: this.subject,
           fromState: this.currentState,
           toState: target,
           transition: selected,
@@ -961,39 +1066,34 @@ var Statemachine = class {
           timestamp: Date.now(),
           machineName: this.process.getName()
         });
-        for (const observer of this.beforeObservers) {
-          await observer.notify(proposedFrame);
+        for (const observer of [...this.beforeObservers]) {
+          await this.guardSync(() => observer.notify(frame));
         }
-        const fromState = this.currentState;
-        this.lastState = fromState;
+        this.lastState = this.currentState;
         this.currentState = target;
-        const committedFrame = Object.freeze({
-          fromState,
-          toState: target,
-          transition: selected,
-          event,
-          condition: selected.getCondition(),
-          context: this.readonlyContext(context),
-          timestamp: proposedFrame.timestamp,
-          machineName: this.process.getName()
-        });
         const enqueueCtx = {
-          enqueue: (chainedEventName, chainedCtx) => {
-            this.queue.enqueue({
-              kind: "triggerEvent",
-              eventName: chainedEventName,
-              context: chainedCtx ?? /* @__PURE__ */ new Map(),
-              resolve: () => {
+          enqueue: (chainedEventName, chainedCtx, ifStateName) => {
+            this.enqueueOperation(
+              chainedEventName,
+              chainedCtx,
+              () => {
+              },
+              (err) => {
+                try {
+                  this.onChainedOperationError?.(err, {
+                    eventName: chainedEventName
+                  });
+                } catch {
+                }
               },
-              reject: () => {
-              }
-            });
+              ifStateName
+            );
           }
         };
         const errors = [];
-        for (const observer of this.afterObservers) {
+        for (const observer of [...this.afterObservers]) {
           try {
-            await observer.notify(committedFrame, enqueueCtx);
+            await this.guardSync(() => observer.notify(frame, enqueueCtx));
           } catch (err) {
             errors.push(err);
           }
@@ -1060,6 +1160,23 @@ var CallbackCondition = class {
   }
 };
 
+// src/error/InvalidSubjectError.ts
+var InvalidSubjectError = class extends FinitaError {
+  code = "invalidSubject";
+  expectedInterface;
+  missingMembers;
+  constructor(expectedInterface, missingMembers) {
+    const members = Array.from(missingMembers);
+    const memberList = members.map((m) => `"${m}"`).join(", ");
+    super(
+      `Subject does not satisfy ${expectedInterface}; missing member(s): ${memberList || "(unknown)"}`
+    );
+    this.name = "InvalidSubjectError";
+    this.expectedInterface = expectedInterface;
+    this.missingMembers = Object.freeze([...members]);
+  }
+};
+
 // src/condition/Timeout.ts
 function isLastStateHasChangedDate(obj) {
   return typeof obj === "object" && obj !== null && "getLastStateHasChangedDate" in obj && typeof obj.getLastStateHasChangedDate === "function";
@@ -1078,30 +1195,40 @@ var Timeout = class {
     if (isLastStateHasChangedDate(subject)) {
       return subject.getLastStateHasChangedDate();
     }
-    throw new Error("Subject must implement LastStateHasChangedDateInterface");
+    throw new InvalidSubjectError("LastStateHasChangedDateInterface", [
+      "getLastStateHasChangedDate"
+    ]);
   }
   checkCondition(subject, context) {
-    const date = new Date(
-      this.getLastStateHasChangedDate(subject, context).getTime()
-    );
-    date.setTime(date.getTime() + this.timeoutMs);
-    return date <= /* @__PURE__ */ new Date();
+    return this.getLastStateHasChangedDate(subject, context).getTime() + this.timeoutMs <= Date.now();
   }
 };
 
-// src/condition/AndComposite.ts
-var AndComposite = class {
+// src/condition/CompositeCondition.ts
+var CompositeCondition = class {
   conditions = [];
-  constructor(condition) {
+  joinWord;
+  constructor(joinWord, condition) {
+    this.joinWord = joinWord;
     this.conditions.push(condition);
   }
-  addAnd(condition) {
+  addCondition(condition) {
     this.conditions.push(condition);
     return this;
   }
   getName() {
     const names = this.conditions.map((c) => c.getName());
-    return `(${names.join(" and ")})`;
+    return `(${names.join(` ${this.joinWord} `)})`;
+  }
+};
+
+// src/condition/AndComposite.ts
+var AndComposite = class extends CompositeCondition {
+  constructor(condition) {
+    super("and", condition);
+  }
+  addAnd(condition) {
+    return this.addCondition(condition);
   }
   async checkCondition(subject, context) {
     for (const condition of this.conditions) {
@@ -1114,18 +1241,12 @@ var AndComposite = class {
 };
 
 // src/condition/OrComposite.ts
-var OrComposite = class {
-  conditions = [];
+var OrComposite = class extends CompositeCondition {
   constructor(condition) {
-    this.conditions.push(condition);
+    super("or", condition);
   }
   addOr(condition) {
-    this.conditions.push(condition);
-    return this;
-  }
-  getName() {
-    const names = this.conditions.map((c) => c.getName());
-    return `(${names.join(" or ")})`;
+    return this.addCondition(condition);
   }
   async checkCondition(subject, context) {
     for (const condition of this.conditions) {
@@ -1157,10 +1278,9 @@ var CallbackObserver = class {
   constructor(callback) {
     this.callback = callback;
   }
-  update(subject) {
-    const event = subject;
-    if (typeof event.getInvokeArgs === "function") {
-      return this.callback(...event.getInvokeArgs());
+  update(subject, args) {
+    if (args !== void 0) {
+      return this.callback(...args);
     }
     return this.callback(subject);
   }
@@ -1169,11 +1289,19 @@ var CallbackObserver = class {
 // src/observer/StatefulStatusChanger.ts
 var StatefulStatusChanger = class {
   subject;
+  /**
+   * @param subject Optional explicit subject to write to. When omitted
+   * (recommended), the observer writes to frame.subject — the subject of
+   * whichever machine fired the transition — so a single instance can be
+   * shared safely across every machine a Factory creates.
+   */
   constructor(subject) {
-    this.subject = subject;
+    this.subject = subject ?? null;
   }
   notify(frame) {
-    this.subject.setCurrentStateName(frame.toState.getName());
+    (this.subject ?? frame.subject).setCurrentStateName(
+      frame.toState.getName()
+    );
   }
 };
 
@@ -1186,19 +1314,25 @@ var OnEnterObserver = class _OnEnterObserver {
   }
   notify(frame, ctx) {
     if (frame.toState.hasEvent(this.eventName)) {
-      ctx.enqueue(this.eventName, new Map(frame.context));
+      ctx.enqueue(
+        this.eventName,
+        new Map(frame.context),
+        frame.toState.getName()
+      );
     }
   }
 };
 
-// src/observer/TransitionLogger.ts
+// src/util/index.ts
 function isNamed(obj) {
   return typeof obj === "object" && obj !== null && "getName" in obj && typeof obj.getName === "function";
 }
-function asString(obj) {
+function nameOrString(obj) {
   if (isNamed(obj)) return obj.getName();
   return String(obj);
 }
+
+// src/observer/TransitionLogger.ts
 var TransitionLogger = class {
   logger;
   loggerLevel;
@@ -1208,7 +1342,7 @@ var TransitionLogger = class {
   }
   notify(frame) {
     let message = "Transition";
-    message += ` from "${asString(frame.fromState)}" to "${asString(frame.toState)}"`;
+    message += ` from "${nameOrString(frame.fromState)}" to "${nameOrString(frame.toState)}"`;
     const eventName = frame.event ? frame.event.getName() : null;
     const conditionName = frame.condition ? frame.condition.getName() : null;
     if (eventName || conditionName) {
@@ -1315,23 +1449,30 @@ var WeightTransition = class {
   innerSelector;
   epsilon;
   constructor(innerSelector, epsilon = 1e-3) {
+    if (!Number.isFinite(epsilon) || epsilon <= 0) {
+      throw new RangeError(
+        `WeightTransition epsilon must be a finite number greater than 0; got ${String(epsilon)}`
+      );
+    }
     this.innerSelector = innerSelector ?? new OneOrNoneActiveTransition();
     this.epsilon = epsilon;
   }
   selectTransition(transitions) {
-    let bestTransitions = [];
-    let bestWeight = null;
-    for (const transition of transitions) {
+    const all = Array.from(transitions);
+    let maxWeight = Number.NEGATIVE_INFINITY;
+    for (const transition of all) {
       const weight = transition.getWeight();
-      const diff = weight - (bestWeight ?? 0);
-      if (bestWeight === null || diff >= this.epsilon) {
-        bestWeight = weight;
-        bestTransitions = [transition];
-      } else if (Math.abs(diff) < this.epsilon) {
-        bestTransitions.push(transition);
+      if (!Number.isFinite(weight)) {
+        throw new RangeError(
+          `WeightTransition: transition weights must be finite numbers; got ${String(weight)}`
+        );
       }
+      if (weight > maxWeight) maxWeight = weight;
     }
-    return this.innerSelector.selectTransition(bestTransitions);
+    const best = all.filter(
+      (transition) => maxWeight - transition.getWeight() < this.epsilon
+    );
+    return this.innerSelector.selectTransition(best);
   }
 };
 
@@ -1474,23 +1615,6 @@ var AbstractNamedProcessDetector = class {
   }
 };
 
-// src/error/InvalidSubjectError.ts
-var InvalidSubjectError = class extends FinitaError {
-  code = "invalidSubject";
-  expectedInterface;
-  missingMembers;
-  constructor(expectedInterface, missingMembers) {
-    const members = Array.from(missingMembers);
-    const memberList = members.map((m) => `"${m}"`).join(", ");
-    super(
-      `Subject does not satisfy ${expectedInterface}; missing member(s): ${memberList || "(unknown)"}`
-    );
-    this.name = "InvalidSubjectError";
-    this.expectedInterface = expectedInterface;
-    this.missingMembers = Object.freeze([...members]);
-  }
-};
-
 // src/factory/StatefulStateNameDetector.ts
 function isStateful(obj) {
   return typeof obj === "object" && obj !== null && "getCurrentStateName" in obj && typeof obj.getCurrentStateName === "function";
@@ -1505,11 +1629,8 @@ var StatefulStateNameDetector = class {
 };
 
 // src/graph/GraphBuilder.ts
-function isNamed2(obj) {
-  return typeof obj === "object" && obj !== null && "getName" in obj && typeof obj.getName === "function";
-}
-function escapeDoubleQuotes(str) {
-  return str.replace(/"/g, '\\"');
+function escapeDotString(str) {
+  return str.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
 }
 function toMermaidId(name) {
   return "s_" + name.replace(
@@ -1518,13 +1639,15 @@ function toMermaidId(name) {
   );
 }
 function escapeMermaidLabel(str) {
-  return str.replace(/"/g, "#quot;");
+  return str.replace(/\\/g, "#92;").replace(/"/g, "#quot;");
 }
-function convertToString(obj) {
-  if (isNamed2(obj)) {
-    return obj.getName();
+var VALID_DIRECTIONS = /* @__PURE__ */ new Set(["TB", "BT", "LR", "RL"]);
+function assertDirection(value, optionName) {
+  if (!VALID_DIRECTIONS.has(value)) {
+    throw new RangeError(
+      `${optionName} must be one of "TB", "BT", "LR", "RL"; got ${JSON.stringify(value)}`
+    );
   }
-  return String(obj);
 }
 var GraphBuilder = class {
   nodes = /* @__PURE__ */ new Map();
@@ -1544,13 +1667,15 @@ var GraphBuilder = class {
     const eventName = transition.getEventName();
     if (eventName) {
       parts.push(`E: ${eventName}`);
-      const event = state.getEvent(eventName);
-      const observerNames = [];
-      for (const observer of event.getObservers()) {
-        observerNames.push(convertToString(observer));
-      }
-      if (observerNames.length > 0) {
-        parts.push(`C: ${observerNames.join(", ")}`);
+      if (state.hasEvent(eventName)) {
+        const event = state.getEvent(eventName);
+        const observerNames = [];
+        for (const observer of event.getObservers()) {
+          observerNames.push(nameOrString(observer));
+        }
+        if (observerNames.length > 0) {
+          parts.push(`C: ${observerNames.join(", ")}`);
+        }
       }
     }
     const conditionName = transition.getConditionName();
@@ -1599,17 +1724,18 @@ var GraphBuilder = class {
   toDot(options) {
     const graph = this.getGraph();
     const rankdir = options?.rankdir ?? "LR";
+    assertDirection(rankdir, "rankdir");
     const lines = [];
     lines.push("digraph {");
     lines.push(`  rankdir=${rankdir};`);
     for (const node of graph.nodes) {
-      const label = escapeDoubleQuotes(node.label);
+      const label = escapeDotString(node.label);
       lines.push(`  "${label}" [label="${label}"];`);
     }
     for (const edge of graph.edges) {
-      const source = escapeDoubleQuotes(edge.source);
-      const target = escapeDoubleQuotes(edge.target);
-      const label = escapeDoubleQuotes(edge.label);
+      const source = escapeDotString(edge.source);
+      const target = escapeDotString(edge.target);
+      const label = escapeDotString(edge.label);
       lines.push(`  "${source}" -> "${target}" [label="${label}"];`);
     }
     lines.push("}");
@@ -1618,6 +1744,7 @@ var GraphBuilder = class {
   toMermaid(options) {
     const graph = this.getGraph();
     const direction = options?.direction ?? "LR";
+    assertDirection(direction, "direction");
     const lines = [];
     lines.push(`stateDiagram-v2`);
     lines.push(`  direction ${direction}`);
@@ -1673,6 +1800,8 @@ var GraphBuilder = class {
   ProcessBuilder,
   ProcessFinalizedError,
   ProcessNotFoundError,
+  QueueLimitExceededError,
+  ReentrancyError,
   ScoreTransition,
   SingleProcessDetector,
   State,