feat(rust): native printable-binary raw codec crate (byte-identical to Zig, faster)

A native Rust implementation for the Rust-GUI <-> Zig-core transport. build.rs
codegens the byte<->glyph map and O(1) decode tables (decode_1byte / decode_2byte
payload-indexed / sorted 3-byte binary-search, ported from the C core) straight
from the single-source character_map.txt, so output is byte-identical to every
other impl. lib.rs has encode/decode plus zero-allocation encode_into/decode_into
(reuse a caller-owned buffer; no per-message malloc). Cross-verified vs the Zig
CLI (encode bytes match exactly; Rust decodes Zig-encoded streams) and benchmarked
~1.7-1.85x faster than Zig on 10MB. Minimal stdin/stdout CLI for cross-impl tests.
Flake/CI wiring and the full CLI surface are deliberately deferred (specifics TBD).

Author: pmarreck

.dirtree-state

@@ -3,6 +3,9 @@ ver=1.2
 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/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)
 	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
 	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

.gitignore

@@ -45,3 +45,6 @@ jj_cheatsheet.md
 
 # Inter-LLM coordination notes (LLMsend) — transient/local, never tracked
 inbox/
+
+# Rust build artifacts
+/rust/target/

rust/Cargo.lock

@@ -0,0 +1,18 @@
+[package]
+name = "printable_binary"
+version = "0.1.0"
+edition = "2021"
+description = "PrintableBinary raw codec (Rust) — byte<->printable-UTF-8, for a GUI<->core transport"
+license = "MIT"
+
+[lib]
+path = "src/lib.rs"
+
+[profile.release]
+lto = true
+codegen-units = 1
+panic = "abort"
+
+[[bin]]
+name = "printable-binary-rs"
+path = "src/main.rs"

rust/Cargo.toml

@@ -0,0 +1,63 @@
+// Codegen the byte<->glyph map + O(1) decode tables from the single-source
+// character_map.txt (same parse rules as every other implementation), so the
+// Rust impl produces byte-identical output and stays in lockstep with the map.
+use std::{env, fs, path::Path};
+
+fn main() {
+    let manifest = env::var("CARGO_MANIFEST_DIR").unwrap();
+    let map_path = Path::new(&manifest).join("..").join("character_map.txt");
+    println!("cargo:rerun-if-changed={}", map_path.display());
+    let text = fs::read_to_string(&map_path).expect("read ../character_map.txt");
+
+    // One glyph per line in byte order; `##` = full-line comment; first
+    // whitespace-delimited token is the glyph; blank lines skipped.
+    let mut glyphs: Vec<&str> = Vec::new();
+    for line in text.lines() {
+        let line = line.trim_end_matches('\r');
+        if line.is_empty() || line.starts_with("##") {
+            continue;
+        }
+        match line.split_whitespace().next() {
+            Some(tok) if !tok.is_empty() => glyphs.push(tok),
+            _ => {}
+        }
+    }
+    assert_eq!(glyphs.len(), 256, "expected 256 glyphs, got {}", glyphs.len());
+
+    let mut map_data: Vec<u8> = Vec::new();
+    let mut encode: Vec<(usize, usize)> = Vec::new();
+    let mut decode_1 = [-1i16; 256];
+    let mut decode_2 = [[-1i16; 64]; 32];
+    let mut decode_3: Vec<(u32, u8)> = Vec::new();
+
+    for (byte, g) in glyphs.iter().enumerate() {
+        let b = g.as_bytes();
+        encode.push((map_data.len(), b.len()));
+        map_data.extend_from_slice(b);
+        match b.len() {
+            1 => decode_1[b[0] as usize] = byte as i16,
+            2 => decode_2[(b[0] & 0x1F) as usize][(b[1] & 0x3F) as usize] = byte as i16,
+            3 => {
+                let key = ((b[0] as u32) << 16) | ((b[1] as u32) << 8) | b[2] as u32;
+                decode_3.push((key, byte as u8));
+            }
+            n => panic!("byte {byte}: glyph is {n} bytes (expected 1-3, BMP only)"),
+        }
+    }
+    decode_3.sort_by_key(|&(k, _)| k);
+
+    let mut s = String::new();
+    s.push_str(&format!("pub static MAP_DATA: [u8; {}] = {:?};\n", map_data.len(), map_data));
+    s.push_str("pub static ENCODE: [(u16, u8); 256] = [");
+    for (o, l) in &encode { s.push_str(&format!("({o},{l}),")); }
+    s.push_str("];\n");
+    s.push_str(&format!("pub static DECODE_1: [i16; 256] = {:?};\n", &decode_1[..]));
+    s.push_str("pub static DECODE_2: [[i16; 64]; 32] = [");
+    for row in &decode_2 { s.push_str(&format!("{:?},", &row[..])); }
+    s.push_str("];\n");
+    s.push_str(&format!("pub static DECODE_3: [(u32, u8); {}] = [", decode_3.len()));
+    for (k, b) in &decode_3 { s.push_str(&format!("({k},{b}),")); }
+    s.push_str("];\n");
+
+    fs::write(Path::new(&env::var("OUT_DIR").unwrap()).join("map.rs"), s).unwrap();
+}

