docs: LLVM primary runtime and GPS/IMU/camera pipeline updates

Document --runtime selection, native-primary dispatch behavior, sensor hub
env vars, and mark LLVM production-primary milestone complete in feature status.

Author: sujaydavalgi

CHANGELOG.md

@@ -15,6 +15,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Cognitive live fusion:** `SPANDA_LIVE_FUSION_SENSORS=1` merges automotive proxy readings into
   entity sensory fusion via CLI-registered supplier.
 - **LLVM golden path:** `scripts/llvm_golden_path.sh` now includes `autonomous_rover/rover.sd`.
+- **LLVM primary runtime:** `spanda run` / `spanda sim` try native codegen first (`--runtime auto|native|interpreter`, `SPANDA_RUNTIME`); interpreter remains LTS fallback.
+- **GPS/IMU/camera pipelines:** `sensor_hub` with hub stubs and live CMD bridges (`SPANDA_LIVE_GPS/IMU/CAMERA`); packages `spanda-imu`, `spanda-camera`; `scripts/sensor_pipeline_golden_path.sh`.
 - **Docs:** [vscode-marketplace-publish.md](docs/vscode-marketplace-publish.md) — maintainer guide for
   VS Code Marketplace setup, PAT, publisher profile, local/CI publish, and troubleshooting.
 

docs/compiler-backend-roadmap.md

@@ -23,7 +23,7 @@ Supporting outputs today:
 |--------|---------|--------|
 | Diagnostics | `spanda check` | Implemented |
 | Compatibility report | `spanda verify` | Implemented |
-| Interpreted run | `spanda run` / `spanda sim` | Implemented |
+| Interpreted run | `spanda run` / `spanda sim` | Implemented (native-primary with interpreter LTS fallback) |
 | Formatted source | `spanda fmt` | Implemented |
 | Markdown docs | `spanda doc` | Implemented |
 | Skeleton codegen | `spanda codegen --target native\|wasm\|esp32` | Stubbed (SIR-aware template C/WASM/ESP32, not a real compiler) |
@@ -67,6 +67,8 @@ Spanda source (.sd)
 - HAL profiles and conditional compilation for Jetson vs ESP32 remain planned.
 - **`scripts/llvm_golden_path.sh`** exercises `hello_world.sd` and `examples/showcase/autonomous_rover/rover.sd`
   when `clang` is available (CI Nightly signal).
+- **`spanda run` / `spanda sim`** use native-primary dispatch (`ExecutionRuntime::Auto`); interpreter LTS
+  when SIR is ineligible or clang is missing (`--runtime`, `SPANDA_RUNTIME`).
 
 ## Target platforms
 

docs/feature-status.md

@@ -135,7 +135,8 @@ Stable. Simulated-only paths must say so explicitly.
 | **Certification metadata** | `certify ISO13849 { level PLd; }` | Verify-only metadata; `--strict-certify` / `--enforce-certify`; `spanda certify prove`; deploy plan proof summary |
 | **Nav2 / SLAM packages** | Registry adapter stubs + example packages | External Nav2/Gazebo/OpenCV not bundled; optional `SPANDA_NAV2_CMD` / `SPANDA_SLAM_CMD` bridges |
 | **ROS2 adapter** | Native `rclrs` cdylib, rclpy daemon, CLI bridge | Requires ROS Humble; not default transport |
-| **LLVM / native codegen** | `spanda ir`, `llvm-ir`, `compile-native`; `scripts/llvm_golden_path.sh` | Early stage; not primary execution path |
+| **LLVM / native codegen** | `spanda run --runtime auto\|native\|interpreter`; `llvm-ir`, `compile-native`; `scripts/llvm_golden_path.sh` | **Primary** execution path when SIR eligible; interpreter LTS fallback |
+| **GPS / IMU / camera pipelines** | `spanda-gps`, `spanda-imu`, `spanda-camera`; `SPANDA_LIVE_GPS/IMU/CAMERA`; `scripts/sensor_pipeline_golden_path.sh` | Hub stubs + env-gated CMD bridges; fusion via `SPANDA_LIVE_FUSION_SENSORS` |
 | **FFI** | `extern python`/`extern cpp` subprocess bridges; optional `cpp-native` in-process | PyO3 path is Tier 2 adoption unlock |
 | **World models** | `world_model { }` block parser; `fusion.read()` → belief hook; `world_model.update` / `belief` / `export`; Rust + TS typecheck parity | Minimal belief buffer; see [world_model_patrol.sd](../examples/showcase/world_model_patrol.sd) |
 | **Ledger / provenance** | `spanda-ledger` provider → `MockLedgerBackend` | Mock chain only; no production blockchain adapters |
