@elaraai/e3-types 1.0.79 → 1.0.80

package/src/transfer.spec.ts

@@ -4,25 +4,14 @@
  */
 
 /**
- * The dataset transfer protocol's two invariants that live in e3-types.
- *
- * Part arithmetic is shared by the client that cuts the bytes and the server
- * that places them, so an off-by-one on either side would corrupt uploads
- * silently until the commit's hash check. And protocol 2 only adds variant
- * cases: a version-1 client decodes a version-1 answer from a new server, and a
- * new client decodes an old server's answers, only while every added case sorts
- * after the version-1 cases and so leaves their tags unchanged.
+ * The dataset transfer protocol's part arithmetic, which the client that cuts
+ * the bytes and the server that places them share, so an off-by-one on either
+ * side would corrupt uploads silently until the commit's hash check.
  */
 
 import { describe, it } from 'node:test';
 import * as assert from 'node:assert';
-import { NullType, StringType, StructType, VariantType, decodeBeast2For, encodeBeast2For, variant } from '@elaraai/east';
-import {
-  TransferDoneResponseType,
-  TransferUploadResponseType,
-  transferPartCount,
-  transferPartRange,
-} from './transfer.js';
+import { transferPartCount, transferPartRange } from './transfer.js';
 
 describe('transferPartCount / transferPartRange', () => {
   it('cuts an upload into full parts and a remainder', () => {
@@ -60,39 +49,3 @@ describe('transferPartCount / transferPartRange', () => {
     });
   });
 });
-
-describe('transfer wire compatibility across protocol versions', () => {
-  // The version-1 shapes, as a client and server built before protocol 2 hold them.
-  const UploadResponseV1 = VariantType({
-    completed: NullType,
-    upload: StructType({ id: StringType, uploadUrl: StringType }),
-  });
-  const DoneResponseV1 = VariantType({
-    completed: NullType,
-    error: StructType({ message: StringType }),
-  });
-
-  it('keeps the init answers a version-1 client decodes', () => {
-    const upload = variant('upload', { id: 'abc', uploadUrl: 'http://h/api/uploads/abc' });
-    assert.deepStrictEqual(
-      decodeBeast2For(UploadResponseV1)(encodeBeast2For(TransferUploadResponseType)(upload)),
-      upload,
-    );
-    assert.deepStrictEqual(
-      decodeBeast2For(TransferUploadResponseType)(encodeBeast2For(UploadResponseV1)(upload)),
-      upload,
-    );
-    const completed = variant('completed', null);
-    assert.deepStrictEqual(
-      decodeBeast2For(UploadResponseV1)(encodeBeast2For(TransferUploadResponseType)(completed)),
-      completed,
-    );
-  });
-
-  it('keeps the commit answers a version-1 client decodes', () => {
-    for (const done of [variant('completed', null), variant('error', { message: 'hash mismatch' })] as const) {
-      assert.deepStrictEqual(decodeBeast2For(DoneResponseV1)(encodeBeast2For(TransferDoneResponseType)(done)), done);
-      assert.deepStrictEqual(decodeBeast2For(TransferDoneResponseType)(encodeBeast2For(DoneResponseV1)(done)), done);
-    }
-  });
-});

package/src/transfer.ts

@@ -9,24 +9,24 @@
  * Used by both the API server and client for large dataset uploads
  * that exceed inline body size limits.
  *
