@elaraai/e3-types 0.0.1-beta.0

package/dist/src/structure.js

@@ -0,0 +1,236 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Data structure and path types for e3.
+ *
+ * Terminology:
+ * - **Dataset**: A location holding a value (leaf node in the data tree)
+ * - **Tree**: A location containing datasets or nested trees (branch node)
+ * - **Structure**: The shape of the data tree (what trees/datasets exist and their types)
+ * - **Path**: An address pointing to a dataset or tree
+ *
+ * Paths use East's keypath syntax:
+ * - `.field` for struct field access (backtick-quoted for special chars)
+ * - `[N]` for array index access (future)
+ * - `[key]` for dict key lookup (future)
+ *
+ * @see East serialization docs for keypath syntax details
+ */
+import { VariantType, StringType, ArrayType, DictType, RecursiveType, printIdentifier, variant, EastTypeType } from '@elaraai/east';
+/**
+ * Structure definition for a data tree node.
+ *
+ * Defines the shape of the data tree - which paths are datasets (hold values)
+ * and which are trees (hold other nodes).
+ *
+ * @remarks
+ * - `value`: A dataset - holds a typed value. The type is an `EastTypeValue`.
+ * - `struct`: A tree - has named children, each with its own structure.
+ *
+ * MVP only supports struct trees. Future: array, dict, variant trees.
+ *
+ * @example
+ * ```ts
+ * // A dataset holding an Integer value
+ * const dataset: Structure = variant('value', variant('Integer', null));
+ *
+ * // A tree with named children
+ * const tree: Structure = variant('struct', new Map([
+ *   ['count', variant('value', variant('Integer', null))],
+ *   ['items', variant('value', variant('Array', variant('String', null)))],
+ * ]));
+ * ```
+ */
+export const StructureType = RecursiveType(self => VariantType({
+    /** Dataset: East type of the value (homoiconic EastTypeValue) */
+    value: EastTypeType,
+    /** Struct tree: named children mapping to child structures */
+    struct: DictType(StringType, self),
+}));
+// Backwards compatibility alias
+/** @deprecated Use StructureType instead */
+export const DatasetSchemaType = StructureType;
+/**
+ * Path segment for navigating data trees.
+ *
+ * Uses East keypath syntax for consistency:
+ * - `field`: Struct field access (rendered as `.field` or `` .`field` `` if quoted)
+ * - `index`: Array element access (rendered as `[N]`) - future
+ * - `key`: Dict key lookup (rendered as `[key]`) - future
+ *
+ * @example
+ * ```ts
+ * // Struct field access
+ * const segment: PathSegment = variant('field', 'sales');
+ *
+ * // Array index (future)
+ * const segment: PathSegment = variant('index', 0n);
+ * ```
+ */
+export const PathSegmentType = VariantType({
+    /** Struct field access by name */
+    field: StringType,
+    // Future: case: StringType for variant case identifiers
+    // Future: index: IntegerType for array access
+    // Future: key: StringType (or polymorphic) for dict access
+});
+/**
+ * Path: sequence of segments identifying a location in a data tree.
+ *
+ * Paths point to either a dataset (leaf) or a tree (branch).
+ * Used by tasks to specify where inputs come from and where outputs go.
+ *
+ * @example
+ * ```ts
+ * // Path to .inputs.sales.data
+ * const path: TreePath = [
+ *   variant('field', 'inputs'),
+ *   variant('field', 'sales'),
+ *   variant('field', 'data'),
+ * ];
+ * ```
+ */
+export const TreePathType = ArrayType(PathSegmentType);
+/**
+ * Converts a path to East keypath string representation.
+ *
+ * Uses East's keypath syntax: `.field` for simple identifiers,
+ * `` .`field` `` for identifiers needing quoting.
+ *
+ * @param path - The path to convert
+ * @returns A keypath string (e.g., ".inputs.sales" or ".inputs.`my/field`")
+ *
+ * @example
+ * ```ts
+ * const path = treePath('inputs', 'sales');
+ * pathToString(path); // ".inputs.sales"
+ *
+ * const path2 = treePath('inputs', 'my/field');
+ * pathToString(path2); // ".inputs.`my/field`"
+ * ```
+ */
+export function pathToString(path) {
+    return path.map(segment => {
+        if (segment.type === 'field') {
+            return '.' + printIdentifier(segment.value);
+        }
+        else {
+            throw new Error(`pathToString: unsupported path segment type: ${segment.type}`);
+        }
+    }).join('');
+}
+/**
+ * Parses an East keypath string into a path, validating against the structure.
+ *
+ * Supports `.field` syntax for struct field access.
+ * Backtick-quoted identifiers (`` .`field` ``) are supported for special chars.
+ *
+ * @param pathStr - A keypath string (e.g., ".inputs.sales")
+ * @param structure - The root structure to validate against
+ * @returns The parsed path and the structure at that location
+ *
+ * @throws {Error} If a field doesn't exist in the structure or path descends into a dataset
+ *
+ * @remarks
+ * - Empty string returns empty path (root) with the root structure
+ * - Path must start with `.` (no leading slash)
+ * - Backtick escaping: `` \` `` for literal backtick, `\\` for backslash
+ * - Future: will disambiguate variant cases from struct fields using structure
+ * - Future: will use structure to parse dict keys with correct type
+ *
+ * @example
+ * ```ts
+ * const structure = variant('struct', new Map([
+ *   ['inputs', variant('struct', new Map([
+ *     ['sales', variant('value', variant('Integer', null))],
+ *   ]))],
+ * ]));
+ *
+ * const { path, structure: leafStructure } = parsePath('.inputs.sales', structure);
+ * // path = [field('inputs'), field('sales')]
+ * // leafStructure = variant('value', variant('Integer', null))
+ * ```
+ */
+export function parsePath(pathStr, structure) {
+    if (pathStr === '')
+        return { path: [], structure };
+    const segments = [];
+    let currentStructure = structure;
+    let pos = 0;
+    while (pos < pathStr.length) {
+        if (pathStr[pos] === '.') {
+            pos++;
+            // Parse identifier (TODO: export parseIdentifier from east package)
+            let fieldName;
+            // Check for backtick-quoted identifier
+            if (pos < pathStr.length && pathStr[pos] === '`') {
+                pos++;
+                fieldName = '';
+                while (pos < pathStr.length && pathStr[pos] !== '`') {
+                    if (pathStr[pos] === '\\' && pos + 1 < pathStr.length) {
+                        // Escape sequence
+                        pos++;
+                        fieldName += pathStr[pos];
+                    }
+                    else {
+                        fieldName += pathStr[pos];
+                    }
+                    pos++;
+                }
+                if (pos < pathStr.length && pathStr[pos] === '`') {
+                    pos++; // consume closing backtick
+                }
+            }
+            else {
+                // Simple identifier: [a-zA-Z_][a-zA-Z0-9_]*
+                fieldName = '';
+                while (pos < pathStr.length && /[a-zA-Z0-9_]/.test(pathStr[pos])) {
+                    fieldName += pathStr[pos];
+                    pos++;
+                }
+            }
+            if (fieldName.length === 0) {
+                throw new Error(`parsePath: expected identifier after '.' at position ${pos}`);
+            }
+            // Validate against structure
+            if (currentStructure.type === 'value') {
+                throw new Error(`parsePath: cannot descend into dataset at '${pathToString(segments)}'`);
+            }
+            // currentStructure.type === 'struct' (only other option after 'value' check)
+            const fields = currentStructure.value;
+            const childStructure = fields.get(fieldName);
+            if (childStructure === undefined) {
+                const available = [...fields.keys()].map(k => printIdentifier(k)).join(', ');
+                throw new Error(`parsePath: field '${fieldName}' not found at '${pathToString(segments)}'. Available: ${available}`);
+            }
+            segments.push(variant('field', fieldName));
+            currentStructure = childStructure;
+        }
+        else {
+            throw new Error(`parsePath: unexpected character at position ${pos}: '${pathStr[pos]}'`);
+        }
+    }
+    return { path: segments, structure: currentStructure };
+}
+/**
+ * Creates a path from field names, validating against the structure.
+ *
+ * Convenience function for the common case of navigating through struct fields.
+ *
+ * @param structure - The root structure to validate against
+ * @param fields - Field names to include in the path
+ * @returns The parsed path and the structure at that location
+ *
+ * @throws {Error} If a field doesn't exist in the structure
+ *
+ * @example
+ * ```ts
+ * const { path, structure: leafStructure } = treePath(rootStructure, 'inputs', 'sales');
+ * ```
+ */
+export function treePath(structure, ...fields) {
+    return parsePath('.' + fields.map(printIdentifier).join('.'), structure);
+}
+//# sourceMappingURL=structure.js.map

