@quazardous/quarkernel 1.0.11 → 2.2.2

package/dist/index-BDf1xZi6.d.cts

@@ -0,0 +1,896 @@
+import { M as MachineConfig, a as Machine } from './create-machine-CYsscHPX.cjs';
+
+/**
+ * KernelEvent - Custom event implementation for QuarKernel
+ *
+ * NOT based on native Event/EventTarget for design reasons:
+ * - Need shared mutable context between listeners
+ * - Need dependency-ordered execution
+ * - Simpler API without DOM baggage
+ */
+/**
+ * Event propagation control for listener execution
+ */
+declare class KernelEvent<T = unknown> {
+    /**
+     * Event name/type
+     */
+    readonly name: string;
+    /**
+     * Event payload (typed, immutable)
+     */
+    readonly data: T;
+    /**
+     * Shared mutable context for passing data between listeners
+     */
+    readonly context: Record<string, any>;
+    /**
+     * Event creation timestamp (milliseconds since epoch)
+     */
+    readonly timestamp: number;
+    /**
+     * Internal flag: stop propagation to remaining listeners
+     * @private
+     */
+    private _propagationStopped;
+    constructor(name: string, data: T, context?: Record<string, any>);
+    /**
+     * Stop propagation to remaining listeners in the chain
+     * Similar to DOM Event.stopPropagation()
+     *
+     * After calling this, no more listeners will execute.
+     */
+    stopPropagation: () => void;
+    /**
+     * Check if propagation was stopped
+     * @internal
+     */
+    get isPropagationStopped(): boolean;
+}
+
+/**
+ * ListenerContext provides metadata and utilities for event listeners.
+ * Passed as the second parameter to listener callbacks: (event, ctx) => {}
+ *
+ * Features:
+ * - Listener metadata (id, eventName, priority, dependencies)
+ * - Cancellation via cancel() or AbortSignal
+ * - Event emission from within listeners
+ * - Propagation control
+ */
+
+/**
+ * Context object passed to each listener callback.
+ * Provides utilities for listener self-management without polluting the event object.
+ */
+declare class ListenerContext {
+    /** Unique identifier for this listener instance */
+    readonly id: string;
+    /** Event name this listener is registered for */
+    readonly eventName: string;
+    /** Listener priority (higher = earlier execution) */
+    readonly priority: number;
+    /** Listener dependencies (IDs of listeners that must execute first) */
+    readonly dependencies: readonly string[];
+    /** AbortSignal for cancellation (if provided during registration) */
+    readonly signal?: AbortSignal;
+    /** Reference to the kernel instance for emit/off operations */
+    private readonly kernel;
+    /** Reference to the listener function for removal */
+    private readonly listenerFn;
+    /** Current event being processed (set during emit) */
+    private currentEvent?;
+    /**
+     * Creates a new ListenerContext.
+     * @internal Use Kernel.on() to register listeners, which creates contexts automatically.
+     */
+    constructor(id: string, eventName: string, priority: number, dependencies: readonly string[], kernel: ListenerContextKernel, listenerFn: Function, signal?: AbortSignal);
+    /**
+     * Sets the current event being processed.
+     * @internal Called by Kernel during emit()
+     */
+    setCurrentEvent: (event: KernelEvent<any>) => void;
+    /**
+     * Clears the current event after processing.
+     * @internal Called by Kernel after listener execution
+     */
+    clearCurrentEvent: () => void;
+    /**
+     * Removes this listener from the kernel.
+     * Alias for kernel.off() with this listener's reference.
+     */
+    cancel: () => void;
+    /**
+     * Alias for cancel() to match common naming patterns.
+     */
+    off: () => void;
+    /**
+     * Emits an event from within this listener.
+     * Delegates to kernel.emit().
+     */
+    emit: <T = any>(eventName: string, data?: T) => Promise<void>;
+    /**
+     * Stops propagation of the current event to remaining listeners.
+     * Requires an event to be currently processing.
+     */
+    stopPropagation: () => void;
+}
+/**
+ * Minimal kernel interface required by ListenerContext.
+ * Prevents circular dependencies between ListenerContext and Kernel.
+ */
+interface ListenerContextKernel {
+    off(eventName: string, listener: Function): void;
+    emit<T = any>(eventName: string, data?: T): Promise<void>;
+}
+
+/**
+ * Composition types for QuarKernel v2
+ *
+ * Types for composite events, context merging strategies, and conflict detection.
+ */
+/**
+ * Name of a source event in a composition
+ *
+ * When composing events like `compose(['user:loaded', 'profile:loaded'], 'app:ready')`,
+ * the event names 'user:loaded' and 'profile:loaded' are used as keys to merge their contexts.
+ */
+type EventName$1 = string;
+/**
+ * Result of a context merge operation
+ */
+interface MergeResult {
+    /** The merged context object */
+    context: Record<string, any>;
+    /** Array of detected conflicts during merge */
+    conflicts: ConflictInfo[];
+}
+/**
+ * Context merger strategy interface
+ *
+ * Implementations define how to merge contexts from multiple source events
+ * when creating a composite event.
+ */
+interface ContextMerger$1 {
+    /**
+     * Merge contexts from multiple source events
+     *
+     * @param contexts - Map of source event names to their event context objects
+     * @param sources - Array of source event names in order of emission
+     * @returns Merged context object for the composite event
+     */
+    merge(contexts: Map<EventName$1, Record<string, any>>, sources: EventName$1[]): Record<string, any>;
+    /**
+     * Merge contexts and detect conflicts
+     *
+     * @param contexts - Map of source event names to their event context objects
+     * @param sources - Array of source event names in order of emission
+     * @returns MergeResult with merged context and detected conflicts
+     */
+    mergeWithConflicts(contexts: Map<EventName$1, Record<string, any>>, sources: EventName$1[]): MergeResult;
+}
+/**
+ * Information about a context key conflict during merge
+ */
+interface ConflictInfo {
+    /** The context key that has conflicting values */
+    key: string;
+    /** Source event names that provided values for this key */
+    sources: EventName$1[];
+    /** The actual values from each source (in same order as sources) */
+    values: any[];
+}
+/**
+ * Options for creating a composition
+ */
+interface CompositionOptions$1 {
+    /**
+     * Context merger strategy to use
+     * @default NamespacedMerger
+     */
+    merger?: ContextMerger$1;
+    /**
+     * Maximum number of events to buffer per source event
+     * @default 100
+     */
+    bufferLimit?: number;
+    /**
+     * Whether to reset the buffer after emitting composite event
+     * @default true
+     */
+    reset?: boolean;
+    /**
+     * Callback for context conflicts (debug mode)
+     */
+    onConflict?: (conflict: ConflictInfo) => void;
+    /**
+     * Global time-to-live for buffered events in milliseconds.
+     * Events older than this will be considered expired and won't count
+     * toward composition readiness.
+     *
+     * @default 0 (no expiration - events stay in buffer indefinitely)
+     *
+     * @example
+     * ```ts
+     * // All events expire after 5 seconds
+     * const composition = new Composition(kernels, { eventTTL: 5000 });
+     * ```
+     */
+    eventTTL?: number;
+    /**
+     * Per-event TTL configuration. Overrides global eventTTL for specific events.
+     *
+     * Values can be:
+     * - `0` or `'permanent'`: Event stays in buffer indefinitely (default)
+     * - `number > 0`: Event expires after N milliseconds
+     * - `'instant'`: Event only triggers if it completes a composition immediately,
+     *   otherwise it's discarded (doesn't wait in buffer)
+     *
+     * @example
+     * ```ts
+     * const composition = new Composition(kernels, {
+     *   eventTTLs: {
+     *     'user:click': 'permanent',     // Waits indefinitely
+     *     'mouse:move': 100,             // Expires after 100ms
+     *     'key:press': 'instant'         // Must complete composition now or discard
+     *   }
+     * });
+     * ```
+     */
+    eventTTLs?: Record<EventName$1, number | 'permanent' | 'instant'>;
+}
+
+/**
+ * Type definitions for QuarKernel v2
+ *
+ * This module contains all TypeScript types, interfaces, and type guards
+ * for the event kernel. Uses strict typing with generic parameters for
+ * type-safe event handling.
+ */
+/**
+ * Event name type - can be string or branded type
+ */
+type EventName = string;
+/**
+ * Event data type - the payload for each event
+ * Can be any JSON-serializable value or undefined
+ */
+type EventData = any;
+/**
+ * Type map for events - maps event names to their data types
+ * @example
+ * ```ts
+ * interface Events {
+ *   'user:login': { userId: string }
+ *   'user:logout': { userId: string }
+ *   'app:ready': undefined
+ * }
+ * ```
+ */
+type EventMap = Record<EventName, EventData>;
+/**
+ * Event object passed to listeners
+ * @template T - The event data type
+ *
+ * Note: The actual implementation is in kernel-event.ts
+ * This interface is for type checking only
+ */
+interface IKernelEvent<T = any> {
+    /** Event name */
+    readonly name: string;
+    /** Event payload (typed, immutable) */
+    readonly data: T;
+    /** Shared mutable context - passed through listener chain */
+    readonly context: Record<string, any>;
+    /** Timestamp when event was created */
+    readonly timestamp: number;
+    /** Stop propagation to remaining listeners */
+    stopPropagation(): void;
+    /** Whether propagation was stopped */
+    readonly isPropagationStopped: boolean;
+}
+/**
+ * Listener context - utilities available to each listener
+ */
+interface IListenerContext {
+    /** Unique identifier of this listener */
+    id: string;
+    /** Remove this listener */
+    off(): void;
+    /** Emit another event */
+    emit<K extends string = string>(event: K, data?: any): Promise<void>;
+    /** Stop propagation to remaining listeners */
+    stopPropagation(): void;
+}
+/**
+ * Listener function signature
+ * @template T - The event data type
+ */
+type ListenerFunction<T = any> = (event: IKernelEvent<T>, context: IListenerContext) => void | Promise<void>;
+/**
+ * Predicate function for conditional once listeners
+ *
+ * IMPORTANT: Evaluated AFTER listener execution, not before.
+ * The event parameter contains the final state after the listener has run.
+ *
+ * @template T - The event data type
+ * @param event - Event with post-execution state (includes listener modifications to context)
+ * @returns true to remove the listener, false to keep it for next emission
+ */
+type PredicateFunction<T = any> = (event: IKernelEvent<T>) => boolean;
+/**
+ * Options for registering a listener
+ */
+interface ListenerOptions {
+    /** Unique identifier for dependency resolution */
+    id?: string;
+    /** Dependencies - listener IDs that must execute before this one */
+    after?: string | string[];
+    /** Priority - higher values execute earlier (within same dependency level) */
+    priority?: number;
+    /**
+     * Listen only once - true for always, or predicate function for conditional removal
+     *
+     * IMPORTANT: The predicate is evaluated AFTER listener execution, not before.
+     * This means:
+     * - The listener always executes at least once
+     * - The predicate receives the event object after the listener has run
+     * - The predicate sees any modifications to event.context made by the listener
+     * - If the listener throws an error, the predicate still evaluates (with errorBoundary: true)
+     * - The listener is removed after execution if predicate returns true
+     *
+     * @example
+     * ```ts
+     * // Listener always executes, then removed after execution
+     * kernel.on('event', handler, { once: true });
+     *
+     * // Listener executes each time, removed after count reaches 3
+     * kernel.on('event', handler, {
+     *   once: (event) => event.context.count >= 3
+     * });
+     * ```
+     */
+    once?: boolean | PredicateFunction;
+    /** AbortSignal for cleanup */
+    signal?: AbortSignal;
+}
+/**
+ * Internal listener entry stored in the kernel
+ * @internal
+ */
+interface ListenerEntry {
+    /** Unique identifier */
+    id: string;
+    /** The listener function */
+    callback: ListenerFunction;
+    /** Dependencies (listener IDs) */
+    after: string[];
+    /** Priority for ordering */
+    priority: number;
+    /** Listen only once - true for always, or predicate function evaluated after execution */
+    once: boolean | PredicateFunction;
+    /** Original listener function reference (for off()) */
+    original: ListenerFunction;
+    /** AbortSignal for cleanup */
+    signal?: AbortSignal;
+    /** Abort event listener reference for cleanup */
+    abortListener?: () => void;
+}
+/**
+ * Options for creating a kernel instance
+ */
+interface KernelOptions {
+    /** Event name delimiter for namespacing (default: ':') */
+    delimiter?: string;
+    /** Enable wildcard pattern matching (default: true) */
+    wildcard?: boolean;
+    /** Maximum listeners per event (default: Infinity, 0 = unlimited) */
+    maxListeners?: number;
+    /** Error handler for listener exceptions */
+    onError?: (error: Error, event: IKernelEvent) => void;
+    /** Debug mode - enables warnings and logging */
+    debug?: boolean;
+    /** Error boundary - continue executing listeners even if one fails */
+    errorBoundary?: boolean;
+    /** Default context merger for composite events */
+    contextMerger?: ContextMerger | ContextMergerFunction;
+    /** Callback when context keys conflict during merge */
+    onContextConflict?: (key: string, values: any[]) => void;
+}
+/**
+ * Event stack for composition - maps event names to their event objects
+ */
+type EventStack = Record<string, IKernelEvent>;
+/**
+ * Factory function to create composite event from source events
+ * @param stack - Map of event names to their event objects
+ * @returns The composite event specification (type and data)
+ */
+type CompositionFactory = (stack: EventStack) => {
+    type: string;
+    data: any;
+} | null;
+/**
+ * Options for event composition
+ */
+interface CompositionOptions {
+    /** Reset buffer after composition fires (default: true) */
+    reset?: boolean;
+    /** Context merger for this composition (overrides kernel default) */
+    contextMerger?: ContextMerger | ContextMergerFunction;
+}
+/**
+ * Internal composition entry
+ * @internal
+ */
+interface IComposition {
+    /** Event names to compose */
+    events: string[];
+    /** Buffer of received events */
+    buffer: Map<string, IKernelEvent>;
+    /** Factory to create composite event */
+    factory: CompositionFactory;
+    /** Reset buffer after firing */
+    reset: boolean;
+    /** Context merger */
+    merger: ContextMerger;
+}
+/**
+ * Strategy pattern for merging event contexts in compositions
+ */
+interface ContextMerger {
+    /**
+     * Merge contexts from multiple events
+     * @param contexts - Map of event names to their context objects
+     * @returns The merged context
+     */
+    merge(contexts: Record<string, any>): any;
+}
+/**
+ * Function-based context merger (shorthand for ContextMerger interface)
+ */
+type ContextMergerFunction = (contexts: Record<string, any>) => any;
+/**
+ * Main kernel interface
+ * @template Events - Event map defining event names and their data types
+ */
+interface IKernel<Events extends EventMap = EventMap> {
+    on<K extends keyof Events>(event: K | K[], listener: ListenerFunction<Events[K]>, options?: ListenerOptions): () => void;
+    once<K extends keyof Events>(event: K, listener: ListenerFunction<Events[K]>, options?: Omit<ListenerOptions, 'once'>): () => void;
+    once<K extends keyof Events>(event: K, predicate: PredicateFunction<Events[K]>, listener: ListenerFunction<Events[K]>, options?: Omit<ListenerOptions, 'once'>): () => void;
+    once<K extends keyof Events>(event: K): Promise<IKernelEvent<Events[K]>>;
+    off<K extends keyof Events>(event: K, listener?: ListenerFunction<Events[K]>): void;
+    offAll(event?: keyof Events): void;
+    emit<K extends keyof Events>(event: K, data?: Events[K]): Promise<void>;
+    emitSerial<K extends keyof Events>(event: K, data?: Events[K]): Promise<void>;
+    compose(events: string[], factory: CompositionFactory, options?: CompositionOptions): () => void;
+    events<K extends keyof Events>(event: K): AsyncIterable<IKernelEvent<Events[K]>>;
+    listenerCount(event?: keyof Events): number;
+    eventNames(): (keyof Events)[];
+    debug(enabled: boolean): void;
+}
+/**
+ * Type guard to check if value is a valid event name
+ */
+declare function isEventName(value: unknown): value is EventName;
+/**
+ * Type guard to check if value is a listener function
+ */
+declare function isListenerFunction(value: unknown): value is ListenerFunction;
+/**
+ * Type guard to check if value is a predicate function
+ */
+declare function isPredicateFunction(value: unknown): value is PredicateFunction;
+/**
+ * Type guard to check if value is a context merger
+ */
+declare function isContextMerger(value: unknown): value is ContextMerger;
+/**
+ * Type guard to check if value is a context merger function
+ */
+declare function isContextMergerFunction(value: unknown): value is ContextMergerFunction;
+/**
+ * Type guard to check if value is ListenerOptions
+ */
+declare function isListenerOptions(value: unknown): value is ListenerOptions;
+/**
+ * Type guard to check if value is IKernelEvent
+ */
+declare function isKernelEvent<T = any>(value: unknown): value is IKernelEvent<T>;
+/**
+ * Extract event names from an EventMap
+ */
+type EventNames<E extends EventMap> = keyof E;
+/**
+ * Extract event data type for a specific event
+ */
+type EventDataType<E extends EventMap, K extends keyof E> = E[K];
+/**
+ * Unbind function returned by on() and once()
+ */
+type UnbindFunction = () => void;
+/**
+ * Error thrown when circular dependencies are detected
+ */
+declare class CircularDependencyError extends Error {
+    constructor(cycle: string[]);
+}
+/**
+ * Error thrown when a listener dependency is missing
+ */
+declare class MissingDependencyError extends Error {
+    constructor(listenerId: string, missingDep: string);
+}
+/**
+ * Error thrown when max listeners exceeded
+ */
+declare class MaxListenersExceededError extends Error {
+    constructor(event: string, max: number);
+}
+
+/**
+ * Composition class - Merges multiple kernels into a unified interface
+ *
+ * Subscribes to events from multiple kernels, buffers them, and emits
+ * composite events when all source events have fired. Contexts are merged
+ * using a configurable ContextMerger strategy.
+ */
+
+/**
+ * Buffered event entry for a source kernel
+ */
+interface BufferedEvent {
+    name: string;
+    data: any;
+    context: Record<string, any>;
+    timestamp: number;
+}
+/**
+ * Composition class that merges events from multiple kernels
+ *
+ * Example:
+ * ```ts
+ * const userKernel = createKernel();
+ * const profileKernel = createKernel();
+ *
+ * const composition = new Composition([
+ *   [userKernel, 'user:loaded'],
+ *   [profileKernel, 'profile:loaded'],
+ * ], {
+ *   merger: createNamespacedMerger(),
+ *   bufferLimit: 100,
+ * });
+ *
+ * composition.onComposed((event) => {
+ *   // event.data.merged contains merged contexts from all sources
+ * });
+ * ```
+ */
+declare class Composition<Events extends EventMap = EventMap> {
+    private kernel;
+    private subscriptions;
+    private buffers;
+    private merger;
+    private bufferLimit;
+    private reset;
+    private eventTTL;
+    private eventTTLs;
+    private sourceEvents;
+    private firedSinceLastComposite;
+    private lastConflicts;
+    private expirationTimers;
+    /**
+     * Create a new Composition
+     *
+     * @param kernels - Array of [kernel, eventName] tuples to subscribe to
+     * @param options - Composition options
+     */
+    constructor(kernels: Array<[Kernel, EventName$1]>, options?: CompositionOptions$1);
+    /**
+     * Subscribe to events from a source kernel
+     */
+    private subscribeToKernel;
+    /**
+     * Get the effective TTL for a specific event
+     * Priority: per-event TTL > global TTL > 0 (permanent)
+     */
+    private getEffectiveTTL;
+    /**
+     * Handle an event from a source kernel
+     */
+    private handleSourceEvent;
+    /**
+     * Expire an event from the buffer based on timestamp
+     */
+    private expireEvent;
+    /**
+     * Check if all source events have fired and emit composite event
+     * @returns true if composite was emitted, false otherwise
+     */
+    private checkAndEmitComposite;
+    /**
+     * 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: ListenerFunction<Events[keyof Events]>, options?: ListenerOptions): () => void;
+    /**
+     * Remove a listener for composed events
+     */
+    offComposed(listener?: Function): void;
+    /**
+     * Get number of composed event listeners
+     */
+    composedListenerCount(): number;
+    /**
+     * Register a listener for events on internal kernel
+     * Note: Use onComposed() to listen for composition completion
+     */
+    on<K extends keyof Events>(eventName: K, listener: ListenerFunction<Events[K]>, options?: ListenerOptions): () => void;
+    /**
+     * Remove a listener
+     * Delegates to internal kernel
+     */
+    off(eventName: string, listener?: Function): void;
+    /**
+     * Emit an event through the composition
+     * Note: Reserved internal events (prefixed with __qk:) cannot be emitted
+     */
+    emit<K extends keyof Events>(eventName: K, data?: Events[K]): Promise<void>;
+    /**
+     * Get merged context from latest buffered events
+     * Does not emit - just returns the merged context
+     */
+    getContext(): Record<string, any> | null;
+    /**
+     * Get number of listeners for an event
+     */
+    listenerCount(eventName?: keyof Events): number;
+    /**
+     * Get all event names with registered listeners
+     */
+    eventNames(): (keyof Events)[];
+    /**
+     * Remove all listeners
+     */
+    offAll(eventName?: keyof Events): void;
+    /**
+     * Enable/disable debug mode
+     */
+    debug(enabled: boolean): void;
+    /**
+     * Get buffer for a specific source event (for debugging)
+     */
+    getBuffer(eventName: EventName$1): ReadonlyArray<BufferedEvent> | undefined;
+    /**
+     * Clear all buffers
+     */
+    clearBuffers(): void;
+    /**
+     * 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(): ReadonlyArray<ConflictInfo>;
+    /**
+     * Cleanup all subscriptions and listeners
+     */
+    dispose(): void;
+    /**
+     * Get the configured global event TTL in milliseconds
+     * @returns The TTL value, or 0 if no TTL is configured
+     */
+    getEventTTL(): number;
+    /**
+     * Set the global event TTL in milliseconds
+     * @param ttl - TTL in milliseconds (0 = permanent)
+     */
+    setEventTTL(ttl: number): void;
+    /**
+     * Get per-event TTL configuration
+     * @returns The eventTTLs configuration object
+     */
+    getEventTTLs(): Readonly<Record<EventName$1, number | 'permanent' | 'instant'>>;
+    /**
+     * Set TTL for a specific event
+     * @param eventName - The event name to configure
+     * @param ttl - TTL value: number (ms), 'permanent', or 'instant'
+     */
+    setEventTTLFor(eventName: EventName$1, ttl: number | 'permanent' | 'instant'): void;
+    /**
+     * Remove per-event TTL configuration (falls back to global TTL)
+     * @param eventName - The event name to reset
+     */
+    clearEventTTLFor(eventName: EventName$1): void;
+}
+/**
+ * Factory function to create a Composition instance
+ */
+declare const createComposition: <Events extends EventMap = EventMap>(kernels: Array<[Kernel, EventName$1]>, options?: CompositionOptions$1) => Composition<Events>;
+
+/**
+ * QuarKernel Core Implementation
+ *
+ * A TypeScript event kernel with:
+ * - Priority-based listener ordering
+ * - Shared context between listeners
+ * - Async-first with Promise-based API
+ * - Arrow functions only (no `this` binding)
+ */
+
+/**
+ * Error collected during event execution
+ */
+interface ExecutionError {
+    listenerId: string;
+    error: Error;
+    timestamp: number;
+    eventName: string;
+}
+/**
+ * Core Kernel class
+ * Implements basic on(), off(), emit() with Map-based storage
+ */
+declare class Kernel<Events extends EventMap = EventMap> implements ListenerContextKernel {
+    private listeners;
+    private options;
+    private listenerIdCounter;
+    private executionErrors;
+    constructor(options?: KernelOptions);
+    /**
+     * Register an event listener
+     * Returns an unbind function for cleanup
+     */
+    on<K extends keyof Events>(eventName: K, listener: ListenerFunction<Events[K]>, options?: ListenerOptions): () => void;
+    /**
+     * Remove an event listener
+     * If no listener provided, removes all listeners for the event
+     */
+    off(eventName: string, listener?: Function): void;
+    /**
+     * 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
+     */
+    emit<K extends keyof Events>(eventName: K, data?: Events[K]): Promise<void>;
+    /**
+     * 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
+     */
+    emitSerial<K extends keyof Events>(eventName: K, data?: Events[K]): Promise<void>;
+    /**
+     * Sort listeners by dependencies and priority
+     * Uses topological sort for dependency resolution
+     */
+    private sortListenersByDependencies;
+    /**
+     * Execute a single listener with error handling
+     */
+    private executeListener;
+    /**
+     * 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
+     */
+    private removeOnceListeners;
+    /**
+     * Get number of listeners for an event
+     */
+    listenerCount(eventName?: keyof Events): number;
+    /**
+     * Get all event names with registered listeners
+     */
+    eventNames(): (keyof Events)[];
+    /**
+     * Remove all listeners for all events (or specific event)
+     */
+    offAll(eventName?: keyof Events): void;
+    /**
+     * Enable/disable debug mode
+     * In T115, this is a placeholder - full debug implementation in T129
+     */
+    debug(enabled: boolean): void;
+    /**
+     * Get collected execution errors from the last emit
+     * Useful for error aggregation and reporting
+     */
+    getExecutionErrors(): ReadonlyArray<ExecutionError>;
+    /**
+     * Clear collected execution errors
+     */
+    clearExecutionErrors(): void;
+    /**
+     * 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<Events extends EventMap = EventMap>(...args: (readonly [Kernel, EventName$1] | CompositionOptions$1)[]): Composition<Events>;
+}
+/**
+ * Factory function to create a Kernel instance
+ */
+declare const createKernel: <Events extends EventMap = EventMap>(options?: KernelOptions) => Kernel<Events>;
+
+/**
+ * FSM Machine Implementation
+ *
+ * Flexible state machine layer built on quarkernel events.
+ * Uses prefixed events for loose coupling and multi-machine orchestration.
+ */
+
+/**
+ * Create a state machine on a kernel
+ *
+ * @param kernel - The quarkernel instance to use
+ * @param config - Machine configuration
+ * @returns Machine instance
+ *
+ * @example
+ * ```ts
+ * const kernel = new Kernel();
+ *
+ * const order = useMachine(kernel, {
+ *   prefix: 'order',
+ *   initial: 'draft',
+ *   states: {
+ *     draft: { on: { SUBMIT: 'pending' } },
+ *     pending: { on: { APPROVE: 'confirmed', REJECT: 'draft' } },
+ *     confirmed: { on: { SHIP: 'shipped' } },
+ *     shipped: {}
+ *   }
+ * });
+ *
+ * // Listen to state changes
+ * kernel.on('order:enter:confirmed', (e) => {
+ *   console.log('Order confirmed!');
+ * });
+ *
+ * await order.send('SUBMIT');
+ * await order.send('APPROVE');
+ * ```
+ */
+declare function useMachine<TContext = Record<string, any>>(kernel: Kernel, config: MachineConfig<TContext>): Machine<TContext>;
+/**
+ * Type helper for defining typed machine configs
+ */
+declare function defineMachine<TContext = Record<string, any>>(config: Omit<MachineConfig<TContext>, 'prefix'>): Omit<MachineConfig<TContext>, 'prefix'>;
+
+export { isListenerOptions as A, isKernelEvent as B, type ContextMerger$1 as C, CircularDependencyError as D, type EventName$1 as E, MaxListenersExceededError as F, useMachine as G, defineMachine as H, type IKernelEvent as I, KernelEvent as K, ListenerContext as L, MissingDependencyError as M, type PredicateFunction as P, type UnbindFunction as U, Kernel as a, Composition as b, createKernel as c, createComposition as d, type ConflictInfo as e, type CompositionOptions$1 as f, type EventName as g, type EventData as h, type EventMap as i, type IKernel as j, type IListenerContext as k, type ListenerFunction as l, type ListenerOptions as m, type ListenerEntry as n, type KernelOptions as o, type EventStack as p, type CompositionFactory as q, type IComposition as r, type ContextMergerFunction as s, type EventNames as t, type EventDataType as u, isEventName as v, isListenerFunction as w, isPredicateFunction as x, isContextMerger as y, isContextMergerFunction as z };