iconvex_retro

# Iconvex Retro

`iconvex_retro` adds pure-Elixir codecs for machines and media whose character
sets were measured in card punches, six-bit words, terminal glyph ROMs, and
video-memory cells rather than modern octets.

It contains exactly the frozen package surface:

- 192 byte-stream codecs and aliases
- 23 logical non-octet codecs
- 57 named packed profiles, each with MSB- and LSB-first transports
- 2 Unicode IBMGRAPH table providers

## Install

```elixir
def deps do
  [
    {:iconvex, "~> 0.1.1"},
    {:iconvex_retro, "~> 0.1"}
  ]
end
```

Starting the application installs every route and provider atomically. Stopping
it removes them atomically; a collision rolls the entire transaction back.

## Six-bit machines

```elixir
{:ok, bytes} = Iconvex.convert("HELLO", "UTF-8", "DEC-SIXBIT")
{:ok, "HELLO"} = Iconvex.convert(bytes, "DEC-SIXBIT", "UTF-8")

{:ok, packed} =
  Iconvex.Retro.Packed.encode_from_utf8(
    "HELLO",
    "DEC-SIXBIT-PACKED-MSB"
  )

{:ok, "HELLO"} =
  Iconvex.Retro.Packed.decode_to_utf8(
    packed,
    "DEC-SIXBIT-PACKED-MSB"
  )
```

The same packed API covers CDC Display Code, FIELDATA, PDP-1 concise codes,
Apple-1 Signetics 2513, UNIVAC I, DEC national replacement sets, and DEC
terminal graphics.

## Punched cards as real 12-bit values

Logical card codecs preserve masks as twelve contiguous bits. Explicit 16BE and
16LE word transports remain normal registry codecs.

```elixir
alias Iconvex.Retro.IBM7040HReport

{:ok, card_bits} = IBM7040HReport.encode_packed(~c"HELLO")
{:ok, ~c"HELLO"} = IBM7040HReport.decode_packed(card_bits)

{:ok, words} = Iconvex.convert("HELLO", "UTF-8", "IBM-7040-H-REPORT-16BE")
{:ok, "HELLO"} = Iconvex.convert(words, "IBM-7040-H-REPORT-16BE", "UTF-8")
```

The package includes IBM 7040/7044, IBM 1401, CDC 167 and 6000, University of
Iowa reconstructions, and all ten IBM 24/26 Figure 23 arrangements.

## Video memory and terminal ROMs

The WG2 N5028 family provides 70 separately named mappings for Apple II,
Atari, Commodore, TRS-80, ZX Spectrum, teletext, RISC OS, and other historical
systems. Video order and interchange order remain separate encodings.

```elixir
{:ok, utf8} = Iconvex.convert(memory, "ATASCII-GRAPHICS-VIDEO", "UTF-8")
{:ok, screen_bytes} = Iconvex.convert("┌─┐", "UTF-8", "IBMGRAPH")
```

Other source-qualified highlights include Kermit JIS7 Kanji, DEC Hebrew and
SI 960, DEC Special/Technical, TI-83 Plus, TI-89 AMS 2.0, Mattel Aquarius,
Stanford RFC 698 graphics, ABC 800 character mode, and Kermit vendor sets.

## Discover the exact surface

```elixir
Iconvex.Retro.encodings()          # 192 registry names
Iconvex.Retro.non_octet_encodings() # 23 logical names
Iconvex.Retro.packed_profiles()     # 57 width/order maps
Iconvex.Retro.provider_ids()        # IBMGRAPH providers
```

The machine-readable authority is `SURFACE_MANIFEST.tsv`; the three generated
CSV inventories are convenient release views. Run:

```console
elixir tools/generate_surface_module.exs --check
```

to prove that the public module and inventories still match the frozen
manifest.

## Verification and provenance

The test suite ports the original family tests and fixtures, exhausts byte and
fixed-width domains where finite, checks the complete Unicode scalar corpus for
accidental encoder keys, exercises streaming/error offsets, and runs focused
performance gates against independent source-derived loops.

Large historical scans remain repository-only evidence. The Hex artifact ships
compact transcriptions, mapping attachments, required notices, and runtime
tables. Original Iconvex code is LGPL-2.1-or-later; separately licensed inputs
retain their Apache-2.0, Unicode-3.0, or Kermit BSD-3-Clause terms.