@elaraai/e3-types 1.0.83 → 1.0.85

package/src/execution.spec.ts

@@ -5,15 +5,16 @@
 
 /**
  * Execution status wire: the typed outcomes with their peaks, a split task's
- * plan and whether the execution is a unit, what each keeps from gc, and the
- * refusal of a record an older e3 wrote before `cancelled` and `interrupted`
- * were cases of it, before a runner's peak was recorded, before a split task's
- * plan was, or before a record said whether it is a unit.
+ * plan, whether the execution is a unit and why a stopped one stopped, what
+ * each keeps from gc, and the refusal of a record an older e3 wrote before
+ * `cancelled` and `interrupted` were cases of it, before a runner's peak was
+ * recorded, before a split task's plan was, before a record said whether it
+ * is a unit, or before a stopped one said why.
  */
 
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
-import { ArrayType, DateTimeType, IntegerType, OptionType, StringType, StructType, VariantType, encodeBeast2For, none, some, variant } from '@elaraai/east';
+import { ArrayType, BooleanType, DateTimeType, IntegerType, OptionType, StringType, StructType, VariantType, encodeBeast2For, none, some, variant } from '@elaraai/east';
 import { ExecutionStatusType, decodeExecutionStatus, executionStatusRoots, type ExecutionStatus } from './execution.js';
 
 /** The four-case wire every record had before the typed outcomes. */
