@elaraai/e3-types 0.0.2-beta.5 → 0.0.2-beta.50

package/dist/src/dataflow.js

@@ -0,0 +1,366 @@
+/**
+ * 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),
+    }),
+    /** An input dataset changed during execution (reactive dataflow) */
+    input_changed: StructType({
+        /** Event sequence number */
+        seq: IntegerType,
+        /** When the event occurred */
+        timestamp: DateTimeType,
+        /** Path of the changed input dataset */
+        path: StringType,
+        /** Previous hash (empty string if was unassigned) */
+        previousHash: StringType,
+        /** New hash */
+        newHash: StringType,
+    }),
+    /** A task was invalidated due to upstream input change */
+    task_invalidated: StructType({
+        /** Event sequence number */
+        seq: IntegerType,
+        /** When the event occurred */
+        timestamp: DateTimeType,
+        /** Task name */
+        task: StringType,
+        /** Reason for invalidation */
+        reason: StringType,
+    }),
+    /** A task was deferred due to inconsistent input versions */
+    task_deferred: StructType({
+        /** Event sequence number */
+        seq: IntegerType,
+        /** When the event occurred */
+        timestamp: DateTimeType,
+        /** Task name */
+        task: StringType,
+        /** Path where version conflict was detected */
+        conflictPath: 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),
+    // Reactive dataflow tracking
+    /** Version vectors: dataset keypath -> VersionVector (root input path -> hash) */
+    versionVectors: DictType(StringType, DictType(StringType, StringType)),
+    /** Input snapshot: root input keypath -> hash at time of last check */
+    inputSnapshot: DictType(StringType, StringType),
+    /** Set of dataset keypaths that are task outputs */
+    taskOutputPaths: ArrayType(StringType),
+    /** Number of tasks re-executed due to input changes */
+    reexecuted: IntegerType,
+    // Events (inline array)
+    /** All events for this execution */
+    events: ArrayType(ExecutionEventType),
+    /** Sequence number for next event (auto-increment) */
+    eventSeq: IntegerType,
+});
+// =============================================================================
+// Dataflow Run History
+// =============================================================================
+/**
+ * Status of a dataflow run.
+ */
+export const DataflowRunStatusType = VariantType({
+    /** Run is currently executing */
+    running: StructType({}),
+    /** Run completed successfully */
+    completed: StructType({}),
+    /** Run failed with a task error */
+    failed: StructType({
+        /** Name of the task that failed */
+        failedTask: StringType,
+        /** Error message */
+        error: StringType,
+    }),
+    /** Run was cancelled */
+    cancelled: StructType({}),
+});
+/**
+ * Record of a task execution within a dataflow run.
+ */
+export const TaskExecutionRecordType = StructType({
+    /** Execution ID (UUIDv7) */
+    executionId: StringType,
+    /** Whether this was a cache hit */
+    cached: BooleanType,
+    /** Output version vector (which root input versions produced this output) */
+    outputVersions: DictType(StringType, StringType),
+    /** Number of times this task was executed (including re-executions due to input changes) */
+    executionCount: IntegerType,
+});
+/**
+ * Summary statistics for a dataflow run.
+ */
+export const DataflowRunSummaryType = StructType({
+    /** Total number of tasks */
+    total: IntegerType,
+    /** Number of completed tasks */
+    completed: IntegerType,
+    /** Number of cached tasks */
+    cached: IntegerType,
+    /** Number of failed tasks */
+    failed: IntegerType,
+    /** Number of skipped tasks */
+    skipped: IntegerType,
+    /** Number of tasks re-executed due to input changes */
+    reexecuted: IntegerType,
+});
+/**
+ * A dataflow run record, tracking one execution of a workspace's dataflow.
+ *
+ * Stored in: dataflows/<workspace>/<runId>.beast2
+ *
+ * This provides execution history and provenance tracking:
+ * - Which tasks ran and which were cached
+ * - Input/output snapshots for reproducibility
+ * - Timing information for performance analysis
+ */
+export const DataflowRunType = StructType({
+    /** Run ID (UUIDv7) */
+    runId: StringType,
+    /** Workspace name */
+    workspaceName: StringType,
+    /** Package reference at run time (name@version) */
+    packageRef: StringType,
+    /** When the run started */
+    startedAt: DateTimeType,
+    /** When the run completed (null if still running) */
+    completedAt: OptionType(DateTimeType),
+    /** Current status of the run */
+    status: DataflowRunStatusType,
+    /** Input version snapshot at start (root input path -> hash) */
+    inputVersions: DictType(StringType, StringType),
+    /** Output version snapshot at end (null if still running) */
+    outputVersions: OptionType(DictType(StringType, StringType)),
+    /** Map of task name -> execution record */
+    taskExecutions: DictType(StringType, TaskExecutionRecordType),
+    /** Summary statistics */
+    summary: DataflowRunSummaryType,
+});
+//# 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-ref.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Per-dataset reference types for reactive dataflow.
+ *
+ * Each dataset in a workspace has its own `.ref` file instead of being
+ * part of a single root tree. This enables concurrent writes and
+ * reactive re-execution.
+ *
+ * A DatasetRef tracks:
+ * - The current value hash (or unassigned/null state)
+ * - A version vector mapping root input paths to their content hashes,
+ *   enabling consistency checking across task inputs.
+ */
+import { VariantType, StructType, DictType, StringType, NullType, type ValueTypeOf } from '@elaraai/east';
+/**
+ * Version vector: maps root input dataset path -> content hash.
+ *
+ * Used to track which version of each root input contributed to a
+ * dataset's current value. When a task executes, its output's version
+ * vector is the union of all input version vectors (which must agree
+ * on shared keys for consistency).
+ *
+ * @example
+ * ```ts
+ * // Root input version vector (self-referencing)
+ * const inputVV: VersionVector = new Map([
+ *   ['.inputs.sales', 'abc123...'],
+ * ]);
+ *
+ * // Derived dataset version vector (union of inputs)
+ * const derivedVV: VersionVector = new Map([
+ *   ['.inputs.sales', 'abc123...'],
+ *   ['.inputs.config', 'def456...'],
+ * ]);
+ * ```
+ */
+export declare const VersionVectorType: DictType<StringType, StringType>;
+export type VersionVectorType = typeof VersionVectorType;
+export type VersionVector = ValueTypeOf<typeof VersionVectorType>;
+/**
+ * Per-dataset reference stored in workspace data files.
+ *
+ * Each dataset has a `.ref` file at `workspaces/<ws>/data/<path>.ref`.
+ * The ref tracks the dataset's current state and version provenance.
+ *
+ * Variants:
+ * - `unassigned`: Dataset has no value yet (e.g., pending task output)
+ * - `null`: Dataset has been explicitly set to null, with version tracking
+ * - `value`: Dataset has a value hash in the object store, with version tracking
+ *
+ * @example
+ * ```ts
+ * // Unassigned (initial state for task outputs)
+ * const ref: DatasetRef = variant('unassigned', null);
+ *
+ * // Null value with version tracking
+ * const ref: DatasetRef = variant('null', {
+ *   versions: new Map([['.inputs.sales', 'abc123...']]),
+ * });
+ *
+ * // Value with version tracking
+ * const ref: DatasetRef = variant('value', {
+ *   hash: 'def456...',
+ *   versions: new Map([['.inputs.sales', 'abc123...']]),
+ * });
+ * ```
+ */
+export declare const DatasetRefType: VariantType<{
+    /** Dataset has no value assigned */
+    readonly unassigned: NullType;
+    /** Dataset value is null, with version provenance */
+    readonly null: StructType<{
+        readonly versions: DictType<StringType, StringType>;
+    }>;
+    /** Dataset has a value in the object store, with version provenance */
+    readonly value: StructType<{
+        readonly hash: StringType;
+        readonly versions: DictType<StringType, StringType>;
+    }>;
+}>;
+export type DatasetRefType = typeof DatasetRefType;
+export type DatasetRef = ValueTypeOf<typeof DatasetRefType>;
+//# sourceMappingURL=dataset-ref.d.ts.map

