@elaraai/east-node-cli 1.0.76 → 1.0.78

package/dist/emit-writer.js

@@ -0,0 +1,159 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * The segment writer behind `run --emit` and `merge` (issue #770).
+ *
+ * Entries arrive one at a time and go out as segments of a streaming beast2
+ * writer on the output file: header at open, terminator and index at the
+ * finish, so every finished file is a complete canonical blob. Batches are
+ * re-sized byte-adaptively toward the paged-encode segment target from what
+ * the writer has actually emitted — the refinement `encodeBeast2PagedFor`
+ * applies, so a file written here segments exactly as that encoder segments
+ * the same value. Both commands write through this one class, which is what
+ * makes a merge's output byte-identical to the sink's for the same entries.
+ * Memory is one open batch whatever the output's size.
+ */
+import { closeSync, openSync, writeSync } from 'fs';
+import { Beast2Writer, BEAST2_PAGED_BATCH_DEFAULT, BEAST2_PAGED_PROBE_BATCH, BEAST2_PAGED_TARGET_BYTES_DEFAULT } from '@elaraai/east';
+/** Writes all of `bytes` to `fd` — `writeSync` may write fewer bytes than
+ *  asked, and a silently short write would corrupt the file. */
+function writeAll(fd, bytes) {
+    let written = 0;
+    while (written < bytes.length) {
+        written += writeSync(fd, bytes, written, bytes.length - written);
+    }
+}
+/**
+ * A streaming, byte-adaptively batched writer of one canonical collection
+ * blob. Entries are elements (Array and Set) or `[key, value]` pairs (Dict).
+ */
+export class EmitFileWriter {
+    kind;
+    outType;
+    fd;
+    writer;
+    headerBytes = -1;
+    batch = [];
+    written = 0;
+    nextBatch = BEAST2_PAGED_BATCH_DEFAULT;
+    probed = false;
+    /**
+     * Opens `path` for writing and emits the blob's header.
+     *
+     * @param kind - the collection kind
+     * @param outType - the collection's wire type
+     * @param path - the output file
+     */
+    constructor(kind, outType, path) {
+        this.kind = kind;
+        this.outType = outType;
+        this.fd = openSync(path, 'w');
+        // Frames deflate on worker threads (#763); the refinement below reads
+        // the emitted bytes through the writer's bounds.
+        this.writer = new Beast2Writer(outType, (bytes) => {
+            writeAll(this.fd, bytes);
+            if (this.headerBytes < 0)
+                this.headerBytes = bytes.length;
+        }, { parallel: true });
+    }
+    /**
+     * Appends `entry` under the flush rule: a full batch goes out only now
+     * that an entry which will not fold into it has arrived, so the batch's
+     * last entry is always still open for a fold.
+     *
+     * @param entry - the element, or the `[key, value]` pair
+     */
+    push(entry) {
+        if (this.batch.length >= this.nextBatch)
+            this.flush();
+        this.batch.push(entry);
+        this.probe();
+    }
+    /**
+     * Seeds the batch size from a throwaway encode of the first entries, as
+     * `encodeBeast2PagedFor` does — the same probe, over the same count, so
+     * one value segments the same whether it was returned or emitted.
+     *
+     * Opening at the element cap instead made the first segment as many
+     * elements as the cap whatever they weighed: for rows above the target's
+     * share that is one oversized segment and every later boundary shifted,
+     * so the same Dict written both ways hashed differently. The probed
+     * entries are then drained through the refined size, exactly as the
+     * paged encoder pumps its own probe.
+     */
+    probe() {
+        if (this.probed || this.batch.length < BEAST2_PAGED_PROBE_BATCH)
+            return;
+        this.probed = true;
+        let scratchBytes = 0;
+        const scratch = new Beast2Writer(this.outType, (bytes) => { scratchBytes += bytes.length; });
+        const scratchHeader = scratchBytes;
+        scratch.write(this.toValue(this.batch));
+        const avg = Math.max(1, (scratchBytes - scratchHeader) / this.batch.length);
+        this.nextBatch = Math.max(1, Math.min(BEAST2_PAGED_BATCH_DEFAULT, Math.floor(BEAST2_PAGED_TARGET_BYTES_DEFAULT / avg)));
+        if (this.nextBatch >= this.batch.length)
+            return;
+        // Wider than one probe batch: the entries held so far go out in
+        // refined-size segments, which is what the paged encoder writes.
+        const buffered = this.batch;
+        this.batch = [];
+        for (const item of buffered) {
+            if (this.batch.length >= this.nextBatch)
+                this.flush();
+            this.batch.push(item);
+        }
+    }
+    /**
+     * Replaces the open batch's last entry — where an adjacent equal key's
+     * fold lands.
+     *
+     * @param update - maps the last entry to its folded form
+     */
+    foldLast(update) {
+        const at = this.batch.length - 1;
+        this.batch[at] = update(this.batch[at]);
+    }
+    /** Writes the open batch and finalizes the blob (terminator + index). */
+    finishClose() {
+        this.flush();
+        this.writer.finish();
+        closeSync(this.fd);
+    }
+    /** Closes the file without finalizing it — after an error, the partial
+     *  output carries no terminator or index. */
+    closeAbandoned() {
+        closeSync(this.fd);
+    }
+    flush() {
+        if (this.batch.length === 0)
+            return;
+        this.writer.write(this.toValue(this.batch));
+        this.written += this.batch.length;
+        this.batch = [];
+        this.nextBatch = this.refineNext();
+    }
+    toValue(items) {
+        return this.kind === 'dict' ? new Map(items) : this.kind === 'set' ? new Set(items) : items;
+    }
+    /** The batch size the paged encoder would choose after `bytes` of body
+     *  for `this.written` elements. */
+    refine(bytes) {
+        const avg = Math.max(1, Math.max(1, bytes - Math.max(0, this.headerBytes)) / this.written);
+        return Math.max(1, Math.min(BEAST2_PAGED_BATCH_DEFAULT, Math.floor(BEAST2_PAGED_TARGET_BYTES_DEFAULT / avg)));
+    }
+    /** The next batch size. With frames deflating on workers the bytes
+     *  written are only known within bounds; the refinement is monotone in
+     *  them, so agreeing bounds are the serial decision and disagreeing ones
+     *  wait for the frames — the segmentation never depends on timing. */
+    refineNext() {
+        const { lo, hi } = this.writer.emittedBounds();
+        const next = this.refine(lo);
+        if (next === this.refine(hi))
+            return next;
+        this.writer.settle();
+        return this.refine(this.writer.emittedBounds().lo);
+    }
+}
+//# sourceMappingURL=emit-writer.js.map

package/dist/emit-writer.js.map

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

package/dist/merge.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+import type { PlatformFunction } from '@elaraai/east/internal';
+/** Options accepted by {@link mergeBlobs}. */
+export interface MergeBlobsOptions {
+    /** Dict inputs: an IR file (any format the IR positional accepts) holding
+     *  a `(K, V, V) -> V` East function over the inputs' key and value types,
+     *  compiled with `platformFns`. Equal keys fold with it in input order. */
+    mergePath?: string;
+    /** Set inputs: the first of equal elements stands. */
+    union?: boolean;
+    /** A beast2 blob of `Struct{from: Option<K>, to: Option<K>}` over the
+     *  inputs' key type: only the keys in `[from, to)` merge; an absent
+     *  bound is open. */
+    rangePath?: string;
+    /** The platforms the merge function compiles with. */
+    platformFns?: PlatformFunction[];
+    /** Print the account and timing on stderr. */
+    verbose?: boolean;
+}
+/** What a merge came to. */
+export interface MergeBlobsStats {
+    /** Inputs merged. */
+    inputs: number;
+    /** Entries written to the output. */
+    entries: number;
+    /** Equal keys folded (merge) or collapsed (union). */
+    folds: number;
+}
+/**
+ * Merges sorted Set or Dict blobs of one type into one canonical blob — the
+ * `merge` command.
+ *
+ * @param inputPaths - the inputs, in the order equal keys fold; at least one
+ * @param outputPath - the output blob
+ * @param options - the fold, its platforms, the key range, verbosity
+ * @returns the account: inputs merged, entries written, keys folded
+ * @throws {Error} With the merge's message — an input of another type than
+ *   input 0's, an Array input, keys that do not ascend, a fold whose
+ *   signature does not match the inputs, a range blob of another shape than
+ *   the bounds over the inputs' key type, a file that cannot be opened, a
+ *   shared key without a fold — leaving the output unfinalised (no
+ *   terminator or index).
+ */
+export declare function mergeBlobs(inputPaths: readonly string[], outputPath: string, options?: MergeBlobsOptions): MergeBlobsStats;
+//# sourceMappingURL=merge.d.ts.map

package/dist/merge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../src/merge.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAmDH,OAAO,KAAK,EAAiB,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAK9E,8CAA8C;AAC9C,MAAM,WAAW,iBAAiB;IAC9B;;+EAE2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;yBAEqB;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,WAAW,CAAC,EAAE,gBAAgB,EAAE,CAAC;IACjC,8CAA8C;IAC9C,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,4BAA4B;AAC5B,MAAM,WAAW,eAAe;IAC5B,qBAAqB;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC;CACjB;AA0LD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,eAAe,CAoG9H"}

package/dist/merge.js

@@ -0,0 +1,342 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * The blob merge behind `east-node merge` (issue #770).
+ *
+ * Canonical Set or Dict blobs of one type in — sorted, indexed beast2 v5
+ * collections, as every runner writes them — and one canonical blob out, in
+ * a single pass: every input is read segment by segment through positioned
+ * reads on its descriptor, a heap over the inputs' current entries yields
+ * keys in East order, and the output is written through the same segment
+ * writer as `run --emit`, so the file is byte-identical to what that sink
+ * writes for the same entries emitted ascending. Memory is one decoded
+ * segment per input plus one open batch; no temporary file is ever written.
+ *
+ * Equal keys across inputs fold in input order: with a merge function (Dict
+ * inputs) `acc = merge(key, acc, value)`; in union mode (Set inputs) the
+ * first element stands. Without a fold, an equal key is the duplicate error
+ * the emit sink raises. An input whose keys do not ascend, an input whose
+ * type is not input 0's, and an Array input are refused.
+ *
+ * With a key range (`--range`, a blob of `Struct{from: Option<K>, to:
+ * Option<K>}` over the inputs' key type) only the keys in `[from, to)`
+ * merge: every input is sought to the segment owning `from` through its
+ * fences and read up to the first key at or past `to`, so a unit over a
+ * range of a large output reads that range's share of each input, plus at
+ * most one segment. An absent bound is open; both absent is the whole merge.
+ *
+ * This is the fan-in of a partitioned task's keyed partials: e3 runs it as an
+ * ordinary execution on the task's runner, one unit per key range of a group
+ * of partials, and never decodes a partial itself. east-c and east-py merge
+ * through the same contract, so the three runners write the same bytes.
+ */
+import { closeSync, fstatSync, openSync, readFileSync, readSync } from 'fs';
+import { OptionType, SortedMap, SortedSet, StructType, compareFor, decodeBeast2For, fromEastTypeValue, isTypeValueEqual, openBeast2LazyFor, printFor, readBeast2Extents, readBeast2HeaderType, readBeast2Type, toEastTypeValue, } from '@elaraai/east';
+import { printTypeValue } from '@elaraai/east/internal';
+import { EmitFileWriter } from './emit-writer.js';
+import { duplicateMessage, formatFileSize, loadMergeFunction } from './runner.js';
+/**
+ * Opens input `index` at `path`: reads its geometry and type, and prepares a
+ * segment-by-segment iteration of its entries — from the first key, or from
+ * a range's lower bound, whose owning segment the lazy value seeks through
+ * the fences.
+ *
+ * @param path - the blob
+ * @param index - the input's position, for messages
+ * @param expected - input 0's type, or `null` for input 0 itself
+ * @returns the opened input and its type
+ * @throws {Error} When the file cannot be opened (missing, unreadable, not
+ *   a regular file), is not a blob (too short, or without the magic — the
+ *   reader's own words), cannot be read as a canonical collection blob, or
+ *   its type is not `expected`.
+ */
+function openInput(path, index, expected) {
+    let fd;
+    let size;
+    try {
+        fd = openSync(path, 'r');
+    }
+    catch {
+        throw new Error(`merge: input ${index} (${path}): cannot open the file`);
+    }
+    try {
+        const stat = fstatSync(fd);
+        if (!stat.isFile())
+            throw new Error('not a regular file');
+        size = stat.size;
+    }
+    catch {
+        closeSync(fd);
+        throw new Error(`merge: input ${index} (${path}): cannot open the file`);
+    }
+    const reader = {
+        size,
+        read(offset, length) {
+            const out = new Uint8Array(length);
+            let done = 0;
+            while (done < length) {
+                const n = readSync(fd, out, done, length - done, offset + done);
+                if (n === 0)
+                    throw new Error(`beast2: short read at offset ${offset + done}`);
+                done += n;
+            }
+            return out;
+        },
+    };
+    const prefixed = (err) => new Error(`merge: input ${index} (${path}): ${err.message ?? String(err)}`);
+    let type;
+    let lazy;
+    try {
+        // The header first: a file too short for a blob, or one without the
+        // magic, is refused in the reader's words — the sentence east-c and
+        // east-py give for the same bytes — before the index is looked for.
+        readBeast2HeaderType(reader);
+        const extents = readBeast2Extents(reader);
+        type = extents.typeValue;
+        if (expected !== null && !isTypeValueEqual(type, expected)) {
+            closeSync(fd);
+            throw new Error(`merge: input ${index} (${path}) has type ${printTypeValue(type)}, expected ${printTypeValue(expected)} (input 0)`);
+        }
+        if (type.type !== 'Set' && type.type !== 'Dict') {
+            closeSync(fd);
+            throw new Error(`merge: inputs must be Set or Dict blobs, got ${type.type}`);
+        }
+        if (!extents.selfContained)
+            throw new Error('the blob is not self-contained');
+        lazy = openBeast2LazyFor(type, { frozen: true })(reader);
+    }
+    catch (err) {
+        const message = err.message ?? '';
+        if (message.startsWith('merge: '))
+            throw err;
+        closeSync(fd);
+        throw prefixed(err);
+    }
+    const dict = type.type === 'Dict';
+    return {
+        type,
+        close: () => closeSync(fd),
+        start: (range, cmp) => {
+            // The lazy value streams one decoded segment at a time, checking
+            // the ascent within and across segments as the eager decoder does;
+            // from a lower bound it starts at the segment owning it.
+            let iterator;
+            try {
+                iterator = dict
+                    ? lazy.entries(range.from)
+                    : lazy.keys(range.from);
+            }
+            catch (err) {
+                throw prefixed(err);
+            }
+            let exhausted = false;
+            const input = {
+                head: null,
+                advance: () => {
+                    if (exhausted)
+                        return;
+                    let next;
+                    try {
+                        next = iterator.next();
+                    }
+                    catch (err) {
+                        throw prefixed(err);
+                    }
+                    if (next.done) {
+                        exhausted = true;
+                        input.head = null;
+                        return;
+                    }
+                    const [key, value] = dict ? next.value : [next.value, undefined];
+                    // The first key at or past the upper bound ends the input.
+                    if (range.to !== undefined && cmp(key, range.to) >= 0) {
+                        exhausted = true;
+                        input.head = null;
+                        return;
+                    }
+                    input.head = { key, value };
+                },
+            };
+            return input;
+        },
+    };
+}
+/**
+ * Reads a `--range` blob: `Struct{from: Option<K>, to: Option<K>}` over the
+ * inputs' key type, self-describing, checked against that type.
+ *
+ * @param path - the blob
+ * @param keyType - the inputs' key (Dict) or element (Set) type
+ * @returns the bounds, an absent one `undefined`
+ * @throws {Error} When the file cannot be opened or read as a beast2 blob,
+ *   or its type is not the bounds struct over the inputs' key type.
+ */
+function readRange(path, keyType) {
+    let bytes;
+    try {
+        bytes = new Uint8Array(readFileSync(path));
+    }
+    catch {
+        throw new Error(`merge: --range (${path}): cannot open the file`);
+    }
+    // The same shape east-c builds (merge.c) and e3-core writes
+    // (partitionExec.ts): the bounds struct over the key type.
+    const key = fromEastTypeValue(keyType);
+    const rangeType = toEastTypeValue(StructType({ from: OptionType(key), to: OptionType(key) }));
+    let type;
+    try {
+        type = readBeast2Type(bytes);
+    }
+    catch (err) {
+        throw new Error(`merge: --range (${path}): ${err.message ?? String(err)}`);
+    }
+    if (!isTypeValueEqual(type, rangeType)) {
+        throw new Error(`merge: --range (${path}) has type ${printTypeValue(type)}, expected ${printTypeValue(rangeType)} (bounds over the inputs' key type)`);
+    }
+    let bounds;
+    try {
+        bounds = decodeBeast2For(rangeType)(bytes);
+    }
+    catch (err) {
+        throw new Error(`merge: --range (${path}): ${err.message ?? String(err)}`);
+    }
+    return {
+        from: bounds.from.type === 'some' ? bounds.from.value : undefined,
+        to: bounds.to.type === 'some' ? bounds.to.value : undefined,
+    };
+}
+/**
+ * Merges sorted Set or Dict blobs of one type into one canonical blob — the
+ * `merge` command.
+ *
+ * @param inputPaths - the inputs, in the order equal keys fold; at least one
+ * @param outputPath - the output blob
+ * @param options - the fold, its platforms, the key range, verbosity
+ * @returns the account: inputs merged, entries written, keys folded
+ * @throws {Error} With the merge's message — an input of another type than
+ *   input 0's, an Array input, keys that do not ascend, a fold whose
+ *   signature does not match the inputs, a range blob of another shape than
+ *   the bounds over the inputs' key type, a file that cannot be opened, a
+ *   shared key without a fold — leaving the output unfinalised (no
+ *   terminator or index).
+ */
+export function mergeBlobs(inputPaths, outputPath, options = {}) {
+    const started = performance.now();
+    if (inputPaths.length === 0)
+        throw new Error('merge: at least one input is needed');
+    if (options.mergePath !== undefined && options.union) {
+        throw new Error('merge: --merge and --union are two folds — give one');
+    }
+    const opened = [];
+    const inputs = [];
+    let out = null;
+    let finished = false;
+    try {
+        const first = openInput(inputPaths[0], 0, null);
+        opened.push(first);
+        const type = first.type;
+        const kind = type.type === 'Dict' ? 'dict' : 'set';
+        if (options.mergePath !== undefined && kind !== 'dict')
+            throw new Error('--merge applies to Dict inputs only');
+        if (options.union && kind !== 'set')
+            throw new Error('--union applies to Set inputs only');
+        const keyType = (kind === 'dict' ? type.value.key : type.value);
+        const valueType = (kind === 'dict' ? type.value.value : null);
+        const merge = options.mergePath !== undefined
+            ? loadMergeFunction(options.mergePath, keyType, valueType, options.platformFns ?? [], 'the inputs')
+            : null;
+        const union = options.union ?? false;
+        const range = options.rangePath !== undefined ? readRange(options.rangePath, keyType) : { from: undefined, to: undefined };
+        for (let i = 1; i < inputPaths.length; i++)
+            opened.push(openInput(inputPaths[i], i, type));
+        const cmp = compareFor(keyType);
+        const printKey = printFor(keyType);
+        for (const input of opened)
+            inputs.push(input.start(range, cmp));
+        for (const input of inputs)
+            input.advance();
+        // A binary min-heap over the inputs' current keys, ordered by (key,
+        // input index), so equal keys leave in input order.
+        const heap = [];
+        for (let i = 0; i < inputs.length; i++)
+            if (inputs[i].head !== null)
+                heap.push(i);
+        const before = (a, b) => {
+            const order = cmp(inputs[a].head.key, inputs[b].head.key);
+            return order < 0 || (order === 0 && a < b);
+        };
+        const siftDown = (at) => {
+            for (;;) {
+                const l = 2 * at + 1;
+                const r = l + 1;
+                let least = at;
+                if (l < heap.length && before(heap[l], heap[least]))
+                    least = l;
+                if (r < heap.length && before(heap[r], heap[least]))
+                    least = r;
+                if (least === at)
+                    return;
+                [heap[at], heap[least]] = [heap[least], heap[at]];
+                at = least;
+            }
+        };
+        for (let i = (heap.length >> 1) - 1; i >= 0; i--)
+            siftDown(i);
+        out = new EmitFileWriter(kind, type, outputPath);
+        let entries = 0;
+        let folds = 0;
+        // The current key's entry is held until a greater key arrives, so
+        // every equal key folds into it before it is written.
+        let held = null;
+        const put = (entry) => {
+            out.push(kind === 'dict' ? [entry.key, entry.value] : entry.key);
+            entries++;
+        };
+        while (heap.length > 0) {
+            const input = inputs[heap[0]];
+            const { key, value } = input.head;
+            if (held !== null && cmp(held.key, key) === 0) {
+                if (merge !== null) {
+                    held.value = merge(key, held.value, value);
+                }
+                else if (!union) {
+                    throw new Error(duplicateMessage(kind, printKey, key));
+                }
+                folds++;
+            }
+            else {
+                if (held !== null)
+                    put(held);
+                held = { key, value };
+            }
+            input.advance();
+            if (input.head === null) {
+                heap[0] = heap[heap.length - 1];
+                heap.pop();
+            }
+            if (heap.length > 0)
+                siftDown(0);
+        }
+        if (held !== null)
+            put(held);
+        out.finishClose();
+        finished = true;
+        const stats = { inputs: inputs.length, entries, folds };
+        if (options.verbose) {
+            console.error(`merge: ${stats.inputs} input(s), ${stats.entries} entries, ${stats.folds} fold(s)`);
+            console.error(`Output: ${outputPath}  (${formatFileSize(outputPath)})`);
+            console.error('\nTiming:');
+            console.error(`  Total:    ${(performance.now() - started).toFixed(1).padStart(8)} ms`);
+        }
+        return stats;
+    }
+    finally {
+        for (const input of opened)
+            input.close();
+        if (out !== null && !finished)
+            out.closeAbandoned();
+    }
+}
+//# sourceMappingURL=merge.js.map

package/dist/merge.js.map

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

package/dist/runner.d.ts

@@ -2,8 +2,22 @@
  * Copyright (c) 2025 Elara AI Pty Ltd
  * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
  */
-import type { PlatformFunction } from '@elaraai/east/internal';
+import type { PlatformFunction, EastTypeValue } from '@elaraai/east/internal';
+/** A file's size for the verbose account, or `?` when it cannot be read. @internal */
+export declare function formatFileSize(path: string): string;
 /** Streaming-execution options accepted by {@link runProgram}. */
+/**
+ * A refusal of the command line itself — a flag combination, an output
+ * destination, a function shape the flags do not fit.
+ *
+ * These are the user's errors, not the program's, and east-c and east-py
+ * answer them with one sentence on stderr. Marking them lets the CLI do the
+ * same instead of printing the JS stack it prints for an error thrown from
+ * East or from a platform function, where the frames are the diagnosis.
+ */
+export declare class UsageError extends Error {
+    constructor(message: string);
+}
 export interface RunProgramOptions {
     /** Enable verbose timing/memory output on stderr. */
     verbose?: boolean;
@@ -12,11 +26,19 @@ export interface RunProgramOptions {
      *  collection kind; element/key/value types come from the emit
      *  parameter's function type. */
     emit?: 'array' | 'set' | 'dict';
-    /** Feed the given `-i` input (0-based) lazily — segment-by-segment
+    /** Feed these `-i` inputs (0-based) lazily — segment-by-segment
      *  iteration with O(segment) decoded memory — regardless of size.
      *  Element shapes the lazy contract excludes (nested mutable
      *  containers, vectors/matrices, functions) decode whole instead. */
-    streamInput?: number;
+    streamInputs?: number[];
+    /** With `emit: 'dict'`: an IR file (any format the IR positional
+     *  accepts) holding a `(K, V, V) -> V` East function over the emit
+     *  parameter's key and value types, compiled with the run's platforms.
+     *  Adjacent emissions with an equal key fold left with it, in emission
+     *  order. */
+    merge?: string;
+    /** With `emit: 'set'`: adjacent equal elements collapse to the first. */
+    union?: boolean;
     /** Open indexed beast2 collection inputs at or above this many bytes as
      *  lazy pager-backed values (0 disables). Defaults to 64 MiB, or the
      *  `EAST_LAZY_INPUT_BYTES` environment variable. Applies only to
@@ -34,4 +56,32 @@ export declare function lazyThreshold(options: RunProgramOptions): number;
  * Runs an East IR program.
  */
 export declare function runProgram(irPath: string, platformFns: PlatformFunction[], packages: string[], inputPaths: string[], outputPath?: string, options?: RunProgramOptions | boolean): Promise<unknown>;
+/** A compiled `(K, V, V) -> V` fold of equal keys. */
+export type MergeFunction = (key: unknown, acc: unknown, value: unknown) => unknown;
+/**
+ * Loads a `--merge` function: an IR file holding a `(K, V, V) -> V` East
+ * function over the given key and value types, compiled with the run's
+ * platforms. Shared by the emit sink and the blob merge.
+ *
+ * @param path - the IR file (any format the IR positional accepts)
+ * @param keyType - the key type
+ * @param valueType - the value type
+ * @param platformFns - the run's platforms
+ * @param subject - what the function must match, for the message: `the emit
+ *   parameter` or `the inputs`
+ * @returns the compiled merge function
+ * @throws {Error} When the IR is not a function of that shape, naming the
+ *   expected and the actual types.
+ */
+export declare function loadMergeFunction(path: string, keyType: EastTypeValue, valueType: EastTypeValue, platformFns: PlatformFunction[], subject: string): MergeFunction;
+/**
+ * The canonical duplicate-key error, identical across runners: the emit
+ * sink's, and the blob merge's when a key is shared without a fold.
+ *
+ * @param kind - the collection kind
+ * @param printKey - the key type's printer
+ * @param key - the repeated key
+ * @returns the message
+ */
+export declare function duplicateMessage(kind: 'set' | 'dict', printKey: (v: unknown) => string, key: unknown): string;
 //# sourceMappingURL=runner.d.ts.map