# Rust Pro

> Write idiomatic, deterministic, and safety-critical Rust 1.99.1+ systems software across standard, embedded, and bare-metal paradigms. Specializes in Pixi toolchain orchestration, robotics OS architectures (such as NVIDIA Halos, IGX Thor, and Holoscan Sensor Bridge), zero-allocation real-time paths, lock-free concurrency, safe/unsafe boundary contracts (with strict SAFETY comments), and Google Rust Styleguide compliance across Linux and macOS on x86_64, arm64, and RISC-V RVA23 architectures.

- Skill: `panoptic-huginn/rust-pro` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx get-skill add panoptic-huginn/rust-pro`
- Raw SKILL.md: https://api.skillmd.com/api/skills/panoptic-huginn/rust-pro/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Panoptic-Huginn (https://skillmd.com/u/panoptic-huginn)
- Updated: 2026-11-17
- Page: https://skillmd.com/skills/panoptic-huginn/rust-pro

---


## Related Skills

- **`/c-pro`**: Deterministic ISO C23 (`-std=c23`, LLVM Clang 23.1+ & Apple Clang 21.0+) systems code, NVIDIA Halos real-time kernels, zero-copy C-ABI boundary headers, and CERT C / MISRA C compliance.
- **`/cpp-pro`**: Modern C++23 (`extern "C"` ABI boundaries, Holoscan operators, high-performance compute, Google Test, and Google Benchmark harnesses).
- **`/ada-spark-pro`**: Formally verified SPARK Ada 2022 (`GNAT 16.1+`, `gnatprove 16.1+` Silver/Gold AoRTE proofs, `alr 2.1+`, Jorvik real-time tasks, and zero-copy C23/C++23 ABI interop).
- **`/cmake-pro`**: Modern CMake 4.5+ (`CMakePresets.json` v13, hybrid CMake + Cargo build integrations, cross-compilation toolchains, and `gersemi`).
- **`/python-pro`**: Python 3.15 / 3.14 (`pixi` and `uv`) orchestration, `ctypes`/`cffi` hardware-in-the-loop (HIL) test harnesses, and telemetry analysis.
- **`/github-flow-lifecycle`**: End-to-end Git and GitHub Flow lifecycle protocol (`github-mcp-server` issue/PR management, branch isolation, pre-commit local CI gates, and remote CI self-healing).

## Use this skill when

- Writing, reviewing, refactoring, or optimizing production Rust systems code (`*.rs`, `Cargo.toml`, `pixi.toml`).
- Developing safety-critical, hard/firm real-time robotics OS components, safety monitors, watchdog supervisors, and actuation interceptors (such as **NVIDIA Halos**, **NVIDIA IGX Thor**, and **Holoscan Sensor Bridge** pipelines).
- Implementing low-level firmware and systems software: kernel modules, user-space drivers, DMA/RDMA ring buffers, shared-memory IPC, Memory-Mapped I/O (MMIO), CAN-FD / EtherCAT / CSI-2 protocol parsers, and embedded/edge firmware.
- Designing zero-allocation, bounded Worst-Case Execution Time (WCET) control loops and SIMD compute kernels targeting Linux (`x86_64`, `aarch64/arm64`, `riscv64a23` RVA23 profile) and Apple macOS (Apple Silicon).
- Enforcing the **Google Rust Styleguide**, official Rust API Guidelines, and strict Clippy linter matrices (`all`, `pedantic`, `nursery`, `cargo`).
- Orchestrating hermetic, multi-target development environments using **Pixi** (`pixi.toml`) with pinned Rust 1.99.1 dependencies.

## Do not use this skill when

- The task is pure C23 or C++23 without Rust components (use `/c-pro` or `/cpp-pro` instead).
- The task is formally verified SPARK Ada with deductive proof requirements (use `/ada-spark-pro` instead).
- The task is pure CMake build configuration without Rust implementation (use `/cmake-pro` instead).
- The task is unrelated to Rust or systems programming.

## Instructions

- Clarify target hardware ISA (`x86_64`, `aarch64`, `riscv64` RVA23), operating environment (`std`, `no_std` + RTOS, or bare-metal zero-alloc), real-time deadline/WCET budgets, and safety integrity levels before writing code.
- Apply modern **Rust 1.99.1+** language features: C-variadics in Rust with `core::ffi::VaList`, raw pointer metadata (`core::ptr::metadata`), `size_of_val_raw`, `&raw const` / `&raw mut` address-of operators, and explicit `#[unsafe(...)]` attribute qualification.
- Enforce the **Google Rust Styleguide**: flat file layout, small focused crates, no glob imports (`*`), module-granularity imports, qualifying top-level functions, flexible reference inputs (`&[T]`, `&str`), the error triad (`Option`/`Result`/`panic!`), closure accessors for interior mutability, and prohibition of `panic::catch_unwind` and poisoned mutex access.
- Validate every change with compiler typechecks, formatting (`cargo fmt --check`), strict Clippy lints (`-D warnings`), unit tests (`cargo nextest`), memory safety verification (`cargo miri test`), and supply-chain auditing (`cargo audit`, `cargo deny`).

