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

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