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

package/dist/src/executions.js

@@ -3,23 +3,18 @@
  * Licensed under BSL 1.1. See LICENSE for details.
  */
 /**
- * Task execution for e3 repositories.
+ * Generic task execution APIs for e3 repositories.
  *
- * Provides APIs for:
+ * Provides storage-agnostic APIs for:
  * - Computing execution identity (inputsHash)
  * - Querying execution status and results
  * - Reading execution logs
- * - Running tasks with caching
+ * - Evaluating command IR
+ *
+ * Note: Local process execution is in execution/LocalTaskRunner.ts
  */
-import * as fs from 'fs/promises';
-import * as path from 'path';
-import { spawn } from 'child_process';
-import { createWriteStream } from 'fs';
-import { tmpdir } from 'os';
-import { decodeBeast2For, encodeBeast2For, variant, EastIR, IRType } from '@elaraai/east';
-import { ExecutionStatusType, TaskObjectType, } from '@elaraai/e3-types';
-import { computeHash, objectRead, objectWrite } from './objects.js';
-import { ExecutionCorruptError, isNotFoundError } from './errors.js';
+import { decodeBeast2For, EastIR, IRType } from '@elaraai/east';
+import { computeHash } from './objects.js';
 // ============================================================================
 // Execution Identity
 // ============================================================================
@@ -36,166 +31,149 @@ export function inputsHash(inputHashes) {
     const data = inputHashes.join('\0');
     return computeHash(new TextEncoder().encode(data));
 }
+// ============================================================================
+// Execution Status
+// ============================================================================
 /**
- * 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 function executionPath(repoPath, taskHash, inHash) {
-    return path.join(repoPath, 'executions', taskHash, inHash);
+export async function executionGet(storage, repo, taskHash, inHash, executionId) {
+    return storage.refs.executionGet(repo, taskHash, inHash, executionId);
 }
-// ============================================================================
-// Execution Status
-// ============================================================================
 /**
- * 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 async function executionGet(repoPath, taskHash, inHash) {
-    const execDir = executionPath(repoPath, taskHash, inHash);
-    const statusPath = path.join(execDir, 'status.beast2');
-    let data;
-    try {
-        data = await fs.readFile(statusPath);
-    }
-    catch (err) {
-        if (isNotFoundError(err)) {
-            return null;
-        }
-        throw err;
-    }
-    try {
-        const decoder = decodeBeast2For(ExecutionStatusType);
-        return decoder(data);
-    }
-    catch (err) {
-        throw new ExecutionCorruptError(taskHash, inHash, err instanceof Error ? err : new Error(String(err)));
-    }
+export async function executionGetLatest(storage, repo, taskHash, inHash) {
+    return storage.refs.executionGetLatest(repo, taskHash, inHash);
 }
 /**
- * Get output hash for a completed execution.
+ * Get the latest successful output hash for a completed execution.
+ * This is the primary cache lookup function.
  *
- * @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 Output hash or null if no successful execution exists
  */
