chore(llvm19): close out Layer 3 pre-smoke work

Finalize the Layer 3 plan, add env-driven final-module and LLVM IR capture hooks to vecadd, and validate the harness locally so the next phase can move straight to CUDA 12.9+ smoke testing.

Co-authored-by: OpenAI Codex <codex@openai.com>

Author: brandonros

LLVM19_PLAN.md

@@ -557,7 +557,7 @@ Each "Layer" ends in a known-good state with a single git commit. Within a layer
 - `src/llvm.rs` is either unchanged except for a few high-value wrappers, or changed in a way that clearly reduces Rust-side LLVM-version leakage.
 - No speculative wrappers remain in the diff "just in case".
 - Both feature settings still pass `cargo check`.
-- The next work item after Layer 2 is still Layer 3 file-by-file cfg surgery or, if no Rust-side wrapper actually proved necessary, a direct move into the smallest Layer 3 callsite work.
+- The next work item after Layer 2 is Layer 3 pre-smoke reconciliation and failure-driven triage, not a speculative file-by-file cfg sweep.
 
 **Commit strategy for Layer 2:**
 - Prefer one small commit per sublayer (`2b`, `2c`, `2d`) only when there is real code to land.
@@ -567,85 +567,252 @@ Each "Layer" ends in a known-good state with a single git commit. Within a layer
 
 ---
 
-### Layer 3 — Rust-side cfg surgery, file by file
+### Layer 3 — Pre-Smoke Reconciliation And Edit Map
 
-**Goal:** All Rust source files compile cleanly under both feature settings. Behavioral correctness on the LLVM 19 path is NOT guaranteed yet — that's Layers 5-6.
+**Status (2026-04-14):** Complete.
+- `CARGO_TARGET_DIR=/tmp/rust-cuda-layer3-baseline-v7 cargo build -p rustc_codegen_nvvm --no-default-features` passes.
+- `CARGO_TARGET_DIR=/tmp/rust-cuda-layer3-baseline-v19 LLVM_CONFIG_19=/usr/bin/llvm-config-19 cargo build -p rustc_codegen_nvvm` passes.
+- `CARGO_TARGET_DIR=/tmp/rust-cuda-layer3-vecadd-v19 LLVM_CONFIG_19=/usr/bin/llvm-config-19 cargo build -p vecadd` passes.
+- `cuda_builder` definitely invokes the current backend via `-Zcodegen-backend=<path to rustc_codegen_nvvm>`.
+- The generated PTX on this host still reports `Based on NVVM 7.0.1`, which means this CUDA 12.8 machine can prove compile success but cannot prove the intended CUDA 12.9+ LLVM-19-bitcode acceptance story.
+- `examples/vecadd/build.rs` now has env-driven capture hooks for the first smoke:
+  - `RUST_CUDA_DUMP_FINAL_MODULE=1`
+  - `RUST_CUDA_EMIT_LLVM_IR=1`
+- Those hooks were locally validated with:
+  - `CARGO_TARGET_DIR=/tmp/rust-cuda-layer3-harness-v19 LLVM_CONFIG_19=/usr/bin/llvm-config-19 RUST_CUDA_DUMP_FINAL_MODULE=1 cargo build -p vecadd`
+  - `CARGO_TARGET_DIR=/tmp/rust-cuda-layer3-harness-v19-ir LLVM_CONFIG_19=/usr/bin/llvm-config-19 RUST_CUDA_DUMP_FINAL_MODULE=1 RUST_CUDA_EMIT_LLVM_IR=1 cargo build -p vecadd`
+- Therefore the old "edit files until `cargo check` turns green" version of Layer 3 is obsolete, and the repo-side pre-smoke work is now complete.
+
+**Goal:** Enter the first CUDA 12.9+ smoke run with:
+- a locked compile/build baseline,
+- an explicit capture path for the final LLVM module and PTX,
+- a ranked list of Rust files to patch if smoke fails,
+- and an explicit list of files that are *not* on the first-smoke hot path.
+
+**Working principle:** do not proactively sweep the Rust tree adding `#[cfg(feature = "llvm19")]` branches. Only edit a file if one of the following is true:
+- the file still contains an explicit LLVM-7-era workaround that Layer 3 has now identified as a likely LLVM 19 fast path,
+- the first CUDA 12.9+ smoke failure points directly at it,
+- or a validation artifact (final module, PTX, backtrace, verifier error) makes the mismatch concrete.
+
+#### Layer 3a — Baseline Lock And Consumer Proof
+
+**Status (2026-04-14):** Complete.
 
