perf(zig): vectorize literal decode prefix

Author: pmarreck

.dirtree-state

@@ -15,7 +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 combines a portable 16-byte SIMD literal-prefix gate with padded glyph slots, and decode uses compact direct UTF-8 tables.
+	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_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

@@ -49,9 +49,10 @@ maintained_by: agent
       on simdutf's block classification rather than depending on it. LLVM emits
       a `<16 x i8>` load and vector range checks. Mixed encode remains
       ~612–629 MB/s; a 10 MB all-literal CLI input improved from 46.2 to
-      37.1 ms (~20%). Curiosity poke: this gate stops at the first mapped glyph,
-      so prose containing default-encoded spaces needs a separate benchmarked
-      design. (2026-07-23 12:28 AM EDT)
+      37.1 ms (~20%) on encode and from 41.6 to 25.1 ms (~40%) on decode.
+      Curiosity poke: this gate stops at the first mapped glyph, so prose
+      containing default-encoded spaces needs a separate benchmarked design.
+      (2026-07-23 12:35 AM EDT)
 
 ## Container honors `--spaces` (legible-markdown containers) — DONE (2026-07-21 EDT)
 

README.md

@@ -77,7 +77,7 @@ The Rust crate also has an in-process codec microbenchmark (`nix develop -c carg
 Key optimizations in the Zig core:
 - **Pre-allocated buffers**: encode/decode output sized upfront (no growth checks in the hot loop).
 - **Flat character map**: a comptime-built contiguous byte buffer (~1.5 KB) replacing 256 scattered fat pointers — fits in L1 cache.
-- **SIMD literal-prefix gate**: a portable 16-byte vector check copies a contiguous run of literal passthrough glyphs unchanged, then falls back to the compact variable-width mapper at the first mapped byte.
+- **SIMD literal-prefix gate**: a portable 16-byte vector check copies a contiguous run of literal passthrough glyphs unchanged during both encode and decode, then falls back to the compact variable-width mapper at the first mapped byte.
 - **O(1) decode lookup**: direct tables for 1- and 2-byte UTF-8 sequences plus a compact 24 KiB table for the map's three 3-byte lead-byte planes, replacing the former binary search.
 - **No inner decode loop**: a single UTF-8 length check + direct lookup per character.
 

src/zig/printable_binary.zig

@@ -466,6 +466,12 @@ fn decodeDefault(allocator: std.mem.Allocator, input: []const u8) ![]u8 {
 
     var i: usize = 0;
     var pos: usize = 0;
+    while (input.len - i >= 16 and isSelfMappedBlock16(input[i..][0..16])) {
+        @memcpy(result[pos..][0..16], input[i..][0..16]);
+        i += 16;
+        pos += 16;
+    }
+
     while (i < input.len) {
         const seq_len = utf8SeqLen(input[i]);
         const remaining = input.len - i;
@@ -1197,6 +1203,14 @@ test "decode: unrecognized UTF-8 passes through" {
     try std.testing.expectEqualSlices(u8, input, decoded);
 }
 
+test "decode: 16-byte literal prefix reaches the following mapped glyph" {
+    const allocator = std.testing.allocator;
+    const input = "ABCDEFGHIJKLMNOP" ++ character_map[0];
+    const decoded = try decode(allocator, input, .{});
+    defer allocator.free(decoded);
+    try std.testing.expectEqualStrings("ABCDEFGHIJKLMNOP\x00", decoded);
+}
+
 test "decode: mixed known and unknown UTF-8" {
     const allocator = std.testing.allocator;
     // "Hello" in PB + an unknown character + "World" in PB