build(zig): default to ReleaseFast; add in-process codec benchmarks

build.zig now defaults optimize to ReleaseFast (was standardOptimizeOption =
Debug default) per the project convention, still overridable via -Doptimize.
Adds an in-process codec micro-benchmark to isolate codec speed from CLI stdio
I/O (the existing test/benchmark_test is bin-level): Zig CLI gains a hidden
--bench (0.16 Io monotonic clock); Rust gets rust/examples/bench.rs. Measured
codecs: encode tied (~485 MB/s both); Rust decode ~785 vs Zig ~349 MB/s.

Author: pmarreck

.dirtree-state

@@ -4,6 +4,7 @@ annotate=[
 	PLAN.md = Issue #1 plan: decode workflow + printable-binary-file.json container
 	docs/plans/2026-06-26-printable-binary-file-container-design.md = Design spec: printable-binary-file.json container + web decode workflow (issue #1)
 	rust/build.rs = Codegens byte<->glyph map + O(1) decode tables from character_map.txt (single source)
+	rust/examples/bench.rs = In-process Rust codec throughput bench (isolates codec from CLI I/O)
 	rust/src/lib.rs = Rust printable-binary core: raw encode/decode + zero-alloc *_into (byte-identical to Zig, ~1.8x faster)
 	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)

build.zig

@@ -2,7 +2,7 @@ const std = @import("std");
 
 pub fn build(b: *std.Build) void {
     const target = b.standardTargetOptions(.{});
-    const optimize = b.standardOptimizeOption(.{});
+    const optimize = b.option(std.builtin.OptimizeMode, "optimize", "Optimization mode (default: ReleaseFast)") orelse .ReleaseFast;
 
     // =========================================================================
     // Core Library Module (for use by other Zig packages)

rust/examples/bench.rs

@@ -0,0 +1,34 @@
+// Pure in-process codec throughput (no stdin/stdout I/O), to compare against the
+// Zig core's codec — isolating codec speed from CLI I/O buffering.
+use printable_binary::{decode, decode_into, encode, encode_into};
+use std::time::Instant;
+
+fn main() {
+    let n: usize = 10_000_000;
+    // deterministic pseudo-random bytes
+    let data: Vec<u8> = (0..n).map(|i| (i.wrapping_mul(2654435761)) as u8).collect();
+    let mut ebuf = Vec::new();
+    let mut dbuf = Vec::new();
+    encode_into(&data, &mut ebuf); // warm
+    decode_into(&ebuf, &mut dbuf);
+    assert_eq!(dbuf, data);
+    let iters = 20;
+    let t = Instant::now();
+    for _ in 0..iters { encode_into(&data, &mut ebuf); }
+    let es = t.elapsed().as_secs_f64() / iters as f64;
+    let t = Instant::now();
+    for _ in 0..iters { decode_into(&ebuf, &mut dbuf); }
+    let ds = t.elapsed().as_secs_f64() / iters as f64;
+    let mb = n as f64 / 1e6;
+    println!("Rust codec (in-process): encode {:.0} MB/s ({:.2} ms), decode {:.0} MB/s ({:.2} ms)",
+        mb / es, es * 1000.0, mb / ds, ds * 1000.0);
+    // allocating path (fair vs Zig core, which allocates per call)
+    let t = Instant::now();
+    for _ in 0..iters { let _ = encode(&data); }
+    let eas = t.elapsed().as_secs_f64() / iters as f64;
+    let t = Instant::now();
+    for _ in 0..iters { let _ = decode(&ebuf); }
+    let das = t.elapsed().as_secs_f64() / iters as f64;
+    println!("Rust codec (in-process, alloc/call): encode {:.0} MB/s ({:.2} ms), decode {:.0} MB/s ({:.2} ms)",
+        mb / eas, eas * 1000.0, mb / das, das * 1000.0);
+}

src/zig/main.zig

@@ -537,6 +537,13 @@ pub fn main(init: std.process.Init) !void {
     const args_buf = try init.arena.allocator().alloc([]const u8, args_z.len);
     for (args_z, 0..) |a, idx| args_buf[idx] = a;
 
+    for (args_buf) |a| {
+        if (std.mem.eql(u8, a, "--bench")) {
+            runBench(io, allocator) catch |e| { writeStats("bench error: {}\n", .{e}); std.process.exit(1); };
+            return;
+        }
+    }
+
     const opts = parseArgs(allocator, args_buf) catch |err| {
         switch (err) {
             error.UnknownOption => writeStats("Error: Unknown option\n", .{}),
@@ -889,3 +896,41 @@ fn handleContainer(io: std.Io, allocator: std.mem.Allocator, opts: Options, inpu
         try writeOutput(io, json, false);
     }
 }
+
+// In-process codec micro-benchmark (`--bench`): pure encode/decode throughput,
+// no stdio, using the Zig 0.16 monotonic clock via the Io interface — for a fair
+// codec-vs-codec comparison with the other implementations.
+fn runBench(io: std.Io, allocator: std.mem.Allocator) !void {
+    const n: usize = 10_000_000;
+    const data = try allocator.alloc(u8, n);
+    defer allocator.free(data);
+    for (data, 0..) |*b, i| b.* = @truncate(i *% 2654435761);
+    const enc0 = try pb.encode(allocator, data, .{});
+    defer allocator.free(enc0);
+    {
+        const d = try pb.decode(allocator, enc0, .{});
+        defer allocator.free(d);
+        if (d.len != n) return error.BenchMismatch;
+    }
+    const iters: usize = 20;
+    const t0 = std.Io.Timestamp.now(io, .awake);
+    var k: usize = 0;
+    while (k < iters) : (k += 1) {
+        const e = try pb.encode(allocator, data, .{});
+        allocator.free(e);
+    }
+    const t1 = std.Io.Timestamp.now(io, .awake);
+    k = 0;
+    while (k < iters) : (k += 1) {
+        const d = try pb.decode(allocator, enc0, .{});
+        allocator.free(d);
+    }
+    const t2 = std.Io.Timestamp.now(io, .awake);
+    const mb: f64 = @as(f64, @floatFromInt(n)) / 1e6;
+    const iters_f: f64 = @as(f64, @floatFromInt(iters));
+    const es: f64 = @as(f64, @floatFromInt(@as(i128, t1.toNanoseconds()) - @as(i128, t0.toNanoseconds()))) / 1e9 / iters_f;
+    const ds: f64 = @as(f64, @floatFromInt(@as(i128, t2.toNanoseconds()) - @as(i128, t1.toNanoseconds()))) / 1e9 / iters_f;
+    var buf: [256]u8 = undefined;
+    const msg = std.fmt.bufPrint(&buf, "Zig codec (in-process, alloc/call): encode {d:.0} MB/s ({d:.2} ms), decode {d:.0} MB/s ({d:.2} ms)\n", .{ mb / es, es * 1000.0, mb / ds, ds * 1000.0 }) catch return;
+    rawWriteAll(std.Io.File.stderr(), msg);
+}