test: xfail regression for #1051 (bwds crash on runtime-start diff loop) + docs workaround

[nv-slang-bot]

Summary

Regression coverage + a documented workaround for #1051, where backward dispatch (.bwds()) of a [Differentiable] function crashes when the function body contains a loop with a runtime (non-constant) induction start, e.g. for (int dx = -radius; dx <= radius; ++dx) where radius is a no_diff runtime param.

This PR does not fix the crash — the root cause is upstream in the Slang compiler's reverse-mode autodiff (tracked as shader-slang/slang#12070), and SlangPy cannot fix it: it hands the user function verbatim to bwd_diff and does no loop/induction rewriting. Confirmed against the generated kernel (SLANGPY_PRINT_GENERATED_SHADERS=1): the bwds kernel prepends [Differentiable] to a _trampoline, calls the user function unchanged, then dispatches bwd_diff(_trampoline).

The trigger is the loop start being non-constant, not negative. A constant negative start such as for (int dx = -2; dx <= 2; ++dx) differentiates fine; the reporter's -radius was incidentally both runtime and negative. Reproduced on CUDA and Vulkan (SIGSEGV, exit 139); the constant-start controls produce correct gradients.

Uses Refs (not Fixes) intentionally: the issue must stay open to track the upstream fix. It will be closed by the upstream Slang change, not by merging this.

Refs #1051
Refs shader-slang/slang#12070

Changes

• slangpy/tests/slangpy_tests/test_diff_loop_runtime_start.py (new):
  • test_diff_loop_runtime_start runs the crashing runtime_start bwds in an isolated subprocess (a SIGSEGV is a hard native crash that would otherwise take down the pytest worker / disrupt pytest-xdist). It brackets the .bwds() dispatch with begin/end markers so a crash is attributed to the backward dispatch specifically (not setup/readback/teardown). Marked xfail(raises=_KnownCrash, strict=True):
    • today's native crash inside the dispatch → XFAIL;
    • a wrong-gradient result (compared element-wise against an independent numpy oracle) → hard FAIL, not masked;
    • a clean child exit once the upstream fix lands → strict XPASS → hard FAIL, forcing removal of the marker + subprocess scaffolding.
  • test_diff_loop_constant_start runs two in-process controls that must always pass: const_neg_start (constant -2 → shows negative-ness is not the trigger) and zero_start (the documented workaround). Together they isolate the trigger to runtime-ness.
• docs/src/autodiff/autodiff.rst: a note documenting the constant-start workaround, cross-linking [Bug] Backward dispatch segfaults when a [Differentiable] function has a loop with a negative runtime start value #1051 and slang#12070.

Verification

• pytest slangpy/tests/slangpy_tests/test_diff_loop_runtime_start.py → 4 passed, 2 xfailed on CUDA + Vulkan, exit 0; identical under pytest-xdist -n2.
• Parent-side returncode→outcome mapping verified: crash-in-dispatch→XFAIL, exit0→XPASS/fail, wrong-grad→fail, no-device→skip, crash-outside-dispatch/other→fail.
• black clean, pure ASCII (satisfies check-ascii-source).

5-bullet status