@@ -45,7 +46,7 @@ describe('ExecutionStatusType', () => {
   };
   const encodeOlder = encodeBeast2For(PreOutcomeExecutionStatusType);
 
-  it('round-trips the typed outcomes, with a runner\'s peak or without one, a task\'s own or a unit\'s', () => {
+  it('round-trips the typed outcomes, with a runner\'s peak or without one, a task\'s own or a unit\'s, and why a stopped one stopped', () => {
     const own = { ...stopped, unit: false };
     const statuses: ExecutionStatus[] = [
       variant('success', { ...own, outputHash: 'b'.repeat(64), peakBytes: some(96n * 1024n ** 2n), plan: none }),
@@ -54,8 +55,11 @@ describe('ExecutionStatusType', () => {
       variant('running', { executionId: '0199-b', inputHashes: ['a'.repeat(64)], startedAt: new Date(1000), pid: 4242n, pidStartTime: 7n, bootId: 'boot', unit: true }),
       variant('failed', { ...own, exitCode: 1n, peakBytes: some(412n * 1024n ** 2n) }),
       variant('failed', { ...own, exitCode: -1n, peakBytes: none }),
-      variant('cancelled', own),
-      variant('interrupted', { ...own, pid: 4242n }),
+      variant('cancelled', { ...own, reason: { kind: variant('aborted', null), message: 'cancelled: e3 stopped the runner because the run was aborted' } }),
+      variant('interrupted', { ...own, pid: 4242n, reason: { kind: variant('owner_gone', null), message: 'its runner and its owner are gone' } }),
+      variant('interrupted', { ...own, pid: 0n, unit: true, reason: { kind: variant('yielded', null), message: 'its run yielded' } }),
+      variant('interrupted', { ...own, pid: 0n, reason: { kind: variant('host', 'OutOfMemoryError'), message: 'its container ran out of memory' } }),
+      variant('interrupted', { ...own, pid: 0n, reason: { kind: variant('unrecorded', null), message: '' } }),
       variant('error', { ...own, message: 'Failed to read output: no such file' }),
     ];
     const encode = encodeBeast2For(ExecutionStatusType);
@@ -67,7 +71,7 @@ describe('ExecutionStatusType', () => {
     assert.deepEqual(executionStatusRoots(variant('success', { ...success, plan: none })), ['b'.repeat(64)]);
     assert.deepEqual(executionStatusRoots(variant('success', { ...success, plan: some('c'.repeat(64)) })), ['b'.repeat(64), 'c'.repeat(64)]);
     assert.deepEqual(executionStatusRoots(variant('failed', { ...stopped, exitCode: 1n, peakBytes: none, unit: false })), []);
-    assert.deepEqual(executionStatusRoots(variant('cancelled', { ...stopped, unit: false })), []);
+    assert.deepEqual(executionStatusRoots(variant('cancelled', { ...stopped, unit: false, reason: { kind: variant('aborted', null), message: '' } })), []);
   });
 
   it('keeps from gc the inputs a running attempt reads, passing over a merge\'s tag', () => {
@@ -113,6 +117,24 @@ describe('ExecutionStatusType', () => {
       }),
     });
     assert.throws(() => decodeExecutionStatus(encodeBeast2For(withoutUnits)(variant('success', { ...stopped, outputHash: 'b'.repeat(64), peakBytes: none, plan: none }))), refusal);
+    // With units, before a stopped record said why it stopped: only the
+    // repository upgrade that carries such a record forward reads it, and every
+    // case of it is refused, since its type names the cases that changed.
+    const withoutReasons = VariantType({
+      ...ExecutionStatusType.cases,
+      cancelled: StructType({ executionId: StringType, inputHashes: ArrayType(StringType), startedAt: DateTimeType, completedAt: DateTimeType, unit: BooleanType }),
+      interrupted: StructType({
+        executionId: StringType, inputHashes: ArrayType(StringType), startedAt: DateTimeType, completedAt: DateTimeType, pid: IntegerType, unit: BooleanType,
+      }),
+    });
+    const own = { ...stopped, unit: false };
+    for (const record of [
+      variant('cancelled', own),
+      variant('interrupted', { ...own, pid: 4242n }),
+      variant('success', { ...own, outputHash: 'b'.repeat(64), peakBytes: none, plan: none }),
+    ] as const) {
+      assert.throws(() => decodeExecutionStatus(encodeBeast2For(withoutReasons)(record)), refusal);
+    }
   });
 
   it('throws for bytes of no status shape', () => {

package/src/execution.ts

@@ -15,7 +15,7 @@
  * - For success: output hash, timing, peak memory and a split task's last plan
  * - For failed: exit code, timing and peak memory
  * - For error: internal error message and timing
- * - For cancelled and interrupted: how e3, not the task, ended it
+ * - For cancelled and interrupted: how e3, not the task, ended it, and why
  *
  * Every case says whether the execution is a unit of a split task — a piece,
  * or a merge of the pieces' outputs — which is recorded under its task's hash
@@ -31,10 +31,42 @@ import {
   IntegerType,
   BooleanType,
   DateTimeType,
+  NullType,
   ValueTypeOf,
   decodeBeast2For,
 } from '@elaraai/east';
 
+/**
+ * Why an execution stopped without finishing: what a `cancelled` or an
+ * `interrupted` record says, written in the same write as the record.
+ *
+ * - `aborted`: the signal it ran under was aborted — its run was cancelled,
+ *   or the call it ran for ended
+ * - `yielded`: its run yielded mid-stage, and a run resumed takes the stage up
+ *   again
+ * - `owner_gone`: its runner and the process, or the browser tab, that owned
+ *   it are gone
+ * - `host`: a host's own reason, by its code — e3-cloud's for a container
+ *   that stopped, say
+ * - `unrecorded`: it stopped before e3 recorded reasons; only the repository
+ *   upgrade that carried its record forward writes it
+ *
+ * `message` is what e3 wrote as the attempt's log's last line, after its
+ * `e3: `, or the host's words; empty for `unrecorded`.
+ */
+export const StopReasonType = StructType({
+  kind: VariantType({
+    aborted: NullType,
+    yielded: NullType,
+    owner_gone: NullType,
+    host: StringType,
+    unrecorded: NullType,
+  }),
+  message: StringType,
+});
+
+export type StopReason = ValueTypeOf<typeof StopReasonType>;
+
 /** A running execution's process identification. */
 const RunningStatusType = StructType({
   /** Unique execution ID (UUIDv7) */
@@ -126,10 +158,14 @@ const ErrorStatusType = StructType({
  * - `success`: Task ran and returned exit code 0
  * - `failed`: Task ran and returned non-zero exit code
  * - `error`: e3 execution engine had an internal error (runner not found, output missing, etc.)
- * - `cancelled`: e3 stopped the execution because the run was aborted, before
- *   its runner started or while it ran — not the task's own failure
- * - `interrupted`: the orchestrator that owned the execution exited before it
- *   finished, and its runner is gone too, so nothing will write its outcome
+ * - `cancelled`: e3 stopped the execution because the signal it ran under was
+ *   aborted, before its runner started or while it ran — not the task's own
+ *   failure
+ * - `interrupted`: the execution can no longer finish, and nothing will write
+ *   its outcome: its runner and its owner are gone, its host says it cannot,
+ *   or its run yielded mid-stage
+ *
+ * Each of the two says why it stopped ({@link StopReasonType}).
  *
  * The `running` state includes process identification fields (pid, pidStartTime, bootId)
  * to enable detection of crashed executions. See design/e3-execution.md for details.
@@ -154,6 +190,8 @@ export const ExecutionStatusType = VariantType({
      *  the pieces' outputs — rather than a task's own execution, which the one
      *  unit of a task whose input closes no piece is */
     unit: BooleanType,
+    /** Why it stopped: `aborted` */
+    reason: StopReasonType,
   }),
   interrupted: StructType({
     /** Unique execution ID (UUIDv7) */
@@ -170,6 +208,9 @@ export const ExecutionStatusType = VariantType({
      *  the pieces' outputs — rather than a task's own execution, which the one
      *  unit of a task whose input closes no piece is */
     unit: BooleanType,
+    /** Why it can no longer finish: `owner_gone`, `yielded`, or its host's
+     *  reason */
+    reason: StopReasonType,
   }),
 });
 
@@ -209,8 +250,12 @@ const decodeCurrentStatus = decodeBeast2For(ExecutionStatusType);
  * Decode an execution status.
  *
  * @remarks
- * Stored state, so it changes by hard cutover: a repository an older e3 wrote
- * is re-created rather than read, and this says so.
+ * Stored state, which changes as `docs/conventions/WIRE_MIGRATION.md` says:
+ * this reads the current form alone. A repository's upgrade steps carry its
+ * records into it when an e3 first opens the repository — the stop reasons'
+ * step those from before a stopped execution recorded why — so a record in an
+ * earlier form here is one from before repositories recorded their upgrades,
+ * whose repository is re-created, and this says so.
  *
  * @param data - the stored bytes
  * @returns the status

package/src/index.ts

@@ -92,6 +92,7 @@ export {
   treePath,
   pathToString,
   parsePath,
+  parseKeypath,
   parseDatasetPath,
   parsePackageRef,
   urlPathToTreePath,
@@ -122,6 +123,7 @@ export {
   decodeRecordObject,
   RecordIndexObjectType,
   type RecordIndexObject,
+  decodeRecordIndexObject,
   RECORD_STATE_KIND,
   RecordStateType,
   type RecordState,
@@ -184,6 +186,8 @@ export {
 
 // Execution status
 export {
+  StopReasonType,
+  type StopReason,
   ExecutionStatusType,
   type ExecutionStatus,
   decodeExecutionStatus,
@@ -223,6 +227,8 @@ export {
 export {
   RepositoryRecordType,
   type RepositoryRecord,
+  RepositoryUpgradeProgressType,
+  type RepositoryUpgradeProgress,
   RepoStatusType,
   type RepoStatus,
   RepoMetadataType,
@@ -232,8 +238,8 @@ export {
 // The release of e3 this build is, which what it keeps and ships records
 export { E3_RELEASE, compareReleases } from './release.js';
 
-// The names e3 makes paths of
-export { type NamedKind, nameProblem } from './names.js';
+// The names e3 makes paths of, and the hashes and ids
+export { type NamedKind, type HashKind, type IdKind, type IdentifierKind, nameProblem } from './names.js';
 
 // Dataset transfer types
 export {
@@ -256,6 +262,7 @@ export {
   isCollectionRoot,
   encodeDatasetBlob,
   writeCollectionManifest,
+  SEGMENT_WRITES_IN_FLIGHT,
   type CollectionSegmentRef,
   type CollectionPiece,
   type SegmentSink,
@@ -355,6 +362,7 @@ export {
   // Execution
   DataflowRequestType,
   LogChunkType,
+  TaskLogChunkType,
   TaskExecutionResultType,
   DataflowResultType,
   // Dataflow API polling
@@ -365,9 +373,12 @@ export {
   UnitWaitType,
   SplitProgressType,
   ApiDataflowExecutionStateType,
+  DATAFLOW_POLL_EVENTS_MAX,
   // Task Execution History
   ExecutionHistoryStatusType,
   ExecutionListItemType,
+  TASK_EXECUTIONS_PAGE_DEFAULT,
+  TASK_EXECUTIONS_PAGE_MAX,
   // Dataset List
   TreeKindType,
   ListEntryType,
@@ -377,6 +388,7 @@ export {
   ExecuteLimitsType,
   DiagnosticType,
   ExecuteResultType,
+  CallArgType,
   FunctionCallRequestType,
   FunctionSignatureType,
   OneShotRequestType,
@@ -388,9 +400,16 @@ export {
   SplitCallPlanType,
   MutationCallRequestType,
   MutationResultType,
+  RecordMigrationAppliedType,
   RecordSignatureType,
   RecordCommitInfoType,
+  RecordArgPreviewType,
+  RecordCommitArgsType,
+  RecordHistoryCommitType,
   RecordHistoryResultType,
+  RECORD_ARG_TEXT_CHARS,
+  RECORD_ARG_TEXT_BYTES,
+  RECORD_ARGS_READ_BYTES,
   // Type aliases
   type Error,
   type RepositoryStatus,
@@ -424,6 +443,7 @@ export {
   type TaskDetails,
   type DataflowRequest,
   type LogChunk,
+  type TaskLogChunk,
   type TaskExecutionResult,
   type DataflowResult,
   type DataflowEvent,
@@ -441,6 +461,7 @@ export {
   type ExecuteLimits,
   type Diagnostic,
   type ExecuteResult,
+  type CallArg,
   type FunctionCallRequest,
   type FunctionSignature,
   type OneShotRequest,
@@ -451,8 +472,12 @@ export {
   type SplitCallPlan,
   type MutationCallRequest,
   type MutationResult,
+  type RecordMigrationApplied,
   type RecordSignature,
   type RecordCommitInfo,
+  type RecordArgPreview,
+  type RecordCommitArgs,
+  type RecordHistoryCommit,
   type RecordHistoryResult,
 } from './api.js';
 
@@ -473,9 +498,17 @@ export {
   ExecutionEventType,
   type ExecutionEvent,
   type PartitionProgress,
+  DataflowForceType,
+  type DataflowForce,
+  dataflowForce,
+  dataflowForceOption,
   DataflowExecutionStateType,
   type DataflowExecutionState,
   decodeDataflowExecutionState,
+  ExecutionStateSummaryType,
+  type ExecutionStateSummary,
+  executionStateSummary,
+  lastEventSeq,
   // Dataflow run history
   DataflowRunStatusType,
   type DataflowRunStatus,
@@ -487,6 +520,10 @@ export {
   type DataflowRun,
 } from './dataflow.js';
 
+// The sizes e3 cuts a split task's input into pieces at, which a caller
+// planning a split call weighs a dataset against
+export { PIECE_SIZES, type PieceSizes } from './pieces.js';
+
 // A split task's unit graph, a stage at a time
 export {
   UNIT_PLAN_KIND,

package/src/names.ts

@@ -13,6 +13,18 @@
 /** What a name names. */
 export type NamedKind = 'repository' | 'workspace' | 'package' | 'package version' | 'lock';
 
+/** What a hash e3 makes a path or a key of names: an object, or an
+ *  execution's task or inputs. */
+export type HashKind = 'object hash' | 'task hash' | 'inputs hash';
+
+/** What an id e3 makes a path or a key of names: an execution attempt, a
+ *  dataflow run, or a gc run in steps. */
+export type IdKind = 'execution id' | 'run id' | 'gc run id';
+
+/** What a hash or an id e3 makes a path or a key of names: not a name, so
+ *  checked for its form rather than by {@link nameProblem}. */
+export type IdentifierKind = HashKind | IdKind;
+
 /** What no name may hold: a path separator, a character a Windows file name
  *  refuses, or a control character. */
 const REFUSED = /[/\\:*?"<>|\u0000-\u001f]/;

package/src/pieces.spec.ts

@@ -0,0 +1,23 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+
+/**
+ * The platform's piece sizes, which e3-core's piece rule closes pieces at and
+ * a caller planning a split call weighs a dataset against.
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { PIECE_SIZES } from './index.js';
+
+describe('PIECE_SIZES', () => {
+  it('is 16, 64 and 256 MiB, exported from the package', () => {
+    assert.deepEqual(PIECE_SIZES, { min: 16 * 2 ** 20, target: 64 * 2 ** 20, max: 256 * 2 ** 20 });
+  });
+
+  it('orders its sizes: the least a piece holds, its middle, and the most', () => {
+    assert.ok(PIECE_SIZES.min < PIECE_SIZES.target && PIECE_SIZES.target < PIECE_SIZES.max);
+  });
+});

package/src/pieces.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.
+ */
+
+/**
+ * The sizes e3 cuts a split task's input into pieces at.
+ *
+ * They live here, beside the wire types, so a caller that plans a split call
+ * in a browser — the query builder — weighs a dataset against the smallest
+ * piece e3 cuts without importing e3-core. e3-core's piece rule closes pieces
+ * at these sizes, and its `pieceSizes()` gives the sizes a process plans with:
+ * these, or the sizes a test sets.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The sizes the piece rule closes pieces at, in stored bytes: a piece closes
+ * only once it holds `min`, weighs its segments against `max` until it holds
+ * `target` and against `min` after, and always closes once it holds `max`.
+ *
+ * @remarks
+ * A dataset that weighs no more than `min` is one piece, which is why a
+ * caller compares a dataset's stored bytes with `min` to tell whether a split
+ * call would split it.
+ */
+export interface PieceSizes {
+  /** The least a piece holds, unless the input ends first. */
+  readonly min: number;
+  /** Where a piece starts closing readily: the pieces' middle size, which a
+   *  merge range aims for too. */
+  readonly target: number;
+  /** The most a piece holds, but for the rest of a `by` group. */
+  readonly max: number;
+}
+
+/**
+ * The platform's piece sizes: 16, 64 and 256 MiB.
+ *
+ * @example
+ * ```ts
+ * import { PIECE_SIZES } from '@elaraai/e3-types';
+ *
+ * // A dataset within one piece is read in one call.
+ * const split = storedBytes > PIECE_SIZES.min;
+ * ```
+ */
+export const PIECE_SIZES: PieceSizes = { min: 16 * 2 ** 20, target: 64 * 2 ** 20, max: 256 * 2 ** 20 };

package/src/record.spec.ts

@@ -6,26 +6,29 @@
 /**
  * The record wire types' decoders: each reads the current shape, and refuses
  * an older one naming the fix — a commit an older e3 wrote, whose repository
- * is re-created, and a mutation, migration or record object an older SDK
- * exported, whose package is re-exported.
+ * is re-created, and a mutation, migration, index or record object an older
+ * SDK exported, whose package is re-exported.
  */
 
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
-import { DateTimeType, DictType, IntegerType, OptionType, StringType, StructType, ArrayType, EastTypeType, encodeBeast2For, isTypeValueEqual, some, toEastTypeValue, variant } from '@elaraai/east';
+import { BooleanType, DateTimeType, DictType, IntegerType, OptionType, StringType, StructType, ArrayType, EastTypeType, VariantType, encodeBeast2For, isTypeValueEqual, some, toEastTypeValue, variant } from '@elaraai/east';
 import { RunnerType } from './runner.js';
 import {
   MigrationObjectType,
   MutationObjectType,
   RecordCommitType,
+  RecordIndexObjectType,
   RecordObjectType,
   decodeMigrationObject,
   decodeMutationObject,
   decodeRecordCommit,
+  decodeRecordIndexObject,
   decodeRecordObject,
   type MigrationObject,
   type MutationObject,
   type RecordCommit,
+  type RecordIndexObject,
   type RecordObject,
 } from './record.js';
 
@@ -65,7 +68,7 @@ describe('decodeMutationObject', () => {
   const mutation: MutationObject = {
     bodyIr: 'a'.repeat(64),
     argTypes: [toEastTypeValue(IntegerType)],
-    runner: variant('east_node', { platforms: ['@elaraai/east-node-std'] }),
+    runner: variant('east_node', { platforms: ['@elaraai/east-node-std'], decode: variant('lazy', null) }),
     form: variant('edit', null),
     programIr: 'b'.repeat(64),
   };
@@ -113,6 +116,49 @@ describe('decodeMutationObject', () => {
   });
 });
 
+describe('decodeRecordIndexObject', () => {
+  const index: RecordIndexObject = {
+    keyIr: 'a'.repeat(64),
+    multi: false,
+    valueIr: some('b'.repeat(64)),
+    keyType: toEastTypeValue(StringType),
+    valueType: toEastTypeValue(IntegerType),
+    buildIr: 'c'.repeat(64),
+    runner: variant('east_node', { platforms: ['@elaraai/east-node-std'], decode: variant('whole', null) }),
+  };
+
+  it('round-trips a current index object, its types among it', () => {
+    const decoded = decodeRecordIndexObject(encodeBeast2For(RecordIndexObjectType)(index));
+    // A decoded type value carries no memoized identity, so only the East
+    // comparison says whether two of them are the same type.
+    assert.ok(isTypeValueEqual(decoded.keyType, index.keyType));
+    assert.ok(isTypeValueEqual(decoded.valueType, index.valueType));
+    const { keyType: _keyType, valueType: _valueType, ...rest } = decoded;
+    const { keyType: _k, valueType: _v, ...expected } = index;
+    assert.deepEqual(rest, expected);
+  });
+
+  it('refuses an index object whose runner predates its decode, naming the fix', () => {
+    // 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 PreDecodeIndexType = StructType({
+      keyIr: StringType, multi: BooleanType, valueIr: OptionType(StringType), keyType: EastTypeType,
+      valueType: EastTypeType, buildIr: StringType, runner: PreDecodeRunnerType,
+    });
+    const older = encodeBeast2For(PreDecodeIndexType)({ ...index, runner: variant('east_node', { platforms: ['@elaraai/east-node-std'] }) });
+    assert.throws(
+      () => decodeRecordIndexObject(older),
+      /^Error: the index object does not decode: the package was exported by an older e3 SDK — re-export it with the current one \(/,
+    );
+  });
+});
+
 describe('decodeMigrationObject', () => {
   const RowV1Type = StructType({ name: StringType });
   const RowV2Type = StructType({ name: StringType, shift: IntegerType });
@@ -122,7 +168,7 @@ describe('decodeMigrationObject', () => {
     to: toEastTypeValue(DictType(StringType, RowV2Type)),
     bodyIr: 'a'.repeat(64),
     programIr: 'b'.repeat(64),
-    runner: variant('east_node', { platforms: ['@elaraai/east-node-std'] }),
+    runner: variant('east_node', { platforms: ['@elaraai/east-node-std'], decode: variant('lazy', null) }),
   };
 
   it('round-trips a current migration, its types among it', () => {

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.83';
+export const E3_RELEASE = '1.0.85';
 
 /** 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/repository.ts

@@ -34,6 +34,24 @@ export const RepositoryRecordType = StructType({
 
 export type RepositoryRecord = ValueTypeOf<typeof RepositoryRecordType>;
 
+/**
+ * A store upgrade under way in a repository, kept beside the repository
+ * record: the step, the release of e3 applying it, and where its last part
+ * stopped. A step applies in parts, and the next part takes it up from here,
+ * in this process or another; the record lists the step only once it is done.
+ */
+export const RepositoryUpgradeProgressType = StructType({
+  /** The step's name */
+  step: StringType,
+  /** The release of e3 applying it */
+  release: StringType,
+  /** Where its last part stopped: the step's own cursor, which the next part
+   *  takes it up from */
+  cursor: StringType,
+});
+
+export type RepositoryUpgradeProgress = ValueTypeOf<typeof RepositoryUpgradeProgressType>;
+
 /**
  * Where a repository is in its lifecycle.
  */

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;