@nosana/node 1.0.0-rc

package/dist/NodeManager/node/task/TaskManager.js

@@ -0,0 +1,480 @@
+import EventEmitter from 'events';
+import { runTaskManagerOperation } from './operations/runTaskManagerOperation.js';
+import { restartTaskManagerOperation } from './operations/restartTaskManagerOperation.js';
+import { stopTaskManagerOperation } from './operations/stopTaskManagerOperation.js';
+import { stopTaskManagerGroupOperations } from './operations/stopTaskManagerGroupOperation.js';
+import { restartTaskManagerGroupOperations } from './operations/restartTaskManagerGroupOperation.js';
+import { createOperationMap } from './executions/createOperationMap.js';
+import { createExecutionPlan } from './executions/createExecutionPlan.js';
+import { validateExecutionPlan } from './executions/validateExecutionPlan.js';
+import { stopAllTaskManagerOperations } from './operations/stopAllTaskManagerOperations.js';
+import { createInitialFlow } from './helpers/createInitialFlow.js';
+import { createDependencyMap } from './executions/createDependencyMap.js';
+import { getCurrentGroup, getCurrentGroupStatus, getGroupStatus, getOperationsStatus, getOperationStatus, } from './operations/getOperationsInfos.js';
+import { addLog, getAllLogs, getLogsByGroup, getLogsByOp, subscribe, unsubscribe, } from './loggers/logManager.js';
+import { moveTaskManagerGroupOperations } from './operations/moveTaskManagerGroupOperation.js';
+import { setResult, setResults, setHost, setDefaults, rehydrateEndpointsForOperation, getByPath, resolveLiteralsInString, interpolate, interpolateOperation, transformCollections, } from './globalStore/index.js';
+import { configs } from '../../configs/configs.js';
+import { getSDK } from '../../sdk/index.js';
+export const StopReasons = {
+    COMPLETED: 'completed',
+    EXPIRED: 'expired',
+    STOPPED: 'stopped',
+    QUIT: 'quit',
+    UNKNOWN: 'unknown',
+    RESTART: 'restart',
+};
+export const Statuses = {
+    SUCCESS: 'success',
+    STOPPED: 'stopped',
+    FAILED: 'failed',
+};
+export const OperationProgressStatuses = {
+    FINISHED: 'finished',
+    STOPPED: 'stopped',
+    FAILED: 'failed',
+    RUNNING: 'running',
+    RESTARTING: 'restarting',
+    STOPPING: 'stopping',
+    STARTING: 'starting',
+    WAITING: 'waiting',
+    PENDING: 'pending',
+    INIT: 'init',
+};
+export default class TaskManager {
+    constructor(provider, repository, job, project, definition) {
+        this.provider = provider;
+        this.repository = repository;
+        this.job = job;
+        this.project = project;
+        this.definition = definition;
+        /**
+         * The ordered execution plan built from the job definition.
+         * Each item represents a group of ops that run together horizontally.
+         */
+        this.executionPlan = [];
+        /**
+         * this creates a map to assign the dependency
+         */
+        this.dependecyMap = new Map();
+        /**
+         * A map for fast lookup of operations by their ID.
+         * Useful during validation and execution.
+         */
+        this.opMap = new Map();
+        /**
+         * Global data store for all operations in a job definition.
+         *
+         * This allows operations to reference data produced by others using literals like:
+         *   "%%ops.nginx-1.results.someKey%%"
+         *   "%%ops.nginx-1.host%%"
+         *
+         * Supported keys:
+         * - result: Stores the output of an operation so it can be accessed later, even if it was unknown at the start of the job.
+         * - host: Stores the reachable host/URL of the operation. Since Docker container names are dynamic,
+         *         this ensures other operations can communicate with it without needing to know the name in advance.
+         */
+        this.globalOpStore = {};
+        /**
+         * Main controller to allow global cancellation of the entire task flow.
+         * All per-op controllers should eventually be tied to this as their parent,
+         * or fallback to this if no specific controller is assigned yet.
+         */
+        this.mainAbortController = new AbortController();
+        /**
+         * Stores one AbortController per op.
+         * Used to signal cancellation to all ops in a group or individually if needed.
+         */
+        this.abortControllerMap = new Map();
+        /**
+         * keeps track of all promises of the current running group
+         */
+        this.currentGroupOperationsPromises = new Map();
+        /**
+         * this is to create concurrency control on the operations
+         */
+        this.lockedOperations = new Map();
+        /**
+         * this is used to track the operations statuses
+         */
+        this.operationStatus = new Map();
+        /**
+         * this is to track event emitter to emit events
+         */
+        this.operationsEventEmitters = new Map();
+        /**
+         * save log buffer for streaming logs
+         */
+        this.opLogBuffers = new Map();
+        /**
+         * this list of ws sub to the task managers events
+         */
+        this.subscribers = new Set();
+        /**
+         * stores filters
+         */
+        this.logMatchers = new Map();
+        this.TOTAL_LOGS_COUNT = 0;
+        /**
+         * Lifecycle status of the task manager.
+         * Can be 'init', 'running', 'stopped', or 'done'.
+         */
+        this.status = 'init';
+        /**
+         * Event emitter for task- and op-level lifecycle events.
+         */
+        this.events = new EventEmitter();
+        if (definition) {
+            this.operations = definition.ops;
+        }
+        this.runTaskManagerOperation = runTaskManagerOperation.bind(this);
+        this.restartTaskManagerOperation = restartTaskManagerOperation.bind(this);
+        this.stopTaskManagerOperation = stopTaskManagerOperation.bind(this);
+        this.stopTaskManagerGroupOperations =
+            stopTaskManagerGroupOperations.bind(this);
+        this.restartTaskManagerGroupOperations =
+            restartTaskManagerGroupOperations.bind(this);
+        this.moveTaskManagerGroupOperations =
+            moveTaskManagerGroupOperations.bind(this);
+        this.stopAllTaskManagerOperations = stopAllTaskManagerOperations.bind(this);
+        this.createOperationMap = createOperationMap.bind(this);
+        this.createExecutionPlan = createExecutionPlan.bind(this);
+        this.createDependencyMap = createDependencyMap.bind(this);
+        this.validateExecutionPlan = validateExecutionPlan.bind(this);
+        this.getOperationsStatus = getOperationsStatus.bind(this);
+        this.getOperationStatus = getOperationStatus.bind(this);
+        this.getCurrentGroup = getCurrentGroup.bind(this);
+        this.getCurrentGroupStatus = getCurrentGroupStatus.bind(this);
+        this.getGroupStatus = getGroupStatus.bind(this);
+        this.addlog = addLog.bind(this);
+        this.getLogsByOp = getLogsByOp.bind(this);
+        this.getLogsByGroup = getLogsByGroup.bind(this);
+        this.getAllLogs = getAllLogs.bind(this);
+        this.subscribe = subscribe.bind(this);
+        this.unsubscribe = unsubscribe.bind(this);
+        this.setResult = setResult.bind(this);
+        this.setResults = setResults.bind(this);
+        this.setHost = setHost.bind(this);
+        this.setDefaults = setDefaults.bind(this);
+        this.rehydrateEndpointsForOperation =
+            rehydrateEndpointsForOperation.bind(this);
+        this.getByPath = getByPath.bind(this);
+        this.resolveLiteralsInString = resolveLiteralsInString.bind(this);
+        this.interpolate = interpolate.bind(this);
+        this.interpolateOperation = interpolateOperation.bind(this);
+        this.transformCollections = transformCollections.bind(this);
+        const sdk = getSDK();
+        this.globalStore = {
+            job,
+            project,
+            frps_address: configs().frp.serverAddr,
+            host: sdk.solana.wallet.publicKey.toString(),
+        };
+        // Allow more listeners to account for many ops without warnings
+        this.events.setMaxListeners(100);
+    }
+    /**
+     * Returns the unified event emitter for this task manager.
+     */
+    getEventsEmitter() {
+        return this.events;
+    }
+    /**
+     * Registers an op-level emitter and relays its relevant events to the
+     * task-level unified emitter. Also tracks the emitter in operationsEventEmitters.
+     */
+    registerAndRelayOpEmitter(opId, emitter) {
+        const existing = this.operationsEventEmitters.get(opId);
+        if (existing && existing === emitter)
+            return;
+        const lifecycleEvents = new Set([
+            'start',
+            'exit',
+            'error',
+            'updateOpState',
+            'healthcheck:startup:success',
+            'flow:secrets-updated',
+        ]);
+        const eventsToRegister = [...lifecycleEvents, 'log'];
+        if (existing && existing !== emitter) {
+            for (const eventName of eventsToRegister) {
+                existing.removeAllListeners(eventName);
+            }
+        }
+        emitter.setMaxListeners(50);
+        const relay = (eventType) => (payload) => {
+            this.events.emit('op:event', { opId, type: eventType, payload });
+            // For events that impact job-info payload, also emit flow:updated
+            if (lifecycleEvents.has(eventType)) {
+                this.events.emit('flow:updated', {
+                    jobId: this.job,
+                    opId,
+                    type: eventType,
+                });
+            }
+        };
+        for (const eventName of eventsToRegister) {
+            emitter.on(eventName, relay(eventName));
+        }
+        this.operationsEventEmitters.set(opId, emitter);
+        this.events.emit('op:emitter-registered', { opId });
+    }
+    /**
+     * Prepares the TaskManager for execution by performing all necessary setup steps.
+     *
+     * This method performs two key operations:
+     *
+     *  `build()`:
+     *    - Generates a map of all operations for fast lookup.
+     *    - Creates the execution plan based on operation groups and dependencies.
+     *    - Validates the structure of the plan to catch any misconfigurations early.
+     *
+     *  `init()`:
+     *    - Initializes the task's persistent flow state in the repository.
+     *    - Skips initialization if the flow already exists (resumable/restartable design).
+     *
+     * Call this once before `start()` to ensure the task manager is fully ready.
+     */
+    bootstrap() {
+        this.build(); // Set up opMap, executionPlan, and validate
+        this.init(); // Create initial flow in the repository if it doesn't already exist
+        // register all operations to init status
+        [...this.opMap.keys()].forEach((op) => this.operationStatus.set(op, OperationProgressStatuses.INIT));
+    }
+    /**
+     * Starts the execution of the job by processing each group in the execution plan.
+     * Tracks the full lifecycle including flow state updates and dynamic operations.
+     *
+     * Execution Lifecycle:
+     * - If already started, returns the tracked lifecycle promise.
+     * - Sets status to 'running' and updates the repository with start time.
+     * - Iterates through execution groups and runs each op concurrently.
+     * - Uses a dynamic while-loop to ensure all ops (including restarts) finish before advancing.
+     * - After all groups finish, updates the flow state to 'success' or keeps previous status.
+     * - On any uncaught failure, marks the flow as 'failed' with end time.
+     */
+    async start() {
+        // Return the lifecycle promise if already running
+        if (this.currentRunningStartPromise)
+            return this.currentRunningStartPromise;
+        // Track the entire execution lifecycle in one promise
+        this.currentRunningStartPromise = (async () => {
+            // Fetch existing flow to determine whether execution should continue
+            const flow = this.repository.getFlow(this.job);
+            try {
+                // If job already ended (either success or failure), no need to start again
+                // if (flow.state.endTime) return;
+                // Mark as running and update DB
+                this.status = 'running';
+                this.repository.updateflowState(this.job, {
+                    status: this.status,
+                    startTime: Date.now(),
+                });
+                this.events.emit('flow:updated', {
+                    jobId: this.job,
+                    type: 'status:start',
+                });
+                // update all operations status to pending since we have started
+                [...this.opMap.keys()].forEach((op) => this.operationStatus.set(op, OperationProgressStatuses.PENDING));
+                // Loop through execution plan, group by group
+                for (const p of this.executionPlan) {
+                    this.currentGroup = p.group;
+                    this.events.emit('flow:updated', {
+                        jobId: this.job,
+                        type: 'group:start',
+                        group: this.currentGroup,
+                    });
+                    // Queue each operation in the group for execution
+                    for (const id of p.ops) {
+                        const dependencyContext = this.dependecyMap.get(id);
+                        const dependencies = dependencyContext.dependencies || [];
+                        const depsSatisfied = dependencies.length === 0 ||
+                            dependencies.every((depId) => {
+                                const depStatus = this.operationStatus.get(depId);
+                                return (depStatus === OperationProgressStatuses.FINISHED ||
+                                    depStatus === OperationProgressStatuses.STOPPED);
+                            });
+                        if (depsSatisfied) {
+                            this.operationStatus.set(id, OperationProgressStatuses.STARTING);
+                            this.currentGroupOperationsPromises.set(id, this.trackGroupOperationPromise(id, this.setUpOperationFunc(flow, id, dependencyContext.dependents)));
+                        }
+                        else {
+                            this.operationStatus.set(id, OperationProgressStatuses.WAITING);
+                        }
+                    }
+                    // push updated STARTING/WAITING statuses to listeners
+                    this.events.emit('flow:updated', {
+                        jobId: this.job,
+                        type: 'group:schedule',
+                        group: this.currentGroup,
+                    });
+                    try {
+                        /**
+                         * We use a `while` loop instead of a single `await Promise.all(...)` to handle dynamic group operations.
+                         *
+                         * Why:
+                         * - During execution, new operations (like restarted ops) can be added to `currentGroupOperationsPromises`.
+                         * - If we used a static `Promise.all(...)` outside the loop, it would only await the current snapshot,
+                         *   and any late-added promises wouldn't be awaited — leading to premature group advancement.
+                         *
+                         * This loop ensures:
+                         * - We await all operations in the group, including those dynamically inserted (e.g. from restarts).
+                         * - The group doesn't complete until all its tracked promises are settled and removed.
+                         */
+                        while (this.currentGroupOperationsPromises.size > 0) {
+                            await Promise.all([
+                                ...this.currentGroupOperationsPromises.values(),
+                            ]);
+                        }
+                    }
+                    finally {
+                        // Reset group state after completion. successful or not
+                        const finishedGroup = this.currentGroup;
+                        this.currentGroup = undefined;
+                        this.currentGroupOperationsPromises.clear();
+                        this.events.emit('flow:updated', {
+                            jobId: this.job,
+                            type: 'group:end',
+                            group: finishedGroup,
+                        });
+                    }
+                }
+                // If status is still 'running', mark the job as successful
+                this.status = this.status === 'running' ? 'success' : this.status;
+                this.repository.updateflowState(this.job, {
+                    status: this.status,
+                    endTime: Date.now(),
+                    secrets: {},
+                });
+                this.events.emit('flow:updated', {
+                    jobId: this.job,
+                    type: 'status:end',
+                });
+            }
+            catch (error) {
+                // Any uncaught failure sets the flow to 'failed'
+                this.repository.updateflowState(this.job, {
+                    status: 'failed',
+                    endTime: Date.now(),
+                    secrets: {},
+                });
+                this.events.emit('flow:updated', {
+                    jobId: this.job,
+                    type: 'status:failed',
+                });
+            }
+            finally {
+                // Do a total operation clean up where we go through all the opmap and clean all operations
+                const closingOperationPromises = [];
+                for (const op of this.opMap.values()) {
+                    closingOperationPromises.push(this.provider.stopTaskManagerOperation(flow, op));
+                }
+                await Promise.all(closingOperationPromises);
+            }
+        })();
+        return this.currentRunningStartPromise;
+    }
+    /**
+     * Gracefully stops the task manager and all its operations.
+     *
+     * This method:
+     * - Immediately aborts all running operations by triggering the main abort controller.
+     * - Waits for the current `start()` flow to finish, including database updates.
+     * - Ensures `stop()` logic runs only once per job to prevent race conditions.
+     *
+     * Important:
+     * - `stopAllTaskManagerOperations()` is synchronous and triggers cancellation.
+     * - The actual cleanup and final state update (e.g., setting `endTime`) is handled
+     *   by the `start()` method’s final logic.
+     */
+    async stop(reason) {
+        const lockKey = `stop:${this.job}`;
+        // Ensure stop logic runs only once per job
+        if (this.lockedOperations.has(lockKey))
+            return;
+        this.lockedOperations.set(lockKey, reason);
+        try {
+            // Immediately abort all running operations
+            this.stopAllTaskManagerOperations(reason);
+            // Wait for the ongoing start logic to gracefully complete
+            if (this.currentRunningStartPromise) {
+                try {
+                    await this.currentRunningStartPromise;
+                }
+                catch {
+                    // We ignore start errors during shutdown — cleanup should proceed regardless
+                }
+            }
+        }
+        finally {
+            // Cleanup the lock regardless of outcome
+            this.lockedOperations.delete(lockKey);
+        }
+    }
+    setUpOperationFunc(flow, id, dependent) {
+        const op = this.opMap.get(id);
+        if (!op) {
+            throw new Error(`Invalid Op id: ${id}`);
+        }
+        return this.runTaskManagerOperation(flow, op, dependent);
+    }
+    trackGroupOperationPromise(opId, promise) {
+        this.currentGroupOperationsPromises.set(opId, promise);
+        promise.finally(() => {
+            this.currentGroupOperationsPromises.delete(opId);
+            for (const [nextOpId, { execution }] of this.opMap) {
+                if (!this.currentGroup ||
+                    !execution ||
+                    !execution.depends_on ||
+                    !execution.stop_if_dependent_stops)
+                    continue;
+                if (execution.depends_on.includes(opId)) {
+                    this.stopTaskManagerOperation(this.currentGroup, nextOpId);
+                }
+            }
+        });
+        return promise;
+    }
+    getStatus(reason, type) {
+        const map = {
+            [StopReasons.COMPLETED]: {
+                ops: Statuses.SUCCESS,
+                flow: Statuses.SUCCESS,
+            },
+            [StopReasons.EXPIRED]: { ops: Statuses.SUCCESS, flow: Statuses.SUCCESS },
+            [StopReasons.STOPPED]: { ops: Statuses.STOPPED, flow: Statuses.STOPPED },
+            [StopReasons.RESTART]: { ops: Statuses.STOPPED, flow: Statuses.STOPPED },
+            [StopReasons.QUIT]: { ops: Statuses.FAILED, flow: Statuses.FAILED },
+            [StopReasons.UNKNOWN]: { ops: Statuses.FAILED, flow: Statuses.FAILED },
+        };
+        return map[reason][type];
+    }
+    getOpStateIndex(opId) {
+        const index = this.operations.findIndex((op) => op.id === opId);
+        if (index === -1) {
+            throw new Error(`Operation not found for ID: ${opId}`);
+        }
+        return index;
+    }
+    build() {
+        this.opMap = this.createOperationMap();
+        this.validateExecutionPlan();
+        this.executionPlan = this.createExecutionPlan();
+        this.dependecyMap = this.createDependencyMap();
+    }
+    init() {
+        const flow = this.repository.getFlow(this.job);
+        if (flow && flow.state.status !== 'waiting-for-job-definition') {
+            this.definition = flow.jobDefinition;
+        }
+        else {
+            const now = Date.now();
+            const flow = createInitialFlow(this.job, this.project, this.definition, this.operations, this.status, now);
+            this.repository.setflow(this.job, flow);
+            this.setDefaults(flow.id, this.project, this.definition);
+        }
+        if (!this.definition) {
+            throw new Error('Job Definition Not Specified');
+        }
+    }
+}