-export async function executionGetOutput(repoPath, taskHash, inHash) {
-    const execDir = executionPath(repoPath, taskHash, inHash);
-    const outputPath = path.join(execDir, 'output');
-    try {
-        const content = await fs.readFile(outputPath, 'utf-8');
-        return content.trim();
-    }
-    catch (err) {
-        if (isNotFoundError(err)) {
-            return null;
-        }
-        throw err;
-    }
+export async function executionGetOutput(storage, repo, taskHash, inHash) {
+    return storage.refs.executionGetLatestOutput(repo, taskHash, inHash);
+}
+/**
+ * List all execution IDs for a (taskHash, inputsHash) pair.
+ *
+ * @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 Array of execution IDs (sorted lexicographically ascending)
+ */
+export async function executionListIds(storage, repo, taskHash, inHash) {
+    return storage.refs.executionListIds(repo, taskHash, inHash);
 }
 /**
  * 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 async function executionListForTask(repoPath, taskHash) {
-    const taskDir = path.join(repoPath, 'executions', taskHash);
-    try {
-        const entries = await fs.readdir(taskDir);
-        // Filter to only valid hash directories (64 hex chars)
-        return entries.filter((e) => /^[a-f0-9]{64}$/.test(e));
-    }
-    catch {
-        return [];
-    }
+export async function executionListForTask(storage, repo, taskHash) {
+    return storage.refs.executionListForTask(repo, taskHash);
 }
 /**
  * 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 async function executionList(repoPath) {
-    const executionsDir = path.join(repoPath, 'executions');
-    const result = [];
-    try {
-        const taskDirs = await fs.readdir(executionsDir);
-        for (const taskHash of taskDirs) {
-            if (!/^[a-f0-9]{64}$/.test(taskHash))
-                continue;
-            const taskDir = path.join(executionsDir, taskHash);
-            const stat = await fs.stat(taskDir);
-            if (!stat.isDirectory())
-                continue;
-            const inputsDirs = await fs.readdir(taskDir);
-            for (const inputsHash of inputsDirs) {
-                if (/^[a-f0-9]{64}$/.test(inputsHash)) {
-                    result.push({ taskHash, inputsHash });
-                }
+export async function executionList(storage, repo) {
+    return storage.refs.executionList(repo);
+}
+/**
+ * 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 async function executionFindCurrent(storage, repo, ws, taskName) {
+    // Import here to avoid circular dependency
+    const { workspaceGetTaskHash, workspaceGetTask } = await import('./tasks.js');
+    const { workspaceGetDatasetHash } = await import('./trees.js');
+    const taskHash = await workspaceGetTaskHash(storage, repo, ws, taskName);
+    const task = await workspaceGetTask(storage, repo, ws, taskName);
+    // Get the current input hashes from the workspace
+    const currentInputHashes = [];
+    let allInputsAssigned = true;
+    for (const inputPath of task.inputs) {
+        const { refType, hash } = await workspaceGetDatasetHash(storage, repo, ws, inputPath);
+        if (refType !== 'value' || hash === null) {
+            allInputsAssigned = false;
+            break;
+        }
+        currentInputHashes.push(hash);
+    }
+    const executions = await executionListForTask(storage, repo, taskHash);
+    if (allInputsAssigned) {
+        const inHash = inputsHash(currentInputHashes);
+        if (executions.includes(inHash)) {
+            // Get the latest execution status to get the executionId
+            const status = await storage.refs.executionGetLatest(repo, taskHash, inHash);
+            if (status) {
+                // Extract executionId from the status (all variants have it)
+                const executionId = status.value.executionId;
+                return { taskHash, inputsHash: inHash, executionId, isCurrent: true };
             }
         }
     }
-    catch {
-        // Executions directory doesn't exist
+    // Fall back to most recent execution
+    if (executions.length > 0) {
+        const inHash = executions[0];
+        const status = await storage.refs.executionGetLatest(repo, taskHash, inHash);
+        if (status) {
+            const executionId = status.value.executionId;
+            return { taskHash, inputsHash: inHash, executionId, isCurrent: false };
+        }
     }
-    return result;
+    return null;
 }
 /**
  * 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 async function executionReadLog(repoPath, taskHash, inHash, stream, options = {}) {
-    const execDir = executionPath(repoPath, taskHash, inHash);
-    const logPath = path.join(execDir, `${stream}.txt`);
-    const offset = options.offset ?? 0;
-    const limit = options.limit ?? 65536; // 64KB default
-    try {
-        const stat = await fs.stat(logPath);
-        const totalSize = stat.size;
-        // Open file and read chunk
-        const fd = await fs.open(logPath, 'r');
-        try {
-            const buffer = Buffer.alloc(Math.min(limit, totalSize - offset));
-            const { bytesRead } = await fd.read(buffer, 0, buffer.length, offset);
-            return {
-                data: buffer.slice(0, bytesRead).toString('utf-8'),
-                offset,
-                size: bytesRead,
-                totalSize,
-                complete: offset + bytesRead >= totalSize,
-            };
-        }
-        finally {
-            await fd.close();
-        }
-    }
-    catch {
-        // Log file doesn't exist yet
-        return {
-            data: '',
-            offset: 0,
-            size: 0,
-            totalSize: 0,
-            complete: true,
-        };
-    }
+export async function executionReadLog(storage, repo, taskHash, inHash, executionId, stream, options = {}) {
+    return storage.logs.read(repo, taskHash, inHash, executionId, stream, options);
 }
 // ============================================================================
 // Command IR Evaluation
@@ -205,14 +183,15 @@ export async function executionReadLog(repoPath, taskHash, inHash, stream, optio
  *
  * 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 async function evaluateCommandIr(repoPath, commandIrHash, inputPaths, outputPath) {
-    const irData = await objectRead(repoPath, commandIrHash);
+export async function evaluateCommandIr(storage, repo, commandIrHash, inputPaths, outputPath) {
+    const irData = await storage.objects.read(repo, commandIrHash);
     try {
         // Decode the IR from beast2 format
         const decoder = decodeBeast2For(IRType);
@@ -237,349 +216,4 @@ export async function evaluateCommandIr(repoPath, commandIrHash, inputPaths, out
         throw new Error(`Failed to evaluate command IR: ${err}`);
     }
 }
-// ============================================================================
-// Process Identification (for crash detection)
-// ============================================================================
-/**
- * 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;
-}
-/**
- * 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 async function taskExecute(repoPath, taskHash, inputHashes, options = {}) {
-    const inHash = inputsHash(inputHashes);
-    const execDir = executionPath(repoPath, taskHash, inHash);
-    const startTime = Date.now();
-    // Step 1: Check cache (unless force)
-    if (!options.force) {
-        const existingOutput = await executionGetOutput(repoPath, taskHash, inHash);
-        if (existingOutput !== null) {
-            const status = await executionGet(repoPath, taskHash, inHash);
-            if (status && status.type === 'success') {
-                return {
-                    inputsHash: inHash,
-                    cached: true,
-                    state: 'success',
-                    outputHash: existingOutput,
-                    exitCode: 0,
-                    duration: 0,
-                    error: null,
-                };
-            }
-        }
-    }
-    // Step 2: Read task object
-    let task;
-    try {
-        const taskData = await objectRead(repoPath, taskHash);
-        const decoder = decodeBeast2For(TaskObjectType);
-        task = decoder(Buffer.from(taskData));
-    }
-    catch (err) {
-        return {
-            inputsHash: inHash,
-            cached: false,
-            state: 'error',
-            outputHash: null,
-            exitCode: null,
-            duration: Date.now() - startTime,
-            error: `Failed to read task object: ${err}`,
-        };
-    }
-    // Step 3: Create scratch directory
-    // Include PID to prevent collisions when multiple e3 processes run the same
-    // task concurrently (e.g., same task in different workspaces at same millisecond)
-    const scratchDir = path.join(tmpdir(), `e3-exec-${taskHash.slice(0, 8)}-${inHash.slice(0, 8)}-${process.pid}-${Date.now()}`);
-    await fs.mkdir(scratchDir, { recursive: true });
-    try {
-        // Step 4: Marshal inputs to scratch dir
-        const inputPaths = [];
-        for (let i = 0; i < inputHashes.length; i++) {
-            const inputPath = path.join(scratchDir, `input-${i}.beast2`);
-            const inputData = await objectRead(repoPath, inputHashes[i]);
-            await fs.writeFile(inputPath, inputData);
-            inputPaths.push(inputPath);
-        }
-        // Step 5: Evaluate command IR to get exec args
-        const outputPath = path.join(scratchDir, 'output.beast2');
-        let args;
-        try {
-            args = await evaluateCommandIr(repoPath, task.commandIr, inputPaths, outputPath);
-        }
-        catch (err) {
-            return {
-                inputsHash: inHash,
-                cached: false,
-                state: 'error',
-                outputHash: null,
-                exitCode: null,
-                duration: Date.now() - startTime,
-                error: `Failed to evaluate command IR: ${err}`,
-            };
-        }
-        if (args.length === 0) {
-            return {
-                inputsHash: inHash,
-                cached: false,
-                state: 'error',
-                outputHash: null,
-                exitCode: null,
-                duration: Date.now() - startTime,
-                error: 'Command IR produced empty command',
-            };
-        }
-        // Step 6: Create execution directory
-        await fs.mkdir(execDir, { recursive: true });
-        // Step 7: Get boot ID for crash detection
-        const bootId = await getBootId();
-        // Step 8: Execute command
-        const result = await runCommand(args, execDir, inputHashes, bootId, options);
-        // Step 9: Handle result
-        if (result.exitCode === 0) {
-            // Success - read and store output
-            try {
-                const outputData = await fs.readFile(outputPath);
-                const outputHash = await objectWrite(repoPath, outputData);
-                // Write output ref
-                await fs.writeFile(path.join(execDir, 'output'), outputHash + '\n');
-                // Write success status
-                const status = variant('success', {
-                    inputHashes,
-                    outputHash,
-                    startedAt: new Date(startTime),
-                    completedAt: new Date(),
-                });
-                const encoder = encodeBeast2For(ExecutionStatusType);
-                await fs.writeFile(path.join(execDir, 'status.beast2'), encoder(status));
-                return {
-                    inputsHash: inHash,
-                    cached: false,
-                    state: 'success',
-                    outputHash,
-                    exitCode: 0,
-                    duration: Date.now() - startTime,
-                    error: null,
-                };
-            }
-            catch (err) {
-                // Output file missing or unreadable
-                const status = variant('error', {
-                    inputHashes,
-                    startedAt: new Date(startTime),
-                    completedAt: new Date(),
-                    message: `Failed to read output: ${err}`,
-                });
-                const encoder = encodeBeast2For(ExecutionStatusType);
-                await fs.writeFile(path.join(execDir, 'status.beast2'), encoder(status));
-                return {
-                    inputsHash: inHash,
-                    cached: false,
-                    state: 'error',
-                    outputHash: null,
-                    exitCode: 0,
-                    duration: Date.now() - startTime,
-                    error: `Failed to read output: ${err}`,
-                };
-            }
-        }
-        else {
-            // Failed - write failed status
-            const status = variant('failed', {
-                inputHashes,
-                startedAt: new Date(startTime),
-                completedAt: new Date(),
-                exitCode: BigInt(result?.exitCode ?? -1),
-            });
-            const encoder = encodeBeast2For(ExecutionStatusType);
-            await fs.writeFile(path.join(execDir, 'status.beast2'), encoder(status));
-            return {
-                inputsHash: inHash,
-                cached: false,
-                state: 'failed',
-                outputHash: null,
-                exitCode: result.exitCode,
-                duration: Date.now() - startTime,
-                error: result.error,
-            };
-        }
-    }
-    finally {
-        // Cleanup scratch directory
-        try {
-            await fs.rm(scratchDir, { recursive: true, force: true });
-        }
-        catch {
-            // Ignore cleanup errors
-        }
-    }
-}
-/**
- * Run a command and capture output
- */
-async function runCommand(args, execDir, inputHashes, bootId, options) {
-    const [cmd, ...cmdArgs] = args;
-    // Process Lifecycle Management
-    // ============================
-    // We use detached: true to create a new process group, allowing us to kill
-    // the entire process tree by signaling the negative PID (process group leader).
-    //
-    // LIMITATION: Process groups are flat, not hierarchical. If a task spawns a
-    // subprocess that creates its own process group (via setsid, daemonization,
-    // or another detached spawn), that subprocess will escape our kill signal.
-    // This is a fundamental Unix limitation - process groups were designed for
-    // terminal job control (Ctrl+C/Ctrl+Z), not process tree management.
-    //
-    // For most tasks (shell scripts, pipelines, normal child processes) this works
-    // fine. A task would have to intentionally call setsid() to escape.
-    //
-    // Potential improvements for hosted e3:
-    // - Linux cgroups: Hierarchical containment with no escape. Requires root or
-    //   systemd integration (systemd-run --scope). Used by Docker/Kubernetes.
-    // - PR_SET_CHILD_SUBREAPER: Makes e3 adopt orphaned processes instead of init,
-    //   allowing tracking and cleanup. Requires polling to detect orphans.
-    // - Firecracker/microVMs: Complete isolation with hardware virtualization.
-    //   The VM boundary provides bulletproof containment. Best for multi-tenant.
-    const child = spawn(cmd, cmdArgs, {
-        stdio: ['ignore', 'pipe', 'pipe'],
-        detached: true,
-    });
-    // Set up event listeners IMMEDIATELY before any async work
-    // to avoid missing events if the process completes quickly
-    const resultPromise = new Promise((resolve) => {
-        child.on('error', (err) => {
-            resolve({ exitCode: null, error: `Failed to spawn: ${err.message}` });
-        });
-        child.on('close', (code) => {
-            resolve({ exitCode: code, error: code !== 0 ? `Exit code: ${code}` : null });
-        });
-    });
-    // Open log files for writing
-    const stdoutStream = createWriteStream(path.join(execDir, 'stdout.txt'));
-    const stderrStream = createWriteStream(path.join(execDir, 'stderr.txt'));
-    // Tee stdout
-    child.stdout?.on('data', (data) => {
-        stdoutStream.write(data);
-        if (options.onStdout) {
-            options.onStdout(data.toString('utf-8'));
-        }
-    });
-    // Tee stderr
-    child.stderr?.on('data', (data) => {
-        stderrStream.write(data);
-        if (options.onStderr) {
-            options.onStderr(data.toString('utf-8'));
-        }
-    });
-    // Helper to kill the entire process group (child and all its descendants).
-    // With detached: true, child.pid is the process group leader, so killing
-    // -child.pid sends the signal to all processes in that group.
-    const killProcessGroup = () => {
-        if (child.pid) {
-            try {
-                process.kill(-child.pid, 'SIGKILL');
-            }
-            catch {
-                // Process may have already exited
-            }
-        }
-    };
-    // Handle timeout
-    let timeoutId;
-    if (options.timeout) {
-        timeoutId = setTimeout(killProcessGroup, options.timeout);
-    }
-    // Handle abort signal
-    if (options.signal) {
-        if (options.signal.aborted) {
-            // Already aborted before we started
-            killProcessGroup();
-        }
-        else {
-            options.signal.addEventListener('abort', killProcessGroup, { once: true });
-        }
-    }
-    // Write running status with actual child PID (can be async now)
-    const pidStartTime = await getPidStartTime(child.pid);
-    const status = variant('running', {
-        inputHashes,
-        startedAt: new Date(),
-        pid: BigInt(child.pid ?? -1),
-        pidStartTime: BigInt(pidStartTime ?? -1),
-        bootId,
-    });
-    const encoder = encodeBeast2For(ExecutionStatusType);
-    await fs.writeFile(path.join(execDir, 'status.beast2'), encoder(status));
-    // Wait for process to complete
-    const result = await resultPromise;
-    // Cleanup
-    if (timeoutId)
-        clearTimeout(timeoutId);
-    if (options.signal) {
-        options.signal.removeEventListener('abort', killProcessGroup);
-    }
-    stdoutStream.end();
-    stderrStream.end();
-    return result;
-}
 //# sourceMappingURL=executions.js.map