feat(models): BaseVLA spine + 6 component bases + name_mapping (basevla-spine lift #1 Day 3)

[rylinjames]

Summary

Lift #1 Day 3 per features/03_export/basevla-spine_plan.md. Foundation for the BaseVLA spine refactor. Pure addition — zero behavior change to existing exporters/runtime.

Implements the abstract spine + 6 component base classes + per-VLA name_mapping walker. Days 4-9 decompose each existing exporter onto this spine with per-model parity gates.

What this lands (~830 LOC including tests)

• src/reflex/models/base_vla.py (~320 LOC) — BaseVLA ABC with 6 slots (per decision S-2: vision/llm/vlm/projectors/heads/text). REQUIRED_SLOTS + OPTIONAL_SLOTS contract validated at construction (raises on missing required, undeclared slot pass, unknown slot name, required/optional overlap). from_config(spec) resolves type-tagged dicts through component registries. prepare_inference_weights() aggregates components' prepare_triton outputs (lift Expand doctor checklist to detect ROS2 distro + workspace state #3 substrate). load_state_dict() applies NAME_MAPPING + routes by slot prefix.

• src/reflex/models/_name_mapping.py (~95 LOC) — Per-VLA name_mapping walker per decision S-1 (faithful FluxVLA port, NOT per-component). First-match-wins prefix substitution; strict mode catches HF layout drift early.

• src/reflex/models/{vision,llm,vlm,projectors,heads,text}/__init__.py (~50 LOC each) — 6 component base ABCs. Each declares abstract forward() + concrete prepare_triton(prefix) no-op default per decision S-2 (bundles lift Expand doctor checklist to detect ROS2 distro + workspace state #3 interface into spine refactor to avoid per-component retrofit).

• tests/test_models_abstract.py (~270 LOC, 18 tests) — ABC enforcement, slot validation (5 cases), from_config dispatch (3 cases), prepare_inference_weights aggregation (3 cases), apply_name_mapping walker (5 cases including strict mode + immutability).

Decisions referenced

• S-1: per-VLA-config name_mapping (faithful FluxVLA port). Implemented as BaseVLA.NAME_MAPPING class var + apply_name_mapping walker.
• S-2: 6 slots including vlm_backbone (GR00T's Eagle) + text_encoder (DreamZero's T5). Validated via ALL_SLOTS constant.
• S-3: hybrid registration (decorator + explicit) — uses the Day 2 registries.
• S-5: JSON-Schema validation deferred. V1 catches typos via clear TypeError + diagnostic messages.

Pre-merge validation (per the lift #4 review-pass discipline)

• ast.parse syntax check on all 10 new files
• AST orphan-imports sweep — zero suspect names referenced without import
• Live import test: PYTHONPATH=src python -c "from reflex.models import BaseVLA..." succeeds with no circular deps
• CI pytest green (deferred — local venv has unrelated logfire/otel breakage)
• Doctor regression smoke green

Independent of in-flight work

• No collision with the existing dead src/reflex/models/smolvla.py (unused) or src/reflex/models/adapt.py (its own test). Day 6 will add models/vlas/smolvla.py (different path).
• No collision with PR fix(deps): scope numpy<2 upper bound to aarch64 (Jetson) only #143's numpy fix or any other open PR.

Next: Day 4

Decompose pi0 as the spine canary — proves the design works on a real VLA before pi0.5/smolvla/gr00t decomposition. Will be a separate PR.

🤖 Generated with Claude Code