Architecture

Architecture

How blackwell-kernel-lab is organized, how experiments are layered, and where responsibilities end.

Repo layout

docs/           Mission, hardware baseline, train-fit, kernel layering, CI, forge consume/boundary, F0 schemas
fixtures/       CPU JSONL fixtures (F0 Agoge ↔ BKL correlation; NVML/efficiency)
recipes/        Human-run kernel measurement playbooks
kernels/        First-party CUDA workspace (sm_120) — L3 `.cu` + L2 green-ctx bench
tools/          CPU validators (correlation, NVML capability, GPU CI policy, efficiency)
results/        Kernel measurement outputs (gitignored)

Kernel layering (L1 / L2 / L3)

New first-party device code lands only after L1 proves a gap — never write CUDA first.

flowchart TB
    subgraph L1["L1 — measure engine CUDA paths"]
      FA["Flash / fused attention"]
      G["CUDA graphs"]
      Q["Q4 / MXFP4 / NVFP4 GEMM"]
      P["Prefix / KV reuse"]
    end
    subgraph L2["L2 — host scheduling"]
      GC["Green Contexts<br/>bkl_green_ctx_bench"]
    end
    subgraph L3["L3 — first-party .cu / CUTLASS"]
      DH["bkl_device_hello"]
      GL["bkl_graph_launch_bench"]
      FUTURE["Future operator for v0.2.0<br/>(after L1 proves a training gap)"]
    end
    L1 -->|"proven gap only"| L3
    L1 --> L2
    FORGE["agoge-forger<br/>trainer / datasets / SFT·QLoRA"] -. consume recipes / libs .-> L1
    FORGE -. consume .-> L3
    F0["F0 JSONL join<br/>bkl.f0_correlation.v1"] --- FORGE
    F0 --- TOOLS["tools/ + fixtures/"]

Loading

Layer	Meaning	Where
L1	Measure engine CUDA paths (FA, graphs, quant, prefix)	recipes/, docs/, results/ — start here
L2	Host scheduling (Green Contexts, dual P/D queues)	First-party benches, recipes, measured artifacts
L3	New .cu / CUTLASS	kernels/

Ranked L1 levers: (1) 4-bit weight path, (2) CUDA graphs, (3) engine FA (not datacenter FA4 / sm_100), (4) prefix / session KV reuse, then Green Contexts.

The kernels/ tree

kernels/
  README.md / CMakeLists.txt
  src/
    device_hello.cu         # L3 smoke (#21) → bkl_device_hello
    green_ctx_bench.cu      # L2 Green Context (#17) → bkl_green_ctx_bench
    graph_launch_bench.cu   # L3 graph vs eager (#30) → bkl_graph_launch_bench
  tools/
    check_green_ctx_report.py
    wait_gpu_headroom.sh
    check_compute_sanitizer_runner.sh / run_compute_sanitizer.sh

-DBKL_ENABLE_CUDA=OFF configures without CUDA (what ci-cpu.yml runs).

Forge boundary

Work	Lives in
CUDA backend / GPU kernels / engine CUDA measurements on this 5080	this repo
Model training / fine-tune / post-training ladder	rmems/agoge-forger
Optional neuromorphic kernels	Limen-Neural/myelin-accelerator (optional; not SoT for this host)

Do not grow a second first-party CUDA tree under agoge-forger/cuda/.

F0 telemetry join

Versioned JSONL (bkl.f0_correlation.v1 in docs/f0-correlation-schema.md): Agoge emits agoge_marker; this lab emits bkl_gpu_sample + bkl_clock_skew. Join by agoge_run_id + monotonic time. Related: bkl.f0_capability.v1 (NVML), bkl.f0_efficiency.v1 (tokens/s, step-time, VRAM/power summaries). CPU tools under tools/; fixtures under fixtures/.

CI split

Workflow	Runner	Purpose
ci-cpu.yml	ubuntu-latest	Kernel-tree checks, CUDA-disabled configure, F0 validators
ci-gpu.yml	Self-hosted ShipOfTheseus (self-hosted, Linux, X64, CUDA)	GPU probe + sm_120 build/smoke; waits ≤10 min for ≥2048 MiB free

Markdown-only PRs skip the GPU host. Fork PRs never run on the GPU host. Compute Sanitizer is opt-in (ci-gpu-sanitizer).

Release posture @ 22cc4f3

• Tagged: v0.1.0 (M0).
• Active target: v0.2.0 — profile MiniCPM5 + Granite, freeze one justified operator, implement/package, integrate in Agoge, qualify, tag. Historical L1 inference / synthetic L2/L3 results are context, not proof of that gate.
• Milestones are work tracks, not an automatic release ladder; closing a milestone does not cut a tag.

---

Refreshed 2026-10-15 by Wiki Keeper (Grok Bot) from code at main @ 22cc4f3 (tagged v0.1.0; release target v0.2.0).