-**Working principle:** for each file in the list below, read upstream's current version, ask "does any code here need to behave differently on LLVM 19?", and add localized cfg branches. **Do not** copy June's version of the file. **Do not** restructure upstream's code.
+**Goal:** Prove the backend builds, and prove that a real GPU consumer (`vecadd`) can compile through the current LLVM 19 path before making any more Rust changes.
 
-**Files in execution order:**
+**Checklist:**
+- [x] `cargo build -p rustc_codegen_nvvm --no-default-features`
+- [x] `LLVM_CONFIG_19=/usr/bin/llvm-config-19 cargo build -p rustc_codegen_nvvm`
+- [x] `LLVM_CONFIG_19=/usr/bin/llvm-config-19 cargo build -p vecadd`
+- [x] Confirm `cuda_builder` drives `rustc_codegen_nvvm` through `-Zcodegen-backend=...`
+- [x] Inspect generated PTX and record what this host can and cannot prove
 
-#### 3a. `src/back.rs` — TargetMachine factory call site
-- The single callsite already goes through `create_target_machine(TargetMachineConfig)`. Only extend the wrapper if runtime validation proves we need more explicit LLVM 19 knobs than the current shim-preserved surface exposes.
-- Build the `TargetMachineConfig` struct with sensible defaults for the new v19 fields (`FloatABI::Default`, no split debug file, no debug compression, no emulated TLS).
-- Verify upstream's `temp_path_for_cgu` → `temp_path` rename mentioned in explorer is not actually a v19 thing (it's a nightly-2026-04-02 thing). Skip.
-- ~20 lines changed. Smallest hot file. Good warm-up.
+**Findings to carry forward:**
+- `vecadd` compiles successfully through the current backend path.
+- The copied PTX lives at:
+  - `/tmp/rust-cuda-layer3-vecadd-v19/debug/build/vecadd-0550a17a21893201/out/kernels.ptx`
+- The underlying `cuda-builder` target PTX lives at:
+  - `/tmp/rust-cuda-layer3-vecadd-v19/cuda-builder/nvptx64-nvidia-cuda/release/vecadd_kernels.ptx`
+- On this CUDA 12.8 host, the PTX header still says `Based on NVVM 7.0.1`.
+- Practical consequence: this machine is good enough to prove the current LLVM 19 backend can compile a real kernel crate, but it is still the wrong host for answering the CUDA 12.9+ / Blackwell acceptance question.
 
-#### 3b. `src/lto.rs` — ThinLTO buffer creation
-- The current Rust-side ThinLTO path does **not** call `LLVMRustThinLTOBufferCreate`. `ModuleBuffer::new(..., is_thin)` now explicitly documents that it still serializes full-module bitcode and that the ThinLTO-specific shim APIs remain unwired on the Rust side.
-- The old plan's `is_thin=true, emit_summary=true` note was based on a stale candidate API shape and should not drive new wrapper work by itself.
-- ~5 lines changed.
+**Validation checkpoint for 3a:**
+- Backend builds pass under both feature settings.
+- A real GPU crate builds through the LLVM 19 path.
+- No additional Rust source edits are required just to keep the build green.
 
