@camcima/finita 2.1.0 → 3.0.0

package/dist/index.cjs

@@ -22,19 +22,24 @@ var index_exports = {};
 __export(index_exports, {
   AbstractNamedProcessDetector: () => AbstractNamedProcessDetector,
   ActiveTransitionFilter: () => ActiveTransitionFilter,
+  AmbiguousTransitionError: () => AmbiguousTransitionError,
   AndComposite: () => AndComposite,
+  AutomaticTransitionCycleError: () => AutomaticTransitionCycleError,
   CallbackCondition: () => CallbackCondition,
   CallbackObserver: () => CallbackObserver,
   Contradiction: () => Contradiction,
-  Dispatcher: () => Dispatcher,
   DuplicateStateError: () => DuplicateStateError,
+  DuplicateTransitionError: () => DuplicateTransitionError,
   Event: () => Event,
   Factory: () => Factory,
   FilterStateByEvent: () => FilterStateByEvent,
   FilterStateByFinalState: () => FilterStateByFinalState,
   FilterStateByTransition: () => FilterStateByTransition,
   FilterTransitionByEvent: () => FilterTransitionByEvent,
+  FinitaError: () => FinitaError,
   GraphBuilder: () => GraphBuilder,
+  GraphValidationError: () => GraphValidationError,
+  InvalidSubjectError: () => InvalidSubjectError,
   LockAdapterMutex: () => LockAdapterMutex,
   LockCanNotBeAcquiredError: () => LockCanNotBeAcquiredError,
   MutexFactory: () => MutexFactory,
@@ -44,12 +49,14 @@ __export(index_exports, {
   OneOrNoneActiveTransition: () => OneOrNoneActiveTransition,
   OrComposite: () => OrComposite,
   Process: () => Process,
+  ProcessBuilder: () => ProcessBuilder,
+  ProcessFinalizedError: () => ProcessFinalizedError,
+  ProcessNotFoundError: () => ProcessNotFoundError,
   ScoreTransition: () => ScoreTransition,
-  SetupHelper: () => SetupHelper,
   SingleProcessDetector: () => SingleProcessDetector,
   State: () => State,
-  StateCollection: () => StateCollection,
-  StateCollectionMerger: () => StateCollectionMerger,
+  StateEventNotFoundError: () => StateEventNotFoundError,
+  StateNotFoundError: () => StateNotFoundError,
   StatefulStateNameDetector: () => StatefulStateNameDetector,
   StatefulStatusChanger: () => StatefulStatusChanger,
   Statemachine: () => Statemachine,
@@ -116,37 +123,148 @@ var Event = class {
   }
 };
 
-// src/State.ts
-var State = class {
+// src/internal/InternalConstruction.ts
+var INTERNAL_CONSTRUCTION_KEY = /* @__PURE__ */ Symbol(
+  "@camcima/finita/InternalConstruction"
+);
+
+// src/error/FinitaError.ts
+var FinitaError = class _FinitaError extends Error {
+  constructor(message) {
+    super(message);
+    if (new.target === _FinitaError) {
+      throw new TypeError(
+        "FinitaError is abstract and cannot be instantiated directly"
+      );
+    }
+  }
+};
+
+// src/error/StateNotFoundError.ts
+var StateNotFoundError = class extends FinitaError {
+  code = "stateNotFound";
+  stateName;
+  availableStates;
+  constructor(stateName, availableStates) {
+    const list = Array.from(availableStates);
+    const display = list.length > 0 ? list.map((n) => `"${n}"`).join(", ") : "(none)";
+    super(`State "${stateName}" not found. Available: ${display}`);
+    this.name = "StateNotFoundError";
+    this.stateName = stateName;
+    this.availableStates = Object.freeze([...list]);
+  }
+};
+
+// src/StateCollection.ts
+var StateCollection = class {
+  states;
+  constructor(states) {
+    const map = /* @__PURE__ */ new Map();
+    for (const s of states) {
+      map.set(s.getName(), s);
+    }
+    this.states = map;
+  }
+  getStates() {
+    return this.states.values();
+  }
+  getState(name) {
+    const s = this.states.get(name);
+    if (!s) {
+      throw new StateNotFoundError(name, this.states.keys());
+    }
+    return s;
+  }
+  hasState(name) {
+    return this.states.has(name);
+  }
+};
+
+// src/Process.ts
+var Process = class {
   name;
-  transitions = /* @__PURE__ */ new Set();
-  events = /* @__PURE__ */ new Map();
-  metadata = /* @__PURE__ */ new Map();
-  constructor(name) {
+  initialState;
+  states;
+  constructor(key, name, initialState, states) {
+    if (key !== INTERNAL_CONSTRUCTION_KEY) {
+      throw new Error("Process is not user-constructible; use ProcessBuilder.");
+    }
     this.name = name;
+    this.initialState = initialState;
+    this.states = new StateCollection(states);
+    Object.freeze(this);
   }
   getName() {
     return this.name;
   }
-  getTransitions() {
-    return this.transitions;
+  getInitialState() {
+    return this.initialState;
+  }
+  getStates() {
+    return this.states.getStates();
   }
-  addTransition(transition) {
-    if (this.transitions.has(transition)) {
-      return;
+  getState(name) {
+    return this.states.getState(name);
+  }
+  hasState(name) {
+    return this.states.hasState(name);
+  }
+};
+
+// src/error/StateEventNotFoundError.ts
+var StateEventNotFoundError = class extends FinitaError {
+  code = "stateEventNotFound";
+  stateName;
+  eventName;
+  constructor(stateName, eventName) {
+    super(`State "${stateName}" has no event "${eventName}"`);
+    this.name = "StateEventNotFoundError";
+    this.stateName = stateName;
+    this.eventName = eventName;
+  }
+};
+
+// src/State.ts
+var State = class {
+  name;
+  _transitions = null;
+  events;
+  metadata;
+  constructor(key, name, eventNames, metadata) {
+    if (key !== INTERNAL_CONSTRUCTION_KEY) {
+      throw new Error("State is not user-constructible; use ProcessBuilder.");
     }
-    const targetName = transition.getTargetState().getName();
-    const eventName = transition.getEventName();
-    const conditionName = transition.getConditionName();
-    for (const existing of this.transitions) {
-      if (existing.getTargetState().getName() === targetName && existing.getEventName() === eventName && existing.getConditionName() === conditionName) {
-        return;
-      }
+    this.name = name;
+    const events = /* @__PURE__ */ new Map();
+    for (const en of eventNames) {
+      events.set(en, new Event(en));
     }
-    this.transitions.add(transition);
-    if (eventName) {
-      this.getEvent(eventName);
+    this.events = events;
+    this.metadata = new Map(metadata);
+  }
+  /**
+   * Internal: populate transitions after State construction.
+   * May only be called once and only with the construction key.
+   * Used by ProcessBuilder to break the cycle: State must exist before
+   * Transitions can target it, but State needs its transitions to be useful.
+   */
+  _initTransitions(key, transitions) {
+    if (key !== INTERNAL_CONSTRUCTION_KEY) {
+      throw new Error("_initTransitions is internal");
+    }
+    if (this._transitions !== null) {
+      throw new Error(`State "${this.name}" transitions already set`);
+    }
+    this._transitions = new Set(transitions);
+  }
+  getName() {
+    return this.name;
+  }
+  getTransitions() {
+    if (this._transitions === null) {
+      return [];
     }
+    return this._transitions;
   }
   getEventNames() {
     return Array.from(this.events.keys());
@@ -155,10 +273,9 @@ var State = class {
     return this.events.has(name);
   }
   getEvent(name) {
-    let event = this.events.get(name);
+    const event = this.events.get(name);
     if (!event) {
-      event = new Event(name);
-      this.events.set(name, event);
+      throw new StateEventNotFoundError(this.name, name);
     }
     return event;
   }
@@ -168,15 +285,9 @@ var State = class {
   getMetadataValue(key) {
     return this.metadata.get(key);
   }
-  setMetadataValue(key, value) {
-    this.metadata.set(key, value);
-  }
   hasMetadataValue(key) {
     return this.metadata.has(key);
   }
-  deleteMetadataValue(key) {
-    this.metadata.delete(key);
-  }
 };
 
 // src/Transition.ts
@@ -184,11 +295,17 @@ var Transition = class {
   targetState;
   eventName;
   condition;
-  weight = 1;
-  constructor(targetState, eventName = null, condition = null) {
+  weight;
+  constructor(key, targetState, eventName, condition, weight) {
+    if (key !== INTERNAL_CONSTRUCTION_KEY) {
+      throw new Error(
+        "Transition is not user-constructible; use ProcessBuilder."
+      );
+    }
     this.targetState = targetState;
     this.eventName = eventName;
     this.condition = condition;
+    this.weight = weight;
   }
   getTargetState() {
     return this.targetState;
@@ -197,117 +314,31 @@ var Transition = class {
     return this.eventName;
   }
   getConditionName() {
-    if (this.condition) {
-      return this.condition.getName();
-    }
-    return null;
+    return this.condition ? this.condition.getName() : null;
   }
   getCondition() {
     return this.condition;
   }
   async isActive(subject, context, event) {
-    let result;
+    let active;
     if (event) {
-      result = event.getName() === this.eventName;
+      active = event.getName() === this.eventName;
     } else {
-      result = this.eventName === null;
+      active = this.eventName === null;
     }
-    if (this.condition && result) {
-      result = await this.condition.checkCondition(subject, context);
+    if (this.condition && active) {
+      active = await this.condition.checkCondition(subject, context);
     }
-    return result;
+    return active;
   }
   getWeight() {
     return this.weight;
   }
-  setWeight(weight) {
-    this.weight = weight;
-  }
-};
-
-// src/util/StateCollectionMerger.ts
-var StateCollectionMerger = class {
-  targetCollection;
-  stateNamePrefix = "";
-  constructor(targetCollection) {
-    this.targetCollection = targetCollection;
-  }
-  getStateNamePrefix() {
-    return this.stateNamePrefix;
-  }
-  setStateNamePrefix(prefix) {
-    this.stateNamePrefix = prefix;
-  }
-  getTargetCollection() {
-    return this.targetCollection;
-  }
-  createState(name) {
-    return new State(name);
-  }
-  findOrCreateState(name) {
-    const prefixedName = this.stateNamePrefix + name;
-    if (this.targetCollection.hasState(prefixedName)) {
-      return this.targetCollection.getState(prefixedName);
-    }
-    const state = this.createState(prefixedName);
-    this.targetCollection.addState(state);
-    return state;
-  }
-  createCondition(sourceTransition) {
-    return sourceTransition.getCondition();
-  }
-  createTransition(sourceTransition) {
-    const targetStateName = sourceTransition.getTargetState().getName();
-    const targetState = this.findOrCreateState(targetStateName);
-    this.mergeMetadata(sourceTransition.getTargetState(), targetState);
-    const eventName = sourceTransition.getEventName();
-    const condition = this.createCondition(sourceTransition);
-    const transition = new Transition(targetState, eventName, condition);
-    transition.setWeight(sourceTransition.getWeight());
-    return transition;
-  }
-  mergeMetadata(source, target) {
-    const metadata = source.getMetadata();
-    for (const [key, value] of Object.entries(metadata)) {
-      target.setMetadataValue(key, value);
-    }
-  }
-  mergeEvent(source, target, eventName) {
-    const sourceEvent = source.getEvent(eventName);
-    const targetEvent = target.getEvent(eventName);
-    const sourceMetadata = sourceEvent.getMetadata();
-    for (const [key, value] of Object.entries(sourceMetadata)) {
-      targetEvent.setMetadataValue(key, value);
-    }
-    for (const observer of sourceEvent.getObservers()) {
-      targetEvent.attach(observer);
-    }
-  }
-  mergeState(sourceState) {
-    const targetState = this.findOrCreateState(sourceState.getName());
-    this.mergeMetadata(sourceState, targetState);
-    for (const sourceTransition of sourceState.getTransitions()) {
-      const targetTransition = this.createTransition(sourceTransition);
-      targetState.addTransition(targetTransition);
-    }
-    for (const eventName of sourceState.getEventNames()) {
-      this.mergeEvent(sourceState, targetState, eventName);
-    }
-  }
-  merge(source) {
-    if ("getStates" in source && typeof source.getStates === "function") {
-      const collection = source;
-      for (const state of collection.getStates()) {
-        this.mergeState(state);
-      }
-    } else {
-      this.mergeState(source);
-    }
-  }
 };
 
 // src/error/DuplicateStateError.ts
-var DuplicateStateError = class extends Error {
+var DuplicateStateError = class extends FinitaError {
+  code = "duplicateState";
   stateName;
   constructor(stateName) {
     super(
@@ -318,81 +349,309 @@ var DuplicateStateError = class extends Error {
   }
 };
 
-// src/StateCollection.ts
-var StateCollection = class {
-  states = /* @__PURE__ */ new Map();
-  stateCollectionMerger = null;
-  getState(name) {
-    const state = this.states.get(name);
-    if (!state) {
-      throw new Error(`State "${name}" not found`);
-    }
-    return state;
-  }
-  getStates() {
-    return this.states.values();
-  }
-  hasState(name) {
-    return this.states.has(name);
-  }
-  addState(state) {
-    const existing = this.states.get(state.getName());
-    if (existing && existing !== state) {
-      throw new DuplicateStateError(state.getName());
-    }
-    this.states.set(state.getName(), state);
+// src/error/ProcessFinalizedError.ts
+var ProcessFinalizedError = class extends FinitaError {
+  code = "processFinalized";
+  processName;
+  constructor(processName) {
+    super(
+      `Process "${processName}" has already been built; ProcessBuilder.build() may only be called once`
+    );
+    this.name = "ProcessFinalizedError";
+    this.processName = processName;
   }
-  getStateCollectionMerger() {
-    if (!this.stateCollectionMerger) {
-      this.stateCollectionMerger = new StateCollectionMerger(this);
-    }
-    return this.stateCollectionMerger;
+};
+
+// src/error/GraphValidationError.ts
+var GraphValidationError = class extends FinitaError {
+  code;
+  details;
+  constructor(code, message, details = {}) {
+    super(`[${code}] ${message}`);
+    this.name = "GraphValidationError";
+    this.code = code;
+    this.details = Object.freeze({ ...details });
   }
-  merge(source) {
-    const merger = this.getStateCollectionMerger();
-    merger.merge(source);
+};
+
+// src/error/DuplicateTransitionError.ts
+var DuplicateTransitionError = class extends FinitaError {
+  code = "duplicateTransition";
+  conflict;
+  constructor(conflict) {
+    const eventLabel = conflict.eventName ?? "<automatic>";
+    const existing = conflict.existingConditionName ?? "<no condition>";
+    const incoming = conflict.newConditionName ?? "<no condition>";
+    super(
+      `Conflicting transition declarations from "${conflict.fromState}" to "${conflict.toState}" on event "${eventLabel}": existing condition "${existing}" vs new condition "${incoming}"`
+    );
+    this.name = "DuplicateTransitionError";
+    this.conflict = Object.freeze({ ...conflict });
   }
 };
 
-// src/Process.ts
-var Process = class {
-  name;
-  initialState;
-  states;
-  constructor(name, initialState) {
-    this.name = name;
-    this.initialState = initialState;
-    this.states = new StateCollection();
-    this.registerState(initialState);
+// src/ProcessBuilder.ts
+var ProcessBuilder = class {
+  processName;
+  stateSpecs = /* @__PURE__ */ new Map();
+  transitionSpecs = [];
+  built = false;
+  constructor(processName) {
+    this.processName = processName;
+  }
+  addState(name, options = {}) {
+    if (this.built) {
+      throw new ProcessFinalizedError(this.processName);
+    }
+    if (this.stateSpecs.has(name)) {
+      throw new DuplicateStateError(name);
+    }
+    this.stateSpecs.set(name, {
+      name,
+      initial: options.initial === true,
+      metadata: new Map(Object.entries(options.metadata ?? {}))
+    });
+    return this;
   }
-  registerState(state) {
-    const name = state.getName();
-    if (this.states.hasState(name)) {
-      if (this.states.getState(name) !== state) {
-        throw new DuplicateStateError(name);
+  addTransition(fromState, toState, options = {}) {
+    if (this.built) {
+      throw new ProcessFinalizedError(this.processName);
+    }
+    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;
+    }
+    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 }
+        );
       }
-      return;
     }
-    this.states.addState(state);
-    for (const transition of state.getTransitions()) {
-      const targetState = transition.getTargetState();
-      this.registerState(targetState);
+    this.transitionSpecs.push({
+      fromState,
+      toState,
+      eventName,
+      condition: options.condition ?? null,
+      weight: options.weight ?? 1
+    });
+    return this;
+  }
+  build(options = {}) {
+    if (this.built) {
+      throw new ProcessFinalizedError(this.processName);
+    }
+    this.built = true;
+    this.validateInitialState();
+    this.validateTransitionEndpoints();
+    this.validateNoConflictingDuplicates();
+    const initialName = this.findInitialStateName();
+    const eventNamesByState = this.collectEventNamesByState();
+    const finalStates = this.buildAllStates(eventNamesByState);
+    if (options.strictOrphans) {
+      this.validateOrphans(finalStates, initialName);
+    }
+    const initialState = finalStates.get(initialName);
+    return new Process(
+      INTERNAL_CONSTRUCTION_KEY,
+      this.processName,
+      initialState,
+      finalStates.values()
+    );
+  }
+  // --- private helpers ---
+  validateInitialState() {
+    const initials = Array.from(this.stateSpecs.values()).filter(
+      (s) => s.initial
+    );
+    if (initials.length === 0) {
+      throw new GraphValidationError(
+        "missingInitialState",
+        `Process "${this.processName}" has no state declared with { initial: true }`,
+        { processName: this.processName }
+      );
+    }
+    if (initials.length > 1) {
+      throw new GraphValidationError(
+        "multipleInitialStates",
+        `Process "${this.processName}" declares multiple initial states: ${initials.map((s) => `"${s.name}"`).join(", ")}`,
+        {
+          processName: this.processName,
+          initialStates: initials.map((s) => s.name)
+        }
+      );
     }
   }
-  getName() {
-    return this.name;
+  findInitialStateName() {
+    return Array.from(this.stateSpecs.values()).find((s) => s.initial).name;
   }
-  getInitialState() {
-    return this.initialState;
+  validateTransitionEndpoints() {
+    for (const t of this.transitionSpecs) {
+      if (!this.stateSpecs.has(t.fromState)) {
+        throw new GraphValidationError(
+          "unknownSource",
+          `Transition source state "${t.fromState}" was not declared with addState`,
+          {
+            fromState: t.fromState,
+            toState: t.toState,
+            eventName: t.eventName
+          }
+        );
+      }
+      if (!this.stateSpecs.has(t.toState)) {
+        throw new GraphValidationError(
+          "unknownTarget",
+          `Transition target state "${t.toState}" was not declared with addState`,
+          {
+            fromState: t.fromState,
+            toState: t.toState,
+            eventName: t.eventName
+          }
+        );
+      }
+    }
   }
-  getStates() {
-    return this.states.getStates();
+  validateNoConflictingDuplicates() {
+    const seen = /* @__PURE__ */ new Map();
+    for (const t of this.transitionSpecs) {
+      const key = `${t.fromState}\0${t.eventName ?? ""}\0${t.toState}`;
+      const existing = seen.get(key);
+      if (!existing) {
+        seen.set(key, t);
+        continue;
+      }
+      if (existing.condition !== t.condition) {
+        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
+        });
+      }
+    }
   }
-  getState(name) {
-    return this.states.getState(name);
+  collectEventNamesByState() {
+    const out = /* @__PURE__ */ new Map();
+    for (const t of this.transitionSpecs) {
+      if (t.eventName === null) continue;
+      let bucket = out.get(t.fromState);
+      if (!bucket) {
+        bucket = /* @__PURE__ */ new Set();
+        out.set(t.fromState, bucket);
+      }
+      bucket.add(t.eventName);
+    }
+    return new Map(
+      Array.from(out.entries()).map(([k, v]) => [k, Array.from(v)])
+    );
   }
-  hasState(name) {
-    return this.states.hasState(name);
+  /**
+   * Two-phase construction:
+   * Phase 1 — create all final State instances with no transitions.
+   * Phase 2 — build Transitions targeting the Phase-1 States, then attach
+   *            them via State._initTransitions.
+   *
+   * Because every Transition is created after every State exists, target
+   * identity holds by construction for any graph topology (acyclic, cyclic,
+   * self-loop).
+   */
+  buildAllStates(eventNamesByState) {
+    const built = /* @__PURE__ */ new Map();
+    for (const spec of this.stateSpecs.values()) {
+      built.set(
+        spec.name,
+        new State(
+          INTERNAL_CONSTRUCTION_KEY,
+          spec.name,
+          eventNamesByState.get(spec.name) ?? [],
+          spec.metadata
+        )
+      );
+    }
+    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)}`;
+      if (dedupSeen.has(dedupKey)) continue;
+      dedupSeen.add(dedupKey);
+      const targetState = built.get(tSpec.toState);
+      const transition = new Transition(
+        INTERNAL_CONSTRUCTION_KEY,
+        targetState,
+        tSpec.eventName,
+        tSpec.condition,
+        tSpec.weight
+      );
+      transitionsByState.get(tSpec.fromState).push(transition);
+    }
+    for (const [name, transitions] of transitionsByState) {
+      built.get(name)._initTransitions(
+        INTERNAL_CONSTRUCTION_KEY,
+        transitions
+      );
+    }
+    return built;
+  }
+  validateOrphans(states, initialName) {
+    const reachable = /* @__PURE__ */ new Set();
+    const queue = [initialName];
+    while (queue.length > 0) {
+      const name = queue.shift();
+      if (reachable.has(name)) continue;
+      reachable.add(name);
+      const s = states.get(name);
+      for (const t of s.getTransitions()) {
+        queue.push(t.getTargetState().getName());
+      }
+    }
+    const orphans = [];
+    for (const name of states.keys()) {
+      if (!reachable.has(name)) orphans.push(name);
+    }
+    if (orphans.length > 0) {
+      throw new GraphValidationError(
+        "orphanState",
+        `Process "${this.processName}" has unreachable states: ${orphans.map((n) => `"${n}"`).join(", ")}`,
+        { processName: this.processName, orphanStates: orphans }
+      );
+    }
+  }
+};
+
+// src/error/AmbiguousTransitionError.ts
+var AmbiguousTransitionError = class extends FinitaError {
+  code = "ambiguousTransition";
+  activeCount;
+  constructor(activeCount) {
+    super(`More than one transition is active! (active count: ${activeCount})`);
+    this.name = "AmbiguousTransitionError";
+    this.activeCount = activeCount;
   }
 };
 
@@ -406,7 +665,7 @@ var OneOrNoneActiveTransition = class {
       case 1:
         return arr[0];
       default:
-        throw new Error("More than one transition is active!");
+        throw new AmbiguousTransitionError(arr.length);
     }
   }
 };
@@ -430,19 +689,15 @@ var NullMutex = class {
   }
 };
 
-// src/Dispatcher.ts
+// src/internal/Dispatcher.ts
 var Dispatcher = class {
   commands = [];
-  onReadyCallbacks = [];
   ready = false;
-  dispatch(event, args = [], onReadyCallback) {
+  dispatch(event, args = []) {
     if (this.ready) {
       throw new Error("Was already invoked!");
     }
     this.commands.push({ event, args });
-    if (onReadyCallback) {
-      this.onReadyCallbacks.push(onReadyCallback);
-    }
   }
   async invoke() {
     if (this.ready) {
@@ -452,12 +707,20 @@ var Dispatcher = class {
       await event.invoke(...args);
     }
     this.ready = true;
-    for (const callback of this.onReadyCallbacks) {
-      await callback.invoke();
-    }
   }
-  isReady() {
-    return this.ready;
+};
+
+// src/internal/OperationQueue.ts
+var OperationQueue = class {
+  items = [];
+  enqueue(op) {
+    this.items.push(op);
+  }
+  dequeue() {
+    return this.items.shift();
+  }
+  isEmpty() {
+    return this.items.length === 0;
   }
 };
 
@@ -475,7 +738,8 @@ var ActiveTransitionFilter = class {
 };
 
 // src/error/WrongEventForStateError.ts
-var WrongEventForStateError = class extends Error {
+var WrongEventForStateError = class extends FinitaError {
+  code = "wrongEventForState";
   stateName;
   eventName;
   constructor(stateName, eventName) {
@@ -487,41 +751,52 @@ var WrongEventForStateError = class extends Error {
 };
 
 // src/error/LockCanNotBeAcquiredError.ts
-var LockCanNotBeAcquiredError = class extends Error {
+var LockCanNotBeAcquiredError = class extends FinitaError {
+  code = "lockCanNotBeAcquired";
   constructor(message = "Lock can not be acquired!") {
     super(message);
     this.name = "LockCanNotBeAcquiredError";
   }
 };
 
+// src/error/AutomaticTransitionCycleError.ts
+var AutomaticTransitionCycleError = class extends FinitaError {
+  code = "automaticTransitionCycle";
+  targetStateName;
+  visitedStateNames;
+  constructor(targetStateName, visitedStateNames) {
+    const visited = Array.from(visitedStateNames);
+    super(
+      `Automatic transition cycle detected: state "${targetStateName}" was already visited \u2014 this would cause infinite recursion`
+    );
+    this.name = "AutomaticTransitionCycleError";
+    this.targetStateName = targetStateName;
+    this.visitedStateNames = Object.freeze([...visited]);
+  }
+};
+
 // src/Statemachine.ts
 var Statemachine = class {
   subject;
-  currentState;
-  lastState = null;
-  transitionSelector;
-  selectedTransition = null;
   process;
+  transitionSelector;
   mutex;
-  autoreleaseLock = true;
-  dispatcher = null;
-  currentEvent = null;
-  currentContext = null;
-  observers = /* @__PURE__ */ new Set();
-  constructor(subject, process, stateName, transitionSelector, mutex) {
+  currentState;
+  lastState = null;
+  autoreleaseLock;
+  queue = new OperationQueue();
+  running = false;
+  beforeObservers = [];
+  afterObservers = [];
+  constructor(subject, process, options = {}) {
     this.subject = subject;
-    if (stateName) {
-      this.currentState = process.getState(stateName);
-    } else {
-      this.currentState = process.getInitialState();
-    }
-    this.transitionSelector = transitionSelector ?? new OneOrNoneActiveTransition();
     this.process = process;
-    this.mutex = mutex ?? new NullMutex();
-  }
-  getProcess() {
-    return this.process;
+    this.currentState = options.initialStateName ? process.getState(options.initialStateName) : process.getInitialState();
+    this.transitionSelector = options.transitionSelector ?? new OneOrNoneActiveTransition();
+    this.mutex = options.mutex ?? new NullMutex();
+    this.autoreleaseLock = options.autoreleaseLock ?? true;
   }
+  // --- public getters ---
   getCurrentState() {
     return this.currentState;
   }
@@ -531,147 +806,32 @@ var Statemachine = class {
   getSubject() {
     return this.subject;
   }
-  getSelectedTransition() {
-    return this.selectedTransition;
-  }
-  getCurrentContext() {
-    return this.currentContext;
-  }
-  async doCheckTransitions(context, event, automaticVisited) {
-    try {
-      const transitions = this.currentState.getTransitions();
-      const activeTransitions = await ActiveTransitionFilter.filter(
-        transitions,
-        this.subject,
-        context,
-        event
-      );
-      this.selectedTransition = this.transitionSelector.selectTransition(activeTransitions);
-      if (this.selectedTransition) {
-        const targetState = this.selectedTransition.getTargetState();
-        if (this.selectedTransition.getEventName() === null) {
-          if (!automaticVisited) {
-            automaticVisited = /* @__PURE__ */ new Set();
-          }
-          automaticVisited.add(this.currentState);
-          if (automaticVisited.has(targetState)) {
-            throw new Error(
-              `Automatic transition cycle detected: state "${targetState.getName()}" was already visited \u2014 this would cause infinite recursion`
-            );
-          }
-        }
-        if (this.currentState !== targetState) {
-          this.lastState = this.currentState;
-          this.currentState = targetState;
-          this.currentContext = context;
-          this.currentEvent = event ?? null;
-          try {
-            await this.notify();
-          } finally {
-            this.currentContext = null;
-            this.currentEvent = null;
-            this.selectedTransition = null;
-            this.lastState = null;
-          }
-        }
-        await this.doCheckTransitions(context, void 0, automaticVisited);
-      }
-    } catch (error) {
-      let message = `Exception was thrown when doing a transition from current state "${this.currentState.getName()}"`;
-      if (this.currentEvent) {
-        message += ` with event "${this.currentEvent.getName()}"`;
-      }
-      const named = this.subject;
-      if (named && typeof named.getName === "function") {
-        message += ` for "${named.getName()}"`;
-      }
-      throw new Error(message, { cause: error });
-    }
-  }
-  async onDispatcherReady() {
-    if (this.dispatcher && this.dispatcher.isReady()) {
-      const context = this.currentContext;
-      const event = this.currentEvent ?? void 0;
-      this.dispatcher = null;
-      this.currentContext = null;
-      this.currentEvent = null;
-      try {
-        await this.doCheckTransitions(context, event);
-      } finally {
-        if (this.autoreleaseLock && this.isLockAcquired()) {
-          await this.releaseLock();
-        }
-      }
-    }
+  getProcess() {
+    return this.process;
   }
-  async dispatchEvent(dispatcher, name, context) {
-    if (this.dispatcher) {
-      throw new Error("Event dispatching is still running!");
-    }
-    if (this.currentState.hasEvent(name)) {
-      await this.acquireLockOrThrowException();
-      try {
-        this.dispatcher = dispatcher;
-        this.currentContext = context ?? /* @__PURE__ */ new Map();
-        this.currentEvent = this.currentState.getEvent(name);
-        dispatcher.dispatch(
-          this.currentEvent,
-          [this.subject, this.currentContext],
-          { invoke: () => this.onDispatcherReady() }
-        );
-      } catch (error) {
-        this.dispatcher = null;
-        this.currentContext = null;
-        this.currentEvent = null;
-        if (this.autoreleaseLock) {
-          await this.releaseLock();
-        }
-        throw error;
-      }
-    } else {
-      throw new WrongEventForStateError(this.currentState.getName(), name);
-    }
+  // --- public observer attach/detach ---
+  attachBefore(observer) {
+    this.beforeObservers.push(observer);
   }
-  async triggerEvent(name, context) {
-    const dispatcher = new Dispatcher();
-    try {
-      await this.dispatchEvent(dispatcher, name, context);
-      await dispatcher.invoke();
-    } finally {
-      this.dispatcher = null;
-      this.currentContext = null;
-      this.currentEvent = null;
-      if (this.autoreleaseLock && this.isLockAcquired()) {
-        await this.releaseLock();
-      }
-    }
+  detachBefore(observer) {
+    const idx = this.beforeObservers.indexOf(observer);
+    if (idx >= 0) this.beforeObservers.splice(idx, 1);
   }
-  async checkTransitions(context) {
-    await this.acquireLockOrThrowException();
-    const ctx = context ?? /* @__PURE__ */ new Map();
-    try {
-      await this.doCheckTransitions(ctx);
-    } finally {
-      if (this.autoreleaseLock && this.isLockAcquired()) {
-        await this.releaseLock();
-      }
-    }
+  getBeforeObservers() {
+    return this.beforeObservers;
   }
-  async acquireLockOrThrowException() {
-    if (!await this.acquireLock()) {
-      throw new LockCanNotBeAcquiredError("Lock can not be acquired!");
-    }
+  attachAfter(observer) {
+    this.afterObservers.push(observer);
   }
-  isAutoreleaseLock() {
-    return this.autoreleaseLock;
+  detachAfter(observer) {
+    const idx = this.afterObservers.indexOf(observer);
+    if (idx >= 0) this.afterObservers.splice(idx, 1);
   }
-  setAutoreleaseLock(autorelease) {
-    this.autoreleaseLock = autorelease;
+  getAfterObservers() {
+    return this.afterObservers;
   }
+  // --- public locking ---
   async acquireLock() {
-    if (this.mutex.isAcquired()) {
-      return true;
-    }
     return this.mutex.acquireLock();
   }
   async releaseLock() {
@@ -680,19 +840,179 @@ var Statemachine = class {
   isLockAcquired() {
     return this.mutex.isAcquired();
   }
-  attach(observer) {
-    this.observers.add(observer);
+  isAutoreleaseLock() {
+    return this.autoreleaseLock;
   }
-  detach(observer) {
-    this.observers.delete(observer);
+  setAutoreleaseLock(autorelease) {
+    this.autoreleaseLock = autorelease;
   }
-  async notify() {
-    for (const observer of this.observers) {
-      await observer.update(this);
+  // --- 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();
+    });
+  }
+  checkTransitions(context) {
+    return new Promise((resolve, reject) => {
+      this.queue.enqueue({
+        kind: "checkTransitions",
+        eventName: null,
+        context: context ?? /* @__PURE__ */ new Map(),
+        resolve,
+        reject
+      });
+      void this.runIfIdle();
+    });
+  }
+  // --- internal runner ---
+  async runIfIdle() {
+    if (this.running) return;
+    this.running = true;
+    try {
+      while (!this.queue.isEmpty()) {
+        const op = this.queue.dequeue();
+        await this.runOperation(op);
+      }
+    } finally {
+      this.running = false;
     }
   }
-  getObservers() {
-    return this.observers;
+  async runOperation(op) {
+    let acquiredHere = false;
+    try {
+      if (!this.mutex.isAcquired()) {
+        if (!await this.mutex.acquireLock()) {
+          throw new LockCanNotBeAcquiredError("Lock can not be acquired!");
+        }
+        acquiredHere = true;
+      }
+      const event = op.kind === "triggerEvent" ? this.resolveEvent(op.eventName) : null;
+      await this.processOperation(event, op.context);
+      op.resolve();
+    } catch (err) {
+      op.reject(err);
+    } finally {
+      if (acquiredHere && this.autoreleaseLock) {
+        try {
+          await this.mutex.releaseLock();
+        } catch {
+        }
+      }
+    }
+  }
+  resolveEvent(name) {
+    if (!this.currentState.hasEvent(name)) {
+      throw new WrongEventForStateError(this.currentState.getName(), name);
+    }
+    return this.currentState.getEvent(name);
+  }
+  /**
+   * Drive transitions starting from the current state, following automatic
+   * transitions until quiescent. The first iteration may use the supplied
+   * event; subsequent iterations are automatic.
+   */
+  async processOperation(initialEvent, context) {
+    let event = initialEvent;
+    const automaticVisited = /* @__PURE__ */ new Set();
+    if (event) {
+      const dispatcher = new Dispatcher();
+      dispatcher.dispatch(event, [this.subject, context]);
+      await dispatcher.invoke();
+    }
+    while (true) {
+      const transitions = this.currentState.getTransitions();
+      const active = await ActiveTransitionFilter.filter(
+        transitions,
+        this.subject,
+        context,
+        event ?? void 0
+      );
+      const selected = this.transitionSelector.selectTransition(
+        active
+      );
+      if (!selected) {
+        return;
+      }
+      const target = selected.getTargetState();
+      if (selected.getEventName() === null) {
+        automaticVisited.add(this.currentState);
+        if (automaticVisited.has(target)) {
+          throw new AutomaticTransitionCycleError(
+            target.getName(),
+            Array.from(automaticVisited).map((s) => s.getName())
+          );
+        }
+      }
+      if (this.currentState !== target) {
+        const proposedFrame = Object.freeze({
+          fromState: this.currentState,
+          toState: target,
+          transition: selected,
+          event,
+          condition: selected.getCondition(),
+          context: this.readonlyContext(context),
+          timestamp: Date.now(),
+          machineName: this.process.getName()
+        });
+        for (const observer of this.beforeObservers) {
+          await observer.notify(proposedFrame);
+        }
+        const fromState = this.currentState;
+        this.lastState = fromState;
+        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: () => {
+              },
+              reject: () => {
+              }
+            });
+          }
+        };
+        const errors = [];
+        for (const observer of this.afterObservers) {
+          try {
+            await observer.notify(committedFrame, enqueueCtx);
+          } catch (err) {
+            errors.push(err);
+          }
+        }
+        if (errors.length === 1) {
+          throw errors[0];
+        }
+        if (errors.length > 1) {
+          throw new AggregateError(
+            errors,
+            `${errors.length} after-transition observer(s) threw`
+          );
+        }
+      }
+      event = null;
+    }
+  }
+  readonlyContext(ctx) {
+    return new Map(ctx);
   }
 };
 
@@ -847,62 +1167,36 @@ var CallbackObserver = class {
 };
 
 // src/observer/StatefulStatusChanger.ts
-function isStatemachine(obj) {
-  return typeof obj === "object" && obj !== null && "getCurrentState" in obj && "getSubject" in obj;
-}
-function isStateful(obj) {
-  return typeof obj === "object" && obj !== null && "setCurrentStateName" in obj && typeof obj.setCurrentStateName === "function";
-}
 var StatefulStatusChanger = class {
-  update(subject) {
-    if (isStatemachine(subject)) {
-      const subjectObj = subject.getSubject();
-      if (isStateful(subjectObj)) {
-        const stateName = subject.getCurrentState().getName();
-        subjectObj.setCurrentStateName(stateName);
-      }
-    }
+  subject;
+  constructor(subject) {
+    this.subject = subject;
+  }
+  notify(frame) {
+    this.subject.setCurrentStateName(frame.toState.getName());
   }
 };
 
 // src/observer/OnEnterObserver.ts
-function isStatemachine2(obj) {
-  return typeof obj === "object" && obj !== null && "getCurrentState" in obj && "triggerEvent" in obj;
-}
 var OnEnterObserver = class _OnEnterObserver {
   static DEFAULT_EVENT_NAME = "onEnter";
   eventName;
   constructor(eventName = _OnEnterObserver.DEFAULT_EVENT_NAME) {
     this.eventName = eventName;
   }
-  async update(subject) {
-    if (isStatemachine2(subject) && subject.getCurrentState().hasEvent(this.eventName)) {
-      const sm = subject;
-      const autorelease = sm.isAutoreleaseLock();
-      sm.setAutoreleaseLock(false);
-      try {
-        await sm.triggerEvent(
-          this.eventName,
-          sm.getCurrentContext() ?? void 0
-        );
-      } finally {
-        sm.setAutoreleaseLock(autorelease);
-      }
+  notify(frame, ctx) {
+    if (frame.toState.hasEvent(this.eventName)) {
+      ctx.enqueue(this.eventName, new Map(frame.context));
     }
   }
 };
 
 // src/observer/TransitionLogger.ts
-function isStatemachine3(obj) {
-  return typeof obj === "object" && obj !== null && "getCurrentState" in obj && "getSubject" in obj;
-}
 function isNamed(obj) {
   return typeof obj === "object" && obj !== null && "getName" in obj && typeof obj.getName === "function";
 }
-function convertToString(obj) {
-  if (isNamed(obj)) {
-    return obj.getName();
-  }
+function asString(obj) {
+  if (isNamed(obj)) return obj.getName();
   return String(obj);
 }
 var TransitionLogger = class {
@@ -912,40 +1206,23 @@ var TransitionLogger = class {
     this.logger = logger;
     this.loggerLevel = loggerLevel;
   }
-  update(subject) {
-    if (!isStatemachine3(subject)) {
-      return;
-    }
-    const context = {};
-    context["subject"] = subject.getSubject();
-    context["currentState"] = subject.getCurrentState();
-    context["lastState"] = subject.getLastState();
-    context["transition"] = subject.getSelectedTransition();
+  notify(frame) {
     let message = "Transition";
-    if (context["subject"] != null) {
-      message += ` for "${convertToString(context["subject"])}"`;
-    }
-    if (context["lastState"] != null) {
-      message += ` from "${convertToString(context["lastState"])}"`;
-    }
-    if (context["currentState"] != null) {
-      message += ` to "${convertToString(context["currentState"])}"`;
-    }
-    const transition = context["transition"];
-    if (transition && typeof transition.getEventName === "function") {
-      const eventName = transition.getEventName();
-      const condition = transition.getConditionName?.();
-      if (eventName || condition) {
-        message += " with";
-        if (eventName) {
-          message += ` event "${eventName}"`;
-        }
-        if (condition) {
-          message += ` condition "${condition}"`;
-        }
-      }
-    }
-    this.logger.log(this.loggerLevel, message, context);
+    message += ` from "${asString(frame.fromState)}" to "${asString(frame.toState)}"`;
+    const eventName = frame.event ? frame.event.getName() : null;
+    const conditionName = frame.condition ? frame.condition.getName() : null;
+    if (eventName || conditionName) {
+      message += " with";
+      if (eventName) message += ` event "${eventName}"`;
+      if (conditionName) message += ` condition "${conditionName}"`;
+    }
+    this.logger.log(this.loggerLevel, message, {
+      fromState: frame.fromState,
+      toState: frame.toState,
+      event: frame.event,
+      transition: frame.transition,
+      machineName: frame.machineName
+    });
   }
 };
 
@@ -1111,7 +1388,8 @@ var MutexFactory = class {
 var Factory = class {
   processDetector;
   stateNameDetector;
-  statemachineObservers = /* @__PURE__ */ new Set();
+  beforeObservers = /* @__PURE__ */ new Set();
+  afterObservers = /* @__PURE__ */ new Set();
   transitionSelector = null;
   mutexFactory = null;
   constructor(processDetector, stateNameDetector) {
@@ -1124,30 +1402,30 @@ var Factory = class {
   setTransitionSelector(selector) {
     this.transitionSelector = selector;
   }
-  attachStatemachineObserver(observer) {
-    this.statemachineObservers.add(observer);
+  attachBeforeObserver(observer) {
+    this.beforeObservers.add(observer);
   }
-  detachStatemachineObserver(observer) {
-    this.statemachineObservers.delete(observer);
+  detachBeforeObserver(observer) {
+    this.beforeObservers.delete(observer);
   }
-  getStatemachineObservers() {
-    return this.statemachineObservers;
+  attachAfterObserver(observer) {
+    this.afterObservers.add(observer);
+  }
+  detachAfterObserver(observer) {
+    this.afterObservers.delete(observer);
   }
   async createStatemachine(subject) {
     const process = this.processDetector.detectProcess(subject);
-    const stateName = this.stateNameDetector ? this.stateNameDetector.detectCurrentStateName(subject) : null;
-    const mutex = this.mutexFactory ? await this.mutexFactory.createMutex(subject) : null;
-    const statemachine = new Statemachine(
-      subject,
-      process,
-      stateName,
-      this.transitionSelector,
-      mutex
-    );
-    for (const observer of this.statemachineObservers) {
-      statemachine.attach(observer);
-    }
-    return statemachine;
+    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, {
+      initialStateName: stateName ?? void 0,
+      transitionSelector: this.transitionSelector ?? void 0,
+      mutex: mutex ?? void 0
+    });
+    for (const o of this.beforeObservers) sm.attachBefore(o);
+    for (const o of this.afterObservers) sm.attachAfter(o);
+    return sm;
   }
 };
 
@@ -1162,6 +1440,21 @@ var SingleProcessDetector = class {
   }
 };
 
+// src/error/ProcessNotFoundError.ts
+var ProcessNotFoundError = class extends FinitaError {
+  code = "processNotFound";
+  processName;
+  availableProcesses;
+  constructor(processName, availableProcesses) {
+    const list = Array.from(availableProcesses);
+    const display = list.length > 0 ? list.map((n) => `"${n}"`).join(", ") : "(none)";
+    super(`Process "${processName}" not found. Available: ${display}`);
+    this.name = "ProcessNotFoundError";
+    this.processName = processName;
+    this.availableProcesses = Object.freeze([...list]);
+  }
+};
+
 // src/factory/AbstractNamedProcessDetector.ts
 var AbstractNamedProcessDetector = class {
   processes = /* @__PURE__ */ new Map();
@@ -1175,74 +1468,39 @@ var AbstractNamedProcessDetector = class {
     const name = this.detectProcessName(subject);
     const process = this.processes.get(name);
     if (!process) {
-      throw new Error(`Process "${name}" not found`);
+      throw new ProcessNotFoundError(name, this.processes.keys());
     }
     return process;
   }
 };
 
+// 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 isStateful2(obj) {
+function isStateful(obj) {
   return typeof obj === "object" && obj !== null && "getCurrentStateName" in obj && typeof obj.getCurrentStateName === "function";
 }
 var StatefulStateNameDetector = class {
   detectCurrentStateName(subject) {
-    if (isStateful2(subject)) {
+    if (isStateful(subject)) {
       return subject.getCurrentStateName();
     }
-    throw new Error("Subject has to implement the StatefulInterface!");
-  }
-};
-
-// src/util/SetupHelper.ts
-var SetupHelper = class {
-  stateCollection;
-  constructor(stateCollection) {
-    this.stateCollection = stateCollection;
-  }
-  findOrCreateState(name) {
-    if (!this.stateCollection.hasState(name)) {
-      this.stateCollection.addState(new State(name));
-    }
-    return this.stateCollection.getState(name);
-  }
-  findTransition(sourceState, targetState, eventName = null, condition = null) {
-    const conditionName = condition ? condition.getName() : null;
-    for (const transition of sourceState.getTransitions()) {
-      const hasSameTargetState = transition.getTargetState() === targetState;
-      const hasSameCondition = transition.getConditionName() === conditionName;
-      const hasSameEvent = transition.getEventName() === eventName;
-      if (hasSameTargetState && hasSameCondition && hasSameEvent) {
-        return transition;
-      }
-    }
-    return null;
-  }
-  findOrCreateTransition(sourceStateName, targetStateName, eventName = null, condition = null) {
-    const sourceState = this.findOrCreateState(sourceStateName);
-    const targetState = this.findOrCreateState(targetStateName);
-    let transition = this.findTransition(
-      sourceState,
-      targetState,
-      eventName,
-      condition
-    );
-    if (!transition) {
-      transition = new Transition(targetState, eventName, condition);
-      sourceState.addTransition(transition);
-    }
-    return transition;
-  }
-  findOrCreateEvent(sourceStateName, eventName) {
-    const sourceState = this.findOrCreateState(sourceStateName);
-    return sourceState.getEvent(eventName);
-  }
-  addCommand(sourceStateName, eventName, command) {
-    this.findOrCreateEvent(sourceStateName, eventName).attach(command);
-  }
-  addCommandAndSelfTransition(sourceStateName, eventName, command) {
-    this.addCommand(sourceStateName, eventName, command);
-    this.findOrCreateTransition(sourceStateName, sourceStateName, eventName);
+    throw new InvalidSubjectError("StatefulInterface", ["getCurrentStateName"]);
   }
 };
 
@@ -1262,7 +1520,7 @@ function toMermaidId(name) {
 function escapeMermaidLabel(str) {
   return str.replace(/"/g, "#quot;");
 }
-function convertToString2(obj) {
+function convertToString(obj) {
   if (isNamed2(obj)) {
     return obj.getName();
   }
@@ -1271,6 +1529,7 @@ function convertToString2(obj) {
 var GraphBuilder = class {
   nodes = /* @__PURE__ */ new Map();
   edges = [];
+  statesWithEdges = /* @__PURE__ */ new Set();
   getOrCreateNode(state) {
     const name = state.getName();
     let node = this.nodes.get(name);
@@ -1288,7 +1547,7 @@ var GraphBuilder = class {
       const event = state.getEvent(eventName);
       const observerNames = [];
       for (const observer of event.getObservers()) {
-        observerNames.push(convertToString2(observer));
+        observerNames.push(convertToString(observer));
       }
       if (observerNames.length > 0) {
         parts.push(`C: ${observerNames.join(", ")}`);
@@ -1303,6 +1562,9 @@ var GraphBuilder = class {
   }
   addState(state) {
     this.getOrCreateNode(state);
+    const name = state.getName();
+    if (this.statesWithEdges.has(name)) return;
+    this.statesWithEdges.add(name);
     for (const transition of state.getTransitions()) {
       const sourceNode = this.getOrCreateNode(state);
       const targetNode = this.getOrCreateNode(transition.getTargetState());
@@ -1381,19 +1643,24 @@ var GraphBuilder = class {
 0 && (module.exports = {
   AbstractNamedProcessDetector,
   ActiveTransitionFilter,
+  AmbiguousTransitionError,
   AndComposite,
+  AutomaticTransitionCycleError,
   CallbackCondition,
   CallbackObserver,
   Contradiction,
-  Dispatcher,
   DuplicateStateError,
+  DuplicateTransitionError,
   Event,
   Factory,
   FilterStateByEvent,
   FilterStateByFinalState,
   FilterStateByTransition,
   FilterTransitionByEvent,
+  FinitaError,
   GraphBuilder,
+  GraphValidationError,
+  InvalidSubjectError,
   LockAdapterMutex,
   LockCanNotBeAcquiredError,
   MutexFactory,
@@ -1403,12 +1670,14 @@ var GraphBuilder = class {
   OneOrNoneActiveTransition,
   OrComposite,
   Process,
+  ProcessBuilder,
+  ProcessFinalizedError,
+  ProcessNotFoundError,
   ScoreTransition,
-  SetupHelper,
   SingleProcessDetector,
   State,
-  StateCollection,
-  StateCollectionMerger,
+  StateEventNotFoundError,
+  StateNotFoundError,
   StatefulStateNameDetector,
   StatefulStatusChanger,
   Statemachine,