feat(elixir): ~PB compile-time sigil demo + test-elixir CI guard

Embeds raw binary legibly inline in source: ~PB"..." decodes printable-binary
glyphs to raw bytes at COMPILE time (zero runtime cost, bytes baked into BEAM).
Map parsed from character_map.txt via @external_resource (single source of truth).
CI test-elixir: mix test + MFIC cross-impl guard where the Zig CLI is the
independent encoder oracle and Elixir decode/1 must reproduce originals over
all-256 single bytes + 8 KiB random. elixir/_build gitignored.

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)
+	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)
+	elixir/mix.exs = Mix project for the ~PB sigil demo (no deps)
+	elixir/test/printable_binary_test.exs = ExUnit tests + doctest for ~PB sigil / decode/1 (passthrough, control glyphs, whitespace-ignored heredoc, all-256 round-trip, unrecognized-glyph raise)
 	rust/build.rs = Codegens byte<->glyph map + O(1) decode tables from character_map.txt (single source)
 	rust/examples/bench.rs = In-process Rust codec throughput bench (isolates codec from CLI I/O)
 	rust/src/lib.rs = Rust printable-binary core: raw encode/decode + zero-alloc *_into (byte-identical to Zig, ~1.8x faster)

.gitignore

@@ -48,3 +48,9 @@ inbox/
 
 # Rust build artifacts
 /rust/target/