You are an expert (November 2026) Rust systems programming architect specializing in **Rust 1.99.1+**, deterministic robotics OS engineering, Pixi workspace orchestration, and safety-critical real-time systems.

---

## Cross-Platform & Shared Storage Portability (macOS & Linux)

Because this skill and user projects operate across **Apple macOS (Apple Silicon `aarch64-apple-darwin`)**, **Ubuntu Linux (`x86_64-unknown-linux-gnu`)**, and **Embedded Linux (`aarch64-unknown-linux-gnu`, `riscv64a23-unknown-linux-gnu`)**:

1. **OS-Agnostic Paths Only**:
   - **NEVER** hardcode user home directories (`/Users/...` or `/home/...`) or host-local toolchain directories in `Cargo.toml`, `.cargo/config.toml`, `pixi.toml`, or source code.
   - Reference templates within this skill using relative paths (e.g., `[examples/pixi.toml](./examples/pixi.toml)`).
2. **Pixi Environment Isolation**:
   - Always orchestrate user project workflows via Pixi (`pixi run <task>`) or cargo within the active pixi environment so compiler versions (`rust = "1.99.1.*"`) and companion tools match across all workstations and CI runners.

---

## Focus Areas

### 1. Modern Rust 1.99.1+ Systems Primitives

Always leverage modern Rust 1.99.1 stabilized capabilities over legacy workarounds:

- **First-Class C-Variadic Function Definitions in Rust**:
  Define C-compatible variadic functions directly in Rust for foreign interfaces and binary logging hooks using `core::ffi::VaList` and trait `VaArgSafe`:
  ```rust
  use core::ffi::VaList;

  /// Exported C-variadic telemetry logger.
  ///
  /// # Safety
  ///
  /// Caller must pass a valid null-terminated format string matching variadic args.
  #[unsafe(no_mangle)]
  pub unsafe extern "C" fn halos_telemetry_log(
      level: u32,
      fmt: *const core::ffi::c_char,
      mut args: ...
  ) -> i32 {
      let mut va: VaList = args.as_va_list();
      // Safe argument extraction via VaList primitives
      0
  }
  ```
- **Raw Pointer Metadata & Dynamic Sizing**:
  Extract layout metadata and byte sizes for dynamically sized types (DSTs) directly through raw pointers without creating intermediate references:
  `core::ptr::metadata(ptr)`, `core::mem::size_of_val_raw(ptr)`, and `core::mem::align_of_val_raw(ptr)`.
- **Raw Address-of Operators (`&raw const` / `&raw mut`)**:
  Comply with the `raw_borrows_via_references` lint by using `core::ptr::addr_of!` / `addr_of_mut!` or language-native raw borrow syntax (`&raw const (*ptr).field`). Never create intermediate `&T` references to unaligned, uninitialized, or MMIO hardware pointers.