package/dist/src/dataset-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataset-ref.d.ts","sourceRoot":"","sources":["../../src/dataset-ref.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAE1G;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,iBAAiB,kCAAmC,CAAC;AAClE,MAAM,MAAM,iBAAiB,GAAG,OAAO,iBAAiB,CAAC;AAEzD,MAAM,MAAM,aAAa,GAAG,WAAW,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,cAAc;IACzB,oCAAoC;;IAEpC,qDAAqD;;;;IAIrD,uEAAuE;;;;;EAKvE,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC;AAEnD,MAAM,MAAM,UAAU,GAAG,WAAW,CAAC,OAAO,cAAc,CAAC,CAAC"}

package/dist/src/dataset-ref.js

@@ -0,0 +1,82 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Per-dataset reference types for reactive dataflow.
+ *
+ * Each dataset in a workspace has its own `.ref` file instead of being
+ * part of a single root tree. This enables concurrent writes and
+ * reactive re-execution.
+ *
+ * A DatasetRef tracks:
+ * - The current value hash (or unassigned/null state)
+ * - A version vector mapping root input paths to their content hashes,
+ *   enabling consistency checking across task inputs.
+ */
+import { VariantType, StructType, DictType, StringType, NullType } from '@elaraai/east';
+/**
+ * Version vector: maps root input dataset path -> content hash.
+ *
+ * Used to track which version of each root input contributed to a
+ * dataset's current value. When a task executes, its output's version
+ * vector is the union of all input version vectors (which must agree
+ * on shared keys for consistency).
+ *
+ * @example
+ * ```ts
+ * // Root input version vector (self-referencing)
+ * const inputVV: VersionVector = new Map([
+ *   ['.inputs.sales', 'abc123...'],
+ * ]);
+ *
+ * // Derived dataset version vector (union of inputs)
+ * const derivedVV: VersionVector = new Map([
+ *   ['.inputs.sales', 'abc123...'],
+ *   ['.inputs.config', 'def456...'],
+ * ]);
+ * ```
+ */
+export const VersionVectorType = DictType(StringType, StringType);
+/**
+ * Per-dataset reference stored in workspace data files.
+ *
+ * Each dataset has a `.ref` file at `workspaces/<ws>/data/<path>.ref`.
+ * The ref tracks the dataset's current state and version provenance.
+ *
+ * Variants:
+ * - `unassigned`: Dataset has no value yet (e.g., pending task output)
+ * - `null`: Dataset has been explicitly set to null, with version tracking
+ * - `value`: Dataset has a value hash in the object store, with version tracking
+ *
+ * @example
+ * ```ts
+ * // Unassigned (initial state for task outputs)
+ * const ref: DatasetRef = variant('unassigned', null);
+ *
+ * // Null value with version tracking
+ * const ref: DatasetRef = variant('null', {
+ *   versions: new Map([['.inputs.sales', 'abc123...']]),
+ * });
+ *
+ * // Value with version tracking
+ * const ref: DatasetRef = variant('value', {
+ *   hash: 'def456...',
+ *   versions: new Map([['.inputs.sales', 'abc123...']]),
+ * });
+ * ```
+ */
+export const DatasetRefType = VariantType({
+    /** Dataset has no value assigned */
+    unassigned: NullType,
+    /** Dataset value is null, with version provenance */
+    null: StructType({
+        versions: VersionVectorType,
+    }),
+    /** Dataset has a value in the object store, with version provenance */
+    value: StructType({
+        hash: StringType,
+        versions: VersionVectorType,
+    }),
+});
+//# sourceMappingURL=dataset-ref.js.map