-#### 3c. `src/debug_info/mod.rs` — debug location setter
-- The debug-location callsites already go through `set_current_debug_location(builder, context, Option<&DILocation>)`, and the DIBuilder function/variable creation callsites already go through named Rust helpers.
-- Verify the `DIBuilderCreateFunction` callsites still have a clean containment point for any future bool → `DISPFlags` conversion, whether that lives in Layer `2c` or stays in the C++ shim.
-- Verify dwarf op widths (i64 vs u64 from explorer report) are absorbed by the wrapper or are local enough to cfg-branch in place.
-- ~30 lines changed across this file.
+**Suggested commit message:** `chore(llvm19): lock post-Layer-2 baseline and vecadd compile proof`
 
-#### 3d. `src/debug_info/metadata.rs` and `src/debug_info/metadata/enums.rs`
-- Similar treatment. If Layer `2c` does not grow Rust-side DI wrappers, keep this work local and minimal. Any leftovers (DIBuilder schema differences in struct/enum metadata creation) get local `#[cfg]` branches.
-- ~20 lines combined.
+#### Layer 3b — Close Stale Compile-Only Work Items
 
-#### 3e. `src/intrinsic.rs` — the high-stakes file
-- **DO NOT** rewrite intrinsic dispatch. Upstream's dispatch is correct.
-- Identify the *specific* places where LLVM 19 enables a code path that LLVM 7 cannot:
-  - `volatile_load` opaque-pointer rewrite (small, local)
-  - i128 intrinsics that LLVM 19 has natively (`llvm.ctlz.i128`, `llvm.cttz.i128`, `llvm.bswap.i128`, `llvm.bitreverse.i128`, `llvm.fshl.i128`, `llvm.fshr.i128`, `llvm.ctpop.i128`) — on LLVM 19, call them directly instead of falling through to the emulation in `builder/emulate_i128.rs`. On LLVM 7, do nothing different.
-  - Saturating ops: same — LLVM 19 has them, LLVM 7 doesn't. Skip the reimplementation when feature is on.
-  - `abort()` callsite already goes through the existing call helper surface; only change it if later wrapper cleanup in Layer `2b` actually alters that surface.
-  - `type_test` stub for CFI — confirm whether upstream already handles this or if we need a stub.
-- Each of these is a `#[cfg(feature = "llvm19")]` branch *inside* upstream's existing function bodies, not a rewrite.
-- ~50-100 lines changed across this file. The largest single Rust file in this layer.
+**Status (2026-04-14):** Complete.
 
-#### 3f. `src/builder.rs` — opaque-pointer adjustments and call sites
-- Most call-site changes can be absorbed by Layer 2 helper cleanup if we choose to add it; otherwise keep the current `LLVMRustBuildCall` / `LLVMRustBuildCall2` split and only touch the specific call sites that need adjustment.
-- Any opaque-pointer-related GEP or load/store callsites that LLVM 19 requires `Type*` for need cfg branches.
-- ~30 lines changed.
+**Goal:** Remove outdated Layer 3 candidates that no longer need proactive Rust work.
 
