@elaraai/e3-types 1.0.82 → 1.0.84

package/src/record.ts

@@ -200,6 +200,34 @@ export const RecordIndexObjectType = StructType({
 export type RecordIndexObjectType = typeof RecordIndexObjectType;
 export type RecordIndexObject = ValueTypeOf<typeof RecordIndexObjectType>;
 
+const decodeCurrentRecordIndex = decodeBeast2For(RecordIndexObjectType);
+
+/**
+ * Decode a `RecordIndexObject`.
+ *
+ * @remarks
+ * A package-borne wire, so it changes by hard cutover: a package exported by
+ * an older SDK is re-exported with the current one, and this says so. A
+ * record's state names the index object each index was built under, so one an
+ * older SDK exported is read until a deploy of the re-exported package
+ * rebuilds the index under the current one.
+ *
+ * @param data - the stored bytes
+ * @returns the index object
+ * @throws {Error} When the bytes are not a current index object — a package
+ *   exported by an older SDK, which is re-exported with the current one.
+ */
+export function decodeRecordIndexObject(data: Uint8Array): RecordIndexObject {
+  try {
+    return decodeCurrentRecordIndex(data);
+  } catch (err) {
+    throw new Error(
+      `the index object does not decode: the package was exported by an older e3 SDK — re-export it with the current one ` +
+      `(${err instanceof Error ? err.message : String(err)})`,
+    );
+  }
+}
+
 /**
  * How a migration says what it changes.
  *

package/src/release.ts

@@ -17,7 +17,7 @@
  */
 
 /** The release of e3 this build is. */
-export const E3_RELEASE = '1.0.82';
+export const E3_RELEASE = '1.0.84';
 
 /** A semantic version: its core, a pre-release, and build metadata. */
 const RELEASE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;

package/src/runner.spec.ts

@@ -18,9 +18,9 @@ import { variant } from '@elaraai/east';
 import { withRunnerLifeline, type RunnerValue } from './runner.js';
 
 const KNOWN: Array<[string, RunnerValue, string]> = [
-  ['east_node', variant('east_node', { platforms: ['@elaraai/east-node-std'] }), 'east-node'],
-  ['east_py', variant('east_py', { platforms: ['east-py-std'] }), 'east-py'],
-  ['east_c', variant('east_c', { platforms: ['east-c-std'] }), 'east-c'],
+  ['east_node', variant('east_node', { platforms: ['@elaraai/east-node-std'], decode: variant('lazy', null) }), 'east-node'],
+  ['east_py', variant('east_py', { platforms: ['east-py-std'], decode: variant('lazy', null) }), 'east-py'],
+  ['east_c', variant('east_c', { platforms: ['east-c-std'], decode: variant('lazy', null) }), 'east-c'],
 ];
 
 describe('withRunnerLifeline', () => {
@@ -38,7 +38,7 @@ describe('withRunnerLifeline', () => {
   });
 
   it('is a no-op on a degenerate argv and does not mutate its input', () => {
-    const runner = variant('east_c', { platforms: [] });
+    const runner = variant('east_c', { platforms: [], decode: variant('lazy', null) });
     assert.deepStrictEqual(withRunnerLifeline(runner, ['east-c']), ['east-c']);
     const args = ['east-c', 'exec', 'unit.beast2'];
     const before = [...args];

package/src/runner.ts

@@ -11,23 +11,26 @@
  * its `exec` command; `custom` names a command of the author's own.
  */
 
-import { VariantType, StructType, ArrayType, StringType, ValueTypeOf } from '@elaraai/east';
+import { VariantType, StructType, ArrayType, StringType, UnitDecodeType, ValueTypeOf } from '@elaraai/east';
 
 /**
  * Wire representation of a runner — shared by tasks, functions and records.
  *
- * A known-runtime tag names a stock runner, and `platforms` names the platform
- * packages the units it runs load. `custom` carries a command, which e3 runs
- * with the arguments of a stock runner's `run`: `-i` for each input, `-o` for
- * the output, then the program's file. A custom task's body is its own
- * command, and its runner's is empty. Package authors can already execute
- * arbitrary commands via custom tasks, so `custom` grants no capability that
- * tasks don't have.
+ * A known-runtime tag names a stock runner: `platforms` names the platform
+ * packages the units it runs load, and `decode` how it reads a run unit's
+ * inputs — each collection `lazy`, a segment decoded as the program reaches
+ * it, or every input decoded `whole` before the program runs — which e3 writes
+ * into each run unit it stages for the runner. `custom` carries a command,
+ * which e3 runs with the arguments of a stock runner's `run`: `-i` for each
+ * input, `-o` for the output, then the program's file. A custom task's body is
+ * its own command, and its runner's is empty. Package authors can already
+ * execute arbitrary commands via custom tasks, so `custom` grants no
+ * capability that tasks don't have.
  */
 export const RunnerType = VariantType({
-  east_node: StructType({ platforms: ArrayType(StringType) }),
-  east_py:   StructType({ platforms: ArrayType(StringType) }),
-  east_c:    StructType({ platforms: ArrayType(StringType) }),
+  east_node: StructType({ platforms: ArrayType(StringType), decode: UnitDecodeType }),
+  east_py:   StructType({ platforms: ArrayType(StringType), decode: UnitDecodeType }),
+  east_c:    StructType({ platforms: ArrayType(StringType), decode: UnitDecodeType }),
   custom:    StructType({ command: ArrayType(StringType) }),
 });
 export type RunnerType = typeof RunnerType;

package/src/task.spec.ts

@@ -9,10 +9,14 @@
 
 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 { ArrayType, BlobType, IntegerType, OptionType, StringType, StructType, VariantType, encodeBeast2For, none, some, variant } from '@elaraai/east';
 import {
   TASK_OBJECT_KIND,
+  TaskBodyType,
+  TaskInputType,
   TaskObjectType,
+  TaskOutputType,
+  TaskRoleType,
   decodeTaskObject,
   type TaskObject,
 } from './task.js';
@@ -26,7 +30,7 @@ describe('TaskObjectType', () => {
   const base: TaskObject = {
     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),
@@ -49,6 +53,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);
@@ -71,12 +76,33 @@ 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/src/task.ts

@@ -132,7 +132,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),