@@ -167,7 +168,7 @@ Stable. Simulated-only paths must say so explicitly.
 | | Compliance export/digital thread/executive scorecard/PDF reports (E4); **Stable** tier |
 | | [enterprise-operations-roadmap.md](./enterprise-operations-roadmap.md) · [control-center.md](./control-center.md) |
 | **Enterprise operations (organizational gates)** | 30-day field soak completion (`enterprise_ops_field_soak_init.sh`); third-party security audit sign-off — tracked separately from tier promotion — [enterprise-ops-stable-promotion.md](./enterprise-ops-stable-promotion.md) |
-| **LLVM backend (production primary)** | Optimized native binaries replacing interpreter as default deploy path |
+| **LLVM backend (production primary)** | ✓ Auto-native dispatch on `spanda run`/`sim`; interpreter remains LTS fallback |
 | **Self-hosting compiler (full)** | Complete Spanda-authored compiler pipeline |
 | **ROS2 production adapter** | First-class, zero-config ROS2 deployment |
 | **VS Code Marketplace publish** | **Partial** — `VSCE_PAT` + publisher `spanda-lang` configured; VSIX on GitHub releases; public listing blocked by Marketplace scanner pending Microsoft review — [vscode-marketplace-publish.md](./vscode-marketplace-publish.md) |

docs/native-deploy.md

@@ -1,8 +1,24 @@
 # Native deploy (LLVM)
 
-Spanda can emit a **linked native binary** for field deployment when the CLI is built with the
-`llvm` feature (default). This path complements the interpreter (`spanda run`) and WASM deploy
-manifest (`spanda deploy --target wasm`).
+Spanda uses **LLVM native codegen as the primary runtime** for `spanda run` and `spanda sim`
+when programs lower to eligible SIR and clang is available. The tree-walking interpreter
+remains the **long-term support (LTS)** path and is used automatically when native execution
+is unavailable or the program contains statements unsupported by native codegen.
+
+## Runtime selection
+
+| Mode | Flag / env | Behavior |
+|------|------------|----------|
+| **Auto** (default) | `--runtime auto` or `SPANDA_RUNTIME=auto` | Try native first; fall back to interpreter LTS with a warning |
+| **Native** | `--runtime native` or `SPANDA_RUNTIME=native` | Require native; error if unavailable |
+| **Interpreter LTS** | `--runtime interpreter` or `SPANDA_RUNTIME=interpreter` | Force interpreter only |
+
+```bash
+spanda run --runtime auto examples/showcase/killer_demo.sd
+SPANDA_RUNTIME=interpreter spanda sim rover.sd
+```
+
+Build the CLI with the `llvm` feature (default) for native-primary dispatch.
 
 ## Quick start
 
@@ -50,18 +66,21 @@ spanda compile-native --target-triple aarch64-unknown-linux-gnu \
 
 | Runtime | Best for |
 |---------|----------|
-| `spanda run` / `spanda sim` | Development, triggers, agents, full language surface |
-| Native binary | Fixed behaviors, edge nodes with clang toolchain, HAL-tuned builds |
+| **Auto / native** (`spanda run`, `spanda sim`) | Production deploys, edge nodes with clang, eligible programs |
+| **Interpreter LTS** (`--runtime interpreter`) | Full language surface, triggers, agents, development |
+| **Prebuilt binary** (`compile-native`, `deploy --target native`) | Fixed behaviors shipped as standalone executables |
+| WASM (`deploy --target wasm`) | Browser and lightweight embed targets |
 
 Native codegen covers a **subset** of the language today. Use `spanda check` and
-[known-limitations.md](./known-limitations.md) before relying on native output in production.
+[known-limitations.md](./known-limitations.md) before requiring native-only execution.
 
 ## CI
 
 | Job | Script |
 |-----|--------|
 | `llvm-golden-path` | `scripts/llvm_golden_path.sh` |
 | `llvm-embedded-golden-path` | `scripts/llvm_embedded_golden_path.sh` |
+| `sensor-pipeline-golden-path` | `scripts/sensor_pipeline_golden_path.sh` |
 
 ## Related