package/dist/NodeManager/node/task/TaskManagerRegistry.d.ts

@@ -0,0 +1,49 @@
+import TaskManager from './TaskManager.js';
+/**
+ * TaskManagerRegistry
+ *
+ * A singleton registry to track active TaskManager instances, keyed by `jobId`.
+ *
+ * In a system where jobs are processed via isolated TaskManager instances,
+ * this registry provides global visibility and control over running jobs
+ * without violating encapsulation or spawning duplicates.
+ *
+ * ---------------------------------------------------------------------------------------
+ * ✅ WHY THIS EXISTS:
+ * ---------------------------------------------------------------------------------------
+ * - Each `TaskManager` is designed to handle a single job at a time.
+ * - The API (or other system components) should not create new instances blindly.
+ * - Instead, they can **query the registry** for the job-specific TaskManager.
+ * - This avoids duplicate execution and lets the system safely:
+ *    - Pause/resume/stop jobs
+ *    - Fetch logs or live state
+ *    - Broadcast updates via WebSocket
+ *
+ * ---------------------------------------------------------------------------------------
+ *  FUTURE USE CASES:
+ * ---------------------------------------------------------------------------------------
+ * - **Parallel Job Execution:**
+ *   You’ll eventually support multiple jobs running at the same time (concurrently).
+ *   This registry is the backbone for that. Each job gets its own `TaskManager`,
+ *   but the registry keeps them accessible and uniquely identifiable.
+ *
+ * - **Safe Shutdown / Cleanup:**
+ *   On server shutdown, loop through all managers via the registry
+ *   and gracefully shut down active tasks.
+ *
+ * - Use `.register()` when starting a job
+ * - Use `.remove()` once the job finishes (success/fail)
+ * - `.get()` to safely access a manager by ID
+ * - Singleton ensures the same instance is used everywhere
+ */
+export declare class TaskManagerRegistry {
+    private static instance;
+    private registry;
+    private constructor();
+    static getInstance(): TaskManagerRegistry;
+    register(jobId: string, manager: TaskManager): void;
+    get(jobId: string): TaskManager | undefined;
+    remove(jobId: string): void;
+    has(jobId: string): boolean;
+    stop(): Promise<void>;
+}