- * Two protocol versions share these types. A client names the version it speaks
- * with `?protocol=N` on the init and commit requests (a request without it is
- * version 1), and a server answers only in the forms that version understands —
- * every case version 2 adds sorts after the version-1 cases, so the tags a
- * version-1 client decodes keep their numbers.
+ * A client names the protocol version it speaks with `?protocol=N` on the init
+ * and commit requests, and its release beside it (`&release=`). A server
+ * refuses a request that names another version, or none, naming both
+ * releases and the fix. The release decides nothing, so an older client and a
+ * newer server that speak one version work together.
  */
 
 import { VariantType, StructType, StringType, IntegerType, NullType, DictType, type ValueTypeOf } from '@elaraai/east';
 
 /**
- * The dataset transfer protocol version this build speaks.
+ * The dataset transfer protocol version this build speaks, and the only one.
  *
  * @remarks
- * Version 2 lets the server plan an upload as parts — each sent to its own URL
- * with the request headers the server names, so an object store can bind a
- * checksum to a single PUT or take a multipart upload larger than one PUT
- * allows — and lets a commit answer `processing` while the server verifies the
- * bytes, for the client to poll.
+ * The server plans an upload as parts — each sent to its own URL with the
+ * request headers the server names, so an object store can bind a checksum to
+ * a single PUT or take a multipart upload larger than one PUT allows — and a
+ * commit may answer `processing` while the server verifies the bytes, for the
+ * client to poll.
  */
 export const TRANSFER_PROTOCOL_VERSION = 2;
 
@@ -81,11 +81,9 @@ export type TransferUploadRequest = ValueTypeOf<typeof TransferUploadRequestType
  * Transfer upload init response.
  *
  * - `completed`: Object already exists (dedup), dataset ref updated
- * - `upload`: Staging slot created; the client PUTs every byte to `uploadUrl`,
- *   then commits
- * - `upload_parts` (protocol 2): the client sends the bytes as parts of
- *   `partBytes` bytes each (the last part holds the remainder, and an upload no
- *   larger than `partBytes` is one part). Part `n` (1-based) is the byte range
+ * - `upload_parts`: the client sends the bytes as parts of `partBytes` bytes
+ *   each (the last part holds the remainder, and an upload no larger than
+ *   `partBytes` is one part). Part `n` (1-based) is the byte range
  *   `[(n - 1) * partBytes, min(size, n * partBytes))`; its URL and required
  *   headers come from `GET …/upload/<id>/parts/<n>`. Parts may be sent in any
  *   order and concurrently, and re-sending a part replaces it. The client
