@elaraai/e3-types 1.0.83 → 1.0.85

package/dist/src/structure.spec.js

@@ -0,0 +1,57 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Keypaths: `parseKeypath` reads back what `pathToString` writes, whatever a
+ * field is named, with no structure to check it against; `parsePath` reads the
+ * same syntax and checks each field against a structure as it reads it.
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { IntegerType, equalFor, printFor, toEastTypeValue, variant } from '@elaraai/east';
+import { TreePathType, parseKeypath, parsePath, pathToString } from './structure.js';
+const equalPath = equalFor(TreePathType);
+const printPath = printFor(TreePathType);
+describe('parseKeypath', () => {
+    it('reads back what pathToString writes, whatever a field is named', () => {
+        const names = ['inputs', 'my field', 'a.b', 'a/b', 'back`tick', 'back\\slash', 'café', '1st', '', '`'];
+        for (const name of names) {
+            const path = [variant('field', 'inputs'), variant('field', name)];
+            const printed = pathToString(path);
+            if (name === '') {
+                // An empty field name prints as nothing a keypath can read.
+                assert.throws(() => parseKeypath(printed));
+                continue;
+            }
+            const read = parseKeypath(printed);
+            assert.ok(equalPath(read, path), `${JSON.stringify(name)}: ${printed} read back as ${printPath(read)}`);
+        }
+    });
+    it('reads the empty string as the root', () => {
+        assert.ok(equalPath(parseKeypath(''), []));
+    });
+    it('refuses a string that is not a keypath, naming where', () => {
+        assert.throws(() => parseKeypath('inputs.x'), { message: "parseKeypath: unexpected character at position 0: 'i'" });
+        assert.throws(() => parseKeypath('.inputs.'), { message: "parseKeypath: expected identifier after '.' at position 8" });
+        assert.throws(() => parseKeypath('.inputs!'), { message: "parseKeypath: unexpected character at position 7: '!'" });
+    });
+});
+describe('parsePath', () => {
+    const structure = variant('struct', new Map([
+        ['inputs', variant('struct', new Map([
+                ['sales', variant('value', { type: toEastTypeValue(IntegerType), writable: true })],
+            ]))],
+    ]));
+    it('reads a keypath, and the structure at it', () => {
+        const { path, structure: at } = parsePath('.inputs.sales', structure);
+        assert.ok(equalPath(path, [variant('field', 'inputs'), variant('field', 'sales')]));
+        assert.equal(at.type, 'value');
+    });
+    it('refuses a field the structure lacks before a malformed one after it, and a path into a dataset', () => {
+        assert.throws(() => parsePath('.nope!', structure), { message: "parsePath: field 'nope' not found at ''. Available: inputs" });
+        assert.throws(() => parsePath('.inputs!', structure), { message: "parsePath: unexpected character at position 7: '!'" });
+        assert.throws(() => parsePath('.inputs.sales.more', structure), { message: "parsePath: cannot descend into dataset at '.inputs.sales'" });
+    });
+});
+//# sourceMappingURL=structure.spec.js.map

package/dist/src/structure.spec.js.map

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

package/dist/src/task.d.ts

