Add BufferView: safe sub-range ndarray access for kernels

[alanray-tech]

Migrated from #445 (fork branch) to this in-repo branch per @hughperkins' request, so that CI AI review jobs can run. All commits, review history, and discussion are preserved in #445.

Summary

BufferView provides a safe, zero-copy sub-range view into an ndarray for kernel arguments. It rewrites view[i] to arr[offset + i] at AST-translation time, requiring no IR modifications.

In debug mode (debug=True), it inserts runtime bounds assertions that report the kernel name, thread ID, file and line for every frame in the callstack.

API

from quadrants import BufferView
import quadrants as qd

qd.init(arch=qd.cpu, debug=True)

N = 32
data = qd.ndarray(qd.f32, shape=(N,))

# Slice an ndarray to create a view:
view = data[:16]          # offset=0, size=16

# Slice a view to create a subview (offsets accumulate):
sub = view[4:12]          # offset=4, size=8 into data

# Or use subview() with explicit offset and size:
sub = view.subview(offset=4, size=8)

# Kernel annotation - dtype is optional:
@qd.kernel
def scale(v: BufferView[qd.f32], factor: qd.f32):
    for i in range(v.size):
        v[i] = v[i] * factor

scale(data[:16], 2.0)

Slicing forms a closed chain: ndarray -> slice -> BufferView -> slice -> BufferView. Each step validates bounds against the parent.

Debug output (OOB access):

quadrants.lang.exception.QuadrantsAssertionError:
BufferView Out Of Range: kernel[kernel] tid=0, got index 16 (offset=0, size=16).
Callstack:
kernel (script.py:12)
  writer (script.py:7)

Design notes

• Zero C++ changes. All features are implemented purely in the Python AST transformation and runtime layers.
• Host-side validation: BufferView.__init__ coerces offset/size to int and checks bounds (1D, non-negative, within ndarray length). subview() and slice validate against the parent view's size.
• Device-side validation: subscript() inserts qd_assert(0 <= i < size) in debug mode, with kernel name, thread ID, and full callstack in the error message. _subview_expr() inserts qd_assert(offset >= 0, size >= 0, offset + size <= parent_size).
• BufferView[dtype] annotation delegates to BufferViewType via __class_getitem__. dtype can be omitted - Quadrants infers it from the passed ndarray at compile time.
• Kernel-side slicing: v[4:8] inside a kernel is intercepted by impl.subscript() and routed to subview().

Files changed

File	Change
python/quadrants/lang/buffer_view.py	New - BufferView class with subview(), _subview_expr(), __getitem__ slice, __class_getitem__, debug OOB
python/quadrants/types/buffer_view_type.py	New - BufferViewType annotation
python/quadrants/lang/impl.py	BufferView dispatch in subscript / assign, kernel-side slice support
python/quadrants/lang/_func_base.py	BufferViewType param handling, dtype-optional support
python/quadrants/lang/_template_mapper_hotpath.py	BufferViewType cache key + dtype validation
python/quadrants/lang/ast/.../function_def_transformer.py	AST decomposition for BufferViewType, @qd.func support
python/quadrants/lang/_ndarray.py	_slice_to_buffer_view enables data[:16] slice syntax
python/quadrants/lang/matrix.py	Slice guard for VectorNdarray and MatrixNdarray
python/quadrants/lang/__init__.py	Export BufferView, filter buffer_view module from all
python/quadrants/types/__init__.py	Export BufferViewType
python/quadrants/types/enums.py	Add BoundaryMode to all, improve error message
tests/python/test_api.py	Add BufferView to expected public API list
docs/source/user_guide/buffer_view.md	New - user-facing guide
docs/source/user_guide/index.md	Add buffer_view to Core concepts toctree
tests/python/test_buffer_view.py	New - 40 tests

See user-facing documentation for full usage guide.

Test plan (40 tests)

Group A - Slice syntax + host-side validation (17 tests)

• Slice semantics: data[:16], data[8:24], data[:], data[8:], data[-8:]
• Error paths: step!=1, 2D array, negative offset, negative size, exceeds length
• Subview: view.subview(4, 8), subview OOB, chained view[4:12], view step error, view int index error
• VectorNdarray slice, explicit constructor

Group B - Kernel functional tests (10 tests)

