@elaraai/e3-types 0.0.2-beta.2 → 0.0.2-beta.21

package/README.md

@@ -11,11 +11,14 @@ npm install @elaraai/e3-types
 ## Types
 
 - **Repository** - Repository configuration and paths
-- **Commit** - Task commit types (new, done, error)
-- **Task** - Task definition and state
 - **Package** - Package manifest and metadata
 - **Dataset** - Dataset schemas and paths
-- **Dataflow** - Dataflow definitions
+- **Task** - Task definition and configuration
+- **Dataflow** - Dataflow graph and execution state
+  - `TaskStateType` - Individual task execution state
+  - `DataflowGraphType` - Task dependency graph
+  - `ExecutionEventType` - Execution progress events
+  - `DataflowExecutionStateType` - Full execution state
 - **Runner** - Runner configuration
 
 
@@ -41,7 +44,7 @@ Dual AGPL-3.0 / Commercial. See [LICENSE.md](./LICENSE.md).
   - [@elaraai/e3](https://www.npmjs.com/package/@elaraai/e3): SDK for authoring e3 packages with typed tasks and pipelines
   - [@elaraai/e3-core](https://www.npmjs.com/package/@elaraai/e3-core): Git-like object store, task queue, result caching
   - [@elaraai/e3-types](https://www.npmjs.com/package/@elaraai/e3-types): Shared type definitions for e3 packages
-  - [@elaraai/e3-cli](https://www.npmjs.com/package/@elaraai/e3-cli): `e3 init`, `e3 run`, `e3 logs` commands for managing and monitoring tasks
+  - [@elaraai/e3-cli](https://www.npmjs.com/package/@elaraai/e3-cli): `e3 repo`, `e3 workspace`, `e3 start`, `e3 logs` commands for managing repositories, workspaces, and tasks
   - [@elaraai/e3-api-client](https://www.npmjs.com/package/@elaraai/e3-api-client): HTTP client for remote e3 servers
   - [@elaraai/e3-api-server](https://www.npmjs.com/package/@elaraai/e3-api-server): REST API server for e3 repositories
 

package/dist/src/dataflow.d.ts

@@ -0,0 +1,376 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Dataflow execution state type definitions.
+ *
+ * These types define the persistent state for dataflow execution,
+ * stored in workspaces/<ws>/execution.beast2
+ *
+ * Key design decisions:
+ * - Dates are Date objects (via DateTimeType), not strings
+ * - Events stored inline as array (single file, not separate JSONL)
+ * - Tasks stored as Dict (not Map) for beast2 compatibility
+ */
+import { StructType, VariantType, ArrayType, DictType, StringType, IntegerType, BooleanType, DateTimeType, OptionType, ValueTypeOf } from '@elaraai/east';
+/**
+ * Status of a dataflow execution.
+ */
+export type DataflowExecutionStatus = 'running' | 'completed' | 'failed' | 'cancelled';
+/**
+ * Status of an individual task within an execution.
+ */
+export type TaskStatus = 'pending' | 'ready' | 'in_progress' | 'completed' | 'failed' | 'skipped';
+/**
+ * Information about a task's execution state.
+ *
+ * Stored in the tasks Dict of DataflowExecutionStateType.
+ */
+export declare const TaskStateType: StructType<{
+    /** Task name */
+    readonly name: StringType;
+    /** Current status (TaskStatus as string) */
+    readonly status: StringType;
+    /** Whether the result was served from cache */
+    readonly cached: OptionType<BooleanType>;
+    /** Output hash if completed successfully */
+    readonly outputHash: OptionType<StringType>;
+    /** Error message if failed */
+    readonly error: OptionType<StringType>;
+    /** Exit code if task process failed */
+    readonly exitCode: OptionType<IntegerType>;
+    /** When the task started */
+    readonly startedAt: OptionType<DateTimeType>;
+    /** When the task completed */
+    readonly completedAt: OptionType<DateTimeType>;
+    /** Duration in milliseconds */
+    readonly duration: OptionType<IntegerType>;
+}>;
+export type TaskState = ValueTypeOf<typeof TaskStateType>;
+/**
+ * A task within the dataflow graph.
+ */
+export declare const DataflowGraphTaskType: StructType<{
+    /** Task name */
+    readonly name: StringType;
+    /** Task object hash */
+    readonly hash: StringType;
+    /** Input dataset paths */
+    readonly inputs: ArrayType<StringType>;
+    /** Output dataset path */
+    readonly output: StringType;
+    /** Names of tasks this depends on */
+    readonly dependsOn: ArrayType<StringType>;
+}>;
+export type DataflowGraphTask = ValueTypeOf<typeof DataflowGraphTaskType>;
+/**
+ * The complete dataflow dependency graph.
+ */
+export declare const DataflowGraphType: StructType<{
+    /** All tasks in the graph */
+    readonly tasks: ArrayType<StructType<{
+        /** Task name */
+        readonly name: StringType;
+        /** Task object hash */
+        readonly hash: StringType;
+        /** Input dataset paths */
+        readonly inputs: ArrayType<StringType>;
+        /** Output dataset path */
+        readonly output: StringType;
+        /** Names of tasks this depends on */
+        readonly dependsOn: ArrayType<StringType>;
+    }>>;
+}>;
+export type DataflowGraph = ValueTypeOf<typeof DataflowGraphType>;
+/**
+ * Execution events (VariantType for discriminated union).
+ *
+ * Events track the progress of a dataflow execution and are stored
+ * inline in the execution state (not as a separate JSONL file).
+ */
+export declare const ExecutionEventType: VariantType<{
+    /** Execution started */
+    readonly execution_started: StructType<{
+        /** Event sequence number */
+        readonly seq: IntegerType;
+        /** When the event occurred */
+        readonly timestamp: DateTimeType;
+        /** Execution ID */
+        readonly executionId: StringType;
+        /** Total number of tasks in the graph */
+        readonly totalTasks: IntegerType;
+    }>;
+    /** Task became ready to execute */
+    readonly task_ready: StructType<{
+        /** Event sequence number */
+        readonly seq: IntegerType;
+        /** When the event occurred */
+        readonly timestamp: DateTimeType;
+        /** Task name */
+        readonly task: StringType;
+    }>;
+    /** Task execution started */
+    readonly task_started: StructType<{
+        /** Event sequence number */
+        readonly seq: IntegerType;
+        /** When the event occurred */
+        readonly timestamp: DateTimeType;
+        /** Task name */
+        readonly task: StringType;
+    }>;
+    /** Task completed successfully */
+    readonly task_completed: StructType<{
+        /** Event sequence number */
+        readonly seq: IntegerType;
+        /** When the event occurred */
+        readonly timestamp: DateTimeType;
+        /** Task name */
+        readonly task: StringType;
+        /** Whether the result was served from cache */
+        readonly cached: BooleanType;
+        /** Output hash */
+        readonly outputHash: StringType;
+        /** Duration in milliseconds */
+        readonly duration: IntegerType;
+    }>;
+    /** Task failed */
+    readonly task_failed: StructType<{
+        /** Event sequence number */
+        readonly seq: IntegerType;
+        /** When the event occurred */
+        readonly timestamp: DateTimeType;
+        /** Task name */
+        readonly task: StringType;
+        /** Error message */
+        readonly error: OptionType<StringType>;
+        /** Exit code if task process failed */
+        readonly exitCode: OptionType<IntegerType>;
+        /** Duration in milliseconds */
+        readonly duration: IntegerType;
+    }>;
+    /** Task was skipped due to upstream failure */
+    readonly task_skipped: StructType<{
+        /** Event sequence number */
+        readonly seq: IntegerType;
+        /** When the event occurred */
+        readonly timestamp: DateTimeType;
+        /** Task name */
+        readonly task: StringType;
+        /** Name of the upstream task that caused the skip */
+        readonly cause: StringType;
+    }>;
+    /** Execution completed */
+    readonly execution_completed: StructType<{
+        /** Event sequence number */
+        readonly seq: IntegerType;
+        /** When the event occurred */
+        readonly timestamp: DateTimeType;
+        /** Whether all tasks succeeded */
+        readonly success: BooleanType;
+        /** Number of tasks executed (not from cache) */
+        readonly executed: IntegerType;
+        /** Number of tasks served from cache */
+        readonly cached: IntegerType;
+        /** Number of tasks that failed */
+        readonly failed: IntegerType;
+        /** Number of tasks skipped */
+        readonly skipped: IntegerType;
+        /** Total duration in milliseconds */
+        readonly duration: IntegerType;
+    }>;
+    /** Execution was cancelled */
+    readonly execution_cancelled: StructType<{
+        /** Event sequence number */
+        readonly seq: IntegerType;
+        /** When the event occurred */
+        readonly timestamp: DateTimeType;
+        /** Reason for cancellation */
+        readonly reason: OptionType<StringType>;
+    }>;
+}>;
+export type ExecutionEvent = ValueTypeOf<typeof ExecutionEventType>;
+/**
+ * Persistent state for a dataflow execution.
+ *
+ * Stored in workspaces/<ws>/execution.beast2
+ *
+ * @remarks
+ * - Tasks are stored as a Dict (serializes as object, not array of tuples)
+ * - Events are stored inline (not as separate JSONL file)
+ * - Dates are Date objects (via DateTimeType)
+ */
+export declare const DataflowExecutionStateType: StructType<{
+    /** Unique execution ID (local: auto-increment, cloud: UUID) */
+    readonly id: StringType;
+    /** Repository identifier */
+    readonly repo: StringType;
+    /** Workspace name */
+    readonly workspace: StringType;
+    /** When the execution started */
+    readonly startedAt: DateTimeType;
+    /** Maximum concurrent task executions */
+    readonly concurrency: IntegerType;
+    /** Force re-execution even if cached */
+    readonly force: BooleanType;
+    /** Filter to run only specific task(s) by exact name */
+    readonly filter: OptionType<StringType>;
+    /** The dependency graph (for local execution) */
+    readonly graph: OptionType<StructType<{
+        /** All tasks in the graph */
+        readonly tasks: ArrayType<StructType<{
+            /** Task name */
+            readonly name: StringType;
+            /** Task object hash */
+            readonly hash: StringType;
+            /** Input dataset paths */
+            readonly inputs: ArrayType<StringType>;
+            /** Output dataset path */
+            readonly output: StringType;
+            /** Names of tasks this depends on */
+            readonly dependsOn: ArrayType<StringType>;
+        }>>;
+    }>>;
+    /** Hash/key referencing a separately stored graph (for cloud) */
+    readonly graphHash: OptionType<StringType>;
+    /** Map of task name -> task state */
+    readonly tasks: DictType<StringType, StructType<{
+        /** Task name */
+        readonly name: StringType;
+        /** Current status (TaskStatus as string) */
+        readonly status: StringType;
+        /** Whether the result was served from cache */
+        readonly cached: OptionType<BooleanType>;
+        /** Output hash if completed successfully */
+        readonly outputHash: OptionType<StringType>;
+        /** Error message if failed */
+        readonly error: OptionType<StringType>;
+        /** Exit code if task process failed */
+        readonly exitCode: OptionType<IntegerType>;
+        /** When the task started */
+        readonly startedAt: OptionType<DateTimeType>;
+        /** When the task completed */
+        readonly completedAt: OptionType<DateTimeType>;
+        /** Duration in milliseconds */
+        readonly duration: OptionType<IntegerType>;
+    }>>;
+    /** Number of tasks executed (not from cache) */
+    readonly executed: IntegerType;
+    /** Number of tasks served from cache */
+    readonly cached: IntegerType;
+    /** Number of tasks that failed */
+    readonly failed: IntegerType;
+    /** Number of tasks skipped due to upstream failure */
+    readonly skipped: IntegerType;
+    /** Current execution status */
+    readonly status: StringType;
+    /** When the execution completed */
+    readonly completedAt: OptionType<DateTimeType>;
+    /** Error message if status is 'failed' */
+    readonly error: OptionType<StringType>;
+    /** All events for this execution */
+    readonly events: ArrayType<VariantType<{
+        /** Execution started */
+        readonly execution_started: StructType<{
+            /** Event sequence number */
+            readonly seq: IntegerType;
+            /** When the event occurred */
+            readonly timestamp: DateTimeType;
+            /** Execution ID */
+            readonly executionId: StringType;
+            /** Total number of tasks in the graph */
+            readonly totalTasks: IntegerType;
+        }>;
+        /** Task became ready to execute */
+        readonly task_ready: StructType<{
+            /** Event sequence number */
+            readonly seq: IntegerType;
+            /** When the event occurred */
+            readonly timestamp: DateTimeType;
+            /** Task name */
+            readonly task: StringType;
+        }>;
+        /** Task execution started */
+        readonly task_started: StructType<{
+            /** Event sequence number */
+            readonly seq: IntegerType;
+            /** When the event occurred */
+            readonly timestamp: DateTimeType;
+            /** Task name */
+            readonly task: StringType;
+        }>;
+        /** Task completed successfully */
+        readonly task_completed: StructType<{
+            /** Event sequence number */
+            readonly seq: IntegerType;
+            /** When the event occurred */
+            readonly timestamp: DateTimeType;
+            /** Task name */
+            readonly task: StringType;
+            /** Whether the result was served from cache */
+            readonly cached: BooleanType;
+            /** Output hash */
+            readonly outputHash: StringType;
+            /** Duration in milliseconds */
+            readonly duration: IntegerType;
+        }>;
+        /** Task failed */
+        readonly task_failed: StructType<{
+            /** Event sequence number */
+            readonly seq: IntegerType;
+            /** When the event occurred */
+            readonly timestamp: DateTimeType;
+            /** Task name */
+            readonly task: StringType;
+            /** Error message */
+            readonly error: OptionType<StringType>;
+            /** Exit code if task process failed */
+            readonly exitCode: OptionType<IntegerType>;
+            /** Duration in milliseconds */
+            readonly duration: IntegerType;
+        }>;
+        /** Task was skipped due to upstream failure */
+        readonly task_skipped: StructType<{
+            /** Event sequence number */
+            readonly seq: IntegerType;
+            /** When the event occurred */
+            readonly timestamp: DateTimeType;
+            /** Task name */
+            readonly task: StringType;
+            /** Name of the upstream task that caused the skip */
+            readonly cause: StringType;
+        }>;
+        /** Execution completed */
+        readonly execution_completed: StructType<{
+            /** Event sequence number */
+            readonly seq: IntegerType;
+            /** When the event occurred */
+            readonly timestamp: DateTimeType;
+            /** Whether all tasks succeeded */
+            readonly success: BooleanType;
+            /** Number of tasks executed (not from cache) */
+            readonly executed: IntegerType;
+            /** Number of tasks served from cache */
+            readonly cached: IntegerType;
+            /** Number of tasks that failed */
+            readonly failed: IntegerType;
+            /** Number of tasks skipped */
+            readonly skipped: IntegerType;
+            /** Total duration in milliseconds */
+            readonly duration: IntegerType;
+        }>;
+        /** Execution was cancelled */
+        readonly execution_cancelled: StructType<{
+            /** Event sequence number */
+            readonly seq: IntegerType;
+            /** When the event occurred */
+            readonly timestamp: DateTimeType;
+            /** Reason for cancellation */
+            readonly reason: OptionType<StringType>;
+        }>;
+    }>>;
+    /** Sequence number for next event (auto-increment) */
+    readonly eventSeq: IntegerType;
+}>;
+export type DataflowExecutionState = ValueTypeOf<typeof DataflowExecutionStateType>;
+//# sourceMappingURL=dataflow.d.ts.map

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

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

package/dist/src/dataflow.js

@@ -0,0 +1,239 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Dataflow execution state type definitions.
+ *
+ * These types define the persistent state for dataflow execution,
+ * stored in workspaces/<ws>/execution.beast2
+ *
+ * Key design decisions:
+ * - Dates are Date objects (via DateTimeType), not strings
+ * - Events stored inline as array (single file, not separate JSONL)
+ * - Tasks stored as Dict (not Map) for beast2 compatibility
+ */
+import { StructType, VariantType, ArrayType, DictType, StringType, IntegerType, BooleanType, DateTimeType, OptionType, } from '@elaraai/east';
+// =============================================================================
+// Task State
+// =============================================================================
+/**
+ * Information about a task's execution state.
+ *
+ * Stored in the tasks Dict of DataflowExecutionStateType.
+ */
+export const TaskStateType = StructType({
+    /** Task name */
+    name: StringType,
+    /** Current status (TaskStatus as string) */
+    status: StringType,
+    /** Whether the result was served from cache */
+    cached: OptionType(BooleanType),
+    /** Output hash if completed successfully */
+    outputHash: OptionType(StringType),
+    /** Error message if failed */
+    error: OptionType(StringType),
+    /** Exit code if task process failed */
+    exitCode: OptionType(IntegerType),
+    /** When the task started */
+    startedAt: OptionType(DateTimeType),
+    /** When the task completed */
+    completedAt: OptionType(DateTimeType),
+    /** Duration in milliseconds */
+    duration: OptionType(IntegerType),
+});
+// =============================================================================
+// Graph Types
+// =============================================================================
+/**
+ * A task within the dataflow graph.
+ */
+export const DataflowGraphTaskType = StructType({
+    /** Task name */
+    name: StringType,
+    /** Task object hash */
+    hash: StringType,
+    /** Input dataset paths */
+    inputs: ArrayType(StringType),
+    /** Output dataset path */
+    output: StringType,
+    /** Names of tasks this depends on */
+    dependsOn: ArrayType(StringType),
+});
+/**
+ * The complete dataflow dependency graph.
+ */
+export const DataflowGraphType = StructType({
+    /** All tasks in the graph */
+    tasks: ArrayType(DataflowGraphTaskType),
+});
+// =============================================================================
+// Event Types
+// =============================================================================
+/**
+ * Execution events (VariantType for discriminated union).
+ *
+ * Events track the progress of a dataflow execution and are stored
+ * inline in the execution state (not as a separate JSONL file).
+ */
+export const ExecutionEventType = VariantType({
+    /** Execution started */
+    execution_started: StructType({
+        /** Event sequence number */
+        seq: IntegerType,
+        /** When the event occurred */
+        timestamp: DateTimeType,
+        /** Execution ID */
+        executionId: StringType,
+        /** Total number of tasks in the graph */
+        totalTasks: IntegerType,
+    }),
+    /** Task became ready to execute */
+    task_ready: StructType({
+        /** Event sequence number */
+        seq: IntegerType,
+        /** When the event occurred */
+        timestamp: DateTimeType,
+        /** Task name */
+        task: StringType,
+    }),
+    /** Task execution started */
+    task_started: StructType({
+        /** Event sequence number */
+        seq: IntegerType,
+        /** When the event occurred */
+        timestamp: DateTimeType,
+        /** Task name */
+        task: StringType,
+    }),
+    /** Task completed successfully */
+    task_completed: StructType({
+        /** Event sequence number */
+        seq: IntegerType,
+        /** When the event occurred */
+        timestamp: DateTimeType,
+        /** Task name */
+        task: StringType,
+        /** Whether the result was served from cache */
+        cached: BooleanType,
+        /** Output hash */
+        outputHash: StringType,
+        /** Duration in milliseconds */
+        duration: IntegerType,
+    }),
+    /** Task failed */
+    task_failed: StructType({
+        /** Event sequence number */
+        seq: IntegerType,
+        /** When the event occurred */
+        timestamp: DateTimeType,
+        /** Task name */
+        task: StringType,
+        /** Error message */
+        error: OptionType(StringType),
+        /** Exit code if task process failed */
+        exitCode: OptionType(IntegerType),
+        /** Duration in milliseconds */
+        duration: IntegerType,
+    }),
+    /** Task was skipped due to upstream failure */
+    task_skipped: StructType({
+        /** Event sequence number */
+        seq: IntegerType,
+        /** When the event occurred */
+        timestamp: DateTimeType,
+        /** Task name */
+        task: StringType,
+        /** Name of the upstream task that caused the skip */
+        cause: StringType,
+    }),
+    /** Execution completed */
+    execution_completed: StructType({
+        /** Event sequence number */
+        seq: IntegerType,
+        /** When the event occurred */
+        timestamp: DateTimeType,
+        /** Whether all tasks succeeded */
+        success: BooleanType,
+        /** Number of tasks executed (not from cache) */
+        executed: IntegerType,
+        /** Number of tasks served from cache */
+        cached: IntegerType,
+        /** Number of tasks that failed */
+        failed: IntegerType,
+        /** Number of tasks skipped */
+        skipped: IntegerType,
+        /** Total duration in milliseconds */
+        duration: IntegerType,
+    }),
+    /** Execution was cancelled */
+    execution_cancelled: StructType({
+        /** Event sequence number */
+        seq: IntegerType,
+        /** When the event occurred */
+        timestamp: DateTimeType,
+        /** Reason for cancellation */
+        reason: OptionType(StringType),
+    }),
+});
+// =============================================================================
+// Main Execution State
+// =============================================================================
+/**
+ * Persistent state for a dataflow execution.
+ *
+ * Stored in workspaces/<ws>/execution.beast2
+ *
+ * @remarks
+ * - Tasks are stored as a Dict (serializes as object, not array of tuples)
+ * - Events are stored inline (not as separate JSONL file)
+ * - Dates are Date objects (via DateTimeType)
+ */
+export const DataflowExecutionStateType = StructType({
+    // Identity
+    /** Unique execution ID (local: auto-increment, cloud: UUID) */
+    id: StringType,
+    /** Repository identifier */
+    repo: StringType,
+    /** Workspace name */
+    workspace: StringType,
+    /** When the execution started */
+    startedAt: DateTimeType,
+    // Config (immutable after initialization)
+    /** Maximum concurrent task executions */
+    concurrency: IntegerType,
+    /** Force re-execution even if cached */
+    force: BooleanType,
+    /** Filter to run only specific task(s) by exact name */
+    filter: OptionType(StringType),
+    // Graph (inline or by reference)
+    /** The dependency graph (for local execution) */
+    graph: OptionType(DataflowGraphType),
+    /** Hash/key referencing a separately stored graph (for cloud) */
+    graphHash: OptionType(StringType),
+    // Task tracking
+    /** Map of task name -> task state */
+    tasks: DictType(StringType, TaskStateType),
+    // Summary counters
+    /** Number of tasks executed (not from cache) */
+    executed: IntegerType,
+    /** Number of tasks served from cache */
+    cached: IntegerType,
+    /** Number of tasks that failed */
+    failed: IntegerType,
+    /** Number of tasks skipped due to upstream failure */
+    skipped: IntegerType,
+    // Status
+    /** Current execution status */
+    status: StringType, // DataflowExecutionStatus
+    /** When the execution completed */
+    completedAt: OptionType(DateTimeType),
+    /** Error message if status is 'failed' */
+    error: OptionType(StringType),
+    // Events (inline array)
+    /** All events for this execution */
+    events: ArrayType(ExecutionEventType),
+    /** Sequence number for next event (auto-increment) */
+    eventSeq: IntegerType,
+});
+//# sourceMappingURL=dataflow.js.map

package/dist/src/dataflow.js.map

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

package/dist/src/dataset.d.ts

@@ -35,13 +35,13 @@ import { VariantType, StringType, NullType, ValueTypeOf, StructType, EastType }
  */
 export declare const DataRefType: VariantType<{
     /** Unassigned value (e.g., pending task output) */
-    unassigned: NullType;
+    readonly unassigned: NullType;
     /** Inline null value (optimization for NullType) */
-    null: NullType;
+    readonly null: NullType;
     /** Hash of a beast2 value blob in objects/ */
-    value: StringType;
+    readonly value: StringType;
     /** Hash of a tree object in objects/ */
-    tree: StringType;
+    readonly tree: StringType;
 }>;
 export type DataRefType = typeof DataRefType;
 export type DataRef = ValueTypeOf<typeof DataRefType>;