Release 0.7.0

.github/workflows/verify-gpu-proof.yml

@@ -73,13 +73,15 @@ jobs:
       - name: Install GRiD (CPU deps only)
         # Packaging unit tests import the build hooks outside pip's isolated
         # build environment, so their setuptools dependency must be explicit.
-        # pytest-gpu-proof requires CPython 3.11 or newer; on 3.10 the two
-        # plugin-scope test modules importorskip it and everything else runs.
+        # The pinned plugin supports every interpreter in this matrix; receipt
+        # tooling and scope regressions must also execute on Python 3.10.
         run: |
           pip install -e . && pip install pytest matplotlib pyyaml "setuptools>=77"
-          if python -c 'import sys; sys.exit(0 if sys.version_info >= (3, 11) else 1)'; then
-            pip install "$(grep -o '^pytest-gpu-proof==[0-9.]*' install/requirements-dev.txt)"
-          fi
+          pip install "$(grep -o '^pytest-gpu-proof==[0-9.]*' install/requirements-dev.txt)"
+          # The Pinocchio anchors of the CPU lane (test_manifold_conventions,
+          # test_urdf_oracle) import pinocchio; the same load-bearing pins as
+          # install/requirements-dev.txt and the RBDReference peer suite.
+          pip install "pin<4" cmeel-eigen "cmeel-urdfdom<5"
 
       # The BROAD CPU set (audit W00, 2026-09-19): every test/test_*.py + the
       # benchmark-spec guards + the CPU-only bindings modules. The former six-

CHANGELOG.md

@@ -12,6 +12,144 @@ repository. Everything below describes the packaged A2R-Lab releases.
 
 ## [Unreleased]
 
