@elaraai/e3-core 0.0.2-beta.4 → 0.0.2-beta.40

package/dist/src/execution/MockTaskRunner.js

@@ -0,0 +1,54 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * TaskRunner mock for testing dataflow orchestration without spawning processes.
+ *
+ * Allows configuring responses per task and records all calls for assertions.
+ */
+export class MockTaskRunner {
+    results = new Map();
+    calls = [];
+    defaultResult = { state: 'success', cached: false, outputHash: 'mock-hash' };
+    /**
+     * Set result for a specific task hash.
+     *
+     * @param taskHash - The task hash to configure
+     * @param result - Either a static TaskResult or a function that computes result from inputHashes
+     */
+    setResult(taskHash, result) {
+        this.results.set(taskHash, result);
+    }
+    /**
+     * Set default result for tasks without specific results configured.
+     *
+     * @param result - The default TaskResult to return
+     */
+    setDefaultResult(result) {
+        this.defaultResult = result;
+    }
+    /**
+     * Get all recorded calls.
+     *
+     * @returns Readonly array of all execute() calls
+     */
+    getCalls() {
+        return this.calls;
+    }
+    /**
+     * Clear recorded calls.
+     */
+    clearCalls() {
+        this.calls = [];
+    }
+    async execute(_storage, taskHash, inputHashes, options) {
+        this.calls.push({ taskHash, inputHashes, options });
+        const configured = this.results.get(taskHash);
+        if (configured) {
+            return typeof configured === 'function' ? await configured(inputHashes) : configured;
+        }
+        return this.defaultResult;
+    }
+}
+//# sourceMappingURL=MockTaskRunner.js.map

package/dist/src/execution/MockTaskRunner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MockTaskRunner.js","sourceRoot":"","sources":["../../../src/execution/MockTaskRunner.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAcH;;;;GAIG;AACH,MAAM,OAAO,cAAc;IACjB,OAAO,GAAG,IAAI,GAAG,EAAsF,CAAC;IACxG,KAAK,GAAmB,EAAE,CAAC;IAC3B,aAAa,GAAe,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,CAAC;IAEjG;;;;;OAKG;IACH,SAAS,CAAC,QAAgB,EAAE,MAAkF;QAC5G,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACrC,CAAC;IAED;;;;OAIG;IACH,gBAAgB,CAAC,MAAkB;QACjC,IAAI,CAAC,aAAa,GAAG,MAAM,CAAC;IAC9B,CAAC;IAED;;;;OAIG;IACH,QAAQ;QACN,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED;;OAEG;IACH,UAAU;QACR,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;IAClB,CAAC;IAED,KAAK,CAAC,OAAO,CACX,QAAwB,EACxB,QAAgB,EAChB,WAAqB,EACrB,OAA4B;QAE5B,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC,CAAC;QAEpD,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC9C,IAAI,UAAU,EAAE,CAAC;YACf,OAAO,OAAO,UAAU,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;QACvF,CAAC;QACD,OAAO,IAAI,CAAC,aAAa,CAAC;IAC5B,CAAC;CACF"}

package/dist/src/execution/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * Execution abstraction layer for e3 dataflow.
+ *
+ * This module provides interfaces that separate orchestration from business
+ * logic, enabling different execution strategies:
+ * - LocalDataflowExecutor: In-process execution with AsyncMutex (CLI, local dev)
+ * - StepFunctionsDataflowExecutor: AWS Step Functions orchestration (cloud)
+ */
+export { type TaskExecuteOptions, type TaskResult, type TaskRunner, type ExecutionHandle, type DataflowStatus, type DataflowExecuteOptions, type DataflowExecuteResult, type DataflowExecutor, type TaskGraph, type DataflowGetGraphFn, type DataflowCheckCacheFn, type DataflowWriteOutputFn, type DataflowGetReadyTasksFn, } from './interfaces.js';
+export { LocalTaskRunner } from './LocalTaskRunner.js';
+export { MockTaskRunner, type MockTaskCall } from './MockTaskRunner.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/execution/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/execution/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;GAOG;AAEH,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,UAAU,EACf,KAAK,UAAU,EAEf,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EAErB,KAAK,SAAS,EAEd,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,uBAAuB,GAC7B,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/src/execution/index.js

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+// TaskRunner implementations
+export { LocalTaskRunner } from './LocalTaskRunner.js';
+export { MockTaskRunner } from './MockTaskRunner.js';
+//# sourceMappingURL=index.js.map

