feat(cli): promote Zig as canonical executable

Author: pmarreck

.dirtree-state

@@ -5,6 +5,7 @@ annotate=[
 	MEMORIES/WASM benchmarks must stream inputs and APE needs a clean environment = WASI and Cosmopolitan runtime requirements for benchmark adapters.
 	PLAN.md = Active project plan; records measured Zig codec performance wins, a rejected scalar ASCII experiment, and remaining API-design questions.
 	bm/benchmark-zig-opt = Benchmarks all available CLI variants, including Rust stdin, WASM, and APE adapters.
+	build_all = Builds the current-platform C, Zig, WASM, and Linux APE distributions through the canonical build script.
 	docs/plans/2026-06-26-printable-binary-file-container-design.md = Design spec: printable-binary-file.json container + web decode workflow (issue #1)
 	elixir/lib/printable_binary.ex = Elixir ~PB compile-time sigil: decodes printable-binary glyphs to raw bytes at compile time (reads character_map.txt via @external_resource); decode/1 runtime helper (whitespace-tolerant)
 	elixir/mix.exs = Mix project for the ~PB sigil demo (no deps)
@@ -15,8 +16,11 @@ annotate=[
 	rust/src/main.rs = Minimal Rust CLI (encode default, -d decode; stdin->stdout) for cross-impl verification
 	src/container_json.h = Shared pure transport-resistant flat-JSON helpers for the .pbf.json container (C FFI + standalone C)
 	src/zig/ffi.zig = C ABI (FFI) export surface: all 12 pb_* C functions; root of libprintable_binary.a; keeps C symbols OUT of the importable printable_binary module so static (musl) consumers don't collide
+	src/zig/main.zig = Zig canonical CLI adapter with input-throughput status reporting and compact-map codec integration.
 	src/zig/printable_binary.zig = Pure Zig codec core; default encode/decode use a portable 16-byte SIMD literal-prefix gate, padded encode slots, and compact direct UTF-8 decode tables.
 	test/module_consumer.zig = Test fixture: minimal downstream importer of the printable_binary Zig module (mirrors how difz/blip consume it) for the FFI-symbol-leak test
+	test/test_build_all = Hermetic delegation test proving build_all invokes the complete build target.
+	test/test_cli_layout = Nix-backed behavioral test for canonical Zig and retained LuaJIT executable names.
 	test/test_container = Container (.pbf.json) CLI round-trip + self-verify test, parameterized by IMPLEMENTATION_TO_TEST (issue #1)
 	test/test_container_cross = Cross-impl container differential: impl-A container decodes via impl-B (MFIC, issue #1)
 	test/test_docs_benchmark_contract = Guards implementation docs, mapping labels, benchmark inventory, and Mechatron CI manifest/badge contract.

.mechatron-prime/targets

@@ -9,13 +9,16 @@ checks.x86_64-linux.test-container-ffi
 checks.x86_64-linux.test-container-lua
 checks.x86_64-linux.test-container-node
 checks.x86_64-linux.test-container-zig
+checks.x86_64-linux.test-build-all
+checks.x86_64-linux.test-cli-layout
 checks.x86_64-linux.test-docs-benchmark-contract
 checks.x86_64-linux.test-elixir
 checks.x86_64-linux.test-embedded-map-sync
 checks.x86_64-linux.test-ffi-cli
 checks.x86_64-linux.test-js
 checks.x86_64-linux.test-js-unit
 checks.x86_64-linux.test-leak
+checks.x86_64-linux.test-lua
 checks.x86_64-linux.test-no-ffi-symbols
 checks.x86_64-linux.test-rust
 checks.x86_64-linux.test-zig

FUTURE_WORK.md

@@ -1,6 +1,8 @@
 # Future Work / Proposed Ideas
 
-- CLI wrapper resilience: add a smoke test so `bin/printable-binary` errors clearly when neither LuaJIT nor a WASM runner is available.
+- [x] Canonical CLI migration: `test/test_cli_layout` verifies that the Zig
+  executable installs as `printable-binary`, LuaJIT remains explicitly available
+  as `printable-binary-luajit`, and Linux `build_all` includes APE.
 - JS/Node perf: cache the parsed `character_map` inside `js/printable_binary.js` to avoid repeated fs reads in tight loops.
 - Map override parity: allow `PRINTABLE_BINARY_MAP` in the WASM test harness, mirroring Node/Deno behavior.
 - CI ergonomics: run `test_all` per implementation (LuaJIT, C, APE, Node) in parallel to shorten logs and isolate failures.

Makefile

@@ -26,7 +26,7 @@ STRIP ?= strip
 
 # Zig build outputs
 ZIG_LIB = zig-out/lib/libprintable_binary.a
-ZIG_CLI = zig-out/bin/printable-binary-zig
+ZIG_CLI = zig-out/bin/printable-binary
 
 COSMOCC_VERSION ?= 4.0.2
 COSMOCC_URL ?= https://cosmo.zip/pub/cosmocc/cosmocc-$(COSMOCC_VERSION).zip
@@ -379,7 +379,7 @@ benchmark: $(TARGET)
 # Compare with LuaJIT version
 .PHONY: compare
 compare: $(TARGET)
-	@if [ ! -f bin/printable-binary ]; then \
+	@if [ ! -f bin/printable-binary-luajit ]; then \
 		echo "Error: LuaJIT version not found"; \
 		exit 1; \
 	fi
@@ -392,13 +392,13 @@ compare: $(TARGET)
 	@time $(BIN_DIR)/$(TARGET) compare_test.bin > compare_c_encoded.tmp 2>/dev/null
 	@echo
 	@echo "LuaJIT version encoding:"
-	@time ./bin/printable-binary compare_test.bin > compare_lua_encoded.tmp 2>/dev/null
+	@time ./bin/printable-binary-luajit compare_test.bin > compare_lua_encoded.tmp 2>/dev/null
 	@echo
 	@echo "C version decoding:"
 	@time $(BIN_DIR)/$(TARGET) -d compare_c_encoded.tmp > compare_c_decoded.tmp 2>/dev/null
 	@echo
 	@echo "LuaJIT version decoding:"
-	@time ./bin/printable-binary -d compare_lua_encoded.tmp > compare_lua_decoded.tmp 2>/dev/null
+	@time ./bin/printable-binary-luajit -d compare_lua_encoded.tmp > compare_lua_decoded.tmp 2>/dev/null
 	@echo
 	@echo "Verifying output compatibility:"
 	@if cmp compare_c_encoded.tmp compare_lua_encoded.tmp; then \
@@ -422,13 +422,13 @@ hyperfine: $(TARGET)
 		echo "Running hyperfine benchmark..."; \
 		hyperfine --warmup 3 \
 			"$(BIN_DIR)/$(TARGET) hyperfine_test.bin" \
-		"./bin/printable-binary hyperfine_test.bin" \
+		"./bin/printable-binary-luajit hyperfine_test.bin" \
 			--export-markdown benchmark_results.md; \
 		echo "Encode benchmark results saved to benchmark_results.md"; \
 		$(BIN_DIR)/$(TARGET) hyperfine_test.bin > hyperfine_encoded.tmp 2>/dev/null; \
 		hyperfine --warmup 3 \
 			"$(BIN_DIR)/$(TARGET) -d hyperfine_encoded.tmp" \
-		"./bin/printable-binary -d hyperfine_encoded.tmp" \
+		"./bin/printable-binary-luajit -d hyperfine_encoded.tmp" \
 			--export-markdown decode_benchmark_results.md;
 		echo "Decode benchmark results saved to decode_benchmark_results.md"; \
 		rm -f hyperfine_test.bin hyperfine_encoded.tmp; \

PLAN.md

@@ -20,6 +20,23 @@ maintained_by: agent
       build. Pushed as `1281b38`; Mechatron reported `PASSING` on
       2026-07-22 10:28 PM EDT.
 
+## Canonical Zig CLI migration — active (2026-07-24 EDT)
+
+- [x] Make the compiled Zig CLI the `printable-binary` installation and PATH
+      name; retain the legacy LuaJIT CLI as `printable-binary-luajit`.
+      Curiosity poke: package, development, benchmark, documentation, and
+      direct-script entry points must all select the same implementation while
+      both CLIs remain independently usable. Nix package/install, local `bin/`,
+      benchmark discovery, docs, and `test-cli-layout` now agree; `./build_all`
+      builds Linux C, Zig, WASM, and APE outputs. (2026-07-24 02:49 PM EDT)
+- [x] Add a common stderr processed-input throughput line to every CLI
+      implementation. Curiosity poke: rate must use elapsed wall time and
+      input bytes (the stable denominator across encode/decode), must not
+      pollute stdout, and must remain finite for tiny inputs. Every CLI now
+      emits `Input throughput: … MB read … (… MB/s)` with decimal MB and MB/s
+      rounded to two places; tests cover encode/decode where supported.
+      (2026-07-24 02:49 PM EDT)
+
 ## Deferred performance investigation
 
 - [x] Baseline the deterministic 10 MB mixed-byte core benchmark against Rust,
@@ -202,7 +219,7 @@ ALL-EXECUTABLES STATUS (Peter's ask):
 - [ ] Zig CLI (src/zig/main.zig) — core has crc32; use std.json for the envelope.
 - [ ] C FFI CLI (src/printable_binary_ffi_main.c) — pb_crc32 + hand-rolled flat JSON.
 - [ ] C standalone (src/printable_binary.c) — own crc32 + hand-rolled flat JSON.
-- [ ] Lua (bin/printable-binary) — own crc32 + Lua JSON.
+- [ ] Lua (bin/printable-binary-luajit) — own crc32 + Lua JSON.
 PATTERN for each: add `-C` (encode→container, `-d -C` decode→restore+self-verify),
 crc32 VECTOR-PINNED to CRC32("123456789")=0xCBF43926 (so all impls agree), then add
 a test-container-<impl> flake check running test/test_container against it. Once ≥2

README.md

@@ -91,18 +91,21 @@ The optional PGO path (`make pgo-ffi`) adds a further ~1–3% via profile-guided
 
 ```bash
 # Use any implementation:
-# LuaJIT version:     ./bin/printable-binary
+# Zig CLI (default):  ./build zig && ./bin/printable-binary
+# LuaJIT CLI:         ./bin/printable-binary-luajit
 # Node.js CLI:         ./bin/printable-binary-node.js
 # C version:           ./build native && ./bin/printable-binary-c
 # APE version:         ./build ape && ./bin/printable-binary-ape.com
-# Zig version:         ./build zig && ./bin/printable-binary-zig
 # WASM version:        ./build wasm && wazero run bin/printable-binary.wasm < input.bin
 # Rust raw codec:      cargo build --release --manifest-path rust/Cargo.toml
 #                     < input.bin rust/target/release/printable-binary-rs
-# (Examples below use the LuaJIT full CLI. Rust intentionally offers only
+# (Examples below use the canonical Zig full CLI. Rust intentionally offers only
 # stdin→stdout encoding and -d/--decode; the other listed CLI variants share
 # the full option surface.)
 
+# Build every compiled distribution on Linux (C, Zig, WASM, and APE).
+./build_all
+
 # Encode binary data
 echo -n "Hello, World!" | ./bin/printable-binary
 # Output: Hello,␣World﹗
@@ -154,6 +157,16 @@ echo -n "Hello, World!" | ./bin/printable-binary --passthrough 2>encoded.txt | w
 ./bin/printable-binary-c large_file.bin > encoded_large.txt
 ```
 
+Every CLI writes a final stderr line for informal comparisons:
+
+```text
+Input throughput: 4999.36 MB read in 49.939 s (100.11 MB/s)
+```
+
+`MB` means decimal input megabytes (1,000,000 bytes). The rate uses bytes read,
+not the larger encoded result, and covers input read, codec work, and output
+write. Set `PRINTABLE_BINARY_MUTE_STATS=1` to suppress it.
+
 ### Web Interface
 
 - Live demo: <https://pmarreck.github.io/printable_binary/>

README_IMPLEMENTATIONS.md

@@ -24,7 +24,7 @@ PrintableBinary is available in multiple high-performance implementations:
 - **Full CLI parity**: Same arguments and mapping behavior as the native C binary
 - **Measured honestly**: The benchmark includes wazero startup and runtime overhead
 
-### 🦎 **Zig Implementation** (Modern, Memory-Safe)
+### 🦎 **Zig Implementation** (Canonical CLI)
 - **Memory-safe**: Zig's safety features catch bugs at compile time and runtime
 - **Cross-compilation**: Easy cross-compilation to many platforms from a single host
 - **Fast compilation**: Incremental builds and fast compile times
@@ -41,7 +41,7 @@ PrintableBinary is available in multiple high-performance implementations:
 - **Portable runtime**: Runs in browsers, Node.js, and compatible bundlers
 - **CLI parity**: Node exposes the full user-facing command surface
 
-### ⚡ **LuaJIT Implementation** (Original)
+### ⚡ **LuaJIT Implementation** (Explicit Legacy CLI)
 - **Reference implementation**: Easy to modify and extend
 - **Well-tested**: Extensive test suite and battle-tested
 - **Development-friendly**: Rapid prototyping and debugging
@@ -115,11 +115,11 @@ WASM has the C CLI's feature set. The runtime does not automatically inherit hos
 ```bash
 # Build with Nix
 nix build .#printableBinaryZig
-./result-zig/bin/printable-binary-zig file.bin
+./result-zig/bin/printable-binary file.bin
 
 # Or build directly with Zig
 zig build -Doptimize=ReleaseFast
-./zig-out/bin/printable-binary-zig file.bin
+./zig-out/bin/printable-binary file.bin
 ```
 
 ### Rust Implementation
@@ -141,8 +141,8 @@ Use Rust as an embedded codec or a Rust↔Zig transport boundary. Its CLI curren
 
 ```bash
 # Already optimized and ready to use
-./bin/printable-binary file.bin
-./bin/printable-binary -d encoded_file.txt
+./bin/printable-binary-luajit file.bin
+./bin/printable-binary-luajit -d encoded_file.txt
 ```
 
 ## Installation Options
@@ -490,7 +490,7 @@ dd if=/dev/urandom of=test.bin bs=1M count=1
 
 # Binary compatibility test
 ./bin/printable-binary-c test.bin > c_output.txt
-./bin/printable-binary test.bin > lua_output.txt
+./bin/printable-binary-luajit test.bin > lua_output.txt
 cmp c_output.txt lua_output.txt && echo "✓ Outputs identical"
 ```
 

bin/printable-binary bin/printable-binary-luajitbin/printable-binary renamed to bin/printable-binary-luajit

@@ -699,6 +699,34 @@ if arg then
     end
   end
 
+  -- Use a wall clock for CLI pipeline timing; fall back to Lua CPU time on a
+  -- non-POSIX LuaJIT host where gettimeofday is unavailable.
+  local now_seconds = os.clock
+  if ffi.os ~= "Windows" then
+    local cdef_ok = pcall(ffi.cdef, [[
+      struct timeval { long tv_sec; long tv_usec; };
+      int gettimeofday(struct timeval *tv, void *tz);
+    ]])
+    if cdef_ok then
+      local tv = ffi.new("struct timeval[1]")
+      now_seconds = function()
+        if ffi.C.gettimeofday(tv, nil) == 0 then
+          return tonumber(tv[0].tv_sec) + tonumber(tv[0].tv_usec) / 1000000
+        end
+        return os.clock()
+      end
+    end
+  end
+
+  local function report_input_throughput(input_bytes_read, started_at)
+    local elapsed = math.max(now_seconds() - started_at, 0.0005)
+    local megabytes = input_bytes_read / 1000000
+    stats_write(string.format(
+      "Input throughput: %.2f MB read in %.3f s (%.2f MB/s)\n",
+      megabytes, elapsed, megabytes / elapsed
+    ))
+  end
+
   -- Main program
   if #arg == 0 then
     -- Check if stdin is a terminal
@@ -987,13 +1015,17 @@ if arg then
     os.exit(0)
   end
 
+  -- Measure the user-visible pipeline: input read, codec work, and output write.
+  local throughput_started_at = now_seconds()
+
   -- Read input data
   local input_data
   if file_path then
     input_data = read_file(file_path)
   else
     input_data = read_stdin()
   end
+  local input_bytes_read = #input_data
 
   -- Apply byte range if specified
   if range_start ~= nil or range_end ~= nil then
@@ -1076,6 +1108,7 @@ if arg then
         os.exit(1)
       end
       io.write(decoded)
+      report_input_throughput(input_bytes_read, throughput_started_at)
       os.exit(0)
     else
       local data = PrintableBinary.encode(input_data, { spaces = spaces_mode })
@@ -1088,6 +1121,7 @@ if arg then
         .. json_escape(fname) .. '",\n  "byte_length": ' .. #input_data
         .. ',\n  "crc32": "' .. crc_orig .. '",\n  "crc32_encoded": "' .. crc_enc
         .. '",\n  "data": "' .. data .. '"\n}\n')
+      report_input_throughput(input_bytes_read, throughput_started_at)
       os.exit(0)
     end
   end
@@ -1258,6 +1292,8 @@ if arg then
     -- Normal encode mode, send output to stdout
     io.write(output)
   end
+
+  report_input_throughput(input_bytes_read, throughput_started_at)
 end
 
 return PrintableBinary