package/dist/NodeManager/node/task/TaskManagerRegistry.js

@@ -0,0 +1,68 @@
+/**
+ * TaskManagerRegistry
+ *
+ * A singleton registry to track active TaskManager instances, keyed by `jobId`.
+ *
+ * In a system where jobs are processed via isolated TaskManager instances,
+ * this registry provides global visibility and control over running jobs
+ * without violating encapsulation or spawning duplicates.
+ *
+ * ---------------------------------------------------------------------------------------
+ * ✅ WHY THIS EXISTS:
+ * ---------------------------------------------------------------------------------------
+ * - Each `TaskManager` is designed to handle a single job at a time.
+ * - The API (or other system components) should not create new instances blindly.
+ * - Instead, they can **query the registry** for the job-specific TaskManager.
+ * - This avoids duplicate execution and lets the system safely:
+ *    - Pause/resume/stop jobs
+ *    - Fetch logs or live state
+ *    - Broadcast updates via WebSocket
+ *
+ * ---------------------------------------------------------------------------------------
+ *  FUTURE USE CASES:
+ * ---------------------------------------------------------------------------------------
+ * - **Parallel Job Execution:**
+ *   You’ll eventually support multiple jobs running at the same time (concurrently).
+ *   This registry is the backbone for that. Each job gets its own `TaskManager`,
+ *   but the registry keeps them accessible and uniquely identifiable.
+ *
+ * - **Safe Shutdown / Cleanup:**
+ *   On server shutdown, loop through all managers via the registry
+ *   and gracefully shut down active tasks.
+ *
+ * - Use `.register()` when starting a job
+ * - Use `.remove()` once the job finishes (success/fail)
+ * - `.get()` to safely access a manager by ID
+ * - Singleton ensures the same instance is used everywhere
+ */
+export class TaskManagerRegistry {
+    constructor() {
+        this.registry = new Map();
+    }
+    static getInstance() {
+        if (!TaskManagerRegistry.instance) {
+            TaskManagerRegistry.instance = new TaskManagerRegistry();
+        }
+        return TaskManagerRegistry.instance;
+    }
+    register(jobId, manager) {
+        this.registry.set(jobId, manager);
+    }
+    get(jobId) {
+        return this.registry.get(jobId);
+    }
+    remove(jobId) {
+        this.registry.delete(jobId);
+    }
+    has(jobId) {
+        return this.registry.has(jobId);
+    }
+    async stop() {
+        const stopPromises = [];
+        for (const [jobId, manager] of this.registry.entries()) {
+            const p = manager.stop('quit').finally(() => this.registry.delete(jobId));
+            stopPromises.push(p);
+        }
+        await Promise.all(stopPromises);
+    }
+}

