feat: [U4-B] benchmark kernels + lowering/correctness/limitations wri…

[DenkuKuro]

U4-B — Benchmark kernels + write-ups

Every per-operation lowering is derived and verified, so this ticket produces
what we benchmark and what we present.

Benchmark kernels

bench/ compiles each kernel twice from the same .ll: baseline straight to
llc -O3 -mcpu=native (the default legalizer scalarizes the narrow op), and
lowered through opt -passes=nybbler followed by the identical llc line.
The only difference between the two binaries is the pass.

A shared driver.c times only the kernel loop — fixed-seed inputs, no I/O in
the timed region, 20 warmup + 50 timed reps reporting the minimum — and FNV-1a
checksums the output. The checksum both defeats dead-code elimination and gates
the comparison: run.sh refuses to report timings if the two builds disagree.

Kernels: arith_i4 (<32 x i4> add/shl/sub), field_i2 (<64 x i2>
add/lshr/sub), mask_i1 (<128 x i1> bitwise), cmp_i4 (icmp ult → bitmask).

Measured on Ryzen 9 5900HX / AVX2 / LLVM 22.1.8:

kernel	baseline ns/vec	lowered ns/vec	speedup
arith_i4	67.25	5.02	13.40x
field_i2	144.85	2.49	58.27x
cmp_i4	48.50	35.90	1.35x (partial)
mask_i1	1.04	1.04	1.00x

Scalarization markers in the inner loop go 114→0 (arith_i4) and
236→0 (field_i2).

Three findings are documented rather than smoothed over:

• Kernels must keep loads/stores at byte type. Written the obvious way
  (load <32 x i4>), the lowered build is worse — the narrow load scalarizes
  in both builds and the pass must then repack. Recorded as a caller constraint.
• mask_i1 shows no speedup because LLVM already reinterprets <K x i1>
  bitwise as bytes. Reported at face value: the speedup claim rests on the
  masked paths, not the correct-by-construction bitwise case.
• cmp_i4 is a lower bound — the pass lowers the icmp but not the bitcast
  materializing its <K x i1> result, which dominates both builds.

Write-ups

• docs/lowering.md — carrier dispatch, SWAR add/sub carry and borrow
  containment, per-field shift masking, ashr sign handling, compare lowerings.
• docs/correctness.md — why bitwise is correct by construction, how the masked
  paths keep carries and shifted-in bits inside their field, and what verifies it.
• docs/benchmarks.md — methodology, results, and limitations (no mul/div,
  vertical ops only, icmp limited to eq/ne/ult/slt, untouched narrow
  loads/stores, the padding path's cost on non-byte-multiple widths).

README.md refreshed — it still described Slice 1 (bitwise only,
non-byte-multiple vectors skipped), superseded three commits ago.

Testing

test/bench_checksum.test wires the checksum gate into lit — correctness only,
since CI runners are too noisy for a speedup threshold. Full suite 58/58 on the
default seed and on NYBBLER_DIFF_SEED=1234. No changes to lib/Nybbler.cpp.

closes #10