package/dist/src/structure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structure.js","sourceRoot":"","sources":["../../src/structure.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,aAAa,EAAe,eAAe,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAEjJ;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC,WAAW,CAAC;IAC7D,iEAAiE;IACjE,KAAK,EAAE,YAAY;IACnB,8DAA8D;IAC9D,MAAM,EAAE,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC;CACnC,CAAC,CAAC,CAAC;AAKJ,gCAAgC;AAChC,4CAA4C;AAC5C,MAAM,CAAC,MAAM,iBAAiB,GAAG,aAAa,CAAC;AAM/C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,WAAW,CAAC;IACzC,kCAAkC;IAClC,KAAK,EAAE,UAAU;IACjB,wDAAwD;IACxD,8CAA8C;IAC9C,2DAA2D;CAC5D,CAAC,CAAC;AAKH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,SAAS,CAAC,eAAe,CAAC,CAAC;AAKvD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,YAAY,CAAC,IAAc;IACzC,OAAO,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE;QACxB,IAAI,OAAO,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;YAC7B,OAAO,GAAG,GAAG,eAAe,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAC9C,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,KAAK,CAAC,gDAAgD,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;QAClF,CAAC;IACH,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACd,CAAC;AAYD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,SAAS,CAAC,OAAe,EAAE,SAAoB;IAC7D,IAAI,OAAO,KAAK,EAAE;QAAE,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC;IAEnD,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,IAAI,gBAAgB,GAAG,SAAS,CAAC;IACjC,IAAI,GAAG,GAAG,CAAC,CAAC;IAEZ,OAAO,GAAG,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;QAC5B,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,GAAG,EAAE,CAAC;YACzB,GAAG,EAAE,CAAC;YAEN,oEAAoE;YACpE,IAAI,SAAiB,CAAC;YAEtB,uCAAuC;YACvC,IAAI,GAAG,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,GAAG,EAAE,CAAC;gBACjD,GAAG,EAAE,CAAC;gBACN,SAAS,GAAG,EAAE,CAAC;gBACf,OAAO,GAAG,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,GAAG,EAAE,CAAC;oBACpD,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,IAAI,IAAI,GAAG,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;wBACtD,kBAAkB;wBAClB,GAAG,EAAE,CAAC;wBACN,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC;oBAC5B,CAAC;yBAAM,CAAC;wBACN,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC;oBAC5B,CAAC;oBACD,GAAG,EAAE,CAAC;gBACR,CAAC;gBACD,IAAI,GAAG,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,GAAG,EAAE,CAAC;oBACjD,GAAG,EAAE,CAAC,CAAC,2BAA2B;gBACpC,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,4CAA4C;gBAC5C,SAAS,GAAG,EAAE,CAAC;gBACf,OAAO,GAAG,GAAG,OAAO,CAAC,MAAM,IAAI,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAE,CAAC,EAAE,CAAC;oBAClE,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC;oBAC1B,GAAG,EAAE,CAAC;gBACR,CAAC;YACH,CAAC;YAED,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC3B,MAAM,IAAI,KAAK,CAAC,wDAAwD,GAAG,EAAE,CAAC,CAAC;YACjF,CAAC;YAED,6BAA6B;YAC7B,IAAI,gBAAgB,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;gBACtC,MAAM,IAAI,KAAK,CAAC,8CAA8C,YAAY,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;YAC3F,CAAC;YAED,6EAA6E;YAC7E,MAAM,MAAM,GAAG,gBAAgB,CAAC,KAAK,CAAC;YACtC,MAAM,cAAc,GAAG,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YAC7C,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;gBACjC,MAAM,SAAS,GAAG,CAAC,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBAC7E,MAAM,IAAI,KAAK,CAAC,qBAAqB,SAAS,mBAAmB,YAAY,CAAC,QAAQ,CAAC,iBAAiB,SAAS,EAAE,CAAC,CAAC;YACvH,CAAC;YACD,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC;YAC3C,gBAAgB,GAAG,cAAc,CAAC;QACpC,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,KAAK,CAAC,+CAA+C,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC3F,CAAC;IACH,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,gBAAgB,EAAE,CAAC;AACzD,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,QAAQ,CAAC,SAAoB,EAAE,GAAG,MAAgB;IAChE,OAAO,SAAS,CAAC,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,SAAS,CAAC,CAAC;AAC3E,CAAC"}