package/dist/NodeManager/node/task/executions/createDependencyMap.d.ts

@@ -0,0 +1,18 @@
+import TaskManager from '../TaskManager.js';
+/**
+ * Creates a dependency map for all operations.
+ *
+ * Returns a Map of operation ID -> {
+ *   dependencies: operation IDs this op waits for
+ *   dependents: operation IDs that wait for this op
+ * }
+ *
+ * This allows the task manager to:
+ * - Dynamically trigger downstream ops when upstream completes
+ * - Track dependencies and dependents efficiently during execution
+ * - Use alongside the execution plan to resolve execution flow
+ */
+export declare function createDependencyMap(this: TaskManager): Map<string, {
+    dependencies: string[];
+    dependents: string[];
+}>;

package/dist/NodeManager/node/task/executions/createDependencyMap.js

@@ -0,0 +1,32 @@
+/**
+ * Creates a dependency map for all operations.
+ *
+ * Returns a Map of operation ID -> {
+ *   dependencies: operation IDs this op waits for
+ *   dependents: operation IDs that wait for this op
+ * }
+ *
+ * This allows the task manager to:
+ * - Dynamically trigger downstream ops when upstream completes
+ * - Track dependencies and dependents efficiently during execution
+ * - Use alongside the execution plan to resolve execution flow
+ */
+export function createDependencyMap() {
+    const map = new Map();
+    // Initialize map with declared dependencies
+    for (const op of this.operations) {
+        map.set(op.id, {
+            dependencies: op.execution?.depends_on ?? [],
+            dependents: [],
+        });
+    }
+    // Populate dependents for each dependency
+    for (const [id, { dependencies }] of map.entries()) {
+        for (const depId of dependencies) {
+            if (!map.has(depId))
+                continue;
+            map.get(depId).dependents.push(id);
+        }
+    }
+    return map;
+}

package/dist/NodeManager/node/task/executions/createExecutionPlan.d.ts

@@ -0,0 +1,14 @@
+import TaskManager from '../TaskManager.js';
+import { ExecutionContext } from '../TaskManager.js';
+/**
+ * Converts the list of operations into a structured execution plan.
+ *
+ * This function focuses only on grouping operations by execution group.
+ * Dependency resolution (dependencies + dependents) is now handled separately
+ * in `createDependencyMap()`.
+ *
+ * Each `ExecutionContext` includes:
+ * - `group`: The logical group name
+ * - `ops`: Array of operations with their `id` only
+ */
+export declare function createExecutionPlan(this: TaskManager): ExecutionContext[];