• BufferView[dtype] and plain BufferView annotations
• Write isolation, v.size iteration, multiple views, @qd.func annotation
• Kernel-internal: BufferView(arr, off, sz) construction, v.subview(4, 4), v[4:8] slice
• Type mismatch error

Group C - Debug mode: OOB + callstack (13 tests, x64 + cuda)

• subscript() bounds: upper, lower, offset/size in message, nested callstack
• _subview_expr() bounds: subview OOB
• No false positive, no assertion without debug mode

All 40 tests pass on x64 and cuda backends.

AI Attestation

See timestamped comment in #445.

Maintenance

I will monitor and respond to any bugs or issues related to this feature.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 412cb1f4f6

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[github-actions]

Coverage Report (03e4d02c9)

File	Coverage	Missing
🔴 python/quadrants/lang/__init__.py	0%	7
🟢 python/quadrants/lang/_func_base.py	92%	38
🟢 python/quadrants/lang/_ndarray.py	91%	266
🟢 python/quadrants/lang/_template_mapper_hotpath.py	92%	39
🔴 python/quadrants/lang/ast/ast_transformers/function_def_transformer.py	79%	24,31,226
🔴 python/quadrants/lang/buffer_view.py	67%	3,5-9,11,14,28,35,49-56,58-62,65,70,94,96-97,100,103,114,123-124,128,143-144,173,188-189,230,235
🟢 python/quadrants/lang/impl.py	83%	21,259
🔴 python/quadrants/lang/matrix.py	75%	1717
🔴 python/quadrants/types/__init__.py	0%	13
🔴 python/quadrants/types/buffer_view_type.py	21%	1,4,25,30-34,36-37,40
🔴 python/quadrants/types/enums.py	0%	15,47
🟢 tests/python/test_buffer_view.py	99%	366-367,468

Diff coverage: 88% · Overall: 61% · 549 lines, 68 missing

Full annotated report

[alanray-tech]

Inline comments for the two codex review fixes: kernel-side bounds assertion and slice step rejection.

[hughperkins]

Note: some comment underwraps to address: https://github.com/Genesis-Embodied-AI/quadrants/actions/runs/25045033191/job/73357813381

[github-actions]

Coverage Report (97ba51b81)

File	Coverage	Missing
🔴 python/quadrants/lang/__init__.py	0%	7
🟢 python/quadrants/lang/_func_base.py	92%	38
🟢 python/quadrants/lang/_ndarray.py	91%	266
🟢 python/quadrants/lang/_template_mapper_hotpath.py	92%	39
🔴 python/quadrants/lang/ast/ast_transformers/function_def_transformer.py	79%	24,31,226
🔴 python/quadrants/lang/buffer_view.py	70%	3,5-9,11,14,28,35,49-56,58-62,65,70,94,96-97,100,103,124,133-134,138,153-154,183,198-199,240,245
🟢 python/quadrants/lang/impl.py	86%	21,259
🔴 python/quadrants/lang/matrix.py	75%	1717
🔴 python/quadrants/types/__init__.py	0%	13
🔴 python/quadrants/types/buffer_view_type.py	21%	1,4,24,29-33,35-36,39
🔴 python/quadrants/types/enums.py	0%	15,47
🟢 tests/python/test_buffer_view.py	98%	367-369,382-383,484,500

Diff coverage: 88% · Overall: 73% · 584 lines, 72 missing

Full annotated report

[hughperkins]

Once you are ready-ish to merge, could you run Genesis benchmarks and unit-tests please.

There are three approaches that I know of to do this:

1. create a pre-release release of Quadrants (I have a video I can send you of how to do this), then create a draft PR onto Genesis, that updated quadrants version to use the release, and wait for PR to run
   • this is the easiest way, and if you're not sure waht to do, I'd go this way
   • the main downside is that it takes a lloooonnnggg elapsed timed
     - creating the pre-release takes ~1.5 hours
     - then waiting for CI to run on Genesis another ~2-4 hours, depending on CI load
2. spin up your own cluster node, run the benchmarks and unit tests manually somehow
   • I wouldn't recommend this route, on the whole. Hard to do, easy to make errors, not very repeatable, doesnt give you a nice results table
3. use my script at https://github.com/Genesis-Embodied-AI/cmp-tooling/blob/main/bench_cluster_wandb.py (and also unit_tests_cluster.py)
   • does eveyrhting for you, once you've done initial setup (primarliy cloning repos in the right relative locations)
   • gives you a nice results table at teh end
   • just run a single command (once initial setup is done)