package/dist/src/task.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Task object types for e3.
+ *
+ * A task object defines a complete executable unit: the command IR that
+ * generates the exec args, where to read inputs from, and where to write output.
+ *
+ * Task objects are stored in the object store and referenced by packages.
+ * They are content-addressed, enabling deduplication and memoization.
+ *
+ * Input and output types are inferred from the package's structure at the
+ * specified paths - the task just references locations, not types.
+ */
+import { StructType, StringType, ArrayType, ValueTypeOf } from '@elaraai/east';
+/**
+ * Task object stored in the object store.
+ *
+ * A task is a complete executable unit that reads from input dataset paths
+ * and writes to an output dataset path. The commandIr is evaluated at runtime
+ * to produce the exec args.
+ *
+ * @remarks
+ * - `commandIr`: Hash of East IR object that produces exec args
+ *   - IR signature: (inputs: Array<String>, output: String) -> Array<String>
+ *   - `inputs` are paths to staged input .beast2 files
+ *   - `output` is the path where output should be written
+ *   - Returns array of strings to exec (e.g., ["sh", "-c", "python ..."])
+ * - `inputs`: Paths to input datasets in the data tree
+ * - `output`: Path to the output dataset in the data tree
+ *
+ * Types are not stored in the task - they are inferred from the package's
+ * structure at the specified paths. This keeps tasks simple and avoids
+ * redundant type information.
+ *
+ * @example
+ * ```ts
+ * import { variant } from '@elaraai/east';
+ *
+ * // Task with command IR that generates: ["sh", "-c", "python script.py <input> <output>"]
+ * const task: TaskObject = {
+ *   commandIr: '5e7a3b...',  // hash of compiled IR
+ *   inputs: [
+ *     [variant('field', 'inputs'), variant('field', 'sales')],
+ *   ],
+ *   output: [variant('field', 'tasks'), variant('field', 'train'), variant('field', 'output')],
+ * };
+ * ```
+ */
+export declare const TaskObjectType: StructType<{
+    /** Hash of East IR that generates exec args: (inputs, output) -> Array<String> */
+    commandIr: StringType;
+    /** Input paths: where to read each input dataset from the data tree */
+    inputs: ArrayType<ArrayType<import("@elaraai/east").VariantType<{
+        field: StringType;
+    }>>>;
+    /** Output path: where to write the output dataset in the data tree */
+    output: ArrayType<import("@elaraai/east").VariantType<{
+        field: StringType;
+    }>>;
+}>;
+export type TaskObjectType = typeof TaskObjectType;
+export type TaskObject = ValueTypeOf<typeof TaskObjectType>;
+//# sourceMappingURL=task.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../src/task.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,cAAc;IACzB,kFAAkF;;IAElF,uEAAuE;;;;IAEvE,sEAAsE;;;;EAEtE,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC;AAEnD,MAAM,MAAM,UAAU,GAAG,WAAW,CAAC,OAAO,cAAc,CAAC,CAAC"}