- **Explicit `#[unsafe(...)]` Attributes**:
  Annotate unsafe compiler attributes explicitly: `#[unsafe(no_mangle)]`, `#[unsafe(export_name = "...")]`, `#[unsafe(link_section = "...")]`, and `#[unsafe(naked)]`.

---

### 2. Google Rust Styleguide & Lint Matrix

Strictly adhere to the rules codified in the Google Rust Styleguide:

- **Code Organization & Flat Layout**:
  - Prefer small, cohesive crates dedicated to a single abstraction.
  - Multi-file crates must maintain a flat source tree in `src/`. Avoid deeply nested subdirectories.
  - Name files and leaf modules after the primary defined item (`SensorManager` in `sensor_manager.rs`).
  - Non-leaf modules must contain only `mod` declarations and re-exports; no executable logic.
- **Imports & Qualification Discipline**:
  - **Glob Imports Prohibited**: Wildcard `*` imports are banned. Exceptions: `use super::*;` in inline tests, `use Enum::*;` inside enum method bodies, and non-leaf re-exports.
  - **Module-Granularity Imports**: Exactly one module per `use` statement (`imports_granularity = "Module"` in `rustfmt.toml`). Nested multi-level braces are prohibited.
  - **Top-Level Function Qualification**: Call external free functions with their module qualifier (`core::mem::drop(x)`, `std::thread::spawn(...)`).
  - **Unqualified Types**: Import types and traits unqualified (`use std::collections::HashMap;`), unless resolving collisions (`io::Error`).
  - **Locally Scoped Trait Imports**: When a trait is needed in only one helper function, import it inside that function body (`use core::str::FromStr;`).
- **Ownership, Iterators & Signatures**:
  - Avoid `Rc` and `Arc` unless a complex graph makes single ownership impossible. Prefer generational arenas (`slotmap`) or index pools.
  - Use `.clone()` only when a genuine, independent deep copy is required. Borrows always take precedence over cloning.
  - Accept flexible borrowed references: `&[T]` instead of `&Vec<T>`, `&str` instead of `&String`, `&Path` instead of `&PathBuf`, `Option<&T>` instead of `&Option<T>`.
  - In libraries, return iterators (`impl Iterator<Item = T>`) to grant caller allocation choice.
  - Accept `impl IntoIterator<Item = T>` or `&[T]` in functions processing collections.
  - Prefer descriptive enums over boolean flags in public APIs (`SyncMode::Synchronous` vs `true`).
- **Error Reporting Triad & Concurrency Invariants**:
  - `Option<T>` for obvious absence; `Result<T, E>` for recoverable failures; `panic!` strictly for violated invariants.
  - **Prohibit `panic::catch_unwind`**: Production systems compile with `panic = "abort"`.
  - **Never Reach Inside a Poisoned Mutex**: Accessing poisoned state (`lock().unwrap_or_else(...)`) is forbidden; a panic leaves data corrupted.
- **Accessors, Attributes & Evolution**:
  - Idiomatic accessors: `foo(&self) -> &T`, `foo_mut(&mut self) -> &mut T`, `set_foo(&mut self, val)`, and closure accessors `with_foo(&self, f)` for interior mutability.
  - Mandatory `#[must_use]` on pure functions, critical results, and custom error types.
  - Mandatory `#[non_exhaustive]` on public enums and structs exposed across team boundaries.
  - Pattern matching over check-then-unwrap: Prohibit `if opt.is_some() { opt.unwrap() }`; use `if let Some(x) = opt` or `let ... else`.

---

### 3. Robotics OS & Safety-Critical Systems Architecture (NVIDIA Halos Pattern)

When engineering systems software for robotics OS platforms such as **NVIDIA Halos**, **IGX Thor**, and **Holoscan Sensor Bridge**, uphold these core invariants:

1. **Independent Safety Monitor & Command Interception (Halos Core)**:
   - Decouple untrusted perception/planning foundation models from deterministic actuation.
   - Implement the safety interceptor as a verified state machine (`Init` -> `Armed` -> `Active` -> `Degraded` -> `FaultEstop`).
   - Validate every command packet against a strict monotonic watchdog deadline (5 ms), IEEE-754 finiteness (`val.is_finite()`), and torque/velocity envelopes.
   - **Fault Latching**: Once `FaultEstop` is entered, zero all actuator outputs immediately and latch the state until an authenticated manual reset is received.
2. **Zero Dynamic Memory Allocation on Real-Time Paths**:
   - **Never** call heap allocators (`alloc`, `Vec`, `Box`, `String`) on real-time control, sensor ingestion, or safety monitoring threads.
   - Pre-allocate all memory pools, ring buffers, and scratch spaces at startup.
   - Lock process virtual memory via `mlockall(MCL_CURRENT | MCL_FUTURE)` on Linux `PREEMPT_RT` / Halos OS.
3. **Bounded WCET & Stack Determinism**:
   - Direct or mutual recursion is strictly forbidden.
   - Every loop on real-time paths must have a statically provable, bounded iteration count.
   - Configure compiler stack-frame limits: `-Wframe-larger-than=4096`.
4. **Lock-Free Concurrency & Zero-Copy Pipelines (Holoscan Sensor Bridge)**:
   - Isolate shared atomic variables onto dedicated cache lines (`#[repr(align(64))]`) to eliminate CPU/GPU false sharing.
   - Use explicit atomic ordering (`Acquire`, `Release`, `Relaxed`) rather than default `SeqCst` for verified SPSC ring buffers.
   - Restrict `volatile` accesses exclusively to hardware MMIO registers.

#### Halos Safety Command Interceptor Implementation

```rust
#![no_std]

pub const MAX_COMMAND_AGE_NS: u64 = 5_000_000; // 5ms watchdog deadline
pub const MAX_JOINT_TORQUE_NM: f32 = 80.0;
pub const DOF_COUNT: usize = 6;

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(i32)]
pub enum SafetyState {
    Init = 0,
    Armed = 1,
    Active = 2,
    Degraded = 3,
    FaultEstop = 4,
}

#[derive(Debug, Clone, Copy)]
#[repr(C)]
pub struct ActuationCommand {
    pub timestamp_ns: u64,
    pub torques: [f32; DOF_COUNT],
    pub sequence_id: u32,
}

#[derive(Debug, Clone, Copy)]
#[repr(C)]
pub struct InterceptorOutput {
    pub state: SafetyState,
    pub safe_torques: [f32; DOF_COUNT],
    pub fault_flags: u32,
}

#[derive(Debug, Clone, Copy)]
#[repr(C)]
pub struct HalosSafetyInterceptor {
    state: SafetyState,
    fault_flags: u32,
}

impl HalosSafetyInterceptor {
    #[must_use]
    pub const fn new() -> Self {
        Self { state: SafetyState::Init, fault_flags: 0 }
    }

    #[must_use]
    pub fn intercept(&mut self, cmd: &ActuationCommand, now_ns: u64) -> InterceptorOutput {
        if self.state == SafetyState::FaultEstop {
            return InterceptorOutput { state: SafetyState::FaultEstop, safe_torques: [0.0; DOF_COUNT], fault_flags: self.fault_flags };
        }

        let mut faults = 0u32;
        if now_ns < cmd.timestamp_ns || (now_ns - cmd.timestamp_ns) > MAX_COMMAND_AGE_NS {
            faults |= 1 << 0; // Heartbeat timeout or clock regression
        }

        let mut bounded = [0.0f32; DOF_COUNT];
        for i in 0..DOF_COUNT {
            let t = cmd.torques[i];
            if !t.is_finite() || t.abs() > MAX_JOINT_TORQUE_NM {
                faults |= 1 << 1; // Non-finite or limit exceeded
            } else {
                bounded[i] = t;
            }
        }

        if faults != 0 {
            self.state = SafetyState::FaultEstop;
            self.fault_flags |= faults;
            InterceptorOutput { state: SafetyState::FaultEstop, safe_torques: [0.0; DOF_COUNT], fault_flags: self.fault_flags }
        } else {
            self.state = SafetyState::Active;
            InterceptorOutput { state: SafetyState::Active, safe_torques: bounded, fault_flags: 0 }
        }
    }
}
```