[alanray-tech]

Once you are ready-ish to merge, could you run Genesis benchmarks and unit-tests please.

There are three approaches that I know of to do this:

1. create a pre-release release of Quadrants (I have a video I can send you of how to do this), then create a draft PR onto Genesis, that updated quadrants version to use the release, and wait for PR to run

   • this is the easiest way, and if you're not sure waht to do, I'd go this way
   • the main downside is that it takes a lloooonnnggg elapsed timed
     • creating the pre-release takes ~1.5 hours
     • then waiting for CI to run on Genesis another ~2-4 hours, depending on CI load

2. spin up your own cluster node, run the benchmarks and unit tests manually somehow

   • I wouldn't recommend this route, on the whole. Hard to do, easy to make errors, not very repeatable, doesnt give you a nice results table

3. use my script at https://github.com/Genesis-Embodied-AI/cmp-tooling/blob/main/bench_cluster_wandb.py (and also unit_tests_cluster.py)

   • does eveyrhting for you, once you've done initial setup (primarliy cloning repos in the right relative locations)
   • gives you a nice results table at teh end
   • just run a single command (once initial setup is done)

I think 3. is good enough.

• Do I need some account for the GPU cluster?
• Anything I need to provide after running this?

[hughperkins]

Once you are ready-ish to merge, could you run Genesis benchmarks and unit-tests please.
There are three approaches that I know of to do this:

1. create a pre-release release of Quadrants (I have a video I can send you of how to do this), then create a draft PR onto Genesis, that updated quadrants version to use the release, and wait for PR to run

   • this is the easiest way, and if you're not sure waht to do, I'd go this way

   • the main downside is that it takes a lloooonnnggg elapsed timed

     • creating the pre-release takes ~1.5 hours
     • then waiting for CI to run on Genesis another ~2-4 hours, depending on CI load

2. spin up your own cluster node, run the benchmarks and unit tests manually somehow

   • I wouldn't recommend this route, on the whole. Hard to do, easy to make errors, not very repeatable, doesnt give you a nice results table

3. use my script at https://github.com/Genesis-Embodied-AI/cmp-tooling/blob/main/bench_cluster_wandb.py (and also unit_tests_cluster.py)

   • does eveyrhting for you, once you've done initial setup (primarliy cloning repos in the right relative locations)
   • gives you a nice results table at teh end
   • just run a single command (once initial setup is done)

I think 3. is good enough.

• Do I need some account for the GPU cluster?
• Anything I need to provide after running this?

If you configure slack, it'll slack you the unit test stats, and an image of the benchmark results

• copy and paste the unit test stats here
• upload the benchmarks results image here

[hughperkins]

Yes, please submit a pr to improve this script :) thank you

…