package/dist/src/dataset-ref.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataset-ref.js","sourceRoot":"","sources":["../../src/dataset-ref.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAoB,MAAM,eAAe,CAAC;AAE1G;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;AAKlE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,WAAW,CAAC;IACxC,oCAAoC;IACpC,UAAU,EAAE,QAAQ;IACpB,qDAAqD;IACrD,IAAI,EAAE,UAAU,CAAC;QACf,QAAQ,EAAE,iBAAiB;KAC5B,CAAC;IACF,uEAAuE;IACvE,KAAK,EAAE,UAAU,CAAC;QAChB,IAAI,EAAE,UAAU;QAChB,QAAQ,EAAE,iBAAiB;KAC5B,CAAC;CACH,CAAC,CAAC"}

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>;

package/dist/src/execution.d.ts

@@ -30,50 +30,58 @@ import { VariantType, StructType, ArrayType, StringType, IntegerType, DateTimeTy
  */
 export declare const ExecutionStatusType: VariantType<{
     /** Task has been launched but not yet completed */
-    running: StructType<{
+    readonly running: StructType<{
+        /** Unique execution ID (UUIDv7) */
+        readonly executionId: StringType;
         /** Input dataset hashes */
-        inputHashes: ArrayType<StringType>;
+        readonly inputHashes: ArrayType<StringType>;
         /** When execution started */
-        startedAt: DateTimeType;
+        readonly startedAt: DateTimeType;
         /** Process ID of the runner */
-        pid: IntegerType;
+        readonly pid: IntegerType;
         /** Process start time in jiffies since boot (from /proc/<pid>/stat field 22) */
-        pidStartTime: IntegerType;
+        readonly pidStartTime: IntegerType;
         /** System boot ID (from /proc/sys/kernel/random/boot_id) */
-        bootId: StringType;
+        readonly bootId: StringType;
     }>;
     /** Task ran and returned exit code 0 */
-    success: StructType<{
+    readonly success: StructType<{
+        /** Unique execution ID (UUIDv7) */
+        readonly executionId: StringType;
         /** Input dataset hashes */
-        inputHashes: ArrayType<StringType>;
+        readonly inputHashes: ArrayType<StringType>;
         /** Hash of the output dataset */
-        outputHash: StringType;
+        readonly outputHash: StringType;
         /** When execution started */
-        startedAt: DateTimeType;
+        readonly startedAt: DateTimeType;
         /** When execution completed */
-        completedAt: DateTimeType;
+        readonly completedAt: DateTimeType;
     }>;
     /** Task ran and returned non-zero exit code */
-    failed: StructType<{
+    readonly failed: StructType<{
+        /** Unique execution ID (UUIDv7) */
+        readonly executionId: StringType;
         /** Input dataset hashes */
-        inputHashes: ArrayType<StringType>;
+        readonly inputHashes: ArrayType<StringType>;
         /** When execution started */
-        startedAt: DateTimeType;
+        readonly startedAt: DateTimeType;
         /** When execution completed */
-        completedAt: DateTimeType;
+        readonly completedAt: DateTimeType;
         /** Process exit code */
-        exitCode: IntegerType;
+        readonly exitCode: IntegerType;
     }>;
     /** e3 execution engine had an internal error */
-    error: StructType<{
+    readonly error: StructType<{
+        /** Unique execution ID (UUIDv7) */
+        readonly executionId: StringType;
         /** Input dataset hashes */
-        inputHashes: ArrayType<StringType>;
+        readonly inputHashes: ArrayType<StringType>;
         /** When execution started */
-        startedAt: DateTimeType;
+        readonly startedAt: DateTimeType;
         /** When execution completed */
-        completedAt: DateTimeType;
+        readonly completedAt: DateTimeType;
         /** Error message describing what went wrong */
-        message: StringType;
+        readonly message: StringType;
     }>;
 }>;
 export type ExecutionStatus = ValueTypeOf<typeof ExecutionStatusType>;

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

@@ -1 +1 @@
-{"version":3,"file":"execution.d.ts","sourceRoot":"","sources":["../../src/execution.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,WAAW,EACX,UAAU,EACV,SAAS,EACT,UAAU,EACV,WAAW,EACX,YAAY,EACZ,WAAW,EACZ,MAAM,eAAe,CAAC;AAEvB;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB;IAC9B,mDAAmD;;QAEjD,2BAA2B;;QAE3B,6BAA6B;;QAE7B,+BAA+B;;QAE/B,gFAAgF;;QAEhF,4DAA4D;;;IAG9D,wCAAwC;;QAEtC,2BAA2B;;QAE3B,iCAAiC;;QAEjC,6BAA6B;;QAE7B,+BAA+B;;;IAGjC,+CAA+C;;QAE7C,2BAA2B;;QAE3B,6BAA6B;;QAE7B,+BAA+B;;QAE/B,wBAAwB;;;IAG1B,gDAAgD;;QAE9C,2BAA2B;;QAE3B,6BAA6B;;QAE7B,+BAA+B;;QAE/B,+CAA+C;;;EAGjD,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,WAAW,CAAC,OAAO,mBAAmB,CAAC,CAAC"}
+{"version":3,"file":"execution.d.ts","sourceRoot":"","sources":["../../src/execution.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,WAAW,EACX,UAAU,EACV,SAAS,EACT,UAAU,EACV,WAAW,EACX,YAAY,EACZ,WAAW,EACZ,MAAM,eAAe,CAAC;AAEvB;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB;IAC9B,mDAAmD;;QAEjD,mCAAmC;;QAEnC,2BAA2B;;QAE3B,6BAA6B;;QAE7B,+BAA+B;;QAE/B,gFAAgF;;QAEhF,4DAA4D;;;IAG9D,wCAAwC;;QAEtC,mCAAmC;;QAEnC,2BAA2B;;QAE3B,iCAAiC;;QAEjC,6BAA6B;;QAE7B,+BAA+B;;;IAGjC,+CAA+C;;QAE7C,mCAAmC;;QAEnC,2BAA2B;;QAE3B,6BAA6B;;QAE7B,+BAA+B;;QAE/B,wBAAwB;;;IAG1B,gDAAgD;;QAE9C,mCAAmC;;QAEnC,2BAA2B;;QAE3B,6BAA6B;;QAE7B,+BAA+B;;QAE/B,+CAA+C;;;EAGjD,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,WAAW,CAAC,OAAO,mBAAmB,CAAC,CAAC"}