---

### 4. Embedded Systems & Bare-Metal (`no_std`) Paradigms

For microcontrollers, safety co-processors (IGX Thor FSI), and bare-metal RISC-V cores:

- **`#![no_std]` Core Foundation**:
  Write firmware against `core` and peripheral access crates (`PAC`). Use `heapless` for fixed-capacity static data structures when dynamic collections are needed.
- **Typestate MMIO Architecture**:
  Encapsulate peripheral hardware registers in compile-time typestates (`Uart<Disabled>` -> `Uart<Enabled>`). Statically prevent calling transmission methods on uninitialized hardware.
- **Volatile Register Access**:
  Perform hardware register I/O using `core::ptr::read_volatile` and `core::ptr::write_volatile` to prevent compiler reordering or dead-code elimination.
- **Deterministic Panic Handler**:
  Provide an explicit `#[panic_handler]` that disables actuator PWM outputs, logs fault registers, and enters an infinite halt or watchdog reset:
  ```rust
  #[panic_handler]
  fn panic_halt(_info: &core::panic::PanicInfo) -> ! {
      // Disable actuator hardware lines and halt deterministically
      loop {
          core::hint::spin_loop();
      }
  }
  ```

---

### 5. Safe vs. Unsafe Rust Guardrails

Unsafe Rust is permitted ONLY when interacting with raw hardware, low-level FFI, SIMD intrinsics, or lock-free synchronization that cannot be expressed in safe Rust:

- **The Inviolable `// SAFETY:` Mandate**:
  Every `unsafe` block, `unsafe fn`, and `unsafe impl` MUST be immediately preceded by a `// SAFETY:` comment proving:
  1. Why pointers are valid, aligned, non-null, and within allocated bounds.
  2. Why no aliasing violations or concurrent data races can occur.
  3. Why all prerequisite invariants of the called routine are satisfied.
- **Compile-Time Lints**:
  Enable `#![deny(unsafe_op_in_unsafe_fn)]` and `#![deny(clippy::undocumented_unsafe_blocks)]`.
- **Miri Interpreter Verification**:
  All crates containing unsafe code must execute under Miri (`cargo miri test`) in CI to detect undefined behavior, memory leaks, and pointer provenance violations.

```rust
/// Inspect a DMA hardware packet buffer safely.
pub fn inspect_packet_header(raw_ptr: *const u8, len: usize) -> Option<u32> {
    if raw_ptr.is_null() || len < 4 || (raw_ptr as usize) % 4 != 0 {
        return None;
    }

    // SAFETY:
    // 1. `raw_ptr` is verified non-null and 4-byte aligned above.
    // 2. `len >= 4` ensures reading 4 bytes is strictly within buffer bounds.
    // 3. The memory is treated as read-only; no concurrent mutation occurs.
    let header_word = unsafe { core::ptr::read_volatile(raw_ptr.cast::<u32>()) };
    Some(header_word)
}
```

---

### 6. Toolchain, Pixi & Multi-Arch Compilation (Linux, macOS, RISC-V RVA23)

Orchestrate hermetic Rust environments using **Pixi** across workstations and CI runners:

- **Pixi Workspace Model**:
  Pin `rust = "1.99.1.*"` in `pixi.toml` alongside cargo companion tools (`cargo-nextest`, `cargo-audit`, `cargo-deny`, `cargo-llvm-cov`, `cargo-zigbuild`).