@@ -160,7 +160,7 @@ export type TaskRole = ValueTypeOf<typeof TaskRoleType>;
  * const task: TaskObject = {
  *   kind: TASK_OBJECT_KIND,
  *   body: variant('east', { program: '5e7a3b...' }),
- *   runner: variant('east_node', { platforms: ['@elaraai/east-node-std'] }),
+ *   runner: variant('east_node', { platforms: ['@elaraai/east-node-std'], decode: variant('lazy', null) }),
  *   inputs: [{ path: [variant('field', 'inputs'), variant('field', 'sales')], partition: none }],
  *   output: { path: [variant('field', 'tasks'), variant('field', 'totals'), variant('field', 'output')], kind: variant('value', null) },
  *   role: variant('data', null),
@@ -185,12 +185,24 @@ export declare const TaskObjectType: StructType<{
     readonly runner: VariantType<{
         readonly east_node: StructType<{
             readonly platforms: ArrayType<StringType>;
+            readonly decode: VariantType<{
+                readonly lazy: NullType;
+                readonly whole: NullType;
+            }>;
         }>;
         readonly east_py: StructType<{
             readonly platforms: ArrayType<StringType>;
+            readonly decode: VariantType<{
+                readonly lazy: NullType;
+                readonly whole: NullType;
+            }>;
         }>;
         readonly east_c: StructType<{
             readonly platforms: ArrayType<StringType>;
+            readonly decode: VariantType<{
+                readonly lazy: NullType;
+                readonly whole: NullType;
+            }>;
         }>;
         readonly custom: StructType<{
             readonly command: ArrayType<StringType>;

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

@@ -1 +1 @@
-{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../src/task.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAmB,MAAM,eAAe,CAAC;AAInI;qBACqB;AACrB,eAAO,MAAM,gBAAgB,UAAU,CAAC;AAExC;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY;;;;;;;EAGvB,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC;AAC/C,MAAM,MAAM,QAAQ,GAAG,WAAW,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;;EAA4C,CAAC;AAC3E,MAAM,MAAM,iBAAiB,GAAG,OAAO,iBAAiB,CAAC;AACzD,MAAM,MAAM,aAAa,GAAG,WAAW,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE,yEAAyE;AACzE,eAAO,MAAM,aAAa;;;;;;;EAGxB,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC;AACjD,MAAM,MAAM,SAAS,GAAG,WAAW,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;EAM7B,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,kBAAkB,CAAC;AAC3D,MAAM,MAAM,cAAc,GAAG,WAAW,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEpE,sDAAsD;AACtD,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;EAGzB,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC;AACnD,MAAM,MAAM,UAAU,GAAG,WAAW,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;EAK3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,gBAAgB,CAAC;AACvD,MAAM,MAAM,YAAY,GAAG,WAAW,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;GAGG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;EAGvB,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC;AAC/C,MAAM,MAAM,QAAQ,GAAG,WAAW,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,cAAc;IACzB,uCAAuC;;IAEvC,0BAA0B;;;;;;;;;IAE1B;gDAC4C;;;;;;;;;;;;;;;IAE5C,kEAAkE;;;;;;;;;IAElE,iDAAiD;;;;;;;;;;;;;;;;;;IAEjD,8BAA8B;;;;;;;;;;;;;;IAE9B;uCACmC;;EAEnC,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC;AAEnD,MAAM,MAAM,UAAU,GAAG,WAAW,CAAC,OAAO,cAAc,CAAC,CAAC;AAI5D;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAc7D"}
+{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../src/task.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAmB,MAAM,eAAe,CAAC;AAInI;qBACqB;AACrB,eAAO,MAAM,gBAAgB,UAAU,CAAC;AAExC;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY;;;;;;;EAGvB,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC;AAC/C,MAAM,MAAM,QAAQ,GAAG,WAAW,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;;EAA4C,CAAC;AAC3E,MAAM,MAAM,iBAAiB,GAAG,OAAO,iBAAiB,CAAC;AACzD,MAAM,MAAM,aAAa,GAAG,WAAW,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE,yEAAyE;AACzE,eAAO,MAAM,aAAa;;;;;;;EAGxB,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC;AACjD,MAAM,MAAM,SAAS,GAAG,WAAW,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;EAM7B,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,kBAAkB,CAAC;AAC3D,MAAM,MAAM,cAAc,GAAG,WAAW,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEpE,sDAAsD;AACtD,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;EAGzB,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC;AACnD,MAAM,MAAM,UAAU,GAAG,WAAW,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;EAK3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,gBAAgB,CAAC;AACvD,MAAM,MAAM,YAAY,GAAG,WAAW,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;GAGG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;EAGvB,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC;AAC/C,MAAM,MAAM,QAAQ,GAAG,WAAW,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,cAAc;IACzB,uCAAuC;;IAEvC,0BAA0B;;;;;;;;;IAE1B;gDAC4C;;;;;;;;;;;;;;;;;;;;;;;;;;;IAE5C,kEAAkE;;;;;;;;;IAElE,iDAAiD;;;;;;;;;;;;;;;;;;IAEjD,8BAA8B;;;;;;;;;;;;;;IAE9B;uCACmC;;EAEnC,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC;AAEnD,MAAM,MAAM,UAAU,GAAG,WAAW,CAAC,OAAO,cAAc,CAAC,CAAC;AAI5D;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAc7D"}

package/dist/src/task.js

@@ -107,7 +107,7 @@ export const TaskRoleType = VariantType({
  * const task: TaskObject = {
  *   kind: TASK_OBJECT_KIND,
  *   body: variant('east', { program: '5e7a3b...' }),
- *   runner: variant('east_node', { platforms: ['@elaraai/east-node-std'] }),
+ *   runner: variant('east_node', { platforms: ['@elaraai/east-node-std'], decode: variant('lazy', null) }),
  *   inputs: [{ path: [variant('field', 'inputs'), variant('field', 'sales')], partition: none }],
  *   output: { path: [variant('field', 'tasks'), variant('field', 'totals'), variant('field', 'output')], kind: variant('value', null) },
  *   role: variant('data', null),

package/dist/src/task.spec.js

@@ -7,8 +7,8 @@
  */
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
-import { ArrayType, BlobType, IntegerType, OptionType, StringType, StructType, encodeBeast2For, none, some, variant } from '@elaraai/east';
-import { TASK_OBJECT_KIND, TaskObjectType, decodeTaskObject, } from './task.js';
+import { ArrayType, BlobType, IntegerType, OptionType, StringType, StructType, VariantType, encodeBeast2For, none, some, variant } from '@elaraai/east';
+import { TASK_OBJECT_KIND, TaskBodyType, TaskInputType, TaskObjectType, TaskOutputType, TaskRoleType, decodeTaskObject, } from './task.js';
 import { RunnerType } from './runner.js';
 import { TreePathType } from './structure.js';
 describe('TaskObjectType', () => {
@@ -18,7 +18,7 @@ describe('TaskObjectType', () => {
     const base = {
         kind: TASK_OBJECT_KIND,
         body: variant('east', { program: 'a'.repeat(64) }),
-        runner: variant('east_node', { platforms: ['@elaraai/east-node-std'] }),
+        runner: variant('east_node', { platforms: ['@elaraai/east-node-std'], decode: variant('lazy', null) }),
         inputs: [{ path: sales, partition: none }],
         output: { path: totals, kind: variant('value', null) },
         role: variant('data', null),
@@ -40,6 +40,7 @@ describe('TaskObjectType', () => {
             },
             { ...base, output: { path: totals, kind: variant('fold', { zero: 'e'.repeat(64), combine: 'f'.repeat(64) }) } },
             { ...base, output: { path: totals, kind: variant('set', null) } },
+            { ...base, runner: variant('east_py', { platforms: ['east-py-std'], decode: variant('whole', null) }) },
             { ...base, role: variant('ui', { paths: [sales], functions: ['forecast'], records: ['plans'], pages: [rates] }) },
         ];
         const encode = encodeBeast2For(TaskObjectType);
@@ -62,11 +63,31 @@ describe('TaskObjectType', () => {
             output: totals,
             kind: none,
             metadata: none,
-            runner: variant('east_node', { platforms: [] }),
+            runner: variant('east_node', { platforms: [], decode: variant('lazy', null) }),
             environment: none,
         });
         assert.throws(() => decodeTaskObject(older), /exported by an older e3 SDK — re-export it with the current one/);
     });
+    it('refuses a task object whose runner predates its decode, saying to re-export the package', () => {
+        // A stock runner as a package exported before runners said how they read
+        // a program's inputs: its platforms alone.
+        const PreDecodeRunnerType = VariantType({
+            east_node: StructType({ platforms: ArrayType(StringType) }),
+            east_py: StructType({ platforms: ArrayType(StringType) }),
+            east_c: StructType({ platforms: ArrayType(StringType) }),
+            custom: StructType({ command: ArrayType(StringType) }),
+        });
+        const older = encodeBeast2For(StructType({
+            kind: StringType,
+            body: TaskBodyType,
+            runner: PreDecodeRunnerType,
+            inputs: ArrayType(TaskInputType),
+            output: TaskOutputType,
+            role: TaskRoleType,
+            environment: OptionType(StringType),
+        }))({ ...base, runner: variant('east_node', { platforms: ['@elaraai/east-node-std'] }) });
+        assert.throws(() => decodeTaskObject(older), /exported by an older e3 SDK — re-export it with the current one/);
+    });
     it('refuses an object of the task shape that carries another kind tag', () => {
         assert.throws(() => decodeTaskObject(encodeBeast2For(TaskObjectType)({ ...base, kind: '$plan' })), /its kind is '\$plan', not '\$task'/);
     });

package/dist/src/task.spec.js.map

@@ -1 +1 @@
-{"version":3,"file":"task.spec.js","sourceRoot":"","sources":["../../src/task.spec.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"task.spec.js","sourceRoot":"","sources":["../../src/task.spec.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,MAAM,MAAM,oBAAoB,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,eAAe,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxJ,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,cAAc,EACd,cAAc,EACd,YAAY,EACZ,gBAAgB,GAEjB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,QAAQ,CAAC,gBAAgB,EAAE,GAAG,EAAE;IAC9B,MAAM,KAAK,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;IACtE,MAAM,KAAK,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;IACtE,MAAM,MAAM,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;IACnG,MAAM,IAAI,GAAe;QACvB,IAAI,EAAE,gBAAgB;QACtB,IAAI,EAAE,OAAO,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;QAClD,MAAM,EAAE,OAAO,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,CAAC,wBAAwB,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC;QACtG,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;QAC1C,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE;QACtD,IAAI,EAAE,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC;QAC3B,WAAW,EAAE,IAAI;KAClB,CAAC;IAEF,EAAE,CAAC,8CAA8C,EAAE,GAAG,EAAE;QACtD,MAAM,KAAK,GAAiB;YAC1B,IAAI;YACJ;gBACE,GAAG,IAAI;gBACP,IAAI,EAAE,OAAO,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;gBACvD,MAAM,EAAE,OAAO,CAAC,QAAQ,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;gBAC1C,WAAW,EAAE,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;aAClC;YACD;gBACE,GAAG,IAAI;gBACP,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;gBAC3G,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE;aACjF;YACD,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE;YAC/G,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,EAAE;YACjE,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,CAAC,EAAE;YACvG,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE;SAClH,CAAC;QACF,MAAM,MAAM,GAAG,eAAe,CAAC,cAAc,CAAC,CAAC;QAC/C,KAAK,MAAM,QAAQ,IAAI,KAAK;YAAE,MAAM,CAAC,SAAS,CAAC,gBAAgB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;IAC/F,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,8EAA8E,EAAE,GAAG,EAAE;QACtF,MAAM,wBAAwB,GAAG,UAAU,CAAC;YAC1C,SAAS,EAAE,UAAU;YACrB,MAAM,EAAE,SAAS,CAAC,YAAY,CAAC;YAC/B,MAAM,EAAE,YAAY;YACpB,IAAI,EAAE,UAAU,CAAC,UAAU,CAAC;YAC5B,QAAQ,EAAE,UAAU,CAAC,QAAQ,CAAC;YAC9B,MAAM,EAAE,UAAU;YAClB,WAAW,EAAE,UAAU,CAAC,UAAU,CAAC;SACpC,CAAC,CAAC;QACH,MAAM,KAAK,GAAG,eAAe,CAAC,wBAAwB,CAAC,CAAC;YACtD,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YACzB,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,OAAO,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC,EAAE,KAAK,CAAC;YACzG,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,IAAI;YACV,QAAQ,EAAE,IAAI;YACd,MAAM,EAAE,OAAO,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC;YAC9E,WAAW,EAAE,IAAI;SAClB,CAAC,CAAC;QACH,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,iEAAiE,CAAC,CAAC;IAClH,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yFAAyF,EAAE,GAAG,EAAE;QACjG,yEAAyE;QACzE,2CAA2C;QAC3C,MAAM,mBAAmB,GAAG,WAAW,CAAC;YACtC,SAAS,EAAE,UAAU,CAAC,EAAE,SAAS,EAAE,SAAS,CAAC,UAAU,CAAC,EAAE,CAAC;YAC3D,OAAO,EAAE,UAAU,CAAC,EAAE,SAAS,EAAE,SAAS,CAAC,UAAU,CAAC,EAAE,CAAC;YACzD,MAAM,EAAE,UAAU,CAAC,EAAE,SAAS,EAAE,SAAS,CAAC,UAAU,CAAC,EAAE,CAAC;YACxD,MAAM,EAAE,UAAU,CAAC,EAAE,OAAO,EAAE,SAAS,CAAC,UAAU,CAAC,EAAE,CAAC;SACvD,CAAC,CAAC;QACH,MAAM,KAAK,GAAG,eAAe,CAAC,UAAU,CAAC;YACvC,IAAI,EAAE,UAAU;YAChB,IAAI,EAAE,YAAY;YAClB,MAAM,EAAE,mBAAmB;YAC3B,MAAM,EAAE,SAAS,CAAC,aAAa,CAAC;YAChC,MAAM,EAAE,cAAc;YACtB,IAAI,EAAE,YAAY;YAClB,WAAW,EAAE,UAAU,CAAC,UAAU,CAAC;SACpC,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,CAAC,wBAAwB,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QAC1F,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,iEAAiE,CAAC,CAAC;IAClH,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,mEAAmE,EAAE,GAAG,EAAE;QAC3E,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,gBAAgB,CAAC,eAAe,CAAC,cAAc,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,oCAAoC,CAAC,CAAC;IAC3I,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yCAAyC,EAAE,GAAG,EAAE;QACjD,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,gBAAgB,CAAC,eAAe,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC;IACvF,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elaraai/e3-types",
-  "version": "1.0.83",
+  "version": "1.0.85",
   "description": "Shared type definitions for e3 (East Execution Engine)",
   "type": "module",
   "main": "dist/src/index.js",
@@ -18,12 +18,13 @@
     "directory": "libs/e3/packages/e3-types"
   },
   "peerDependencies": {
-    "@elaraai/east": "1.0.83"
+    "@elaraai/east": "1.0.85"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "@typescript-eslint/eslint-plugin": "^8.47.0",
     "@typescript-eslint/parser": "^8.47.0",
+    "eslint": "^9.0.0",
     "eslint-plugin-headers": "^1.3.3",
     "typescript": "^5.7.2"
   },

package/src/api.ts

@@ -36,10 +36,11 @@ import {
 } from '@elaraai/east';
 
 import { StructureType, TreePathType } from './structure.js';
+import { StopReasonType } from './execution.js';
 import { IntakeFileType } from './intake.js';
 import { RunnerType } from './runner.js';
 import { TaskBodyType, TaskInputType, TaskOutputType, TaskPartitionType, TaskRoleType } from './task.js';
-import { RequeueReasonType, StageUnitType } from './dataflow.js';
+import { DataflowForceType, RequeueReasonType, StageUnitType } from './dataflow.js';
 
 // =============================================================================
 // Error Types
@@ -565,6 +566,9 @@ export const DatasetStatusInfoType = StructType({
  * @property peakBytes - The highest peak resident memory, in bytes, a runner
  *   of the execution the status comes from reached: the one the output came
  *   from, or the failure; `none` when it recorded none, or while it runs
+ * @property stopped - Why the latest attempt over the task's current inputs
+ *   stopped, when it was cancelled or interrupted and the task therefore reads
+ *   `ready`; `none` otherwise
  */
 export const TaskStatusInfoType = StructType({
   name: StringType,
@@ -574,6 +578,7 @@ export const TaskStatusInfoType = StructType({
   output: StringType,
   dependsOn: ArrayType(StringType),
   peakBytes: OptionType(IntegerType),
+  stopped: OptionType(StopReasonType),
 });
 
 /**
@@ -664,11 +669,15 @@ export const TaskDetailsType = StructType({
  * Request to start dataflow execution. The run takes the server's budget of
  * cores and memory, which it shares with everything else the server runs.
  *
- * @property force - Force re-execution of all tasks
- * @property filter - Filter to specific task names (glob pattern)
+ * @property force - The tasks the run re-executes even where the cache holds
+ *   their results: none, all, or the tasks named ({@link DataflowForceType}).
+ *   A start naming a task the graph does not have, or one the filter's run set
+ *   leaves out, is refused before anything runs.
+ * @property filter - One task's exact name: the run runs that task and its
+ *   dependency closure, and no other task
  */
 export const DataflowRequestType = StructType({
-  force: BooleanType,
+  force: DataflowForceType,
   filter: OptionType(StringType),
 });
 
@@ -689,6 +698,29 @@ export const LogChunkType = StructType({
   complete: BooleanType,
 });
 
+/**
+ * Chunk of a task's log, as the logs route serves it: a {@link LogChunkType}'s
+ * fields, and the execution it was read from. A client polling the log reads
+ * on from its offset, starts over when the execution changes, and stops
+ * reading once the execution has ended and its log is read.
+ *
+ * @property inputsHash - The execution's inputs hash, which a request names,
+ *   with its id, to read on from the same execution
+ * @property executionId - The execution's id
+ * @property ended - True once the execution is recorded as anything but
+ *   running: its log grows no more
+ */
+export const TaskLogChunkType = StructType({
+  data: StringType,
+  offset: IntegerType,
+  size: IntegerType,
+  totalSize: IntegerType,
+  complete: BooleanType,
+  inputsHash: StringType,
+  executionId: StringType,
+  ended: BooleanType,
+});
+
 /**
  * Result of executing a single task.
  *
@@ -876,12 +908,32 @@ export const SplitProgressType = StructType({
  * DataflowExecutionStateType in dataflow.ts which stores the full
  * execution state on disk.
  *
+ * A poll names a cursor (`since`), the sequence number of the last event it
+ * has, and is served the run's events past it, at most its `limit`, and never
+ * more than {@link DATAFLOW_POLL_EVENTS_MAX}; the response's `nextSeq` is the
+ * cursor of the poll after it. A poll that has every event reads no event of
+ * the run, so a client polls on a timer for the whole run at the cost of what
+ * is new.
+ *
+ * The response names the run (`runId`) and where its events end (`lastSeq`).
+ * A cursor counts a run's own events, so a client that sees another run starts
+ * from 0. A poll whose `nextSeq` is before `lastSeq` left events for the next,
+ * which a client reads before it takes a run's end as its last word; and a
+ * client opens a running run's feed near its tail from `lastSeq`, or follows
+ * its progress with polls that ask for no events (`limit` 0).
+ *
+ * @property runId - The run's id, a UUIDv7
  * @property status - Current execution status
  * @property startedAt - ISO timestamp when execution started
  * @property completedAt - ISO timestamp when execution finished (if done)
  * @property summary - Execution summary (available when complete)
- * @property events - Task events (may be paginated via offset/limit)
- * @property totalEvents - Total number of events (for pagination)
+ * @property events - The run's task events past the poll's cursor, at most
+ *   its limit, in the order they happened
+ * @property nextSeq - The cursor past the events served, which the next poll
+ *   passes as `since`: the poll's own when it served none
+ * @property lastSeq - The sequence number of the run's last event when the
+ *   poll read it, 0 while it has none: the cursor of a poll that has every
+ *   event
  * @property budget - The server's budget now, where it has one: a server whose
  *   runners hold none, as a remote backend's, serves `none`
  * @property waiting - The tasks and units of the run waiting for room, while it
@@ -890,25 +942,36 @@ export const SplitProgressType = StructType({
  *   stores it
  */
 export const ApiDataflowExecutionStateType = StructType({
+  runId: StringType,
   status: ApiExecutionStatusType,
   startedAt: StringType,
   completedAt: OptionType(StringType),
   summary: OptionType(DataflowExecutionSummaryType),
   events: ArrayType(DataflowEventType),
-  totalEvents: IntegerType,
+  nextSeq: IntegerType,
+  lastSeq: IntegerType,
   budget: OptionType(DataflowBudgetType),
   waiting: ArrayType(UnitWaitType),
   splits: ArrayType(SplitProgressType),
 });
 
+/**
+ * The most events a poll of a run is served ({@link ApiDataflowExecutionStateType}):
+ * a poll that names no `limit`, or a larger one, is served this many, so an
+ * answer stays within what a host's response may hold however long the run. A
+ * client reads on from the answer's `nextSeq`.
+ */
+export const DATAFLOW_POLL_EVENTS_MAX = 1_000;
+
 // =============================================================================
 // Task Execution History Types
 // =============================================================================
 
 /**
  * Execution status for history listing: `cancelled` when e3 stopped the
- * execution because its run was aborted, `interrupted` when the orchestrator
- * that owned it exited before it finished.
+ * execution because the signal it ran under was aborted, `interrupted` when
+ * it can no longer finish — its runner and its owner are gone, its host says
+ * so, or its run yielded mid-stage. Each says why in its item's `reason`.
  */
 export const ExecutionHistoryStatusType = VariantType({
   running: NullType,
@@ -920,9 +983,12 @@ export const ExecutionHistoryStatusType = VariantType({
 });
 
 /**
- * A single execution in task history.
+ * A single execution in task history: a run of the task, never a split task's
+ * unit. The history lists them the latest first, a page at a time.
  *
  * @property inputsHash - Hash of concatenated inputs (execution identifier)
+ * @property executionId - The run's id, a UUIDv7: the next page is the runs
+ *   before the last one's
  * @property inputHashes - Individual input object hashes
  * @property status - Execution outcome
  * @property startedAt - ISO timestamp when execution started
@@ -931,9 +997,11 @@ export const ExecutionHistoryStatusType = VariantType({
  * @property exitCode - Process exit code (if failed)
  * @property peakBytes - The highest peak resident memory, in bytes, a runner
  *   of the execution reached, when it succeeded or failed and one reported it
+ * @property reason - Why it stopped, when it was cancelled or interrupted
  */
 export const ExecutionListItemType = StructType({
   inputsHash: StringType,
+  executionId: StringType,
   inputHashes: ArrayType(StringType),
   status: ExecutionHistoryStatusType,
   startedAt: StringType,
@@ -941,8 +1009,23 @@ export const ExecutionListItemType = StructType({
   duration: OptionType(IntegerType),
   exitCode: OptionType(IntegerType),
   peakBytes: OptionType(IntegerType),
+  reason: OptionType(StopReasonType),
 });
 
+/**
+ * The runs a page of a task's history holds when its request names no
+ * `limit`.
+ */
+export const TASK_EXECUTIONS_PAGE_DEFAULT = 100;
+
+/**
+ * The most runs a page of a task's history holds ({@link ExecutionListItemType}):
+ * a request naming a larger `limit` is served this many, so a page stays
+ * within what a host's response may hold. A client reads on with the last
+ * run's id as `before`.
+ */
+export const TASK_EXECUTIONS_PAGE_MAX = 1_000;
+
 // =============================================================================
 // Dataset List Types (recursive)
 // =============================================================================
@@ -1043,8 +1126,8 @@ export const DiagnosticType = StructType({
  *
  * `inputs` names what the call read: each dataset argument's path and the hash
  * it was pinned at, in argument order, so an answer can be reproduced and a
- * stale one noticed. It is empty for a named function call, for a one-shot
- * with value arguments only, and for an `invalid` result.
+ * stale one noticed. It is empty for a call with value arguments only, and for
+ * an `invalid` result.
  */
 export const ExecuteResultType = StructType({
   outcome: VariantType({
@@ -1061,9 +1144,24 @@ export const ExecuteResultType = StructType({
   inputs: ArrayType(StructType({ path: TreePathType, hash: StringType })),
 });
 
-/** Named function call. Positional args, one beast2-encoded value per param. */
+/**
+ * A call's argument: a beast2-encoded value, or a dataset of the workspace the
+ * call runs in, resolved and pinned by its content hash at launch and named in
+ * the result's `inputs`. A named function call and a one-shot take it alike.
+ */
+export const CallArgType = VariantType({
+  value:   BlobType,
+  dataset: TreePathType,
+});
+
+/**
+ * Named function call. Positional args, one per param: a value, or a dataset
+ * of the workspace ({@link CallArgType}). The package-scoped route has no
+ * workspace to read a dataset from, and answers a dataset argument `invalid`;
+ * the workspace-scoped route pins it, as a one-shot's is.
+ */
 export const FunctionCallRequestType = StructType({
-  args:   ArrayType(BlobType),
+  args:   ArrayType(CallArgType),
   runner: OptionType(RunnerType),       // optional override; only the known runtimes
   limits: OptionType(ExecuteLimitsType),
 });
@@ -1089,10 +1187,7 @@ export const FunctionSignatureType = StructType({
  */
 export const OneShotRequestType = StructType({
   bodyIr: BlobType,                       // anonymous EastIR, not deployed
-  args:   ArrayType(VariantType({         // each arg: an inline value OR a live dataset
-    value:   BlobType,
-    dataset: TreePathType,                // workspace-scoped; resolved + pinned by content hash at launch
-  })),
+  args:   ArrayType(CallArgType),         // each arg: an inline value OR a live dataset, pinned at launch
   runner: RunnerType,
   limits: OptionType(ExecuteLimitsType),
 });
@@ -1219,10 +1314,26 @@ export const MutationResultType = StructType({
   }),
 });
 
+/**
+ * When a record applied one step of its migration chain.
+ *
+ * @property at - When the step was applied: the time of the deploy that
+ *   applied it; `none` for a step a record applied before e3 kept the time
+ * @property commit - The commit that applied it: its `$migrate:<name>` commit,
+ *   or the `$init` or `$reset` commit that counted the chain applied; `none`
+ *   once a compaction has cut it from the chain, or for a step a record applied
+ *   before e3 kept it
+ */
+export const RecordMigrationAppliedType = StructType({
+  at:     OptionType(DateTimeType),
+  commit: OptionType(StringType),
+});
+
 /**
  * A record's callable surface, returned by `describe` so dynamic callers can
- * encode mutation arguments and read through its indexes. The mutation
- * `argTypes` are the EXTRA parameters after the implicit current state.
+ * encode mutation arguments and read through its indexes, and a console can
+ * show the record whole without reading its history. The mutation `argTypes`
+ * are the EXTRA parameters after the implicit current state.
  */
 export const RecordSignatureType = StructType({
   name: StringType,
@@ -1246,6 +1357,26 @@ export const RecordSignatureType = StructType({
     valueType: EastTypeType,
     /** Whether a row may hold several index keys. */
     multi:     BooleanType,
+    /** Whether the record's head state holds the index, built under the
+     *  declaration the deployed package carries. A deploy, a reindex and a
+     *  system commit build what the state lacks; a read through an index the
+     *  state holds no build of answers `index_not_found`. */
+    built:     BooleanType,
+  })),
+  /** The migration chain the record declares, in order. A deployed record
+   *  has applied every step, since a deploy migrates it or is refused. */
+  migrations: ArrayType(StructType({
+    name:    StringType,
+    /** The step's form — `value`, `rows` or `rekey` — which says what it
+     *  runs over: the whole state, its rows, or its rows under new keys. */
+    form:    StringType,
+    /** The record's type before the step. */
+    from:    EastTypeType,
+    /** The record's type after it. */
+    to:      EastTypeType,
+    /** When the record applied the step, and the commit that did; `none`
+     *  when it has not applied it. */
+    applied: OptionType(RecordMigrationAppliedType),
   })),
 });
 
@@ -1262,11 +1393,78 @@ export const RecordCommitInfoType = StructType({
   delta:    OptionType(StringType),
 });
 
+/**
+ * One argument of a record's commit, as the history previews it.
+ *
+ * @property type - The argument's own East type, as its encoding carries it
+ * @property bytes - Its encoded size
+ * @property text - Its value printed as East text, cut at
+ *   {@link RECORD_ARG_TEXT_CHARS} characters; empty for an argument over
+ *   {@link RECORD_ARG_TEXT_BYTES}, which is not printed, and for one that
+ *   cannot be
+ * @property truncated - Whether `text` holds less than the whole value
+ */
+export const RecordArgPreviewType = StructType({
+  type:      EastTypeType,
+  bytes:     IntegerType,
+  text:      StringType,
+  truncated: BooleanType,
+});
+
+/**
+ * A record commit's arguments, as the history previews them.
+ *
+ * @property hash - The arguments' object, which the objects route serves
+ *   whole: a beast2 `Array<Blob>` of the encoded arguments, in order
+ * @property bytes - The object's size
+ * @property values - Each argument's preview, in order; empty when the object
+ *   is over {@link RECORD_ARGS_READ_BYTES}, which the history does not read,
+ *   or holds arguments that are not East values, as a system commit may
+ *   record its caller's
+ */
+export const RecordCommitArgsType = StructType({
+  hash:   StringType,
+  bytes:  IntegerType,
+  values: ArrayType(RecordArgPreviewType),
+});
+
+/**
+ * One commit in a record's history, as the history route answers it: a
+ * {@link RecordCommitInfoType}'s fields, and a preview of its arguments, so a
+ * history says what a commit set as well as which mutation ran.
+ * `RecordCommitInfoType` stays without them: e3-ui's record binding and the
+ * pages built on it carry it in their East types.
+ */
+export const RecordHistoryCommitType = StructType({
+  hash:     StringType,
+  parent:   OptionType(StringType),
+  state:    StringType,
+  mutation: StringType,
+  actor:    StringType,
+  at:       DateTimeType,
+  /** The delta this commit applied, when it wrote one. */
+  delta:    OptionType(StringType),
+  /** The commit's arguments, previewed; `none` for a commit with none. */
+  args:     OptionType(RecordCommitArgsType),
+});
+
 /** A page of a record's commit history, newest first. */
 export const RecordHistoryResultType = StructType({
-  commits: ArrayType(RecordCommitInfoType),
+  commits: ArrayType(RecordHistoryCommitType),
 });
 
+/** The characters of an argument's East text a history preview keeps. */
+export const RECORD_ARG_TEXT_CHARS = 256;
+
+/** The encoded size, in bytes, past which a history preview prints no text
+ *  of an argument, only its type and size. */
+export const RECORD_ARG_TEXT_BYTES = 64 * 1024;
+
+/** The size, in bytes, past which a history reads no commit's arguments'
+ *  object, and previews none of them: a page reads at most this much of
+ *  arguments per commit, however large a patch is. */
+export const RECORD_ARGS_READ_BYTES = 1024 * 1024;
+
 // =============================================================================
 // Value type aliases
 // =============================================================================
@@ -1304,6 +1502,7 @@ export type TaskListItem = ValueTypeOf<typeof TaskListItemType>;
 export type TaskDetails = ValueTypeOf<typeof TaskDetailsType>;
 export type DataflowRequest = ValueTypeOf<typeof DataflowRequestType>;
 export type LogChunk = ValueTypeOf<typeof LogChunkType>;
+export type TaskLogChunk = ValueTypeOf<typeof TaskLogChunkType>;
 export type TaskExecutionResult = ValueTypeOf<typeof TaskExecutionResultType>;
 export type DataflowResult = ValueTypeOf<typeof DataflowResultType>;
 export type DataflowEvent = ValueTypeOf<typeof DataflowEventType>;
@@ -1321,6 +1520,7 @@ export type DatasetStatusDetail = ValueTypeOf<typeof DatasetStatusDetailType>;
 export type ExecuteLimits = ValueTypeOf<typeof ExecuteLimitsType>;
 export type Diagnostic = ValueTypeOf<typeof DiagnosticType>;
 export type ExecuteResult = ValueTypeOf<typeof ExecuteResultType>;
+export type CallArg = ValueTypeOf<typeof CallArgType>;
 export type FunctionCallRequest = ValueTypeOf<typeof FunctionCallRequestType>;
 export type FunctionSignature = ValueTypeOf<typeof FunctionSignatureType>;
 export type OneShotRequest = ValueTypeOf<typeof OneShotRequestType>;
@@ -1331,6 +1531,10 @@ export type SplitCallStatus = ValueTypeOf<typeof SplitCallStatusType>;
 export type SplitCallPlan = ValueTypeOf<typeof SplitCallPlanType>;
 export type MutationCallRequest = ValueTypeOf<typeof MutationCallRequestType>;
 export type MutationResult = ValueTypeOf<typeof MutationResultType>;
+export type RecordMigrationApplied = ValueTypeOf<typeof RecordMigrationAppliedType>;
 export type RecordSignature = ValueTypeOf<typeof RecordSignatureType>;
 export type RecordCommitInfo = ValueTypeOf<typeof RecordCommitInfoType>;
+export type RecordArgPreview = ValueTypeOf<typeof RecordArgPreviewType>;
+export type RecordCommitArgs = ValueTypeOf<typeof RecordCommitArgsType>;
+export type RecordHistoryCommit = ValueTypeOf<typeof RecordHistoryCommitType>;
 export type RecordHistoryResult = ValueTypeOf<typeof RecordHistoryResultType>;