perf(zig): vectorize literal encode prefix

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 = Active project plan; records benchmarked default-path optimization and remaining SIMD/decode experiments.
+	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.
 	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,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 uses four-byte padded slots and decode uses compact direct UTF-8 lookup tables.
+	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.
 	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

@@ -45,11 +45,13 @@ maintained_by: agent
       classifier branch. Curiosity poke: revisit only with a genuinely vector
       block classifier that does not tax non-passthrough data. (2026-07-23
       12:25 AM EDT)
-- [ ] 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.
+- [x] Add a portable 16-byte SIMD literal-prefix gate using `@Vector`, modeled
+      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)
 
 ## Container honors `--spaces` (legible-markdown containers) — DONE (2026-07-21 EDT)
 

README.md

@@ -77,6 +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.
 - **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

@@ -112,6 +112,20 @@ const padded_map_data: [256][4]u8 = blk: {
     break :blk data;
 };
 
+/// Check one vector-width block against the map's literal ASCII passthrough
+/// ranges. This is the simdutf-style common-case gate: successful blocks copy
+/// unchanged, while mixed/binary input immediately falls back to scalar slots.
+fn isSelfMappedBlock16(bytes: *const [16]u8) bool {
+    const ByteVector = @Vector(16, u8);
+    const block: ByteVector = bytes.*;
+    const period = block == @as(ByteVector, @splat('.'));
+    const digits = (block >= @as(ByteVector, @splat('0'))) & (block <= @as(ByteVector, @splat('9')));
+    const upper = (block >= @as(ByteVector, @splat('A'))) & (block <= @as(ByteVector, @splat('Z')));
+    const punctuation = (block >= @as(ByteVector, @splat('^'))) & (block <= @as(ByteVector, @splat('_')));
+    const lower = (block >= @as(ByteVector, @splat('a'))) & (block <= @as(ByteVector, @splat('z')));
+    return @reduce(.And, period | digits | upper | punctuation | lower);
+}
+
 /// Direct O(1) decode lookup for 1-byte UTF-8 sequences
 const decode_1byte: [256]?u8 = blk: {
     @setEvalBranchQuota(100000);
@@ -379,8 +393,15 @@ fn encodeDefault(allocator: std.mem.Allocator, input: []const u8) ![]u8 {
     var result = try allocator.alloc(u8, capacity);
     errdefer allocator.free(result);
 
+    var input_pos: usize = 0;
     var pos: usize = 0;
-    for (input) |byte| {
+    while (input.len - input_pos >= 16 and isSelfMappedBlock16(input[input_pos..][0..16])) {
+        @memcpy(result[pos..][0..16], input[input_pos..][0..16]);
+        input_pos += 16;
+        pos += 16;
+    }
+
+    for (input[input_pos..]) |byte| {
         @memcpy(result[pos..][0..4], &padded_map_data[byte]);
         pos += flat_map_entries[byte].len;
     }
@@ -1145,6 +1166,14 @@ test "encode: ASCII passthrough characters are preserved" {
     try std.testing.expectEqualStrings("Hello.World@123", encoded);
 }
 
+test "encode: 16-byte literal prefix remains compact before a mapped glyph" {
+    const allocator = std.testing.allocator;
+    const input = "ABCDEFGHIJKLMNOP\x00";
+    const encoded = try encode(allocator, input, .{});
+    defer allocator.free(encoded);
+    try std.testing.expectEqualStrings("ABCDEFGHIJKLMNOP" ++ character_map[0], encoded);
+}
+
 test "encode: spaces option preserves literal spaces" {
     const allocator = std.testing.allocator;
     const input = "A B";