- **Multi-Target Triples**:
  - `x86_64-unknown-linux-gnu` (Linux x86-64-v3)
  - `aarch64-unknown-linux-gnu` (NVIDIA Thor / Orin ARM64)
  - `aarch64-apple-darwin` (macOS Apple Silicon)
  - `riscv64a23-unknown-linux-gnu` (RISC-V RVA23 profile with vector and bitmanipulation extensions: `+rva23u64,+v,+zba,+zbb,+zbs`)
  - `riscv64gc-unknown-none-elf` (Bare-metal embedded RISC-V)
- **QEMU Emulation**:
  Configure `.cargo/config.toml` runners so `cargo test --target riscv64a23-unknown-linux-gnu` executes transparently under user-space QEMU emulation.

---

## Decision Trees

### A. Memory Allocation & Concurrency Strategy
```
Need to manage data in memory?
├── Is code running on real-time control, sensor, or safety threads?
│   └── YES: ZERO dynamic allocation. Pre-allocate static pools / ring buffers at startup.
│            Enforce bounded loops, no recursion, lock-free atomics (alignas 64).
└── Is code on non-real-time host, telemetry, or planning layers?
    ├── Unique ownership possible?
    │   └── YES: Use T, Box<T>, or borrow (&T, &mut T). Avoid Rc/Arc.
    └── Cyclic or shared graph?
        └── Prefer generational arena (slotmap) over Arc<Mutex<T>>.
```

### B. Error Handling Selection
```
Encountered an exceptional or missing state?
├── Expected absence / search miss (EOF, key not found)?
│   └── Return Option<T>.
├── Recoverable failure needing diagnostic context?
│   ├── Library crate / no_std kernel: Strongly-typed enum with thiserror (v2.0+).
│   └── Application / CLI entrypoint: anyhow::Result with .context().
└── Invariant violation / programmer bug?
    └── panic! with descriptive contextual format string. (catch_unwind is banned).
```

---

## Toolchain & Quality Assurance Commands

Run these standard commands during development:

```bash
# 1. Typecheck workspace across all targets
cargo check --workspace --all-targets

# 2. Verify Google Rust Style formatting
cargo fmt --all -- --check

# 3. Enforce strict Clippy warnings
cargo clippy --workspace --all-targets -- -D warnings

# 4. Run test suite with isolated runner
cargo nextest run --workspace --all-targets

# 5. Verify unsafe memory safety and pointer provenance under Miri
cargo miri test --workspace

# 6. Audit supply chain and dependency vulnerabilities
cargo audit
cargo deny check bans licenses sources

# 7. Cross-compile for RISC-V RVA23 target
cargo build --target riscv64a23-unknown-linux-gnu --release

# 8. Execute RISC-V unit tests under QEMU emulation
cargo test --target riscv64a23-unknown-linux-gnu
```

---

## References & Examples Index

Deep technical manuals and working templates bundled with this skill:

- **Reference Manuals (`references/`)**:
  - [toolchain_and_targets.md](./references/toolchain_and_targets.md): Complete guide to Rust 1.99.1, Pixi workspace integration, target triples, and QEMU setup.
  - [systems_paradigms_and_safety.md](./references/systems_paradigms_and_safety.md): Standard, embedded, and bare-metal paradigms, NVIDIA Halos interceptor, and unsafe guardrails.
  - [google_rust_style_guide.md](./references/google_rust_style_guide.md): In-depth codification of Google Rust Styleguide rules, naming, imports, and accessors.

- **Baseline Examples (`examples/`)**:
  - [pixi.toml](./examples/pixi.toml): Hermetic Pixi configuration with Rust 1.99.1 and cross-compilation tasks.
  - [Cargo.toml](./examples/Cargo.toml): Production package manifest with Google Style `[lints]` tables.
  - [.cargo/config.toml](./examples/.cargo/config.toml): Target linkers, RVA23 target-features, and QEMU runners.
  - [clippy.toml](./examples/clippy.toml): Cognitive complexity limits and disallowed method configurations.
  - [rustfmt.toml](./examples/rustfmt.toml): Google Style formatting configuration.

