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

[andrewjong]

RFC: Modular AirStack — module repos, stack folders, 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 @ 1c41f8c0 (VERSION 0.19.0-alpha.16).

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. A visual companion, #385: Directory Atlas, shows the resulting directory layouts for every repo shape both RFCs define.

The design in one paragraph: a module is a thin repo — code, a small manifest for deps and identity, no wiring metadata. A stack is a self-contained folder that composes modules into a running system: a pinned list of module repos to pull, plain ROS 2 launch files defining the node topology, and a compose file assembling the Docker images. Wiring legibility comes from authoring conventions plus a CI-generated wiring diagram snapshotted from the running graph and committed beside the launch files; correctness claims come from running trunk's existing system-test suite against published, signed base images. A registry makes modules and stacks discoverable; governance keeps the compatibility claims true.

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.
9. Custom topologies — real users have stacks and node graphs that don't match trunk's reference architecture (end-to-end learned planners, offboard splits, heterogeneous fleets). The design must serve them without forcing their topology through trunk's taxonomy.

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.
• Topology is authored in standard ROS 2 launch files. No configuration language compiles into a launch graph, and no slot/plugin taxonomy stands between a module and a stack. Swap-by-configuration works when the contract is a code API (Nav2/pluginlib); at the topic-topology level the ROS ecosystem's interoperability point has stubbornly remained the launch file, real deployments have topologies no fixed taxonomy anticipates, and any wiring-resolution layer becomes a new debugging surface that day-one ROS knowledge can't touch. When wiring breaks in the field, ros2 launch, readable XML, and ros2 topic info must be enough.
• Interface conventions over interface enforcement. Canonical topic names, types, QoS, and frames are a versioned spec page plus conformance tests. Enforcement is by test and by observation — never by schema or code generation.
• Checks observe; they never generate. The wiring picture is snapshotted from the running system in CI and committed; doctor diffs reality against it. An observed artifact can't lie, and an observational check works on any topology, however unconventional.
• 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 small manifest

A module repo contains its packages, a test_stack/ (§5), and a module.yaml that is deliberately small — deps, identity, and test metadata only. Wiring does not live here.

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 | data (e.g. vehicle — see #380) | platform (future — #380 §6)
airstack_compat: ">=0.19.0 <0.21.0"        # semver range vs trunk .env VERSION
targets: [isaac-sim]                       # host containers touched: robot | gcs | isaac-sim

deps: {apt: [], pip: []}                   # dep tier 1 (§6); rosdep keys come from package.xml
dockerfile: null                           # tier 2: Dockerfile.module using ARG BASE_IMAGE
overlay_image: null                        # tier 3: prebuilt overlay image ref
compose: null                              # optional compose fragment (mounts, env)

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/)
  marks: []                                # system-test marks its CI runs (guidance table in §5)

Deliberately absent: wiring metadata. The manifest carries no slot, role, or topic annotations. A module's interface is its launch file's declared args (ros2 launch <pkg> <file> --show-args) plus the interface conventions spec (§4); its wiring lives in whatever stack includes it.

The one interface convention modules follow (and it does the plug-and-play work): a module's launch file exposes every topic endpoint as a launch arg and defaults it to the canonical name from the conventions spec. In a conventional stack, including the module therefore requires zero remaps; only deviations appear in stack files — which is what makes them skimmable (§4).

Mapping the motivating cases: OptiTrack → ros_package whose launch defaults its output to /$ROBOT_NAME/odometry; custom planner → ros_package defaulting to /$ROBOT_NAME/global_plan; DFM2 → isaac_extension (Isaac supports extension search paths — lowest-coupling pilot).

3. Stacks: topology as self-contained folders

A stack is a folder — plain files, no schema beyond a required layout:

stacks/full_default/
├── modules.repos        # vcstool format, PINNED to tags/commits — never branches; optional top-level
│                        #   airstack_compat: key (sibling to repositories:, ignored by vcstool) declares
│                        #   the trunk range the stack was tested against
├── launch/
│   └── stack.launch.xml # THE wiring document: flat list of module includes (§4 rules).
│                        #   An unsplit stack has exactly this one entry point; a split stack carries one
│                        #   per host role (onboard/offboard/…) plus bridge.yaml — #380 §2
├── docker-compose.yaml  # composes this stack's images from module layers (§6)
├── wiring.md            # GENERATED in CI from the running graph (§4) — never hand-edited
└── README.md            # what this stack is for, its known limits

