ryg-rans-rs-cli

Production-grade rANS compression CLI — ryg-rans
Versioned block-streaming container format (RYGRANS v1).
SHA-256 integrity verification. Resource-bounded, deterministic, non-panicking.
Encode, decode, inspect, verify, compare, benchmark, trace.
10 codec formats · 6 decode backends · 10 stable exit codes · 5 shell completions.

Table of Contents

1. What This Crate Is
2. Commands
3. Container Format
4. Codec vs Backend Distinction
5. Safety Guarantees
6. Exit Codes
7. Architecture
8. Examples

What This Crate Is

This crate provides the ryg-rans command-line tool for rANS entropy coding. It is a production-grade implementation built on the repository's sealed rANS primitives.

Design Principles

1. #![forbid(unsafe_code)] — the CLI crate is entirely safe Rust. All SIMD acceleration is accessed through the facade crate's safe APIs with runtime feature detection.
2. Versioned container format — RYGRANS v1 is a block-streaming format with explicit fields, bounds checking, and SHA-256 integrity verification at both the block and stream level.
3. Resource limits — every command enforces configurable limits on input size, output size, block size, block count, and memory. Limits are checked during reading, not after.
4. Deterministic output — identical input + options → byte-identical container. No timestamps, random identifiers, or host-dependent values.
5. Strict validation — every field, bound, and hash is verified. Unknown format versions, unsupported codecs, and trailing data are all rejected.

Commands

Container Format

RYGRANS v1 — a versioned block-streaming container:

┌─────────────────────┐
│ File Header (32 B)  │  ← magic "RYGRANS\0", version, flags, codec, block size
├─────────────────────┤
│ Block Record 0      │  ← header (104 B) + model + payload
│   (RAW/RLE/RANS)    │     per-block SHA-256 integrity
├─────────────────────┤
│ Block Record 1      │
│   ...               │
├─────────────────────┤
│ Footer (104 B)      │  ← block count, totals, container + stream SHA-256
└─────────────────────┘

Block Kinds

Block selection is deterministic: RANS is used only if it's strictly smaller than RAW.

See docs/container-format-v1.md for the full specification.

Codec vs Backend Distinction

Codec IDs (Stream Format)

Codec IDs identify the stream format — the number of states, renormalization unit, and scale constraint:

Backends (Implementation Choice)

Backends are not codec IDs. Division vs reciprocal are arithmetic implementations. SSE4.1 vs AVX-512 are decode backends. When two implementations produce the same canonical stream, that distinction belongs in execution metadata, not the format ID.

Safety Guarantees

Exit Codes

Architecture

main.rs                    → thin entry point (parse args → call lib → return ExitCode)
lib.rs                     → command routing + capabilities + completions
container/
  mod.rs                   → constants (magic, sizes, block kinds)
  header.rs                → FileHeader: 32-byte fixed-size header
  block.rs                 → Block: 104-byte header + model + payload
  footer.rs                → FileFooter: 104-byte footer + SHA-256 hashes
  codec.rs                 → Codec registry: 10 IDs, scale validation, state counts
  model.rs                 → FrequencyModel: canonical normalization (integer only)
  reader.rs                → ContainerReader: streaming parser with validation
  writer.rs                → ContainerWriter: streaming serializer with hashing
error.rs                   → AppError: 10 typed variants with structured context
exit.rs                    → 10 stable exit codes with documentation
limits.rs                  → Limits: central resource bounds, size parsing

Examples

# Encode a file
ryg-rans encode --input input.bin --output input.bin.rygr

# Decode a container
ryg-rans decode --input archive.rygr --output restored.bin

# Encode from stdin to stdout
cat input.bin | ryg-rans encode --input - --output archive.rygr

# Decode to stdout (verified spool — no output until verification passes)
ryg-rans decode --input archive.rygr --output -

# Inspect container structure
ryg-rans inspect --input archive.rygr --output-format json

# Verify integrity with all available backends
ryg-rans verify --input archive.rygr --backend all-available

# Build a frequency model
ryg-rans model build --input input.bin --scale-bits 12 --output model.json

# Show capabilities in JSON
ryg-rans capabilities --output-format json

# Generate bash completions
ryg-rans completions bash > /etc/bash_completion.d/ryg-rans