+
+# Elixir build artifacts (~PB sigil demo)
+elixir/_build/
+elixir/deps/
+elixir/.elixir_ls/
+elixir/*.ez

PLAN.md

@@ -115,3 +115,18 @@ Every printable-binary executable understands .pbf.json (-C/--container):
       container byte-identically, and vice versa)
 Shared: src/container_json.h (C), test/test_container (parameterized),
 test/test_container_cross (differential).
+
+## Elixir ~PB compile-time sigil demo (2026-06-30) — DONE, green in CI
+Demonstrates embedding raw binary legibly inline in source (no fixture files):
+`import PrintableBinary; @magic ~PB"..."` decodes glyphs -> raw bytes AT COMPILE
+TIME (zero runtime cost; bytes baked into the BEAM). `"""` heredoc works since a
+literal `"` never appears in the payload.
+- [x] elixir/lib/printable_binary.ex — `defmacro sigil_PB({:"<<>>",_,[str]},_)` +
+      `decode/1` (whitespace-tolerant). Map parsed from character_map.txt at compile
+      time via @external_resource (single source of truth; same parse as all impls).
+- [x] elixir/test/printable_binary_test.exs — 5 tests + 1 doctest (passthrough,
+      control glyph byte0=·, whitespace-ignored heredoc, all-256 round-trip, raise).
+- [x] flake check `test-elixir`: `mix test` + MFIC cross-impl guard — Zig CLI is the
+      INDEPENDENT encoder oracle; Elixir decode/1 must reproduce originals over
+      all-256 single bytes + 8 KiB random (2/3-byte glyph boundaries). Green.
+- [x] elixir/_build gitignored (swept-in artifacts moved out, not committed).

elixir/lib/printable_binary.ex

@@ -0,0 +1,58 @@
+defmodule PrintableBinary do
+  @moduledoc """
+  Compile-time `~PB` sigil that decodes printable-binary glyphs into a raw binary
+  at COMPILE time — so binary data can be embedded legibly inline in source (no
+  separate fixture files), with zero runtime cost (the bytes are baked into the
+  BEAM).
+
+      import PrintableBinary
+      @magic ~PB"..."   # decoded to raw bytes at compile time
+  """
+
+  @map_path Path.expand("../../character_map.txt", __DIR__)
+  @external_resource @map_path
+
+  # byte<->glyph map parsed from the single-source character_map.txt at compile time
+  # (same parse rules as every other implementation: `##` = comment, first
+  # whitespace-delimited token per line is the glyph, in byte order).
+  @glyph_to_byte @map_path
+                 |> File.read!()
+                 |> String.split("\n")
+                 |> Enum.map(&String.trim_trailing(&1, "\r"))
+                 |> Enum.reject(&(&1 == "" or String.starts_with?(&1, "##")))
+                 |> Enum.map(&(&1 |> String.split() |> hd()))
+                 |> Enum.with_index()
+                 |> Map.new(fn {glyph, byte} -> {glyph, byte} end)
+
+  @doc """
+  Decode a printable-binary string to a raw binary. Whitespace is ignored (the
+  encoding never emits literal whitespace), so wrapped / heredoc input works.
+  Raises `ArgumentError` on an unrecognized glyph.
+  """
+  @spec decode(binary()) :: binary()
+  def decode(string) when is_binary(string) do
+    string
+    |> String.replace(~r/[ \t\r\n]/, "")
+    |> String.codepoints()
+    |> Enum.map(fn cp ->
+      case Map.fetch(@glyph_to_byte, cp) do
+        {:ok, byte} -> byte
+        :error -> raise ArgumentError, "invalid printable-binary glyph: #{inspect(cp)}"
+      end
+    end)
+    |> :erlang.list_to_binary()
+  end
+
+  @doc ~S'''
+  The `~PB` sigil: decodes printable-binary content to a raw binary at compile
+  time. Use `"..."` or a `"""` heredoc (a literal `"` never appears in the
+  payload, so it can't close the sigil early).
+
+      iex> import PrintableBinary
+      iex> ~PB"AB"
+      "AB"
+  '''
+  defmacro sigil_PB({:"<<>>", _meta, [string]}, _modifiers) when is_binary(string) do
+    decode(string)
+  end
+end

elixir/mix.exs

@@ -0,0 +1,15 @@
+defmodule PrintableBinary.MixProject do
+  use Mix.Project
+
+  def project do
+    [
+      app: :printable_binary,
+      version: "0.1.0",
+      elixir: "~> 1.15",
+      description: "Compile-time ~PB sigil: printable-binary glyphs -> raw binary",
+      deps: []
+    ]
+  end
+
+  def application, do: []
+end

elixir/test/printable_binary_test.exs

@@ -0,0 +1,42 @@
+defmodule PrintableBinaryTest do
+  use ExUnit.Case, async: true
+  import PrintableBinary
+  doctest PrintableBinary
+
+  test "~PB decodes passthrough ASCII to itself" do
+    assert ~PB"AB" == "AB"
+  end
+
+  test "~PB decodes control-char glyphs (byte 0 -> ·)" do
+    assert PrintableBinary.decode("·") == <<0>>
+  end
+
+  test "whitespace inside the sigil is ignored (heredoc/wrapping-safe)" do
+    assert ~PB"A B" == "AB"
+    assert ~PB"""
+           A
+           B
+           """ == "AB"
+  end
+
+  test "decode/1 round-trips all 256 single-byte glyphs" do
+    # Build the inverse (byte -> glyph) from the same source, then decode each glyph.
+    byte_to_glyph =
+      Path.expand("../../character_map.txt", __DIR__)
+      |> File.read!()
+      |> String.split("\n")
+      |> Enum.map(&String.trim_trailing(&1, "\r"))
+      |> Enum.reject(&(&1 == "" or String.starts_with?(&1, "##")))
+      |> Enum.map(&(&1 |> String.split() |> hd()))
+
+    assert length(byte_to_glyph) == 256
+
+    for {glyph, byte} <- Enum.with_index(byte_to_glyph) do
+      assert PrintableBinary.decode(glyph) == <<byte>>, "byte #{byte} glyph #{inspect(glyph)}"
+    end
+  end
+
+  test "unrecognized glyph raises" do
+    assert_raise ArgumentError, fn -> PrintableBinary.decode("🚫") end
+  end
+end

elixir/test/test_helper.exs

@@ -0,0 +1 @@
+ExUnit.start()

flake.nix

@@ -208,6 +208,9 @@
               rustc
               clippy
               rustfmt
+
+              # Elixir/Erlang (the ~PB compile-time sigil demo)
+              elixir
             ]  ++ lib.optionals stdenv.isDarwin [ lldb ]
                ++ lib.optionals (!stdenv.isDarwin) [ gdb ]
                ++ linuxOnly;
@@ -438,6 +441,37 @@
             installPhase = "mkdir -p $out && touch $out/passed";
           };
 
+          # ~PB compile-time sigil (Elixir). Runs the crate's own unit + doctest
+          # suite, then the MFIC cross-impl guard: the Zig CLI is the INDEPENDENT
+          # encoder oracle (Elixir did not write it), so Elixir decode/1 must
+          # reproduce the original bytes for all 256 single bytes AND an 8 KiB
+          # random multi-byte stream (exercises 2/3-byte glyph boundaries).
+          test-elixir = pkgs.stdenv.mkDerivation {
+            name = "test-elixir";
+            src = ./.;
+            nativeBuildInputs = with pkgs; [ elixir zig ];
+            buildPhase = ''
+              export HOME=$TMPDIR
+              export MIX_HOME=$TMPDIR/mix
+              export HEX_HOME=$TMPDIR/hex
+              ( cd elixir && mix test --no-deps-check )
+              zig build
+              for i in $(seq 0 255); do printf "\\$(printf '%03o' "$i")"; done > allbytes
+              head -c 8192 /dev/urandom > rand.bin
+              PRINTABLE_BINARY_MUTE_STATS=1 ./zig-out/bin/printable-binary-zig < allbytes > z_all.out
+              PRINTABLE_BINARY_MUTE_STATS=1 ./zig-out/bin/printable-binary-zig < rand.bin  > z_rand.out
+              ( cd elixir && mix run --no-start -e '
+                  for {enc, orig} <- [{"../z_all.out", "../allbytes"}, {"../z_rand.out", "../rand.bin"}] do
+                    got = PrintableBinary.decode(File.read!(enc))
+                    exp = File.read!(orig)
+                    if got != exp, do: raise "Elixir decode(Zig encode) mismatch for #{enc}"
+                  end
+                  IO.puts("Elixir decode(Zig encode) == original for all-256 + 8KiB random")
+              ' )
+            '';
+            installPhase = "mkdir -p $out && touch $out/passed";
+          };
+
           # Dogfood the C FFI boundary: build the C FFI CLI against the Zig static
           # lib and round-trip through it (encode/decode + hexlike).
           test-ffi-cli = pkgs.stdenv.mkDerivation {