package/dist/src/task.js

@@ -0,0 +1,61 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Task object types for e3.
+ *
+ * A task object defines a complete executable unit: the command IR that
+ * generates the exec args, where to read inputs from, and where to write output.
+ *
+ * Task objects are stored in the object store and referenced by packages.
+ * They are content-addressed, enabling deduplication and memoization.
+ *
+ * Input and output types are inferred from the package's structure at the
+ * specified paths - the task just references locations, not types.
+ */
+import { StructType, StringType, ArrayType } from '@elaraai/east';
+import { TreePathType } from './structure.js';
+/**
+ * Task object stored in the object store.
+ *
+ * A task is a complete executable unit that reads from input dataset paths
+ * and writes to an output dataset path. The commandIr is evaluated at runtime
+ * to produce the exec args.
+ *
+ * @remarks
+ * - `commandIr`: Hash of East IR object that produces exec args
+ *   - IR signature: (inputs: Array<String>, output: String) -> Array<String>
+ *   - `inputs` are paths to staged input .beast2 files
+ *   - `output` is the path where output should be written
+ *   - Returns array of strings to exec (e.g., ["sh", "-c", "python ..."])
+ * - `inputs`: Paths to input datasets in the data tree
+ * - `output`: Path to the output dataset in the data tree
+ *
+ * Types are not stored in the task - they are inferred from the package's
+ * structure at the specified paths. This keeps tasks simple and avoids
+ * redundant type information.
+ *
+ * @example
+ * ```ts
+ * import { variant } from '@elaraai/east';
+ *
+ * // Task with command IR that generates: ["sh", "-c", "python script.py <input> <output>"]
+ * const task: TaskObject = {
+ *   commandIr: '5e7a3b...',  // hash of compiled IR
+ *   inputs: [
+ *     [variant('field', 'inputs'), variant('field', 'sales')],
+ *   ],
+ *   output: [variant('field', 'tasks'), variant('field', 'train'), variant('field', 'output')],
+ * };
+ * ```
+ */
+export const TaskObjectType = StructType({
+    /** Hash of East IR that generates exec args: (inputs, output) -> Array<String> */
+    commandIr: StringType,
+    /** Input paths: where to read each input dataset from the data tree */
+    inputs: ArrayType(TreePathType),
+    /** Output path: where to write the output dataset in the data tree */
+    output: TreePathType,
+});
+//# sourceMappingURL=task.js.map

