kernelport 0.1.0__tar.gz → 0.2.0__tar.gz

{kernelport-0.1.0 → kernelport-0.2.0}/.github/workflows/ci.yml

@@ -62,13 +62,22 @@ jobs:
         run: kernelport zoo --backend metal --no-bench
       - name: llm.c example (Metal ports vs references frozen on NVIDIA)
         working-directory: examples/llm.c
+        run: |
+          kernelport verify --backend metal
+          kernelport pipeline gpt2_embed_gelu_residual --backend metal
+          kernelport status
+      - name: flash-attention-minimal example (Metal port vs reference frozen on NVIDIA)
+        working-directory: examples/flash-attention-minimal
         run: |
           kernelport verify --backend metal
           kernelport status
       - uses: actions/upload-artifact@v4
         with:
           name: llmc-results-metal
-          path: examples/llm.c/.kernelport/kernels/*/ports/metal/results/*.json
+          path: |
+            examples/llm.c/.kernelport/kernels/*/ports/metal/results/*.json
+            examples/llm.c/.kernelport/pipelines/results/*/metal/*.json
+            examples/flash-attention-minimal/.kernelport/kernels/*/ports/metal/results/*.json
 
   webgpu:
     # WGSL ports through wgpu-native: Mesa llvmpipe (software Vulkan) on Linux, Metal on macOS.
@@ -99,15 +108,25 @@ jobs:
         run: python -m pytest -q -rs tests/test_webgpu_backend.py
       - name: WebGPU zoo
         run: kernelport zoo --backend webgpu --no-bench
+      - name: Browser check (docs/web in headless Chrome; Tint, not naga, compiles the WGSL)
+        # Chrome's adapter: SwiftShader on Linux, the Apple GPU on macOS
+        run: python scripts/check_web_demo.py --timeout 240
       - name: llm.c example (WGSL ports vs references frozen on NVIDIA)
         working-directory: examples/llm.c
         run: |
           kernelport verify --backend webgpu
           kernelport status
+      - name: flash-attention-minimal example (WGSL port vs reference frozen on NVIDIA)
+        working-directory: examples/flash-attention-minimal
+        run: |
+          kernelport verify --backend webgpu
+          kernelport status
       - uses: actions/upload-artifact@v4
         with:
           name: llmc-results-webgpu-${{ matrix.os }}
-          path: examples/llm.c/.kernelport/kernels/*/ports/webgpu/results/*.json
+          path: |
+            examples/llm.c/.kernelport/kernels/*/ports/webgpu/results/*.json
+            examples/flash-attention-minimal/.kernelport/kernels/*/ports/webgpu/results/*.json
 
   package:
     name: build sdist + wheel

{kernelport-0.1.0 → kernelport-0.2.0}/.gitignore

@@ -10,3 +10,6 @@ build/
 
 # Committed example workspaces (frozen references, ports, results) are part of the repo.
 !examples/*/.kernelport/
+
+# local drafts of upstream issues (not published)
+drafts/

kernelport-0.2.0/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+## 0.2.0 (2026-11-02)
+
+**Multi-kernel pipelines**
+- Run ported kernels in a chain and check every stage on the data it really gets
+  (`kernelport pipeline`, MCP tools `write_pipeline` and `verify_pipeline`).
+- Time the chain of ports against the chain of original CUDA kernels, whole and per stage
+  (`kernelport pipeline <name> --bench`, MCP tool `bench_pipeline`). A stage is called slower only if
+  it loses every one of 5 rounds.
+- Pipelines show up in `kernelport status` and the HTML/Markdown reports.
+
+**New static checks** (warnings from `scan_kernels`, the hazards that pass runtime tests on today's
+NVIDIA GPUs and break elsewhere)
+- A lane can exit before a full-mask warp shuffle (`__shfl_*_sync(0xffffffff, ...)`). This flags the
+  two softmax kernels fixed upstream in karpathy/llm.c#867.
+- Some threads can miss a `__syncthreads()`: a thread-dependent early return before it, or the
+  barrier inside a branch or loop that differs between threads.
+
+**WebGPU**
+- The runner refuses WGSL that wgpu-native accepts but browsers reject or run differently: a
+  non-uniform `workgroupBarrier()`, float literals beyond `f32` range, and a `var` without initializer
+  inside a loop (wgpu-native 29 zeroes it once instead of every iteration).
+- In-browser check (`docs/web`): runs 15 WGSL ports (the 12 zoo kernels, two llm.c kernels and the
+  FlashAttention forward pass) on the viewer's GPU against kernelport's own cases and tolerances,
+  float32 and float16. CI runs it in headless Chrome. `docs/index.html` is a landing page for
+  GitHub Pages.
+- The Colab notebook has a self-test section that runs the zoo and the llm.c example on the T4.
+- `shader-f16` support is checked when a shader runs, not when binding text is generated.
+
+**Analyzer**
+- Kernels defined through macros (`#define KERNEL __global__`, `FOR_TYPES(DEFINE_X)`, `C_KERNEL(name)`)
+  are found, with a small cpp-style macro expander.
+- Survives braces opened separately in each `#if` branch.
+
+**Examples**
+- `examples/flash-attention-minimal`: the unmodified `flash.cu` ported to Triton (23x the original),
+  Metal and WGSL, all PASS.
+- `examples/llm.c`: two pipelines (GPT-2 loss head; bf16 encoder, GELU, residual).
+
+**CLI and reports**
+- `kernelport verify softmax` and `bench softmax` take the kernel id as an argument; unknown ids are
+  usage errors.
+- Reports lead with a headline (kernels verified, PASS results, hardware targets) and each PASS cell
+  shows the hardware and speedup.
+- The README has an animated recording of a real session (`scripts/record_demo.py`).
+
+**Fixes**
+- Benchmarks of very short kernels no longer flag noise as a slowdown.
+- WebGPU tests: a deliberately racy port may pass on a CPU adapter, so that case is skipped there
+  instead of failing.
+
+## 0.1.0 (2026-10-14)
+
+First release: MCP server, agent skill and CLI; Triton, Metal, WebGPU and CPU backends verified,
+HIP written but not run on AMD hardware; 12-kernel zoo; the llm.c example.

kernelport-0.2.0/HANDOFF.md

