Request for Comments: Modular AirStack — module repos, slot contracts, marketplace, and distributed CI/docs

[andrewjong]

RFC: Modular AirStack — module repos, slot contracts, a module marketplace, and distributed CI/docs

Output of a design session on making AirStack modular rather than monolithic. Written to be self-contained: a reader (human or AI agent) should be able to implement from this document alone. Repo facts current as of develop @ 55d9b887 (VERSION 0.19.0-alpha.9).

Scope: this RFC covers how modules are packaged, integrated, tested, distributed, and documented. Its companion, RFC #380: Heterogeneous AirStack, builds on this machinery to configure heterogeneous deployments — vehicle variants, mixed multi-robot fleets, top-level configuration, and (future) cross-embodiment platforms.

1. Problem statement

Projects branched from AirStack build features we want as optional trunk capabilities, but today the only paths are merging into the monolith or living in a fork. Motivating cases: DFM2's Isaac Sim disturbance library (buried in a whole-repo fork), an OptiTrack motion-capture state-estimation integration with its own tests, and a custom global planner.

Pain points to solve:

1. Distribution — modules in their own repos, pulled on demand, running their own CI without bogging down trunk's suite.
2. Version compatibility — modules report (and ideally CI-verify) which AirStack versions they support.
3. Launch integration — enabling a module today means hand-editing bringup XML and rewiring topics; the result is variant explosion (local.launch.xml, local_droan_cpu.launch.xml, local_macvo_obstacle_avoidance.launch.xml are near-copies with alternate wirings commented out).
4. Cross-module compatibility — modules expect certain inputs/topics or depend on each other.
5. Discoverability — a "marketplace" of compatible modules.
6. Docker — all deps for all modules merged into one Dockerfile per host type; breaks when deps are cross-repo, and module permutations are too many to prebuild.
7. Tests — a repo containing only a module must be able to run trunk's full system tests (image builds, liveliness, takeoff/hover/land, trajectory following, waypoint navigation).
8. Docs — module docs distributed across repos, still served coherently on the versioned public site.

Design principles (decided)

• Steal the rosdistro model — index repo + version-pinned manifests + CI-verified compatibility is proven (rosdistro, vcstool, ROS buildfarm). Don't invent.
• Modules are thin repos, never forks.
• Standardize the waists, not the topology. Contracts live at a few interchange points ("rungs"), so the architecture absorbs module shapes we haven't imagined (§4).
• Containers stay machines — one per robot + GCS + sim models real deployments (DDS isolation, replicas, onboard/offboard split). Dependencies are solved at image composition (§6), never per-module containers.
• Compatibility claims must be CI-verified or they rot. The CI loop (§5) is the foundation everything else depends on.

2. Module anatomy: a thin repo with a manifest

A module repo contains only its packages plus module.yaml:

name: dfm2_disturbances
description: Isaac Sim disturbance library (lens flare, strobes, ice planes)
maintainer: someone@andrew.cmu.edu        # required; see §8
license: BSD-3-Clause                      # checked at registration
type: isaac_extension                      # isaac_extension | ros_package | stack_module (+ data-only types, e.g. vehicle — see #380)
airstack_compat: ">=0.19.0 <0.21.0"        # semver range vs trunk .env VERSION
targets: [isaac-sim]                       # host containers touched: robot | gcs | isaac-sim

slot: null                                 # e.g. "global_planner" if it fills a standard slot
provides: [disturbance_injection]          # capability names
requires: []                               # capabilities it needs
replaces: []                               # slots it vacates (stack_module, §4)

launch: launch/dfm2.launch.xml             # entry point honoring contract args
interface:                                 # the module's overridable surface (resolution: §3)
  launch_args: {}                          # keys mirror the launch file's args 1:1 (doctor diffs vs
                                           #   `ros2 launch --show-args`); topic-endpoint args carry
                                           #   {role: input|output, type, rung} for the resolver;
                                           #   e.g. disparity_in: {role: input, type: stereo_msgs/DisparityImage}
  params: config/dfm2.yaml                 # ROS params = separate mechanism; this file is their source of truth