• Status: Regression test (xfail) + docs workaround added; crash reproduced on CUDA + Vulkan and traced to upstream Slang autodiff, not SlangPy.
• Link: [Bug] Backward dispatch segfaults when a [Differentiable] function has a loop with a negative runtime start value #1051 (upstream: [autodiff] bwd_diff of a [Differentiable] loop with a runtime (non-constant) induction start crashes (SPIR-V ICE / CUDA SIGSEGV) slang#12070)
• Verdict: Not a SlangPy-fixable codegen bug — SlangPy delegates the whole function body to bwd_diff. In-repo action is coverage + docs only.
• Next-action: Upstream fix in shader-slang/slang (per the upstream analysis on slang#12070, reverse-mode reconstruction splices the loop's non-constant counter offset into the reverse scope without a remap/constant-guard) is owned by a separate Slang chain. When it lands, the strict xfail XPASSes → remove the marker + subprocess isolation.
• Blocker: None. Issue stays open tracking the upstream fix.

_{🤖 Generated by an automated SlangPy coworker — may be inaccurate. A human maintainer should verify.}

[nv-slang-bot]

Status: this PR is BLOCKED on a CI/test-harness issue that is not a defect in this PR's code — do not merge; held pending a maintainer/operator decision.

• What's red: the ci GPU test lanes hang. The Unit Tests (Python) step on the macOS-aarch64 lanes runs to the 6h job timeout (cancelled at 360min) and the x86_64 linux/windows lanes are killed ~128min mid-test. Non-GPU (linux-aarch64) build+test lanes pass in minutes.

• Root-caused to NOT be this PR's content. The test file here ships only two constant-start control tests + a docs note (the deliberately-crashing runtime-start case was already removed); the controls pass locally 4/4. Dropping the crashing test did not stop the hang, and rebasing onto current main (0-behind) did not stop it — so stale-base and the crashing-test are both ruled out. For comparison, other current PRs pass the identical 12-job CI matrix in ~12–17min, so this is not a general CI outage.

• Open question (tracked separately): why a ~140-line test file wedges the full GPU Unit Tests (Python) suite for hours is undiagnosable without GPU-runner access — a SlangPy CI-harness investigation, distinct from the functional change here.

• Disposition in flight: a maintainer/operator is deciding between (a) a GPU-runner bisect and (b) landing the docs + constant-start controls now and deferring the GPU-hanging piece, with follow-ups tracked. This PR stays a draft and must not be flipped/merged by automation.

• Scope reminder: the underlying [Bug] Backward dispatch segfaults when a [Differentiable] function has a loop with a negative runtime start value #1051 crash is fixed upstream in the Slang compiler ([autodiff] bwd_diff of a [Differentiable] loop with a runtime (non-constant) induction start crashes (SPIR-V ICE / CUDA SIGSEGV) slang#12070 → PR Fix reverse-mode autodiff for runtime induction start (#12070) slang#12072); issue [Bug] Backward dispatch segfaults when a [Differentiable] function has a loop with a negative runtime start value #1051 stays open until that lands in a released wheel. This PR is regression coverage + docs only.

• Harness-hang tracked separately: the GPU Unit Tests (Python) wedge is filed as CI: GPU "Unit Tests (Python)" step wedges to the 6h timeout with a specific test file (surfaced in #1053) #1070 for investigation (independent of this PR's correctness).

_{🤖 Generated by an automated SlangPy coworker — may be inaccurate. A human maintainer should verify.}

[jhelferty-nv]

Assigning over to @saipraveenb25 since he owns shader-slang/slang#12070 where this will ultimately need to be fixed

[nv-slang-bot]

Update — the upstream root cause is fixed; this PR's remaining gate is the bundled-Slang pin, not a release.

Correcting my 2026-07-14 note above, which is now stale in three ways:

• Upstream fix landed. shader-slang/slang#12299 ("Preserve runtime induction values in reverse differentiation", @saipraveenb25) merged to master 2026-08-03T21:28:38Z as 546ad18f. It supersedes the earlier draft slang#12072. slang#12070 and slangpy#1051 are both closed.
• The gate for re-adding the runtime_start case is the SGL_SLANG_VERSION bump — not "the next wheel". SlangPy bundles Slang as a release tarball pinned at external/CMakeLists.txt:85, currently 2026.12 (last bumped 2026-06-30, Update to slang 2026.12 #1037). 546ad18f is 25 commits ahead of the newest Slang tag v2026.14.1, so it is in no released tarball yet. A wheel cut today would still bundle Slang 2026.12 and the test would fail for the original reason. Sequence: merge ✅ → Slang tag containing 546ad18f ⏳ → slangpy pin bump ⏳.
• Earlier verification is available without waiting for either. ci-latest-slang.yml builds slangpy main against Slang master; the two repository_dispatch runs it fired for slang#12299 (30836651948, 30848628629) both passed, GPU Unit Tests (Python) included. A workflow_dispatch with slang_branch=master would confirm the fix against slangpy before any tag exists.

On the CI blocker (#1070), one caveat worth flagging before assuming this PR is unblocked. #1070 was closed as "the race condition in profiling", but two things don't fit, and I'd rather raise them than quietly rely on them:

• The profiler feature (src/sgl/utils/profiler.cpp, "Profiler (Profiler #1063)" dac9e0e3, merged 07-13T17:02Z) is absent from 5 of the 6 wedged commits on this branch (2b2379d2, 6c656dc9, a7294115, 6c64cee0, bc4e5ba2; 07-12T17:03 → 07-13T14:33). Only 0fb3344 contains it.
• Temporarily disable intermittent profiler tests #1076 (merged 07-28) added doctest::skip() to two C++ test cases only; Fix profiler collector finalizing frames before consuming their zones (#1072) #1073, the actual fix, is still open. Neither changes the Python lane.

Across 07-29 → 08-03 there were 46 ci runs on 14 branches with zero wedges (Unit Tests (Python) median 1.70 min, max 7.00 min), so the lane looks healthy — but the signature only ever fired on dev/slangpy-fixer/1051, which hasn't run CI since 07-13, and its test file never reached main. That reads as unexercised, not proven fixed. Re-running this PR's CI is the measurement; I'm not assuming either outcome. Note the structural gap is still open on main: Unit Tests (Python) has no timeout-minutes, and tools/ci.py still uses --maxprocesses=4 (#1024 closed unmerged), so a recurrence would again burn 6h with no signal.

Suggested next step, @saipraveenb25 / @jhelferty-nv — since this PR is assigned to you, flagging rather than pushing: the docs half (the autodiff.rst workaround note) is worth landing on its own merits, though its "Until the upstream fix lands" wording should become past-tense now that #12299 is in. I can (a) rebase onto main and re-run CI to re-measure the hang, (b) update the docs wording, and/or (c) add runtime_start as a plain passing test once the pin moves to a Slang tag containing 546ad18f. Happy to do any of these on your word — no changes pushed in the meantime.

_{🤖 Generated by an automated SlangPy coworker — may be inaccurate. A human maintainer should verify.}