@elaraai/e3-core 0.0.2-beta.3 → 0.0.2-beta.31

package/dist/src/dataflow/orchestrator/LocalOrchestrator.js

@@ -0,0 +1,416 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * Local in-process dataflow orchestrator.
+ *
+ * Executes dataflow using an async loop with step functions.
+ * This is the default orchestrator for CLI and local API server usage.
+ */
+import { variant } from '@elaraai/east';
+import { taskExecute } from '../../execution/LocalTaskRunner.js';
+import { workspaceSetDatasetByHash } from '../../trees.js';
+import { parsePathString } from '../../dataflow.js';
+import { WorkspaceLockError, DataflowAbortedError } from '../../errors.js';
+import { stateToStatus } from './interfaces.js';
+import { stepInitialize, stepGetReady, stepPrepareTask, stepTaskStarted, stepTaskCompleted, stepTaskFailed, stepTasksSkipped, stepIsComplete, stepFinalize, stepCancel, } from '../steps.js';
+/**
+ * Simple async mutex to serialize workspace state updates.
+ *
+ * When multiple tasks complete concurrently, their workspace writes must be
+ * serialized to prevent race conditions (read-modify-write on the workspace
+ * root hash). This mutex ensures only one update runs at a time.
+ */
+class AsyncMutex {
+    queue = [];
+    locked = false;
+    /**
+     * Acquire the mutex, execute the callback, then release.
+     * If the mutex is already held, waits until it's available.
+     */
+    async runExclusive(fn) {
+        await this.acquire();
+        try {
+            return await fn();
+        }
+        finally {
+            this.release();
+        }
+    }
+    acquire() {
+        return new Promise((resolve) => {
+            if (!this.locked) {
+                this.locked = true;
+                resolve();
+            }
+            else {
+                this.queue.push(resolve);
+            }
+        });
+    }
+    release() {
+        const next = this.queue.shift();
+        if (next) {
+            next();
+        }
+        else {
+            this.locked = false;
+        }
+    }
+}
+/**
+ * Local orchestrator for in-process dataflow execution.
+ *
+ * @remarks
+ * - Uses step functions for each operation
+ * - Serializes workspace writes with AsyncMutex
+ * - Supports AbortSignal for cancellation
+ * - Persists state through the provided state store
+ */
+export class LocalOrchestrator {
+    stateStore;
+    executions = new Map();
+    /**
+     * Create a new LocalOrchestrator.
+     *
+     * @param stateStore - Optional state store for persistence.
+     *   If not provided, state is only kept in memory.
+     */
+    constructor(stateStore) {
+        this.stateStore = stateStore;
+    }
+    async start(storage, repo, workspace, options = {}) {
+        // Acquire lock if not provided externally
+        const externalLock = !!options.lock;
+        const lock = options.lock ?? await storage.locks.acquire(repo, workspace, variant('dataflow', null));
+        if (!lock) {
+            throw new WorkspaceLockError(workspace);
+        }
+        try {
+            // Get next execution ID from state store if available
+            const executionId = this.stateStore
+                ? await this.stateStore.nextExecutionId(repo, workspace)
+                : String(Date.now()); // Fallback to timestamp if no state store
+            // Initialize execution state
+            const { state, readyTasks: _ } = await stepInitialize(storage, repo, workspace, executionId, {
+                concurrency: options.concurrency,
+                force: options.force,
+                filter: options.filter,
+            });
+            // Persist initial state
+            if (this.stateStore) {
+                await this.stateStore.create(state);
+            }
+            // Create completion promise
+            let resolveCompletion;
+            let rejectCompletion;
+            const completionPromise = new Promise((resolve, reject) => {
+                resolveCompletion = resolve;
+                rejectCompletion = reject;
+            });
+            // Create running execution state
+            const execution = {
+                state,
+                lock,
+                externalLock,
+                options,
+                mutex: new AsyncMutex(),
+                aborted: false,
+                runningTasks: new Map(),
+                completionPromise,
+                resolveCompletion,
+                rejectCompletion,
+            };
+            const key = this.executionKey(repo, workspace, executionId);
+            this.executions.set(key, execution);
+            // Listen for abort signal to persist cancellation immediately.
+            // This ensures the "cancelled" status survives even if the process
+            // is killed (e.g., repeated Ctrl-C) before the loop can persist.
+            if (options.signal) {
+                const onAbort = () => {
+                    execution.aborted = true;
+                    if (this.stateStore) {
+                        // Fire-and-forget: best-effort immediate persistence
+                        void this.stateStore.updateStatus(repo, workspace, executionId, 'cancelled', { error: 'Execution was cancelled' }).catch(() => { });
+                    }
+                };
+                options.signal.addEventListener('abort', onAbort, { once: true });
+            }
+            // Start the execution loop (non-blocking)
+            this.runExecutionLoop(storage, repo, execution).catch(err => {
+                rejectCompletion(err);
+            });
+            return { id: executionId, repo, workspace };
+        }
+        catch (err) {
+            // Release lock on initialization failure (if we acquired it)
+            if (!externalLock) {
+                await lock.release();
+            }
+            throw err;
+        }
+    }
+    async wait(handle) {
+        const key = this.executionKey(handle.repo, handle.workspace, handle.id);
+        const execution = this.executions.get(key);
+        if (!execution) {
+            throw new Error(`Execution ${handle.id} not found for workspace '${handle.workspace}'`);
+        }
+        return execution.completionPromise;
+    }
+    async getStatus(handle) {
+        const key = this.executionKey(handle.repo, handle.workspace, handle.id);
+        const execution = this.executions.get(key);
+        if (!execution) {
+            // Try to read from state store
+            if (this.stateStore) {
+                const state = await this.stateStore.read(handle.repo, handle.workspace, handle.id);
+                if (state) {
+                    return stateToStatus(state);
+                }
+            }
+            throw new Error(`Execution ${handle.id} not found for workspace '${handle.workspace}'`);
+        }
+        return stateToStatus(execution.state);
+    }
+    async cancel(handle) {
+        const key = this.executionKey(handle.repo, handle.workspace, handle.id);
+        const execution = this.executions.get(key);
+        if (!execution) {
+            throw new Error(`Execution ${handle.id} not found for workspace '${handle.workspace}'`);
+        }
+        execution.aborted = true;
+        // Persist cancellation immediately so it survives process crashes.
+        // The execution loop will also detect the abort and clean up gracefully.
+        if (this.stateStore) {
+            await this.stateStore.updateStatus(handle.repo, handle.workspace, handle.id, 'cancelled', { error: 'Execution was cancelled' });
+        }
+    }
+    async getEvents(handle, sinceSeq) {
+        if (!this.stateStore) {
+            return [];
+        }
+        return this.stateStore.getEventsSince(handle.repo, handle.workspace, handle.id, sinceSeq);
+    }
+    /**
+     * Main execution loop.
+     *
+     * Uses step functions to execute tasks, managing concurrency and
+     * workspace state updates.
+     */
+    async runExecutionLoop(storage, repo, execution) {
+        const { state, options, mutex } = execution;
+        try {
+            let hasFailure = false;
+            // Check for abort signal from options
+            const checkAborted = () => {
+                if (options.signal?.aborted && !execution.aborted) {
+                    execution.aborted = true;
+                }
+                return execution.aborted;
+            };
+            while (true) {
+                // Check if we're done
+                if (execution.runningTasks.size === 0 && stepIsComplete(state)) {
+                    break;
+                }
+                // Get ready tasks
+                const readyTasks = stepGetReady(state);
+                // Launch tasks up to concurrency limit if no failure and not aborted
+                const concurrencyLimit = Number(state.concurrency);
+                while (!hasFailure &&
+                    !checkAborted() &&
+                    readyTasks.length > 0 &&
+                    execution.runningTasks.size < concurrencyLimit) {
+                    const taskName = readyTasks.shift();
+                    const taskState = state.tasks.get(taskName);
+                    if (!taskState || taskState.status === 'in_progress' || taskState.status === 'completed') {
+                        continue;
+                    }
+                    // Prepare task (resolve inputs, check cache)
+                    const prepared = await stepPrepareTask(storage, state, taskName);
+                    // Check cache
+                    if (prepared.cachedOutputHash !== null) {
+                        // Cache hit - handle synchronously within mutex
+                        await mutex.runExclusive(async () => {
+                            stepTaskCompleted(state, taskName, prepared.cachedOutputHash, true, 0);
+                            // Notify callback
+                            options.onTaskComplete?.({
+                                name: taskName,
+                                cached: true,
+                                state: 'success',
+                                duration: 0,
+                            });
+                            // Update state store (events are added by step function)
+                            if (this.stateStore) {
+                                await this.stateStore.update(state);
+                            }
+                        });
+                        continue;
+                    }
+                    // Mark as started (event added by step function)
+                    stepTaskStarted(state, taskName);
+                    if (this.stateStore) {
+                        await this.stateStore.update(state);
+                    }
+                    options.onTaskStart?.(taskName);
+                    // Launch task execution
+                    const taskPromise = this.executeTask(storage, repo, execution, taskName, prepared).then(async (result) => {
+                        // Handle task completion within mutex
+                        await mutex.runExclusive(async () => {
+                            if (result.state === 'success') {
+                                const outputPath = parsePathString(prepared.outputPath);
+                                if (result.outputHash) {
+                                    await workspaceSetDatasetByHash(storage, repo, state.workspace, outputPath, result.outputHash);
+                                }
+                                stepTaskCompleted(state, taskName, result.outputHash ?? '', result.cached, result.duration);
+                                options.onTaskComplete?.({
+                                    name: taskName,
+                                    cached: result.cached,
+                                    state: 'success',
+                                    duration: result.duration,
+                                });
+                            }
+                            else {
+                                hasFailure = true;
+                                const { result: failedResult } = stepTaskFailed(state, taskName, result.error, result.exitCode, result.duration);
+                                options.onTaskComplete?.({
+                                    name: taskName,
+                                    cached: false,
+                                    state: result.state === 'failed' ? 'failed' : 'error',
+                                    error: result.error,
+                                    exitCode: result.exitCode,
+                                    duration: result.duration,
+                                });
+                                // Skip dependents (events added by step function)
+                                const skipEvents = stepTasksSkipped(state, failedResult.toSkip, taskName);
+                                for (const skipEvent of skipEvents) {
+                                    // skipEvents are always task_skipped events
+                                    if (skipEvent.type === 'task_skipped') {
+                                        options.onTaskComplete?.({
+                                            name: skipEvent.value.task,
+                                            cached: false,
+                                            state: 'skipped',
+                                            duration: 0,
+                                        });
+                                    }
+                                }
+                            }
+                            // Update state store
+                            if (this.stateStore) {
+                                await this.stateStore.update(state);
+                            }
+                        });
+                    }).finally(() => {
+                        execution.runningTasks.delete(taskName);
+                    });
+                    execution.runningTasks.set(taskName, taskPromise);
+                }
+                // Wait for at least one task to complete if we can't launch more
+                if (execution.runningTasks.size > 0) {
+                    await Promise.race(execution.runningTasks.values());
+                }
+                else if (readyTasks.length === 0 || checkAborted() || hasFailure) {
+                    break;
+                }
+            }
+            // Wait for any remaining tasks
+            if (execution.runningTasks.size > 0) {
+                await Promise.all(execution.runningTasks.values());
+            }
+            // Check for abort one final time
+            if (checkAborted()) {
+                stepCancel(state, 'Execution was aborted');
+                if (this.stateStore) {
+                    await this.stateStore.update(state);
+                }
+                // Build partial results for abort error
+                const partialResults = this.buildPartialResults(state);
+                throw new DataflowAbortedError(partialResults);
+            }
+            // Finalize (event added by step function)
+            const { result } = stepFinalize(state);
+            if (this.stateStore) {
+                await this.stateStore.update(state);
+            }
+            execution.resolveCompletion(result);
+        }
+        finally {
+            // Release lock if we acquired it
+            if (!execution.externalLock) {
+                await execution.lock.release();
+            }
+            // Clean up execution state
+            const key = this.executionKey(repo, state.workspace, state.id);
+            this.executions.delete(key);
+        }
+    }
+    /**
+     * Execute a single task.
+     */
+    async executeTask(storage, repo, execution, taskName, prepared) {
+        const { options } = execution;
+        const startTime = Date.now();
+        const execOptions = {
+            force: execution.state.force,
+            signal: options.signal,
+            onStdout: options.onStdout ? (data) => options.onStdout(taskName, data) : undefined,
+            onStderr: options.onStderr ? (data) => options.onStderr(taskName, data) : undefined,
+        };
+        // Use provided runner if available, otherwise call taskExecute directly
+        if (options.runner) {
+            const result = await options.runner.execute(storage, prepared.taskHash, prepared.inputHashes, execOptions);
+            return {
+                state: result.state,
+                cached: result.cached,
+                outputHash: result.outputHash,
+                exitCode: result.exitCode,
+                error: result.error,
+                duration: Date.now() - startTime,
+            };
+        }
+        else {
+            const result = await taskExecute(storage, repo, prepared.taskHash, prepared.inputHashes, execOptions);
+            return {
+                state: result.state,
+                cached: result.cached,
+                outputHash: result.outputHash ?? undefined,
+                exitCode: result.exitCode ?? undefined,
+                error: result.error ?? undefined,
+                duration: Date.now() - startTime,
+            };
+        }
+    }
+    /**
+     * Build partial results for abort error.
+     */
+    buildPartialResults(state) {
+        const results = [];
+        for (const [name, taskState] of state.tasks) {
+            if (taskState.status === 'completed' || taskState.status === 'failed' || taskState.status === 'skipped') {
+                // Extract values from Option types
+                const cached = taskState.cached.type === 'some' ? taskState.cached.value : false;
+                const error = taskState.error.type === 'some' ? taskState.error.value : undefined;
+                const exitCode = taskState.exitCode.type === 'some' ? Number(taskState.exitCode.value) : undefined;
+                const duration = taskState.duration.type === 'some' ? Number(taskState.duration.value) : 0;
+                results.push({
+                    name,
+                    cached,
+                    state: taskState.status === 'completed' ? 'success' : taskState.status,
+                    error,
+                    exitCode,
+                    duration,
+                });
+            }
+        }
+        return results;
+    }
+    /**
+     * Generate unique key for an execution.
+     */
+    executionKey(repo, workspace, id) {
+        return `${repo}::${workspace}:${id}`;
+    }
+}
+//# sourceMappingURL=LocalOrchestrator.js.map

