@elaraai/e3-core 0.0.1-alpha.2

package/dist/src/errors.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * Domain error types for e3-core.
+ *
+ * All e3 errors extend E3Error, allowing callers to catch all domain errors
+ * with `if (err instanceof E3Error)` or specific errors with their class.
+ */
+import type { TaskExecutionResult } from './dataflow.js';
+/** Base class for all e3 errors */
+export declare class E3Error extends Error {
+    constructor(message: string);
+}
+export declare class RepositoryNotFoundError extends E3Error {
+    readonly path: string;
+    constructor(path: string);
+}
+export declare class WorkspaceNotFoundError extends E3Error {
+    readonly workspace: string;
+    constructor(workspace: string);
+}
+export declare class WorkspaceNotDeployedError extends E3Error {
+    readonly workspace: string;
+    constructor(workspace: string);
+}
+export declare class WorkspaceExistsError extends E3Error {
+    readonly workspace: string;
+    constructor(workspace: string);
+}
+/**
+ * Information about the process holding a workspace lock.
+ */
+export interface LockHolder {
+    /** Process ID of the lock holder */
+    pid: number;
+    /** When the lock was acquired (ISO 8601) */
+    acquiredAt: string;
+    /** System boot ID (to detect stale locks after reboot) */
+    bootId?: string;
+    /** Process start time in jiffies (to detect PID reuse) */
+    startTime?: number;
+    /** Command that acquired the lock (for debugging) */
+    command?: string;
+}
+/**
+ * Thrown when a workspace is locked by another process.
+ *
+ * This error is thrown when attempting to acquire an exclusive lock on a
+ * workspace that is already locked by another process (e.g., another
+ * `e3 start` command or API server).
+ */
+export declare class WorkspaceLockError extends E3Error {
+    readonly workspace: string;
+    readonly holder?: LockHolder | undefined;
+    constructor(workspace: string, holder?: LockHolder | undefined);
+}
+export declare class PackageNotFoundError extends E3Error {
+    readonly packageName: string;
+    readonly version?: string | undefined;
+    constructor(packageName: string, version?: string | undefined);
+}
+export declare class PackageInvalidError extends E3Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+export declare class PackageExistsError extends E3Error {
+    readonly packageName: string;
+    readonly version: string;
+    constructor(packageName: string, version: string);
+}
+export declare class DatasetNotFoundError extends E3Error {
+    readonly workspace: string;
+    readonly path: string;
+    constructor(workspace: string, path: string);
+}
+export declare class TaskNotFoundError extends E3Error {
+    readonly task: string;
+    constructor(task: string);
+}
+export declare class ObjectNotFoundError extends E3Error {
+    readonly hash: string;
+    constructor(hash: string);
+}
+export declare class ObjectCorruptError extends E3Error {
+    readonly hash: string;
+    readonly reason: string;
+    constructor(hash: string, reason: string);
+}
+export declare class ExecutionCorruptError extends E3Error {
+    readonly taskHash: string;
+    readonly inputsHash: string;
+    readonly cause: Error;
+    constructor(taskHash: string, inputsHash: string, cause: Error);
+}
+export declare class DataflowError extends E3Error {
+    readonly taskResults?: TaskExecutionResult[] | undefined;
+    readonly cause?: Error | undefined;
+    constructor(message: string, taskResults?: TaskExecutionResult[] | undefined, cause?: Error | undefined);
+}
+/**
+ * Thrown when a dataflow execution is aborted via AbortSignal.
+ *
+ * This is not an error condition - it indicates the execution was intentionally
+ * cancelled (e.g., by an API server before applying a write). The partial
+ * results contain the status of tasks that completed before the abort.
+ */
+export declare class DataflowAbortedError extends E3Error {
+    readonly partialResults?: TaskExecutionResult[] | undefined;
+    constructor(partialResults?: TaskExecutionResult[] | undefined);
+}
+export declare class PermissionDeniedError extends E3Error {
+    readonly path: string;
+    constructor(path: string);
+}
+/** Check if error is ENOENT (file not found) */
+export declare function isNotFoundError(err: unknown): boolean;
+/** Check if error is EACCES (permission denied) */
+export declare function isPermissionError(err: unknown): boolean;
+/** Check if error is EEXIST (already exists) */
+export declare function isExistsError(err: unknown): boolean;
+/** Wrap unknown errors with context */
+export declare function wrapError(err: unknown, message: string): E3Error;
+//# sourceMappingURL=errors.d.ts.map

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

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

