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

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"}

package/dist/src/executions.d.ts

@@ -2,7 +2,8 @@
  * Copyright (c) 2025 Elara AI Pty Ltd
  * Licensed under BSL 1.1. See LICENSE for details.
  */
-import { type ExecutionStatus } from '@elaraai/e3-types';
+import type { ExecutionStatus } from '@elaraai/e3-types';
+import type { StorageBackend, LogChunk } from './storage/interfaces.js';
 /**
  * Compute the combined hash of input hashes.
  *
@@ -14,51 +15,95 @@ import { type ExecutionStatus } from '@elaraai/e3-types';
  */
 export declare function inputsHash(inputHashes: string[]): string;
 /**
- * Get the filesystem path for an execution directory.
+ * Get execution status for a specific execution.
  *
- * @param repoPath - Path to .e3 repository
+ * @param storage - Storage backend
+ * @param repo - Repository identifier (for local storage, the path to e3 repository directory)
  * @param taskHash - Hash of the task object
  * @param inHash - Combined hash of input hashes
- * @returns Path to execution directory: executions/<taskHash>/<inputsHash>/
+ * @param executionId - Execution ID (UUIDv7)
+ * @returns ExecutionStatus or null if execution doesn't exist
+ * @throws {ExecutionCorruptError} If status file exists but cannot be decoded
  */
-export declare function executionPath(repoPath: string, taskHash: string, inHash: string): string;
+export declare function executionGet(storage: StorageBackend, repo: string, taskHash: string, inHash: string, executionId: string): Promise<ExecutionStatus | null>;
 /**
- * Get execution status.
+ * Get the latest execution status (lexicographically greatest executionId).
  *
- * @param repoPath - Path to .e3 repository
+ * @param storage - Storage backend
+ * @param repo - Repository identifier (for local storage, the path to e3 repository directory)
  * @param taskHash - Hash of the task object
  * @param inHash - Combined hash of input hashes
- * @returns ExecutionStatus or null if execution doesn't exist
- * @throws {ExecutionCorruptError} If status file exists but cannot be decoded
+ * @returns ExecutionStatus or null if no executions exist
+ */
+export declare function executionGetLatest(storage: StorageBackend, repo: string, taskHash: string, inHash: string): Promise<ExecutionStatus | null>;
+/**
+ * Get the latest successful output hash for a completed execution.
+ * This is the primary cache lookup function.
+ *
+ * @param storage - Storage backend
+ * @param repo - Repository identifier (for local storage, the path to e3 repository directory)
+ * @param taskHash - Hash of the task object
+ * @param inHash - Combined hash of input hashes
+ * @returns Output hash or null if no successful execution exists
  */
-export declare function executionGet(repoPath: string, taskHash: string, inHash: string): Promise<ExecutionStatus | null>;
+export declare function executionGetOutput(storage: StorageBackend, repo: string, taskHash: string, inHash: string): Promise<string | null>;
 /**
- * Get output hash for a completed execution.
+ * List all execution IDs for a (taskHash, inputsHash) pair.
  *
- * @param repoPath - Path to .e3 repository
+ * @param storage - Storage backend
+ * @param repo - Repository identifier (for local storage, the path to e3 repository directory)
  * @param taskHash - Hash of the task object
  * @param inHash - Combined hash of input hashes
- * @returns Output hash or null if not complete or failed
+ * @returns Array of execution IDs (sorted lexicographically ascending)
  */
-export declare function executionGetOutput(repoPath: string, taskHash: string, inHash: string): Promise<string | null>;
+export declare function executionListIds(storage: StorageBackend, repo: string, taskHash: string, inHash: string): Promise<string[]>;
 /**
  * List all input hashes that have executions for a given task.
  *
- * @param repoPath - Path to .e3 repository
+ * @param storage - Storage backend
+ * @param repo - Repository identifier (for local storage, the path to e3 repository directory)
  * @param taskHash - Hash of the task object
  * @returns Array of input hashes
  */
-export declare function executionListForTask(repoPath: string, taskHash: string): Promise<string[]>;
+export declare function executionListForTask(storage: StorageBackend, repo: string, taskHash: string): Promise<string[]>;
 /**
  * List all executions in the repository.
  *
- * @param repoPath - Path to .e3 repository
+ * @param storage - Storage backend
+ * @param repo - Repository identifier (for local storage, the path to e3 repository directory)
  * @returns Array of { taskHash, inputsHash } objects
  */
