iconvex_extras

# Benchmarks

Run the production benchmark with:

```sh
ICONVEX_PATH=../iconvex MIX_ENV=prod mix run bench/benchmark.exs
```

It compares CP943 from this external package with core CP932 over byte-identical
mapping data, in both directions. This isolates package/registry dispatch from
codec algorithm and input differences. Results from the release verification
run are recorded below.

Apple M1, OTP 28, Elixir 1.19.5; median of 12 measured iterations after 3
warmups:

| Conversion | Throughput | Median | Reductions |
|---|---:|---:|---:|
| Core CP932 -> UTF-8 | 8.27 MiB/s | 88.61 ms | 2,566,932 |
| Extras CP943 -> UTF-8 | 8.14 MiB/s | 89.98 ms | 2,590,570 |
| UTF-8 -> core CP932 | 30.76 MiB/s | 35.72 ms | 1,688,833 |
| UTF-8 -> extras CP943 | 30.57 MiB/s | 35.93 ms | 1,691,730 |

Relative external-package cost is 1.6% for decoding and 0.6% for encoding in
this paired run. Both paths use the same packed data and native linear codec
engine; the difference is external registry and table-provider dispatch.

## Fair GNU conversion-engine gate

The exhaustive differential does not time `System.cmd/3`. The pinned GNU CLI
still produces the correctness bytes, but its process startup, file reads, and
stdout are excluded from performance ratios. A C11 helper under `tools/`,
linked to the GNU libiconv 1.19 prefix derived from `--iconv`, reads each input
before an internal `CLOCK_MONOTONIC` window and reports conversion-engine time
in fractional microseconds. Iconvex is measured with the same input already in
memory. Each side calibrates one fixed iteration count using the fastest of
three probes at every doubling. Calibration stops only when that fastest probe
reaches 10,000,000 ns, which means all three crossed the threshold and one
preempted probe cannot choose a batch that is too small. Each side then reports
the fastest of three final batches at that fixed count. Fractional per-call
values need no denominator clamp; forward and reverse ratios retain the
independent 30x gate.

The final Extras-owned hotspot smoke after the review fixes used every one of
the 1,114,112 UCS-4BE code points and GNU `//IGNORE`. Both encoded streams,
both own round trips, and both cross-decodes were byte-exact:

| Codec/direction | Iconvex | GNU engine | Slowdown |
|---|---:|---:|---:|
| EUC-JISX0213 forward | 11,061.534 µs | 3,751.5395 µs | 2.95x |
| EUC-JISX0213 reverse | 898.4010625 µs | 58.402242 µs | 15.38x |
| CP943 forward | 40,037.268 µs | 9,927.0355 µs | 4.03x |
| CP943 reverse | 1,107.894 µs | 52.969699 µs | 20.92x |

The helper also checks that its converted byte count equals the independently
captured CLI output size on every timed direction. It is offline benchmark and
test tooling only; the Extras runtime has no C, NIF, or port dependency.

The final independent full run took 151,134 ms: all 198 codecs were byte-exact
with zero performance failures, and ISO-2022-CN was worst at 24.80x.