package/dist/src/execution/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/execution/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA+BH,6BAA6B;AAC7B,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAqB,MAAM,qBAAqB,CAAC"}

package/dist/src/execution/interfaces.d.ts

@@ -0,0 +1,246 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * Execution abstraction interfaces for e3 dataflow.
+ *
+ * These interfaces separate orchestration from business logic, enabling:
+ * - LocalDataflowExecutor: In-process execution with AsyncMutex (CLI, local dev)
+ * - StepFunctionsDataflowExecutor: AWS Step Functions orchestration (cloud)
+ *
+ * The core insight: Everything in dataflowExecute() except the processQueue()
+ * loop is pure business logic that both local and cloud execution share.
+ * By extracting these as functions and abstracting the orchestration,
+ * Step Functions can replace the local loop while reusing all e3-core logic.
+ */
+import type { StorageBackend, LockHandle } from '../storage/interfaces.js';
+/**
+ * Options for task execution.
+ */
+export interface TaskExecuteOptions {
+    /** Force execution even if cached */
+    force?: boolean;
+    /** AbortSignal for cancellation */
+    signal?: AbortSignal;
+    /** Callback for stdout data */
+    onStdout?: (data: string) => void;
+    /** Callback for stderr data */
+    onStderr?: (data: string) => void;
+}
+/**
+ * Result of a single task execution.
+ */
+export interface TaskResult {
+    /** Final state */
+    state: 'success' | 'failed' | 'error';
+    /** Whether the result was served from cache */
+    cached: boolean;
+    /** Execution ID (UUIDv7) */
+    executionId?: string;
+    /** Output hash (if state is 'success') */
+    outputHash?: string;
+    /** Exit code (if state is 'failed') */
+    exitCode?: number;
+    /** Error message (if state is 'error') */
+    error?: string;
+}
+/**
+ * Task execution abstraction.
+ *
+ * Implementations:
+ * - LocalTaskRunner: Spawns east-node/east-py/julia processes locally
+ * - LambdaTaskRunner: Dispatches to AWS Lambda
+ * - FargateTaskRunner: Dispatches to AWS Fargate
+ */
+export interface TaskRunner {
+    /**
+     * Execute a task.
+     *
+     * @param storage - Storage backend
+     * @param taskHash - Hash of the TaskObject
+     * @param inputHashes - Hashes of input datasets
+     * @param options - Execution options
+     * @returns Task result
+     */
+    execute(storage: StorageBackend, taskHash: string, inputHashes: string[], options?: TaskExecuteOptions): Promise<TaskResult>;
+}
+/**
+ * Handle to a running dataflow execution.
+ */
+export interface ExecutionHandle {
+    /** Unique execution ID (Local: UUID, Cloud: Step Functions ARN) */
+    readonly id: string;
+}
+/**
+ * Status of a dataflow execution.
+ */
+export interface DataflowStatus {
+    /** 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;
+}
+/**
+ * Options for dataflow execution.
+ */
+export interface DataflowExecuteOptions {
+    /** 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;
+    /** Callback when a task starts */
+    onTaskStart?: (taskName: string) => void;
+    /** Callback when a task completes */
+    onTaskComplete?: (taskName: string, result: TaskResult) => void;
+    /** Callback for task stdout */
+    onStdout?: (taskName: string, data: string) => void;
+    /** Callback for task stderr */
+    onStderr?: (taskName: string, data: string) => void;
+}
+/**
+ * Result of a dataflow execution.
+ */
+export interface DataflowExecuteResult {
+    /** Overall success - true if all tasks completed successfully */
+    success: boolean;
+    /** Number of tasks executed (not from cache) */
+    executed: number;
+    /** Number of tasks served from cache */
+    cached: number;
+    /** Number of tasks that failed */
+    failed: number;
+    /** Number of tasks skipped due to upstream failure */
+    skipped: number;
+    /** Total duration in milliseconds */
+    duration: number;
+}
+/**
+ * Dataflow orchestration abstraction.
+ *
+ * Implementations:
+ * - LocalDataflowExecutor: In-process loop with AsyncMutex
+ * - StepFunctionsDataflowExecutor: AWS Step Functions state machine
+ */
+export interface DataflowExecutor {
+    /**
+     * Start a dataflow execution.
+     *
+     * Returns immediately with a handle. Use getStatus() to poll for completion.
+     *
+     * @param storage - Storage backend
+     * @param workspace - Workspace name
+     * @param options - Execution options
+     * @returns Execution handle
+     */
+    start(storage: StorageBackend, workspace: string, options?: DataflowExecuteOptions): Promise<ExecutionHandle>;
+    /**
+     * Get the status of a dataflow execution.
+     *
+     * @param handle - Execution handle from start()
+     * @returns Current status
+     */
+    getStatus(handle: ExecutionHandle): Promise<DataflowStatus>;
+    /**
+     * 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>;
+    /**
+     * Wait for a dataflow execution to complete.
+     *
+     * @param handle - Execution handle from start()
+     * @returns Final result
+     */
+    wait(handle: ExecutionHandle): Promise<DataflowExecuteResult>;
+}
+/**
+ * Task dependency graph.
+ */
+export interface TaskGraph {
+    /** Map of task name -> task info */
+    tasks: Map<string, {
+        hash: string;
+        inputPaths: string[];
+        outputPath: string;
+        dependencies: string[];
+    }>;
+    /** Map of output path -> producing task name */
+    outputToTask: Map<string, string>;
+}
+/**
+ * These functions are the shared business logic that both local and cloud
+ * execution use. They are called by the orchestrator (LocalDataflowExecutor
+ * or Step Functions via Lambda handlers).
+ *
+ * Note: These are defined as function signatures here for documentation.
+ * The actual implementations are in dataflow.ts and will be exported
+ * as standalone functions.
+ */
+/**
+ * Get the task dependency graph for a workspace.
+ *
+ * Pure function - reads workspace state and package to build DAG.
+ *
+ * @param storage - Storage backend
+ * @param workspace - Workspace name
+ * @returns Task dependency graph
+ */
+export type DataflowGetGraphFn = (storage: StorageBackend, workspace: string) => Promise<TaskGraph>;
+/**
+ * Check if a task's output is cached.
+ *
+ * Returns the cached output hash if available and valid.
+ *
+ * @param storage - Storage backend
+ * @param workspace - Workspace name
+ * @param taskHash - Task object hash
+ * @param inputHashes - Input dataset hashes
+ * @returns Cached output hash, or null if not cached or invalid
+ */
+export type DataflowCheckCacheFn = (storage: StorageBackend, workspace: string, taskHash: string, inputHashes: string[]) => Promise<string | null>;
+/**
+ * Write task output to workspace tree.
+ *
+ * Called after successful task execution to update the workspace.
+ *
+ * @param storage - Storage backend
+ * @param workspace - Workspace name
+ * @param taskName - Task name
+ * @param outputPath - Output dataset path
+ * @param outputHash - Output object hash
+ */
+export type DataflowWriteOutputFn = (storage: StorageBackend, workspace: string, taskName: string, outputPath: string, outputHash: string) => Promise<void>;
+/**
+ * Get tasks that are ready to execute.
+ *
+ * A task is ready when all its input dependencies have values assigned.
+ *
+ * @param storage - Storage backend
+ * @param workspace - Workspace name
+ * @param graph - Task dependency graph
+ * @param completed - Set of completed task names
+ * @returns Array of task names ready to execute
+ */
+export type DataflowGetReadyTasksFn = (storage: StorageBackend, workspace: string, graph: TaskGraph, completed: Set<string>) => Promise<string[]>;
+//# sourceMappingURL=interfaces.d.ts.map

package/dist/src/execution/interfaces.d.ts.map

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

package/dist/src/execution/interfaces.js

@@ -0,0 +1,6 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+export {};
+//# sourceMappingURL=interfaces.js.map

package/dist/src/execution/interfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../../../src/execution/interfaces.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/src/execution/processHelpers.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * Get the current system boot ID.
+ * Used for detecting stale locks/processes after system reboot.
+ */
+export declare function getBootId(): Promise<string>;
+/**
+ * Get process start time from /proc/<pid>/stat.
+ * Returns the starttime field (field 22) which is jiffies since boot.
+ * Used together with boot ID to uniquely identify a process (handles PID reuse).
+ */
+export declare function getPidStartTime(pid: number): Promise<number>;
+/**
+ * Check if a process is still alive based on stored identification
+ */
+export declare function isProcessAlive(pid: number, pidStartTime: number, bootId: string): Promise<boolean>;
+//# sourceMappingURL=processHelpers.d.ts.map

package/dist/src/execution/processHelpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"processHelpers.d.ts","sourceRoot":"","sources":["../../../src/execution/processHelpers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAWH;;;GAGG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,CAQjD;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAalE;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,OAAO,CAAC,CAWlB"}

package/dist/src/execution/processHelpers.js

@@ -0,0 +1,62 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * Process identification helpers for crash detection.
+ *
+ * These functions are used by LocalTaskRunner and LocalLockService
+ * to detect stale processes and locks after crashes or reboots.
+ */
+import * as fs from 'fs/promises';
+/**
+ * Get the current system boot ID.
+ * Used for detecting stale locks/processes after system reboot.
+ */
+export async function getBootId() {
+    try {
+        const data = await fs.readFile('/proc/sys/kernel/random/boot_id', 'utf-8');
+        return data.trim();
+    }
+    catch {
+        // Not on Linux, use a placeholder
+        return 'unknown-boot-id';
+    }
+}
+/**
+ * Get process start time from /proc/<pid>/stat.
+ * Returns the starttime field (field 22) which is jiffies since boot.
+ * Used together with boot ID to uniquely identify a process (handles PID reuse).
+ */
+export async function getPidStartTime(pid) {
+    try {
+        const data = await fs.readFile(`/proc/${pid}/stat`, 'utf-8');
+        // Fields are space-separated, but comm (field 2) can contain spaces and is in parens
+        // Find the closing paren, then split the rest
+        const closeParen = data.lastIndexOf(')');
+        const fields = data.slice(closeParen + 2).split(' ');
+        // After the closing paren, field index 0 is state (field 3), so starttime is at index 19
+        // (field 22 - 3 = 19)
+        return parseInt(fields[19], 10);
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Check if a process is still alive based on stored identification
+ */
+export async function isProcessAlive(pid, pidStartTime, bootId) {
+    // Different boot? Process is dead
+    const currentBootId = await getBootId();
+    if (currentBootId !== bootId)
+        return false;
+    // Check if PID exists and has same start time
+    const currentStartTime = await getPidStartTime(pid);
+    if (currentStartTime === 0)
+        return false; // PID doesn't exist
+    if (currentStartTime !== pidStartTime)
+        return false; // PID reused
+    return true;
+}
+//# sourceMappingURL=processHelpers.js.map

package/dist/src/execution/processHelpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"processHelpers.js","sourceRoot":"","sources":["../../../src/execution/processHelpers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,aAAa,CAAC;AAElC;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS;IAC7B,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,iCAAiC,EAAE,OAAO,CAAC,CAAC;QAC3E,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC;IACrB,CAAC;IAAC,MAAM,CAAC;QACP,kCAAkC;QAClC,OAAO,iBAAiB,CAAC;IAC3B,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,GAAW;IAC/C,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,SAAS,GAAG,OAAO,EAAE,OAAO,CAAC,CAAC;QAC7D,qFAAqF;QACrF,8CAA8C;QAC9C,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QACzC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACrD,yFAAyF;QACzF,sBAAsB;QACtB,OAAO,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,CAAC;IACX,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,GAAW,EACX,YAAoB,EACpB,MAAc;IAEd,kCAAkC;IAClC,MAAM,aAAa,GAAG,MAAM,SAAS,EAAE,CAAC;IACxC,IAAI,aAAa,KAAK,MAAM;QAAE,OAAO,KAAK,CAAC;IAE3C,8CAA8C;IAC9C,MAAM,gBAAgB,GAAG,MAAM,eAAe,CAAC,GAAG,CAAC,CAAC;IACpD,IAAI,gBAAgB,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,CAAC,oBAAoB;IAC9D,IAAI,gBAAgB,KAAK,YAAY;QAAE,OAAO,KAAK,CAAC,CAAC,aAAa;IAElE,OAAO,IAAI,CAAC;AACd,CAAC"}