v0.1.0 — 538 Hexagon kernels that actually use the accelerator

538 Hexagon NSP kernels, every one carrying HVX or HMX intrinsics — each with a scalar reference to check it against, the prompt that produced it, and normalised metadata. A scalar C file is never a library entry here; it ships as reference.c, which is a different job.

pip install hexkernels          # no SDK, no hardware needed to browse the corpus

from hexkernels.library import find
find(hmx=True)                  # 73 kernels that reach the matrix engine
find(origin="expert")           # 350 hand-written, with measured speedups
find(elf_confirmed=True)        # 9 the disassembler confirms, not just the source

The library

origin	n	what it attests
expert	350	Hand-written, each measured against its own scalar baseline on the simulator. Median speedup 3.39×, p90 18.2×, best 124.7×. Ships 421 near-miss kernels alongside — plausible wrong implementations the harness must reject.
mined	171	Written against operators mined from the PyTorch registry. 126 carry a tier mismatch, recorded in provenance.tier_match rather than hidden — they will trip the static entitlement gate until a re-mine moves them.
model	17	Written by a language model; the survivors of 1,920 attempts.

73 reach HMX. Spread across fp32 (168), int8 (96), fp16 (36), uint8 (29), int16 (18) and mixed-precision variants; task tiers T0–T3 for the 188 entries that carry one.

Every entry has the same shape, so a consumer never branches on origin. The entry point is always candidate_kernel. kernels/index.json is the whole corpus in one file; tools/assemble_library.py rebuilds it.

What ships with each kernel

467 entries are bundle: complete — reference and harness both present. The other 71 are harness-regenerable: a harness embeds its golden vectors as base64, so its size tracks the task's working set rather than its complexity, and those 71 alone would have been 675 MB of an otherwise 16 MB corpus (largest single file: 93 MB). They ship a HARNESS.md carrying the one command that regenerates it in ~14 s per batch. Nothing that cannot be reproduced from the task definition was dropped.

Anti-cheat: why this repo exists

A working scalar loop passes a correctness test and often beats a mediocre vectorised kernel on cycles. A score based on speed therefore actively rewards not using the accelerator. Correctness and speed both fail as evidence, so the verdict is read off the disassembled ELF instead.

All 17 model-written kernels have HVX intrinsics in the source. Of the 12 that were scanned:

ELF verdict	n
confirms the mechanism	9
refutes it	3
never scanned	5

Writing the intrinsic is not the same as the binary containing it. elf_confirmed is deliberately tri-state — null means never scanned, which is not the same claim as scanned-and-absent, and collapsing the two would overstate what is known.

Also included

• hexkernels/forge/ — the agentic pipeline: PyTorch operator → Linalg IR → MLIR fusion → affine loops → portable scalar C, which is then the question, not the answer. A kernel without an FX graph or real Linalg IR is not a product of this pipeline.
• hexkernels/gym/ — profile-and-tune loop: the model writes a kernel, a profiler names the bottleneck, and it is told which mechanism is missing.
• hexkernels/core/ — toolchain wrapper, target detection, simulator fleet, reward.
• hexkernels/device/qdc/ — on-silicon measurement. verdict.py is vendored in full because it is what keeps a false pass off the money path: a job that ran zero tests once reported passing, and cycles_total=0 satisfied a check that only tested for the substring.

Known limits

• The mined kernels are not verified against the tasks they are filed under — see provenance.tier_match and docs/study/MINED-PROVENANCE.md before using one.
• The 350 expert kernels are attested by measured cycles, not by an ELF scan; elf_confirmed is null for all of them.
• Building, simulating or scanning needs the Hexagon SDK. Loading and querying the corpus needs nothing.
• Never parallelise hexagon-sim — see docs/MEASUREMENT.md. That rule cost 352 discarded verdicts to learn.

25 tests pass, covering the admission rule, that no reference.c is itself vectorised, the tri-state invariant, and every QDC false-pass shape.

🤖 Generated with Claude Code