feat(core): CRC-32/ISO-HDLC primitive + pb_crc32 FFI export (issue #1)

Checksum primitive backing the printable-binary-file.json container (issue #1):
pure `crc32` (ISO-HDLC, vector-pinned to CRC32("123456789")=0xCBF43926) in
printable_binary.zig, and the `pb_crc32` C-ABI export in ffi.zig (delegates to
pb.crc32; null-safe). Adds the container design spec + PLAN.md, and gitignores
inbox/ (transient LLMsend coordination).

Author: pmarreck

.dirtree-state

@@ -1,6 +1,8 @@
 # Dirtree: Stateful directory trees in the CLI for humans and LLMs. https://github.com/pmarreck/dirtree
 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)
 	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
 	test/test_module_no_ffi_symbols = Regression test (nm oracle): importing the module must emit 0 pb_* symbols while the FFI static lib keeps all 12 — guards the difz-blocking duplicate-symbol bug

.gitignore

@@ -42,3 +42,6 @@ CLAUDE*.md
 # Local convenience symlink to ~/dotfiles (external target — must not be committed
 # into a published repo; broke the GitHub Pages build as a dangling symlink).
 jj_cheatsheet.md
+
+# Inter-LLM coordination notes (LLMsend) — transient/local, never tracked
+inbox/

PLAN.md

@@ -0,0 +1,56 @@
+---
+purpose: Track work on GitHub issue #1 — web-demo decode workflow + printable-binary-file.json metadata container
+audience: both
+maintained_by: agent
+---
+
+# PLAN — issue #1: decode workflow + printable-binary-file.json
+
+GitHub: https://github.com/pmarreck/printable_binary/issues/1
+Dispatch: inbox/2026-06-26-handle-issue-1.md (from Einstein)
+Spec: docs/plans/2026-06-26-printable-binary-file-container-design.md
+Ruling: inbox/processed/2026-06-26-RULING-issue-1-forks.md
+
+## Forks RESOLVED (Einstein ruling, on Peter's behalf, 2026-06-26)
+- [x] FORK 1 — Architecture: **A2** (schema-as-spec + shared crc32 in core via FFI;
+      consumers assemble the trivial JSON envelope natively; cross-impl differential
+      + CRC vector-pinning guard drift; web stays pure-JS).
+- [x] FORK 2 — Checksum: **CRC-32/ISO-HDLC** (vector-pinned).
+- [x] FORK 3 — Naming: **<name>.pbf.json**.
+- [~] FORK 4 — Web UX: NON-BLOCKING. Mock BOTH (explicit Encode/Decode AND
+      auto-detect) for Peter at the web gate; bias toward making decode obvious.
+- Minors: snake_case keys; lowercase 8-hex crc; container is ADDITIVE (raw .pbt stays).
+
+## SCM NOTE (resolved 2026-06-26 ~3:52pm EDT) — see Einstein ping
+Session began with the working copy on a STALE base (dd0f8014, Jun 10), which
+PREDATES the Jun 24 "refactor(ffi): move pb_* exports into ffi.zig" + Jun 25 CI.
+First crc32 pass landed there (export wrongly in printable_binary.zig). Re-homed
+NON-DESTRUCTIVELY onto yolo (3a6682dc): `jj new yolo` + restored docs + re-applied
+code in the CORRECT files. Old work preserved at ef7496c2 (change pqzmoppq/0,
+divergent) — recoverable via jj oplog. NOT pushed; stale divergent commit NOT
+abandoned — both await Peter's ok.
+
+## DONE (core-first TDD, on yolo base, all green)
+- [x] `pub fn crc32` (src/zig/printable_binary.zig) — CRC-32/ISO-HDLC, bitwise,
+      vector test (CRC32("")=0, "123456789"=0xCBF43926, "a"=0xE8B7BE43). RED→GREEN.
+- [x] `export fn pb_crc32` (src/zig/ffi.zig) — delegates to pb.crc32; FFI test
+      (vector + null-safety). RED→GREEN.
+- [x] Green on: test-zig-unit, test-ffi-cli, test-zig (ReleaseFast + cross-impl).
+      no-ffi-symbols invariant safe by construction (Linux CI enforces on push).
+
+## NEXT (after Peter spec sign-off; web held for Peter mockup)
+- [ ] C header decl `uint32_t pb_crc32(const char*, size_t);` (src/printable_binary.h)
+      — add when the CLI container verb consumes it (TDD-driven).
+- [ ] Container codec — round-trip oracle FIRST: decode(encode(bytes,meta)) ==
+      (bytes,meta), byte+metadata identical. JS side (js/printable_binary.js) +
+      C CLI side.
+- [ ] JS CRC-32 (vector-pinned to same constant) for the web demo.
+- [ ] CLI verb to emit/consume <name>.pbf.json (-/@stdin/@stdout + JSON I/O conv).
+- [ ] Cross-impl differential: C-built container decodes in JS & vice versa.
+- [ ] Web demo: decode UI (paste + drop) + metadata restore. MOCK BOTH for Peter
+      FIRST (can't see rendered output), then build.
+- [ ] Docs: README section, dirtree notes, schema doc finalize.
+
+## Discipline
+jj-only (never raw git); rm-safe (mv ~/.Trash, never rm); per-unit ./test green;
+./build + full suite before push; commit per logical unit; ping Einstein at milestones.

docs/plans/2026-06-26-printable-binary-file-container-design.md

@@ -0,0 +1,136 @@
+# Design: printable-binary-file.json container + web decode workflow
+
+**Date:** 2026-06-26
+**Issue:** https://github.com/pmarreck/printable_binary/issues/1
+**Status:** DRAFT — awaiting Peter's spec sign-off (forks 1–4 ruled by Einstein
+2026-06-26; see inbox/processed/2026-06-26-RULING-issue-1-forks.md)
+
+## Problem
+The browser demo bills itself "Encoder/Decoder" but (a) offers **no clear
+DECODE workflow** — you can only decode by drag-dropping a `.pbt` file; there is
+no way to paste a printable-binary block and get a binary back — and (b) has
+**no way to preserve/restore file metadata** (filename, perms, owner/group,
+timestamps). Encoding `foo.png` yields `foo.png.pbt` and discards everything
+else.
+
+## Resolved decisions (Einstein ruling, on Peter's behalf)
+1. **Architecture = A2.** The JSON envelope is a documented *schema* (the single
+   source of truth). The only *algorithms* — the existing bytes↔glyphs codec and
+   the new CRC-32 — live in the Zig core and are reached through the C FFI. Each
+   consumer (C CLI in C, web demo in JS) assembles/parses the trivial flat-dict
+   envelope with its native JSON facilities. Cross-impl agreement is guaranteed
+   by a **differential test** (container built by C decodes in JS and vice
+   versa) plus **CRC vector-pinning** — not by routing JSON through WASM.
+2. **Checksum = CRC-32/ISO-HDLC** (the zip/gzip/png CRC; reflected, poly
+   `0xEDB88320`, init/xorout `0xFFFFFFFF`). Vector-pinned:
+   `CRC32("123456789") == 0xCBF43926`.
+3. **On-disk name = `<originalname>.pbf.json`** (e.g. `photo.png.pbf.json`).
+   Keeps the name+ext visible, gives editors/jq a `.json` affordance, `.pbf`
+   marks it. The authoritative filename round-trips inside the `filename` key.
+4. **Web UX = deferred, non-blocking.** Does not gate core/CLI. At the web gate,
+   mock BOTH an explicit Encode/Decode affordance AND an auto-detect+paste-box,
+   and let Peter pick — biasing toward making decode *obvious* (the issue's real
+   complaint is discoverability).
+
+Minors: `snake_case` keys; CRC fields are lowercase 8-hex strings; the container
+is **additive** — the raw `.pbt` encode/decode flow stays; the container is a
+NEW option, not a replacement.
+
+## Container schema v1 (`printable-binary-file`)
+```json
+{
+  "format": "printable-binary-file",
+  "version": 1,
+  "filename": "photo.png",
+  "data": "<printable-binary-encoded string>",
+  "byte_length": 12345,
+  "crc32": "cbf43926",
+  "crc32_encoded": "1a2b3c4d",
+  "modified_ms": 1719430000000,
+  "created_ms": 1719420000000,
+  "mode": "0644",
+  "owner": "pmarreck",
+  "group": "staff"
+}
+```
+
+### Field semantics
+| key            | type    | required | meaning |
+|----------------|---------|----------|---------|
+| `format`       | string  | yes      | literal `"printable-binary-file"` (format discriminator) |
+| `version`      | number  | yes      | schema version (1) |
+| `filename`     | string  | yes      | original base filename (authoritative; restored on decode) |
+| `data`         | string  | yes      | the printable-binary-encoded original bytes |
+| `byte_length`  | number  | yes      | length in bytes of the ORIGINAL (decoded) data |
+| `crc32`        | string  | yes      | CRC-32 of the ORIGINAL bytes, lowercase 8-hex |
+| `crc32_encoded`| string  | opt      | CRC-32 of the UTF-8 bytes of the `data` string |
+| `modified_ms`  | number  | opt      | mtime, integer ms since Unix epoch (UTC) |
+| `created_ms`   | number  | opt      | birthtime, ms since epoch (omit if unavailable) |
+| `mode`         | string  | opt      | POSIX permission bits as octal string, e.g. `"0644"` |
+| `owner`        | string  | opt      | owner username (POSIX) |
+| `group`        | string  | opt      | group name (POSIX) |
+
+### Cross-platform rule
+POSIX-only fields (`mode`, `owner`, `group`) and `created_ms` are **omitted when
+unavailable** (Windows, browser). **Decode MUST tolerate any missing optional
+field and never fail because one is absent.** The browser File API yields only
+`name`, `size`, and `lastModified` (ms) — so the web demo populates `filename`,
+`byte_length`, `modified_ms`, `crc32` (and `crc32_encoded`), omitting the rest.
+
+### Self-verification semantics (decode)
+- If `crc32_encoded` is present, verify it against the UTF-8 bytes of `data`
+  BEFORE decoding (catches transport corruption of the JSON/`data` itself).
+- After decoding `data` → bytes, recompute CRC-32 and compare to `crc32`;
+  recompute length and compare to `byte_length`.
+- A mismatch is a hard error in the CLI (non-zero exit, message to stderr) and a
+  clear error in the web UI. (No silent acceptance of corrupted round-trips.)
+
+## Architecture / where each piece lives
+- **Zig core (`src/zig/printable_binary.zig`)**
+  - Existing: `pb_encode` / `pb_decode` (the codec) — unchanged, reused.
+  - NEW `pb_crc32(input: ?[*]const u8, len: usize) -> u32` exported
+    `callconv(.c)`. Pure, no I/O. Table-driven CRC-32/ISO-HDLC.
+- **C FFI header (`src/printable_binary.h`)**: declare `uint32_t pb_crc32(const
+  char*, size_t);`.
+- **C CLI (`src/printable_binary.c` + FFI CLI)**: a verb/flag to EMIT a container
+  (`--to-file-json` / read file+stat → assemble JSON) and to CONSUME one
+  (`--from-file-json` / parse JSON → write bytes + restore metadata). Honors
+  `-`/`@stdin`/`@stdout`. Names exact flags during implementation (kept Unix +
+  Windows-alias-friendly per CLI conventions).
+- **JS (`js/printable_binary.js`)**: container assemble/parse methods + a JS
+  CRC-32 (vector-pinned to the same constant) used by the web demo.
+- **No new format logic in WASM**; the web demo stays pure-JS.
+
+## CRC-32 detail (to avoid impl drift)
+CRC-32/ISO-HDLC, reflected input/output, polynomial `0xEDB88320` (reflected
+`0x04C11DB7`), init `0xFFFFFFFF`, final xor `0xFFFFFFFF`. Both the Zig and JS
+implementations are unit-tested against published vectors:
+`""` → `0x00000000`, `"123456789"` → `0xCBF43926`, `"a"` → `0xE8B7BE43`. Because
+both are pinned to the SAME published oracle, authorship is irrelevant and they
+cannot silently disagree (MFIC: external oracle).
+
+## TDD oracle / test plan (write tests FIRST)
+1. **CRC-32 vectors** (Zig unit + JS): the published vectors above. RED first.
+2. **Container round-trip** (the primary MFIC inverse-pair oracle):
+   `decode(encode(bytes, meta)) == (bytes, meta)` — byte-identical `data` AND
+   identical metadata (modulo platform-omitted fields). RED first.
+3. **Self-verify negative tests**: flip a byte in `data`, or corrupt a CRC
+   field, → decode errors (proves the check isn't vacuous).
+4. **Cross-impl differential** (added to `test/test_cross_implementation.sh`):
+   a container emitted by the C CLI decodes correctly in JS, and a
+   JS/Node-emitted container decodes correctly via the C CLI — byte + metadata
+   identical. External oracle against envelope drift.
+5. **Missing-optional-field tolerance**: a container with only the required
+   fields decodes cleanly (no POSIX fields) — proves cross-platform tolerance.
+
+## Non-goals (YAGNI)
+- No cryptographic/tamper-evidence hashing (CRC-32 is transport-integrity only).
+- No compression (the codec is the codec; container just wraps it).
+- No multi-file/archive container (single file per container in v1).
+- No restoration of owner/group/mode by the *web* demo (browser can't set them);
+  it restores filename + mtime where the download mechanism allows.
+
+## Build order
+core CRC-32 (+FFI) → container codec + round-trip oracle → CLI verb → cross-impl
+differential → web UI (after Peter picks the mockup). Ping Einstein at the core
+and CLI milestones.

src/zig/ffi.zig

@@ -224,3 +224,16 @@ test "FFI: pb_hexlike_encode/decode roundtrip + detect + null safety" {
 	try std.testing.expect(bad.error_code != 0);
 	try std.testing.expect(pb_detect_hexlike(null, 100) == 0);
 }
+
+/// FFI: CRC-32/ISO-HDLC of `len` bytes at `input`. Null ptr (or len 0) yields
+/// the CRC of empty input (0). Delegates to the pure core `pb.crc32`.
+export fn pb_crc32(input: ?[*]const u8, len: usize) callconv(.c) u32 {
+	if (input == null or len == 0) return pb.crc32("");
+	return pb.crc32(input.?[0..len]);
+}
+
+test "FFI: pb_crc32 matches vectors + null safety" {
+	const s = "123456789";
+	try std.testing.expectEqual(@as(u32, 0xCBF43926), pb_crc32(s.ptr, s.len));
+	try std.testing.expectEqual(@as(u32, 0), pb_crc32(null, 100));
+}

src/zig/printable_binary.zig

@@ -1314,3 +1314,33 @@ test "parseGlyphLine: filters comments/blank, strips trailing comment, takes fir
     // CRLF tolerance
     try std.testing.expectEqualStrings("·", parseGlyphLine("·\r").?);
 }
+
+// =========================================================================
+// CRC-32 (issue #1: printable-binary-file.json container integrity)
+// =========================================================================
+
+/// CRC-32/ISO-HDLC (the zip/gzip/png CRC): reflected input/output, polynomial
+/// 0xEDB88320, init 0xFFFFFFFF, final xor 0xFFFFFFFF. Pure helper backing the
+/// container's transport-integrity fields. Bitwise (table-free); ample for
+/// container-sized payloads. `pub` so the FFI surface (ffi.zig) can delegate.
+pub fn crc32(data: []const u8) u32 {
+    var crc: u32 = 0xFFFFFFFF;
+    for (data) |byte| {
+        crc ^= @as(u32, byte);
+        var k: usize = 0;
+        while (k < 8) : (k += 1) {
+            if (crc & 1 != 0) {
+                crc = (crc >> 1) ^ 0xEDB88320;
+            } else {
+                crc >>= 1;
+            }
+        }
+    }
+    return ~crc;
+}
+
+test "crc32: published vectors (ISO-HDLC)" {
+    try std.testing.expectEqual(@as(u32, 0x00000000), crc32(""));
+    try std.testing.expectEqual(@as(u32, 0xCBF43926), crc32("123456789"));
+    try std.testing.expectEqual(@as(u32, 0xE8B7BE43), crc32("a"));
+}