Slim rclcppyy 0.2.0 onto the cppyy_kit suite (deprecation shims) (M3)

rclcppyy becomes the drop-in rclpy accelerator product on top of the cppyy_kit
suite; the rclcpp core it carried was carved into rclcpp_kit (M1b) and the kits into
their own packages. Replace the moved internals with re-export shims:

- rclcppyy/bringup_rclcpp.py -> rclcpp_kit.bringup_rclcpp (silent: node.py/monkey.py
  use it internally). serialization / rosbag2_cpp / rosbag2_py_compat / tf -> the
  matching rclcpp_kit.* modules, each with a DeprecationWarning on import. All use
  importlib.import_module to fetch the real submodule (the package binds a
  bringup_rclcpp *function* over its submodule, so a plain import would shadow it).
- rclcppyy/kits/*.py -> deprecation shims re-exporting the standalone kit packages
  (bt/pcl/ompl/nav2/moveit/control/cv/dbow_kit, cppyy_kit, cppyy_kit.freeze); a
  missing kit package raises a clear install hint, not a bare ModuleNotFoundError.
- __init__.py: bringup stays eager; the moved submodules are exposed lazily via
  module __getattr__ so `import rclcppyy` doesn't fire the deprecation warnings for
  the product's own use, while `rclcppyy.tf` / `from rclcppyy import serialization`
  still resolve and warn.

Dev/test wiring (pre-release, suite unpublished): a PYTHONPATH bridge exposes
rclcpp_kit + cppyy_kit from a sibling cppyy_kit source checkout
(workspace_activation.sh, CPPYY_KIT_SRC; only those two packages, so domain-kit
shims still fail-with-hint). No file:// channel in pixi.lock (would not resolve on
CI). ci.yml checks out awesomebytes/cppyy_kit for the bridge. The local recipe
channel (pkg-build) stays for local recipe validation. Chosen over the local-conda
channel because a committed file:// lock breaks CI/other machines; documented.

Tests: the duplicated kit suites (they now live in the cppyy_kit repo) are removed
and replaced by test/test_kit_shims.py (shim re-exports + warns / clear hint). The
core suite is unchanged and passes against the shims.

Release prep: version 0.2.0 (package.xml, pixi.toml); recipe run-deps gain
ros-jazzy-rclcpp-kit + cppyy-kit; recipe/pkg-build/release.yml resolve them from the
suite channel (local now -> awesomebytes post-publish). RELEASING.md documents the
suite-first publish choreography. README reflects the new architecture + links the
suite repo.

Gates (local, ROS_DOMAIN_ID=57): build 0; lint 0; test 26 passed (core 16 + 10 kit-
shim smokes); bench 3000 msgs, 0 dropped (parity with 0.1.0).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: awesomebytes

.github/workflows/ci.yml

@@ -17,10 +17,24 @@ jobs:
   build-test:
     name: build + test + bench smoke
     runs-on: ubuntu-latest
+    env:
+      # M3 pre-release bridge: rclcppyy 0.2.0 imports rclcpp_kit / cppyy_kit (the
+      # carved-out suite), which is not published to prefix.dev yet. Provide them
+      # from a source checkout of the cppyy_kit repo; workspace_activation.sh puts
+      # exactly those two packages on PYTHONPATH via CPPYY_KIT_SRC. Remove this
+      # (and the checkout step) once rclcppyy depends on the published conda
+      # packages (channel swap local/awesomebytes; see RELEASING.md).
+      CPPYY_KIT_SRC: ${{ github.workspace }}/_cppyy_kit
     steps:
       - name: Checkout
         uses: actions/checkout@v5
 
+      - name: Checkout cppyy_kit (suite source for the pre-release bridge)
+        uses: actions/checkout@v5
+        with:
+          repository: awesomebytes/cppyy_kit
+          path: _cppyy_kit
+
       - name: Set up pixi
         uses: prefix-dev/setup-pixi@v0.10.0
         with:

.github/workflows/release.yml

@@ -38,9 +38,17 @@ jobs:
           # Only the packaging env; it doesn't pull the ROS/cppyy stack.
           environments: pkg
 
-      # rattler-build also runs the recipe's import smoke test in a fresh env.
+      # rattler-build also runs the recipe's import smoke test in a fresh env, which
+      # now resolves the 0.2.0 suite run-deps (ros-jazzy-rclcpp-kit, cppyy-kit) — so
+      # the build must see the awesomebytes channel. RELEASE CHOREOGRAPHY: the suite
+      # is published to awesomebytes BEFORE this rclcppyy release runs (RELEASING.md).
+      # (Local dev uses `pixi run -e pkg pkg-build`, which points at the local
+      # rattler-build channel instead of awesomebytes.)
       - name: Build conda package
-        run: pixi run -e pkg pkg-build
+        run: |
+          pixi run -e pkg rattler-build build --recipe recipe/recipe.yaml \
+            -c https://repo.prefix.dev/awesomebytes -c robostack-jazzy -c conda-forge \
+            --output-dir output
 
       # The point of releasing: a user with no clone gets a working install from
       # the channel alone. Reproduce that in a throwaway pixi workspace whose
@@ -53,7 +61,10 @@ jobs:
           cat > "$workdir/pixi.toml" <<EOF
           [workspace]
           name = "rclcppyy-artifact-test"
-          channels = ["file://$GITHUB_WORKSPACE/output", "robostack-jazzy", "conda-forge"]
+          # The freshly built rclcppyy is in output/; its 0.2.0 run-deps
+          # (ros-jazzy-rclcpp-kit, cppyy-kit) come from awesomebytes (published
+          # first, per RELEASING.md).
+          channels = ["file://$GITHUB_WORKSPACE/output", "https://repo.prefix.dev/awesomebytes", "robostack-jazzy", "conda-forge"]
           platforms = ["linux-64"]
           version = "0.0.0"
 

.gitignore

@@ -18,3 +18,9 @@ output/
 # build/ is already ignored above (DBoW2 lands in build/vendor/); data/ holds the
 # downloaded TUM RGB-D sequence and the ORBvoc vocabulary.
 data/
+
+# M3 pre-release PYTHONPATH bridge (generated symlinks to the sibling cppyy_kit checkout)
+.suite_bridge/
+
+# Local Claude agent state / worktrees
+.claude/

README.md

@@ -100,20 +100,38 @@ no `LD_LIBRARY_PATH` or activation setup required. Message packages you publish
 or subscribe (e.g. `ros-jazzy-std-msgs`) are separate dependencies, as in any
 ROS 2 project.
 
+## Architecture (0.2.0): rclcppyy on top of the cppyy_kit suite
+
+As of **0.2.0**, rclcppyy is the **drop-in rclpy accelerator product** in a larger
+family. The reusable machinery it pioneered was extracted into the
+**[cppyy_kit suite](https://github.com/awesomebytes/cppyy_kit)**:
+
+- **`cppyy_kit`** — the ROS-free base (load/keep-alive/callback/teardown friction
+  primitives, the `freeze` PCH tooling).
+- **`rclcpp_kit`** — the ROS 2 core capability layer (rclcpp bringup, C++ message
+  resolution/conversion, serialization, rosbag2, **tf**).
+- the domain **kits** (`bt_kit`, `pcl_kit`, `ompl_kit`, `nav2_kit`, `moveit_kit`,
+  `control_kit`, `cv_kit`, `dbow_kit`).
+
+rclcppyy keeps the brand and the one-line monkeypatch (`enable_cpp_acceleration`)
+and re-exports the moved pieces through **deprecation shims** — existing
+`from rclcppyy.bringup_rclcpp import ...`, `rclcppyy.tf`, `from rclcppyy.kits import
+bt_kit`, etc. keep working (with a `DeprecationWarning` pointing at the new home).
+New code should import `rclcpp_kit.*` and the standalone kit packages directly. See
+[`RELEASING.md`](RELEASING.md) for the suite/product publish order.
+
 ## Kits
 
-Beyond `rclcpp` itself, this repo uses the same `cppyy` approach to drive other
-C++ robotics libraries from Python: a "kit" is a thin layer that mirrors the
-library's own API and hides only the `cppyy` friction (bringup, lifetime,
-crossing callbacks, teardown), rather than inventing a new one. Six kits exist
-today — [BehaviorTree.CPP](https://www.behaviortree.dev/) (no other Python binding
-of it exists), [PCL](https://pointclouds.org/), [OMPL](https://ompl.kavrakilab.org/),
-[Nav2](https://docs.nav2.org/), [MoveIt 2](https://moveit.ai/), and
-[ros2_control](https://control.ros.org/) — plus a vision loop-closure **tutorial**
-composing OpenCV + DBoW2 + GTSAM. The patterns common to all live in
-[`rclcppyy/kits/cppyy_kit.py`](rclcppyy/kits/cppyy_kit.py).
+The cppyy "kits" — a "kit" is a thin layer that mirrors a C++ library's own API and
+hides only the `cppyy` friction (bringup, lifetime, crossing callbacks, teardown) —
+now live in the **[cppyy_kit repo](https://github.com/awesomebytes/cppyy_kit)**:
+[BehaviorTree.CPP](https://www.behaviortree.dev/) (no other Python binding of it
+exists), [PCL](https://pointclouds.org/), [OMPL](https://ompl.kavrakilab.org/),
+[Nav2](https://docs.nav2.org/), [MoveIt 2](https://moveit.ai/),
+[ros2_control](https://control.ros.org/), plus a vision loop-closure tutorial
+composing OpenCV + DBoW2 + GTSAM. `rclcppyy.kits.*` remains as compatibility shims.
 
-Measured results:
+Measured results (from the suite):
 
 | Kit | What it shows | Number |
 |---|---|---|
@@ -127,24 +145,12 @@ Measured results:
 | L1 "freeze" (Cling PCH) | header parse eliminated | 890 ms → 6 ms (~140×); rclcpp 1.71 s → 6 ms |
 | L2 lowering | Python leaf → native `.so` | ~2.8× tick rate, identical output |
 
-Quick run (each kit has its own opt-in pixi env):
-
-```bash
-pixi run -e bt demo-bt-t01           # + demo-bt-t03 (mixed Python/C++/ROS tree)
-pixi run -e pcl bench-pcl
-pixi run -e ompl demo-ompl-plan
-pixi run -e nav2 demo-nav2-stack
-pixi run -e moveit demo-moveit-plan
-pixi run -e control demo-control-python
-pixi run -e vision demo-vision-loop
-```
-
-More detail: [docs/kits/COMMON_PATTERNS.md](docs/kits/COMMON_PATTERNS.md) and
-[docs/kits/FREEZE.md](docs/kits/FREEZE.md); the vision walkthrough in
-[docs/tutorials/vision_loop_closure.md](docs/tutorials/vision_loop_closure.md);
-per-kit "why" docs [bt](docs/bt_kit/WHY.md), [pcl](docs/pcl_kit/WHY.md),
-[ompl](docs/ompl_kit/WHY.md), [nav2](docs/nav2_kit/WHY.md),
-[moveit](docs/moveit_kit/WHY.md), [control](docs/control_kit/WHY.md).
+Run the kit demos/benchmarks and read the per-kit `SKILL.md` / `WHY.md` / `REPORT.md`
+in the **[cppyy_kit repo](https://github.com/awesomebytes/cppyy_kit)** (each kit has
+its own opt-in pixi env there, e.g. `pixi run -e bt demo-bt-t01`,
+`pixi run -e pcl bench-pcl`, `pixi run -e vision demo-vision-loop`). The common-pattern
+playbook, the L0→L1→L2 freeze ladder, and the vision loop-closure walkthrough live
+there too.
 
 ## Setup
 

RELEASING.md

@@ -0,0 +1,69 @@
+# Releasing rclcppyy (0.2.0+)
+
+As of 0.2.0, rclcppyy is the **drop-in rclpy accelerator product built on top of the
+cppyy_kit suite**. Its rclcpp core was carved into the standalone `rclcpp_kit`
+package, and the cppyy kits into their own packages (the
+[cppyy_kit](https://github.com/awesomebytes/cppyy_kit) repo). rclcppyy re-exports the
+moved pieces through deprecation shims, so it now **depends on the suite at runtime**:
+
+- `rclcppyy.bringup_rclcpp` / `serialization` / `rosbag2_cpp` / `rosbag2_py_compat` /
+  `tf` → re-export `rclcpp_kit.*` (conda: `ros-jazzy-rclcpp-kit`).
+- `rclcppyy.kits.cppyy_kit` / `.freeze` → re-export `cppyy_kit` (conda: `cppyy-kit`).
+- `rclcppyy.kits.{bt,pcl,ompl,nav2,moveit,control,cv,dbow}_kit` → re-export the
+  standalone kit packages, which the user installs separately if wanted.
+
+This creates a **publish order**: the suite must be on the prefix.dev `awesomebytes`
+channel before an rclcppyy release can build, prove, and upload.
+
+## Pre-release dev/test wiring (current state, suite unpublished)
+
+The suite is not on `awesomebytes` yet (that needs Sam's prefix.dev authorization).
+Until then:
+
+- **Dev + CI import** rclcpp_kit / cppyy_kit from a **sibling `cppyy_kit` source
+  checkout** via a PYTHONPATH bridge — `workspace_activation.sh` puts exactly those
+  two packages on `PYTHONPATH` (default `../cppyy_kit`; override with `CPPYY_KIT_SRC`).
+  CI (`.github/workflows/ci.yml`) checks out `awesomebytes/cppyy_kit` and sets
+  `CPPYY_KIT_SRC`. No file:// channel is committed to `pixi.lock` (it would not
+  resolve on other machines / CI).
+- **Local recipe validation** uses a **local rattler-build channel**: `pixi run -e
+  pkg pkg-build` passes `-c file://.../cppyy_kit/output` so the recipe's import-smoke
+  test env can resolve the suite run-deps. (Build the suite's local channel first in
+  the cppyy_kit repo: `pixi run -e pkg <suite pkg-build>`.)
+
+## Release choreography (do these in order)
+
+**Do not tag rclcppyy until step 1 is done.**
+
+1. **Publish the suite** from the cppyy_kit repo to `awesomebytes` (needs Sam's
+   prefix.dev auth): `cppyy-kit`, `ros-jazzy-rclcpp-kit`, and the domain kits, all
+   artifact-proven from a fresh env first (the suite's own release discipline).
+
+2. **Swap rclcppyy from the pre-release bridge to the published channel:**
+   - `pixi.toml`: add channel `https://repo.prefix.dev/awesomebytes`; add deps
+     `ros-jazzy-rclcpp-kit` and `cppyy-kit` (pin to the published version); re-lock
+     (`pixi lock`).
+   - Remove the pre-release bridge: the `# M3 PYTHONPATH bridge` block in
+     `workspace_activation.sh`, and the `_cppyy_kit` checkout + `CPPYY_KIT_SRC` env in
+     `.github/workflows/ci.yml`. (Real conda deps replace them.)
+   - Optional: point the `pkg-build` task's `-c` at `awesomebytes` instead of the
+     local path (or leave it for local dev; the release workflow already uses
+     `awesomebytes` directly).
+
+3. **Verify** on a clean checkout: `pixi run build`, `pixi run lint`, `pixi run test`
+   (core suite + kit-shim smokes), `pixi run bench --variants rclcppyy --rate 1000
+   --duration 3 --json` (≈3000 msgs, 0 dropped). Push; CI must be green.
+
+4. **Tag `v0.2.0`.** `.github/workflows/release.yml` then: builds the
+   `ros-jazzy-rclcppyy` conda package (recipe run-deps resolve from `awesomebytes`),
+   proves it installs + runs a pub/sub roundtrip in a throwaway workspace whose
+   channels include `awesomebytes`, and uploads via OIDC. `recipe/recipe.yaml` and
+   `release.yml` are already prepared for this (they reference `awesomebytes`); step 2
+   only touches the dev/CI wiring.
+
+## Deprecation timeline
+
+The `rclcppyy.*` re-export shims and `rclcppyy.kits.*` shims emit `DeprecationWarning`
+(except `rclcppyy.bringup_rclcpp`, which the product itself uses internally). They
+keep existing imports working across 0.2.x; plan removal for a later major bump once
+downstreams have moved to `rclcpp_kit.*` / the standalone kit packages.

package.xml

@@ -2,7 +2,7 @@
 <?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
 <package format="3">
   <name>rclcppyy</name>
-  <version>0.1.0</version>
+  <version>0.2.0</version>
   <description>rclcpp bindings via cppyy and examples on how to use cppyy in ROS2</description>
   <maintainer email="sammypfeiffer@gmail.com">Sam Pfeiffer</maintainer>
   <license>BSD</license>
@@ -13,8 +13,11 @@
   <depend>rclpy</depend>
   <depend>rclcpp</depend>
 
-  <!-- cppyy is required (rclcppyy/bringup_rclcpp.py, node.py, serialization.py, etc.)
-       but has no rosdep key; it is installed via conda-forge/pip. -->
+  <!-- cppyy is required (node.py, monkeypatch, and transitively via rclcpp_kit) but
+       has no rosdep key; it is installed via conda-forge/pip. Likewise the carved
+       core now lives in rclcpp_kit (conda: ros-jazzy-rclcpp-kit) and the cppyy kit
+       shims re-export cppyy_kit (conda: cppyy-kit); these have no rosdep keys and are
+       declared as conda run-deps in recipe/recipe.yaml (0.2.0). -->
   <exec_depend>ament_index_python</exec_depend>
   <exec_depend>rosidl_runtime_py</exec_depend>
   <exec_depend>rosbag2_py</exec_depend>