-#### 3g. `src/builder/emulate_i128.rs` — guard against double emulation
-- Upstream already has the full emulation. On LLVM 19, several of its routines should short-circuit to the native LLVM 19 intrinsic.
-- Add a top-of-function `#[cfg(feature = "llvm19")]` early-return that calls `LLVMBuildCall` with the native intrinsic name, falling through to the emulation only on LLVM 7.
-- ~20-50 lines changed.
+**Checklist:**
+- [x] Mark `src/back.rs` as no longer a hot Layer 3 file for compile-path reasons:
+  - it already goes through `create_target_machine(TargetMachineConfig)`
+- [x] Mark `src/lto.rs` as no longer a hot Layer 3 file for compile-path reasons:
+  - Rust does not currently call `LLVMRustThinLTOBufferCreate`
+  - `ModuleBuffer::new(..., is_thin)` already documents the current behavior
+- [x] Mark `src/debug_info/mod.rs` and `src/debug_info/metadata.rs` as wrapped but low priority for the first smoke:
+  - the relevant positional DIBuilder callsites are already contained
+  - `vecadd`'s default `CudaBuilder` path is not a debug-info-heavy workload
+- [x] Mark `src/init.rs` as *not* requiring an immediate Rust-side cfg branch:
+  - `LLVMInitializePasses()` is already version-gated in the C++ shim
+- [x] Mark `src/abi.rs` and `src/ctx_intrinsics.rs` as low priority for the first smoke:
+  - upstream already carries the relevant f16/f128 work
+  - `cuda_builder` currently forces `CARGO_FEATURE_NO_F16_F128=1` for the GPU build path
+- [x] Lock the real first-smoke Rust hot files:
+  - `src/intrinsic.rs`
+  - `src/builder.rs`
+  - `src/builder/emulate_i128.rs`
+
+**Validation checkpoint for 3b:**
+- The pending edit list is smaller and evidence-driven.
+- No file remains on the hot path purely because the older plan predicted it might matter.
+
+**Suggested commit message:** `docs(llvm19): trim stale Layer 3 compile-only work`
+
+#### Layer 3c — First CUDA 12.9+ Smoke Harness
+
+**Status (2026-04-14):** Complete on the repo side; ready to run on the correct host.
+
+**Goal:** Make the first CUDA 12.9+ `vecadd` smoke run maximally informative so that any later Rust edits are driven by concrete evidence.
+
+**Repo work completed in this layer:**
+- [x] Added env-driven capture hooks to `examples/vecadd/build.rs`:
+  - `RUST_CUDA_DUMP_FINAL_MODULE=1` enables `.final_module_path(out_path.join("final-module.ll"))`
+  - `RUST_CUDA_EMIT_LLVM_IR=1` enables `.emit_llvm_ir(true)`
+- [x] Added `cargo::rerun-if-env-changed` hooks for both capture env vars.
+- [x] Validated final-module capture on this host:
+  - `/tmp/rust-cuda-layer3-harness-v19/debug/build/vecadd-0550a17a21893201/out/final-module.ll`
+- [x] Validated LLVM-IR emission on this host:
+  - `/tmp/rust-cuda-layer3-harness-v19-ir/cuda-builder/nvptx64-nvidia-cuda/release/deps/vecadd_kernels.ll`
+  - `/tmp/rust-cuda-layer3-harness-v19-ir/debug/build/vecadd-0550a17a21893201/out/final-module.ll`
+
+**Exact checklist for the next host:**
+- [ ] Run on a host with:
+  - CUDA Toolkit `12.9+`
+  - visible NVIDIA driver runtime (`libcuda.so.1`)
+  - LLVM 19 toolchain reachable via `LLVM_CONFIG_19`
+- [ ] Export:
+  ```bash
+  export LLVM_CONFIG_19=/path/to/llvm19/bin/llvm-config
+  export CUDA_HOME=/usr/local/cuda-12.9
+  export LD_LIBRARY_PATH=$CUDA_HOME/nvvm/lib64:$LD_LIBRARY_PATH
+  ```
+- [ ] Use a fresh target dir:
+  ```bash
+  export CARGO_TARGET_DIR=/tmp/rust-cuda-layer3-smoke-v19
+  ```
+- [ ] Capture knobs are already implemented in `examples/vecadd/build.rs`; enable them with:
+  ```bash
+  export RUST_CUDA_DUMP_FINAL_MODULE=1
+  export RUST_CUDA_EMIT_LLVM_IR=1   # optional
+  ```
+- [ ] Run:
+  ```bash
+  cargo build -p vecadd
+  ```
+- [ ] Capture:
+  - full stderr/stdout,
+  - copied PTX,
+  - the final module dumped by `CudaBuilder`,
+  - and any `cargo` JSON diagnostics if the build fails
+- [ ] If runtime is available, also run:
+  ```bash
+  cargo run -p vecadd
+  ```
+  and capture runtime stderr / backtrace / driver errors
 