On Wed, Apr 29, 2026, 07:19 alanray-tech ***@***.***> wrote: *alanray-tech* left a comment (Genesis-Embodied-AI/quadrants#585) <#585 (comment)> @hughperkins <https://github.com/hughperkins> I ran into a small issue running \unit_tests_cluster.py\ on the cluster. The script writes \salloc\ output to a hardcoded path /tmp/salloc_test.txt, which is currently owned by your user (\hugh:hugh), so my user gets \Permission denied\ when trying to write to it. Could you delete it when you get a chance? \ rm /tmp/salloc_test.txt \\ Alternatively, I could patch the script to use a per-user filename like /tmp/salloc_test_.txt\ — happy to open a quick PR on cmp-tooling if you prefer that. — Reply to this email directly, view it on GitHub <#585 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAA6FKEAW4C7JM3IJ7ZKHIL4YHQMXAVCNFSM6AAAAACYJCKIJGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DGNBTGE4TQNZQG4> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>. You are receiving this because you were mentioned.Message ID: ***@***.***>

[alanray-tech]

Genesis Validation Results

Unit Tests

python3 unit_tests_cluster.py --branch main --backend ndarray \
  --quadrants-branch feature/buffer-view --partition rtx-mid --time 60

Item	Value
Genesis branch	main (c5984a2)
Quadrants branch	feature/buffer-view (97ba51b)
Backend	ndarray
Partition	rtx-mid (8 GPU)
Duration	13m 22s

Result: 582 passed, 2 skipped, 2 xfailed, 0 failed

The 2 skips are pre-existing (SAPCoupler does not support ndarray yet). The 2 xfails are pre-existing known issues. No regressions introduced by BufferView.

Speed Benchmarks

python3 bench_cluster_wandb.py --ref buffer-view --branch main --backend ndarray \
  --quadrants-branch feature/buffer-view --partition rtx-mid --time 60

32 benchmarks passed. Branch results vs WandB main baseline (selected high-traffic envs):

Env	Backend	Batch	Branch FPS	Main FPS	Delta
franka	cuda	30000	15,999,389	15,852,506	+0.9%
franka_random	cuda	30000	12,348,453	12,508,873	-1.3%
franka_free	cuda	30000	21,251,349	21,284,966	-0.2%
anymal_uniform	cuda	30000	10,566,985	10,382,809	+1.8%
anymal_zero	cuda	30000	14,455,816	14,235,909	+1.5%
go2 (Newton)	cuda	4096	3,052,034	3,040,264	+0.4%
dex_hand	cuda	4096	14,196	14,257	-0.4%
box_pyramid_6	cuda	4096	53,062	51,841	+2.4%
shadow_hand_cubes	cpu	0	31	31	0.0%
franka_random	cpu	0	3,179	3,042	+4.5%

All deltas are within normal run-to-run variance (< 5%). No performance regressions.

[alanray-tech]

Final comprehensive review: inline comments on every changed file documenting the design intent and rationale for each modification. 15 files changed, 46 tests, 0 regressions in Genesis benchmarks (ndarray + field).

[alanray-tech]

Two construction paths gated by impl.inside_kernel():

Host-side: int() coercion + 1D shape check + bounds validation (offset >= 0, size >= 0, offset+size <= len).

Kernel-compilation: Debug-mode assertions via ExternalTensorShapeAlongAxisStmt (same IR instruction as C++ CheckOutOfBound pass). Validates offset >= 0, size >= 0, offset+size <= ndarray_length at device runtime.

[alanray-tech]

@hughperkins Merged latest main. I believe this PR is ready to merge once CI passes:

• All reviewer feedback addressed (API rename count->size, dtype-optional, doc rewrite, coverage fixes)
• Genesis validation: 582 unit tests passed (ndarray), 64 benchmarks passed (ndarray + field), no regressions
• 46 local tests covering all code paths (host slice, kernel annotation, subview, kernel slice, debug OOB with callstack, Matrix/Vector ndarray support)
• Inline review comments added on every changed file for documentation

Let me know if anything else is needed.

[alanray-tech]

Corrected inline review with accurate line references (post-merge). Documents design intent for every changed file.

[alanray-tech]

BufferView[qd.f32] -> BufferViewType(qd.f32). Lets BufferView serve as both runtime object and type annotation, consistent with Python generics (list[int]). The entire downstream pipeline (_func_base, _template_mapper_hotpath, function_def_transformer) recognizes BufferViewType instances -- no downstream changes needed.

[alanray-tech]

Two construction paths gated by impl.inside_kernel():

Host-side: int() coercion + 1D shape check + bounds validation.

Kernel-compilation: Debug-mode assertions via ExternalTensorShapeAlongAxisStmt (same IR instruction as C++ CheckOutOfBound pass) -- validates offset >= 0, size >= 0, offset+size <= ndarray_length at device runtime.

[alanray-tech]

subview() creates a narrower view within an existing view. Host path validates against self.size. Kernel path delegates to _subview_expr() which inserts three qd_assert calls (offset >= 0, size >= 0, offset+size <= parent_size) in debug mode.

[alanray-tech]

__getitem__ is only reachable on the host. Inside kernels, v[...] is intercepted by the AST transformer and dispatched through impl.subscript() -> subscript() (index) or subview() (slice). The assert guards against accidental future routing changes.

[alanray-tech]

_build_callstack is called at compile time. The callstack string is frozen as a literal in the compiled IR assertion message. Dynamic values (tid, index, offset, size) are injected at runtime via %d format args -- zero runtime string-building cost.

[alanray-tech]

Kernel-side v[4:8] slice: AST transformer's build_Subscript -> build_Slice -> impl.subscript(). Converts slice(start, stop) to subview(start, stop-start), inheriting debug-mode bounds assertions from _subview_expr(). Step != 1 is rejected.

[alanray-tech]

Slice guard for MatrixNdarray.__getitem__. Without this, mat_arr[:16] reaches tuple(key) -> TypeError: 'slice' object is not iterable. Same guard on both VectorNdarray.__getitem__ overrides.

[alanray-tech]

buffer_view excluded from __all__ to prevent the submodule name from leaking into the public API. BufferView (the class) is exported via from quadrants.lang.buffer_view import *; the module itself should not be user-visible.

[alanray-tech]

BoundaryMode was defined but absent from __all__. Pre-existing issue, fixed since BufferView uses BoundaryMode for boundary checking.

[alanray-tech]

BufferView registered as a new public API symbol. test_api checks qd.__all__ against this hardcoded list.

[hughperkins]

@claude review

[hughperkins]

Note: for claude review, whilst I think we should address 🔴 comments, I'll leave it to your own discretion whether you wish to address 🟡 comments.

[alanray-tech]

Addressed all three @claude review findings in 10b1065:

1. BufferViewType.boundary dead field — Removed self.boundary (string). All functional consumers read self.ndarray_type.boundary (int). __repr__ updated to use self.ndarray_type.boundary.

2. _build_callstack docstring typo — _CALLSTACK_WARNING_SIZE -> _CALLSTACK_WARNING_BYTE to match the actual constant name.

3. Kernel slice step error message — Changed from "requires step=1 (or omit step)" to "does not support an explicit step in kernels". This avoids the misleading suggestion that step=1 should work, since inside a kernel s.step is an Expr and cannot be compared to 1 at compile time.

[github-actions]

Coverage Report (6f780b0c6)

File	Coverage	Missing
🔴 python/quadrants/lang/__init__.py	0%	7
🟢 python/quadrants/lang/_func_base.py	92%	42
🟢 python/quadrants/lang/_ndarray.py	91%	391
🟢 python/quadrants/lang/_template_mapper_hotpath.py	92%	43
🔴 python/quadrants/lang/ast/ast_transformers/function_def_transformer.py	79%	29,36,351
🔴 python/quadrants/lang/buffer_view.py	76%	3,5-10,12,14,17,31,38,51,59,83,85-86,89,92,113,122-123,127,142-143,172,187-188,229,234
🟢 python/quadrants/lang/impl.py	86%	21,271
🟢 python/quadrants/lang/matrix.py	100%
🔴 python/quadrants/types/__init__.py	0%	13
🔴 python/quadrants/types/buffer_view_type.py	33%	1,4,23,28-29,32
🔴 python/quadrants/types/enums.py	0%	15,47
🟢 tests/python/test_buffer_view.py	98%	420-422,435-436,537,553

Diff coverage: 91% · Overall: 74% · 604 lines, 55 missing

Full annotated report

[github-actions]

Coverage Report (10b106524)

File	Coverage	Missing
🔴 python/quadrants/lang/__init__.py	0%	7
🟢 python/quadrants/lang/_func_base.py	92%	42
🟢 python/quadrants/lang/_ndarray.py	91%	391
🟢 python/quadrants/lang/_template_mapper_hotpath.py	92%	43
🔴 python/quadrants/lang/ast/ast_transformers/function_def_transformer.py	79%	29,36,351
🔴 python/quadrants/lang/buffer_view.py	76%	3,5-10,12,14,17,31,38,51,59,83,85-86,89,92,113,122-123,127,142-143,172,187-188,229,234
🟢 python/quadrants/lang/impl.py	86%	21,271
🟢 python/quadrants/lang/matrix.py	100%
🔴 python/quadrants/types/__init__.py	0%	13
🔴 python/quadrants/types/buffer_view_type.py	25%	1,4,23,27-28,31
🔴 python/quadrants/types/enums.py	0%	15,47
🟢 tests/python/test_buffer_view.py	98%	420-422,435-436,537,553

Diff coverage: 91% · Overall: 67% · 603 lines, 55 missing

Full annotated report

[alanray-tech]

Addressed @claude review (7c61de7):

1. _build_callstack dedup by funcname only (line 35) — Fixed. Now deduplicates by (filepath, funcname) instead of funcname alone. Same-named functions in different modules are no longer collapsed into a single frame.

2. __init__ kernel branch missing 1D check + callstack (line 106) — Not fixing. The ndim is already guaranteed by the compiler: function_def_transformer._decl_and_create_variable calls decl_ndarray_arg(..., ndim=1), so the backing array is always 1D by construction. Adding a redundant runtime check + callstack here would add complexity without catching any real bug. The existing three assertion args (offset >= 0, size >= 0, offset+size <= length) are sufficient.

[alanray-tech]

Fixed both @claude findings in 7cc3e3f:

1. Launch-context cache id-reuse bug (_func_base.py:685) — Changed return 3, True to return 3, False. Temporary BufferView objects created by data[:16] are GC'd between calls, and CPython can reuse the same memory address for the next data[16:32], causing cache hits with stale offset/size. Disabling cacheability is the correct fix — the ~540ns pybind11 overhead per call is negligible vs kernel execution time.

2. Silent gradient drop (buffer_view.py) — Added TypeError in host-side __init__ when the backing ndarray has .grad is not None. BufferView currently hardcodes needs_grad=False at three sites (cache key, decl_ndarray_arg, launch_ctx). Rather than threading gradient support through all three, we reject it early with a clear error. Gradient support can be added later if needed.

[claude]

🔴 🟡 The frozen-dataclass fast path at _func_base.py:626-650 discards the cacheability flag from each child's recursive call (line 637 destructures with _) and returns a hardcoded True (line 650), overriding the (3, False) that the BufferView branch correctly returns at line 685. So a frozen dataclass containing a BufferView field reintroduces the same id()-reuse silent corruption that commit 7cc3e3f closed at top level: fill(MyStruct(v=data[:16])) followed by fill(MyStruct(v=data[16:32])) can replay stale offset/size from the launch_ctx cache and write the wrong region. This is a pre-existing gap in the frozen-DC fast path (introduced in PR #561), but BufferView is the first user-facing arg type that documents transient-instance construction (data[:16]) where cacheability=False is correctness-critical. Fix is mechanical: mirror the non-frozen branch at lines 664-678 — capture each child's cacheability and AND-aggregate into a returned bool.

Extended reasoning...

What the bug is

The frozen-dataclass fast path in FuncBase._recursive_set_args discards the is_launch_ctx_cacheable flag from every recursive child call and unconditionally tells the caller the dataclass is cacheable. The non-frozen branch immediately below does this correctly — it AND-aggregates each child's cacheability and returns the result.

# python/quadrants/lang/_func_base.py:626-650 (frozen-DC, BUGGY)
if is_frozen:
    plan = _get_frozen_dc_plan(...)
    unwrapped = _get_frozen_dc_unwrapped(v, needed_arg_fields)
    for field_name, field_full_name, field_type in plan:
        field_value = unwrapped[field_name]
        num_args_, _ = FuncBase._recursive_set_args(...)   # ← cacheability discarded
        idx += num_args_
    return idx, True                                       # ← hardcoded True

# python/quadrants/lang/_func_base.py:651-678 (non-frozen, CORRECT pattern)
is_launch_ctx_cacheable = False  # (separately buggy — should be True, but irrelevant here)
for field in needed_arg_fields.values():
    ...
    num_args_, is_launch_ctx_cacheable_ = FuncBase._recursive_set_args(...)
    idx += num_args_
    is_launch_ctx_cacheable &= is_launch_ctx_cacheable_
return idx, is_launch_ctx_cacheable

The BufferView branch at line 685 correctly returns (3, False) — this is the fix from commit 7cc3e3f that closed the top-level id()-reuse bug for transient slices like data[:16]. But when a BufferView is wrapped in a frozen dataclass, that False is silently overridden back to True by line 650.

How it manifests

@dataclass(frozen=True)
class MyStruct:
    v: BufferView[qd.f32]

@qd.kernel
def fill(s: MyStruct):
    for i in range(s.v.size):
        s.v[i] = 1.0

data = qd.ndarray(qd.f32, shape=(64,))
fill(MyStruct(v=data[:16]))     # call 1: caches launch_ctx with offset=0, size=16
                                # MyStruct + BufferView GC'd; pymalloc returns slot to LIFO free list
fill(MyStruct(v=data[16:32]))   # call 2: NEW MyStruct lands at SAME id()
                                #   args_hash = (id(t_kernel), id(MyStruct))  →  cache hit
                                #   populate_launch_ctx_from_cache copies STALE offset=0, size=16
                                #   kernel writes data[0:16] AGAIN, data[16:32] untouched

Step-by-step:

1. kernel.py:461 computes args_hash = (id(t_kernel), *[id(arg) for arg in args]) — uses Python id() of each top-level arg, including the transient MyStruct wrapper.
2. After call 1, MyStruct and its BufferView field are GC'd. CPython pymalloc puts the slot back on a per-size-class LIFO free list.
3. Call 2 allocates a new MyStruct at the same address (deterministic on CPython for same-size-class objects).
4. _recursive_set_args runs the frozen-DC fast path; at line 637 it gets (3, False) from the BufferView child but discards the False.
5. Line 650 returns True → top-level caller treats the cache entry as valid.
6. populate_launch_ctx_from_cache (kernel.py:178) copies the cached launch_ctx wholesale, including the stale offset=0, size=16 values that launch_ctx.set_args_int baked in during call 1.
7. Kernel runs with stale offset/size — writes data[0:16] instead of data[16:32].

Expected: data[0:32] all 1.0. Actual: data[0:16] all 1.0, data[16:32] untouched. No exception.

Why existing safeguards don't prevent it

• The line-685 return 3, False fix from 7cc3e3f covers top-level BufferView args, but only because the top-level dispatch in Kernel.__call__ reads the returned cacheability directly. The frozen-DC parent intercepts and discards that signal one wrapping level deeper.
• LaunchContextBufferCache weakref-evict callbacks (kernel.py:122-153) only track _QD_ARRAY entries, which point at the long-lived inner.arr (the backing ndarray), not the transient wrapper. So GC of the wrapper does not invalidate the cache entry.
• The 40 BufferView tests in tests/python/test_buffer_view.py do not exercise frozen-DC + BufferView. test_multiple_views passes views in a single call (both alive at once, no id collision), not in sequential calls.
• The _template_mapper_hotpath cache key for BufferView at line 152 is (element_type, ndim, False, boundary) with no offset/size — so two slices like data[:16] and data[16:32] produce the same template-cache entry. That's correct for template caching but means they collide on the post-template launch-context cache too.

Pre-existing nature

This gap was introduced in PR #561 (the frozen-DC fast path). It would also affect frozen DCs with float fields (line 609 returns 1, False), large-int fields (line 619 conditional), and external arrays — any leaf that returns False. BufferView is the most user-facing new participant because the user guide explicitly documents data[:16] (transient slice) as the idiomatic usage pattern, and a user wrapping that in a @dataclass(frozen=True) is plausible.

The fix lives entirely in pre-existing code (lines 626-650 are not touched by this PR), so this technically meets the bar for pre_existing severity. I'm filing it as normal because:

1. The user-facing surface area materially expanded with this PR — BufferView is the first arg type whose documented idiom produces transient instances, and a user wrapping that pattern in a frozen DC is plausible.
2. Silent data corruption with a documented usage pattern warrants pre-merge attention rather than a follow-up.
3. The fix is mechanical (~3 lines) and matches an existing precedent already in the file.

Maintainers may reasonably disagree and prefer to land this and address the frozen-DC gap comprehensively in a follow-up that also covers float/int/external-array participants.

How to fix

Mirror the non-frozen branch's pattern (lines 664-678). Capture each child's cacheability, AND-aggregate into a running flag, return that instead of hardcoded True:

if is_frozen:
    plan = _get_frozen_dc_plan(...)
    unwrapped = _get_frozen_dc_unwrapped(v, needed_arg_fields)
    is_launch_ctx_cacheable = True   # ← initialize True for AND-aggregation
    for field_name, field_full_name, field_type in plan:
        field_value = unwrapped[field_name]
        num_args_, is_launch_ctx_cacheable_ = FuncBase._recursive_set_args(...)
        idx += num_args_
        is_launch_ctx_cacheable &= is_launch_ctx_cacheable_
    return idx, is_launch_ctx_cacheable

Note: the non-frozen branch at line 652 initializes is_launch_ctx_cacheable = False, which makes False & x = False always — the non-frozen path is over-conservative (no cache hits), the frozen path is over-optimistic (stale cache hits). The frozen-path fix above uses the correct True initializer; the non-frozen-path's False initializer is a separate pre-existing bug worth addressing in the same patch but doesn't affect this verdict.

[hughperkins]

Reminder: no obligation to handle the 🟡 . And every time you handle a 🟡 you risk getting a new 🔴 :). Just handle the 🟡 if you want to (if you think it's going to be useful to you, in the short-term). You can always make newer PRs later.

[alanray-tech]

Addressed 2 of 3 @claude findings in ffd7334:

Doc: needs_grad limitation — Added to the Limitations section in buffer_view.md.

Nested BufferView(view, ...) rejection — Added isinstance(arr, BufferView) check in __init__ with clear error message pointing to subview().

---

Re: frozen dataclass cache override (_func_base.py:626-650) — This is a pre-existing issue in the frozen-dataclass fast path (introduced in PR #561), not specific to BufferView. The fast path discards is_launch_ctx_cacheable from child fields and hardcodes True, which would override our return 3, False fix for any dataclass containing a BufferView field.

@hughperkins Should this be tracked as a separate issue? The fix would be to propagate the cacheability flag in the frozen-DC fast path, but that changes behavior for all frozen dataclass args, not just BufferView.

[alanray-tech]

For context on the launch-ctx cache issue — here's a concrete example of the id-reuse bug that return 3, False fixes:

data = qd.ndarray(qd.f32, shape=(32,))
data.from_numpy(np.zeros(32, dtype=np.float32))

@qd.kernel
def fill(v: BufferView[qd.f32]):
    for i in range(v.size):
        v[i] = 1.0

# Call 1
fill(data[:16])       # temp BufferView(data, 0, 16), id=0xABC
                       # cache miss -> set launch_ctx: arr=data, offset=0, size=16
                       # cache stores: key=id(0xABC) -> launch_ctx
                       # executes: data[0:16] = 1.0  (correct)
                       # call returns, temp object has no refs -> GC frees 0xABC

# Call 2
fill(data[16:32])     # new BufferView(data, 16, 16)
                       # CPython pymalloc reuses address -> id=0xABC (same as call 1!)
                       # cache hit -> reuses old launch_ctx: offset=0, size=16
                       # executes: data[0:16] = 1.0 again  (WRONG! should write data[16:32])

# Expected: all 32 elements = 1.0
# Actual:   data[0:16] = 1.0, data[16:32] = 0.0 (second call wrote to wrong region)

The root cause is that id(arg) is used as the cache key, but CPython reuses memory addresses for short-lived objects of the same size. return 3, False disables caching for BufferView, so launch_ctx is always rebuilt with the correct offset/size.

The frozen-dataclass fast path (_func_base.py:626-650) has the same vulnerability: it discards child is_launch_ctx_cacheable flags and hardcodes True, so a frozen dataclass containing a BufferView field would re-enable caching and reproduce this bug. This is a pre-existing issue in the DC fast path, not introduced by BufferView.

[alanray-tech]

@hughperkins Thanks for the guidance. I'll stop addressing further 🟡 nits here — the remaining findings (kernel-side nested BufferView rejection, frozen-DC cache propagation) are edge cases that can be handled in follow-up PRs.

The PR is ready for merge from my side. Summary of current state:

• 46 tests, all passing (host slice, kernel annotation, subview, kernel slice, debug OOB with callstack, Matrix/Vector ndarray support)
• Genesis validation: 582 unit tests passed, 64 benchmarks passed (ndarray + field), no regressions
• All reviewer feedback addressed (API, docs, coverage, cache safety, gradient guard)

[github-actions]

Coverage Report (ffd7334c1)

File	Coverage	Missing
🔴 python/quadrants/lang/__init__.py	0%	7
🟢 python/quadrants/lang/_func_base.py	92%	42
🟢 python/quadrants/lang/_ndarray.py	91%	391
🟢 python/quadrants/lang/_template_mapper_hotpath.py	92%	43
🔴 python/quadrants/lang/ast/ast_transformers/function_def_transformer.py	79%	29,36,351
🔴 python/quadrants/lang/buffer_view.py	75%	3,5-10,12,14,17,31,39,52,60,84,86-87,90,93,112,114,118,127-128,132,147-148,177,192-193,234,239
🟢 python/quadrants/lang/impl.py	86%	21,271
🟢 python/quadrants/lang/matrix.py	100%
🔴 python/quadrants/types/__init__.py	0%	13
🔴 python/quadrants/types/buffer_view_type.py	25%	1,4,23,27-28,31
🔴 python/quadrants/types/enums.py	0%	15,47
🟢 tests/python/test_buffer_view.py	98%	420-422,435-436,537,553

Diff coverage: 91% · Overall: 74% · 608 lines, 57 missing

Full annotated report

[hughperkins]

Thanks! 🙌