+## [0.7.0] — 2026-10-31
+
+Consumers rebuild their prepared artifacts (schema 2), declare pybind modules
+with `python_extension=True` and pass `CollisionMargins` where a scalar margin
+went before; the migration steps are on the documentation's *Migrating to 0.7*
+page, which this changelog does not repeat.
+
+- Make the spherizer's warnings errors on the generated-from-mesh collision
+  routes (`collision=True`, `collision_native=True`, `grid-generate -c`,
+  `grid-spherize`): a mesh whose voxel fill failed and would be replaced by a
+  bounding-box cover, or a model with no spheres, stops generation because
+  either silently changes the clearance rows a consumer bakes.
+  `strict_collision=False` on `build_artifact`, `--no-strict-collision` on the
+  two command lines, and `strict=False` on `spherize_urdf` accept them with the
+  warning. The opt-out is part of the artifact's input key.
+- Rename `ConsumerArtifact.descriptor` to `model_descriptor`, the name the
+  robot handle uses for the same metadata.
+- Keep the double-precision cells of the suites added in this release in the
+  fp64 alpha lane (`make test-fp64`), outside the signed receipt, the policy
+  the fp64 tier has had since 0.5.3; the receipt keeps a float cell of every
+  configuration those suites cover.
+- Add the skew revolute mimic fixture `revolute_mimic_fixed_tool` with
+  closed-form mechanics checks of the numpy oracle and the generated CUDA
+  inverse dynamics, forward dynamics, ABA, mass matrix and its inverse.
+- Compile the CUDA equivalence runners with `-std=c++17`, the header's
+  documented standard; the generated constexpr record accessors use switch
+  bodies, which the runners' former `-std=c++11` flag rejected.
+- Update GLASS to `6a82320`, which declares no `__restrict__` on its own
+  interfaces and carries a regression for the selected-operand miscompile
+  (nvcc 11.4 through 13.2 dropped the stores of an inlined scalar joint
+  transform writer whose output a restricted gemm operand selected). The scalar
+  joint transform writer is inlined again; no call frame in consumer suffixes.
+- Add thread-local full-configuration and independent-scalar joint transforms,
+  plus compact and dense native configuration-difference Jacobians derived from
+  the model descriptor's coordinate partition. Document buffer ownership,
+  runtime-table limits, parameter lifetime and defect composition.
+- Repair admitted fixed-spherical Euler/semi-implicit step second derivatives
+  in the CPU reference and generated CUDA. Stabilize small-angle reference
+  Rodrigues coefficients. Clarify that `plant_step_hessian` differentiates the
+  moving-basis gradient: it is not a fixed-chart or shooting-defect Hessian.
+- Add checked generated cost-menu views, explicit full-shared/deep-spill
+  fixed-base plant-Hessian views with matched evaluators, gradient initialization
+  extents, and exact target EE inner scratch queries. Keep allocation, collective
+  synchronization, invocation ownership and actual enclosing-kernel resource
+  admission explicit. Correct the plant-Hessian launch-size query's missing
+  runtime-transform reserve using the same resolved layout as its kernel.
+  Numerical arithmetic and tier selection are unchanged.
+- Add CPU model inspection and generated host/device coordinate/frame metadata
+  with explicit independent ownership, xyzw conventions and typed canonical
+  identity. A single-body-pose frame composer requires no FK pass or shared
+  scratch and refuses nominal runtime-transform offsets. Wrapper metadata is
+  derived from the same descriptor. Consumer artifact schema 2 validates the
+  descriptor/header/binary association on build, reuse and source-free prepared
+  load; older prepared artifacts require rebuilding. Descriptor identity is
+  not complete dynamics or artifact identity.
+- Omit zero-weight reduced projections in floating-base constant-joint CRBA
+  while retaining composite inertia and transport through constant ancestors.
+  Add FP32/FP64 floating and fixed-base descendant dynamics tests against
+  independently locked models, including first and second derivatives.
+- Preserve coordinate ownership in homogeneous derivative tables and EE
+  gradient/Hessian metadata when constant joints are retained. Correct empty
+  coordinate generation in integrator/plant arena binders. Add zero-DoF pose
+  Hessian and Euler plant-gradient device canary tests plus nonempty controls.
+  Preserve non-unit mimic scaling when an EE Jacobian column has just one
+  contribution, including after a constant column is removed.
+- Exclude constant-joint reduced rows/columns in fixed-base mimic CRBA, preserving
+  composite inertia and ancestor transport. This removes a zero-size mass-matrix
+  access exposed by FP64 memcheck through the Euler plant-gradient path.
+- Omit constant-joint local columns and zero-weight projection reads in generated
+  inverse-dynamics derivatives, second-order folds, frame Jacobians/Jdot and
+  Coriolis metadata. Retain inherited body motion and force transmission. Add
+  independent locked-model, poisoned-branch and empty-buffer CUDA regressions;
+  these do not establish general zero-DoF wrapper or timing support.
+- Match plant-step, gradient and Hessian C ABI gravity/timestep scalars to the
+  selected precision, including MuJoCo entry points. FP64 callers previously
+  passed doubles to float arguments; add signature and numerical regressions.
+- Size the full-shared plant-gradient arena independently of the tier-selected
+  integrator allocation. Reject oversized plant-gradient calls before launching;
+  retain the tiered integrator-gradient path. Share spherical scratch dimensions
+  and test compiled carve bounds, canaries and device admission. Fix template
+  commas in generated debug-layout assertions.
+- Correct constant-mimic coordinate evaluation: fixed-leader chains keep their
+  composed offset without reading an unrelated q slot. Match block and
+  thread/warp FK emission and omit zero local motion/projection contributions in
+  the reference while retaining body motion and transmitted forces. Add
+  direct/chained, empty-coordinate and FP32/FP64 CUDA regressions.
+- Do not read placeholder velocity/acceleration slots or project zero local
+  contributions in generated inverse dynamics for constant joints. Add a
+  branched FP32/FP64 poison regression that preserves genuine NaN inputs.
+- Update GLASS first to `9a24f37` for cooperative handoff reloads under
+  restricted callers (the release pin is `6a82320`, above). Add embedded FP32/FP64 solve, eigenvalue-clamp and pivoted-inverse
+  regressions with poisoned scratch and thread-count checks. Update
+  pytest-gpu-proof to 0.5.0, enable receipt-tooling CPU checks on Python 3.10,
+  and test compiler-metadata merge refusal and legacy-field compatibility.
+- Capture consumer translation-unit dependencies with `nvcc -MM` and hash the
+  selected non-system header contents into artifact and per-unit reuse keys.
+  Build lookups rediscover include selection, including newly shadowing headers;
+  prepared loads remain compiler-free. Explicit headers supplement discovery,
+  while omitted system development headers remain a documented environment
+  assumption. No stat-based hashing shortcut or kernel change is introduced.
+- Project fixed-base skew-axis mimic forces and mass matrices through every
+  nonzero motion-subspace component instead of a cardinal-axis index. Independent
+  slider mechanics now check ID/FD/ABA/M/Minv, with first derivatives on cardinal
+  slider/mimic cases. This is not a claim of general skew-mimic derivative support.
+- Add an executable native/Python consumer migration example and process-death
+  publication recovery tests. Document the non-transactional crash boundary and
+  the tested GCC/CUDA scope separately from Clang flag recognition.
+- Add independent environment and self clearances to collision feasibility checks
+  through `CollisionMargins<T>` and the validating host factory
+  `make_collision_margins`. Scalar calls still apply one margin to both; explicit
+  per-side zero overrides are supported. The trailing self toggle, raw distances,
+  normals and cost derivatives retain their meanings.
+- Isolate consumer-library symbols by default. Native C entry points now require
+  explicit default visibility; pybind initialization exports remain visible.
+  Consumer compile and link share a recorded host-compiler selection, with
+  GCC-only GNU-unique suppression. GRiD's wrapper export policy is unchanged.
+- Add `python_extension=True` to consumer builds. Interpreter ABI identity guards
+  pointer, content and object reuse and prepared loads; native artifacts remain
+  independent of Python. Builds verify the declaration against exported Python
+  initialization symbols before publication.
+- Repair incomplete wrapper and consumer cache entries under a per-content
+  publication lock. Private staging, object, pointer and identity temporary files
+  distinguish concurrent threads as well as processes. Publication I/O failures propagate
+  instead of being mistaken for a completed concurrent build. Malformed identity
+  records are cache misses; permission failures remain errors.
+- Include resolved source paths and suffixes in consumer reuse identity (including
+  path-sensitive `__FILE__` expansions), and use
+  distinct output paths for same-stem sources such as `kernel.cu` and
+  `kernel.cpp`. Collision requests fingerprint resolved mesh paths and bytes
+  before reusing a cached artifact.
+- Fix generation for all-prismatic robots with fixed tool targets, initialize
+  mimic coordinates on no-trigonometry transform paths, and use typed block
+  loads on those paths. One-DoF second-order contraction uses an untiled width
+  of one instead of failing to select a tile.
+- Floor a warm compile job's memory prediction at the largest measured peak
+  among variants of the same robot. A relink measurement cannot reduce that
+  floor; first-job admission and the default for unmeasured jobs are unchanged.
+
 ## [0.6.0] — 2026-10-24
 
 - Margin-aware collision checking (HJCD-IK ask G7). `grid_collision::config_free` on the block,