-#### 3h. `src/abi.rs` — verify, do not edit
-- The explorer flagged this as HOT, but on closer reading: upstream already added f16/f128 support and PassMode::Cast for align(16) ADTs. June's version was *trying to do* what upstream now does. **No changes expected here.** If `cargo check --features llvm19` flags errors in this file, first ask whether they are really an FFI containment problem before adding Layer 3 cfg branches.
+**Expected output classification:**
+- [ ] Success
+- [ ] Backend crash inside `librustc_codegen_nvvm.so`
+- [ ] `libnvvm` rejects the module
+- [ ] PTX is emitted but invalid / suspicious
+- [ ] PTX loads fail at runtime
 
-#### 3i. `src/ctx_intrinsics.rs` — verify, do not edit
-- Same situation. Upstream removed i128 remapping and added f16/f128 entries. Should compile under both feature settings without changes.
+**Validation checkpoint for 3c:**
+- The repository now has a reproducible capture harness for the first CUDA 12.9+ smoke.
+- The capture hooks were validated locally on this CUDA 12.8 host.
+- Actual CUDA 12.9+ execution is deferred to Layer 5, which is where the smoke outcome itself gets classified.
 
-#### 3j. `src/init.rs` — pass registration
-- The legacy pass registration calls (`LLVMInitializeCore`, `LLVMInitializeCodeGen`, etc.) are LLVM-7-specific. On LLVM 19 with the new pass manager, this becomes a no-op or a `PassBuilder::registerXxx()` call.
-- `#[cfg]`-branch the body of the init function. ~20 lines.
+**Suggested commit message:** `chore(llvm19): capture first CUDA 12.9 smoke artifacts`
 
-#### 3k. Everything else listed in the explorer's TRIVIAL bucket
-- `attributes.rs`, `consts.rs`, `const_ty.rs`, `ty.rs`, `target.rs`, `link.rs`, `mono_item.rs`, `override_fns.rs`, `asm.rs`, `allocator.rs`, `int_replace.rs`
-- These need either zero changes or single-line cfg branches. Defer until `cargo check` complains; don't proactively touch.
+#### Layer 3d — Ranked Rust Intervention Map
 
-**Validation between sub-steps:**
-- After each sub-step, `cargo check --features llvm19` should make incremental progress (fewer errors than before).
-- After each sub-step, `cargo check --no-default-features` must remain clean — never break the LLVM 7 path.
+**Status (2026-04-14):** Complete.
 
