perf(zig): use padded map slots for default encode

Author: pmarreck

.dirtree-state

@@ -3,7 +3,7 @@ ver=1.2
 annotate=[
 	.mechatron-prime/targets = Exact Nix package and check targets that Mechatron Prime builds from each pushed commit.
 	MEMORIES/WASM benchmarks must stream inputs and APE needs a clean environment = WASI and Cosmopolitan runtime requirements for benchmark adapters.
-	PLAN.md = Issue #1 plan: decode workflow + printable-binary-file.json container
+	PLAN.md = Active project plan; records benchmarked default-path optimization and remaining SIMD/decode experiments.
 	bm/benchmark-zig-opt = Benchmarks all available CLI variants, including Rust stdin, WASM, and APE adapters.
 	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)
@@ -15,6 +15,7 @@ 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/printable_binary.zig = Pure Zig codec core; default encode uses four-byte padded internal glyph slots while returning compact UTF-8.
 	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_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)

PLAN.md

@@ -22,13 +22,26 @@ maintained_by: agent
 
 ## Deferred performance investigation
 
-- [ ] Benchmark SIMD feasibility for PrintableBinary encode/decode using
-      `simdutf` as a technique reference (or dependency only if it cleanly
-      fits). Start with a scalar profile and a reproducible before/after
-      benchmark; prioritize byte classification, UTF-8 validation, and
-      variable-width packing only where measurements show a bottleneck.
-      Curiosity poke: per-byte map lookup plus 1–3-byte output may make gathers
-      and compaction slower than the scalar table path on real inputs.
+- [x] Baseline the deterministic 10 MB mixed-byte core benchmark against Rust,
+      then implement and measure a four-byte internal glyph slot. Zig began at
+      236 MB/s encode / 308 MB/s decode; Rust measured 300/462 MB/s alloc/call.
+      The compact-wire-format-preserving slot plus default-option fast path
+      reaches 605–631 MB/s encode; decode remains ~310 MB/s. (2026-07-23
+      12:17 AM EDT)
+- [ ] Measure reusable-output ownership only if a consumer needs it. The public
+      `[]u8` API must shrink before return, whereas Rust's `Vec` retains
+      capacity; exposing an owned-capacity buffer is an API design, not a
+      transparent micro-optimization. Curiosity poke: callers must never
+      observe stale bytes after a shorter subsequent encode/decode.
+- [ ] Prototype and measure a cache-resident O(1) decoder for the 28 three-byte
+      glyphs before replacing the current ~100-byte binary-search table.
+      Curiosity poke: a 24 KB direct table may cost more cache than five
+      predictable comparisons.
+- [ ] Prototype a portable SIMD/hybrid classifier only if the measured
+      scalar loop remains dominant. Use `simdutf` as a technique reference,
+      not a dependency: its UTF-8 transcoder cannot directly express this
+      custom byte-to-glyph map. Curiosity poke: 1–3-byte output compaction can
+      cost more than the scalar table path on mixed data.
 
 ## Container honors `--spaces` (legible-markdown containers) — DONE (2026-07-21 EDT)
 

src/zig/printable_binary.zig

@@ -99,6 +99,19 @@ const flat_map_entries: [256]FlatMapEntry = blk: {
     break :blk entries;
 };
 
+/// Four-byte internal slots let the default encoder use one fixed-width write
+/// per glyph while retaining the compact 1–3 byte PrintableBinary wire format.
+/// The final three bytes are allocation-only padding and are excluded on return.
+const padded_map_data: [256][4]u8 = blk: {
+    @setEvalBranchQuota(100000);
+    var data = [_][4]u8{[_]u8{0} ** 4} ** 256;
+    for (0..256) |i| {
+        const glyph = character_map[i];
+        for (glyph, 0..) |byte, j| data[i][j] = byte;
+    }
+    break :blk data;
+};
+
 /// Direct O(1) decode lookup for 1-byte UTF-8 sequences
 const decode_1byte: [256]?u8 = blk: {
     @setEvalBranchQuota(100000);
@@ -365,11 +378,33 @@ fn decodeLookup(bytes: []const u8) ?u8 {
     }
 }
 
+/// Encode the common option-free case with fixed-width internal writes.
+/// Each map glyph is stored in a four-byte slot, avoiding per-glyph variable
+/// copies; only the true 1–3 byte length advances the public output.
+fn encodeDefault(allocator: std.mem.Allocator, input: []const u8) ![]u8 {
+    // Three trailing bytes make a four-byte store safe even for the final glyph.
+    const capacity = try std.math.add(usize, try std.math.mul(usize, input.len, 3), 3);
+    var result = try allocator.alloc(u8, capacity);
+    errdefer allocator.free(result);
+
+    var pos: usize = 0;
+    for (input) |byte| {
+        @memcpy(result[pos..][0..4], &padded_map_data[byte]);
+        pos += flat_map_entries[byte].len;
+    }
+
+    return allocator.realloc(result, pos);
+}
+
 /// Encode binary data to printable UTF-8.
+/// The option-free path specializes the dominant CLI/library workload so
+/// disabled formatting switches do not branch inside the per-byte loop.
 /// Caller owns the returned slice and must free it with the same allocator.
 pub fn encode(allocator: std.mem.Allocator, input: []const u8, options: EncodeOptions) ![]u8 {
-    if (input.len == 0) {
-        return try allocator.alloc(u8, 0);
+    if (input.len == 0) return try allocator.alloc(u8, 0);
+
+    if (!options.spaces and !options.tabs and !options.crlf and options.preserve_chars.len == 0) {
+        return encodeDefault(allocator, input);
     }
 
     // Pre-allocate worst case: every byte → max 3-byte UTF-8
@@ -408,12 +443,46 @@ pub fn encode(allocator: std.mem.Allocator, input: []const u8, options: EncodeOp
     return allocator.realloc(result, pos);
 }
 
+/// Decode printable UTF-8 back to binary data.
+/// Unrecognized UTF-8 characters pass through unchanged.
+/// The normal path has neither literal-space nor whitespace formatting rules;
+/// specializing it keeps those option checks out of the UTF-8 character loop.
+fn decodeDefault(allocator: std.mem.Allocator, input: []const u8) ![]u8 {
+    var result = try allocator.alloc(u8, input.len);
+    errdefer allocator.free(result);
+
+    var i: usize = 0;
+    var pos: usize = 0;
+    while (i < input.len) {
+        const seq_len = utf8SeqLen(input[i]);
+        const remaining = input.len - i;
+        const actual_len: usize = if (seq_len > remaining) remaining else seq_len;
+
+        if (actual_len == seq_len) {
+            if (decodeLookup(input[i .. i + actual_len])) |byte| {
+                result[pos] = byte;
+                pos += 1;
+                i += actual_len;
+                continue;
+            }
+        }
+
+        @memcpy(result[pos..][0..actual_len], input[i..][0..actual_len]);
+        pos += actual_len;
+        i += actual_len;
+    }
+
+    return allocator.realloc(result, pos);
+}
+
 /// Decode printable UTF-8 back to binary data.
 /// Unrecognized UTF-8 characters pass through unchanged.
 /// Caller owns the returned slice and must free it with the same allocator.
 pub fn decode(allocator: std.mem.Allocator, input: []const u8, options: DecodeOptions) ![]u8 {
-    if (input.len == 0) {
-        return try allocator.alloc(u8, 0);
+    if (input.len == 0) return try allocator.alloc(u8, 0);
+
+    if (!options.spaces and !options.strip_whitespace) {
+        return decodeDefault(allocator, input);
     }
 
     // Optionally strip whitespace (pre-allocated buffer, no ArrayList)