@elaraai/east-c-cli 1.0.76 → 1.0.78

package/README.md

@@ -37,21 +37,93 @@ The CLI loads the standard platform from `east-c-std` by default. Custom platfor
 
 A function whose trailing parameter is an emit capability writes its output
 incrementally instead of returning it; a large collection input can be fed
-lazily, one decoded segment at a time:
+lazily, one decoded segment at a time (`--stream` is repeatable):
 
 ```bash
 # Emit a Dict (or array / set) through the trailing parameter, feeding
-# input 0 lazily from an indexed beast2 blob
-east-c run task.beast2 -i rows.beast2 --stream 0 --emit dict -o out.beast2 -v
+# inputs 0 and 1 lazily from indexed beast2 blobs
+east-c run task.beast2 -i rows.beast2 -i more.beast2 --stream 0 --stream 1 \
+    --emit dict -o out.beast2 -v
 ```
 
-Dict and Set emissions may arrive in any order. While they ascend, segments
-stream straight to the output; on the first out-of-order key the sink
-encodes each further emission as it arrives, keeps only the key, and spills
-sorted runs of `EAST_EMIT_RUN_ELEMENTS` entries (default 100000) beside the
-output as raw byte records, merging them at the end by decoding keys only.
-With `-v` the epilogue reports the spills, the peak entries and bytes
-buffered, and the time spent spilling and merging.
+Dict and Set emissions must ascend in East order. The sink writes one pass,
+segment by segment, with one open batch in memory whatever the size of the
+output, and a key below the previous one is an error naming both:
+
+```text
+beast2 v5: Dict key emitted out of order: 1 after 2 — Set/Dict emissions must ascend in East order
+```
+
+Equal keys are an error too unless the sink folds them:
+
+```bash
+# Dict: fold the values of adjacent equal keys with an East function (K, V, V) -> V
+east-c run task.beast2 --emit dict --merge merge.beast2 -o out.beast2
+
+# Set: keep the first of adjacent equal elements
+east-c run task.beast2 --emit set --union -o out.beast2
+```
+
+`--merge` takes an IR file in any format the program itself may use, compiled
+with the run's `-p` platforms; its signature must match the emit parameter's
+key and value types. Adjacent equal keys fold left in emission order,
+`acc = merge(key, acc, value)`, and the output is byte-identical to what the
+sink writes without the flag for the already-folded sequence.
+
+### Merging blobs
+
+`merge` combines sorted Set or Dict blobs of one type — the files `run --emit`
+writes — into one, in a single pass over the inputs: every input is read
+segment by segment, equal keys across inputs fold in input order (`--merge`
+on Dict inputs, `--union` on Set inputs; without a fold an equal key is an
+error), and the output is byte-identical to what `run --emit` writes for the
+same entries emitted ascending. This is how e3 assembles a partitioned task's
+keyed partials; all three runners write the same bytes.
+
+```bash
+# Dict partials: fold the values of equal keys, in input order
+east-c merge --merge merge.beast2 -i part-0.beast2 -i part-1.beast2 -i part-2.beast2 -o out.beast2 -v
+
+# Set partials: the first of equal elements stands
+east-c merge --union -i part-0.beast2 -i part-1.beast2 -o out.beast2
+
+# Only the keys in [from, to): range.beast2 holds a Struct{from: Option<K>,
+# to: Option<K>} over the inputs' key type, an absent bound open
+east-c merge --merge merge.beast2 --range range.beast2 -i part-0.beast2 -i part-1.beast2 -o out.beast2
+```
+
+With `--range` 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 merge over one key
+range of large partials reads that range's share of each, plus at most one
+segment — how e3 merges a large output in parallel, one range per unit.
+
+An input of another type than the first, an Array input, an input whose keys
+do not ascend, a fold whose signature does not match the inputs, and bounds of
+another type than the inputs' key are refused, naming the input. With `-v` the
+merge prints its account:
+
+```text
+merge: 3 input(s), 31 entries, 13 fold(s)
+```
+
+### Exiting with the parent
+
+With `--exit-with-parent` on its command line (any command, anywhere among
+the arguments) the runner watches its stdin on a thread of its own and exits
+with status 1 as soon as a read returns end of file or fails. A parent that
+spawns the runner with a stdin pipe it never writes to — as e3 does — takes
+the runner down with it when it dies, even while the body is computing.
+Without the flag, stdin is left alone.
+
+```bash
+east-c run task.beast2 --exit-with-parent --emit dict -o out.beast2
+```
+
+On Windows the watcher reads a synchronous pipe or an overlapped one. Hand it
+an overlapped pipe — `FILE_FLAG_OVERLAPPED`, or Node's stdio `'overlapped'`,
+as e3 does: a read pending on a synchronous pipe holds the pipe's file-object
+lock, so any other use of stdin in the runner would wait until the parent is
+gone.
 
 ### Profiling
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elaraai/east-c-cli",
-  "version": "1.0.76",
+  "version": "1.0.78",
   "description": "Provides the `east-c` bin. A tiny launcher resolves the native binary for your platform from the matching per-platform package (@elaraai/east-c-cli-<target>), pulled in via optional dependencies.",
   "bin": {
     "east-c": "bin/east-c.mjs"
@@ -32,14 +32,14 @@
     "node": ">=18.0.0"
   },
   "devDependencies": {
-    "@elaraai/east": "1.0.76"
+    "@elaraai/east": "1.0.78"
   },
   "optionalDependencies": {
-    "@elaraai/east-c-cli-linux-x64": "1.0.76",
-    "@elaraai/east-c-cli-linux-arm64": "1.0.76",
-    "@elaraai/east-c-cli-darwin-arm64": "1.0.76",
-    "@elaraai/east-c-cli-darwin-x64": "1.0.76",
-    "@elaraai/east-c-cli-win32-x64": "1.0.76"
+    "@elaraai/east-c-cli-linux-x64": "1.0.78",
+    "@elaraai/east-c-cli-linux-arm64": "1.0.78",
+    "@elaraai/east-c-cli-darwin-arm64": "1.0.78",
+    "@elaraai/east-c-cli-darwin-x64": "1.0.78",
+    "@elaraai/east-c-cli-win32-x64": "1.0.78"
   },
   "scripts": {}
 }