-**Commit message strategy:**
-- One commit per sub-step (3a, 3b, ...) for clean bisectability. Easy to revert one without losing the rest.
-- Or one big commit if the sub-steps all land in one sitting.
+**Goal:** If the first smoke fails, edit the smallest, highest-signal Rust file first.
+
+**Priority order and entry criteria:**
+
+1. `src/intrinsic.rs`
+   Trigger:
+   - smoke or final-module inspection implicates explicit LLVM-7-era intrinsic workarounds
+   - especially the existing `TODO(@LegNeato): LLVM 7.1 doesn't have ...` branches
+   Planned changes:
+   - LLVM 19-native fast paths for:
+     - `llvm.ctlz.i128`
+     - `llvm.cttz.i128`
+     - `llvm.ctpop.i128`
+     - `llvm.bswap.i128`
+     - `llvm.bitreverse.i128`
+     - `llvm.fshl.i128`
+     - `llvm.fshr.i128`
+   - LLVM 19-native saturating integer intrinsics where available
+   Guardrail:
+   - do this as local `#[cfg(feature = "llvm19")]` branches inside the existing dispatch, not as a rewrite
+
+2. `src/builder/emulate_i128.rs`
+   Trigger:
+   - LLVM 19 is still falling into emulation for paths that should be native
+   - or `intrinsic.rs` grows LLVM 19 fast paths and now needs shared helpers or early-outs
+   Planned changes:
+   - short-circuit the specific emulation routines that should no longer run on LLVM 19
+   Guardrail:
+   - do not refactor the whole emulation module; only fence off the now-obsolete LLVM 7 path where necessary
+
+3. `src/builder.rs`
+   Trigger:
+   - verifier output, final-module inspection, or backend crashes implicate typed-pointer / opaque-pointer mismatches
+   - especially around:
+     - `load` / `volatile_load`
+     - local atomic fallback loads
+     - `LLVMBuildGEP2` / `LLVMBuildInBoundsGEP2`
+     - call construction sites that still depend on typed-pointer assumptions
+   Planned changes:
+   - local cfg branches or helper use to satisfy LLVM 19's stricter pointer/type expectations
+   Guardrail:
+   - touch only the exact sites implicated by the smoke artifacts
+
+4. `src/debug_info/mod.rs`, `src/debug_info/metadata.rs`, `src/debug_info/metadata/enums.rs`
+   Trigger:
+   - only if the smoke run is done with debug info enabled or `libnvvm` / verifier diagnostics point at metadata schema drift
+   Planned changes:
+   - local metadata schema fixes only
+   Guardrail:
+   - not on the first default `vecadd` hot path
+
+5. `src/init.rs`, `src/lto.rs`, `src/back.rs`
+   Trigger:
+   - only if the failure directly implicates pass initialization, ThinLTO setup, or target-machine option plumbing
+   Current assessment:
+   - low probability for the first smoke because these areas are already shimmed or explicitly documented
+
+**Validation checkpoint for 3d:**
+- Any Rust edit after Layer 3 starts maps to one of the ranked buckets above.
+- We can explain *why* that file moved from dormant to hot.
+
+**Suggested commit message:** `docs(llvm19): rank first-smoke Rust fix buckets`
+
+**Layer 3 done means:**
+- The post-Layer-2 compile/build baseline is locked and recorded.
+- A real consumer build (`vecadd`) has been proven on the current host.
+- The first CUDA 12.9+ smoke command set is written down with capture instructions.
+- The repo-side smoke harness is implemented and locally validated.
+- The first-smoke Rust edit order is explicit and ranked.
+- No speculative file-sweep changes remain justified.
+
+**Commit strategy for Layer 3:**
+- Prefer docs-only or harness-only checkpoints until the first CUDA 12.9+ smoke failure exists.
+- Once smoke starts producing concrete failures, use one commit per affected hot file or failure bucket.
+- Do not land opportunistic edits to dormant files just to "get ahead" of possible runtime issues.
 
 ---
 
-### Layer 4 — Get `cargo check --features llvm19` fully green
+### Layer 4 — Keep The Build Baseline Green
+
+**Status (2026-04-14):** Baseline already green for backend builds.
+- `cargo check -p rustc_codegen_nvvm --no-default-features` passes
+- `LLVM_CONFIG_19=/usr/bin/llvm-config-19 cargo check -p rustc_codegen_nvvm` passes
+- `cargo build -p rustc_codegen_nvvm --no-default-features` passes
+- `LLVM_CONFIG_19=/usr/bin/llvm-config-19 cargo build -p rustc_codegen_nvvm` passes
 
-**Goal:** Both `cargo check --features llvm19` and `cargo check --no-default-features` pass with zero errors and minimal warnings.
+**Goal:** Preserve those compile/build baselines while Layer 3/5/6 land smoke-driven fixes.
 
-This isn't a "layer" so much as an iteration loop. Errors will surface in unexpected files. For each:
+This is now a maintenance loop. If a later edit breaks the baseline:
 
 1. **Read the error in context.** Don't guess.
 2. **Decide: is this an FFI shim gap, a missed cfg branch, or a genuine LLVM 19 API difference we missed?**