package/dist/src/dataflow/orchestrator/LocalOrchestrator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocalOrchestrator.js","sourceRoot":"","sources":["../../../../src/dataflow/orchestrator/LocalOrchestrator.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAGxC,OAAO,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAC;AACjE,OAAO,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAQ3E,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAOhD,OAAO,EACL,cAAc,EACd,YAAY,EACZ,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,UAAU,GACX,MAAM,aAAa,CAAC;AAErB;;;;;;GAMG;AACH,MAAM,UAAU;IACN,KAAK,GAAsB,EAAE,CAAC;IAC9B,MAAM,GAAG,KAAK,CAAC;IAEvB;;;OAGG;IACH,KAAK,CAAC,YAAY,CAAI,EAAW;QAC/B,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACrB,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,CAAC;IACH,CAAC;IAEO,OAAO;QACb,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;YAC7B,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;gBACjB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;gBACnB,OAAO,EAAE,CAAC;YACZ,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC3B,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAEO,OAAO;QACb,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QAChC,IAAI,IAAI,EAAE,CAAC;YACT,IAAI,EAAE,CAAC;QACT,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACtB,CAAC;IACH,CAAC;CACF;AAkBD;;;;;;;;GAQG;AACH,MAAM,OAAO,iBAAiB;IASC;IARrB,UAAU,GAAG,IAAI,GAAG,EAA4B,CAAC;IAEzD;;;;;OAKG;IACH,YAA6B,UAAgC;QAAhC,eAAU,GAAV,UAAU,CAAsB;IAAG,CAAC;IAEjE,KAAK,CAAC,KAAK,CACT,OAAuB,EACvB,IAAY,EACZ,SAAiB,EACjB,UAAoC,EAAE;QAEtC,0CAA0C;QAC1C,MAAM,YAAY,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC;QACpC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,MAAM,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC,CAAC;QAErG,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,kBAAkB,CAAC,SAAS,CAAC,CAAC;QAC1C,CAAC;QAED,IAAI,CAAC;YACH,sDAAsD;YACtD,MAAM,WAAW,GAAG,IAAI,CAAC,UAAU;gBACjC,CAAC,CAAC,MAAM,IAAI,CAAC,UAAU,CAAC,eAAe,CAAC,IAAI,EAAE,SAAS,CAAC;gBACxD,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,0CAA0C;YAElE,6BAA6B;YAC7B,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,EAAE,GAAG,MAAM,cAAc,CACnD,OAAO,EACP,IAAI,EACJ,SAAS,EACT,WAAW,EACX;gBACE,WAAW,EAAE,OAAO,CAAC,WAAW;gBAChC,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,MAAM,EAAE,OAAO,CAAC,MAAM;aACvB,CACF,CAAC;YAEF,wBAAwB;YACxB,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;gBACpB,MAAM,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACtC,CAAC;YAED,4BAA4B;YAC5B,IAAI,iBAAoD,CAAC;YACzD,IAAI,gBAAyC,CAAC;YAC9C,MAAM,iBAAiB,GAAG,IAAI,OAAO,CAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBACxE,iBAAiB,GAAG,OAAO,CAAC;gBAC5B,gBAAgB,GAAG,MAAM,CAAC;YAC5B,CAAC,CAAC,CAAC;YAEH,iCAAiC;YACjC,MAAM,SAAS,GAAqB;gBAClC,KAAK;gBACL,IAAI;gBACJ,YAAY;gBACZ,OAAO;gBACP,KAAK,EAAE,IAAI,UAAU,EAAE;gBACvB,OAAO,EAAE,KAAK;gBACd,YAAY,EAAE,IAAI,GAAG,EAAE;gBACvB,iBAAiB;gBACjB,iBAAiB;gBACjB,gBAAgB;aACjB,CAAC;YAEF,MAAM,GAAG,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,SAAS,EAAE,WAAW,CAAC,CAAC;YAC5D,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;YAEpC,+DAA+D;YAC/D,mEAAmE;YACnE,iEAAiE;YACjE,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;gBACnB,MAAM,OAAO,GAAG,GAAG,EAAE;oBACnB,SAAS,CAAC,OAAO,GAAG,IAAI,CAAC;oBACzB,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;wBACpB,qDAAqD;wBACrD,KAAK,IAAI,CAAC,UAAU,CAAC,YAAY,CAC/B,IAAI,EACJ,SAAS,EACT,WAAW,EACX,WAAW,EACX,EAAE,KAAK,EAAE,yBAAyB,EAAE,CACrC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAuC,CAAC,CAAC,CAAC;oBACzD,CAAC;gBACH,CAAC,CAAC;gBACF,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YACpE,CAAC;YAED,0CAA0C;YAC1C,IAAI,CAAC,gBAAgB,CAAC,OAAO,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE;gBAC1D,gBAAgB,CAAC,GAAG,CAAC,CAAC;YACxB,CAAC,CAAC,CAAC;YAEH,OAAO,EAAE,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QAC9C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,6DAA6D;YAC7D,IAAI,CAAC,YAAY,EAAE,CAAC;gBAClB,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;YACvB,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,MAAuB;QAChC,MAAM,GAAG,GAAG,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;QACxE,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAE3C,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,aAAa,MAAM,CAAC,EAAE,6BAA6B,MAAM,CAAC,SAAS,GAAG,CAAC,CAAC;QAC1F,CAAC;QAED,OAAO,SAAS,CAAC,iBAAiB,CAAC;IACrC,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,MAAuB;QACrC,MAAM,GAAG,GAAG,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;QACxE,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAE3C,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,+BAA+B;YAC/B,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;gBACpB,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;gBACnF,IAAI,KAAK,EAAE,CAAC;oBACV,OAAO,aAAa,CAAC,KAAK,CAAC,CAAC;gBAC9B,CAAC;YACH,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,aAAa,MAAM,CAAC,EAAE,6BAA6B,MAAM,CAAC,SAAS,GAAG,CAAC,CAAC;QAC1F,CAAC;QAED,OAAO,aAAa,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACxC,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,MAAuB;QAClC,MAAM,GAAG,GAAG,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;QACxE,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAE3C,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,aAAa,MAAM,CAAC,EAAE,6BAA6B,MAAM,CAAC,SAAS,GAAG,CAAC,CAAC;QAC1F,CAAC;QAED,SAAS,CAAC,OAAO,GAAG,IAAI,CAAC;QAEzB,mEAAmE;QACnE,yEAAyE;QACzE,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACpB,MAAM,IAAI,CAAC,UAAU,CAAC,YAAY,CAChC,MAAM,CAAC,IAAI,EACX,MAAM,CAAC,SAAS,EAChB,MAAM,CAAC,EAAE,EACT,WAAW,EACX,EAAE,KAAK,EAAE,yBAAyB,EAAE,CACrC,CAAC;QACJ,CAAC;IACH,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,MAAuB,EAAE,QAAgB;QACvD,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;YACrB,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,OAAO,IAAI,CAAC,UAAU,CAAC,cAAc,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;IAC5F,CAAC;IAED;;;;;OAKG;IACK,KAAK,CAAC,gBAAgB,CAC5B,OAAuB,EACvB,IAAY,EACZ,SAA2B;QAE3B,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,SAAS,CAAC;QAE5C,IAAI,CAAC;YACH,IAAI,UAAU,GAAG,KAAK,CAAC;YAEvB,sCAAsC;YACtC,MAAM,YAAY,GAAG,GAAG,EAAE;gBACxB,IAAI,OAAO,CAAC,MAAM,EAAE,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;oBAClD,SAAS,CAAC,OAAO,GAAG,IAAI,CAAC;gBAC3B,CAAC;gBACD,OAAO,SAAS,CAAC,OAAO,CAAC;YAC3B,CAAC,CAAC;YAEF,OAAO,IAAI,EAAE,CAAC;gBACZ,sBAAsB;gBACtB,IAAI,SAAS,CAAC,YAAY,CAAC,IAAI,KAAK,CAAC,IAAI,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;oBAC/D,MAAM;gBACR,CAAC;gBAED,kBAAkB;gBAClB,MAAM,UAAU,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;gBAEvC,qEAAqE;gBACrE,MAAM,gBAAgB,GAAG,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;gBACnD,OACE,CAAC,UAAU;oBACX,CAAC,YAAY,EAAE;oBACf,UAAU,CAAC,MAAM,GAAG,CAAC;oBACrB,SAAS,CAAC,YAAY,CAAC,IAAI,GAAG,gBAAgB,EAC9C,CAAC;oBACD,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,EAAG,CAAC;oBACrC,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;oBAE5C,IAAI,CAAC,SAAS,IAAI,SAAS,CAAC,MAAM,KAAK,aAAa,IAAI,SAAS,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;wBACzF,SAAS;oBACX,CAAC;oBAED,6CAA6C;oBAC7C,MAAM,QAAQ,GAAG,MAAM,eAAe,CAAC,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;oBAEjE,cAAc;oBACd,IAAI,QAAQ,CAAC,gBAAgB,KAAK,IAAI,EAAE,CAAC;wBACvC,gDAAgD;wBAChD,MAAM,KAAK,CAAC,YAAY,CAAC,KAAK,IAAI,EAAE;4BAClC,iBAAiB,CACf,KAAK,EACL,QAAQ,EACR,QAAQ,CAAC,gBAAiB,EAC1B,IAAI,EACJ,CAAC,CACF,CAAC;4BAEF,kBAAkB;4BAClB,OAAO,CAAC,cAAc,EAAE,CAAC;gCACvB,IAAI,EAAE,QAAQ;gCACd,MAAM,EAAE,IAAI;gCACZ,KAAK,EAAE,SAAS;gCAChB,QAAQ,EAAE,CAAC;6BACZ,CAAC,CAAC;4BAEH,yDAAyD;4BACzD,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;gCACpB,MAAM,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;4BACtC,CAAC;wBACH,CAAC,CAAC,CAAC;wBACH,SAAS;oBACX,CAAC;oBAED,iDAAiD;oBACjD,eAAe,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;oBACjC,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;wBACpB,MAAM,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;oBACtC,CAAC;oBACD,OAAO,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,CAAC;oBAEhC,wBAAwB;oBACxB,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,CAClC,OAAO,EACP,IAAI,EACJ,SAAS,EACT,QAAQ,EACR,QAAQ,CACT,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE;wBACtB,sCAAsC;wBACtC,MAAM,KAAK,CAAC,YAAY,CAAC,KAAK,IAAI,EAAE;4BAClC,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;gCAC/B,MAAM,UAAU,GAAG,eAAe,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;gCACxD,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;oCACtB,MAAM,yBAAyB,CAC7B,OAAO,EACP,IAAI,EACJ,KAAK,CAAC,SAAS,EACf,UAAU,EACV,MAAM,CAAC,UAAU,CAClB,CAAC;gCACJ,CAAC;gCAED,iBAAiB,CACf,KAAK,EACL,QAAQ,EACR,MAAM,CAAC,UAAU,IAAI,EAAE,EACvB,MAAM,CAAC,MAAM,EACb,MAAM,CAAC,QAAQ,CAChB,CAAC;gCAEF,OAAO,CAAC,cAAc,EAAE,CAAC;oCACvB,IAAI,EAAE,QAAQ;oCACd,MAAM,EAAE,MAAM,CAAC,MAAM;oCACrB,KAAK,EAAE,SAAS;oCAChB,QAAQ,EAAE,MAAM,CAAC,QAAQ;iCAC1B,CAAC,CAAC;4BACL,CAAC;iCAAM,CAAC;gCACN,UAAU,GAAG,IAAI,CAAC;gCAElB,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,GAAG,cAAc,CAC7C,KAAK,EACL,QAAQ,EACR,MAAM,CAAC,KAAK,EACZ,MAAM,CAAC,QAAQ,EACf,MAAM,CAAC,QAAQ,CAChB,CAAC;gCAEF,OAAO,CAAC,cAAc,EAAE,CAAC;oCACvB,IAAI,EAAE,QAAQ;oCACd,MAAM,EAAE,KAAK;oCACb,KAAK,EAAE,MAAM,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO;oCACrD,KAAK,EAAE,MAAM,CAAC,KAAK;oCACnB,QAAQ,EAAE,MAAM,CAAC,QAAQ;oCACzB,QAAQ,EAAE,MAAM,CAAC,QAAQ;iCAC1B,CAAC,CAAC;gCAEH,kDAAkD;gCAClD,MAAM,UAAU,GAAG,gBAAgB,CAAC,KAAK,EAAE,YAAY,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;gCAC1E,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;oCACnC,4CAA4C;oCAC5C,IAAI,SAAS,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;wCACtC,OAAO,CAAC,cAAc,EAAE,CAAC;4CACvB,IAAI,EAAE,SAAS,CAAC,KAAK,CAAC,IAAI;4CAC1B,MAAM,EAAE,KAAK;4CACb,KAAK,EAAE,SAAS;4CAChB,QAAQ,EAAE,CAAC;yCACZ,CAAC,CAAC;oCACL,CAAC;gCACH,CAAC;4BACH,CAAC;4BAED,qBAAqB;4BACrB,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;gCACpB,MAAM,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;4BACtC,CAAC;wBACH,CAAC,CAAC,CAAC;oBACL,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE;wBACd,SAAS,CAAC,YAAY,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;oBAC1C,CAAC,CAAC,CAAC;oBAEH,SAAS,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;gBACpD,CAAC;gBAED,iEAAiE;gBACjE,IAAI,SAAS,CAAC,YAAY,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;oBACpC,MAAM,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC;gBACtD,CAAC;qBAAM,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,IAAI,YAAY,EAAE,IAAI,UAAU,EAAE,CAAC;oBACnE,MAAM;gBACR,CAAC;YACH,CAAC;YAED,+BAA+B;YAC/B,IAAI,SAAS,CAAC,YAAY,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;gBACpC,MAAM,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC;YACrD,CAAC;YAED,iCAAiC;YACjC,IAAI,YAAY,EAAE,EAAE,CAAC;gBACnB,UAAU,CAAC,KAAK,EAAE,uBAAuB,CAAC,CAAC;gBAC3C,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;oBACpB,MAAM,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBACtC,CAAC;gBAED,wCAAwC;gBACxC,MAAM,cAAc,GAAG,IAAI,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC;gBACvD,MAAM,IAAI,oBAAoB,CAAC,cAAc,CAAC,CAAC;YACjD,CAAC;YAED,0CAA0C;YAC1C,MAAM,EAAE,MAAM,EAAE,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;YACvC,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;gBACpB,MAAM,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACtC,CAAC;YAED,SAAS,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC;QACtC,CAAC;gBAAS,CAAC;YACT,iCAAiC;YACjC,IAAI,CAAC,SAAS,CAAC,YAAY,EAAE,CAAC;gBAC5B,MAAM,SAAS,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YACjC,CAAC;YAED,2BAA2B;YAC3B,MAAM,GAAG,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC;YAC/D,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,WAAW,CACvB,OAAuB,EACvB,IAAY,EACZ,SAA2B,EAC3B,QAAgB,EAChB,QAAqD;QASrD,MAAM,EAAE,OAAO,EAAE,GAAG,SAAS,CAAC;QAC9B,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAE7B,MAAM,WAAW,GAAuB;YACtC,KAAK,EAAE,SAAS,CAAC,KAAK,CAAC,KAAK;YAC5B,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,QAAS,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;YACpF,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,QAAS,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;SACrF,CAAC;QAEF,wEAAwE;QACxE,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YACnB,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;YAC3G,OAAO;gBACL,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,UAAU,EAAE,MAAM,CAAC,UAAU;gBAC7B,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;aACjC,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;YACtG,OAAO;gBACL,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,SAAS;gBAC1C,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,SAAS;gBACtC,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,SAAS;gBAChC,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;aACjC,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;OAEG;IACK,mBAAmB,CAAC,KAA6B;QACvD,MAAM,OAAO,GAA0B,EAAE,CAAC;QAE1C,KAAK,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;YAC5C,IAAI,SAAS,CAAC,MAAM,KAAK,WAAW,IAAI,SAAS,CAAC,MAAM,KAAK,QAAQ,IAAI,SAAS,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;gBACxG,mCAAmC;gBACnC,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC;gBACjF,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;gBAClF,MAAM,QAAQ,GAAG,SAAS,CAAC,QAAQ,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;gBACnG,MAAM,QAAQ,GAAG,SAAS,CAAC,QAAQ,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;gBAE3F,OAAO,CAAC,IAAI,CAAC;oBACX,IAAI;oBACJ,MAAM;oBACN,KAAK,EAAE,SAAS,CAAC,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM;oBACtE,KAAK;oBACL,QAAQ;oBACR,QAAQ;iBACT,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;OAEG;IACK,YAAY,CAAC,IAAY,EAAE,SAAiB,EAAE,EAAU;QAC9D,OAAO,GAAG,IAAI,KAAK,SAAS,IAAI,EAAE,EAAE,CAAC;IACvC,CAAC;CACF"}