package/dist/src/task.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task.js","sourceRoot":"","sources":["../../src/task.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAe,MAAM,eAAe,CAAC;AAC/E,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,UAAU,CAAC;IACvC,kFAAkF;IAClF,SAAS,EAAE,UAAU;IACrB,uEAAuE;IACvE,MAAM,EAAE,SAAS,CAAC,YAAY,CAAC;IAC/B,sEAAsE;IACtE,MAAM,EAAE,YAAY;CACrB,CAAC,CAAC"}

package/dist/src/workspace.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Workspace state type definitions.
+ *
+ * A workspace is a mutable working copy of a package. The state tracks:
+ * - Which package was deployed (immutable reference via hash)
+ * - When the deployment occurred
+ * - Current root data tree hash
+ * - When the root was last updated
+ *
+ * State file location: workspaces/<name>/state.beast2
+ * No state file = workspace exists but not yet deployed.
+ */
+import { StructType, StringType, DateTimeType, ValueTypeOf } from '@elaraai/east';
+/**
+ * Workspace state stored in workspaces/<name>/state.beast2
+ *
+ * Contains both deployment info and current data root in a single
+ * atomic unit to ensure consistency.
+ *
+ * Future audit trail support:
+ * When we implement full audit trail, this state will move to the object
+ * store (content-addressed) with a ref file pointing to current state hash.
+ * Additional fields for the Merkle chain:
+ *
+ *   previousStateHash: NullableType(StringType),  // null for initial deploy
+ *   message: StringType,  // "deployed package X", "user Y wrote to dataset Z"
+ *
+ * This gives a complete history of workspace changes, similar to git commits.
+ */
+export declare const WorkspaceStateType: StructType<{
+    /** Name of the deployed package */
+    packageName: StringType;
+    /** Version of the deployed package */
+    packageVersion: StringType;
+    /** Hash of the package object at deploy time (immutable reference) */
+    packageHash: StringType;
+    /** UTC datetime when the package was deployed */
+    deployedAt: DateTimeType;
+    /** Current root data tree hash */
+    rootHash: StringType;
+    /** UTC datetime when root was last updated */
+    rootUpdatedAt: DateTimeType;
+}>;
+export type WorkspaceState = ValueTypeOf<typeof WorkspaceStateType>;
+//# sourceMappingURL=workspace.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/workspace.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAElF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,kBAAkB;IAC7B,mCAAmC;;IAEnC,sCAAsC;;IAEtC,sEAAsE;;IAEtE,iDAAiD;;IAEjD,kCAAkC;;IAElC,8CAA8C;;EAE9C,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,WAAW,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/dist/src/workspace.js

