feat(skills): improve spacecraft-rust-guidelines with Apollo Best Practices

Integrate cargo flamegraph profiling and smart pointer/thread safety references:
- Add cargo flamegraph installation and execution guide to SKILL.md under Tooling section.
- Add thread-safety guidelines and smart pointer comparison table to references/idioms.md.
- Add standard library lazy initialization primitives (OnceCell, OnceLock, LazyCell, LazyLock).
- Update references/ATTRIBUTION.md and CREDITS.md to reflect new adapted materials.

Co-Authored-By: Antigravity (Gemini 3.5 Flash) <noreply@google.com>

Author: UnbreakableMJ

spacecraft-rust-guidelines.skill

@@ -13,7 +13,7 @@ in accordance with [The Steelbore Standard §15.3](../spacecraft-standard/SKILL.
 | Author(s)  | Apollo Graph, Inc.                             |
 | License    | MIT License                                    |
 | Source URL | https://github.com/apollographql/skills        |
-| Scope      | Idiom/readability rules distilled into `references/idioms.md` — borrowing-vs-cloning, `Copy` sizing, idiomatic `Option`/`Result` flow, iterators-vs-`for`, clippy lint names + `expect`-over-`allow`, testing conventions (one assertion per test, `insta` snapshots), static-vs-dynamic dispatch, the type-state pattern, comments-vs-docs, and import ordering. Apollo's error-handling and performance-mindset chapters were **not** adapted (this skill's SKILL.md and `microsoft-rust-guidelines` cover those). |
+| Scope      | Idiom/readability rules distilled into `references/idioms.md` — borrowing-vs-cloning, `Copy` sizing, idiomatic `Option`/`Result` flow, iterators-vs-`for`, clippy lint names + `expect`-over-`allow`, testing conventions (one assertion per test, `insta` snapshots), static-vs-dynamic dispatch, the type-state pattern, comments-vs-docs, import ordering, flamegraph profiling (adapted from Chapter 3), and smart pointers / thread-safety (adapted from Chapter 9). Apollo's error-handling chapter was **not** adapted (this skill's SKILL.md and `microsoft-rust-guidelines` cover those). |
 
 The verbatim upstream MIT notice is preserved in
 [`references/ATTRIBUTION.md`](references/ATTRIBUTION.md) (Standard §4.2).

spacecraft-rust-guidelines.zip

@@ -86,6 +86,19 @@ characteristics, and a clear understanding of the trade‑offs involved.
 - `cargo audit` and `cargo deny` to keep dependencies secure and minimal.
 - CI must run fmt, clippy, all tests, doc tests, and at least a sample benchmark.
 
+### Performance Profiling with Flamegraph
+When profiling to identify performance bottlenecks (Standard §3.2):
+- **Installation:** `cargo install flamegraph`
+- **Execution (always use `--release`):**
+  - Run binary: `cargo flamegraph`
+  - Run specific binary: `cargo flamegraph --bin=<name>`
+  - Run unit tests: `cargo flamegraph --unit-test -- <test_name>`
+  - Run benchmarks (e.g., criterion): `cargo flamegraph --bench <name> -- --bench`
+- **Reading a Flamegraph:**
+  - **Y-axis:** Stack depth. The entry point (e.g., `main`) is at the bottom; called functions stack on top.
+  - **X-axis (Width):** Total CPU time/percentage spent on that function or its callees. Wider box = more CPU time.
+  - **Color:** Randomized (has no performance/semantic meaning). Focus on wide boxes and thick stacks.
+
 ## Error Handling & Resilience
 - Libraries: precise error types via `thiserror`, avoid `unwrap()`.
 - Applications: `anyhow`/`eyre` for propagation, with `.context()`.

spacecraft-rust-guidelines/CREDITS.md

@@ -18,8 +18,9 @@ attribution), the upstream MIT notice is preserved verbatim below.
   sizing, idiomatic `Option`/`Result` flow, iterators-vs-`for`, clippy lint names and
   `expect`-over-`allow` discipline, testing conventions (one assertion per test,
   descriptive names, `insta` snapshots), static-vs-dynamic dispatch, the type-state
-  pattern, comments-vs-docs, and import ordering. Apollo's error-handling and
-  performance-mindset chapters were intentionally **not** adapted (covered by this
+  pattern, comments-vs-docs, import ordering, flamegraph profiling details (adapted
+  from Chapter 3), and smart pointers / thread-safety guidelines (adapted from Chapter 9).
+  Apollo's error-handling chapter was intentionally **not** adapted (covered by this
   skill's SKILL.md and by `microsoft-rust-guidelines`).
 
 > Note: the *skill* we adapted from (the `apollographql/skills` repository) is MIT. A

spacecraft-rust-guidelines/SKILL.md

@@ -172,3 +172,34 @@ group_imports = "StdExternalCrate"
 ```
 
 (`group_imports` currently needs `cargo +nightly fmt`.)
+
+## 10. Smart pointers & thread safety
+
+Rust tracks thread safety via compiler-enforced auto-traits:
+- `Send` indicates that ownership of a type can be transferred across thread boundaries.
+- `Sync` indicates that references to a type (`&T`) can be shared safely across threads.
+
+### Smart Pointer Comparison
+
+| Pointer Type | Description | Send / Sync | Use Case |
+| :--- | :--- | :--- | :--- |
+| `&T` | Shared reference | `Send + Sync` (if `T: Sync`) | Immutable shared access. |
+| `&mut T` | Exclusive mutable reference | `Send + Sync` (if `T: Send + Sync`) | Exclusive temporary mutation. |
+| `Box<T>` | Unique heap-allocated pointer | `Send + Sync` (if `T: Send + Sync`) | Owned indirection / recursive types. |
+| `Rc<T>` | Non-atomic reference-counted | **Neither** `Send` nor `Sync` | Shared ownership within a single thread. |
+| `Arc<T>` | Atomic reference-counted | `Send + Sync` (if `T: Send + Sync`) | Shared ownership across multiple threads. |
+| `Cell<T>` | Interior mutability for `Copy` types | `Send` (if `T: Send`), **not** `Sync` | Zero-overhead single-thread mutability. |
+| `RefCell<T>` | Interior mutability (dynamic borrow) | `Send` (if `T: Send`), **not** `Sync` | Single-thread runtime-checked mutation. |
+| `Mutex<T>` | Thread-safe mutual exclusion lock | `Send + Sync` (if `T: Send`) | Shared mutable access across threads. |
+| `RwLock<T>` | Thread-safe readers-writer lock | `Send + Sync` (if `T: Send + Sync`) | Read-heavy shared mutable thread access. |
+
+### Lazy Initialization & One-Time Cells
+
+Avoid complex custom setups with `Option` or unsafe blocks for lazy values. Use standard library cells:
+
+- **Single-Threaded (`std::cell`):**
+  - `OnceCell<T>`: Write-once container for single-threaded deferred initialization.
+  - `LazyCell<T>` (stabilized in Rust 1.80): Lazy value initialized via a closure on first deref.
+- **Thread-Safe / Shared (`std::sync`):**
+  - `OnceLock<T>` (stabilized in Rust 1.70): Thread-safe `OnceCell` for global/shared resources.
+  - `LazyLock<T>` (stabilized in Rust 1.80): Thread-safe `LazyCell` for lazy thread-safe globals.