@maxdrellin/xenocline 0.0.2 → 0.0.4

package/dist/xenocline.cjs

@@ -0,0 +1,1299 @@
+'use strict';
+
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const clean = (obj)=>{
+    return Object.fromEntries(Object.entries(obj).filter(([_, v])=>v !== undefined));
+};
+
+const DEFAULT_AGGREGATOR_OPTIONS = {
+    aggregate: async (input)=>{
+        return {
+            status: 'Ready',
+            output: input
+        };
+    }
+};
+const createAggregator = (name, options)=>{
+    let aggregatorOptions = {
+        ...DEFAULT_AGGREGATOR_OPTIONS
+    };
+    if (options) {
+        aggregatorOptions = {
+            ...aggregatorOptions,
+            ...clean(options)
+        };
+    }
+    return {
+        name,
+        aggregate: aggregatorOptions.aggregate
+    };
+};
+const isAggregator = (obj)=>{
+    return obj !== undefined && obj !== null && typeof obj === 'object' && typeof obj.name === 'string' && typeof obj.aggregate === 'function';
+};
+
+const createEvent = (type, sourceId, stage, data)=>{
+    return {
+        date: new Date(),
+        type,
+        stage,
+        sourceId,
+        data
+    };
+};
+
+function createAggregatorEvent(sourceId, stage, aggregator, data) {
+    const event = createEvent('aggregator', sourceId, stage, data);
+    return {
+        ...event,
+        aggregator
+    };
+}
+function isAggregatorEvent(event) {
+    if (event === null || event === undefined || typeof event !== 'object') {
+        return false;
+    }
+    const hasRequiredProperties = event.type === 'aggregator' && 'stage' in event && 'aggregator' in event && typeof event.aggregator === 'object' && event.aggregator !== null && 'name' in event.aggregator;
+    if (!hasRequiredProperties) {
+        return false;
+    }
+    const aggregatorEvent = event;
+    const isValidStage = [
+        'start',
+        'aggregate',
+        'ready',
+        'defer'
+    ].includes(aggregatorEvent.stage);
+    return isValidStage;
+}
+
+const createTransition = (type, id)=>{
+    return {
+        id,
+        type
+    };
+};
+const isTransition = (item)=>{
+    return item !== null && typeof item === 'object' && typeof item.id === 'string' && (item.type === 'connection' || item.type === 'decision' || item.type === 'termination' || item.type === 'beginning');
+};
+const validateTransition = (item, coordinates)=>{
+    const errors = [];
+    const currentCoordinates = [
+        ...coordinates || [],
+        'Transition'
+    ];
+    if (item === undefined || item === null) {
+        errors.push({
+            coordinates: [
+                ...currentCoordinates
+            ],
+            error: 'Transition is undefined or null.'
+        });
+        return errors;
+    }
+    if (typeof item !== 'object') {
+        errors.push({
+            coordinates: [
+                ...currentCoordinates
+            ],
+            error: 'Transition is not an object.'
+        });
+        return errors;
+    }
+    if (item.id === undefined || typeof item.id !== 'string') {
+        errors.push({
+            coordinates: [
+                ...currentCoordinates
+            ],
+            error: 'Transition id is undefined or not a string.'
+        });
+    }
+    if (item.type === undefined || typeof item.type !== 'string') {
+        errors.push({
+            coordinates: [
+                ...currentCoordinates
+            ],
+            error: 'Transition type is undefined or not a string.'
+        });
+    }
+    if (item.type !== 'connection' && item.type !== 'decision' && item.type !== 'termination' && item.type !== 'beginning') {
+        errors.push({
+            coordinates: [
+                ...currentCoordinates
+            ],
+            error: 'Transition type is not a valid type.'
+        });
+    }
+    // We have an id, push to current coordinates
+    currentCoordinates.push(`Transition: ${item.id}`);
+    if (item.type === undefined || typeof item.type !== 'string') {
+        errors.push({
+            coordinates: [
+                ...currentCoordinates
+            ],
+            error: 'Transition type is undefined or not a string.'
+        });
+    }
+    return errors;
+};
+
+// NEW: Termination type extending Transition
+const createTermination = (id, options)=>{
+    const defaultOptions = {
+        terminate: async (output)=>{
+            return output;
+        }
+    };
+    let terminationOptions = {
+        ...defaultOptions
+    };
+    if (options) {
+        terminationOptions = {
+            ...terminationOptions,
+            ...clean(options)
+        };
+    }
+    return {
+        ...createTransition('termination', id),
+        terminate: terminationOptions.terminate
+    };
+};
+const isTermination = (item)=>{
+    return isTransition(item) && item.type === 'termination' && (item.terminate === undefined || typeof item.terminate === 'function');
+};
+const validateTermination = (item, coordinates)=>{
+    const errors = [];
+    const currentCoordinates = [
+        ...coordinates || [],
+        'Termination'
+    ];
+    errors.push(...validateTransition(item, currentCoordinates));
+    if (errors.length === 0) {
+        currentCoordinates.push(`Termination: ${item.id}`);
+        if (item.terminate !== undefined && typeof item.terminate !== 'function') {
+            errors.push({
+                coordinates: [
+                    ...currentCoordinates
+                ],
+                error: 'terminate is not a function.'
+            });
+        }
+    }
+    return errors;
+};
+
+const DEFAULT_CONNECTION_OPTIONS = {
+    transform: async (output, context)=>{
+        return [
+            output,
+            context
+        ];
+    }
+};
+const createConnection = (id, targetNodeId, options)=>{
+    let connectionOptions = {
+        ...DEFAULT_CONNECTION_OPTIONS
+    };
+    if (options) {
+        connectionOptions = {
+            ...connectionOptions,
+            ...clean(options)
+        };
+    }
+    return {
+        ...createTransition('connection', id),
+        targetNodeId,
+        transform: connectionOptions.transform
+    };
+};
+const isConnection = (item)=>{
+    return isTransition(item) && item.type === 'connection' && item.targetNodeId !== undefined;
+};
+const validateConnection = (item, coordinates)=>{
+    const errors = [];
+    const connectionBaseCoordinates = [
+        ...coordinates || [],
+        'Connection'
+    ];
+    errors.push(...validateTransition(item, coordinates));
+    if (errors.length === 0) {
+        if (item && typeof item === 'object') {
+            const connectionSpecificErrorPath = [
+                ...connectionBaseCoordinates,
+                `Connection: ${item.id}`
+            ];
+            if (item.type === 'connection') {
+                if (typeof item.targetNodeId !== 'string') {
+                    errors.push({
+                        coordinates: connectionSpecificErrorPath,
+                        error: 'Property "targetNodeId" must be a string when type is "connection".'
+                    });
+                }
+                // transform is optional, but if present, must be a function.
+                if (item.transform !== undefined && typeof item.transform !== 'function') {
+                    errors.push({
+                        coordinates: connectionSpecificErrorPath,
+                        error: 'Optional property "transform" must be a function if present.'
+                    });
+                }
+            } else {
+                // If type is not 'connection', but these properties exist and are malformed.
+                // This primarily helps catch if a non-connection object has these fields incorrectly defined.
+                if (item.targetNodeId !== undefined && typeof item.targetNodeId !== 'string') {
+                    errors.push({
+                        coordinates: connectionSpecificErrorPath,
+                        error: 'Property "targetNodeId" is present but is not a string.'
+                    });
+                }
+                if (item.transform !== undefined && typeof item.transform !== 'function') {
+                    errors.push({
+                        coordinates: connectionSpecificErrorPath,
+                        error: 'Property "transform" is present but is not a function.'
+                    });
+                }
+            }
+        }
+    }
+    return errors;
+};
+
+const createDecision = (id, decide)=>{
+    return {
+        ...createTransition('decision', id),
+        decide
+    };
+};
+const isDecision = (item)=>{
+    return isTransition(item) && item.type === 'decision' && typeof item.decide === 'function';
+};
+const validateDecision = (item, coordinates)=>{
+    const errors = [];
+    const decisionBaseCoordinates = [
+        ...coordinates || [],
+        'Decision'
+    ];
+    errors.push(...validateTransition(item, coordinates));
+    if (errors.length === 0) {
+        if (item && typeof item === 'object') {
+            const decisionSpecificErrorPath = [
+                ...decisionBaseCoordinates,
+                `Decision: ${item.id}`
+            ];
+            if (item.type === 'decision') {
+                if (typeof item.decide !== 'function') {
+                    errors.push({
+                        coordinates: decisionSpecificErrorPath,
+                        error: 'Property "decide" must be a function when type is "decision".'
+                    });
+                }
+            } else {
+                // If type is not 'decision', but 'decide' property exists and is malformed.
+                if (item.decide !== undefined && typeof item.decide !== 'function') {
+                    errors.push({
+                        coordinates: decisionSpecificErrorPath,
+                        error: 'Property "decide" is present but is not a function.'
+                    });
+                }
+            }
+        }
+    }
+    return errors;
+};
+
+const isNext = (item)=>{
+    if (isTermination(item)) {
+        return true;
+    }
+    if (!Array.isArray(item)) {
+        return false;
+    }
+    if (item.length === 0) {
+        return true;
+    }
+    const firstElement = item[0];
+    if (isConnection(firstElement)) {
+        return item.every((el)=>isConnection(el));
+    }
+    if (isDecision(firstElement)) {
+        return item.every((el)=>isDecision(el));
+    }
+    return false;
+};
+const validateDecisionOrConnectionArray = (item, coordinates)=>{
+    const errors = [];
+    const currentCoordinates = [
+        ...coordinates || []
+    ];
+    if (item.length === 0) {
+        errors.push({
+            coordinates: [
+                ...currentCoordinates
+            ],
+            error: 'Next Array is empty.'
+        });
+        return errors;
+    }
+    const firstElement = item[0];
+    if (isConnection(firstElement)) {
+        for (const element of item){
+            errors.push(...validateConnection(element, currentCoordinates));
+        }
+    } else if (isDecision(firstElement)) {
+        for (const element of item){
+            errors.push(...validateDecision(element, currentCoordinates));
+        }
+    } else {
+        errors.push({
+            coordinates: [
+                ...currentCoordinates
+            ],
+            error: 'Next Array contains invalid element types. Expected all Connections or all Decisions.'
+        });
+    }
+    return errors;
+};
+const validateNext = (item, coordinates)=>{
+    const errors = [];
+    const currentCoordinates = [
+        ...coordinates || [],
+        'Next'
+    ];
+    if (item === undefined || item === null) {
+        errors.push({
+            coordinates: [
+                ...currentCoordinates
+            ],
+            error: 'Next is undefined or null.'
+        });
+        return errors;
+    }
+    if (Array.isArray(item)) {
+        errors.push(...validateDecisionOrConnectionArray(item, currentCoordinates));
+    } else {
+        errors.push(...validateTermination(item, currentCoordinates));
+    }
+    return errors;
+};
+
+const DEFAULT_NODE_OPTIONS = {};
+const createNode = (type, id, options)=>{
+    let nodeOptions = {
+        ...DEFAULT_NODE_OPTIONS
+    };
+    if (options) {
+        nodeOptions = {
+            ...nodeOptions,
+            ...clean(options)
+        };
+    }
+    return {
+        id,
+        type,
+        next: nodeOptions.next
+    };
+};
+const isNode = (item)=>{
+    return item !== null && typeof item === 'object' && typeof item.id === 'string' && (item.type === 'aggregator' || item.type === 'phase') && (item.next === undefined || isNext(item.next));
+};
+const validateNode = (item, coordinates)=>{
+    const errors = [];
+    const currentCoordinates = [
+        ...coordinates || [],
+        'Node'
+    ];
+    if (item === undefined || item === null) {
+        errors.push({
+            coordinates: [
+                ...currentCoordinates
+            ],
+            error: 'Node is undefined or null.'
+        });
+        return errors;
+    }
+    if (typeof item !== 'object') {
+        errors.push({
+            coordinates: [
+                ...currentCoordinates
+            ],
+            error: 'Node is not an object.'
+        });
+        return errors;
+    }
+    if (item.id === undefined || typeof item.id !== 'string') {
+        errors.push({
+            coordinates: [
+                ...currentCoordinates
+            ],
+            error: 'Node id is undefined or not a string.'
+        });
+    }
+    if (item.type === undefined || typeof item.type !== 'string') {
+        errors.push({
+            coordinates: [
+                ...currentCoordinates
+            ],
+            error: 'Node type is undefined or not a string.'
+        });
+    }
+    if (item.type !== 'aggregator' && item.type !== 'phase') {
+        errors.push({
+            coordinates: [
+                ...currentCoordinates
+            ],
+            error: 'Node type is not a valid type.'
+        });
+    }
+    currentCoordinates.push(`Node: ${item.id}`);
+    if (item.next !== undefined) {
+        errors.push(...validateNext(item.next, currentCoordinates));
+    }
+    return errors;
+};
+
+const DEFAULT_AGGREGATOR_NODE_OPTIONS = {};
+const createAggregatorNode = (id, aggregator, options)=>{
+    let aggregatorNodeOptions = {
+        ...DEFAULT_AGGREGATOR_NODE_OPTIONS
+    };
+    if (options) {
+        aggregatorNodeOptions = {
+            ...aggregatorNodeOptions,
+            ...clean(options)
+        };
+    }
+    return {
+        ...createNode('aggregator', id, {
+            next: aggregatorNodeOptions.next
+        }),
+        aggregator
+    };
+};
+/**
+ * Type guard to check if an object is an AggregatorNode.
+ *
+ * @param obj - The object to check.
+ * @returns True if the object is an AggregatorNode, false otherwise.
+ */ const isAggregatorNode = (obj)=>{
+    if (!isNode(obj) || obj.type !== 'aggregator') {
+        return false;
+    }
+    // At this point, obj is a Node with type 'aggregator'.
+    // Now check for AggregatorNode specific properties.
+    const potentialAggNode = obj; // Cast to access specific props
+    if (!(typeof potentialAggNode.aggregator === 'object' && potentialAggNode.aggregator !== null && typeof potentialAggNode.aggregator.aggregate === 'function')) {
+        return false;
+    }
+    return true; // Not Termination and not a recognized array type for 'next'
+};
+
+// NEW: Termination type extending Transition
+const DEFAULT_BEGINNING_OPTIONS = {
+    begin: async (input)=>{
+        return input;
+    }
+};
+const createBeginning = (id, targetNodeId, options)=>{
+    let beginningOptions = {
+        ...DEFAULT_BEGINNING_OPTIONS
+    };
+    if (options) {
+        beginningOptions = {
+            ...beginningOptions,
+            ...clean(options)
+        };
+    }
+    return {
+        ...createTransition('beginning', id),
+        targetNodeId,
+        begin: beginningOptions.begin
+    };
+};
+const isBeginning = (item)=>{
+    return isTransition(item) && item.type === 'beginning' && (item.begin === undefined || typeof item.begin === 'function');
+};
+
+const createTransitionEvent = (sourceId, transitionType, stage, transition, data)=>{
+    const event = createEvent('transition', sourceId, stage, data);
+    return {
+        ...event,
+        transitionType,
+        transition
+    };
+};
+const createConnectionEvent = (sourceId, stage, transition, data)=>{
+    return createTransitionEvent(sourceId, 'connection', stage, transition, data);
+};
+const isConnectionEvent = (item)=>{
+    return typeof item === 'object' && item !== null && item.type === 'transition' && item.transitionType === 'connection' && typeof item.transitionType === 'string';
+};
+const createDecisionEvent = (sourceId, stage, transition, data)=>createTransitionEvent(sourceId, 'decision', stage, transition, data);
+const isDecisionEvent = (item)=>{
+    return typeof item === 'object' && item !== null && item.type === 'transition' && item.transitionType === 'decision' && typeof item.transitionType === 'string';
+};
+const createTerminationEvent = (sourceId, stage, transition, data)=>{
+    return createTransitionEvent(sourceId, 'termination', stage, transition, data);
+};
+const isTerminationEvent = (item)=>{
+    return typeof item === 'object' && item !== null && item.type === 'transition' && item.transitionType === 'termination' && typeof item.transitionType === 'string';
+};
+const createBeginningEvent = (sourceId, stage, transition, data)=>{
+    return createTransitionEvent(sourceId, 'beginning', stage, transition, data);
+};
+const isBeginningEvent = (item)=>{
+    return typeof item === 'object' && item !== null && item.type === 'transition' && item.transitionType === 'beginning' && typeof item.transitionType === 'string';
+};
+
+const createEventHandler = (handle)=>{
+    return {
+        handle
+    };
+};
+
+const createEventFilter = (type, stage)=>{
+    const filterFn = (event)=>{
+        const typeMatch = !type || type.includes(event.type);
+        const stageMatch = !stage || stage.includes(event.stage);
+        return typeMatch && stageMatch;
+    };
+    return {
+        type,
+        stage,
+        filter: filterFn
+    };
+};
+
+const createFilteredHandler = (filter, options)=>{
+    const handler = 'handler' in options ? options.handler : createEventHandler(options.handle);
+    const handle = async (event, context)=>{
+        if (filter.filter(event)) {
+            await handler.handle(event, context);
+        }
+    };
+    return {
+        filter,
+        handler,
+        handle
+    };
+};
+
+/**
+ * Creates an instance of EventState.
+ * @param handlers An optional array of event handlers to initialize the state with.
+ *                 These handlers should be of type `EventHandler<Event, C>`, meaning they
+ *                 are prepared to receive any event and filter internally if necessary.
+ * @returns A new, readonly EventState object.
+ */ const createEventState = (handlers)=>{
+    // Store a copy of the handlers array to ensure immutability of the provided array.
+    return {
+        handlers: handlers ? [
+            ...handlers
+        ] : []
+    };
+};
+/**
+ * Dispatches an event to all registered handlers.
+ * @param eventState The current event state containing the handlers.
+ * @param event The event to dispatch. This can be any specific event type that extends `Event`.
+ * @param context The current context to pass to the handlers.
+ */ const dispatchEvent = async (eventState, event, context)=>{
+    for (const handler of eventState.handlers){
+        // Each handler is EventHandler<Event, C>, so its `handle` method expects an `Event`.
+        // Since `E` extends `Event`, passing `event` (of type `E`) is type-safe.
+        await handler.handle(event, context);
+    }
+};
+
+const createNodeEvent = (sourceId, nodeType, stage, node, data)=>{
+    const event = createEvent('node', sourceId, stage, data);
+    return {
+        ...event,
+        nodeType,
+        node
+    };
+};
+const isNodeEvent = (item)=>{
+    return item !== null && item !== undefined && typeof item === 'object' && item.type === 'node' && item.node !== null && item.node !== undefined && item.stage !== null && item.stage !== undefined;
+};
+const createAggregatorNodeEvent = (sourceId, stage, aggregatorNode, data)=>createNodeEvent(sourceId, 'aggregator', stage, aggregatorNode, data);
+const isAggregatorNodeEvent = (item)=>{
+    return isNodeEvent(item) && item.nodeType === 'aggregator';
+};
+const createPhaseNodeEvent = (sourceId, stage, phaseNode, data)=>createNodeEvent(sourceId, 'phase', stage, phaseNode, data);
+const isPhaseNodeEvent = (item)=>{
+    return isNodeEvent(item) && item.nodeType === 'phase';
+};
+
+const createPhase = (name, options)=>{
+    const defaultOptions = {
+        execute: async (input)=>{
+            return input;
+        }
+    };
+    const phaseOptions = {
+        ...defaultOptions,
+        ...clean(options)
+    };
+    return {
+        name,
+        execute: phaseOptions.execute,
+        verify: phaseOptions.verify
+    };
+};
+const isPhase = (obj)=>{
+    return obj !== undefined && obj !== null && typeof obj === 'object' && typeof obj.name === 'string' && typeof obj.execute === 'function';
+};
+
+const DEFAULT_PHASE_NODE_OPTIONS = {};
+const createPhaseNode = (id, phase, options)=>{
+    let phaseNodeOptions = {
+        ...DEFAULT_PHASE_NODE_OPTIONS
+    };
+    if (options) {
+        phaseNodeOptions = {
+            ...phaseNodeOptions,
+            ...clean(options)
+        };
+    }
+    return {
+        ...createNode('phase', id, {
+            next: phaseNodeOptions.next
+        }),
+        phase,
+        prepare: phaseNodeOptions.prepare,
+        process: phaseNodeOptions.process
+    };
+};
+const isPhaseNode = (obj)=>{
+    if (!isNode(obj) || obj.type !== 'phase') {
+        return false;
+    }
+    const potentialPhaseNode = obj;
+    if (!(potentialPhaseNode.phase && typeof potentialPhaseNode.phase === 'object' && isPhase(potentialPhaseNode.phase))) {
+        return false;
+    }
+    return true;
+};
+
+//import * as ClassifyPhase from './phases/classify';
+// import * as TranscribePhase from './phases/transcribe';
+// import * as ComposePhase from './phases/compose';
+// import * as CompletePhase from './phases/complete';
+const createProcess = (name, options)=>{
+    const defaultOptions = {
+        phases: {}
+    };
+    const processOptions = {
+        ...defaultOptions,
+        ...clean(options)
+    };
+    // Removed: const eventState = createEventState<C>(processOptions.eventHandlers);
+    return {
+        name,
+        phases: processOptions.phases
+    };
+};
+const isProcess = (obj)=>{
+    return obj !== undefined && obj !== null && typeof obj === 'object' && typeof obj.name === 'string' && typeof obj.phases === 'object';
+};
+const validateProcess = (item, coordinates)=>{
+    const errors = [];
+    const currentCoordinates = [
+        ...[],
+        'Process'
+    ];
+    if (item === undefined || item === null) {
+        errors.push({
+            coordinates: [
+                ...currentCoordinates
+            ],
+            error: 'Process is undefined or null.'
+        });
+        return errors;
+    }
+    if (item.name === undefined || typeof item.name !== 'string') {
+        errors.push({
+            coordinates: [
+                ...currentCoordinates
+            ],
+            error: 'Process name is undefined or not a string.'
+        });
+    }
+    const processNameForPath = typeof item.name === 'string' ? item.name : 'UnnamedProcess';
+    const basePath = [
+        ...currentCoordinates,
+        `name:${processNameForPath}`
+    ];
+    if (item.phases === undefined || typeof item.phases !== 'object') {
+        errors.push({
+            coordinates: [
+                ...basePath,
+                'phases'
+            ],
+            error: 'Process phases is undefined or not an object.'
+        });
+    } else {
+        for(const phaseId in item.phases){
+            const node = item.phases[phaseId];
+            if (Object.prototype.hasOwnProperty.call(item.phases, phaseId)) {
+                errors.push(...validateNode(node, [
+                    ...basePath,
+                    'phases',
+                    phaseId
+                ]));
+            }
+        }
+        for(const phaseId in item.phases){
+            if (Object.prototype.hasOwnProperty.call(item.phases, phaseId)) {
+                const node = item.phases[phaseId];
+                if (node && typeof node === 'object' && node.next) {
+                    if (Array.isArray(node.next)) {
+                        const transitions = node.next;
+                        if (transitions.length > 0 && transitions.every((t)=>isConnection(t))) {
+                            transitions.forEach((connection, index)=>{
+                                if (connection && typeof connection.targetNodeId === 'string') {
+                                    if (!(connection.targetNodeId in item.phases)) {
+                                        errors.push({
+                                            coordinates: [
+                                                ...basePath,
+                                                'phases',
+                                                phaseId,
+                                                'next',
+                                                connection.id || `connection-at-index-${index}`
+                                            ],
+                                            error: `Node "${phaseId}" has a connection to non-existent targetNodeId "${connection.targetNodeId}".`
+                                        });
+                                    }
+                                } else if (!connection || connection.targetNodeId === undefined) ;
+                            });
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return errors;
+};
+
+const createProcessEvent = (sourceId, stage, process, data)=>{
+    const event = createEvent('process', sourceId, stage, data);
+    return {
+        ...event,
+        process
+    };
+};
+const isProcessEvent = (item)=>{
+    return item !== null && item !== undefined && typeof item === 'object' && item.type === 'process' && item.process !== null && item.process !== undefined && item.stage !== null && item.stage !== undefined;
+};
+
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+class Deferred {
+    constructor(){
+        _define_property(this, "promise", void 0);
+        _define_property(this, "resolve", void 0);
+        _define_property(this, "reject", void 0);
+        this.promise = new Promise((resolve, reject)=>{
+            this.resolve = resolve;
+            this.reject = reject;
+        });
+    }
+}
+function createAggregatorState() {
+    return {
+        aggregatorDeferreds: new Map(),
+        registerPendingAggregator (nodeId) {
+            let deferred = this.aggregatorDeferreds.get(nodeId);
+            if (!deferred) {
+                deferred = new Deferred();
+                this.aggregatorDeferreds.set(nodeId, deferred);
+            }
+            return deferred;
+        },
+        resolvePendingAggregator (nodeId, output) {
+            const deferred = this.aggregatorDeferreds.get(nodeId);
+            if (deferred) {
+                deferred.resolve(output);
+                this.aggregatorDeferreds.delete(nodeId);
+            }
+        },
+        getPendingAggregator (nodeId) {
+            return this.aggregatorDeferreds.get(nodeId);
+        },
+        pendingAggregatorIds () {
+            return Array.from(this.aggregatorDeferreds.keys());
+        }
+    };
+}
+async function executeAggregatorNode(nodeId, node, input, state) {
+    dispatchEvent(state.eventState, createAggregatorEvent(nodeId, 'start', node.aggregator, {
+        input
+    }), state.context);
+    let deferred = state.getPendingAggregator(nodeId);
+    const aggregationResult = await node.aggregator.aggregate(input, state.context);
+    dispatchEvent(state.eventState, createAggregatorEvent(nodeId, 'aggregate', node.aggregator, {
+        input,
+        result: aggregationResult
+    }), state.context);
+    if (aggregationResult.status === 'Ready') {
+        const output = aggregationResult.output;
+        dispatchEvent(state.eventState, createAggregatorEvent(nodeId, 'ready', node.aggregator, {
+            output
+        }), state.context);
+        state.resolvePendingAggregator(nodeId, output);
+        return output;
+    }
+    dispatchEvent(state.eventState, createAggregatorEvent(nodeId, 'defer', node.aggregator, {
+        input,
+        result: aggregationResult
+    }), state.context);
+    deferred = deferred !== null && deferred !== void 0 ? deferred : state.registerPendingAggregator(nodeId);
+    return deferred.promise;
+}
+
+// Helper function to handle the next step in the process
+async function handleNextStep(nodeOutput, nodeId, next, state) {
+    //console.log('[_HANDLE_NEXT_STEP_START]', { nodeId, nodeOutput, nextType: next && next.constructor ? next.constructor.name : typeof next, next });
+    if (Array.isArray(next) && next.length > 0 && next.every(isDecision)) {
+        const decisions = next;
+        // console.log('[_HANDLE_NEXT_STEP_DECISIONS]', { nodeId, count: decisions.length, decisions });
+        for (const decision of decisions){
+            // console.log('[_HANDLE_NEXT_STEP_DECISION_PROCESSING]', { nodeId, decisionId: decision.id, decision });
+            await dispatchEvent(state.eventState, createDecisionEvent(nodeId, 'start', decision, {
+                output: nodeOutput
+            }), state.context);
+            try {
+                const decisionOutcome = await decision.decide(nodeOutput, state.context);
+                await dispatchEvent(state.eventState, createDecisionEvent(nodeId, 'decide', decision, {
+                    output: nodeOutput,
+                    result: decisionOutcome
+                }), state.context);
+                // console.log('[_HANDLE_NEXT_STEP_DECISION_OUTCOME]', { nodeId, decisionId: decision.id, decisionOutcome });
+                await handleNextStep(nodeOutput, decision.id, decisionOutcome, state); // outcome processed, decision.id is context for next step if it's an error source. The original nodeId is implicitly the source of this decision.
+                await dispatchEvent(state.eventState, createDecisionEvent(nodeId, 'end', decision), state.context);
+            } catch (decisionError) {
+                // eslint-disable-next-line no-console
+                console.error(`[_HANDLE_NEXT_STEP_DECISION_ERROR] Error in decision ${decision.id} from node ${nodeId}:`, {
+                    decisionError,
+                    nodeId,
+                    decisionId: decision.id
+                });
+                state.errors.push({
+                    nodeId: decision.id,
+                    message: decisionError.message
+                });
+            // Note: 'end' event for this decision path is skipped due to error.
+            }
+        }
+    } else if (Array.isArray(next) && next.length > 0 && next.every(isConnection)) {
+        //console.log('[_HANDLE_NEXT_STEP_CONNECTIONS]', { nodeId, count: next.length, connections: next });
+        const connections = next;
+        const nextPhasePromises = [];
+        for (const connection of connections){
+            let nextInput = nodeOutput;
+            let nextContext = state.context;
+            await dispatchEvent(state.eventState, createConnectionEvent(nodeId, 'start', connection, {
+                input: nextInput
+            }), state.context);
+            if (connection.transform) {
+                //console.log('[_HANDLE_NEXT_STEP_CONNECTION_TRANSFORM_START]', { nodeId, targetNodeId: connection.targetNodeId });
+                try {
+                    const context = state.context;
+                    [nextInput, nextContext] = await connection.transform(nodeOutput, context);
+                    await dispatchEvent(state.eventState, createConnectionEvent(nodeId, 'transform', connection, {
+                        input: nextInput,
+                        output: nodeOutput,
+                        context: nextContext
+                    }), state.context);
+                    state.context = nextContext;
+                //console.log('[_HANDLE_NEXT_STEP_CONNECTION_TRANSFORM_SUCCESS]', { nodeId, targetNodeId: connection.targetNodeId, nextInput, nextContext });
+                } catch (transformError) {
+                    // eslint-disable-next-line no-console
+                    console.error(`[_HANDLE_NEXT_STEP_CONNECTION_TRANSFORM_ERROR] Error in transform for connection from ${nodeId} to ${connection.targetNodeId}:`, {
+                        transformError,
+                        nodeId,
+                        targetNodeId: connection.targetNodeId
+                    });
+                    state.errors.push({
+                        nodeId: connection.targetNodeId,
+                        message: transformError.message
+                    });
+                    continue;
+                }
+            }
+            //console.log('[_HANDLE_NEXT_STEP_CONNECTION_EXECUTE_TARGET]', { nodeId, targetNodeId: connection.targetNodeId, nextInput });
+            nextPhasePromises.push(executeNode(connection.targetNodeId, nextInput, state));
+            await dispatchEvent(state.eventState, createConnectionEvent(nodeId, 'end', connection), state.context);
+        }
+    // Optional: await Promise.all(nextPhasePromises); // Current design relies on executeProcess waiting on activeExecutions
+    //console.log('[_HANDLE_NEXT_STEP_CONNECTIONS_PROMISES_PUSHED]', { nodeId, count: nextPhasePromises.length });
+    } else if (isTermination(next)) {
+        //console.log('[_HANDLE_NEXT_STEP_TERMINATION]', { nodeId, termination: next });
+        const termination = next;
+        await dispatchEvent(state.eventState, createTerminationEvent(nodeId, 'start', termination, {
+            output: nodeOutput
+        }), state.context);
+        const result = nodeOutput;
+        if (termination.terminate) {
+            //console.log('[_HANDLE_NEXT_STEP_TERMINATION_CALLING_TERMINATE_FN]', { nodeId, terminationId: termination.id });
+            termination.terminate(nodeOutput, state.context);
+            await dispatchEvent(state.eventState, createTerminationEvent(nodeId, 'terminate', termination, {
+                output: nodeOutput
+            }), state.context);
+        }
+        state.results[termination.id] = result;
+    } else if (Array.isArray(next) && next.length === 0) {
+        // Empty array, potentially from a Decision that leads to no connections or an empty Connection array.
+        // This could mean an implicit termination for this path or simply no further action from this branch.
+        // If it's considered an end state for the path, store the result.
+        const result = nodeOutput;
+        state.results[nodeId] = result; // Using nodeId as the key for this implicit termination
+    } else {
+        // If there is no next (e.g. next is undefined or null after a decision), or it's an unhandled type.
+        // Consider this an end state and store the result with the nodeId
+        //console.log('[_HANDLE_NEXT_STEP_NO_NEXT_OR_UNHANDLED]', { nodeId, next, nodeOutput });
+        const result = nodeOutput;
+        state.results[nodeId] = result;
+    }
+//console.log('[_HANDLE_NEXT_STEP_END]', { nodeId });
+}
+
+function createPhaseEvent(sourceId, stage, phase, data) {
+    const event = createEvent('phase', sourceId, stage, data);
+    return {
+        ...event,
+        phase
+    };
+}
+
+async function executePhase(nodeId, node, input, state) {
+    dispatchEvent(state.eventState, createPhaseEvent(nodeId, 'start', node.phase, {
+        input
+    }), state.context);
+    if (node.phase.verify) {
+        const verifyResponse = await node.phase.verify(input);
+        if (!verifyResponse.verified) {
+            throw new Error(verifyResponse.messages.join('\n'));
+        }
+    }
+    const output = await node.phase.execute(input);
+    dispatchEvent(state.eventState, createPhaseEvent(nodeId, 'execute', node.phase, {
+        input,
+        output
+    }), state.context);
+    return output;
+}
+
+async function executeNode(nodeId, input, state) {
+    //console.log('[EXECUTE_NODE_RECURSIVE_START]', { nodeId, input, phaseResultsKeys: Object.keys(state.phaseResults), activeExecutionsKeys: Array.from(state.activeExecutions.keys()), aggregatorDeferredsKeys: Array.from(state.aggregatorDeferreds.keys()) });
+    // 1. Check if result is already cached in phaseResults (final output, node fully completed)
+    if (state.phaseResults[nodeId]) {
+        //console.log('[EXECUTE_NODE_RECURSIVE_CACHE_HIT_PHASERESULTS]', { nodeId, result: state.phaseResults[nodeId] });
+        return state.phaseResults[nodeId];
+    }
+    const node = state.process.phases[nodeId];
+    if (!node) {
+        const error = new Error(`Node with ID "${nodeId}" not found.`);
+        //console.error('[EXECUTE_NODE_RECURSIVE_NODE_NOT_FOUND]', { nodeId, error });
+        state.errors.push({
+            nodeId,
+            message: error.message
+        });
+        throw error;
+    }
+    //console.log('[EXECUTE_NODE_RECURSIVE_NODE_FOUND]', { nodeId, nodeType: node.constructor.name, node });
+    // 2. Handle active/pending executions
+    // If it's an aggregator that has a deferred promise, it means it's pending.
+    // We need to re-evaluate it with the current input. The IIFE below will handle this.
+    if (state.activeExecutions.has(nodeId) && !isAggregatorNode(node)) {
+        // For non-aggregators, if already active, return the promise.
+        // Aggregators will fall through to the IIFE to allow input processing.
+        // The IIFE itself handles returning a shared deferred promise if needed.
+        //console.log('[EXECUTE_NODE_RECURSIVE_ACTIVE_EXECUTION_HIT_NON_AGGREGATOR]', { nodeId });
+        return state.activeExecutions.get(nodeId);
+    }
+    // If it IS an aggregator and state.activeExecutions.has(nodeId),
+    // it means its deferred.promise might be in activeExecutions from a previous input that made it pending.
+    // The IIFE logic below will correctly retrieve this deferred (if it exists and is still relevant)
+    // from state.aggregatorDeferreds.get(nodeId) and use its promise, or process the input.
+    //console.log('[EXECUTE_NODE_RECURSIVE_CONTINUING_TO_EXECUTION_LOGIC]', { nodeId, isActive: state.activeExecutions.has(nodeId), isAggregator: isAggregatorNode(node), hasDeferred: state.aggregatorDeferreds.has(nodeId) });
+    // If it's an aggregator and it's pending (has a deferred), we fall through to re-execute its logic within the IIFE.
+    // If it's the first call to any node, we fall through.
+    // 3. Mark as active and execute (or re-evaluate pending aggregator)
+    const executionPromise = (async ()=>{
+        //console.log('[EXECUTE_NODE_RECURSIVE_IIFE_START]', { nodeId, input });
+        try {
+            let output;
+            if (isAggregatorNode(node)) {
+                dispatchEvent(state.eventState, createAggregatorNodeEvent(nodeId, 'start', node, {
+                    input
+                }), state.context);
+                output = await executeAggregatorNode(nodeId, node, input, state);
+            } else if (isPhaseNode(node)) {
+                dispatchEvent(state.eventState, createPhaseNodeEvent(nodeId, 'start', node, {
+                    input
+                }), state.context);
+                if (node.prepare) {
+                    const [preparedInput, preparedContext] = await node.prepare(input, state.context);
+                    input = preparedInput;
+                    state.context = preparedContext;
+                }
+                dispatchEvent(state.eventState, createPhaseNodeEvent(nodeId, 'prepared', node, {
+                    input
+                }), state.context);
+                output = await executePhase(nodeId, node, input, state);
+                if (node.process) {
+                    const [processedOutput, processedContext] = await node.process(output, state.context);
+                    output = processedOutput;
+                    state.context = processedContext;
+                }
+                dispatchEvent(state.eventState, createPhaseNodeEvent(nodeId, 'processed', node, {
+                    input,
+                    output
+                }), state.context);
+            //console.log('[EXECUTE_NODE_RECURSIVE_PHASE_NODE_EXECUTE_END]', { nodeId, output });
+            } else {
+                const error = new Error(`Unknown or invalid node type for ID "${nodeId}". Expected PhaseNode or AggregatorNode.`);
+                //console.error('[EXECUTE_NODE_RECURSIVE_UNKNOWN_NODE_TYPE]', { nodeId, node, error });
+                throw error;
+            }
+            state.phaseResults[nodeId] = output; // Set final output once ready/executed
+            //console.log('[EXECUTE_NODE_RECURSIVE_PHASE_RESULT_CACHED]', { nodeId, output });
+            // 4. Handle next step
+            if (node.next) {
+                //console.log('[EXECUTE_NODE_RECURSIVE_HANDLING_NEXT_STEP]', { nodeId, nextType: node.next.constructor.name, next: node.next });
+                if (Array.isArray(node.next) && node.next.length > 0 && node.next.every(isDecision)) {
+                    //console.log('[EXECUTE_NODE_RECURSIVE_DECISIONS_FOUND]', { nodeId, count: node.next.length, decisions: node.next });
+                    const decisions = node.next;
+                    const decisionExecutionPromises = [];
+                    for (const decision of decisions){
+                        dispatchEvent(state.eventState, createDecisionEvent(nodeId, 'start', decision, {
+                            output
+                        }), state.context);
+                        const decisionPromise = (async ()=>{
+                            //console.log('[EXECUTE_NODE_RECURSIVE_DECISION_EXECUTE_START]', { nodeId, decisionId: decision.id, output });
+                            try {
+                                const decisionOutcome = await decision.decide(output, state.context);
+                                dispatchEvent(state.eventState, createDecisionEvent(nodeId, 'decide', decision, {
+                                    output,
+                                    result: decisionOutcome
+                                }), state.context);
+                                //console.log('[EXECUTE_NODE_RECURSIVE_DECISION_OUTCOME]', { nodeId, decisionId: decision.id, decisionOutcome });
+                                await handleNextStep(output, decision.id, decisionOutcome, state);
+                                dispatchEvent(state.eventState, createDecisionEvent(nodeId, 'end', decision), state.context);
+                            } catch (decisionError) {
+                                // eslint-disable-next-line no-console
+                                console.error(`[_HANDLE_NEXT_STEP_DECISION_ERROR] Error in decision ${decision.id} for node ${nodeId}:`, {
+                                    decisionError,
+                                    nodeId,
+                                    decisionId: decision.id
+                                });
+                                state.errors.push({
+                                    nodeId: decision.id,
+                                    message: decisionError.message
+                                });
+                            }
+                        })();
+                        decisionExecutionPromises.push(decisionPromise);
+                    }
+                    //console.log('[EXECUTE_NODE_RECURSIVE_WAITING_FOR_DECISIONS]', { nodeId, count: decisionExecutionPromises.length });
+                    await Promise.all(decisionExecutionPromises);
+                //console.log('[EXECUTE_NODE_RECURSIVE_DECISIONS_COMPLETE]', { nodeId });
+                } else {
+                    //console.log('[EXECUTE_NODE_RECURSIVE_CALLING_HANDLE_NEXT_STEP_FOR_NON_DECISION]', { nodeId, next: node.next });
+                    await handleNextStep(output, nodeId, node.next, state);
+                }
+            } else {
+                //console.log('[EXECUTE_NODE_RECURSIVE_NO_NEXT_NODE_IMPLICIT_TERMINATION]', { nodeId, output });
+                const result = output;
+                state.results[nodeId] = result;
+            }
+            if (isPhaseNode(node)) {
+                dispatchEvent(state.eventState, createPhaseNodeEvent(nodeId, 'end', node, {
+                    input,
+                    output
+                }), state.context);
+            } else {
+                dispatchEvent(state.eventState, createAggregatorNodeEvent(nodeId, 'end', node, {
+                    input,
+                    output
+                }), state.context);
+            }
+            //console.log('[EXECUTE_NODE_RECURSIVE_IIFE_RETURNING_OUTPUT]', { nodeId, output });
+            return output;
+        } catch (error) {
+            // eslint-disable-next-line no-console
+            console.error(`[EXECUTE_NODE_RECURSIVE_IIFE_ERROR] Error executing node ${nodeId}:`, {
+                error,
+                nodeId
+            });
+            state.errors.push({
+                nodeId,
+                message: error.message
+            });
+            throw error;
+        } finally{
+            //console.log('[EXECUTE_NODE_RECURSIVE_IIFE_FINALLY]', { nodeId, hasAggregatorDeferred: state.aggregatorDeferreds.has(nodeId) });
+            // If a node completed (not pending via deferred mechanism) or an error occurred.
+            // An aggregator that is still pending (has a deferred) should keep its promise in activeExecutions.
+            if (!state.aggregatorDeferreds.has(nodeId)) {
+                //console.log('[EXECUTE_NODE_RECURSIVE_IIFE_FINALLY_DELETING_ACTIVE_EXECUTION]', { nodeId });
+                state.activeExecutions.delete(nodeId);
+            }
+        }
+    })();
+    // Store the promise from the IIFE.
+    // If it's an aggregator that went pending, executionPromise IS deferred.promise.
+    // If it's an aggregator that became ready, executionPromise is a promise resolving to its output.
+    // If it's a phase node, executionPromise is a promise resolving to its output.
+    //console.log('[EXECUTE_NODE_RECURSIVE_SETTING_ACTIVE_EXECUTION]', { nodeId });
+    state.activeExecutions.set(nodeId, executionPromise);
+    //console.log('[EXECUTE_NODE_RECURSIVE_END_RETURNING_PROMISE]', { nodeId });
+    return executionPromise;
+}
+
+const EMPTY_INPUT = {};
+
+const DEFAULT_PROCESS_EXECUTION_OPTIONS = {
+    input: EMPTY_INPUT,
+    context: {},
+    eventHandlers: []
+};
+async function executeProcess(processInstance, beginning, options) {
+    const processExecutionOptions = {
+        ...DEFAULT_PROCESS_EXECUTION_OPTIONS,
+        ...clean(options || {})
+    };
+    if (options && options.input) {
+        processExecutionOptions.input = options.input;
+    }
+    if (options && options.eventHandlers) {
+        processExecutionOptions.eventHandlers = options.eventHandlers;
+    }
+    const validationErrors = validateProcess(processInstance);
+    if (validationErrors.length > 0) {
+        const errorMessages = validationErrors.map((err)=>err.error).join('\n');
+        throw new Error(`Invalid process definition:\n${errorMessages}`);
+    }
+    const eventState = createEventState(processExecutionOptions.eventHandlers);
+    const state = {
+        process: processInstance,
+        context: processExecutionOptions.context,
+        results: {},
+        phaseResults: {},
+        activeExecutions: new Map(),
+        errors: [],
+        ...createAggregatorState(),
+        eventState: eventState
+    };
+    dispatchEvent(state.eventState, createProcessEvent(processInstance.name, 'start', processInstance, {
+        input: processExecutionOptions.input,
+        context: state.context
+    }), state.context);
+    dispatchEvent(state.eventState, createBeginningEvent(beginning.id, 'start', beginning, {
+        input: processExecutionOptions.input
+    }), state.context);
+    const initialInput = await beginning.begin(processExecutionOptions.input, state.context);
+    dispatchEvent(state.eventState, createBeginningEvent(beginning.id, 'begin', beginning, {
+        input: initialInput
+    }), state.context);
+    const initialNodeId = beginning.targetNodeId;
+    if (!state.process.phases[initialNodeId]) {
+        throw new Error(`Start phase ID "${initialNodeId}" not found in process phases.`);
+    }
+    try {
+        await executeNode(initialNodeId, initialInput, state);
+        const allPromises = Array.from(state.activeExecutions.values());
+        if (allPromises.length > 0) {
+            await Promise.all(allPromises);
+        }
+    } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        state.errors.push({
+            message: "Critical error during process execution",
+            details: errorMessage,
+            nodeId: initialNodeId
+        });
+        // eslint-disable-next-line no-console
+        console.error("[EXECUTE_PROCESS_CRITICAL_ERROR]", {
+            processName: processInstance.name,
+            error: errorMessage,
+            collectedErrors: state.errors
+        });
+    }
+    if (state.aggregatorDeferreds && state.aggregatorDeferreds.size > 0) {
+        const pendingNodeIds = state.pendingAggregatorIds ? state.pendingAggregatorIds().join(', ') : 'unknown';
+        // eslint-disable-next-line no-console
+        console.warn(`[EXECUTE_PROCESS_PENDING_AGGREGATORS] Process execution may have pending aggregators: ${pendingNodeIds}.`, {
+            processName: processInstance.name,
+            pendingNodeIds
+        });
+    }
+    dispatchEvent(state.eventState, createProcessEvent(processInstance.name, 'end', processInstance, {
+        input: processExecutionOptions.input,
+        context: state.context
+    }), state.context);
+    return [
+        state.results,
+        state.phaseResults,
+        state.context
+    ];
+}
+
+exports.createAggregator = createAggregator;
+exports.createAggregatorEvent = createAggregatorEvent;
+exports.createAggregatorNode = createAggregatorNode;
+exports.createBeginning = createBeginning;
+exports.createBeginningEvent = createBeginningEvent;
+exports.createConnection = createConnection;
+exports.createConnectionEvent = createConnectionEvent;
+exports.createDecision = createDecision;
+exports.createDecisionEvent = createDecisionEvent;
+exports.createEventFilter = createEventFilter;
+exports.createEventHandler = createEventHandler;
+exports.createEventState = createEventState;
+exports.createFilteredHandler = createFilteredHandler;
+exports.createNode = createNode;
+exports.createNodeEvent = createNodeEvent;
+exports.createPhase = createPhase;
+exports.createPhaseNode = createPhaseNode;
+exports.createProcess = createProcess;
+exports.createProcessEvent = createProcessEvent;
+exports.createTermination = createTermination;
+exports.createTerminationEvent = createTerminationEvent;
+exports.createTransitionEvent = createTransitionEvent;
+exports.dispatchEvent = dispatchEvent;
+exports.executeProcess = executeProcess;
+exports.isAggregator = isAggregator;
+exports.isAggregatorEvent = isAggregatorEvent;
+exports.isAggregatorNode = isAggregatorNode;
+exports.isAggregatorNodeEvent = isAggregatorNodeEvent;
+exports.isBeginning = isBeginning;
+exports.isBeginningEvent = isBeginningEvent;
+exports.isConnection = isConnection;
+exports.isConnectionEvent = isConnectionEvent;
+exports.isDecision = isDecision;
+exports.isDecisionEvent = isDecisionEvent;
+exports.isNode = isNode;
+exports.isNodeEvent = isNodeEvent;
+exports.isPhase = isPhase;
+exports.isPhaseNode = isPhaseNode;
+exports.isPhaseNodeEvent = isPhaseNodeEvent;
+exports.isProcess = isProcess;
+exports.isProcessEvent = isProcessEvent;
+exports.isTermination = isTermination;
+exports.isTerminationEvent = isTerminationEvent;
+exports.isTransition = isTransition;
+exports.validateNode = validateNode;
+//# sourceMappingURL=xenocline.cjs.map