@@ -0,0 +1,48 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Workspace state type definitions.
+ *
+ * A workspace is a mutable working copy of a package. The state tracks:
+ * - Which package was deployed (immutable reference via hash)
+ * - When the deployment occurred
+ * - Current root data tree hash
+ * - When the root was last updated
+ *
+ * State file location: workspaces/<name>/state.beast2
+ * No state file = workspace exists but not yet deployed.
+ */
+import { StructType, StringType, DateTimeType } from '@elaraai/east';
+/**
+ * Workspace state stored in workspaces/<name>/state.beast2
+ *
+ * Contains both deployment info and current data root in a single
+ * atomic unit to ensure consistency.
+ *
+ * Future audit trail support:
+ * When we implement full audit trail, this state will move to the object
+ * store (content-addressed) with a ref file pointing to current state hash.
+ * Additional fields for the Merkle chain:
+ *
+ *   previousStateHash: NullableType(StringType),  // null for initial deploy
+ *   message: StringType,  // "deployed package X", "user Y wrote to dataset Z"
+ *
+ * This gives a complete history of workspace changes, similar to git commits.
+ */
+export const WorkspaceStateType = StructType({
+    /** Name of the deployed package */
+    packageName: StringType,
+    /** Version of the deployed package */
+    packageVersion: StringType,
+    /** Hash of the package object at deploy time (immutable reference) */
+    packageHash: StringType,
+    /** UTC datetime when the package was deployed */
+    deployedAt: DateTimeType,
+    /** Current root data tree hash */
+    rootHash: StringType,
+    /** UTC datetime when root was last updated */
+    rootUpdatedAt: DateTimeType,
+});
+//# sourceMappingURL=workspace.js.map

package/dist/src/workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../../src/workspace.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,EAAe,MAAM,eAAe,CAAC;AAElF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,UAAU,CAAC;IAC3C,mCAAmC;IACnC,WAAW,EAAE,UAAU;IACvB,sCAAsC;IACtC,cAAc,EAAE,UAAU;IAC1B,sEAAsE;IACtE,WAAW,EAAE,UAAU;IACvB,iDAAiD;IACjD,UAAU,EAAE,YAAY;IACxB,kCAAkC;IAClC,QAAQ,EAAE,UAAU;IACpB,8CAA8C;IAC9C,aAAa,EAAE,YAAY;CAC5B,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@elaraai/e3-types",
+  "version": "0.0.1-beta.0",
+  "description": "Shared type definitions for e3 (East Execution Engine)",
+  "type": "module",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "scripts": {
+    "build": "tsc --build",
+    "clean": "rm -rf dist",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  },
+  "keywords": [
+    "east",
+    "e3",
+    "types"
+  ],
+  "author": "Elara AI",
+  "license": "SEE LICENSE IN LICENSE",
+  "dependencies": {
+    "@elaraai/east": "0.0.1-beta.11"
+  },
+  "devDependencies": {
+    "@typescript-eslint/eslint-plugin": "^8.47.0",
+    "@typescript-eslint/parser": "^8.47.0",
+    "eslint-plugin-headers": "^1.3.3",
+    "typescript": "^5.7.2"
+  }
+}

package/src/dataset.ts