compose: docker-compose.module.yaml        # optional compose fragment (mounts, env)

deps: {apt: [], pip: []}                   # dep tier 1 (§6)
dockerfile: null                           # tier 2: Dockerfile.module using ARG BASE_IMAGE
overlay_image: null                        # tier 3: prebuilt overlay image ref

assets: []                                 # [{url, sha256, dest}] fetched to cache — no Git LFS
docs: {readme: README.md}                  # or {dir: docs/, nav: nav.yml}
foxglove: null                             # optional layout/panel fragment

tests:
  packages: [dfm2_disturbances]            # colcon unit-test packages (co-located test/)
  conformance_marks: []                    # system-test marks required (per-slot defaults, §5)

Mapping the motivating cases: OptiTrack → ros_package, slot: state_estimator, provides: [odometry]; custom planner → slot: global_planner; DFM2 → isaac_extension (Isaac supports extension search paths — lowest-coupling pilot).

3. Sync and launch integration

Sync: modules.repos (vcstool format — not submodules). airstack module add <name|url> clones into a gitignored modules/ dir; overlay plumbing places each module by type/targets: ROS packages symlinked into robot/ros_ws/src/modules/ (colcon picks them up), Isaac extensions onto the extension path, compose fragments merged via COMPOSE_FILE. Trunk never carries module code. CLI surface: airstack module add|remove|list|sync|doctor|create|search|extract, airstack init --release <X>, module create --in-tree / doctor --drift (§11).

Slots: the layers' implicit roles become named slots (state_estimator, local_planner, local_world_model, global_planner, global_world_model, controller, behavior). Each slot's contract = the standard topics (already in docs/robot/autonomy/integration_checklist.md) as required launch args, plus QoS profiles and TF frame/units conventions — both are classic silent failures (best-effort-vs-reliable mismatch receives nothing; ENU vs NED) that doctor must check. Every module — trunk's included — ships a launch file honoring its slot's arg interface.

stack.yaml replaces hand-edited bringup XML. Trunk's default stack, expressed as data (module names per the reference implementations):

# stacks/full_default.yaml — trunk's current full-autonomy stack
slots:
  state_estimator:    odometry_conversion   # swap in a module (e.g. optitrack) = edit this line
  local_world_model:  disparity_expansion
  local_planner:      droan                 # or droan_cpu / macvo_avoidance — the launch-file variants, as presets
  controller:         trajectory_controller
  global_world_model: vdb_mapping
  global_planner:     random_walk
  behavior:           behavior_tree

extras: [stereo_image_proc, takeoff_landing_planner]   # slotless: perception preprocessing, task servers

overrides:                                  # leaf params / contract-arg rewires only
  droan.disparity_in: /$ROBOT_NAME/perception/stereo_image_proc/disparity
  behavior_tree.tree: trees/exploration.xml

Stacks compose by inheritance, so experiments are diffs, not copies — here the VLA stack from #380's fleet example, exercising §4's replaces semantics:

# stacks/vla_experimental.yaml — end-to-end VLA swallows the planning pipeline
base: stacks/full_default.yaml       # inherit everything, then modify

extras: [vla_pilot]                  # stack_module (§4): consumes front_stereo + odometry +
                                     # tasks/navigate, produces trajectory_override
slots:
  global_planner:    none            # vacated explicitly — doctor enforces these match
  local_planner:     none            #   vla_pilot's `replaces:` list
  local_world_model: none
  # controller, behavior, global_world_model, state_estimator inherited from base

overrides:
  vla_pilot.model_checkpoint: assets/vla_v3.pt

A generic Python bringup reads the resolved stack, includes each module's launch file, passes contract topics. The three local_*.launch.xml variants collapse into preset stacks like these. (Trunk precedent for YAML-driven collection: tests/colcon_unit_test_packages.yaml.)