rust/build.rs

@@ -0,0 +1,121 @@
+//! PrintableBinary — Rust implementation of the raw byte<->printable-UTF-8 codec.
+//!
+//! Produces byte-identical output to the Zig/C/Lua/JS implementations (same
+//! `character_map.txt`). Built for a Rust-GUI <-> Zig-core transport: the
+//! `*_into` variants reuse a caller-owned buffer for zero per-message allocation.
+include!(concat!(env!("OUT_DIR"), "/map.rs"));
+
+/// Worst-case encoded length: every byte maps to at most a 3-byte glyph.
+#[inline]
+pub fn encode_bound(len: usize) -> usize {
+    len * 3
+}
+
+/// Encode raw bytes to printable-binary UTF-8 (allocating).
+pub fn encode(input: &[u8]) -> Vec<u8> {
+    let mut out = Vec::with_capacity(encode_bound(input.len()));
+    encode_into(input, &mut out);
+    out
+}
+
+/// Encode into a caller-owned buffer (cleared, then filled). Reuses the buffer's
+/// allocation across calls — zero allocations per message after warm-up.
+pub fn encode_into(input: &[u8], out: &mut Vec<u8>) {
+    out.clear();
+    out.reserve(encode_bound(input.len()));
+    for &b in input {
+        let (off, len) = ENCODE[b as usize];
+        let (off, len) = (off as usize, len as usize);
+        out.extend_from_slice(&MAP_DATA[off..off + len]);
+    }
+}
+
+#[inline]
+fn utf8_len(b: u8) -> usize {
+    if b < 0x80 { 1 } else if b < 0xE0 { 2 } else if b < 0xF0 { 3 } else { 4 }
+}
+
+/// Decode printable-binary UTF-8 back to raw bytes (allocating). Unrecognized
+/// sequences pass through unchanged, matching the other implementations.
+pub fn decode(input: &[u8]) -> Vec<u8> {
+    let mut out = Vec::with_capacity(input.len());
+    decode_into(input, &mut out);
+    out
+}
+
+/// Decode into a caller-owned buffer (cleared, then filled).
+pub fn decode_into(input: &[u8], out: &mut Vec<u8>) {
+    out.clear();
+    let mut i = 0;
+    while i < input.len() {
+        let b0 = input[i];
+        let mut len = utf8_len(b0);
+        if i + len > input.len() {
+            len = input.len() - i;
+        }
+        let mut matched = false;
+        match len {
+            1 => {
+                let v = DECODE_1[b0 as usize];
+                if v >= 0 {
+                    out.push(v as u8);
+                    i += 1;
+                    matched = true;
+                }
+            }
+            2 => {
+                let v = DECODE_2[(b0 & 0x1F) as usize][(input[i + 1] & 0x3F) as usize];
+                if v >= 0 {
+                    out.push(v as u8);
+                    i += 2;
+                    matched = true;
+                }
+            }
+            3 => {
+                let key = ((input[i] as u32) << 16) | ((input[i + 1] as u32) << 8) | input[i + 2] as u32;
+                if let Ok(idx) = DECODE_3.binary_search_by_key(&key, |&(k, _)| k) {
+                    out.push(DECODE_3[idx].1);
+                    i += 3;
+                    matched = true;
+                }
+            }
+            _ => {}
+        }
+        if !matched {
+            out.extend_from_slice(&input[i..i + len]);
+            i += len;
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn round_trip_all_256_single_bytes() {
+        for b in 0u16..256 {
+            let b = b as u8;
+            let dec = decode(&encode(&[b]));
+            assert_eq!(dec, vec![b], "byte {b:#04x} did not round-trip");
+        }
+    }
+
+    #[test]
+    fn round_trip_mixed_buffer() {
+        let mut data: Vec<u8> = (0u16..256).map(|x| x as u8).collect();
+        data.extend_from_slice(b"Hello, World!\x00\xff\n\t");
+        assert_eq!(decode(&encode(&data)), data);
+    }
+
+    #[test]
+    fn zero_alloc_into_matches_allocating() {
+        let data = b"transport \x00\x01\xfe\xff frame";
+        let mut ebuf = Vec::new();
+        encode_into(data, &mut ebuf);
+        assert_eq!(ebuf, encode(data));
+        let mut dbuf = Vec::new();
+        decode_into(&ebuf, &mut dbuf);
+        assert_eq!(dbuf, data.to_vec());
+    }
+}

rust/src/lib.rs

@@ -0,0 +1,13 @@
+// Minimal CLI for cross-impl verification + the transport smoke path.
+// (Provisional surface — the full CLI is a "specifics" decision still pending.)
+// Default: encode stdin->stdout. `-d`/`--decode`: decode stdin->stdout.
+use printable_binary::{decode, encode};
+use std::io::{Read, Write};
+
+fn main() {
+    let decode_mode = std::env::args().skip(1).any(|a| a == "-d" || a == "--decode");
+    let mut input = Vec::new();
+    std::io::stdin().read_to_end(&mut input).expect("read stdin");
+    let out = if decode_mode { decode(&input) } else { encode(&input) };
+    std::io::stdout().write_all(&out).expect("write stdout");
+}