Reject ndarray fields inside template-annotated struct params

Passing structs containing ndarrays through qd.template() bypasses
argument pruning — every ndarray field gets registered regardless of
whether the kernel uses it — and inflates the cached launch context,
causing a measured 42% launch overhead on real workloads.  Raise a
clear QuadrantsCompilationError guiding users to use a concrete
dataclass type annotation instead.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: hughperkins

python/quadrants/lang/ast/ast_transformers/function_def_transformer.py

@@ -27,6 +27,7 @@
     ASTTransformerFuncContext,
 )
 from quadrants.lang.exception import (
+    QuadrantsCompilationError,
     QuadrantsSyntaxError,
 )
 from quadrants.lang.matrix import MatrixType
@@ -189,18 +190,12 @@ def _transform_as_kernel(ctx: ASTTransformerFuncContext, node: ast.FunctionDef,
 
     @staticmethod
     def _predeclare_struct_ndarrays(ctx: ASTTransformerFuncContext) -> None:
-        """Walk template args that are structs and pre-declare any ``Ndarray`` attributes as kernel args (via
-        ``decl_ndarray_arg``) so they are registered before ``finalize_params``. The resulting ``AnyArray`` objects are
-        cached on the global context for later lookup by ``build_Attribute``.
+        """Reject template-annotated struct args that contain ndarrays.
 
-        Also stores ``(arg_id, template_arg_idx, attr_chain)`` tuples in
-        ``ctx.global_context.struct_ndarray_launch_info`` so the launch path can populate the corresponding slots in the
-        launch context.
+        Passing ndarrays through ``qd.template()`` structs bypasses argument pruning (every ndarray field is registered
+        regardless of whether the kernel uses it) and inflates the cached launch context, causing measurable launch
+        overhead.  Users should annotate such parameters with a concrete ``@dataclass`` type instead.
         """
-        from quadrants.lang.util import cook_dtype  # pylint: disable=C0415
-
-        cache = ctx.global_context.ndarray_to_any_array
-        launch_info = ctx.global_context.struct_ndarray_launch_info
 
         def _walk_obj(obj, arg_idx, path):
             if dataclasses.is_dataclass(obj) and not isinstance(obj, type):
@@ -209,36 +204,33 @@ def _walk_obj(obj, arg_idx, path):
                     if isinstance(child, _TensorClass):
                         child = child._unwrap()
                     if isinstance(child, _ndarray.Ndarray):
-                        _register_ndarray(child, arg_idx, (*path, field.name))
+                        param_name = ctx.func.arg_metas[arg_idx].name
+                        attr_path = ".".join((*path, field.name))
+                        raise QuadrantsCompilationError(
+                            f"Kernel parameter '{param_name}' is annotated as qd.template(), but "
+                            f"'{param_name}.{attr_path}' is a qd.ndarray. Passing ndarrays through "
+                            f"template structs is not supported because it bypasses argument pruning "
+                            f"and degrades launch performance. Use a concrete struct annotation "
+                            f"(e.g. a @dataclass type hint) instead of qd.template() for struct "
+                            f"parameters that contain ndarrays."
+                        )
                     elif dataclasses.is_dataclass(child) and not isinstance(child, type):
                         _walk_obj(child, arg_idx, (*path, field.name))
             else:
                 for attr_name, attr_val in vars(obj).items():
                     if isinstance(attr_val, _TensorClass):
                         attr_val = attr_val._unwrap()
                     if isinstance(attr_val, _ndarray.Ndarray):
-                        _register_ndarray(attr_val, arg_idx, (*path, attr_name))
-
-        def _register_ndarray(nd, arg_idx, attr_chain):
-            key = id(nd)
-            if key in cache:
-                return
-            from quadrants._lib import core as _qd_core  # pylint: disable=C0415
-
-            element_type = cook_dtype(nd.element_type)
-            ndim = len(nd._physical_shape)
-            needs_grad = nd.grad is not None
-            layout = getattr(nd, "_qd_layout", None)
-            name = f"__qd_struct_nd_{key}"
-            arg_id_vec = impl.get_runtime().compiling_callable.insert_ndarray_param(
-                element_type, ndim, name, needs_grad
-            )
-            arr = any_array.AnyArray(
-                _qd_core.make_external_tensor_expr(element_type, ndim, arg_id_vec, needs_grad, BoundaryMode.UNSAFE),
-                _qd_layout=layout,
-            )
-            cache[key] = arr
-            launch_info.append((arg_id_vec[0], arg_idx, attr_chain))
+                        param_name = ctx.func.arg_metas[arg_idx].name
+                        attr_path = ".".join((*path, attr_name))
+                        raise QuadrantsCompilationError(
+                            f"Kernel parameter '{param_name}' is annotated as qd.template(), but "
+                            f"'{param_name}.{attr_path}' is a qd.ndarray. Passing ndarrays through "
+                            f"template structs is not supported because it bypasses argument pruning "
+                            f"and degrades launch performance. Use a concrete struct annotation "
+                            f"(e.g. a @dataclass type hint) instead of qd.template() for struct "
+                            f"parameters that contain ndarrays."
+                        )
 
         assert ctx.py_args is not None
         for i, arg_meta in enumerate(ctx.func.arg_metas):