Where overrides land: each <module>.<key> resolves against the module's declared interface: (§2). A key matching a launch arg is passed straight through to the module's launch file; if the arg is annotated role: input|output it's a topic endpoint — the resolver auto-wires unset ones by finding a provider, and an explicit override pins the choice (droan.disparity_in exists because two disparity sources are available). The role/rung annotations are also what conflict detection and #380's split-placement checks operate on — a split may only cut topic-endpoint args. Any other key must exist in the module's params file and becomes a ROS 2 parameter override layered onto its defaults (bringup emits a merged per-robot param file, extending the config precedence chain into params). A key matching neither is a doctor error: overrides are typo-checked against the manifest, never silently ignored. How stacks are assigned per robot in a multi-robot deployment — and the top-level config that selects them — is #380's territory; a stack.yaml itself stays a single-robot artifact.

Wiring resolution — modules agree with rungs, never with each other. Pairwise agreement (MACVO must know DROAN's topic names) is O(N²) and is what today's hand-maintained remap blocks encode. Instead, in priority order:

1. Rung-annotated args wire to canonical topics. MACVO declares odometry_out: {role: output, rung: odometry}, DROAN declares odometry_in: {role: input, rung: odometry}; bringup remaps both to /{robot}/odometry. Neither learns the other's names — swap MACVO for OptiTrack and nothing downstream changes.
2. Non-rung connections auto-wire only when unambiguous (match unfilled input to provider by capability/type). Zero or 2+ providers → doctor error demanding an explicit override — the resolver never guesses. (droan.disparity_in in full_default.yaml exists because two disparity sources are available.)
3. Explicit overrides win, typo-checked as above.

Legibility: the resolved wiring is a first-class artifact. airstack wiring (+ a per-run dump beside effective_config.yaml) renders the dataflow graph — every connection with topic, type, QoS, and provenance (rung / auto-wired unique provider / override at stack.yaml:line), as terminal table + mermaid. Generated by the same resolver that builds the launch, so it cannot lie or rot. "What feeds DROAN?" = read stack.yaml + rung table + wiring report, not 80 lines of remap XML. doctor --live diffs the running graph against the resolved one (ros2 topic info per connection: both endpoints present, QoS compatible) — catching the wired-but-silent class static checks miss.

Cross-module checks: provides/requires names + slot uniqueness gets ~90% of the value cheaply. doctor reports: two modules claiming one slot, unsatisfied requires, message-type mismatches vs airstack_msgs. No full ontology — names + types, checked at sync time.

4. Modules that don't fit a slot (e.g., an end-to-end VLA planner)

A rigid slot taxonomy breaks on modules that swallow several slots — e.g., an end-to-end vision-language-action planner spanning perception → planning. Three refinements:

(a) Slots are contracts at narrow waists — rungs on a ladder. A conventional module taps in at one rung and out at the next; an end-to-end module taps in high and out low. Admission test: a rung exists only if modules on both sides plausibly vary independently — otherwise it's private wiring (§3 rule 2), deliberately not public API. The proposed set, derived from today's standard topics:

Rung	Flow	Contract	Today
sensors/*	vehicle drivers → perception, planners, loggers	naming convention generated from the vehicle's sensor manifest (#380 §1); Image/CameraInfo/PointCloud2/Imu; sensor-data QoS	/{r}/sensors/front_stereo/…
odometry	state_estimator → nearly everything	nav_msgs/Odometry, map frame, min-rate class, reliable	/{r}/odometry
global_map	global_world_model → global planner, GCS viz	one blessed representation + query interface (see note)	vdb_mapping topics
global_plan	global_planner → local_planner	nav_msgs/Path, map frame	/{r}/global_plan
trajectory (group)	local_planner ↔ controller	down: trajectory_segment_to_add, trajectory_override, set_trajectory_mode; up: tracking_point, look_ahead, completion %	/{r}/trajectory_controller/*
control_setpoint	controller → interface	attitude/rate setpoints — the safety-flagged bypass rung (below)	MAVROS setpoints
interface_status (group)	interface → tasks, safety, GCS	is_armed, has_control, extended_state; robot_command inbound	/{r}/interface/*
tasks/*	behavior → task executors	ROS 2 actions; set is platform-declared (provides_tasks, #380)	/{r}/tasks/{navigate,takeoff,land,fixed_trajectory}
safety	safety executive ↔ all command authority	abstract states (SAFE_STOP/RTB/KILL, #380) + timeout signals	drone_safety_monitor topics
gossip	robot ↔ robot	PeerProfile + attached payloads	gossip domain 99

Notes: rungs are topic groups with one contract (types + QoS + frames + rate class) — the trajectory rung is bidirectional, and per-topic rungs would recreate remap sprawl. sensors/* is a convention, not a fixed list. Deliberate non-rungs: disparity/depth preprocessing stays private wiring (one consumer class; rung-ifying freezes an internal detail into public API); actuator commands below the interface are never a rung (safety floor). The list grows only via the §8 RFC process, with §11 drift reports as the discovery mechanism (three forks patching the same tap point = a missing rung). global_map is the hardest: representations genuinely vary (voxel/ESDF/mesh), so it needs either one blessed representation + adapters or a narrower query interface — flagged, not hand-waved.

(b) A module declares what it replaces:

name: vla_pilot
type: stack_module
consumes: [front_stereo, odometry, tasks/navigate]
produces: [trajectory_override]
replaces: [global_planner, local_planner, local_world_model]

The resolver vacates replaced slots (no double-publishing), verifies everything consumed is still provided, and warns about orphaned downstream consumers.

(c) Three tiers of decreasing verifiability, all first-class: slot filler (doctor verifies everything) → ladder-spanning stack_module (doctor verifies wiring, not internals) → freeform (namespace + sensor bus; doctor checks collisions only).

Non-negotiable safety floor across all tiers: command authority flows through the trajectory controller / interface layer, where arming, safety monitoring, and takeover live. A module emitting trajectory_override inherits the whole safety apparatus free — a selling point, not a constraint. A module that must bypass it declares produces: [attitude_setpoint] and doctor flags it loudly as safety-critical.

5. Version compatibility and test separation

Trunk's docker-build.yml already pushes cosign-signed images tagged by VERSION — published images are the compatibility contract.

Reusable workflow trunk owns (.github/workflows/module-system-tests.yml). A module repo's entire CI:

jobs:
  system-tests:
    uses: castacks/AirStack/.github/workflows/module-system-tests.yml@v0.19.0
    with:
      airstack_ref: v0.19.0    # pin and checkout ref move together
      marks: "build_packages or liveliness or takeoff_hover_land or autonomy or waypoint_flight"
      sim: isaacsim

It: (1) checks out trunk at airstack_ref; (2) checks out the module and runs airstack module add ./ — the same overlay path a developer uses, so the module's slot: wires it into the test bring-up's stack.yaml; (3) runs the existing suite unchanged via airstack test -m "<marks>". The module repo never copies a test.

System tests double as slot conformance tests. tests/waypoint_checker.py judges the odometry track regardless of which planner produced it — passing it is the behavioral definition of a working global planner. Each slot contract names required marks (global_planner → waypoint_flight, autonomy; state_estimator → liveliness, sensors, takeoff_hover_land). The registry compat badge for (module version × AirStack version) is granted only when that set passes.

GPU runners (system tests need GPU + sim license; trunk uses OpenStack ephemeral runners via .github/orchestrator/):

• First-party (org) modules: org-level runner group; orchestrator polls across registered repos. Admission = registry listing (mirrors the existing fork-PR block).
• External modules: never get org GPUs directly. Trunk hosts a dispatch-triggered test bench — repository_dispatch {module_repo, module_ref, airstack_ref}; trunk runs on its own runners, posts a check-run back via a GitHub App. Secrets and licenses never leave trunk; bench time is gated/rate-limited.

Cost ladder: every push → unit + build_packages in the published image (minutes, no GPU); PR/nightly → liveliness (+sensors where relevant), msairsim is the cheap bring-up; release/compat claim → full conformance set on GPU (stamps the badge); trunk-side nightly canary runs registered modules against develop so breakage surfaces the day it lands.

Metrics: module runs' metrics.json diff against trunk's baseline via existing tests/parse_metrics.py — badges can carry e.g. "cross-track RMSE vs. default planner."

6. Docker images: base + composed module layers

Never publish permutations. Trunk publishes one signed base per host type per version; composed images are built where used, from cached layers.

Three dependency tiers (declared in module.yaml):

1. rosdep/apt/pip lists (default) — deps in package.xml + deps:; no Dockerfile in the module repo.
2. Dockerfile fragment — Dockerfile.module written against ARG BASE_IMAGE, never a fixed base.
3. Prebuilt overlay image — for monster deps (20 GB CUDA/PyTorch): module CI publishes ghcr.io/…/<module>-overlay:<airstack_version> built FROM ${BASE_IMAGE}; developers pull instead of build.

Composition chain (airstack module sync, deterministic order, grouped by target host):

ghcr.io/castacks/airstack-robot:0.19.0        ← pulled, never rebuilt
  → +layer: tier-1 rosdep/apt/pip (one RUN per module → per-module cache)
  → +layer: optitrack Dockerfile.module        (BASE_IMAGE = previous)
  → +layer: vla overlay                        (pulled if published for 0.19, else built)
  = airstack-robot:0.19.0-local

Module code changes rebuild nothing (source stays volume-mounted; dev loop = bws in the container, unchanged). A module's dep change rebuilds only its layer and above. modules.lock hashes dep declarations + records image digests → airstack up knows exactly when a rebuild is needed ("optitrack deps changed, rebuilding 2/4 layers") and compat badges record the digest chain they were earned with. CI uses the identical path with a registry-backed buildx cache (runners are ephemeral).

Failure modes: (1) dep conflicts between modules → doctor runs pip check/apt dry-run at compose time and names the fighting modules; (2) prebuilt overlays don't merge → a published overlay is used as-is only when it's the sole tier-3 module; otherwise build each from its fragment in chain order (overlay = cache, fragment = source of truth).

Side effect: trunk Dockerfiles thin out as deps migrate into the modules that own them (MACVO networks, mocap SDKs).

7. Marketplace / registry

An airstack-modules-index repo (rosdistro's distribution.yaml pattern): one YAML per module — name, repo URL, description, maintainer, CI-generated compat matrix. airstack module search|list|add reads it; MkDocs renders a catalog with badges. Getting listed = PR to the index = the quality gate (manifest valid, CI green, README template, license check).

Release sets solve N×N module compatibility: periodically publish "AirStack 0.20 + these module versions, tested together" — one lockfile, blessed by a single CI run with all enabled. Individual badges mean "works with trunk"; release sets mean "works together." Most users pull a release set; à-la-carte is for developers. Release sets also drive versioned docs (§9).

8. Governance (most likely to decide success)

• Maintainer lifecycle. Module authors are grad students; grad students graduate. Every entry has a named maintainer; nightly canary failing N weeks unanswered auto-moves the module to an "unmaintained" shelf (listed, labeled) instead of staying green-badged.
• License checks at registration — a GPL module in the overlay chain must be surfaced, not buried.
• Contract deprecation policy. The rungs are public API. A rung change requires: semver-major on the contract, a coexistence window, and a short RFC in the registry repo. Without this, the first breaking change teaches everyone the badges are meaningless.
• Semver airstack_msgs ruthlessly, as its own package. ROS 2 type hashes make msg mismatches fail silently (no connection), not gracefully. doctor compares msg versions across the composed workspace.

9. Docs

Hybrid, embedding automated. Pure link-outs to repo READMEs lose search, theming, and versioning (a GitHub README shows main — wrong for a user on 0.19). Module docs ride the existing mike machinery:

• Main site owns: the auto-generated marketplace catalog (per-module page: description, maintainer, compat matrix, install snippet, source link); contract/rung specs, QoS + frame conventions, authoring guide, deprecation RFCs.
• Module repos own deep docs (README minimum, optional docs/), declared via docs: and validated against the README template at registration. The docs deploy workflow shallow-clones each registered module at a pinned ref into modules/<name>/ and splices nav (a fetch loop driven by the registry index — simpler than mkdocs-multirepo-plugin; extends the existing same-dir pattern).
• Release sets drive doc versions: the site for version X embeds each module at X's release-set ref — docs and tested distribution stay in lockstep. develop embeds module default branches.
• Failure isolation: an unreachable module repo must not fail trunk's deploy — skip, stub page, warning.
• Freshness: rebuild on registry-index repository_dispatch + existing triggers + nightly. "Within a day, exact at releases."
• Unregistered modules: catalog links out, no embedding — embedding is a perk of registration.

10. Smaller items (all decided)

• Large assets: manifest assets: [{url, sha256, dest}], fetched to cache by module sync. No Git LFS in module repos.
• GCS/Foxglove fragments: a module is field-usable only if operators can see it — manifest may ship a Foxglove layout/panel fragment.
• Scaffolding + agent skills: airstack module create generates the template repo (manifest, CI stub, launch, README); update .agents/skills/ so AI-agent contributions build modules the new way instead of reintroducing the monolith.
• Dogfood the mechanism (use it ourselves as external authors would): migrate 1–2 trunk modules (e.g., MACVO with its heavy deps) early — maintainers hit the friction first, the machinery can't rot, base images shrink.
• DFM2 as test infrastructure: a disturbance-injection module is a test fixture — the harness can take an optional disturbance module to run robustness variants of existing flight marks.

11. The researcher workflow: research in a fork, graduate to a module

Principle: research happens in a fork; modularity is a graduation step, not an entry fee. Demand manifests and CI during exploration and researchers will ignore the process — the design's job is making the fork cheap to extract from, which is decided on day one.

• Stage 0 — pin a release set. airstack init --release 0.20 + module add what the experiments need. Stay pinned through the research.
• Stage 1 — research in-tree, inside a boundary. The expensive part of extraction is archaeology (edits sprinkled across trunk files, hardcoded topics, deps snuck into Dockerfile.robot), not moving files. One cheap discipline: airstack module create --in-tree my_planner scaffolds robot/ros_ws/src/modules/my_planner/ (normal colcon package, stub manifest, own launch) in the researcher's fork — zero CI/registry obligations, only the directory boundary from day one. airstack module doctor --drift diffs the fork against the pinned release and classifies changes: contained in the module dir (fine) vs. trunk edits (extraction debt, listed).
• The boundary is a default, not a cage. Some work is genuinely repo-wide; the drift report informs, never blocks — no gate anywhere. A trunk edit has three healthy destinies: upstream it (PR to trunk — it leaves the report); carry it as extraction debt (becomes an override/launch-arg/Dockerfile fragment at graduation); recognize it as a missing rung (feed the §8 RFC process — drift reports across forks are how contract gaps get discovered).
• Stage 2 — graduate. airstack module extract my_planner moves the directory into a fresh template repo (manifest, CI pinned to their release, README skeleton) and emits the drift report as the task list. Then: conformance marks against the pinned version (same code — should pass immediately), then against current trunk (the deferred compat work, done once), then register.
• Agent-assisted extraction. Extraction is an ideal coding-agent task because it has an objective success criterion: an .agents/skills/extract-module skill takes the manifest schema, contract specs, template, and drift report; the agent converts mechanically and verifies with doctor + the slot's conformance marks (it flies the drone until it passes). A second skill guides agents during Stage 1 to keep changes inside the module dir — cheap prevention that makes Stage 2 nearly free.
• Stage 3 — maintain or park. Canary + compat bumps while the author is around; unmaintained shelf after. A thesis fork becomes a registered module in an afternoon instead of dying with the fork.

12. Phased implementation plan

1. Phase 1 — CI loop + pilot (first; everything depends on it): module.yaml schema + JSON Schema validation; reusable module-system-tests.yml; extract DFM2 disturbances as pilot (sim-side, no slot, lowest coupling).
2. Phase 2 — overlay + CLI: modules/ overlay + modules.repos; module add|remove|sync|doctor; Docker composition chain + modules.lock; extract OptiTrack and the custom planner. Researcher tooling (§11): create --in-tree, doctor --drift, extract, extract-module skill.
3. Phase 3 — slot bringup: contract specs (topics + QoS + frames); stack.yaml-driven bringup; collapse local_*.launch.xml into presets. This phase is also where #380's vehicle/fleet/top-level configuration layer lands — its config surface consumes the slots defined here.
4. Phase 4 — ecosystem: registry repo; docs catalog + embedding; nightly canary; org runner group + dispatch test bench; release sets; governance policies.

Heterogeneous deployment configuration and cross-embodiment platforms are specified in RFC #380; its cross-embodiment part is sequenced after phases 1–4 are proven.

Ranked success factors: (1) the CI-against-published-images loop, (2) contract governance/deprecation policy, (3) maintainer lifecycle policy. Everything else is buildable later; these determine whether the ecosystem stays trustworthy.

Appendix: trunk facts an implementer needs

• .env VERSION="0.19.0-alpha.9" tags docker images; check-version-increment.yml gates PRs on semver bump.
• .github/workflows/docker-build.yml builds, pushes, cosign-signs all compose images on merge to main/develop when VERSION changes.
• System tests: tests/system/ (marks in tests/pytest.ini: unit, build_docker, build_packages, integration, liveliness, sensors, takeoff_hover_land, autonomy, waypoint_flight); harness in tests/harness/ + tests/conftest.py; unit-test packages listed in tests/colcon_unit_test_packages.yaml; metrics via tests/parse_metrics.py (diff-vs-baseline, exits 1 on regression); waypoint pass/fail via standalone tests/waypoint_checker.py.
• GPU CI: runs-on: [self-hosted, airstack-ephemeral] → OpenStack ephemeral VMs via .github/orchestrator/ (spawn loop, JIT tokens, cloud-init, reap loop). Fork PRs blocked from runners.
• Bringup: single entry robot/ros_ws/src/autonomy_bringup/launch/robot.launch.xml, role-dispatched by AUTONOMY_ROLE (full|onboard|offboard); per-layer bringups like robot/ros_ws/src/local/local_bringup/launch/ (the variant explosion).
• Multi-robot: compose deploy.replicas: ${NUM_ROBOTS}; ROBOT_NAME/ROS_DOMAIN_ID resolved at container start by robot/docker/.bashrc + robot/docker/robot_name_map/resolve_robot_name.py.
• Standard topics (the rungs today): /{robot}/odometry, /{robot}/global_plan, /{robot}/trajectory_controller/{trajectory_override,trajectory_segment_to_add,look_ahead,tracking_point,set_trajectory_mode}, /{robot}/tasks/{navigate,takeoff,land,fixed_trajectory}, /{robot}/interface/* — see docs/robot/autonomy/integration_checklist.md.
• Docs: MkDocs Material + mike versioning, same-dir plugin for out-of-tree READMEs, deploy workflows per branch.
• Candidate module sources: DFM2 fork (disturbances under its simulation/), OptiTrack integration (natnet_ros2 exists in trunk), custom global planner.

---

From a design brainstorm session (2026-08-04). Companion: RFC #380 — Heterogeneous AirStack. Comments and pushback welcome — especially from prospective module authors and registry maintainers.