@@ -0,0 +1,126 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+
+/**
+ * Dataset reference and tree types for e3's persistent data structures.
+ *
+ * e3 stores data as persistent trees with structural sharing (like git trees).
+ * Each node is either a leaf (value) or a branch (tree of refs).
+ */
+
+import { VariantType, StringType, NullType, ValueTypeOf, variant, StructType, EastType } from '@elaraai/east';
+
+/**
+ * Reference to data in the object store.
+ *
+ * DataRef is the fundamental building block of e3's data trees.
+ * Each ref points to either a value or another tree node.
+ *
+ * @remarks
+ * - `unassigned`: Placeholder for pending task outputs
+ * - `null`: Inline null value (optimization)
+ * - `value`: Hash of a typed value blob in objects/
+ * - `tree`: Hash of a tree object in objects/
+ *
+ * @example
+ * ```ts
+ * // Pending output
+ * const pending: DataRef = variant('unassigned', null);
+ *
+ * // Value reference
+ * const ref: DataRef = variant('value', 'abc123...');
+ *
+ * // Tree reference
+ * const treeRef: DataRef = variant('tree', 'def456...');
+ * ```
+ */
+export const DataRefType = VariantType({
+  /** Unassigned value (e.g., pending task output) */
+  unassigned: NullType,
+  /** Inline null value (optimization for NullType) */
+  null: NullType,
+  /** Hash of a beast2 value blob in objects/ */
+  value: StringType,
+  /** Hash of a tree object in objects/ */
+  tree: StringType,
+});
+export type DataRefType = typeof DataRefType;
+
+export type DataRef = ValueTypeOf<typeof DataRefType>;
+
+/**
+ * Singleton DataRef representing an unassigned value.
+ *
+ * Used for dataset fields that have not yet been computed (e.g., pending task outputs).
+ *
+ * @example
+ * ```ts
+ * const tree = {
+ *   computed: variant('value', 'abc123...'),
+ *   pending: unassignedRef,
+ * };
+ * ```
+ */
+export const unassignedRef: DataRef = variant('unassigned', null);
+
+/**
+ * Singleton DataRef representing an inline null value.
+ *
+ * Optimization for datasets with NullType fields - avoids storing a separate object.
+ */
+export const nullRef: DataRef = variant('null', null);
+
+/**
+ * Computes the DataTreeType for a given EastType.
+ *
+ * A DataTreeType is a StructType where each field is replaced with a DataRefType,
+ * enabling structural sharing in e3's persistent data trees.
+ *
+ * @typeParam T - The source EastType (must be a StructType for MVP)
+ *
+ * @remarks
+ * Currently only StructType is supported. Future versions may support
+ * ArrayType, DictType, VariantType, and RecursiveType.
+ *
+ * @example
+ * ```ts
+ * const PersonType = StructType({ name: StringType, age: IntegerType });
+ * type PersonTree = DataTreeType<typeof PersonType>;
+ * // Equivalent to: StructType<{ name: DataRefType, age: DataRefType }>
+ * ```
+ */
+export type DataTreeType<T extends EastType> =
+  T extends StructType<infer Fields> ? StructType<{ [K in keyof Fields]: DataRefType }> :
+  never;
+
+/**
+ * Creates a DataTreeType from an EastType at runtime.
+ *
+ * Transforms a StructType into a new StructType where each field
+ * is replaced with DataRefType.
+ *
+ * @param type - The source EastType (must be a StructType)
+ * @returns A new StructType with DataRefType fields
+ *
+ * @throws {Error} When the input type is not a StructType
+ *
+ * @example
+ * ```ts
+ * const PersonType = StructType({ name: StringType, age: IntegerType });
+ * const PersonTreeType = DataTreeType(PersonType);
+ * // PersonTreeType.fields = { name: DataRefType, age: DataRefType }
+ * ```
+ */
+export function DataTreeType<T extends EastType>(type: T): DataTreeType<T> {
+  if (type.type === "Struct") {
+    const fields: Record<string, DataRefType> = {};
+    for (const key of Object.keys(type.fields)) {
+      fields[key] = DataRefType;
+    }
+    return StructType(fields) as DataTreeType<T>;
+  } else {
+    throw new Error(`DataTreeType not implemented for type .${type.type}`);
+  }
+}