@@ -470,7 +608,8 @@ update on top of that, organised here by theme:
 - Closed kinematic loops are unsupported.
 - No Windows, macOS, Jetson or precompiled-robot wheels.
 
-[Unreleased]: https://github.com/A2R-Lab/GRiD/compare/v0.6.0...HEAD
+[Unreleased]: https://github.com/A2R-Lab/GRiD/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/A2R-Lab/GRiD/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/A2R-Lab/GRiD/compare/v0.5.5...v0.6.0
 [0.5.5]: https://github.com/A2R-Lab/GRiD/compare/v0.5.4...v0.5.5
 [0.5.4]: https://github.com/A2R-Lab/GRiD/compare/v0.5.3...v0.5.4

CLAUDE.md

@@ -73,7 +73,7 @@ to the harness's real skip strings by `test/test_suite_floor.py`. GPU test outco
 test fingerprints (red when correctness inputs change without a refreshed receipt).
 Main requires a receipt whose collection EQUALS `test/gpu-proof-tests.txt` (policy
 `required_test_manifest`); diagnostic smoke receipts do not replace that evidence. A release needs one fresh full run
-verified under the RELEASE policy. pytest-gpu-proof is pinned at 0.4.1 (`install/requirements-dev.txt`, CI installs
+verified under the RELEASE policy. pytest-gpu-proof is pinned at 0.5.0 (`install/requirements-dev.txt`, CI installs
 the same pin): the driver takes its BASE carry verdicts from the tool's `plan_carry` (ancestry, receipt and per-shard
 dirty flags, narrow fingerprint) and only demotes on top (oracle pin, recorded failures, wrapper fingerprint schema,
 cuda byte-neutrality); `gpu-proof merge --verify-inputs` authenticates every shard receipt; the merged receipt is