@@ -0,0 +1,168 @@
+# kernelport: handoff notes
+
+*Last updated 2026-11-02. Read this first when resuming. Deeper detail: [PROGRESS.md](PROGRESS.md)
+(full technical history), [LAUNCH_PLAN.md](LAUNCH_PLAN.md) (launch strategy), [RELEASING.md](RELEASING.md)
+(publishing).*
+
+## Where things stand
+
+kernelport 0.1.0 is on [PyPI](https://pypi.org/project/kernelport/), and the llm.c bug it found is
+fixed upstream in an open PR, [karpathy/llm.c#867](https://github.com/karpathy/llm.c/pull/867).
+CI is green on Linux, Windows, macOS, Apple Silicon (Metal), two WebGPU adapters and headless Chrome
+(the in-browser check). HIP (AMD) is the only backend never run on its real hardware.
+
+| Measure | Estimate | What's missing |
+|---|---|---|
+| Public v0.1 (installable, works, honest about status) | ~95% | AMD verification |
+| Ready to launch publicly | ~85% | Agent demo video, GitHub Pages switched on, a first Linux + NVIDIA run, launch posts |
+| Mature product | ~75% | More agents tested, AMD, pipeline timing |
+
+## What is verified
+
+| Backend | Status | Evidence |
+|---|---|---|
+| Triton | Working | 12/12 zoo + 9/9 llm.c ports pass on RTX 5060 (Windows); 1.0-1.3x the original CUDA, matmul 6.2x |
+| Metal (MLX) | Working | 12/12 zoo + 5/5 llm.c + flash-attention ports pass on Apple M1, checked by CI on every push |
+| WebGPU (WGSL) | Working | 12/12 zoo pass on NVIDIA (Vulkan), Apple (Metal) and llvmpipe; 2/2 llm.c fp32 ports + flash-attention pass on all three; in browsers 24/24 (fp32 + fp16) on RTX 5060 + Intel UHD (Edge), and in Chrome on SwiftShader + Apple (CI) |
+| CPU (Numba) | Working | 12/12 zoo pass (fp32) |
+| HIP (AMD) | Unverified | Ports written; `scripts/amd_check.sh` ready to run on an AMD machine |
+
+- **Real code:** `examples/llm.c` has 9 kernels from unmodified llm.c files (host code, cuBLAS headers,
+  `Packed128` templates), 20 PASS results across 5 hardware targets.
+- **Fresh-agent test:** a coding agent with no context ported 4 new llm.c kernels; all 4 passed on the
+  first verification, and its feedback was fixed.
+- **Install:** a clean `pip install kernelport` from PyPI was checked.
+
+## What was done on 2026-10-14
+
+| Area | Change |
+|---|---|
+| Release | 0.1.0 published to PyPI via tag-triggered `release.yml` with trusted publishing; install docs use `pip install kernelport`; `main` is 0.1.1.dev0 |
+| CI | Tests on Linux, Windows, macOS; Metal zoo + llm.c on GitHub's Apple M1 runner; WebGPU on llvmpipe and Apple Metal; wheel build check |
+| Real code | Host-code slicer (`kernelport/harness/device_source.py`) compiles real .cu files (main(), cuBLAS, stdio) with NVRTC; `examples/llm.c` with 9 kernels |
+| llm.c bug | `softmax_forward_online_kernel8` leaves rows unwritten when C < block size; fix tested 90/90, posted by the owner as PR #867 from fork PS12007/llm.c |
+| Fresh-agent test | 4/4 first-try passes; fixes from its feedback: float scalars rounded to their dtype, guide gaps, Windows console crash, clearer tune/bench output |
+| Tuning | New `tune_port` tool (12th tool): verifies every variant, keeps only clear, noise-resistant wins |
+| Benchmarks | Timer no longer measures Python launch overhead; 3 alternating runs with ranges and a noise warning |
+| No NVIDIA locally | `kernelport validate --all` + Colab notebook to freeze references once on a free GPU |
+| Device limits | Cases too big for an adapter are reported as not tested instead of failing the port |
+| Robustness | Line-ending-insensitive hashes; LF workspace files; readable status table when piped |
+
+## What was done on 2026-10-15
+
+| Area | Change |
+|---|---|
+| Macro-defined kernels | `kernelport/analyzer/macros.py`, a small cpp-style expander (`#`, `##`, variadics, `FOR_TYPES(DEFINE_X)`). The analyzer finds kernels stamped out by macros, marked by `#define KERNEL __global__`, or opened by `C_KERNEL(name)(...)`, and records `generated_by`. The NVRTC slicer treats top-level macro calls as items of their own (kept if device code, blanked if host only). Tests: `tests/test_macros.py`, including a GPU validation of a macro-generated kernel |
+| README demo | `scripts/record_demo.py` records a real CLI session (scan, validate, a broken softmax port FAILs, the fix PASSes, bench, status) and renders `docs/img/demo.svg`, an animated terminal, now at the top of the README. `record` needs CUDA + Triton; `render` re-draws from `docs/demo/transcript.json` |
+| CLI | `kernelport verify softmax` / `bench softmax` take the kernel id as an argument; unknown ids are usage errors; piped output honours `$COLUMNS`; "found 1 kernel" |
+| Report | Headline sentence, readable dark-mode links, PASS cells show hardware + speedup, unstarted kernels folded away; Markdown matches |
+| Browser check | `docs/web/index.html` runs the 12 WGSL ports in the browser's WebGPU against kernelport's own cases (`scripts/build_web_demo.py`, 57 float32 cases, 2.1 MB); 12/12 PASS in Edge on the RTX 5060 and the Intel UHD iGPU; a sabotaged port FAILs. `scripts/check_web_demo.py` runs it headless |
+| Browser bug found | zoo softmax WGSL used `-3.4028235e38` (above FLT_MAX): naga accepts, Chrome/Edge reject. Port and the webgpu skill guide fixed; the runner now refuses out-of-range float literals |
+| FlashAttention example | `examples/flash-attention-minimal`: unmodified `flash.cu` (Apache-2.0), reference validated 6/6 within N <= 384 (beyond that the original's own `__expf`/fp32 rounding exceeds the fixed tolerance; documented, not loosened). Triton PASS at 23x, WGSL PASS on RTX 5060 / Apple / llvmpipe, Metal PASS on M1 (CI results committed). New init `{"dist": "full", "value": "-inf"}` |
+| wgpu-native bug found | A `var` declared without initializer in a loop is zeroed once, not per iteration (WGSL spec, browsers), on every backend. Already fixed upstream in naga (gfx-rs/wgpu#9592, v30), but wgpu-native has no v30 release yet and wgpu-py 0.32 bundles 29.0.1.1. The runner refuses such code. Issue drafted (not posted) in `drafts/` (gitignored) |
+| Browser CI | `scripts/check_web_demo.py` runs in CI's WebGPU jobs: Chrome on SwiftShader (Linux) and Apple GPU (macOS), 12/12 |
+| Failure report | "unexpected NaN" hint also names overflow (inf/inf), not only unwritten elements |
+| CI | Flaky WebGPU test fixed: the racy reduce_sum bad port can PASS on llvmpipe (workgroups run one by one), so it is skipped there; earlier red runs on 2026-10-14 were this flake |
+
+## What was done on 2026-10-17
+
+| Area | Change |
+|---|---|
+| Pipelines | Kernels run in a chain over named buffers (`.kernelport/pipelines/<name>.json`); every stage's port is checked against its frozen reference on the data the stage before really wrote. End-to-end drift vs a float64 chain is reported, never decides. Tools `write_pipeline` / `verify_pipeline` (14 tools), CLI `kernelport pipeline`, rows in `status` and both reports (stale results shown as UNVERIFIED). Backend `cuda` chains the originals |
+| llm.c pipelines | `gpt2_loss_head` (softmax -> crossentropy -> backward) and `gpt2_embed_gelu_residual` (bf16): PASS on Triton and the originals; CI runs the bf16 one on Metal |
+| Why it matters | A crossentropy port that clamps probs to >= 1e-3 passes its own cases and fails the pipeline (test). Drift shows fp32 softmax underflow (inf losses) and bf16 error growth (1.5x a tolerance after 3 kernels, same in the originals) |
+
+## What was done on 2026-10-24
+
+| Area | Change |
+|---|---|
+| llm.c PR #867 | A reviewer found the same early-return bug in `softmax_forward_kernel7`. Fixed on the PR branch (only whole warps exit; same speed), tested 504/504 configs on the RTX 5060. The unfixed kernel also passes there: undefined behaviour that happens to work, so only a static check can catch it. The PR's first commit had turned the file into CRLF (all 733 lines in the diff); restored to LF. **Committed in `C:\-CS\llm.c-fork`, not pushed** |
+| Static warnings | `kernelport/analyzer/hazards.py`: a lane can return early before a full-mask warp shuffle/reduce. Shown by `scan` and `read_kernel`; the skill tells agents to test warp-splitting sizes. Flags exactly kernel7 + kernel8 in llm.c; 1 of 152 llama.cpp kernels |
+| Analyzer crash | A kernel opening a brace in each `#if` branch (llama.cpp `mmf.cuh`) crashed the whole scan; fixed |
+
+## What was done on 2026-10-27
+
+| Area | Change |
+|---|---|
+| Pipeline timing | New `bench_pipeline` tool (15 tools) and `kernelport pipeline <name> --bench`: after a PASS, the chain is run once to capture each stage's real input, then the whole chain of ports and each stage are timed against the original CUDA kernels on those inputs (3 alternating rounds). Saved under `.kernelport/pipelines/results/<name>/<backend>/bench/` |
+| First numbers (RTX 5060, Triton) | `gpt2_loss_head` at B=4, T=64, V=50257: chain 1.00 ms vs 1.33 ms original (1.33x; softmax 1.68x, the two cross-entropy kernels ~0.97x). `gpt2_embed_gelu_residual` (bf16, 4x256x768, ~10 µs kernels): about even (1.0-1.4x between runs) |
+| Timing noise | A first run flagged a "slow" stage that moved between stages on reruns: single rounds of ~10 µs kernels spike up to 3x on this laptop. `bench_pipeline` now uses 5 rounds and names a stage slower only if every port round lost to every original round (as `tune_port` does) |
+| Encoder port | `encoder_forward_kernel3` Triton port rewritten row-wise (one program per token and block of C: one token-id load, no per-element divide): 0.023 vs 0.025 ms for the old port, steady across runs; re-verified 4/4 and the bf16 pipeline PASS |
+| PR #867 reply | Reply to the kernel7 reviewer drafted in `drafts/llm-c-867-kernel7-reply.md` (local, gitignored), with the push steps. Still not pushed or posted |
+
+## What was done on 2026-10-28
+
+| Area | Change |
+|---|---|
+| Barrier warnings | `analyzer/hazards.py` also warns when some threads can miss a `__syncthreads()` (or `block.sync()`, or a `blockReduce` helper): a thread-dependent early return before it, or the barrier inside a branch or loop that differs between threads. Over 340 kernels: 4 loop cases in llm.c (threads can hit the barrier a different number of times), 3 + 4 deliberate early returns in llm.c / llama.cpp (fine on NVIDIA, worded as a porting note), 0 in the zoo. Two llama.cpp false-positive patterns fixed and tested |
+| WGSL gap found | wgpu-native (naga, wgpu 0.32) accepts a `workgroupBarrier()` that browsers reject as non-uniform (checked in Edge). A port could PASS in kernelport and not compile in Chrome. The runner now refuses it with a fix hint; it agrees with Edge on 6 probe shaders and accepts all 15 existing WGSL ports |
+| Skill | SKILL.md, webgpu.md and metal.md: keep every thread alive to each barrier in ports, guard the work instead |
+
+## Next steps (owner)
+
+None of these need API credits.
+
+- [ ] **AMD:** join AMD's AI Developer Program for free Developer Cloud credits, start an MI300X with the
+      ROCm image, run `bash scripts/amd_check.sh`, send back `amd_results.txt`.
+- [ ] **Colab:** open `notebooks/freeze_references_colab.ipynb` in Colab (T4 runtime) and run the
+      cells under "Self-test" only (skip the "Your repo" cells). It runs the zoo originals + Triton
+      ports and the llm.c example, the first Linux + NVIDIA run, and downloads `selftest_results.txt`.
+- [ ] **Demo video/GIF (30-60 s):** one prompt to the agent, FAIL → fix → PASS, the green status
+      table. The biggest launch lever. Step-by-step recording plan in `drafts/demo-video-plan.md`.
+- [ ] **Browser check online:** GitHub repo Settings → Pages → Source "Deploy from a branch" → `main`,
+      folder `/docs` → Save. (Claude can't do this: creating a public site is blocked for it.) Then
+      https://ps12007.github.io/kernelport/ is a landing page and `/web/` the browser check (15 ports,
+      27/27 PASS in Edge on the RTX 5060). `docs/.nojekyll` is already there.
+- [ ] **Launch posts, same day:** Show HN, r/LocalLLaMA, r/MachineLearning, X. Drafts with a
+      pre-post checklist in `drafts/launch-posts.md` (local, gitignored).
+- [x] **PR #867:** kernel7 fix + line-ending restore pushed and the reply posted (2026-11-02); the PR
+      diff is now 1 file, +8 / -8. Keep watching for review comments.
+- [ ] **wgpu loop-var bug (optional):** drafts are ready, not posted, in `drafts/` (local only,
+      gitignored): an issue for pygfx/wgpu-py (`wgpu-loop-var-issue.md`, with
+      `wgpu-loop-var-repro.py`) and a short comment for gfx-rs/wgpu-native PR #630. Already fixed in
+      naga v30 (gfx-rs/wgpu#9592); wgpu-native has no v30 release yet (re-checked 2026-11-02: latest is
+      still v29.0.1.1, #630 still open). Re-check both before posting.
+- [ ] **Release 0.2.0:** version bumped and CHANGELOG.md written (2026-11-02); push the `v0.2.0` tag
+      (RELEASING.md) if it isn't on PyPI yet.
+- [ ] Optional: try Codex, Cursor or Gemini CLI with `kernelport setup`.
+
+Future releases: bump the version in `pyproject.toml` and `kernelport/__init__.py`, then push a
+`vX.Y.Z` tag (see RELEASING.md).
+
+## Ideas to make it better
+
+- **Pipelines, more:** a pipeline in the browser check; a chain with a matmul; why the original encoder's time doubles between sessions.
+- **More real projects:** a cuBLAS-heavy repo, or flash-attention's backward pass (forward is done).
+- **Linux GPU checks:** free CI runners have no GPU; a Colab or Kaggle run per release would cover Linux + NVIDIA.
+- **Browser check, more:** let visitors paste a WGSL port; larger cases as an optional download.
+- **Real Mac timings:** CI's virtual M1 proves correctness but gives no fair speed numbers.
+- **When wgpu-native ships v30:** the loop-var check can stay (harmless); note the fixed version in the message.
+
+Done 2026-10-15 from this list: macro-defined kernels, report polish, browser demo page, FlashAttention example.
+Done 2026-10-17: multi-kernel pipelines. Done 2026-10-27: pipeline timing.
+Done 2026-11-02: llm.c + FlashAttention WGSL ports in the browser check.
+
+**Handy here:** headless Edge runs WebGPU on this laptop (`scripts/check_web_demo.py`; `--discrete` for
+the RTX 5060) and takes screenshots for checking pages (`msedge --headless=new --screenshot=...`).
+`scripts/record_demo.py` re-records the README terminal demo.
+
+## How to resume
+
+Open Claude Code in `C:\-CS\CUDAtoanything` and say "keep working on kernelport".
+
+| What | Where |
+|---|---|
+| Repo | https://github.com/PS12007/kernelport |
+| Package | https://pypi.org/project/kernelport/ |
+| CI runs | https://github.com/PS12007/kernelport/actions |
+| llm.c PR | https://github.com/karpathy/llm.c/pull/867 (branch `fix-softmax-online-kernel8-small-c` on PS12007/llm.c; local clone `C:\-CS\llm.c-fork`, `core.autocrlf=false`) |
+| Environment | `.venv` (Python 3.12, torch 2.11 cu128, triton-windows 3.7, cupy 14.2); run tools as `.venv\Scripts\python.exe` / `.venv\Scripts\kernelport.exe` |
+| Tests | `.venv\Scripts\python.exe -m pytest -q` (~6-8 min; 332 pass, 43 skip for hardware not on this machine; with `wgpu` installed the WebGPU tests run too) |
+
+## Rules to keep
+
+- No large downloads; test installs (e.g. `wgpu`) are removed afterwards.
+- No API credits, ever (owner's choice; nothing requires them).
+- Edits to the real agent config (`~/.claude.json`) are reverted after testing.
+- Nothing is posted publicly (issues, PRs, tags, releases) without the owner's go-ahead.
+- On this Windows box, write code with the editor tools, not shell heredocs (they mangle backslashes and backticks).

kernelport-0.2.0/LAUNCH_PLAN.md

@@ -0,0 +1,74 @@
+# kernelport: status and launch plan
+
+*Updated 2026-10-15. kernelport 0.1.0 on PyPI; see HANDOFF.md for the latest one-page status. Technical history: [PROGRESS.md](PROGRESS.md).*
+
+## Where we are
+
+| Measure | Estimate | Why |
+|---|---|---|
+| Public v0.1 (usable, installable, honest) | **~95%** | Released to PyPI, CI green on 3 OSes + Apple Silicon + 2 WebGPU adapters, real-code example, fresh-agent test passed. Missing: AMD verification. |
+| Launch-ready (could be posted for attention) | **~80%** | Missing: a demo video/GIF, a first run on Linux + NVIDIA (only Windows + NVIDIA so far), launch posts. |
+| Mature product | **~60%** | Lexical analyzer (no C++ front end), single-kernel focus, no multi-kernel pipelines, HIP unverified, only one agent (Claude) tested. |
+
+### Backend status
+
+| Backend | Status | Evidence |
+|---|---|---|
+| Triton | working | 12/12 zoo + 9/9 llm.c ports PASS on RTX 5060 (Windows); 1.0-1.3x the original CUDA on the zoo, matmul 6.2x |
+| Metal (MLX) | working | 12/12 zoo + 5/5 llm.c ports PASS on Apple M1 in CI, every push |
+| WebGPU (WGSL) | working | 12/12 zoo PASS on NVIDIA (Vulkan), Apple (Metal) and llvmpipe (CI); 2/2 llm.c fp32 ports PASS on all three |
+| CPU (Numba) | working | 12/12 zoo PASS (fp32) |
+| HIP (hipRTC) | **unverified** | ports written; `scripts/amd_check.sh` ready for an AMD machine |
+
+### What has been proven
+
+- **Real code:** `examples/llm.c` has 9 kernels from unmodified llm.c files (host code, cuBLAS headers,
+  `Packed128` templates), 20 PASS results across 5 hardware targets.
+- **A real bug found:** validation exposed that llm.c's `softmax_forward_online_kernel8` leaves rows
+  unwritten when C < block size. Fix submitted upstream: karpathy/llm.c#867.
+- **Fresh agent:** a coding agent with no context ported 4 new kernels; 4/4 PASS on the first
+  verification. Its feedback was fixed.
+- **Install:** `pip install kernelport` from PyPI, clean install checked.
+- **Honesty checks:** deliberately broken ports fail for the right reason on every backend; tuning
+  and benchmarks refuse to report noise as speedups.
+
+## Next steps
+
+### Owner actions (need an account, hardware or a decision)
+
+1. **AMD:** get AMD Developer Cloud credits (AMD AI Developer Program), start an MI300X with the
+   ROCm image, run `bash scripts/amd_check.sh`, send back `amd_results.txt`.
+2. **Colab:** run `notebooks/freeze_references_colab.ipynb` once on a free T4. That also gives the
+   first Linux + NVIDIA run.
+3. **Demo video/GIF (30-60 s):** clone a CUDA-only repo, one prompt to the agent, the green status
+   table. This is the single biggest launch lever.
+4. **Launch posts, same day:** Show HN, r/LocalLLaMA, r/MachineLearning, X (MLX and Triton
+   communities). Lead with "proven correct, not just translated" and the llm.c bug.
+5. Optional: try Codex / Cursor / Gemini CLI with `kernelport setup` (all free tiers work; no
+   API credits needed anywhere).
+
+### Engineering that would make it better
+
+- **Linux GPU in CI:** none of the free runners have one; a Colab or Kaggle notebook run per
+  release would cover Linux + NVIDIA.
+- **Multi-kernel pipelines:** verify a sequence (e.g. layernorm -> matmul -> gelu) end to end,
+  not just single kernels.
+- **More real projects:** e.g. a FlashAttention-style kernel or a cuBLAS-heavy repo.
+- **Browser demo page:** paste a CUDA kernel, watch the WGSL port verified on your own GPU.
+- **Report polish:** the HTML report is what people will share.
+- **Physical Mac timings:** CI's virtual M1 verifies correctness but gives no fair speed numbers.
+
+## Could it trend on GitHub?
+
+It has a real chance with a deliberate launch. In its favour: a timely hook (CUDA lock-in, Apple
+Silicon, coding agents), a distinctive angle (other tools translate; none prove ports correct on
+real hardware), a recognisable real-code example (llm.c) plus a real upstream bug fix, and a
+two-minute install. Against: without a demo video it stays abstract, and the "NVIDIA needed once
+for validation" step needs explaining (the Colab notebook answers it).
+
+## Rules kept during development
+
+- No large downloads; anything downloaded for testing is uninstalled afterwards.
+- No API credits spent (owner's choice; nothing requires them).
+- Any edit to real agent config (`~/.claude.json`) is reverted after testing.
+- Nothing is posted publicly (issues, PRs) without the owner's go-ahead.

{kernelport-0.1.0 → kernelport-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: kernelport
-Version: 0.1.0
+Version: 0.2.0
 Summary: Bring CUDA-only kernels to Mac, AMD, browsers, and CPU, with proof they are correct.
 Project-URL: Homepage, https://github.com/PS12007/kernelport
 Project-URL: Documentation, https://github.com/PS12007/kernelport/tree/main/docs
@@ -68,6 +68,7 @@ Description-Content-Type: text/markdown
 # kernelport
 
 [![CI](https://github.com/PS12007/kernelport/actions/workflows/ci.yml/badge.svg)](https://github.com/PS12007/kernelport/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/kernelport)](https://pypi.org/project/kernelport/)
 
 Bring CUDA-only kernels to Mac, AMD, browsers, and CPU, with proof they are correct.
 
@@ -76,10 +77,15 @@ Cursor, Gemini CLI) writes the ports; kernelport runs them on real hardware and
 one against a reference that was itself validated against the original CUDA kernel. A port is
 only ever reported as **PASS** if its current code ran on real hardware and matched.
 
-> Status: early release (0.1.0). Triton, CPU and WebGPU backends work and are verified;
+> Status: early release (0.2.0, [changelog](https://github.com/PS12007/kernelport/blob/main/CHANGELOG.md)). Triton, CPU and WebGPU backends work and are verified;
 > Metal is verified on Apple Silicon in CI; the HIP runner and zoo ports are written but not yet
 > verified on an AMD GPU. See [PROGRESS.md](https://github.com/PS12007/kernelport/blob/main/PROGRESS.md).
 
+![Terminal recording: kernelport validates a softmax reference against the original CUDA kernel, a first Triton port without the max subtraction fails 21 of 24 cases with NaN, the fixed port passes 24/24 on an RTX 5060](https://raw.githubusercontent.com/PS12007/kernelport/main/docs/img/demo.svg)
+
+*A real session on an RTX 5060, with the steps an agent takes through the MCP tools run here from the CLI.
+Re-record it with [scripts/record_demo.py](https://github.com/PS12007/kernelport/blob/main/scripts/record_demo.py).*
+
 ![kernelport status for nine llm.c kernels: Triton, Metal and WebGPU ports, each verified against a reference frozen on NVIDIA](https://raw.githubusercontent.com/PS12007/kernelport/main/docs/img/llmc-status.svg)
 
 *Real code, real hardware: [examples/llm.c](https://github.com/PS12007/kernelport/tree/main/examples/llm.c).*
@@ -111,7 +117,7 @@ skill. Details: [docs/how-it-works.md](https://github.com/PS12007/kernelport/blo
 ```bash
 # 1. install (CUDA build of torch first; see docs/installation.md)
 pip install --index-url https://download.pytorch.org/whl/cu128 torch
-pip install "kernelport[cuda,triton,cpu] @ git+https://github.com/PS12007/kernelport"
+pip install "kernelport[cuda,triton,cpu]"
 
 # 2. check what can run here
 kernelport doctor
@@ -136,14 +142,21 @@ given only the one-line request and kernelport's guide; each of its ports passed
 verification. Validation also found an undocumented precondition in llm.c:
 `softmax_forward_online_kernel8` leaves rows unwritten when C < block size.
 
+[`examples/flash-attention-minimal`](https://github.com/PS12007/kernelport/tree/main/examples/flash-attention-minimal)
+does the same for a FlashAttention forward pass (unmodified `flash.cu`, PyTorch-extension host
+code). The Triton port passes and runs 23x faster than the original on the same GPU; the WGSL
+port passes on three WebGPU adapters and the Metal port on Apple M1 (CI). Its README documents where the original's own
+`__expf` and float32 rounding stay within kernelport's fixed tolerance (N <= 384), rather than
+loosening it.
+
 ## Backends
 
 | backend | port language | runs on | status |
-|---|---|---|---|---|
+|---|---|---|---|
 | `triton` | Triton (Python) | NVIDIA (triton / triton-windows), AMD ROCm | working |
 | `cpu` | Numba (Python) | any machine | working (float32/float64) |
 | `metal` | Metal kernel bodies via MLX `metal_kernel` | Apple Silicon | working (float32/float16/bfloat16), verified in CI on an Apple M1 |
-| `webgpu` | WGSL | any Vulkan / Metal / D3D12 GPU via wgpu-native (core WebGPU only, so browser-portable) | working (float32/float16); verified on NVIDIA (Vulkan), Apple (Metal) and llvmpipe (software Vulkan) |
+| `webgpu` | WGSL | any Vulkan / Metal / D3D12 GPU via wgpu-native (core WebGPU only, so browser-portable) | working (float32/float16); verified on NVIDIA (Vulkan), Apple (Metal) and llvmpipe (software Vulkan), and in a browser (Edge) on NVIDIA and Intel GPUs |
 | `hip` | HIP C++ via hipRTC (CuPy ROCm) | AMD ROCm | written, launch path tested on NVIDIA, **not yet verified on AMD** |
 
 Ports for a backend that is not available on the current machine are saved as **UNVERIFIED**,
@@ -152,12 +165,12 @@ never PASS. Commit `.kernelport/` and run `kernelport verify` on the right machi
 ## No coding agent? Use the built-in one (optional)
 
 ```bash
-pip install "kernelport[agent] @ git+https://github.com/PS12007/kernelport"
+pip install "kernelport[agent]"
 export ANTHROPIC_API_KEY=...        # or: ant auth login
 kernelport agent "port the CUDA kernels in this repo to Triton and verify them"
 ```
 
-`kernelport agent` runs Claude (default `claude-opus-5-5`) in a tool-use loop over the same 12
+`kernelport agent` runs Claude (default `claude-opus-5-5`) in a tool-use loop over the same 15
 tools the MCP server exposes, with the workflow skill as its system prompt. It can only act
 through those tools, so all writes stay in `.kernelport/` and it cannot run shell commands.
 Runs are billed to **your** Anthropic account, so it asks before starting (`--yes` skips the
@@ -192,6 +205,22 @@ Measured on an RTX 5060 Laptop GPU (sm_120) and an i7-14700HX (28 threads), benc
 
 (n/c = wall-clock time (CPU, or WebGPU including submission), not comparable to GPU kernel time.)
 
+### Check the WGSL ports in your browser
+
+[`docs/web/`](https://github.com/PS12007/kernelport/tree/main/docs/web) is a single page with no
+dependencies. It runs the 12 WGSL ports on your GPU through the browser's WebGPU and compares every
+output with the frozen reference, using kernelport's tolerances, in float32 and (where the GPU has `shader-f16`) float16. The inputs, expected outputs,
+tolerances and shaders come from kernelport's own harness (`scripts/build_web_demo.py`).
+
+```bash
+python -m http.server -d docs/web 8000     # then open http://localhost:8000
+python scripts/check_web_demo.py           # or headless, in Chrome/Edge (add --discrete for the dGPU)
+```
+
+All 12 ports pass in both dtypes (24/24, 114 cases) in Edge on an RTX 5060 and on Intel UHD Graphics (the i7-14700HX's iGPU). The page also caught a
+real portability bug: the softmax port wrote `-3.4028235e38`, a decimal just above the largest f32.
+wgpu-native rounds it, but browsers reject the shader. The webgpu runner now refuses such literals.
+
 ## CLI
 
 Every MCP tool has a CLI equivalent, so you can drive the workflow by hand or from CI:
@@ -208,6 +237,8 @@ Every MCP tool has a CLI equivalent, so you can drive the workflow by hand or fr
 | `kernelport verify` | `verify_port` | port vs frozen reference |
 | `kernelport bench` | `bench_port` | time port vs original (after PASS) |
 | `kernelport tune <id> <backend>` | `tune_port` | verify + time every `TUNE` variant, keep the fastest that passes |
+| `kernelport pipeline [name]` | `write_pipeline`, `verify_pipeline` | run ported kernels in a chain; check every stage on real intermediate data |
+| `kernelport pipeline <name> --bench` | `bench_pipeline` | time the chain of ports vs the original CUDA chain, whole and per stage (after PASS) |
 | `kernelport status` | `list_status` | kernel × backend × hardware table |
 | `kernelport report [--md]` | `make_report` | HTML or Markdown report |
 | `kernelport setup` | – | register with Claude Code / Codex / Cursor / Gemini CLI |

{kernelport-0.1.0 → kernelport-0.2.0}/PROGRESS.md

@@ -222,16 +222,120 @@
   - llm.c softmax bug: a fix was tested (remove the early return, guard the -inf merge: 10/10 C values
     PASS); issue text drafted for the owner, not posted.
 
+- **Macro-defined kernels + README demo** (2026-10-15):
+  - `analyzer/macros.py`: a small cpp-style expander (object/function-like macros, `#`, `##`,
+    `__VA_ARGS__` and GNU `args...`, nested calls, macro names as arguments, recursion guard, size/depth
+    caps). The analyzer finds kernels stamped out by macros (`FOR_TYPES(DEFINE_SCALE)`), marked by
+    `#define KERNEL __global__ __launch_bounds__(128)`, or opened by a macro (`C_KERNEL(name)(...) {...}`),
+    records `generated_by`, ignores `__global__` inside `#define` bodies, and reads bodies through macros
+    (`KERNEL_LOOP`) for param kinds and features. The NVRTC slicer treats a top-level call of a known macro
+    as its own item (kept if its expansion has device code, blanked if host only), and an unterminated
+    item ends at the next directive. Checked on the 40 kernel-bearing .cu/.cuh files shipped in torch and
+    cupy: no crashes, under 0.1 s each, no false kernels. A macro-generated kernel validates end to end on
+    the RTX 5060 (tests/test_macros.py).
+  - `scripts/record_demo.py`: records a real CLI session (zoo softmax -> Triton: a port without the max
+    subtraction FAILs 21/24, the fix PASSes 24/24) and renders an animated SVG terminal for the README;
+    box characters are drawn as lines and text is pinned to the grid so any font lines up.
+  - CLI/report: `verify`/`bench` take a positional kernel id; piped output honours `$COLUMNS`; the
+    "unexpected NaN" hint also names overflow. CI: the WebGPU racy-port test is skipped on CPU adapters,
+    where the race may not happen (it caused the red runs on 2026-10-14).
+
+- **Report, browser check, FlashAttention** (2026-10-15, later):
+  - Report: headline sentence, readable dark-mode links, PASS cells name the hardware and speedup,
+    unstarted kernels folded into one list; Markdown matches.
+  - `docs/web/`: an in-browser WebGPU check of the 12 zoo WGSL ports, built from kernelport's own
+    harness (`scripts/build_web_demo.py`); `scripts/check_web_demo.py` runs it headless and CI runs it in
+    Chrome (SwiftShader on Linux, the Apple GPU on macOS). 12/12 in Edge on the RTX 5060 and Intel UHD.
+    It caught a real bug: the softmax WGSL port used `-3.4028235e38` (above FLT_MAX); naga accepts it,
+    Tint rejects it. The runner now refuses out-of-range float literals.
+  - `examples/flash-attention-minimal`: unmodified flash.cu; reference validated 6/6 for N <= 384 (the
+    original's own `__expf`/fp32 rounding exceeds the fixed tolerance at N = 512, so larger sizes are
+    documented, not claimed); Triton 23x, WGSL and Metal PASS. Porting to WGSL found that wgpu-native
+    (naga before v30, as bundled by wgpu-py 0.32) zeroes a loop-local `var` without initializer only once
+    (WGSL: every iteration; fixed upstream in gfx-rs/wgpu#9592); the runner refuses it.
+    Harness: init `{"dist": "full", "value": "-inf"}`.
+
+- **Pipelines** (2026-10-17): `kernelport/harness/pipeline.py`, tools `write_pipeline` /
+  `verify_pipeline` (14 tools), CLI `kernelport pipeline`. A pipeline (`.kernelport/pipelines/<name>.json`)
+  names buffers (generated with `init`, or written by a stage) and stages (kernel id, `dims` mapping,
+  `bind` params -> buffers). `resolve` checks names, dtypes, read-before-write and element counts against
+  the frozen specs. Each stage's port output is compared with its frozen reference on the exact input it
+  received (usual tolerances; PASS/FAIL comes only from this). A float64 chain of references gives
+  end-to-end drift: worst |err| / (atol + rtol|exact|) per buffer plus a count of inf/NaN in one chain
+  only; reported, never decides (relative error was useless: 1e-90 vs 0). Backend `cuda` chains the
+  originals. Results in `pipelines/results/<name>/<backend>/<hw>.json`; `status` and both reports show
+  them, downgraded to UNVERIFIED when the pipeline, a port/source or a reference changed.
+  examples/llm.c: `gpt2_loss_head` (softmax -> crossentropy -> backward, fp32) and
+  `gpt2_embed_gelu_residual` (bf16), PASS on Triton and the originals (RTX 5060); CI runs the bf16 one
+  on Metal. Findings: fp32 softmax underflow makes some losses inf on confident logits (originals 8/16,
+  ports 5/16, `__expf` vs `exp`); bf16 drift reaches 1.5x one kernel's tolerance after 3 kernels, same for
+  originals and ports. `tests/bad_ports/crossentropy_clamped.py` (clamps probs >= 1e-3) PASSes its own
+  cases and FAILs the pipeline.
+
+- **Static warnings + llm.c kernel7** (2026-10-24): a reviewer on llm.c#867 noted that
+  `softmax_forward_kernel7` returns early on `tid >= C` too, which leaves partial warps in full-mask
+  `warpReduceMax/Sum` (undefined) and races lane 0 on `maxvals/sumvals[warpId]`. On the RTX 5060 the
+  unfixed kernel7 is still correct for C = 1..50257, block 32..1024, with and without fast math (504/504
+  configs), so validation cannot find it. Fix on the PR branch (local commit, not pushed): return only
+  when the whole warp is past C, lane 0 writes the slots; 504/504, same speed at C = 50257 (removing the
+  return entirely was ~2% slower). The PR's first commit had also converted softmax_forward.cu to CRLF
+  (GitHub showed all 733 lines changed); a commit restores LF, net diff 16 lines.
+  New `kernelport/analyzer/hazards.py`: warns when a lane-varying condition (from threadIdx.x,
+  thread_rank(), laneid; `/ 32` makes a value warp-uniform) returns before a full-mask warp op
+  (`__shfl*_sync`, `__syncwarp()`, votes, `cg::reduce`, warp-reduce helpers by name or via `__device__`
+  bodies; `__activemask()` masks excluded). `KernelInfo.warnings`; shown by `scan` (CLI + tool summary) and
+  `read_kernel`; SKILL.md tells agents to add warp-splitting cases. Flags exactly kernel7 and kernel8 in
+  llm.c dev/cuda; 1 of 152 llama.cpp ggml-cuda kernels (`quantize_mmq_q8_1`, safe there only because ne0 is
+  padded). Also fixed: kernels opening a brace in each `#if` branch (llama.cpp mmf.cuh) crashed the whole
+  scan; braces are now matched in the first branch only, and an unparseable kernel is skipped.
+
+- **Pipeline timing** (2026-10-27): `bench_pipeline(name, backend, case=None)` (15th tool) and
+  `kernelport pipeline <name> --bench [--case]`. Requires a current PASS for the pipeline on this backend
+  and hardware. `harness.pipeline.stage_inputs` runs the chain once with the ports and keeps each stage's
+  real input; each stage's port and original are then prepared on their own copy of it, and the whole
+  chain (launched back to back) and each stage are timed in 3 alternating rounds (CUDA events where the
+  backend allows). No data flows between stages while timing, so the numbers are kernel time only. Result
+  in `pipelines/results/<name>/<backend>/bench/<hw>.json` (not read back as a verification result).
+  RTX 5060, Triton: `gpt2_loss_head` at 4x64x50257 = 1.00 ms vs 1.33 ms (1.33x; softmax 1.68x,
+  crossentropy fwd/bwd ~0.97x); `gpt2_embed_gelu_residual` at 4x256x768 bf16 about even. A first run named the encoder
+  port 0.44x; reruns moved the "slow" stage around: single rounds of ~10 us kernels spike up to 3x, so
+  bench_pipeline now takes 5 rounds and names a stage slower only when no round overlaps. The encoder's
+  Triton port was rewritten row-wise anyway (one token-id load per row, no per-element divide): 0.023 vs
+  0.025 ms. The original encoder measures 0.024-0.047 ms depending on the session (steady within one).
+
+- **Block-barrier hazards** (2026-10-28): `analyzer/hazards.py` gets a second check,
+  `divergent_barriers`: a block barrier (`__syncthreads*`, `this_thread_block().sync()`, `block.sync()` on a
+  `thread_block`, `cg::sync`, `blockReduce`-style helpers by name or via `__device__` bodies, template calls
+  included) that some threads can miss: (a) a thread-dependent `return` before it, (b) inside an `if` whose
+  condition depends on threadIdx (any dim; `/ 32` does not make it block-uniform), (c) inside a loop whose
+  condition does. CUDA-side exemptions, from false positives in llama.cpp: a `for` whose start and bound
+  shift by the same thread term (wkv.cu, gla.cu), and a return inside a block that always ends in `return;`
+  (mmq.cuh fixup). Early return before `__syncthreads` is a deliberate idiom on NVIDIA (exited threads count
+  as arrived; llm.c's encoder.cuh says so), so that kind is worded as a porting note; branch/loop kinds as a
+  CUDA hazard. Scan of 340 kernels: llm.c fork 7 (4 loop cases: dev layernorm_backward kernel9/10,
+  fused_residual_forward_kernel6, llmc layernorm_backward_kernel10; 3 early returns), llama.cpp ggml-cuda 4
+  early returns, zoo 0.
+  **WGSL gap found:** wgpu-native 29 (naga, wgpu-py 0.32) accepts a `workgroupBarrier()` after a
+  non-uniform return, inside a divergent `if`, or in a divergent loop; Edge (Tint) rejects all three
+  ("must only be called from uniform control flow"), plus two cases the CUDA exemptions would allow (a
+  shifted loop; a return nested in a branch that returns). So a WGSL port could PASS here and not compile in
+  a browser. The runner now refuses these (`check_barrier_uniformity`, reusing `divergent_barriers` in
+  `strict` mode with the invocation-id builtins as sources; WGSL is rewritten to C-style conditions first).
+  Agrees with Edge on all 6 probe shaders; all 15 existing WGSL ports are accepted. Not followed: Tint also
+  treats loads from read_write storage as non-uniform. Skill: SKILL.md, webgpu.md, metal.md.
+
 ## Next (pick up here)
 Owner actions (see RELEASING.md for PyPI):
-- PyPI: add the pending trusted publisher + `pypi` environment, set version 0.1.0, push tag `v0.1.0`.
-- Decide whether to post the llm.c softmax issue (draft kept outside the repo).
+- PyPI: DONE 2026-10-14, kernelport 0.1.0 published via release.yml (tag v0.1.0); clean `pip install
+  kernelport` verified. Next release: bump version, tag `vX.Y.Z`.
+- llm.c softmax fix: posted by the owner as karpathy/llm.c#867 (branch fix-softmax-online-kernel8-small-c
+  on PS12007/llm.c). A reviewer flagged kernel7; the fix and an LF restore are committed in the local
+  clone C:\-CS\llm.c-fork, waiting for the owner's go-ahead to push (and to reply on the PR).
 - HIP + Triton-on-ROCm: run `bash scripts/amd_check.sh` on an AMD machine (AMD Developer Cloud
   credits via the AMD AI Developer Program); it writes amd_results.txt. Live `kernelport agent` test: skipped
   by owner choice (no API credits); the MCP/CLI path covers the same tools;
   run notebooks/freeze_references_colab.ipynb once on Colab; dogfood with Codex / Cursor too.
-Engineering left: kernels generated by macros (analyzer + slicer are lexical); a demo GIF/video;
-launch posts.
+Engineering left: a demo GIF/video; launch posts.
 
 ## How to resume
 - Env: `.venv` (Python 3.12, torch 2.11.0+cu128, triton-windows 3.7.1, cupy-cuda12x 14.2). `kernelport doctor`.
@@ -244,7 +348,9 @@ launch posts.
 ## Known issues / notes
 - Requires mcp>=2.0 (FastMCP was renamed MCPServer in 2.x; we use the 2.x API only).
 - The zoo is not shipped in the wheel; `kernelport zoo` needs a repo checkout (or cwd containing zoo/).
-- Analyzer is lexical, not a C++ front end: macros that generate kernels, kernels behind #if branches, and
+- Analyzer is lexical, not a C++ front end. Macro-defined kernels are found by a small macro expander
+  (`kernelport/analyzer/macros.py`: object/function-like macros, # and ##, variadics, macro-name arguments);
+  `#if` is not evaluated (the last `#define` wins). Kernels behind #if branches, and
   pointer kinds through complex aliasing (structs of pointers, pointer arithmetic in loops) may be wrong.
   Kinds are suggestions; the agent confirms them, and reference validation catches mistakes.
 - Reductions (reduce_sum, matmul_naive, cumsum) use inputs quantized to multiples of 1/16 (`"step"` in