package/dist/src/errors.js

@@ -0,0 +1,211 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+// =============================================================================
+// Base Error
+// =============================================================================
+/** Base class for all e3 errors */
+export class E3Error extends Error {
+    constructor(message) {
+        super(message);
+        this.name = this.constructor.name;
+    }
+}
+// =============================================================================
+// Repository Errors
+// =============================================================================
+export class RepositoryNotFoundError extends E3Error {
+    path;
+    constructor(path) {
+        super(`Repository not found at '${path}'`);
+        this.path = path;
+    }
+}
+// =============================================================================
+// Workspace Errors
+// =============================================================================
+export class WorkspaceNotFoundError extends E3Error {
+    workspace;
+    constructor(workspace) {
+        super(`Workspace '${workspace}' does not exist`);
+        this.workspace = workspace;
+    }
+}
+export class WorkspaceNotDeployedError extends E3Error {
+    workspace;
+    constructor(workspace) {
+        super(`Workspace '${workspace}' has no package deployed`);
+        this.workspace = workspace;
+    }
+}
+export class WorkspaceExistsError extends E3Error {
+    workspace;
+    constructor(workspace) {
+        super(`Workspace '${workspace}' already exists`);
+        this.workspace = workspace;
+    }
+}
+/**
+ * Thrown when a workspace is locked by another process.
+ *
+ * This error is thrown when attempting to acquire an exclusive lock on a
+ * workspace that is already locked by another process (e.g., another
+ * `e3 start` command or API server).
+ */
+export class WorkspaceLockError extends E3Error {
+    workspace;
+    holder;
+    constructor(workspace, holder) {
+        const msg = holder
+            ? `Workspace '${workspace}' is locked by process ${holder.pid} (since ${holder.acquiredAt})`
+            : `Workspace '${workspace}' is locked by another process`;
+        super(msg);
+        this.workspace = workspace;
+        this.holder = holder;
+    }
+}
+// =============================================================================
+// Package Errors
+// =============================================================================
+export class PackageNotFoundError extends E3Error {
+    packageName;
+    version;
+    constructor(packageName, version) {
+        super(version
+            ? `Package '${packageName}@${version}' not found`
+            : `Package '${packageName}' not found`);
+        this.packageName = packageName;
+        this.version = version;
+    }
+}
+export class PackageInvalidError extends E3Error {
+    reason;
+    constructor(reason) {
+        super(`Invalid package: ${reason}`);
+        this.reason = reason;
+    }
+}
+export class PackageExistsError extends E3Error {
+    packageName;
+    version;
+    constructor(packageName, version) {
+        super(`Package '${packageName}@${version}' already exists`);
+        this.packageName = packageName;
+        this.version = version;
+    }
+}
+// =============================================================================
+// Dataset Errors
+// =============================================================================
+export class DatasetNotFoundError extends E3Error {
+    workspace;
+    path;
+    constructor(workspace, path) {
+        super(`Dataset '${path}' not found in workspace '${workspace}'`);
+        this.workspace = workspace;
+        this.path = path;
+    }
+}
+// =============================================================================
+// Task Errors
+// =============================================================================
+export class TaskNotFoundError extends E3Error {
+    task;
+    constructor(task) {
+        super(`Task '${task}' not found`);
+        this.task = task;
+    }
+}
+// =============================================================================
+// Object Errors
+// =============================================================================
+export class ObjectNotFoundError extends E3Error {
+    hash;
+    constructor(hash) {
+        super(`Object '${hash.slice(0, 8)}...' not found`);
+        this.hash = hash;
+    }
+}
+export class ObjectCorruptError extends E3Error {
+    hash;
+    reason;
+    constructor(hash, reason) {
+        super(`Object ${hash.slice(0, 8)}... is corrupt: ${reason}`);
+        this.hash = hash;
+        this.reason = reason;
+    }
+}
+// =============================================================================
+// Execution Errors
+// =============================================================================
+export class ExecutionCorruptError extends E3Error {
+    taskHash;
+    inputsHash;
+    cause;
+    constructor(taskHash, inputsHash, cause) {
+        super(`Execution ${taskHash.slice(0, 8)}.../${inputsHash.slice(0, 8)}... is corrupt: ${cause.message}`);
+        this.taskHash = taskHash;
+        this.inputsHash = inputsHash;
+        this.cause = cause;
+    }
+}
+// =============================================================================
+// Dataflow Errors
+// =============================================================================
+export class DataflowError extends E3Error {
+    taskResults;
+    cause;
+    constructor(message, taskResults, cause) {
+        super(cause ? `${message}: ${cause.message}` : message);
+        this.taskResults = taskResults;
+        this.cause = cause;
+    }
+}
+/**
+ * Thrown when a dataflow execution is aborted via AbortSignal.
+ *
+ * This is not an error condition - it indicates the execution was intentionally
+ * cancelled (e.g., by an API server before applying a write). The partial
+ * results contain the status of tasks that completed before the abort.
+ */
+export class DataflowAbortedError extends E3Error {
+    partialResults;
+    constructor(partialResults) {
+        super('Dataflow execution was aborted');
+        this.partialResults = partialResults;
+    }
+}
+// =============================================================================
+// Generic Errors
+// =============================================================================
+export class PermissionDeniedError extends E3Error {
+    path;
+    constructor(path) {
+        super(`Permission denied: '${path}'`);
+        this.path = path;
+    }
+}
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/** Check if error is ENOENT (file not found) */
+export function isNotFoundError(err) {
+    return (err instanceof Error && err.code === 'ENOENT');
+}
+/** Check if error is EACCES (permission denied) */
+export function isPermissionError(err) {
+    return (err instanceof Error && err.code === 'EACCES');
+}
+/** Check if error is EEXIST (already exists) */
+export function isExistsError(err) {
+    return (err instanceof Error && err.code === 'EEXIST');
+}
+/** Wrap unknown errors with context */
+export function wrapError(err, message) {
+    if (err instanceof E3Error)
+        return err;
+    const cause = err instanceof Error ? err.message : String(err);
+    return new E3Error(`${message}: ${cause}`);
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/errors.js.map

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

package/dist/src/executions.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+import { type ExecutionStatus } from '@elaraai/e3-types';
+/**
+ * Compute the combined hash of input hashes.
+ *
+ * Used to create a unique identifier for an execution based on its inputs.
+ * The order of inputs matters - different orderings produce different hashes.
+ *
+ * @param inputHashes - Array of input dataset hashes
+ * @returns Combined SHA256 hash
+ */
+export declare function inputsHash(inputHashes: string[]): string;
+/**
+ * Get the filesystem path for an execution directory.
+ *
+ * @param repoPath - Path to .e3 repository
+ * @param taskHash - Hash of the task object
+ * @param inHash - Combined hash of input hashes
+ * @returns Path to execution directory: executions/<taskHash>/<inputsHash>/
+ */
+export declare function executionPath(repoPath: string, taskHash: string, inHash: string): string;
+/**
+ * Get execution status.
+ *
+ * @param repoPath - Path to .e3 repository
+ * @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
+ */
+export declare function executionGet(repoPath: string, taskHash: string, inHash: string): Promise<ExecutionStatus | null>;
+/**
+ * Get output hash for a completed execution.
+ *
+ * @param repoPath - Path to .e3 repository
+ * @param taskHash - Hash of the task object
+ * @param inHash - Combined hash of input hashes
+ * @returns Output hash or null if not complete or failed
+ */
+export declare function executionGetOutput(repoPath: string, taskHash: string, inHash: string): Promise<string | null>;
+/**
+ * List all input hashes that have executions for a given task.
+ *
+ * @param repoPath - Path to .e3 repository
+ * @param taskHash - Hash of the task object
+ * @returns Array of input hashes
+ */
+export declare function executionListForTask(repoPath: string, taskHash: string): Promise<string[]>;
+/**
+ * List all executions in the repository.
+ *
+ * @param repoPath - Path to .e3 repository
+ * @returns Array of { taskHash, inputsHash } objects
+ */
+export declare function executionList(repoPath: string): Promise<Array<{
+    taskHash: string;
+    inputsHash: string;
+}>>;
+/**
+ * Options for reading execution logs
+ */
+export interface LogReadOptions {
+    /** Byte offset to start reading from (default: 0) */
+    offset?: number;
+    /** 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;
+}
+/**
+ * Read execution logs with pagination support.
+ *
+ * @param repoPath - Path to .e3 repository
+ * @param taskHash - Hash of the task object
+ * @param inHash - Combined hash of input hashes
+ * @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>;
+/**
+ * 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 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>;
+//# sourceMappingURL=executions.d.ts.map

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

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