README.md

@@ -23,7 +23,7 @@ The full documentation is the website, <https://a2r-lab.org/GRiD/>: installation
 [How do I…?](https://a2r-lab.org/GRiD/docs/how_do_i.html) index, concepts, API reference, benchmarks and validation.
 This README points to it.
 
-Version 0.5.1 is on [PyPI](https://pypi.org/project/grid-rbd/); 0.5.0 was the first packaged release. GRiD is alpha
+Version 0.7.0 is on [PyPI](https://pypi.org/project/grid-rbd/); 0.5.0 was the first packaged release. GRiD is alpha
 software and APIs may change between minor versions (see the
 [changelog](https://github.com/A2R-Lab/GRiD/blob/main/CHANGELOG.md)). The GPU test receipt and the release timing ran on
 Linux x86-64 with CPython 3.12, CUDA toolkit 13.2 and one RTX 5090 (sm_120); CPython 3.10, 3.11 and 3.13 wheels are built and
@@ -45,7 +45,7 @@ pip install "grid-rbd[jax]"     # or "grid-rbd[torch]", "grid-rbd[all]"
 ```
 ```python
 import numpy as np, grid_rbd
-robot = grid_rbd.load_robot("grid_assets/robots/iiwa14.urdf",
+robot = grid_rbd.load_robot("robot.urdf",      # any URDF; samples: grid_assets/robots/ in the repository
                             algorithm_list=["forward_dynamics"], enable_mujoco_kernels=False)
 q = np.zeros((8, robot.nq), dtype=np.float32)
 qd, tau = (np.zeros((8, robot.nv), dtype=np.float32) for _ in range(2))
@@ -100,7 +100,7 @@ A Docker image with grid-rbd, `jax[cuda12]`, a cu128 torch wheel and the generat
 |-----------|------|
 | `grid_codegen/` | the code-generation engine: emits `grid.cuh` and the checked-in generated binding regions, driven by the `abi_specs.py` table |
 | `bindings/` | the `grid-rbd` Python package (NumPy/JAX/torch handles over a cached per-robot `.so`); see [`bindings/README.md`](https://github.com/A2R-Lab/GRiD/blob/main/bindings/README.md) |
-| `grid_assets/` | ten sample URDFs (`robots/`) + tuned per-GPU launch configs (`launch_configs/`) |
+| `grid_assets/` | ten sample robots and three test fixtures (`robots/`) + tuned per-GPU launch configs (`launch_configs/`) |
 | `test/` | pytest suites + the split-suite/receipt machinery |
 | `examples/` | `notebooks/` (Python tour), `codegen/`, `cuda/`; see [`examples/README.md`](https://github.com/A2R-Lab/GRiD/blob/main/examples/README.md) |
 | `docs/` | the Sphinx site (`source/`), the cover page (`landing/`), `agent_debugging_guide.md`, `design_history/` |

RELEASING.md

@@ -146,6 +146,22 @@ touches `gpu-proof.json`. Commit the receipt with its header-key ledger.
 A release does not wait for secondary receipts; they are documentation of the
 other architectures, recorded when those machines are available.
 
+Jetson resource budget for a secondary receipt (Orin, 64 GB, twelve cores). The
+10-24 attempt rebooted the box out of memory inside the compile pool (guide
+7.z63), so launch with the budget stated, not the defaults: `GRID_SPLIT_COMPILE_JOBS=2`
+(two full wrapper builds fit with room to spare; the default of five does not),
+`GRID_SPLIT_SHARD_JOBS=1` (one GPU shard at a time, the default), and
+`GRID_RBD_BUILD_JOBS=4` per wrapper build (the default is `min(8, cores,
+MemAvailable / 3 GB)`, which with two concurrent humanoid builds at 12 to 15 GB
+each exceeds the box). Disk preflight before launch: the pass writes wrapper
+objects to `~/.cache/grid-rbd` and runner executables to `.grid_build_cache/cuda`
+in the checkout (37 GB and 47 GB respectively on the 5090 box after a month of
+runs); check `df -h` on both volumes, clear both caches if the volume is under
+30 GB free, and do not start at the 6 GB free the 10-24 launch had. Set
+`GRID_SPLIT_STALL_SECS=7200` so a long humanoid compile is not mistaken for a
+hang, and `GRID_CUDA_ARCH=87` only if a test's architecture probe reports
+otherwise. Everything else follows the shell path above unchanged.
+
 Inspect final package provenance and verify the exact frozen artifacts before the
 TestPyPI rehearsal and the production upload. Package ownership, publisher setup,
 tagging, pushes and uploads need maintainer approval; the artifact workflow
@@ -219,7 +235,7 @@ pull access or GPU runtime correctness. Before announcing the container:
    visibility in the package settings. Do not work around failed anonymous access
    with a personal token and then call the public release verified.
 2. On an exclusively available GPU host with Docker and NVIDIA Container Toolkit,
-   run `sudo bash tools/check_container_image.sh 0.5.3` (substitute the released
+   run `sudo bash tools/check_container_image.sh 0.7.0` (substitute the released
    version). Omit sudo if Docker is already accessible. No host packages, drivers,
    group permissions or registry settings are changed by this checker.
    It uses an empty Docker CLI configuration for the anonymous pull, resolves

bindings/README.md

@@ -161,8 +161,8 @@ The full reference for the rest of the surface lives in the
 
 ## Install
 
-`grid_rbd` ships inside the `grid-rbd` distribution on PyPI (0.5.1: Linux
-x86-64 wheels and an sdist, CPython 3.10–3.13) together with the code
+`grid_rbd` ships inside the `grid-rbd` distribution on PyPI (Linux
+x86-64 wheels and an sdist, CPython 3.10 to 3.13) together with the code
 generator and the `grid-generate` / `grid-spherize` CLIs. Each GPU backend is
 an opt-in extra on top of the numpy base; pick the row for the wrapper surface
 you need:
@@ -254,6 +254,14 @@ the collision options (`collision`, `collision_res`, `collision_native`, `spheri
 GRiD never binds the consumer's symbols; load the artifact with `ctypes` or your own binding.
 See the agent integration guide for the full description.
 
+Consumer build lookups use `nvcc -MM` to rediscover and hash selected non-system
+headers, including transitive headers and newly shadowing include-path matches.
+`headers=[...]` adds explicit file inputs rather than replacing discovery.
+Unchanged build lookups and cached `plan_only` checks preprocess but do not
+compile. Prepared `load_artifact` remains compiler-free. System development
+headers omitted by `-MM` require an immutable build environment or explicit
+header declarations; compiler version alone is not a complete environment hash.
+
 Registration failures (a failed device allocation, a bad toolkit) raise a Python
 exception naming the failed operation; the generated initializers never
 `exit()` or reset the CUDA context inside the interpreter (they use the
@@ -264,7 +272,7 @@ nvcc/ptxas output can be inspected for warnings.
 A first use announces itself: a one-line `WARNING` on the `grid_rbd` logger
 (printed to stderr with no logging setup) says which robot is being compiled,
 how many units on how many cores, roughly how long (1–3 min for an arm or
-quadruped, ~10 min for a humanoid) and where it is cached; a second line reports
+quadruped, 6 to 10 min for a humanoid) and where it is cached; a second line reports
 the elapsed time. `GRID_RBD_QUIET=1` silences it. `get_robot(name, urdf_path=...)`
 compiles and registers on a *miss* (a hit ignores the URDF), so a script can be
 written as "get or build". `python -m grid_rbd.gc_cache` reports store entries