package/dist/src/dataflow/orchestrator/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * Orchestrator implementations for dataflow execution.
+ *
+ * @packageDocumentation
+ */
+export * from './interfaces.js';
+export * from './LocalOrchestrator.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/dataflow/orchestrator/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/dataflow/orchestrator/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;GAIG;AAEH,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC"}

package/dist/src/dataflow/orchestrator/index.js

@@ -0,0 +1,12 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * Orchestrator implementations for dataflow execution.
+ *
+ * @packageDocumentation
+ */
+export * from './interfaces.js';
+export * from './LocalOrchestrator.js';
+//# sourceMappingURL=index.js.map

package/dist/src/dataflow/orchestrator/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/dataflow/orchestrator/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;GAIG;AAEH,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC"}

package/dist/src/dataflow/orchestrator/interfaces.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * Orchestrator interface for dataflow execution.
+ *
+ * Abstracts the execution loop, enabling:
+ * - LocalOrchestrator: In-process async loop with mutex
+ * - StepFunctionsOrchestrator: AWS Step Functions state machine (in e3-aws)
+ */
+import type { StorageBackend, LockHandle } from '../../storage/interfaces.js';
+import type { TaskRunner } from '../../execution/interfaces.js';
+import type { DataflowExecutionState, ExecutionEvent, FinalizeResult } from '../types.js';
+/**
+ * Handle to a running dataflow execution.
+ */
+export interface ExecutionHandle {
+    /** Unique execution ID (string for UUID support) */
+    readonly id: string;
+    /** Repository identifier */
+    readonly repo: string;
+    /** Workspace name */
+    readonly workspace: string;
+}
+/**
+ * Status of a dataflow execution (summary view).
+ */
+export interface ExecutionStatus {
+    /** Execution ID (string for UUID support) */
+    id: string;
+    /** Current state */
+    state: 'running' | 'completed' | 'failed' | 'cancelled';
+    /** Tasks that have completed successfully */
+    completed: string[];
+    /** Tasks currently running */
+    running: string[];
+    /** Tasks waiting to run */
+    pending: string[];
+    /** Tasks that failed */
+    failed: string[];
+    /** Tasks skipped due to upstream failure */
+    skipped: string[];
+    /** Error message if state is 'failed' */
+    error?: string;
+    /** Start time */
+    startedAt: Date;
+    /** Completion time */
+    completedAt?: Date;
+}
+/**
+ * Options for starting a dataflow execution.
+ */
+export interface OrchestratorStartOptions {
+    /** Maximum concurrent task executions (default: 4) */
+    concurrency?: number;
+    /** Force re-execution even if cached (default: false) */
+    force?: boolean;
+    /** Filter to run only specific task(s) by exact name */
+    filter?: string;
+    /** AbortSignal for cancellation */
+    signal?: AbortSignal;
+    /** External lock handle (if caller manages locking) */
+    lock?: LockHandle;
+    /** Task runner for executing individual tasks */
+    runner?: TaskRunner;
+    /** Callback when a task starts */
+    onTaskStart?: (name: string) => void;
+    /** Callback when a task completes */
+    onTaskComplete?: (result: TaskCompletedCallback) => void;
+    /** Callback for task stdout */
+    onStdout?: (taskName: string, data: string) => void;
+    /** Callback for task stderr */
+    onStderr?: (taskName: string, data: string) => void;
+}
+/**
+ * Callback data for task completion.
+ */
+export interface TaskCompletedCallback {
+    /** Task name */
+    name: string;
+    /** Whether the task was cached */
+    cached: boolean;
+    /** Final state */
+    state: 'success' | 'failed' | 'error' | 'skipped';
+    /** Error message if state is 'error' */
+    error?: string;
+    /** Exit code if state is 'failed' */
+    exitCode?: number;
+    /** Duration in milliseconds */
+    duration: number;
+}
+/**
+ * Interface for dataflow orchestration.
+ *
+ * Orchestrators manage the execution loop, calling step functions in sequence
+ * and handling concurrency, cancellation, and state persistence.
+ */
+export interface DataflowOrchestrator {
+    /**
+     * Start a dataflow execution.
+     *
+     * Acquires the workspace lock (if not provided) and begins execution.
+     * Returns immediately with a handle that can be used to monitor progress.
+     *
+     * @param storage - Storage backend
+     * @param repo - Repository identifier
+     * @param workspace - Workspace name
+     * @param options - Execution options
+     * @returns Execution handle
+     *
+     * @throws {WorkspaceNotFoundError} If workspace doesn't exist
+     * @throws {WorkspaceNotDeployedError} If workspace has no package deployed
+     * @throws {WorkspaceLockError} If workspace is locked by another process
+     */
+    start(storage: StorageBackend, repo: string, workspace: string, options?: OrchestratorStartOptions): Promise<ExecutionHandle>;
+    /**
+     * Wait for a dataflow execution to complete.
+     *
+     * Blocks until the execution completes (success, failure, or cancellation).
+     *
+     * @param handle - Execution handle from start()
+     * @returns Final result
+     */
+    wait(handle: ExecutionHandle): Promise<FinalizeResult>;
+    /**
+     * Get the current status of a dataflow execution.
+     *
+     * @param handle - Execution handle from start()
+     * @returns Current status
+     */
+    getStatus(handle: ExecutionHandle): Promise<ExecutionStatus>;
+    /**
+     * Cancel a running dataflow execution.
+     *
+     * Running tasks will be terminated. The execution will transition to
+     * 'cancelled' state.
+     *
+     * @param handle - Execution handle from start()
+     */
+    cancel(handle: ExecutionHandle): Promise<void>;
+    /**
+     * Get events for a dataflow execution since a given sequence number.
+     *
+     * Used for polling/watching execution progress.
+     *
+     * @param handle - Execution handle from start()
+     * @param sinceSeq - Only return events with seq > sinceSeq
+     * @returns Array of events in sequence order
+     */
+    getEvents(handle: ExecutionHandle, sinceSeq: number): Promise<ExecutionEvent[]>;
+}
+/**
+ * Convert execution state to status summary.
+ */
+export declare function stateToStatus(state: DataflowExecutionState): ExecutionStatus;
+//# sourceMappingURL=interfaces.d.ts.map

package/dist/src/dataflow/orchestrator/interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../../../../src/dataflow/orchestrator/interfaces.ts"],"names":[],"mappings":"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"}