A validation suite for binary-in-text encoding patterns, from uuencode (1980) to org-mode babel blocks (2026). Every encoding claim is an executable round-trip test.

Codex Wallerstein (c. 1470) — the Mordhau technique. Binary data, like a sword, must sometimes be disguised to pass through hostile channels.

Foundational Axiom: A binary artifact must survive transit through a channel that only tolerates text.

Every encoding system solves the same constraint:

• 7-bit SMTP channels reject 8-bit bytes
• Text editors corrupt binary data
• Patch utilities expect printable ASCII
• Email headers have strict character limits

The solutions all converge on the same structure:

┌─────────────────────────────────────────┐
│  HEADER   name / type / encoding hint   │
│  PAYLOAD  ascii-safe encoded bytes      │
│  FOOTER   end marker / checksum         │
└─────────────────────────────────────────┘

// JSON Schema for base64-encoded PNG
{
  "type": "string",
  "contentEncoding": "base64",
  "contentMediaType": "image/png"
}

Gladiatoria (c. 1430) — armored combat. Like knights donning armor, binary data dons ASCII encoding to survive hostile text channels.

• spec.org — Literate test suite (the spec is the tests)
• bin/check-prereqs.sh — Tool availability check
• bin/test-*.sh — Round-trip tests for each encoding
• elisp/display-helpers.el — Org-mode inline image support
• Makefile — Tangle and test runner

# Clone
git clone https://github.com/aygp-dr/ascii-armor.git
cd ascii-armor

# Check prerequisites
make prereq

# Generate fixtures and run tests
make test

# Or execute the entire spec in Emacs
make test-org

Base system (already installed):

• uuencode / uudecode
• b64encode / b64decode
• xxd

Packages:

pkg install git              # Required
pkg install sharutils        # Optional: GNU shar
pkg install ImageMagick7     # Optional: XBM/XPM conversion

See INSTALL-FREEBSD.md for details.

Every #+begin_src block in spec.org is executable via C-c C-c. If it cannot be executed, it is marked :eval no.

For each encoding, the test is:

encode(decode(encode(x))) == encode(x)

Partial coverage (encode only) is not sufficient.

Every shell block verifies tools are on PATH before use. Missing tools produce structured JSON errors, not silent failures.

Open hypotheses are tracked and testable:

ascii-armor/
├── spec.org              # Literate test suite (source of truth)
├── CLAUDE.md             # Agent instructions
├── Makefile              # Build/test runner
├── INSTALL-FREEBSD.md    # Package installation guide
├── bin/
│   ├── check-prereqs.sh  # Tool availability check
│   ├── test-uuencode.sh  # uuencode round-trip
│   ├── test-b64encode.sh # base64 round-trip
│   └── ...
├── elisp/
│   └── display-helpers.el
├── resources/
│   ├── codex-wallerstein-107v.jpg
│   ├── gladiatoria-kk5013-28v.jpg
│   └── SOURCES.md
└── archive/
    └── spec-v1-*.org     # Previous spec versions

• uuencode (Wikipedia)
• RFC 2045 (MIME)
• RFC 2397 (data URI)
• XBM (Wikipedia)
• Ascii85 (Wikipedia)
• Org Babel Manual
• Kansas City Standard (Wikipedia)
• BASICODE (Wikipedia)
• NOAA APT Reception (RTL-SDR)
• JSON Schema: contentEncoding
• OpenAPI 3.1 Specification
• MTOM/XOP Binary Optimization

MIT

Medieval fencing manuscripts from Wikimedia Commons (public domain):

• Codex Wallerstein (c. 1470) — Universitätsbibliothek Augsburg
• Gladiatoria Ms. KK5013 (c. 1430) — Kunsthistorisches Museum Vienna