• Sync: airstack sync reads the active stack's modules.repos (vcstool format — not submodules) 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.
• Pinned .repos files are non-negotiable. A branch ref rots silently; airstack sync --update is the deliberate act that moves pins. Consequence: a stack with a pinned .repos is a release set, localized — "these modules at these versions, tested together" is a property every stack has for free, not registry machinery (§7 shrinks accordingly).
• launch/ holds the stack's entry points — one or more. An unsplit stack has exactly stack.launch.xml; a split stack (#380 §2) has one entry file per host role plus an explicit bridge.yaml. The single-locus rule and lint (§4) apply across all of a stack's entry files together.
• A stack declares the trunk it was tested against. modules.repos may carry a top-level airstack_compat: key — a semver range, sibling to repositories:; vcstool ignores it, our tooling reads it. sync warns when the checkout's active release falls outside the range (observe, don't gate); the verified claim remains a registered stack's CI-stamped compat matrix (§5, §7). Without this, a third-party stack's trunk binding lives nowhere but its owner's memory.
• Stacks need not live in trunk. A stack folder is self-contained, so a lab keeps a private stack repo wiring together public modules — no fork of AirStack anywhere. A consuming checkout declares the stack repo in its airstack.yaml and sync fetches it (RFC: Heterogeneous AirStack — vehicle configs, fleets, top-level configuration, and cross-embodiment platforms #380 §3). Trunk ships a small set of reference stacks (full_default, lite_default, plus presets that collapse today's local_*.launch.xml variant explosion into named stacks differing by a few include lines); everything else lives with its owner.
• Unconventional topologies are the same case, not a special case. An end-to-end VLA stack is simply a folder whose launch file includes the VLA module instead of the planning pipeline — nothing to declare, no taxonomy to fit, no machinery to opt out of. The design's obligation to such a stack is unchanged: its wiring is readable in one file, its wiring.md is generated the same way, and the same harness flies it.
• Swapping a module = editing one <include> (and any non-default args) in a launch file you own and can read — transparent when it works and when it breaks.
• Copy-drift between stacks is the accepted trade for folder independence, bounded two ways: genuinely-common sub-wirings (e.g. the takeoff/land task servers) live in shared includable launch files; and airstack stack diff <a> <b> compares two stacks' generated wiring.md (normalized, CI-verified), so the diff shows topology differences, not XML formatting noise.
• CLI surface: airstack module add|remove|list|sync|create|extract|search, airstack stack list|new|diff (stack new copies a reference stack), airstack init --release <X>, module create --in-tree / doctor --drift (§11).

4. Launch legibility: conventions + observed wiring

Traditional ROS launch trees are illegible for identifiable reasons — remaps scattered across a deep include tree, defaults indistinguishable from overrides, runtime logic in Python launch, and no picture — so a developer ends up in rqt_graph archaeology. Each cause gets a countermeasure; together they make a stack's topology readable at a glance from source:

1. Single-locus wiring rule. All cross-module remaps and topic-arg overrides live in the stack's entry-point launch file(s) — one file for an unsplit stack, one per host role for a split stack (RFC: Heterogeneous AirStack — vehicle configs, fleets, top-level configuration, and cross-embodiment platforms #380 §2). Module launch files declare topic args (with canonical defaults, §2) but never remap and never hardcode. The stack's entry files are the wiring diagram: flat files where every <include> block reads "this module, these connections." Enforced by a ~50-line CI lint: no <remap> outside stacks/*/launch/, every topic arg declared with a description=.
2. Interface conventions spec — the narrow waists, as documentation. docs/robot/autonomy/integration_checklist.md upgraded into a versioned spec: for each interchange point (sensors/* naming convention, odometry, global_map, global_plan, the trajectory group, control_setpoint, the interface_status group, tasks/*, safety, gossip) — canonical topic names, message types, QoS profiles, TF frames/units, and rate class. QoS and frames are named explicitly because they're the classic silent failures (best-effort-vs-reliable receives nothing; ENU vs NED). The spec is documentation that modules default to and conformance tests check — it is never input to any wiring machinery.
3. XML at the stack level. Stack launch files are XML only — declarative, greppable, statically parseable. Python launch stays available inside modules where genuinely needed.
4. CI-generated wiring.md. The system-test harness already brings up every reference stack in sim; a harness step snapshots the live graph (ros2 node list + ros2 topic info --verbose per topic — which also captures QoS) and renders a mermaid dataflow diagram, nodes grouped by module, edges labeled topic/type/QoS. It's committed at stacks/<name>/wiring.md; CI fails if the committed diagram differs from the observed graph. Properties: generated from the running system, so it cannot lie or rot; renders on GitHub and MkDocs; and a PR that changes wiring must regenerate it, so the review diff shows the topology change visually. (Prior art to vendor or imitate: ros2_graph; most of the plumbing exists in tests/harness/.) One wiring.md per stack, split or not: for a split stack the harness brings up every entry point and the diagram additionally groups nodes by host, with bridge.yaml edges (RFC: Heterogeneous AirStack — vehicle configs, fleets, top-level configuration, and cross-embodiment platforms #380 §2) drawn as boundary crossings. Sensor-driver nodes are normalized to their vehicle-manifest sensor ids — RFC: Heterogeneous AirStack — vehicle configs, fleets, top-level configuration, and cross-embodiment platforms #380 §1 pairs each sensor's real driver with its sim representation, and that declared pairing is what licenses treating them as the same graph endpoint — so a sim-generated baseline diffs cleanly against a hardware bring-up. A stack that cannot run in CI (hardware-only sensors, no sim asset) still gets an observed wiring.md: doctor --snapshot runs the identical capture against a real bring-up and commits it with a provenance line ("observed on hardware, , "); the CI drift check then reports it as unverified-in-CI rather than silently passing — an artifact observed on hardware still can't lie, it's just refreshed by hand instead of by CI.
5. Grep is a wiring query. Canonical names plus every-connection-in-the-source means grep -r global_plan stacks/my_stack/ answers "who touches this" — there is no layer that could materialize a connection that isn't written down.

doctor, entirely observational: doctor --live diffs the running graph against wiring.md (both endpoints present, QoS compatible, types match — ROS 2 type-hash mismatches fail silently as no-connection, so this check is load-bearing); doctor at compose time runs the dep-conflict checks (§6) and the lint; doctor --drift serves the researcher workflow (§11). Nothing in doctor generates or infers wiring. Where observe-only hardens into a gate — two enumerated places, no others: doctor's default posture everywhere is report-and-step-aside (§11's drift report is the extreme case: informs, never blocks). It errors only where flagging loudly is indistinguishable from launching a broken or unsafe system: (1) dep conflicts that would compose a broken image (§6), and (2) safety-placement violations — control-setpoint or trajectory-group topics appearing in any bridge.yaml (#380 §2). Anything added to this list needs the same RFC process as a conventions change (§8).

Safety floor, as convention + visibility: 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. No manifest field polices bypasses; instead wiring.md makes any direct edge into the interface layer visible, and doctor --live flags publishers of control setpoints that aren't the blessed controller. Loudly.

Layer role names (state_estimator, local_planner, local_world_model, global_planner, global_world_model, controller, behavior) are vocabulary — the docs taxonomy and the conformance-mark groupings in §5 — never configuration keys.

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 ./; (3) brings up the module's test_stack/ — a stack folder in the module repo, copied from a trunk reference stack with the module wired in (scaffolded by module create / module extract); (4) runs the existing suite unchanged via airstack test -m "<marks>". The module repo never copies a test — and its test_stack/ doubles as the module's living usage example: the install documentation is a working stack, by construction.

System tests double as 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. Guidance table by module category: global planner → waypoint_flight, autonomy; state estimator → liveliness, sensors, takeoff_hover_land; world model / perception → liveliness, sensors; sim extension → liveliness on the affected sim. Badge semantics: a compat badge reads "module M @ vM passes marks {…} in a test stack derived from reference stack S, on AirStack vX" — conformance to a stack, demonstrated by flying it.

CI matrix policy (decided — stated now, before it explodes): stacks × modules × sims × robot counts is unbounded, so: trunk CI tests reference stacks only; a module's CI tests that module in its test_stack/ via the reusable workflow; custom stacks are tested by their owners with the same workflow. Anything less explicit and either CI cost balloons or coverage quietly becomes fiction.

GPU runners (system tests need GPU + sim license; trunk uses OSMO-scheduled 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. Stacks never carry monolithic Dockerfiles — a stack's compose file references the module layer chain below; per-stack images are compositions of cached per-module layers. (This is why dep declarations live in module.yaml while wiring doesn't: dependencies must be per-module for layers to cache and compose across stacks.)

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 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-<stack>

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). Registered stacks get catalog entries too (description, target platform, embedded wiring.md).

Release sets are tagged reference stacks. Since a stack's pinned modules.repos already is a tested-together set (§3), a release set needs no machinery of its own: "AirStack 0.20 + full_default @ tag", blessed by one CI run of the whole stack. Individual badges mean "works in a reference stack"; a release-set tag means "this whole stack, these exact pins, passed together." Most users start from a tagged reference stack; à-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 interface conventions spec (§4.2) is public API even though nothing compiles against it — modules' defaults and conformance tests encode it. Changing a canonical topic name, type, QoS profile, or frame convention requires: semver-major on the spec, a coexistence window, and a short RFC in the registry repo. Without this, the first breaking change teaches everyone the badges are meaningless. Additions have a discovery mechanism: §11's drift reports across forks (three forks patching the same tap point = a missing convention).
• 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, and doctor --live catches the resulting silent non-connections at runtime.

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 = its test_stack/, source link); reference stack pages with their wiring.md diagrams embedded; the interface conventions spec; 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 reference-stack pins — 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 airstack 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.
• Agent skills ship with the mechanism, not after it. This repo's de-facto onboarding path is AGENTS.md + .agents/skills/ — if write-launch-file, integrate-module-into-layer, and add-ros2-package still teach the monolithic bringup pattern the day stacks land, every agent session will faithfully reintroduce the monolith. Update those skills in the same PR as each phase's machinery; add create-stack and extract-module skills. airstack module create generates the template repo (manifest, CI stub, launch with canonical defaults, test_stack/, README).
• 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.
• Hand-build before tooling: before writing any of the CLI, extract DFM2 and OptiTrack into module repos and author one custom stack folder by hand. A one-week experiment that surfaces whether the minimal manifest is actually minimal and whether the single-locus launch rule survives contact — it converts this RFC from speculation to a trip report. (Being validated through internal lab discussion + pilot.)

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 (= a tagged reference stack, §7) + 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 with canonical defaults) 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 a stack-launch override or Dockerfile fragment at graduation); recognize it as a missing convention (feed the §8 RFC process — drift reports across forks are how spec 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, test_stack/ scaffolded from the release's reference stack with the module wired in) 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, conventions spec, template, and drift report; the agent converts mechanically and verifies with doctor + the module'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 + success metrics

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, lowest coupling); agent-skill updates land with the machinery (§10).
2. Phase 2 — overlay + CLI: modules/ overlay + pinned 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 — stacks + legibility: reference stack folders (collapse the local_*.launch.xml variants into named stacks); interface conventions spec (topics + types + QoS + frames); single-locus lint; CI wiring snapshot → wiring.md + drift check; doctor --live; stack new|diff. This phase is also where #380's vehicle/fleet/top-level configuration layer lands — its config surface consumes stack folders.
4. Phase 4 — ecosystem: registry repo; docs catalog + embedding; nightly canary; org runner group + dispatch test bench; tagged release-set stacks; 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.

Success metrics (measured, not vibes):

1. Time-to-first-run — fresh clone → a custom stack flying in sim, for a developer new to AirStack.
2. Time-to-extract — an existing fork feature → registered module + working stack (the OptiTrack extraction is the baseline datapoint).
3. Conversion rate — trunk forks that become module + stack within a semester.

(1) and (2) are measured empirically with coding agents as reproducible proxy developers — fixed versioned prompts, pinned commits, harness-judged milestones, multiple trials per condition — under an internal study protocol, alongside human baselines from lab pilots. (3) is an ecosystem-health number tracked in the registry.

Ranked success factors: (1) the CI-against-published-images loop, (2) conventions 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.16" 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; unchanged services registry-retag via content fingerprints (docker_image_plan.py).
• 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] → OSMO-scheduled ephemeral pods via .github/orchestrator/ (spawn loop, JIT tokens, reap loop; privileged DinD with non-overlayfs data-root). 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: local.launch.xml, local_droan_cpu.launch.xml, local_macvo_obstacle_avoidance.launch.xml).
• 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 conventions spec's starting point): /{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.
• Prior art consulted: rosdistro/vcstool/buildfarm (distribution), Nav2/pluginlib (swap-by-config works at code-API contracts), Autoware (cautionary tale for launch-tree configuration abstraction), ros2_graph (live-graph → mermaid).

---

From a design session (2026-08-04), revised after an architecture audit (2026-08-19); consistency pass 2026-08-20 (entry-point layout, doctor gate enumeration, stack airstack_compat, hardware wiring.md provenance — changelog in comments). An earlier draft explored a different integration design — slot taxonomy, stack.yaml, wiring resolver — rejected for reasons summarized in the design-history comment below. Companion: RFC #380 — Heterogeneous AirStack. Comments and pushback welcome — especially from prospective module authors and stack owners.

[andrewjong]

Design history: the slot/resolver design that Rev 1 proposed, and why it was rejected

The RFC body above is Rev 2 (2026-08-19), rewritten as a standalone after an architecture audit. The original Rev 1 (2026-08-04, full text in this post's edit history) proposed a substantially different integration design. This comment records it so readers know what was already considered and rejected — please read it before proposing something similar.

What Rev 1 proposed

• Named slots. The autonomy layers' implicit roles became formal slots (state_estimator, local_planner, local_world_model, global_planner, global_world_model, controller, behavior), each with a contract: required launch args, QoS profiles, TF/frame conventions.
• A fat manifest. module.yaml declared slot:, provides:/requires: capability names, and an interface: block mirroring the launch file's args 1:1, with topic-endpoint args annotated {role: input|output, type, rung}.
• stack.yaml instead of launch files. A stack was a YAML mapping slots → module names, with inheritance (base: + diffs) so experiments were deltas, plus an overrides: section for rewires and leaf params.
• A wiring resolver. A generic Python bringup read the resolved stack and connected modules by rule priority: (1) rung-annotated args wire to canonical topics; (2) non-rung inputs auto-wire when exactly one provider exists; (3) explicit overrides win, typo-checked against the manifest.
• Rungs as machinery. The narrow-waist topic groups (odometry, global_plan, trajectory group, tasks/*, safety, …) were formal contract objects the resolver and doctor computed against, with an admission test for adding new ones.
• Escape hatches for modules that didn't fit: a stack_module type with consumes:/produces:/replaces: (an end-to-end VLA planner would declare replaces: [global_planner, local_planner, local_world_model] and the resolver would vacate those slots), plus a three-tier verifiability ladder (slot filler → ladder-spanning → freeform).
• Release sets as registry machinery — periodically published lockfiles of "trunk + module versions tested together."

Why it was rejected

1. It bundled two separable designs. The distribution machinery (thin module repos, CI-against-published-images, Docker layer tiers, registry, governance, the researcher fork-to-module workflow) never depended on the topology abstraction — Rev 1's own ranked success factors didn't include stack.yaml. All of that survives in Rev 2 nearly verbatim. The slots/resolver half concentrated all the risk.
2. The taxonomy strained on the first hard case. The stack_module/replaces:/three-tier apparatus existed because an end-to-end VLA planner — the first unconventional module considered — didn't fit the slots. A taxonomy needing that many escape hatches before meeting a single external user would break on real custom topologies; each would bend slots into shape through heavy overrides:, reinventing today's remap blocks in YAML plus an indirection layer, and defeating the plug-and-play goal it was built for. In Rev 2 an unconventional topology is not a special case at all: it's a stack folder whose launch file wires what it wires.
3. The resolver was a new debugging surface. When wiring breaks in the field, a developer's day-one ROS knowledge (ros2 launch, readable XML, ros2 topic info) must be sufficient. Debugging three-rule resolution priority isn't that — and auto-wire-on-unique-provider meant adding a second provider anywhere silently changed behavior elsewhere. It also destroyed grep-ability: an auto-wired connection exists nowhere in the source.
4. Prior art cuts against topic-level slot systems. Swap-by-configuration succeeds where the contract is a code API (Nav2/pluginlib); at the topic-topology level the ROS ecosystem's interoperability point has remained the launch file, and launch-tree configuration abstractions (Autoware being the cautionary tale) make swapping harder, not easier.

What Rev 1's ideas became in Rev 2

• Slot names → vocabulary (docs taxonomy, conformance-mark groupings), never config keys.
• The rung table → the interface conventions spec (canonical names/types/QoS/frames as documentation + conformance tests, under the same deprecation governance) — modules default to it instead of being wired by it.
• Resolver-verified wiring → observation: the CI-generated wiring.md snapshot per stack + doctor --live diffing the running graph against it.
• stack.yaml + inheritance → stack folders of plain pinned-.repos + XML launch; inheritance's job is done by shared includable sub-launches and airstack stack diff over generated wiring.
• Slot conformance → stack conformance: a badge means "passes these marks in a test stack derived from a reference stack."
• Release-set lockfiles → tagged reference stacks (a pinned modules.repos already is a tested-together set).
• The safety-floor manifest flag → visibility: bypass edges show up in wiring.md and doctor --live flags unblessed control-setpoint publishers.

Rev 2 also added things absent from Rev 1: the explicit CI matrix policy, agent-skill updates in Phase 1, a hand-build-before-tooling pilot, and measurable success metrics. Validation next: internal lab discussion + the hand-built pilot; the time-based metrics will be measured with coding agents as reproducible proxy developers under a separate internal study protocol.

[andrewjong]

Changelog: consistency pass (2026-08-20)

A cross-review of #379 / #380 / #385 surfaced a few wording-level inconsistencies between the documents and four spec gaps. The body above was updated in place; no design decisions changed. What moved:

• §2 — the type: enum now lists platform (future, RFC: Heterogeneous AirStack — vehicle configs, fleets, top-level configuration, and cross-embodiment platforms #380 §6), so the enum and RFC: Heterogeneous AirStack — vehicle configs, fleets, top-level configuration, and cross-embodiment platforms #380 agree.
• §3 — the stack layout explicitly allows one or more entry points: unsplit stacks have exactly stack.launch.xml; split stacks (RFC: Heterogeneous AirStack — vehicle configs, fleets, top-level configuration, and cross-embodiment platforms #380 §2) carry one entry file per host role plus bridge.yaml. §4's single-locus rule was reworded to span all of a stack's entry files. (Previously the "required layout" mandated stack.launch.xml, which RFC: Heterogeneous AirStack — vehicle configs, fleets, top-level configuration, and cross-embodiment platforms #380's split stacks contradicted.)
• §3 — new: a stack declares the trunk it was tested against via an optional top-level airstack_compat: key in modules.repos (sibling to repositories:; vcstool ignores it). sync warns on mismatch — observe, don't gate; the verified claim remains the CI-stamped compat matrix. Closes the gap where a third-party stack's trunk binding lived nowhere.
• §3 — "stacks need not live in trunk" now points at the consumption mechanism: airstack.yaml stacks: + sync fetch (RFC: Heterogeneous AirStack — vehicle configs, fleets, top-level configuration, and cross-embodiment platforms #380 §3).
• §4.4 — wiring.md semantics pinned down: one per stack, split or not (nodes grouped by host, bridge edges marked); sensor-driver nodes normalized to vehicle-manifest sensor ids so a sim-generated baseline diffs cleanly against hardware; stacks that can't run in CI commit an observed snapshot via doctor --snapshot with a provenance line, reported as unverified-in-CI rather than silently passing.
• §4 — the observe-vs-gate tension is now resolved explicitly: doctor hardens into a hard error in exactly two enumerated places (dep conflicts at compose, control/trajectory topics in a bridge.yaml); growing that list requires the §8 RFC process.

Matching edits landed in #380 (pin-resolution rule, external stack repos) and #385 (trees updated) — see their changelogs.