@elaraai/e3-types 1.0.76 → 1.0.78

package/src/index.ts

@@ -46,6 +46,7 @@ export {
   decodeTaskObject,
   TASK_KIND_PARTITION,
   TASK_KIND_STREAM,
+  TASK_KIND_MERGE,
   PartitionTaskMetadataType,
   type PartitionTaskMetadata,
   encodePartitionTaskMetadata,
@@ -54,8 +55,26 @@ export {
   type StreamTaskMetadata,
   encodeStreamTaskMetadata,
   decodeStreamTaskMetadata,
+  PartitionPlanType,
+  MergeRangePlanType,
+  type PartitionPlan,
+  type MergeRangePlan,
+  encodePartitionPlan,
+  decodePartitionPlan,
+  type ProjectionShape,
+  partitionProjectionShape,
+  projectedKeyType,
+  projectKey,
 } from './task.js';
 
+// Stream and merge commands
+export {
+  type StreamMergeMode,
+  type StreamCommandSpec,
+  streamCommandIr,
+  mergeCommandIr,
+} from './stream.js';
+
 // Execution environments
 export {
   EnvironmentSpecType,
@@ -101,6 +120,7 @@ export {
   type RunnerValue,
   runnerToArgv,
   withRunnerVerbose,
+  withRunnerLifeline,
 } from './runner.js';
 
 // Function objects
@@ -126,6 +146,8 @@ export {
   type PackageData,
   PackageObjectType,
   type PackageObject,
+  DatasetSourceWireType,
+  type DatasetSourceWire,
   decodePackageObject,
   // Backwards compatibility
   PackageDatasetsType,
@@ -161,6 +183,7 @@ export {
 export {
   ExecutionStatusType,
   type ExecutionStatus,
+  type ExecutionOwner,
 } from './execution.js';
 
 // Lock state
@@ -175,10 +198,15 @@ export {
 
 // Dataset transfer types
 export {
+  TRANSFER_PROTOCOL_VERSION,
+  transferPartCount,
+  transferPartRange,
   TransferUploadRequestType,
   type TransferUploadRequest,
   TransferUploadResponseType,
   type TransferUploadResponse,
+  TransferPartResponseType,
+  type TransferPartResponse,
   TransferDoneResponseType,
   type TransferDoneResponse,
 } from './transfer.js';
@@ -190,6 +218,14 @@ export {
   encodeDatasetBlob,
 } from './dataset-blob.js';
 
+// The ONE declared-type-vs-wire-type check, shared by every door a value
+// enters a dataset through (the export, the set, the adopt, the API)
+export {
+  checkDatasetType,
+  datasetAddress,
+  type DatasetTypeMismatch,
+} from './dataset-type.js';
+
 // Wire format constants
 export { BEAST2_CONTENT_TYPE } from './constants.js';
 
@@ -212,6 +248,7 @@ export {
   PermissionDeniedErrorType,
   InternalErrorType,
   RepositoryNotFoundErrorType,
+  DatasetTypeMismatchErrorType,
   ErrorType,
   ResponseType,
   // Repository

package/src/package.ts

@@ -72,6 +72,27 @@ export type PackageDatasets = PackageData;
  * };
  * ```
  */
+/**
+ * Where a dataset's initial value comes from, when it is not in the package.
+ *
+ * @remarks
+ * A package carries the DESCRIPTOR, never the bytes: `e3.input('table', T,
+ * variant('file', './TABLE.beast2'))` puts `{ file: { path } }` here and leaves
+ * the ref `unassigned`, and deploy resolves it — adopting the file into the
+ * object store by hash, so a new delivery under the same path is a new hash
+ * whose consumers re-run. An inline `variant('value', v)` needs no descriptor:
+ * its bytes are an object in the bundle like any other.
+ *
+ * A variant so that further source kinds can be appended later without a wire
+ * break; `file` is the only one today.
+ */
+export const DatasetSourceWireType = VariantType({
+  /** A path on the machine that DEPLOYS the package, resolved at deploy. */
+  file: StructType({ path: StringType }),
+});
+export type DatasetSourceWireType = typeof DatasetSourceWireType;
+export type DatasetSourceWire = ValueTypeOf<typeof DatasetSourceWireType>;
+
 export const PackageObjectType = StructType({
   /** Tasks defined in this package: name -> task object hash */
   tasks: DictType(StringType, StringType),
@@ -83,11 +104,26 @@ export const PackageObjectType = StructType({
    *  BEAST2 encodes struct fields positionally in declaration order, so new
    *  fields MUST be appended LAST — never inserted between existing fields. */
   records: DictType(StringType, StringType),
+  /** Unresolved dataset sources: refPath (e.g. "inputs/table") -> descriptor.
+   *  Appended LAST, per the positional rule above. */
+  sources: DictType(StringType, DatasetSourceWireType),
 });
 export type PackageObjectType = typeof PackageObjectType;
 
 export type PackageObject = ValueTypeOf<typeof PackageObjectType>;
 
+/**
+ * The pre-`sources` package object wire shape (tasks, data, functions,
+ * records), kept only so {@link decodePackageObject} can read packages exported
+ * before path-initialised inputs existed.
+ */
+const RecordsEraPackageObjectType = StructType({
+  tasks: DictType(StringType, StringType),
+  data: PackageDataType,
+  functions: DictType(StringType, StringType),
+  records: DictType(StringType, StringType),
+});
+
 /**
  * The pre-`records` package object wire shape (tasks, data, functions), kept
  * only so {@link decodePackageObject} can read packages exported before records
@@ -110,31 +146,37 @@ const LegacyPackageObjectType = StructType({
 });
 
 const decodeCurrent = decodeBeast2For(PackageObjectType);
+const decodeRecordsEra = decodeBeast2For(RecordsEraPackageObjectType);
 const decodeFunctionsEra = decodeBeast2For(FunctionsEraPackageObjectType);
 const decodeLegacy = decodeBeast2For(LegacyPackageObjectType);
 
 /**
- * Decode a `PackageObject` from BEAST2 bytes, tolerating the two older wire
+ * Decode a `PackageObject` from BEAST2 bytes, tolerating the older wire
  * formats (dual-decode migration).
  *
  * Every package-read path — local AND cloud — must use this instead of
  * `decodeBeast2For(PackageObjectType)` directly, so packages exported before
- * the `records`/`functions` fields existed keep decoding. Older bytes decode
- * with the missing maps defaulted to empty.
+ * the `sources`/`records`/`functions` fields existed keep decoding. Older
+ * bytes decode with the missing maps defaulted to empty.
  */
 export function decodePackageObject(data: Uint8Array): PackageObject {
   try {
     return decodeCurrent(data);
   } catch (err) {
     try {
-      const fnEra = decodeFunctionsEra(data);
-      return { tasks: fnEra.tasks, data: fnEra.data, functions: fnEra.functions, records: new Map() };
+      const recEra = decodeRecordsEra(data);
+      return { ...recEra, sources: new Map() };
     } catch {
       try {
-        const legacy = decodeLegacy(data);
-        return { tasks: legacy.tasks, data: legacy.data, functions: new Map(), records: new Map() };
+        const fnEra = decodeFunctionsEra(data);
+        return { tasks: fnEra.tasks, data: fnEra.data, functions: fnEra.functions, records: new Map(), sources: new Map() };
       } catch {
-        throw err; // no known shape — surface the current-format error
+        try {
+          const legacy = decodeLegacy(data);
+          return { tasks: legacy.tasks, data: legacy.data, functions: new Map(), records: new Map(), sources: new Map() };
+        } catch {
+          throw err; // no known shape — surface the current-format error
+        }
       }
     }
   }

package/src/runner.spec.ts

@@ -17,7 +17,7 @@
 import { describe, it } from 'node:test';
 import * as assert from 'node:assert';
 import { variant } from '@elaraai/east';
-import { runnerToArgv, withRunnerVerbose, type RunnerValue } from './runner.js';
+import { runnerToArgv, withRunnerLifeline, withRunnerVerbose, type RunnerValue } from './runner.js';
 
 /** A realistic fully-built argv: runner prefix + the `-i`/`-o`/`<ir>` suffix. */
 function fullArgv(runner: RunnerValue): string[] {
@@ -73,4 +73,59 @@ describe('withRunnerVerbose', () => {
     assert.deepStrictEqual(withRunnerVerbose(runner, ['east-node'], true), ['east-node']);
     assert.deepStrictEqual(withRunnerVerbose(runner, [], true), []);
   });
+
+  it('inserts -v after the merge subcommand too', () => {
+    const runner = variant('east_c', { platforms: ['east-c-std'] });
+    const args = [...runnerToArgv(runner, 'merge'), '--union', '-i', 'p0.beast2', '-o', 'out.beast2'];
+    assert.deepStrictEqual(withRunnerVerbose(runner, args, true).slice(0, 3), ['east-c', 'merge', '-v']);
+  });
+});
+
+describe('runnerToArgv', () => {
+  for (const [tag, runner, bin] of KNOWN) {
+    it(`resolves the run and merge commands of ${tag}`, () => {
+      assert.deepStrictEqual(runnerToArgv(runner).slice(0, 2), [bin, 'run']);
+      assert.deepStrictEqual(runnerToArgv(runner, 'run'), runnerToArgv(runner));
+      const merge = runnerToArgv(runner, 'merge');
+      assert.deepStrictEqual(merge.slice(0, 2), [bin, 'merge']);
+      // The platform flags follow either command unchanged.
+      assert.deepStrictEqual(merge.slice(2), runnerToArgv(runner).slice(2));
+    });
+  }
+
+  it('resolves a custom runner to its own command, and has no merge command for it', () => {
+    const runner: RunnerValue = variant('custom', { command: ['uv', 'run', 'east-py', 'run'] });
+    assert.deepStrictEqual(runnerToArgv(runner), ['uv', 'run', 'east-py', 'run']);
+    assert.throws(() => runnerToArgv(runner, 'merge'), { message: 'a custom runner has no merge command' });
+  });
+});
+
+describe('withRunnerLifeline', () => {
+  for (const [tag, runner, bin] of KNOWN) {
+    it(`inserts --exit-with-parent after the subcommand for ${tag}, on run and merge`, () => {
+      const args = fullArgv(runner);
+      const out = withRunnerLifeline(runner, args);
+      assert.deepStrictEqual(out.slice(0, 3), [bin, 'run', '--exit-with-parent']);
+      assert.deepStrictEqual(out.slice(3), args.slice(2));
+      const merge = [...runnerToArgv(runner, 'merge'), '--union', '-i', 'p0.beast2', '-o', 'out.beast2'];
+      assert.deepStrictEqual(withRunnerLifeline(runner, merge).slice(0, 3), [bin, 'merge', '--exit-with-parent']);
+      // Composed with -v, both sit ahead of the flags, in either order.
+      assert.deepStrictEqual(withRunnerVerbose(runner, withRunnerLifeline(runner, args), true).slice(0, 4), [bin, 'run', '-v', '--exit-with-parent']);
+    });
+  }
+
+  it('never splices the flag into a custom runner, which keeps an ignored stdin', () => {
+    const runner: RunnerValue = variant('custom', { command: ['uv', 'run', 'east-py', 'run'] });
+    const args = fullArgv(runner);
+    assert.deepStrictEqual(withRunnerLifeline(runner, args), args);
+  });
+
+  it('is a no-op on a degenerate argv and does not mutate its input', () => {
+    const runner = variant('east_c', { platforms: [] });
+    assert.deepStrictEqual(withRunnerLifeline(runner, ['east-c']), ['east-c']);
+    const args = fullArgv(runner);
+    const before = [...args];
+    withRunnerLifeline(runner, args);
+    assert.deepStrictEqual(args, before);
+  });
 });

package/src/runner.ts

@@ -45,19 +45,30 @@ function flags(platforms: string[]): string[] {
 }
 
 /**
- * Resolve a {@link RunnerType} value to the argv prefix (the wire-value
- * analogue of the SDK's `runnerToCommand`). Lives in e3-types so both
- * e3-core (local) and the cloud execution kernel import the one resolver.
+ * Resolve a {@link RunnerType} value to the argv prefix of one of its
+ * commands (the wire-value analogue of the SDK's `runnerToCommand`): `run`,
+ * the default — `[<bin>, 'run', -p…]` — or `merge`, the blob merge every
+ * stock runner ships — `[<bin>, 'merge', -p…]`, the fan-in of a partitioned
+ * task's keyed partials (issue #770). Lives in e3-types so both e3-core
+ * (local) and the cloud execution kernel import the one resolver.
  *
  * Variant tags use underscores (`east_node`) mapped to the binary name
- * (`east-node`) here.
+ * (`east-node`) here. A `custom` runner's command is its `run`; it has no
+ * merge command.
+ *
+ * @param r - the runner
+ * @param command - the runner command, `run` by default
+ * @returns the argv prefix
+ * @throws {Error} When `merge` is asked of a custom runner.
  */
-export function runnerToArgv(r: RunnerValue): string[] {
+export function runnerToArgv(r: RunnerValue, command: 'run' | 'merge' = 'run'): string[] {
   switch (r.type) {
-    case 'east_node': return ['east-node', 'run', ...flags(r.value.platforms)];
-    case 'east_py':   return ['east-py',   'run', ...flags(r.value.platforms)];
-    case 'east_c':    return ['east-c',    'run', ...flags(r.value.platforms)];
-    case 'custom':    return [...r.value.command];
+    case 'east_node': return ['east-node', command, ...flags(r.value.platforms)];
+    case 'east_py':   return ['east-py',   command, ...flags(r.value.platforms)];
+    case 'east_c':    return ['east-c',    command, ...flags(r.value.platforms)];
+    case 'custom':
+      if (command !== 'run') throw new Error(`a custom runner has no ${command} command`);
+      return [...r.value.command];
   }
 }
 
@@ -65,10 +76,10 @@ export function runnerToArgv(r: RunnerValue): string[] {
  * Insert the runner's `-v/--verbose` flag into a fully-built argv, for the
  * known runtimes only.
  *
- * All three known runners (`east-node`/`east-py`/`east-c run`) accept `-v`
- * among their options and print timing/perf detail to stderr; a `custom`
- * runner's argv is user-authored, so a flag is never spliced into it. A
- * known-runtime argv always starts `[<bin>, 'run', …]` (see
+ * All three known runners (`east-node`/`east-py`/`east-c`, `run` and `merge`)
+ * accept `-v` among their options and print timing/perf detail to stderr; a
+ * `custom` runner's argv is user-authored, so a flag is never spliced into
+ * it. A known-runtime argv always starts `[<bin>, <command>, …]` (see
  * {@link runnerToArgv} and the SDK's `runnerToCommand`), so `-v` goes at
  * index 2 — ahead of the `-p`/`-i`/`-o` flags and the trailing IR path.
  *
@@ -85,3 +96,24 @@ export function withRunnerVerbose(runner: RunnerValue, args: string[], verbose?:
   if (!verbose || runner.type === 'custom' || args.length < 2) return args;
   return [...args.slice(0, 2), '-v', ...args.slice(2)];
 }
+
+/**
+ * Insert the runner's `--exit-with-parent` flag into a fully-built argv, for
+ * the known runtimes only — the stdin lifeline (issue #770).
+ *
+ * A stock runner given the flag and a stdin pipe its parent never writes to
+ * exits as soon as the pipe reaches end of file: when the parent dies. A
+ * `custom` runner's argv is user-authored, so the flag is never spliced into
+ * it, and it keeps an ignored stdin. Like {@link withRunnerVerbose} the flag
+ * goes at index 2, after `[<bin>, <command>]`, and is a pure runtime toggle
+ * applied just before spawn — never part of the task's `commandIr` or any
+ * hash.
+ *
+ * @param runner - the runner the argv was built for (gates the injection)
+ * @param args - the fully-built argv
+ * @returns the argv, with `--exit-with-parent` inserted for known runtimes
+ */
+export function withRunnerLifeline(runner: RunnerValue, args: string[]): string[] {
+  if (runner.type === 'custom' || args.length < 2) return args;
+  return [...args.slice(0, 2), '--exit-with-parent', ...args.slice(2)];
+}

package/src/stream.spec.ts

@@ -0,0 +1,88 @@
+/**
+ * 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, type StreamCommandSpec } from './stream.js';
+import type { RunnerValue } from './runner.js';
+
+const EAST_C: RunnerValue = variant('east_c', { platforms: ['east-c-std'] });
+
+/** The argv a stream command evaluates to for the staged `inputs`. */
+function argvOf(runner: RunnerValue, spec: StreamCommandSpec, inputs: string[]): string[] {
+  return streamCommandIr(runner, spec).compile([])(inputs, 'out.beast2');
+}
+
+/** The argv a merge command evaluates to for the staged `inputs`. */
+function mergeArgvOf(runner: RunnerValue, mode: 'function' | 'union', inputs: string[]): string[] {
+  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: RunnerValue = 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: RunnerValue = 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: RunnerValue = 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: RunnerValue = variant('custom', { command: ['uv', 'run', 'east-py', 'run'] });
+    assert.throws(() => mergeCommandIr(custom, 'union'), { message: 'a custom runner has no merge command' });
+  });
+});

package/src/stream.ts

@@ -0,0 +1,170 @@
+/**
+ * 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, EastIR, StringType } from '@elaraai/east';
+import { runnerToArgv, 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 function streamCommandIr(runner: RunnerValue, spec: StreamCommandSpec): EastIR<[string[], string], string[]> {
+  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: RunnerValue, mode: 'function' | 'union'): EastIR<[string[], string], string[]> {
+  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();
+}