-export declare function executionList(repoPath: string): Promise<Array<{
+export declare function executionList(storage: StorageBackend, repo: string): Promise<Array<{
     taskHash: string;
     inputsHash: string;
 }>>;
+/**
+ * Result of finding the current execution for a task
+ */
+export interface CurrentExecutionRef {
+    /** Hash of the task object */
+    taskHash: string;
+    /** Combined hash of input hashes */
+    inputsHash: string;
+    /** Execution ID (UUIDv7) */
+    executionId: string;
+    /** True if this matches the current workspace input state */
+    isCurrent: boolean;
+}
+/**
+ * Find the execution reference for a task in a workspace.
+ *
+ * This looks up the task's current input hashes from the workspace state
+ * and finds the matching execution. If no execution exists for the current
+ * inputs, falls back to the most recent execution.
+ *
+ * @param storage - Storage backend
+ * @param repo - Repository identifier (for local storage, the path to e3 repository directory)
+ * @param ws - Workspace name
+ * @param taskName - Task name
+ * @returns Execution reference or null if no executions exist
+ */
+export declare function executionFindCurrent(storage: StorageBackend, repo: string, ws: string, taskName: string): Promise<CurrentExecutionRef | null>;
 /**
  * Options for reading execution logs
  */
@@ -68,109 +113,31 @@ export interface LogReadOptions {
     /** Maximum bytes to read (default: 64KB) */
     limit?: number;
 }
-/**
- * Result of reading a log chunk
- */
-export interface LogChunk {
-    /** Log content (UTF-8) */
-    data: string;
-    /** Byte offset of this chunk */
-    offset: number;
-    /** Bytes in this chunk */
-    size: number;
-    /** Total log file size (for pagination) */
-    totalSize: number;
-    /** True if this is the end of the file */
-    complete: boolean;
-}
+export type { LogChunk };
 /**
  * Read execution logs with pagination support.
  *
- * @param repoPath - Path to .e3 repository
+ * @param storage - Storage backend
+ * @param repo - Repository identifier (for local storage, the path to e3 repository directory)
  * @param taskHash - Hash of the task object
  * @param inHash - Combined hash of input hashes
+ * @param executionId - Execution ID (UUIDv7)
  * @param stream - Which log stream to read ('stdout' or 'stderr')
  * @param options - Pagination options
  * @returns Log chunk with data and metadata
  */
-export declare function executionReadLog(repoPath: string, taskHash: string, inHash: string, stream: 'stdout' | 'stderr', options?: LogReadOptions): Promise<LogChunk>;
+export declare function executionReadLog(storage: StorageBackend, repo: string, taskHash: string, inHash: string, executionId: string, stream: 'stdout' | 'stderr', options?: LogReadOptions): Promise<LogChunk>;
 /**
  * Evaluate command IR to get exec args.
  *
  * The IR is an East function: (inputs: Array<String>, output: String) -> Array<String>
  *
- * @param repoPath - Path to .e3 repository
+ * @param storage - Storage backend
+ * @param repo - Repository identifier (for local storage, the path to e3 repository directory)
  * @param commandIrHash - Hash of the IR object
  * @param inputPaths - Paths to staged input files
  * @param outputPath - Path where output should be written
  * @returns Array of strings to exec
  */
-export declare function evaluateCommandIr(repoPath: string, commandIrHash: string, inputPaths: string[], outputPath: string): Promise<string[]>;
-/**
- * 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>;
-/**
- * Options for task execution
- */
-export interface ExecuteOptions {
-    /** Re-run even if cached (default: false) */
-    force?: boolean;
-    /** Timeout in milliseconds (default: none) */
-    timeout?: number;
-    /** AbortSignal for cancellation */
-    signal?: AbortSignal;
-    /** Stream stdout callback */
-    onStdout?: (data: string) => void;
-    /** Stream stderr callback */
-    onStderr?: (data: string) => void;
-}
-/**
- * Result of task execution
- */
-export interface ExecutionResult {
-    /** Combined inputs hash (identifies this execution) */
-    inputsHash: string;
-    /** True if result was from cache */
-    cached: boolean;
-    /** Final state */
-    state: 'success' | 'failed' | 'error';
-    /** Output dataset hash (null on failure) */
-    outputHash: string | null;
-    /** Process exit code (null if not applicable) */
-    exitCode: number | null;
-    /** Execution time in ms (0 if cached) */
-    duration: number;
-    /** Error message on failure */
-    error: string | null;
-}
-/**
- * Execute a single task.
- *
- * This is the core execution primitive. It:
- * 1. Computes the execution identity from task + inputs
- * 2. Checks cache (unless force=true)
- * 3. Marshals inputs to a scratch directory
- * 4. Evaluates command IR to get exec args
- * 5. Runs the command
- * 6. Stores the output and updates status
- *
- * @param repoPath - Path to .e3 repository
- * @param taskHash - Hash of the task object
- * @param inputHashes - Array of input dataset hashes
- * @param options - Execution options
- * @returns Execution result
- */
-export declare function taskExecute(repoPath: string, taskHash: string, inputHashes: string[], options?: ExecuteOptions): Promise<ExecutionResult>;
+export declare function evaluateCommandIr(storage: StorageBackend, repo: string, commandIrHash: string, inputPaths: string[], outputPath: string): Promise<string[]>;
 //# sourceMappingURL=executions.d.ts.map

package/dist/src/executions.d.ts.map

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