refactor(ffi): split pb_* C exports into ffi.zig so the importable module emits no C symbols

The printable_binary Zig module and the static FFI lib shared one root
source file, so any Zig consumer importing the module pulled in all 12
'export fn pb_*' C symbols. Two static (musl) consumers of pb then collide
on 'duplicate symbol: pb_*' under ld.lld -- which blocked difz's static build.

Move the C ABI into src/zig/ffi.zig (the static lib's new root, importing the
pure printable_binary.zig). The importable module now defines zero pb_* symbols;
libprintable_binary.a keeps all 12. FFI unit tests move alongside the exports.

Adds a falsifiable regression test (test/test_module_no_ffi_symbols, nm as an
independent oracle) wired as the test-no-ffi-symbols Garnix check.

Author: pmarreck

.dirtree-state

@@ -1,94 +1,7 @@
 # Dirtree: Stateful directory trees in the CLI for humans and LLMs. https://github.com/pmarreck/dirtree
 ver=1.2
-depth=3
-color=false
-
 annotate=[
-	.envrc = direnv: auto-enter the Nix dev shell
-	.github = GitHub Actions CI configuration
-	.github/workflows/ci.yml = GitHub Actions: nix build/test (linux/darwin), cross-compile, windows
-	.gitignore = Git ignore rules
-	.nojekyll = Disable Jekyll on GitHub Pages so symlinks/underscored paths are served
-	AGENTS.md = TDD and workflow discipline for AI agents working in this repo
-	CHARACTER_WIDTHS.md = Notes on terminal character-width (East Asian Width) handling
-	CLAUDE.md = Repository-specific instructions for Claude Code
-	COMPARISON_WITH_BAT.md = Feature/behavior comparison against the bat pager
-	C_VS_LUAJIT_PERFORMANCE.md = Performance notes comparing the C and LuaJIT implementations
-	FUTURE_WORK.md = Roadmap and ideas not yet scheduled
-	LICENSE = Project license
-	Makefile = Build targets: native C, WASM (emcc), APE (cosmocc), PGO
-	NEXT_STEPS.md = Short-term planned next steps
-	README.md = Project overview, usage, and cross-implementation performance table
-	README_IMPLEMENTATIONS.md = Per-implementation details and how they relate
-	WEB_README.md = Docs for the web/WASM browser demo
-	bin = Runnable CLI entry points (Lua/Node) + prebuilt APE binary and the runtime map
-	bin/character_map.txt = Symlink -> ../character_map.txt (runtime map for the Lua CLI)
-	bin/printable-binary = LuaJIT CLI (the original reference implementation)
-	bin/printable-binary-node.js = Node.js CLI (ESM)
-	bin/printable_binary_ape.com = Prebuilt Actually-Portable-Executable (Cosmopolitan) C binary
-	bin/utf16to8 = Helper: transcode UTF-16 stdin -> UTF-8 (iconv wrapper; auto-detects BOM, else LE)
-	bin/utf8to16 = Helper: transcode UTF-8 stdin -> UTF-16 (iconv wrapper; default LE + BOM)
-	bm = Ad-hoc benchmark scripts (C vs Lua vs Zig)
-	bm/benchmark-zig-opt = Zig optimization benchmark
-	bm/benchmark_c_vs_lua.sh = C vs Lua benchmark script
-	bm/benchmark_comparison.lua = Cross-implementation comparison benchmark (Lua)
-	build = Convenience build script
-	build.zig = Zig build: CLI, C-ABI static lib (PIC), unit tests
-	build.zig.zon = Zig package manifest
-	character_map.txt = SOURCE OF TRUTH byte->glyph map (256 lines, ## comments) all builds derive from
-	character_map_embedded.h = Generated C embedding of character_map.txt (via utils/generate_embedded_map.lua)
-	docs = GitHub Pages web demo (symlinks to root) + design plans
-	docs/character_map.txt = Symlink -> ../character_map.txt
-	docs/index.html = Symlink -> ../index.html
-	docs/plans/2026-02-03-double-encode-detection-design.md = Design doc: double-encode detection
-	docs/printable_binary.js = Symlink -> ../js/printable_binary.js
-	flake.lock = Pinned flake input revisions
-	flake.nix = Nix packages (native/zig/wasm/ape) + Garnix checks (test-c/zig/js/ffi/leak/...)
-	index.html = Root web demo page (served by GitHub Pages from /)
-	js = Shared JavaScript module used by the Node CLI and the browser demo
-	js/printable_binary.js = Shared JS module (encode/decode/parseMap) for the Node CLI and browser
-	lib = Vendored Lua helper libraries
-	lib/xxhash32.lua = xxHash32 implementation in Lua
-	package.json = Node ESM manifest (type:module) for the JS implementation
-	printable_binary.js = Symlink -> js/printable_binary.js so the root web page can import it
-	src = Core implementations: standalone C, the C FFI header/CLI, and the Zig core+CLI
-	src/printable_binary.c = Standalone, dependency-free C implementation + CLI (portable build)
-	src/printable_binary.h = Public C FFI header -- the real cross-language API (pb_encode/decode/hexlike/...)
-	src/printable_binary_ffi_main.c = C CLI that dogfoods the FFI by calling the Zig lib through the C ABI
-	src/zig = Zig core library (logic + pb_* C ABI exports) and the Zig CLI
-	src/zig/main.zig = Zig CLI (argument parsing + I/O around the Zig core)
-	src/zig/printable_binary.zig = Zig core: encode/decode/hexlike logic + comptime map + pb_* C ABI exports
-	test = Test suites: functional, fuzz, benchmark, leak, cross-implementation, unit
-	test/benchmark_test = Encode/decode throughput benchmark (Zig default, announces impl)
-	test/fuzz_test = Seeded random-data roundtrip fuzzer (reproducible via --seed)
-	test/js = JavaScript unit tests (Deno/Node)
-	test/js/test_printable_binary.js = JS unit tests (Deno/Node)
-	test/leak_harness.c = FFI-driven leak harness: loops pb_* alloc/free, self-reports RSS
-	test/leak_test = Memory-leak suite: runs a target long-lived and fails on RSS growth
-	test/printable-binary-ape-wrapper = Wrapper to invoke the APE binary in tests
-	test/test = Main cross-implementation functional suite (IMPLEMENTATION_TO_TEST-selectable)
-	test/test-all = Master runner that exercises every implementation
-	test/test_ape_arch_slice = APE multi-arch slice verification
-	test/test_cross_implementation.sh = Cross-implementation output comparison
-	test/test_node_cli_stats = Node CLI stats/stderr behavior test
-	test/test_validate.c = C unit tests for pb_validate
-	test/test_wasm = WASM build validation (via WASI runtime)
-	utils = Tooling: map generation/auditing, fuzz PRNG, EAW data, analysis scripts
-	utils/audit_character_map.lua = Audits the character map for conflicts/issues
-	utils/data = Reference data (Unicode East Asian Width table)
-	utils/data/EastAsianWidth.txt = Unicode East Asian Width reference data
-	utils/diagnose.sh = Diagnostic helper
-	utils/dump-chars.sh = Dump the character map for inspection
-	utils/generate_embedded_map.lua = Generates character_map_embedded.h from character_map.txt (## aware)
-	utils/js = One-off JS scripts used while designing/auditing the character map
-	utils/js/analyze_encoding_sizes.js = One-off: analyze encoded-size distribution
-	utils/js/compare_all_maps.js = One-off: compare candidate maps
-	utils/js/compare_maps.js = One-off: compare two maps
-	utils/js/debug_maps.js = One-off: debug map building
-	utils/js/debug_test.js = One-off: debugging scratch
-	utils/js/find_available.js = One-off: find available glyphs
-	utils/js/find_conflicts.js = One-off: find glyph conflicts
-	utils/js/find_replacements.js = One-off: find replacement glyphs
-	utils/prng = LuaJIT PRNG utility for deterministic fuzz data
-	utils/update_eaw_data.sh = Refresh the Unicode East Asian Width data file
+	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
 ]

build.zig

@@ -17,8 +17,13 @@ pub fn build(b: *std.Build) void {
     // =========================================================================
     // Static Library with C ABI (for FFI consumers like Cosmopolitan)
     // =========================================================================
+    // Root is ffi.zig — the FFI-only file that holds every `export fn pb_*`.
+    // It imports printable_binary.zig (relative), so the C ABI is emitted ONLY
+    // here, never in the importable `printable_binary` module above. This is
+    // what keeps static (musl) downstreams from colliding on duplicate pb_*
+    // symbols. See src/zig/ffi.zig and test/test_module_no_ffi_symbols.
     const static_lib_mod = b.createModule(.{
-        .root_source_file = b.path("src/zig/printable_binary.zig"),
+        .root_source_file = b.path("src/zig/ffi.zig"),
         .target = target,
         .optimize = optimize,
         // Position-independent so the static lib links into PIE executables
@@ -92,9 +97,45 @@ pub fn build(b: *std.Build) void {
     const test_step = b.step("test", "Run unit tests");
     test_step.dependOn(&run_lib_tests.step);
 
+    // FFI-surface tests (the C ABI wrappers now live in ffi.zig)
+    const ffi_test_mod = b.createModule(.{
+        .root_source_file = b.path("src/zig/ffi.zig"),
+        .target = target,
+        .optimize = optimize,
+    });
+    ffi_test_mod.addAnonymousImport("character_map.txt", .{ .root_source_file = b.path("character_map.txt") });
+    const ffi_tests = b.addTest(.{
+        .root_module = ffi_test_mod,
+    });
+    test_step.dependOn(&b.addRunArtifact(ffi_tests).step);
+
     // =========================================================================
     // Library-only step (for Makefile integration)
     // =========================================================================
     const lib_step = b.step("lib", "Build only the static library");
     lib_step.dependOn(&static_lib.step);
+
+    // =========================================================================
+    // Module-consumer static lib (FFI-symbol-leak regression test)
+    // =========================================================================
+    // Builds a downstream consumer that imports the `printable_binary` module
+    // the way sibling Zig projects do. test/test_module_no_ffi_symbols asserts
+    // the resulting archive carries NO `pb_*` C symbols — they must originate
+    // only in the FFI-root static library (libprintable_binary.a). See
+    // test/module_consumer.zig.
+    const consumer_mod = b.createModule(.{
+        .root_source_file = b.path("test/module_consumer.zig"),
+        .target = target,
+        .optimize = optimize,
+        .imports = &.{
+            .{ .name = "printable_binary", .module = lib_mod },
+        },
+    });
+    const consumer_lib = b.addLibrary(.{
+        .name = "module_consumer",
+        .linkage = .static,
+        .root_module = consumer_mod,
+    });
+    const consumer_lib_step = b.step("consumer-lib", "Build the module-consumer static lib (FFI-symbol-leak test fixture)");
+    consumer_lib_step.dependOn(&b.addInstallArtifact(consumer_lib, .{}).step);
 }

flake.nix

@@ -347,6 +347,22 @@
             installPhase = "mkdir -p $out && touch $out/passed";
           };
 
+          # Architecture invariant: importing the `printable_binary` Zig module
+          # must emit ZERO `pb_*` C symbols (the C ABI lives only in the FFI-root
+          # static lib). Two static (musl) consumers of pb otherwise collide on
+          # `duplicate symbol: pb_*` under ld.lld — this blocked difz. nm is an
+          # independent oracle. See test/test_module_no_ffi_symbols.
+          test-no-ffi-symbols = pkgs.stdenv.mkDerivation {
+            name = "test-no-ffi-symbols";
+            src = ./.;
+            nativeBuildInputs = with pkgs; [ zig binutils ];
+            buildPhase = ''
+              export HOME=$TMPDIR
+              bash ./test/test_module_no_ffi_symbols
+            '';
+            installPhase = "mkdir -p $out && touch $out/passed";
+          };
+
           # Guard against a stale generated C header: regenerating from
           # character_map.txt must reproduce the committed character_map_embedded.h.
           test-embedded-map-sync = pkgs.stdenv.mkDerivation {