@quazardous/quarkernel 1.0.12 → 2.2.3

package/dist/fsm.js

@@ -0,0 +1,1432 @@
+// src/kernel-event.ts
+var KernelEvent = class {
+  /**
+   * Event name/type
+   */
+  name;
+  /**
+   * Event payload (typed, immutable)
+   */
+  data;
+  /**
+   * Shared mutable context for passing data between listeners
+   */
+  context;
+  /**
+   * Event creation timestamp (milliseconds since epoch)
+   */
+  timestamp;
+  /**
+   * Internal flag: stop propagation to remaining listeners
+   * @private
+   */
+  _propagationStopped = false;
+  constructor(name, data, context = {}) {
+    this.name = name;
+    this.data = data;
+    this.context = context;
+    this.timestamp = Date.now();
+  }
+  /**
+   * Stop propagation to remaining listeners in the chain
+   * Similar to DOM Event.stopPropagation()
+   *
+   * After calling this, no more listeners will execute.
+   */
+  stopPropagation = () => {
+    this._propagationStopped = true;
+  };
+  /**
+   * Check if propagation was stopped
+   * @internal
+   */
+  get isPropagationStopped() {
+    return this._propagationStopped;
+  }
+};
+
+// src/listener-context.ts
+var ListenerContext = class {
+  /** Unique identifier for this listener instance */
+  id;
+  /** Event name this listener is registered for */
+  eventName;
+  /** Listener priority (higher = earlier execution) */
+  priority;
+  /** Listener dependencies (IDs of listeners that must execute first) */
+  dependencies;
+  /** AbortSignal for cancellation (if provided during registration) */
+  signal;
+  /** Reference to the kernel instance for emit/off operations */
+  kernel;
+  /** Reference to the listener function for removal */
+  listenerFn;
+  /** Current event being processed (set during emit) */
+  currentEvent;
+  /**
+   * Creates a new ListenerContext.
+   * @internal Use Kernel.on() to register listeners, which creates contexts automatically.
+   */
+  constructor(id, eventName, priority, dependencies, kernel, listenerFn, signal) {
+    this.id = id;
+    this.eventName = eventName;
+    this.priority = priority;
+    this.dependencies = dependencies;
+    this.kernel = kernel;
+    this.listenerFn = listenerFn;
+    this.signal = signal;
+  }
+  /**
+   * Sets the current event being processed.
+   * @internal Called by Kernel during emit()
+   */
+  setCurrentEvent = (event) => {
+    this.currentEvent = event;
+  };
+  /**
+   * Clears the current event after processing.
+   * @internal Called by Kernel after listener execution
+   */
+  clearCurrentEvent = () => {
+    this.currentEvent = void 0;
+  };
+  /**
+   * Removes this listener from the kernel.
+   * Alias for kernel.off() with this listener's reference.
+   */
+  cancel = () => {
+    this.kernel.off(this.eventName, this.listenerFn);
+  };
+  /**
+   * Alias for cancel() to match common naming patterns.
+   */
+  off = () => {
+    this.cancel();
+  };
+  /**
+   * Emits an event from within this listener.
+   * Delegates to kernel.emit().
+   */
+  emit = async (eventName, data) => {
+    return this.kernel.emit(eventName, data);
+  };
+  /**
+   * Stops propagation of the current event to remaining listeners.
+   * Requires an event to be currently processing.
+   */
+  stopPropagation = () => {
+    if (!this.currentEvent) {
+      throw new Error("stopPropagation() can only be called during event processing");
+    }
+    this.currentEvent.stopPropagation();
+  };
+};
+
+// src/wildcard.ts
+var patternCache = /* @__PURE__ */ new Map();
+var MAX_CACHE_SIZE = 100;
+var patternToRegex = (pattern, delimiter = ":") => {
+  const escapedDelimiter = delimiter.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  if (pattern === "*") {
+    return new RegExp(`^[^${escapedDelimiter}]+$`);
+  }
+  if (pattern === "**") {
+    return new RegExp("^.*$");
+  }
+  const regexPattern = pattern.replace(/\*\*/g, "___DOUBLE_WILDCARD___").replace(/\*/g, `[^${escapedDelimiter}]+`).replace(/___DOUBLE_WILDCARD___/g, ".*");
+  return new RegExp(`^${regexPattern}$`);
+};
+var hasWildcard = (pattern) => {
+  return pattern.includes("*");
+};
+var getPatternRegex = (pattern, delimiter = ":") => {
+  const cacheKey = `${pattern}::${delimiter}`;
+  let regex = patternCache.get(cacheKey);
+  if (!regex) {
+    regex = patternToRegex(pattern, delimiter);
+    if (patternCache.size >= MAX_CACHE_SIZE) {
+      const firstKey = patternCache.keys().next().value;
+      if (firstKey !== void 0) {
+        patternCache.delete(firstKey);
+      }
+    }
+    patternCache.set(cacheKey, regex);
+  }
+  return regex;
+};
+var matchesPattern = (eventName, pattern, delimiter = ":") => {
+  if (!hasWildcard(pattern)) {
+    return eventName === pattern;
+  }
+  const regex = getPatternRegex(pattern, delimiter);
+  return regex.test(eventName);
+};
+var findMatchingPatterns = (eventName, patterns, delimiter = ":") => {
+  return patterns.filter((pattern) => matchesPattern(eventName, pattern, delimiter));
+};
+
+// src/toposort.ts
+var CyclicDependencyError = class extends Error {
+  constructor(cycle) {
+    super(`Cyclic dependency detected: ${cycle.join(" -> ")}`);
+    this.cycle = cycle;
+    this.name = "CyclicDependencyError";
+  }
+};
+var toposort = (nodes) => {
+  const graph = /* @__PURE__ */ new Map();
+  const inDegree = /* @__PURE__ */ new Map();
+  const allNodes = /* @__PURE__ */ new Set();
+  nodes.forEach((node) => {
+    allNodes.add(node.id);
+    if (!graph.has(node.id)) {
+      graph.set(node.id, []);
+    }
+    if (!inDegree.has(node.id)) {
+      inDegree.set(node.id, 0);
+    }
+  });
+  nodes.forEach((node) => {
+    node.after.forEach((dep) => {
+      if (!allNodes.has(dep)) {
+        allNodes.add(dep);
+        graph.set(dep, []);
+        inDegree.set(dep, 0);
+      }
+      graph.get(dep).push(node.id);
+      inDegree.set(node.id, (inDegree.get(node.id) || 0) + 1);
+    });
+  });
+  const queue = [];
+  const result = [];
+  allNodes.forEach((id) => {
+    if (inDegree.get(id) === 0) {
+      queue.push(id);
+    }
+  });
+  while (queue.length > 0) {
+    const current = queue.shift();
+    result.push(current);
+    const neighbors = graph.get(current) || [];
+    neighbors.forEach((neighbor) => {
+      const newDegree = inDegree.get(neighbor) - 1;
+      inDegree.set(neighbor, newDegree);
+      if (newDegree === 0) {
+        queue.push(neighbor);
+      }
+    });
+  }
+  if (result.length !== allNodes.size) {
+    const remaining = Array.from(allNodes).filter((id) => !result.includes(id));
+    const cycle = detectCycle(remaining, graph);
+    throw new CyclicDependencyError(cycle);
+  }
+  return result.filter((id) => nodes.some((n) => n.id === id));
+};
+var detectCycle = (remaining, graph) => {
+  const visited = /* @__PURE__ */ new Set();
+  const recStack = /* @__PURE__ */ new Set();
+  const path = [];
+  const dfs = (node) => {
+    visited.add(node);
+    recStack.add(node);
+    path.push(node);
+    const neighbors = graph.get(node) || [];
+    for (const neighbor of neighbors) {
+      if (!remaining.includes(neighbor)) continue;
+      if (!visited.has(neighbor)) {
+        if (dfs(neighbor)) return true;
+      } else if (recStack.has(neighbor)) {
+        return true;
+      }
+    }
+    recStack.delete(node);
+    path.pop();
+    return false;
+  };
+  for (const node of remaining) {
+    if (!visited.has(node)) {
+      if (dfs(node)) {
+        return [...path];
+      }
+    }
+  }
+  return remaining;
+};
+
+// src/composition/mergers/namespaced.ts
+var createNamespacedMerger = () => ({
+  merge: (contexts, _sources) => {
+    const result = {};
+    for (const [eventName, context] of contexts) {
+      for (const [key, value] of Object.entries(context)) {
+        result[`${eventName}:${key}`] = value;
+      }
+    }
+    return result;
+  },
+  mergeWithConflicts: (contexts, _sources) => {
+    const result = {};
+    for (const [eventName, context] of contexts) {
+      for (const [key, value] of Object.entries(context)) {
+        result[`${eventName}:${key}`] = value;
+      }
+    }
+    return {
+      context: result,
+      conflicts: []
+      // No conflicts possible with namespacing
+    };
+  }
+});
+
+// src/composition/composition.ts
+var COMPOSED_EVENT = "__qk:composed__";
+var Composition = class {
+  kernel;
+  subscriptions = [];
+  buffers = /* @__PURE__ */ new Map();
+  merger;
+  bufferLimit;
+  reset;
+  eventTTL;
+  eventTTLs;
+  sourceEvents = /* @__PURE__ */ new Set();
+  firedSinceLastComposite = /* @__PURE__ */ new Set();
+  lastConflicts = [];
+  expirationTimers = /* @__PURE__ */ new Map();
+  /**
+   * Create a new Composition
+   *
+   * @param kernels - Array of [kernel, eventName] tuples to subscribe to
+   * @param options - Composition options
+   */
+  constructor(kernels, options = {}) {
+    if (kernels.length === 0) {
+      throw new Error("Composition requires at least one kernel");
+    }
+    this.merger = options.merger ?? createNamespacedMerger();
+    this.bufferLimit = options.bufferLimit ?? 100;
+    this.reset = options.reset ?? true;
+    this.eventTTL = options.eventTTL ?? 0;
+    this.eventTTLs = options.eventTTLs ?? {};
+    this.kernel = new Kernel({
+      debug: false,
+      errorBoundary: true,
+      onContextConflict: options.onConflict ? (key, values) => {
+        options.onConflict({
+          key,
+          sources: [],
+          values
+        });
+      } : void 0
+    });
+    for (const [kernel, eventName] of kernels) {
+      this.subscribeToKernel(kernel, eventName);
+      this.sourceEvents.add(eventName);
+    }
+  }
+  /**
+   * Subscribe to events from a source kernel
+   */
+  subscribeToKernel(kernel, eventName) {
+    this.buffers.set(eventName, []);
+    const unbind = kernel.on(
+      eventName,
+      async (event) => {
+        await this.handleSourceEvent(eventName, event);
+      },
+      { priority: -Infinity }
+    );
+    this.subscriptions.push({
+      kernel,
+      eventName,
+      unbind
+    });
+  }
+  /**
+   * Get the effective TTL for a specific event
+   * Priority: per-event TTL > global TTL > 0 (permanent)
+   */
+  getEffectiveTTL(eventName) {
+    const perEventTTL = this.eventTTLs[eventName];
+    if (perEventTTL !== void 0) {
+      return perEventTTL;
+    }
+    return this.eventTTL > 0 ? this.eventTTL : "permanent";
+  }
+  /**
+   * Handle an event from a source kernel
+   */
+  async handleSourceEvent(eventName, event) {
+    const buffer = this.buffers.get(eventName);
+    if (!buffer) return;
+    const effectiveTTL = this.getEffectiveTTL(eventName);
+    const eventId = `${eventName}:${event.timestamp}:${Math.random().toString(36).slice(2, 8)}`;
+    buffer.push({
+      name: event.name,
+      data: event.data,
+      context: { ...event.context },
+      timestamp: event.timestamp
+    });
+    if (buffer.length > this.bufferLimit) {
+      buffer.shift();
+    }
+    this.firedSinceLastComposite.add(eventName);
+    const compositionCompleted = await this.checkAndEmitComposite();
+    if (effectiveTTL === "instant" && !compositionCompleted) {
+      buffer.pop();
+      this.firedSinceLastComposite.delete(eventName);
+      return;
+    }
+    if (typeof effectiveTTL === "number" && effectiveTTL > 0) {
+      const timer = setTimeout(() => {
+        this.expireEvent(eventName, event.timestamp);
+        this.expirationTimers.delete(eventId);
+      }, effectiveTTL);
+      this.expirationTimers.set(eventId, timer);
+    }
+  }
+  /**
+   * Expire an event from the buffer based on timestamp
+   */
+  expireEvent(eventName, timestamp) {
+    const buffer = this.buffers.get(eventName);
+    if (!buffer) return;
+    const filtered = buffer.filter((e) => e.timestamp > timestamp);
+    this.buffers.set(eventName, filtered);
+    if (filtered.length === 0) {
+      this.firedSinceLastComposite.delete(eventName);
+    }
+  }
+  /**
+   * Check if all source events have fired and emit composite event
+   * @returns true if composite was emitted, false otherwise
+   */
+  async checkAndEmitComposite() {
+    for (const eventName of this.sourceEvents) {
+      const buffer = this.buffers.get(eventName);
+      if (!buffer || buffer.length === 0) {
+        return false;
+      }
+    }
+    for (const eventName of this.sourceEvents) {
+      if (!this.firedSinceLastComposite.has(eventName)) {
+        return false;
+      }
+    }
+    if (this.kernel.listenerCount(COMPOSED_EVENT) === 0) {
+      return false;
+    }
+    const contexts = /* @__PURE__ */ new Map();
+    const sources = Array.from(this.sourceEvents);
+    for (const eventName of sources) {
+      const buffer = this.buffers.get(eventName);
+      if (!buffer || buffer.length === 0) continue;
+      const latestEvent = buffer[buffer.length - 1];
+      const eventData = latestEvent.data && typeof latestEvent.data === "object" ? latestEvent.data : {};
+      const combined = { ...eventData, ...latestEvent.context };
+      contexts.set(eventName, combined);
+    }
+    const mergeResult = this.merger.mergeWithConflicts(contexts, sources);
+    this.lastConflicts = mergeResult.conflicts;
+    await this.kernel.emit(COMPOSED_EVENT, {
+      sources,
+      contexts: Object.fromEntries(contexts),
+      merged: mergeResult.context
+    });
+    this.firedSinceLastComposite.clear();
+    if (this.reset) {
+      for (const eventName of this.sourceEvents) {
+        const buffer = this.buffers.get(eventName);
+        if (buffer && buffer.length > 0) {
+          const latest = buffer[buffer.length - 1];
+          this.buffers.set(eventName, [latest]);
+        }
+      }
+    }
+    return true;
+  }
+  /**
+   * Register a listener for when all source events have fired
+   * This is the primary way to react to composition completion
+   *
+   * @param listener - Function called with merged context when composition completes
+   * @param options - Listener options (priority, id, etc.)
+   * @returns Unbind function to remove the listener
+   */
+  onComposed(listener, options) {
+    return this.kernel.on(COMPOSED_EVENT, listener, options);
+  }
+  /**
+   * Remove a listener for composed events
+   */
+  offComposed(listener) {
+    this.kernel.off(COMPOSED_EVENT, listener);
+  }
+  /**
+   * Get number of composed event listeners
+   */
+  composedListenerCount() {
+    return this.kernel.listenerCount(COMPOSED_EVENT);
+  }
+  /**
+   * Register a listener for events on internal kernel
+   * Note: Use onComposed() to listen for composition completion
+   */
+  on(eventName, listener, options) {
+    return this.kernel.on(eventName, listener, options);
+  }
+  /**
+   * Remove a listener
+   * Delegates to internal kernel
+   */
+  off(eventName, listener) {
+    this.kernel.off(eventName, listener);
+  }
+  /**
+   * Emit an event through the composition
+   * Note: Reserved internal events (prefixed with __qk:) cannot be emitted
+   */
+  async emit(eventName, data) {
+    if (String(eventName).startsWith("__qk:")) {
+      throw new Error(`Cannot emit reserved event: ${String(eventName)}`);
+    }
+    return this.kernel.emit(eventName, data);
+  }
+  /**
+   * Get merged context from latest buffered events
+   * Does not emit - just returns the merged context
+   */
+  getContext() {
+    for (const eventName of this.sourceEvents) {
+      const buffer = this.buffers.get(eventName);
+      if (!buffer || buffer.length === 0) {
+        return null;
+      }
+    }
+    const contexts = /* @__PURE__ */ new Map();
+    const sources = Array.from(this.sourceEvents);
+    for (const eventName of sources) {
+      const buffer = this.buffers.get(eventName);
+      if (!buffer || buffer.length === 0) continue;
+      const latestEvent = buffer[buffer.length - 1];
+      const eventData = latestEvent.data && typeof latestEvent.data === "object" ? latestEvent.data : {};
+      const combined = { ...eventData, ...latestEvent.context };
+      contexts.set(eventName, combined);
+    }
+    const mergeResult = this.merger.mergeWithConflicts(contexts, sources);
+    this.lastConflicts = mergeResult.conflicts;
+    return mergeResult.context;
+  }
+  /**
+   * Get number of listeners for an event
+   */
+  listenerCount(eventName) {
+    return this.kernel.listenerCount(eventName);
+  }
+  /**
+   * Get all event names with registered listeners
+   */
+  eventNames() {
+    return this.kernel.eventNames();
+  }
+  /**
+   * Remove all listeners
+   */
+  offAll(eventName) {
+    this.kernel.offAll(eventName);
+  }
+  /**
+   * Enable/disable debug mode
+   */
+  debug(enabled) {
+    this.kernel.debug(enabled);
+  }
+  /**
+   * Get buffer for a specific source event (for debugging)
+   */
+  getBuffer(eventName) {
+    return this.buffers.get(eventName);
+  }
+  /**
+   * Clear all buffers
+   */
+  clearBuffers() {
+    for (const eventName of this.sourceEvents) {
+      this.buffers.set(eventName, []);
+    }
+    this.firedSinceLastComposite.clear();
+  }
+  /**
+   * Get conflicts detected during the last merge operation
+   *
+   * Returns an array of ConflictInfo objects describing which source events
+   * provided conflicting values for the same context keys.
+   *
+   * @returns Array of conflicts from the last merge, or empty array if no conflicts
+   */
+  getConflicts() {
+    return this.lastConflicts;
+  }
+  /**
+   * Cleanup all subscriptions and listeners
+   */
+  dispose() {
+    for (const sub of this.subscriptions) {
+      sub.unbind();
+    }
+    this.subscriptions = [];
+    for (const timer of this.expirationTimers.values()) {
+      clearTimeout(timer);
+    }
+    this.expirationTimers.clear();
+    this.kernel.offAll();
+    this.buffers.clear();
+    this.sourceEvents.clear();
+    this.firedSinceLastComposite.clear();
+    this.lastConflicts = [];
+  }
+  /**
+   * Get the configured global event TTL in milliseconds
+   * @returns The TTL value, or 0 if no TTL is configured
+   */
+  getEventTTL() {
+    return this.eventTTL;
+  }
+  /**
+   * Set the global event TTL in milliseconds
+   * @param ttl - TTL in milliseconds (0 = permanent)
+   */
+  setEventTTL(ttl) {
+    this.eventTTL = ttl;
+  }
+  /**
+   * Get per-event TTL configuration
+   * @returns The eventTTLs configuration object
+   */
+  getEventTTLs() {
+    return this.eventTTLs;
+  }
+  /**
+   * Set TTL for a specific event
+   * @param eventName - The event name to configure
+   * @param ttl - TTL value: number (ms), 'permanent', or 'instant'
+   */
+  setEventTTLFor(eventName, ttl) {
+    this.eventTTLs[eventName] = ttl;
+  }
+  /**
+   * Remove per-event TTL configuration (falls back to global TTL)
+   * @param eventName - The event name to reset
+   */
+  clearEventTTLFor(eventName) {
+    delete this.eventTTLs[eventName];
+  }
+};
+
+// src/kernel.ts
+var Kernel = class _Kernel {
+  listeners = /* @__PURE__ */ new Map();
+  options;
+  listenerIdCounter = 0;
+  executionErrors = [];
+  constructor(options = {}) {
+    this.options = {
+      delimiter: options.delimiter ?? ":",
+      wildcard: options.wildcard ?? true,
+      maxListeners: options.maxListeners ?? Infinity,
+      debug: options.debug ?? false,
+      errorBoundary: options.errorBoundary ?? true,
+      onError: options.onError ?? ((error) => {
+        console.error("Kernel error:", error);
+      }),
+      contextMerger: options.contextMerger ?? void 0,
+      onContextConflict: options.onContextConflict ?? void 0
+    };
+    if (this.options.debug) {
+      console.debug("[QuarKernel] Kernel initialized", {
+        delimiter: this.options.delimiter,
+        wildcard: this.options.wildcard,
+        maxListeners: this.options.maxListeners,
+        errorBoundary: this.options.errorBoundary
+      });
+    }
+  }
+  /**
+   * Register an event listener
+   * Returns an unbind function for cleanup
+   */
+  on(eventName, listener, options = {}) {
+    const event = String(eventName);
+    if (options.signal?.aborted) {
+      if (this.options.debug) {
+        console.debug("[QuarKernel] Listener not added (signal already aborted)", {
+          event
+        });
+      }
+      return () => {
+      };
+    }
+    const priority = options.priority ?? 0;
+    const id = options.id ?? `listener_${++this.listenerIdCounter}`;
+    const after = Array.isArray(options.after) ? options.after : options.after ? [options.after] : [];
+    let abortListener;
+    if (options.signal) {
+      abortListener = () => this.off(event, listener);
+    }
+    const entry = {
+      id,
+      callback: listener,
+      after,
+      priority,
+      once: options.once ?? false,
+      original: listener,
+      signal: options.signal,
+      abortListener
+    };
+    const entries = this.listeners.get(event) ?? [];
+    entries.push(entry);
+    entries.sort((a, b) => b.priority - a.priority);
+    this.listeners.set(event, entries);
+    if (this.options.debug) {
+      console.debug("[QuarKernel] Listener added", {
+        event,
+        listenerId: id,
+        priority,
+        after,
+        once: entry.once,
+        totalListeners: entries.length
+      });
+    }
+    if (this.options.maxListeners > 0 && entries.length > this.options.maxListeners) {
+      console.warn(
+        `MaxListenersExceeded: Event "${event}" has ${entries.length} listeners (limit: ${this.options.maxListeners})`
+      );
+    }
+    if (options.signal && abortListener) {
+      options.signal.addEventListener("abort", abortListener, { once: true });
+    }
+    return () => this.off(event, listener);
+  }
+  /**
+   * Remove an event listener
+   * If no listener provided, removes all listeners for the event
+   */
+  off(eventName, listener) {
+    const entries = this.listeners.get(eventName);
+    if (!entries) {
+      return;
+    }
+    if (!listener) {
+      if (this.options.debug) {
+        console.debug("[QuarKernel] All listeners removed", {
+          event: eventName,
+          count: entries.length
+        });
+      }
+      for (const entry of entries) {
+        if (entry.signal && entry.abortListener) {
+          entry.signal.removeEventListener("abort", entry.abortListener);
+        }
+      }
+      this.listeners.delete(eventName);
+      return;
+    }
+    const entryToRemove = entries.find((entry) => entry.original === listener);
+    if (entryToRemove?.signal && entryToRemove.abortListener) {
+      entryToRemove.signal.removeEventListener("abort", entryToRemove.abortListener);
+    }
+    const filtered = entries.filter((entry) => entry.original !== listener);
+    const removed = entries.length - filtered.length;
+    if (this.options.debug && removed > 0) {
+      console.debug("[QuarKernel] Listener removed", {
+        event: eventName,
+        removed,
+        remaining: filtered.length
+      });
+    }
+    if (filtered.length === 0) {
+      this.listeners.delete(eventName);
+    } else {
+      this.listeners.set(eventName, filtered);
+    }
+  }
+  /**
+   * Emit an event
+   * Executes all registered listeners in parallel (by default)
+   * Returns a Promise that resolves when all listeners complete
+   * Throws AggregateError if any listeners failed
+   */
+  async emit(eventName, data) {
+    const event = String(eventName);
+    const allPatterns = Array.from(this.listeners.keys());
+    const matchingPatterns = this.options.wildcard ? findMatchingPatterns(event, allPatterns, this.options.delimiter) : allPatterns.filter((p) => p === event);
+    const allEntries = [];
+    for (const pattern of matchingPatterns) {
+      const entries = this.listeners.get(pattern);
+      if (entries) {
+        allEntries.push(...entries);
+      }
+    }
+    if (allEntries.length === 0) {
+      if (this.options.debug) {
+        console.debug("[QuarKernel] Event emitted (no listeners)", { event });
+      }
+      return;
+    }
+    if (this.options.debug) {
+      console.debug("[QuarKernel] Event emitted", {
+        event,
+        listenerCount: allEntries.length,
+        data: data !== void 0 ? JSON.stringify(data).substring(0, 100) : void 0
+      });
+    }
+    this.executionErrors = [];
+    const kernelEvent = new KernelEvent(
+      event,
+      data,
+      {}
+    );
+    const sortedEntries = this.sortListenersByDependencies(allEntries);
+    const promises = sortedEntries.map(
+      (entry) => this.executeListener(entry, kernelEvent, event)
+    );
+    const results = await Promise.allSettled(promises);
+    this.removeOnceListeners(event, sortedEntries, kernelEvent);
+    if (!this.options.errorBoundary) {
+      const errors = results.filter((result) => result.status === "rejected").map((result) => result.reason);
+      if (errors.length > 0) {
+        throw new AggregateError(errors, `${errors.length} listener(s) failed for event "${event}"`);
+      }
+    }
+    if (this.options.debug) {
+      console.debug("[QuarKernel] Event completed", {
+        event
+      });
+    }
+  }
+  /**
+   * Emit an event with serial execution
+   * Executes listeners sequentially (one after another) instead of in parallel
+   * Respects the same dependency and priority ordering as emit()
+   * Stops on first error if errorBoundary is false, otherwise continues and collects errors
+   */
+  async emitSerial(eventName, data) {
+    const event = String(eventName);
+    const allPatterns = Array.from(this.listeners.keys());
+    const matchingPatterns = this.options.wildcard ? findMatchingPatterns(event, allPatterns, this.options.delimiter) : allPatterns.filter((p) => p === event);
+    const allEntries = [];
+    for (const pattern of matchingPatterns) {
+      const entries = this.listeners.get(pattern);
+      if (entries) {
+        allEntries.push(...entries);
+      }
+    }
+    if (allEntries.length === 0) {
+      if (this.options.debug) {
+        console.debug("[QuarKernel] Event emitted serially (no listeners)", { event });
+      }
+      return;
+    }
+    if (this.options.debug) {
+      console.debug("[QuarKernel] Event emitted serially", {
+        event,
+        listenerCount: allEntries.length,
+        data: data !== void 0 ? JSON.stringify(data).substring(0, 100) : void 0
+      });
+    }
+    this.executionErrors = [];
+    const kernelEvent = new KernelEvent(
+      event,
+      data,
+      {}
+    );
+    const sortedEntries = this.sortListenersByDependencies(allEntries);
+    const errors = [];
+    for (const entry of sortedEntries) {
+      try {
+        await this.executeListener(entry, kernelEvent, event);
+      } catch (error) {
+        if (!this.options.errorBoundary) {
+          this.removeOnceListeners(event, sortedEntries, kernelEvent);
+          throw error;
+        }
+        errors.push(error);
+      }
+    }
+    this.removeOnceListeners(event, sortedEntries, kernelEvent);
+    if (!this.options.errorBoundary && errors.length > 0) {
+      throw new AggregateError(errors, `${errors.length} listener(s) failed for event "${event}"`);
+    }
+    if (this.options.debug) {
+      console.debug("[QuarKernel] Event completed serially", {
+        event
+      });
+    }
+  }
+  /**
+   * Sort listeners by dependencies and priority
+   * Uses topological sort for dependency resolution
+   */
+  sortListenersByDependencies(entries) {
+    const hasDependencies = entries.some((e) => e.after.length > 0);
+    if (!hasDependencies) {
+      return [...entries].sort((a, b) => b.priority - a.priority);
+    }
+    const listenerIds = new Set(entries.map((e) => e.id));
+    for (const entry of entries) {
+      for (const dep of entry.after) {
+        if (!listenerIds.has(dep)) {
+          throw new Error(`Listener "${entry.id}" depends on missing listener "${dep}"`);
+        }
+      }
+    }
+    const nodes = entries.map((e) => ({
+      id: e.id,
+      after: e.after
+    }));
+    toposort(nodes);
+    const levelMap = /* @__PURE__ */ new Map();
+    const assignLevel = (id, visited = /* @__PURE__ */ new Set()) => {
+      if (levelMap.has(id)) {
+        return levelMap.get(id);
+      }
+      if (visited.has(id)) {
+        return 0;
+      }
+      visited.add(id);
+      const entry = entries.find((e) => e.id === id);
+      if (!entry || entry.after.length === 0) {
+        levelMap.set(id, 0);
+        return 0;
+      }
+      const maxDepLevel = Math.max(...entry.after.map((dep) => assignLevel(dep, visited)));
+      const level = maxDepLevel + 1;
+      levelMap.set(id, level);
+      return level;
+    };
+    entries.forEach((e) => assignLevel(e.id));
+    return [...entries].sort((a, b) => {
+      const levelA = levelMap.get(a.id) ?? 0;
+      const levelB = levelMap.get(b.id) ?? 0;
+      if (levelA !== levelB) {
+        return levelA - levelB;
+      }
+      return b.priority - a.priority;
+    });
+  }
+  /**
+   * Execute a single listener with error handling
+   */
+  async executeListener(entry, event, eventName) {
+    if (event.isPropagationStopped) {
+      if (this.options.debug) {
+        console.debug("[QuarKernel] Listener skipped (propagation stopped)", {
+          listenerId: entry.id
+        });
+      }
+      return;
+    }
+    const startTime = Date.now();
+    if (this.options.debug) {
+      console.debug("[QuarKernel] Listener executing", {
+        listenerId: entry.id,
+        event: eventName,
+        priority: entry.priority
+      });
+    }
+    try {
+      const ctx = new ListenerContext(
+        entry.id,
+        eventName,
+        entry.priority,
+        entry.after,
+        this,
+        entry.original,
+        entry.signal
+      );
+      ctx.setCurrentEvent(event);
+      try {
+        await entry.callback(event, ctx);
+        if (this.options.debug) {
+          const duration = Date.now() - startTime;
+          console.debug("[QuarKernel] Listener completed", {
+            listenerId: entry.id,
+            duration: `${duration}ms`
+          });
+        }
+      } finally {
+        ctx.clearCurrentEvent();
+      }
+    } catch (error) {
+      const executionError = {
+        listenerId: entry.id,
+        error,
+        timestamp: Date.now(),
+        eventName
+      };
+      this.executionErrors.push(executionError);
+      if (this.options.debug) {
+        console.debug("[QuarKernel] Listener error", {
+          listenerId: entry.id,
+          error: error.message
+        });
+      }
+      if (this.options.errorBoundary) {
+        this.options.onError(error, event);
+      } else {
+        throw error;
+      }
+    }
+  }
+  /**
+   * Remove listeners marked with once: true or whose predicate returns true after execution
+   *
+   * This method is called AFTER all listeners have executed for an event.
+   * The predicate functions receive the event object with the final state after all listeners ran.
+   *
+   * Behavior:
+   * - If once: true, the listener is always removed after execution
+   * - If once is a predicate function, it's evaluated with the post-execution event state
+   * - Predicates can examine event.context to make decisions based on listener modifications
+   * - Listeners are removed even if they threw errors (when errorBoundary: true)
+   *
+   * @param eventName - The event name being processed
+   * @param entries - Listeners that executed (or were scheduled to execute)
+   * @param event - The event object with final state after all listeners executed
+   */
+  removeOnceListeners(eventName, entries, event) {
+    const listenersToRemove = entries.filter((entry) => {
+      if (!entry.once) {
+        return false;
+      }
+      if (entry.once === true) {
+        return true;
+      }
+      if (typeof entry.once === "function") {
+        return entry.once(event);
+      }
+      return false;
+    });
+    if (listenersToRemove.length === 0) {
+      return;
+    }
+    if (this.options.debug) {
+      console.debug("[QuarKernel] Removing once listeners", {
+        event: eventName,
+        count: listenersToRemove.length
+      });
+    }
+    for (const entry of listenersToRemove) {
+      for (const [pattern, entries2] of this.listeners.entries()) {
+        if (entries2.includes(entry)) {
+          this.off(pattern, entry.original);
+          break;
+        }
+      }
+    }
+  }
+  /**
+   * Get number of listeners for an event
+   */
+  listenerCount(eventName) {
+    if (!eventName) {
+      let total = 0;
+      for (const entries2 of this.listeners.values()) {
+        total += entries2.length;
+      }
+      return total;
+    }
+    const event = String(eventName);
+    const entries = this.listeners.get(event);
+    return entries?.length ?? 0;
+  }
+  /**
+   * Get all event names with registered listeners
+   */
+  eventNames() {
+    return Array.from(this.listeners.keys());
+  }
+  /**
+   * Remove all listeners for all events (or specific event)
+   */
+  offAll(eventName) {
+    if (!eventName) {
+      for (const entries2 of this.listeners.values()) {
+        for (const entry of entries2) {
+          if (entry.signal && entry.abortListener) {
+            entry.signal.removeEventListener("abort", entry.abortListener);
+          }
+        }
+      }
+      this.listeners.clear();
+      return;
+    }
+    const event = String(eventName);
+    const entries = this.listeners.get(event);
+    if (entries) {
+      for (const entry of entries) {
+        if (entry.signal && entry.abortListener) {
+          entry.signal.removeEventListener("abort", entry.abortListener);
+        }
+      }
+    }
+    this.listeners.delete(event);
+  }
+  /**
+   * Enable/disable debug mode
+   * In T115, this is a placeholder - full debug implementation in T129
+   */
+  debug(enabled) {
+    this.options.debug = enabled;
+    if (enabled) {
+      console.debug("[QuarKernel] Debug mode enabled");
+    } else {
+      console.debug("[QuarKernel] Debug mode disabled");
+    }
+  }
+  /**
+   * Get collected execution errors from the last emit
+   * Useful for error aggregation and reporting
+   */
+  getExecutionErrors() {
+    return this.executionErrors;
+  }
+  /**
+   * Clear collected execution errors
+   */
+  clearExecutionErrors() {
+    this.executionErrors = [];
+  }
+  /**
+   * Create a composition from multiple kernels
+   *
+   * @param kernels - Rest parameters of [kernel, eventName] tuples
+   * @param options - Optional composition options (if last argument is not a tuple)
+   * @returns Composition instance that merges events from all kernels
+   *
+   * @example
+   * ```ts
+   * const userKernel = createKernel();
+   * const profileKernel = createKernel();
+   *
+   * const composition = Kernel.compose(
+   *   [userKernel, 'user:loaded'],
+   *   [profileKernel, 'profile:loaded'],
+   *   { merger: createNamespacedMerger() }
+   * );
+   *
+   * composition.onComposed((event) => {
+   *   console.log('All sources ready:', event.data.merged);
+   * });
+   * ```
+   */
+  static compose(...args) {
+    const kernels = [];
+    let options;
+    for (const arg of args) {
+      if (Array.isArray(arg) && arg.length === 2 && arg[0] instanceof _Kernel) {
+        kernels.push(arg);
+      } else if (typeof arg === "object" && !Array.isArray(arg)) {
+        options = arg;
+      }
+    }
+    return new Composition(kernels, options);
+  }
+};
+
+// src/fsm/machine.ts
+function useMachine(kernel, config) {
+  const {
+    prefix,
+    initial,
+    states,
+    allowForce = true,
+    snapshot,
+    trackHistory = false,
+    maxHistory = 100
+  } = config;
+  let currentState = snapshot?.state ?? initial;
+  let context = snapshot?.context ?? config.context ?? {};
+  let history = snapshot?.history ? [...snapshot.history] : [];
+  if (!states[currentState]) {
+    throw new Error(`Invalid initial state "${currentState}" - not defined in states`);
+  }
+  const cleanupFns = [];
+  const emitFSM = async (eventType, data) => {
+    const eventData = {
+      machine: prefix,
+      ...data
+    };
+    await kernel.emit(`${prefix}:${eventType}`, eventData);
+  };
+  const getTransition = (event) => {
+    const stateNode = states[currentState];
+    if (!stateNode?.on) return null;
+    const transition = stateNode.on[event];
+    if (!transition) return null;
+    if (typeof transition === "string") {
+      return { target: transition };
+    }
+    return transition;
+  };
+  const doTransition = async (event, targetState, payload, forced = false) => {
+    const fromState = currentState;
+    const fromNode = states[fromState];
+    const toNode = states[targetState];
+    if (!toNode) {
+      throw new Error(`Invalid target state "${targetState}" - not defined in states`);
+    }
+    if (fromNode?.exit) {
+      await fromNode.exit(context, event, payload);
+    }
+    await emitFSM(`exit:${fromState}`, {
+      state: fromState,
+      from: fromState,
+      to: targetState,
+      event,
+      payload,
+      forced
+    });
+    currentState = targetState;
+    if (trackHistory) {
+      history.push({
+        from: fromState,
+        to: targetState,
+        event,
+        timestamp: Date.now()
+      });
+      if (history.length > maxHistory) {
+        history = history.slice(-maxHistory);
+      }
+    }
+    await emitFSM("transition", {
+      state: targetState,
+      from: fromState,
+      to: targetState,
+      event,
+      payload,
+      forced
+    });
+    await emitFSM(`transition:${event}`, {
+      state: targetState,
+      from: fromState,
+      to: targetState,
+      event,
+      payload,
+      forced
+    });
+    await emitFSM(`enter:${targetState}`, {
+      state: targetState,
+      from: fromState,
+      to: targetState,
+      event,
+      payload,
+      forced
+    });
+    if (toNode.entry) {
+      await toNode.entry(context, event, payload);
+    }
+  };
+  const machine = {
+    prefix,
+    getState() {
+      return currentState;
+    },
+    getContext() {
+      return context;
+    },
+    setContext(updater) {
+      if (typeof updater === "function") {
+        context = updater(context);
+      } else {
+        context = { ...context, ...updater };
+      }
+    },
+    async send(event, payload, options = {}) {
+      const { force = false, target, guard: inlineGuard, fallback } = options;
+      if (force && allowForce) {
+        const targetState = target ?? initial;
+        await doTransition(event, targetState, payload, true);
+        return true;
+      }
+      const transition = getTransition(event);
+      if (!transition) {
+        if (force && !allowForce) {
+          throw new Error(`Force transitions not allowed on machine "${prefix}"`);
+        }
+        return false;
+      }
+      const guardFn = inlineGuard ?? transition.guard;
+      if (guardFn && !guardFn(context, event, payload)) {
+        await emitFSM("guard:rejected", {
+          state: currentState,
+          event,
+          payload
+        });
+        if (fallback) {
+          if (!states[fallback]) {
+            throw new Error(`Invalid fallback state "${fallback}" - not defined in states`);
+          }
+          await doTransition(event, fallback, payload, false);
+          return true;
+        }
+        return false;
+      }
+      if (transition.actions) {
+        const actions = Array.isArray(transition.actions) ? transition.actions : [transition.actions];
+        for (const action of actions) {
+          await action(context, event, payload);
+        }
+      }
+      await doTransition(event, transition.target, payload, false);
+      return true;
+    },
+    can(event) {
+      return getTransition(event) !== null;
+    },
+    transitions() {
+      const stateNode = states[currentState];
+      if (!stateNode?.on) return [];
+      return Object.keys(stateNode.on);
+    },
+    toJSON() {
+      return {
+        state: currentState,
+        context: structuredClone(context),
+        history: trackHistory ? [...history] : void 0
+      };
+    },
+    restore(snapshot2) {
+      if (!states[snapshot2.state]) {
+        throw new Error(`Invalid snapshot state "${snapshot2.state}" - not defined in states`);
+      }
+      currentState = snapshot2.state;
+      context = snapshot2.context;
+      if (snapshot2.history) {
+        history = [...snapshot2.history];
+      }
+    },
+    destroy() {
+      for (const cleanup of cleanupFns) {
+        cleanup();
+      }
+      cleanupFns.length = 0;
+    }
+  };
+  if (!snapshot) {
+    setTimeout(async () => {
+      const initialNode = states[initial];
+      await emitFSM(`enter:${initial}`, {
+        state: initial
+      });
+      if (initialNode?.entry) {
+        await initialNode.entry(context, "__INIT__", void 0);
+      }
+    }, 0);
+  }
+  return machine;
+}
+function defineMachine(config) {
+  return config;
+}
+
+// src/fsm/create-machine.ts
+function createMachine(config) {
+  const {
+    id,
+    initial,
+    context: initialContext,
+    states,
+    on: eventHandlers = {},
+    helpers: customHelpers = {}
+  } = config;
+  const kernel = new Kernel();
+  const activeTimers = /* @__PURE__ */ new Map();
+  const machineConfig = {
+    prefix: id,
+    initial,
+    context: initialContext,
+    states: {},
+    trackHistory: true
+  };
+  for (const [stateName, stateDef] of Object.entries(states)) {
+    machineConfig.states[stateName] = {
+      on: stateDef.on ? { ...stateDef.on } : void 0
+    };
+  }
+  const baseMachine = useMachine(kernel, machineConfig);
+  const createHelpers = () => ({
+    // Built-ins
+    set: (partial) => baseMachine.setContext(partial),
+    send: (event, payload) => baseMachine.send(event, payload),
+    log: console.log,
+    // Custom helpers (can override built-ins)
+    ...customHelpers
+  });
+  kernel.on(`${id}:enter:*`, async (e) => {
+    const stateName = e.data?.state;
+    if (!stateName) return;
+    activeTimers.forEach((timer, key) => {
+      if (!key.startsWith(stateName + ":")) {
+        clearTimeout(timer);
+        activeTimers.delete(key);
+      }
+    });
+    const stateConfig = states[stateName];
+    if (!stateConfig) return;
+    if (stateConfig.entry) {
+      await stateConfig.entry(baseMachine.getContext(), createHelpers());
+    }
+    if (stateConfig.after) {
+      const timerId = setTimeout(() => {
+        baseMachine.send(stateConfig.after.send);
+        activeTimers.delete(stateName + ":timer");
+      }, stateConfig.after.delay);
+      activeTimers.set(stateName + ":timer", timerId);
+    }
+  });
+  kernel.on(`${id}:exit:*`, async (e) => {
+    const stateName = e.data?.state;
+    if (!stateName) return;
+    const timerId = activeTimers.get(stateName + ":timer");
+    if (timerId) {
+      clearTimeout(timerId);
+      activeTimers.delete(stateName + ":timer");
+    }
+    const stateConfig = states[stateName];
+    if (!stateConfig) return;
+    if (stateConfig.exit) {
+      await stateConfig.exit(baseMachine.getContext(), createHelpers());
+    }
+  });
+  kernel.on(`${id}:transition`, async (e) => {
+    const event = e.data?.event;
+    if (!event) return;
+    const handler = eventHandlers[event];
+    if (handler) {
+      await handler(baseMachine.getContext(), createHelpers());
+    }
+  });
+  const machine = {
+    ...baseMachine,
+    id,
+    get state() {
+      return baseMachine.getState();
+    },
+    get context() {
+      return baseMachine.getContext();
+    },
+    destroy() {
+      activeTimers.forEach((timer) => clearTimeout(timer));
+      activeTimers.clear();
+      baseMachine.destroy();
+    }
+  };
+  return machine;
+}
+
+export { createMachine, defineMachine, useMachine };
+//# sourceMappingURL=fsm.js.map
+//# sourceMappingURL=fsm.js.map