@@ -93,10 +91,6 @@ export type TransferUploadRequest = ValueTypeOf<typeof TransferUploadRequestType
  */
 export const TransferUploadResponseType = VariantType({
   completed: NullType,
-  upload: StructType({
-    id: StringType,
-    uploadUrl: StringType,
-  }),
   upload_parts: StructType({
     id: StringType,
     partBytes: IntegerType,
@@ -105,7 +99,7 @@ export const TransferUploadResponseType = VariantType({
 export type TransferUploadResponse = ValueTypeOf<typeof TransferUploadResponseType>;
 
 /**
- * Where and how to send one part of a protocol-2 upload.
+ * Where and how to send one part of an upload.
  *
  * @property url - The URL the client PUTs the part's bytes to, without an
  *   `Authorization` header (it may be a presigned object-store URL)
@@ -124,7 +118,7 @@ export type TransferPartResponse = ValueTypeOf<typeof TransferPartResponseType>;
  *
  * - `completed`: Hash verified, object stored, dataset ref updated
  * - `error`: Hash mismatch or other failure
- * - `processing` (protocol 2): the server is still verifying the bytes; poll
+ * - `processing`: the server is still verifying the bytes; poll
  *   `GET …/upload/<id>` until it answers `completed` or `error`
  */
 export const TransferDoneResponseType = VariantType({

package/src/unit-plan.spec.ts

@@ -0,0 +1,31 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { encodeBeast2For, equalFor, none, some, variant } from '@elaraai/east';
+import { UNIT_PLAN_KIND, UnitPlanType, decodeUnitPlan, encodeUnitPlan, type UnitPlan } from './unit-plan.js';
+
+describe('unit plans', () => {
+  it('round-trips each stage', () => {
+    const plans: UnitPlan[] = [
+      { kind: UNIT_PLAN_KIND, task: 'a1', inputs: 'b2', stage: variant('pieces', [['c3', 'd4'], ['e5', 'd4']]), previous: none, peakBytes: none },
+      {
+        kind: UNIT_PLAN_KIND, task: 'a1', inputs: 'b2',
+        stage: variant('merge', { level: 1n, levels: 2n, groups: [{ range: some('f6'), entries: ['g7', 'h8'] }, { range: none, entries: ['i9'] }] }),
+        previous: some('j0'),
+        peakBytes: some(52_428_800n),
+      },
+    ];
+    for (const plan of plans) {
+      assert.ok(equalFor(UnitPlanType)(decodeUnitPlan(encodeUnitPlan(plan)), plan));
+    }
+  });
+
+  it('refuses an object of another kind', () => {
+    const other = encodeBeast2For(UnitPlanType)({ kind: 'task', task: 'a1', inputs: 'b2', stage: variant('pieces', []), previous: none, peakBytes: none });
+    assert.throws(() => decodeUnitPlan(other), { message: "the object is not a unit plan: its kind is 'task', not '$plan'" });
+  });
+});

package/src/unit-plan.ts

@@ -0,0 +1,121 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+
+/**
+ * The unit graph of a task split into pieces, a stage at a time.
+ *
+ * A split task runs in stages: its pieces, and then, for a set, a dict or a
+ * fold, each level of the merges that assemble their outputs. Each stage's
+ * units are one of these objects, written when the stage starts and named by
+ * the task's entry in the dataflow's execution state. So resuming a stage reads
+ * this object back, and finds the units that finished in the execution cache.
+ * Each names the plan of the stage before it, and the task's `success` record
+ * names the last, so every stage the task ran is found from its record, and
+ * with them the units gc keeps beside it.
+ *
+ * It names other objects, so it carries a `kind` tag the garbage collector
+ * dispatches on.
+ *
+ * @packageDocumentation
+ */
+
+import { ArrayType, IntegerType, OptionType, StringType, StructType, VariantType, decodeBeast2For, encodeBeast2For, type ValueTypeOf } from '@elaraai/east';
+
+/** The kind tag every unit plan carries. */
+export const UNIT_PLAN_KIND = '$plan';
+
+/** Parts a merge level assembles into one: a group of the pieces' outputs
+ *  whose keys overlap, over one key range, or a fold's partials. */
+export const UnitPlanGroupType = StructType({
+  /** The hash of the key range the group's merges run over — `{from, to}`
+   *  over the parts' key type — or `none` to merge the parts whole. */
+  range: OptionType(StringType),
+  /** The parts, in the order they fold: each unit of the level merges a run
+   *  of them, and a run of one passes through. */
+  entries: ArrayType(StringType),
+});
+export type UnitPlanGroupType = typeof UnitPlanGroupType;
+export type UnitPlanGroup = ValueTypeOf<typeof UnitPlanGroupType>;
+
+/**
+ * A stage of a split task.
+ *
+ * - `pieces`: each piece's inputs, in the task's input order — a partitioned
+ *   input's piece of it, and every other input as it is.
+ * - `merge`: one level of the merges that assemble the pieces' outputs, and
+ *   the groups it merges, in key order.
+ */
+export const UnitPlanStageType = VariantType({
+  pieces: ArrayType(ArrayType(StringType)),
+  merge: StructType({
+    /** The level, from 1. */
+    level: IntegerType,
+    /** The number of levels the merges take. */
+    levels: IntegerType,
+    /** The groups, in key order. */
+    groups: ArrayType(UnitPlanGroupType),
+  }),
+});
+export type UnitPlanStageType = typeof UnitPlanStageType;
+export type UnitPlanStage = ValueTypeOf<typeof UnitPlanStageType>;
+
+/**
+ * A stage of a split task's unit graph, stored as an object.
+ *
+ * @example
+ * ```ts
+ * import { none, variant } from '@elaraai/east';
+ *
+ * const plan: UnitPlan = {
+ *   kind: UNIT_PLAN_KIND,
+ *   task: '5e7a3b…',
+ *   inputs: '9c01de…',
+ *   stage: variant('pieces', [['a1b2…'], ['c3d4…']]),
+ *   previous: none,
+ *   peakBytes: none,
+ * };
+ * ```
+ */
+export const UnitPlanType = StructType({
+  /** Always {@link UNIT_PLAN_KIND}. */
+  kind: StringType,
+  /** The task object's hash. */
+  task: StringType,
+  /** The task's inputs hash: the execution the plan belongs to. */
+  inputs: StringType,
+  /** The stage. */
+  stage: UnitPlanStageType,
+  /** The plan of the stage before this one; `none` for the pieces. */
+  previous: OptionType(StringType),
+  /** The largest peak resident memory, in bytes, a unit of the stages before
+   *  this one reached, as their execution records hold it; `none` for the
+   *  pieces, or when no unit reported one. A task taken up at this stage
+   *  starts its own peak from it, so its record counts every stage wherever
+   *  it was taken up. */
+  peakBytes: OptionType(IntegerType),
+});
+export type UnitPlanType = typeof UnitPlanType;
+export type UnitPlan = ValueTypeOf<typeof UnitPlanType>;
+
+/** Encodes a {@link UnitPlanType} object for the object store. */
+export const encodeUnitPlan: (plan: UnitPlan) => Uint8Array = encodeBeast2For(UnitPlanType);
+
+const decodeUnitPlanValue = decodeBeast2For(UnitPlanType);
+
+/**
+ * Decodes a unit plan.
+ *
+ * @param data - the stored bytes
+ * @returns the plan
+ * @throws {Error} When the bytes are not a unit plan, or carry another kind
+ *   tag.
+ */
+export function decodeUnitPlan(data: Uint8Array): UnitPlan {
+  const plan = decodeUnitPlanValue(data);
+  if (plan.kind !== UNIT_PLAN_KIND) {
+    throw new Error(`the object is not a unit plan: its kind is '${plan.kind}', not '${UNIT_PLAN_KIND}'`);
+  }
+  return plan;
+}

package/src/workspace.ts

@@ -6,23 +6,17 @@
 /**
  * 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
+ * A workspace is a mutable working copy of a package. Its record is `none`
+ * from its creation until a package is deployed to it, and then its state:
+ * which package was deployed, when, and the latest dataflow run.
  *
- * State file location: workspaces/<name>/state.beast2
- * No state file = workspace exists but not yet deployed.
+ * A local repository keeps the record at `workspaces/<name>.beast2`.
  */
 
 import { StructType, StringType, DateTimeType, OptionType, 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.
+ * A deployed workspace's state.
  *
  * Future audit trail support:
  * When we implement full audit trail, this state will move to the object
@@ -48,3 +42,11 @@ export const WorkspaceStateType = StructType({
 });
 
 export type WorkspaceState = ValueTypeOf<typeof WorkspaceStateType>;
+
+/**
+ * A workspace's record: `none` until a package is deployed to it, and then
+ * its state.
+ */
+export const WorkspaceRecordType = OptionType(WorkspaceStateType);
+
+export type WorkspaceRecord = ValueTypeOf<typeof WorkspaceRecordType>;

package/dist/src/stream.d.ts

@@ -1,97 +0,0 @@
-/**
- * Copyright (c) 2025 Elara AI Pty Ltd
- * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
- */
-/**
- * The stream and merge commands (issue #770) — the builders of every argv a
- * stream execution spawns (an authored `streamTask`'s) and of the merge
- * command a partitioned task's keyed fan-in runs per key range, both built
- * at export time and carried in the package like any other command IR.
- */
-import { EastIR } from '@elaraai/east';
-import { type RunnerValue } from './runner.js';
-/**
- * How a stream execution's emit sink treats equal keys: `none` — a duplicate
- * is an error; `function` — the merge IR (wire input 1) folds adjacent equal
- * Dict keys, passed to the runner as `--merge`; `union` — adjacent equal Set
- * elements collapse to the first, `--union`.
- */
-export type StreamMergeMode = 'none' | 'function' | 'union';
-/**
- * The shape of a stream command.
- *
- * @remarks
- * The wire inputs a stream execution stages are laid out `[body IR, merge IR
- * (function mode only), ...-i inputs]`; `stream` names whether the first of
- * the `-i` inputs is the one the runner opens lazily.
- */
-export interface StreamCommandSpec {
-    /** The output collection kind the emit sink writes. */
-    emit: 'array' | 'set' | 'dict';
-    /** How equal keys fold — see {@link StreamMergeMode}. */
-    merge: StreamMergeMode;
-    /** The `-i` input the runner feeds lazily: none, or the first. */
-    stream: 'none' | 'first';
-}
-/**
- * Builds the command IR of a stream execution: `(input_paths, output_path)
- * -> argv`.
- *
- * The argv is `[...runner, '--emit', <emit>, '--merge' <merge IR path> |
- * '--union', '--stream' '0' when the first -i input streams, '-i' <path> for
- * each -i input, '-o', <output>, <body IR path>]` — the body IR is wire
- * input 0, the merge IR wire input 1 in function mode, and the `-i` inputs
- * follow. Built with `East.function` exactly as a task command is.
- *
- * @param runner - the stock runner the execution spawns
- * @param spec - the emit kind, the merge mode and the streamed input
- * @returns the command IR
- *
- * @example
- * ```ts
- * import { variant } from '@elaraai/east';
- *
- * const command = streamCommandIr(variant('east_c', { platforms: [] }), { emit: 'dict', merge: 'function', stream: 'first' });
- * command.compile([])(['body.beast2', 'merge.beast2', 'a.beast2'], 'out.beast2');
- * // ['east-c', 'run', '--emit', 'dict', '--merge', 'merge.beast2', '--stream', '0',
- * //  '-i', 'a.beast2', '-o', 'out.beast2', 'body.beast2']
- * ```
- */
-export declare function streamCommandIr(runner: RunnerValue, spec: StreamCommandSpec): EastIR<[string[], string], string[]>;
-/**
- * Builds the command IR of a merge execution — the runner's `merge` command
- * over sorted partials of one Set or Dict type, within a key range:
- * `(input_paths, output_path) -> argv`.
- *
- * The argv is `[...runner merge, '--merge' <merge IR path> | '--union',
- * '--range' <range path>, '-i' <path> for each partial, '-o', <output>]`. In
- * `function` mode wire input 0 is the merge IR `(K, V, V) -> V`, wire input
- * 1 the key range and the partials follow; in `union` mode wire input 0 is
- * the key range and every other wire input is a partial. The key range is a
- * blob of `Struct{from: Option<K>, to: Option<K>}` over the output's key
- * type: only the keys in `[from, to)` merge, each partial sought to the
- * segment owning `from`, and an absent bound is open — a component that
- * merges whole takes the open range. Equal keys across partials fold in
- * input order, and the output is byte-identical to what the runner's emit
- * sink writes for the same entries emitted ascending. A partitioned task's
- * SDK writes this IR into its metadata at export, and the orchestrator runs
- * it as an ordinary execution per key range of a group of partials.
- *
- * @param runner - the stock runner whose `merge` command runs
- * @param mode - `function` (a Dict output, folded with the merge IR) or
- *   `union` (a Set output, the first of equal elements standing)
- * @returns the command IR
- * @throws {Error} When the runner is `custom` — it has no merge command.
- *
- * @example
- * ```ts
- * import { variant } from '@elaraai/east';
- *
- * const command = mergeCommandIr(variant('east_c', { platforms: [] }), 'function');
- * command.compile([])(['merge.beast2', 'range.beast2', 'p0.beast2', 'p1.beast2'], 'out.beast2');
- * // ['east-c', 'merge', '--merge', 'merge.beast2', '--range', 'range.beast2',
- * //  '-i', 'p0.beast2', '-i', 'p1.beast2', '-o', 'out.beast2']
- * ```
- */
-export declare function mergeCommandIr(runner: RunnerValue, mode: 'function' | 'union'): EastIR<[string[], string], string[]>;
-//# sourceMappingURL=stream.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/stream.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;GAKG;AAEH,OAAO,EAAmB,MAAM,EAAc,MAAM,eAAe,CAAC;AACpE,OAAO,EAAgB,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAE7D;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC;AAE5D;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,uDAAuD;IACvD,IAAI,EAAE,OAAO,GAAG,KAAK,GAAG,MAAM,CAAC;IAC/B,yDAAyD;IACzD,KAAK,EAAE,eAAe,CAAC;IACvB,kEAAkE;IAClE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,iBAAiB,GAAG,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC,CAqClH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,GAAG,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC,CA+BpH"}

package/dist/src/stream.js

@@ -1,134 +0,0 @@
-/**
- * Copyright (c) 2025 Elara AI Pty Ltd
- * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
- */
-/**
- * The stream and merge commands (issue #770) — the builders of every argv a
- * stream execution spawns (an authored `streamTask`'s) and of the merge
- * command a partitioned task's keyed fan-in runs per key range, both built
- * at export time and carried in the package like any other command IR.
- */
-import { ArrayType, East, StringType } from '@elaraai/east';
-import { runnerToArgv } from './runner.js';
-/**
- * Builds the command IR of a stream execution: `(input_paths, output_path)
- * -> argv`.
- *
- * The argv is `[...runner, '--emit', <emit>, '--merge' <merge IR path> |
- * '--union', '--stream' '0' when the first -i input streams, '-i' <path> for
- * each -i input, '-o', <output>, <body IR path>]` — the body IR is wire
- * input 0, the merge IR wire input 1 in function mode, and the `-i` inputs
- * follow. Built with `East.function` exactly as a task command is.
- *
- * @param runner - the stock runner the execution spawns
- * @param spec - the emit kind, the merge mode and the streamed input
- * @returns the command IR
- *
- * @example
- * ```ts
- * import { variant } from '@elaraai/east';
- *
- * const command = streamCommandIr(variant('east_c', { platforms: [] }), { emit: 'dict', merge: 'function', stream: 'first' });
- * command.compile([])(['body.beast2', 'merge.beast2', 'a.beast2'], 'out.beast2');
- * // ['east-c', 'run', '--emit', 'dict', '--merge', 'merge.beast2', '--stream', '0',
- * //  '-i', 'a.beast2', '-o', 'out.beast2', 'body.beast2']
- * ```
- */
-export function streamCommandIr(runner, spec) {
-    const prefix = [
-        ...runnerToArgv(runner),
-        '--emit', spec.emit,
-        ...(spec.merge === 'union' ? ['--union'] : []),
-    ];
-    // The merge mode and the streamed input are known here, so the flags they
-    // add are emitted by branching at build time — only the merge IR's PATH is
-    // a run-time value, and only the -i inputs need a loop.
-    const mergeInput = spec.merge === 'function' ? 1n : null;
-    const firstInput = mergeInput === null ? 1n : 2n;
-    const command = East.function([ArrayType(StringType), StringType], ArrayType(StringType), ($, input_paths, output_path) => {
-        const argv = $.let(prefix, ArrayType(StringType));
-        if (mergeInput !== null) {
-            $(argv.pushLast('--merge'));
-            $(argv.pushLast(input_paths.get(mergeInput)));
-        }
-        if (spec.stream === 'first') {
-            $(argv.pushLast('--stream'));
-            $(argv.pushLast('0'));
-        }
-        const i = $.let(firstInput);
-        $.while(East.less(i, input_paths.size()), $ => {
-            $(argv.pushLast('-i'));
-            $(argv.pushLast(input_paths.get(i)));
-            $.assign(i, i.add(1n));
-        });
-        $(argv.pushLast('-o'));
-        $(argv.pushLast(output_path));
-        $(argv.pushLast(input_paths.get(0n)));
-        $.return(argv);
-    });
-    return command.toIR();
-}
-/**
- * Builds the command IR of a merge execution — the runner's `merge` command
- * over sorted partials of one Set or Dict type, within a key range:
- * `(input_paths, output_path) -> argv`.
- *
- * The argv is `[...runner merge, '--merge' <merge IR path> | '--union',
- * '--range' <range path>, '-i' <path> for each partial, '-o', <output>]`. In
- * `function` mode wire input 0 is the merge IR `(K, V, V) -> V`, wire input
- * 1 the key range and the partials follow; in `union` mode wire input 0 is
- * the key range and every other wire input is a partial. The key range is a
- * blob of `Struct{from: Option<K>, to: Option<K>}` over the output's key
- * type: only the keys in `[from, to)` merge, each partial sought to the
- * segment owning `from`, and an absent bound is open — a component that
- * merges whole takes the open range. Equal keys across partials fold in
- * input order, and the output is byte-identical to what the runner's emit
- * sink writes for the same entries emitted ascending. A partitioned task's
- * SDK writes this IR into its metadata at export, and the orchestrator runs
- * it as an ordinary execution per key range of a group of partials.
- *
- * @param runner - the stock runner whose `merge` command runs
- * @param mode - `function` (a Dict output, folded with the merge IR) or
- *   `union` (a Set output, the first of equal elements standing)
- * @returns the command IR
- * @throws {Error} When the runner is `custom` — it has no merge command.
- *
- * @example
- * ```ts
- * import { variant } from '@elaraai/east';
- *
- * const command = mergeCommandIr(variant('east_c', { platforms: [] }), 'function');
- * command.compile([])(['merge.beast2', 'range.beast2', 'p0.beast2', 'p1.beast2'], 'out.beast2');
- * // ['east-c', 'merge', '--merge', 'merge.beast2', '--range', 'range.beast2',
- * //  '-i', 'p0.beast2', '-i', 'p1.beast2', '-o', 'out.beast2']
- * ```
- */
-export function mergeCommandIr(runner, mode) {
-    const prefix = [
-        ...runnerToArgv(runner, 'merge'),
-        ...(mode === 'union' ? ['--union'] : []),
-    ];
-    const mergeInput = mode === 'function' ? 0n : null;
-    const rangeInput = mergeInput === null ? 0n : 1n;
-    const firstInput = rangeInput + 1n;
-    const command = East.function([ArrayType(StringType), StringType], ArrayType(StringType), ($, input_paths, output_path) => {
-        const argv = $.let(prefix, ArrayType(StringType));
-        if (mergeInput !== null) {
-            $(argv.pushLast('--merge'));
-            $(argv.pushLast(input_paths.get(mergeInput)));
-        }
-        $(argv.pushLast('--range'));
-        $(argv.pushLast(input_paths.get(rangeInput)));
-        const i = $.let(firstInput);
-        $.while(East.less(i, input_paths.size()), $ => {
-            $(argv.pushLast('-i'));
-            $(argv.pushLast(input_paths.get(i)));
-            $.assign(i, i.add(1n));
-        });
-        $(argv.pushLast('-o'));
-        $(argv.pushLast(output_path));
-        $.return(argv);
-    });
-    return command.toIR();
-}
-//# sourceMappingURL=stream.js.map

package/dist/src/stream.js.map

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

package/dist/src/stream.spec.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"stream.spec.d.ts","sourceRoot":"","sources":["../../src/stream.spec.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/src/stream.spec.js

@@ -1,60 +0,0 @@
-/**
- * Copyright (c) 2025 Elara AI Pty Ltd
- * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
- */
-/**
- * The stream and merge command builders (issue #770): the argv a stream
- * execution spawns for each merge mode and streamed-input choice, and the
- * argv a merge execution spawns over sorted partials within a key range.
- */
-import { describe, it } from 'node:test';
-import assert from 'node:assert/strict';
-import { variant } from '@elaraai/east';
-import { mergeCommandIr, streamCommandIr } from './stream.js';
-const EAST_C = variant('east_c', { platforms: ['east-c-std'] });
-/** The argv a stream command evaluates to for the staged `inputs`. */
-function argvOf(runner, spec, inputs) {
-    return streamCommandIr(runner, spec).compile([])(inputs, 'out.beast2');
-}
-/** The argv a merge command evaluates to for the staged `inputs`. */
-function mergeArgvOf(runner, mode, inputs) {
-    return mergeCommandIr(runner, mode).compile([])(inputs, 'out.beast2');
-}
-describe('streamCommandIr', () => {
-    it('builds a folding dict argv: the merge IR as --merge, the first input streamed', () => {
-        assert.deepEqual(argvOf(EAST_C, { emit: 'dict', merge: 'function', stream: 'first' }, ['body.beast2', 'merge.beast2', 'rows.beast2', 'other.beast2']), ['east-c', 'run', '-p', 'east-c-std', '--emit', 'dict', '--merge', 'merge.beast2', '--stream', '0',
-            '-i', 'rows.beast2', '-i', 'other.beast2', '-o', 'out.beast2', 'body.beast2']);
-    });
-    it('builds a union set argv streaming the first input', () => {
-        assert.deepEqual(argvOf(EAST_C, { emit: 'set', merge: 'union', stream: 'first' }, ['body.beast2', 'stream.beast2', 'other.beast2']), ['east-c', 'run', '-p', 'east-c-std', '--emit', 'set', '--union', '--stream', '0',
-            '-i', 'stream.beast2', '-i', 'other.beast2', '-o', 'out.beast2', 'body.beast2']);
-    });
-    it('builds a producer argv with no merge flag and no streamed input', () => {
-        assert.deepEqual(argvOf(EAST_C, { emit: 'array', merge: 'none', stream: 'none' }, ['body.beast2', 'config.beast2']), ['east-c', 'run', '-p', 'east-c-std', '--emit', 'array', '-i', 'config.beast2', '-o', 'out.beast2', 'body.beast2']);
-    });
-    it('starts from the runner argv of every stock runtime', () => {
-        const node = variant('east_node', { platforms: ['@elaraai/east-node-std'] });
-        const argv = argvOf(node, { emit: 'set', merge: 'none', stream: 'first' }, ['body.beast2', 'rows.beast2']);
-        assert.deepEqual(argv.slice(0, 6), ['east-node', 'run', '-p', '@elaraai/east-node-std', '--emit', 'set']);
-    });
-});
-describe('mergeCommandIr', () => {
-    it('builds a dict merge argv: the merge IR as --merge, the key range as --range, every other input a partial', () => {
-        assert.deepEqual(mergeArgvOf(EAST_C, 'function', ['merge.beast2', 'range.beast2', 'p0.beast2', 'p1.beast2', 'p2.beast2']), ['east-c', 'merge', '-p', 'east-c-std', '--merge', 'merge.beast2', '--range', 'range.beast2',
-            '-i', 'p0.beast2', '-i', 'p1.beast2', '-i', 'p2.beast2', '-o', 'out.beast2']);
-    });
-    it('builds a set union argv: the key range first, every other input a partial', () => {
-        assert.deepEqual(mergeArgvOf(EAST_C, 'union', ['range.beast2', 'p0.beast2', 'p1.beast2']), ['east-c', 'merge', '-p', 'east-c-std', '--union', '--range', 'range.beast2', '-i', 'p0.beast2', '-i', 'p1.beast2', '-o', 'out.beast2']);
-    });
-    it('runs the merge command of every stock runtime', () => {
-        const py = variant('east_py', { platforms: ['east-py-std'] });
-        assert.deepEqual(mergeArgvOf(py, 'union', ['range.beast2', 'p0.beast2']).slice(0, 4), ['east-py', 'merge', '-p', 'east-py-std']);
-        const node = variant('east_node', { platforms: [] });
-        assert.deepEqual(mergeArgvOf(node, 'function', ['merge.beast2', 'range.beast2', 'p0.beast2']).slice(0, 2), ['east-node', 'merge']);
-    });
-    it('refuses a custom runner, which has no merge command', () => {
-        const custom = variant('custom', { command: ['uv', 'run', 'east-py', 'run'] });
-        assert.throws(() => mergeCommandIr(custom, 'union'), { message: 'a custom runner has no merge command' });
-    });
-});
-//# sourceMappingURL=stream.spec.js.map