lazycodex-ai 5.0.0-beta.9 → 5.0.0

package/packages/shared-skills/skills/programming/references/rust/axum-stack.md

@@ -307,19 +307,7 @@ fn init_tracing() {
     fmt().with_env_filter(filter).with_target(false).json().init();
 }
 
-async fn shutdown_signal() {
-    let ctrl_c = async { tokio::signal::ctrl_c().await.expect("ctrl_c handler"); };
-    #[cfg(unix)]
-    let terminate = async {
-        tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate())
-            .expect("signal handler").recv().await;
-    };
-    #[cfg(not(unix))]
-    let terminate = std::future::pending::<()>();
-
-    tokio::select! { _ = ctrl_c => {}, _ = terminate => {} }
-    tracing::info!("shutting down");
-}
+// shutdown_signal(): the Ctrl-C / SIGTERM future from async-tokio.md#graceful-shutdown
 ```
 
 ## Middleware: bearer auth example

package/packages/shared-skills/skills/programming/references/rust/cargo-strict.md

@@ -32,6 +32,8 @@ non_ascii_idents = "deny"
 trivial_numeric_casts = "warn"
 unused_lifetimes = "warn"
 single_use_lifetimes = "warn"
+# every custom cfg is declared here; a typo like cfg(feture = "x") fails the build
+unexpected_cfgs = { level = "deny", check-cfg = ["cfg(loom)"] }
 
 [lints.clippy]
 # Groups
@@ -66,7 +68,9 @@ mutex_atomic = "warn"
 rc_buffer = "warn"
 rc_mutex = "warn"
 exit = "warn"
-allow_attributes_without_reason = "warn"
+allow_attributes = "deny"                 # silence with #[expect(lint, reason)], never #[allow]
+allow_attributes_without_reason = "deny"
+let_underscore_must_use = "deny"          # `let _ = fallible()` drops the error
 dbg_macro = "warn"
 print_stderr = "warn"
 print_stdout = "warn"
@@ -75,10 +79,8 @@ use_debug = "warn"
 # Stylistic relaxations (project-wide opinions only)
 module_name_repetitions = "allow"
 must_use_candidate = "allow"
-missing_errors_doc = "allow"  # we use anyhow::Result with .context() everywhere; doc rule is noisy
 
 # Restriction lints - opt-in soundness rails
-unreachable = "deny"
 mod_module_files = "warn"      # prefer foo.rs over foo/mod.rs
 empty_drop = "warn"
 empty_structs_with_brackets = "warn"
@@ -89,6 +91,8 @@ exhaustive_structs = "warn"
 
 The `priority = -1` trick: group-level levels are weak; specific lints below them win. This lets us deny `unwrap_used` while still allowing `pedantic` group warnings instead of denies.
 
+A lint is silenced only with `#[expect(clippy::lint_name, reason = "...")]` on the smallest item that needs it. Unlike `#[allow]`, `#[expect]` fails the build once the lint stops firing, so stale exceptions cannot pile up; `allow_attributes` and `allow_attributes_without_reason` enforce both halves. `missing_errors_doc` / `missing_panics_doc` stay on (pedantic): public fallible APIs document their `# Errors`.
+
 ## `Cargo.toml` — release profile
 
 ```toml
@@ -116,6 +120,8 @@ opt-level = 1
 overflow-checks = true
 ```
 
+`-C target-cpu=native` and PGO are deployment decisions, not defaults: a `native` binary faults on older CPUs, and PGO only pays with a representative training workload. Apply either only with a before/after measurement.
+
 ## `Cargo.toml` — workspace level
 
 ```toml
@@ -124,15 +130,23 @@ resolver = "3"
 
 [workspace.package]
 edition = "2024"
-rust-version = "1.83"   # bump only when a needed feature lands
+rust-version = "1.85"   # the 2024 edition floor; raise only when a needed feature lands
 license = "Apache-2.0 OR MIT"
 
 [workspace.lints]
 # Then in each member crate:
 # [lints]
 # workspace = true
+
+[workspace.dependencies]
+# one version per dependency; members write `serde = { workspace = true }`
 ```
 
+## Features and build scripts
+
+- **Features are additive.** Enabling a feature never removes an API or changes another feature's behavior, and `--all-features` always builds. Optional dependencies use `dep:` (`serde = ["dep:serde"]`) so no implicit feature leaks. Truly exclusive backends fail loudly: `#[cfg(all(feature = "a", feature = "b"))] compile_error!("features `a` and `b` are mutually exclusive");`.
+- **`build.rs` is deterministic.** Declare every input with `cargo::rerun-if-changed=` / `cargo::rerun-if-env-changed=`, write only under `OUT_DIR`, and never touch the network. A build script that reads undeclared inputs produces stale builds that pass locally and fail in CI.
+
 ## `rustfmt.toml`
 
 ```toml
@@ -156,11 +170,11 @@ Most options come from stable rustfmt. `imports_granularity` and `group_imports`
 # Reduce cognitive load thresholds.
 cognitive-complexity-threshold = 25
 type-complexity-threshold = 250
-too-many-arguments-threshold = 6
+too-many-arguments-threshold = 3   # SKILL.md Smell 2: more than 3 parameters is a smell
 too-many-lines-threshold = 100
 
 # msrv - keeps clippy from suggesting features past our MSRV
-msrv = "1.83"
+msrv = "1.85"
 
 # Avoid `panic` lint complaining about derived Debug impls calling unreachable_unchecked etc.
 allow-unwrap-in-tests = true
@@ -169,7 +183,7 @@ allow-panic-in-tests = true
 allow-dbg-in-tests = true
 allow-print-in-tests = true
 
-# Force named arguments above N params
+# At most 4 single-character bindings in scope
 single-char-binding-names-threshold = 4
 ```
 
@@ -257,6 +271,25 @@ jobs:
       - uses: Swatinem/rust-cache@v2
       - uses: taiki-e/install-action@nextest
       - run: cargo nextest run --all-targets --all-features --workspace
+      - run: cargo test --doc --all-features --workspace   # nextest does not run doctests
+
+  doc:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - env:
+          RUSTDOCFLAGS: "-D warnings"   # broken intra-doc links fail the build
+        run: cargo doc --no-deps --all-features --workspace
+
+  msrv:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@1.85   # = rust-version
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo check --all-features --workspace
 
   miri:
     runs-on: ubuntu-latest
@@ -270,6 +303,9 @@ jobs:
       - env:
           MIRIFLAGS: "-Zmiri-strict-provenance -Zmiri-symbolic-alignment-check"
         run: cargo +nightly miri nextest run --all-features --workspace
+      - env:
+          MIRIFLAGS: "-Zmiri-tree-borrows -Zmiri-strict-provenance -Zmiri-symbolic-alignment-check"
+        run: cargo +nightly miri nextest run --all-features --workspace
 
   machete:
     runs-on: ubuntu-latest
@@ -312,6 +348,6 @@ After every change:
 ```bash
 cargo fmt --all -- --check && \
 cargo clippy --all-targets --all-features -- -D warnings && \
-cargo nextest run && \
+cargo nextest run && cargo test --doc && \
 cargo +nightly miri nextest run    # only if unsafe is involved
 ```

package/packages/shared-skills/skills/programming/references/rust/clap-stack.md

@@ -280,14 +280,19 @@ For automated tests, expose a `--non-interactive` flag and gate all prompts behi
 ## Structured output
 
 ```rust
+use std::io::Write as _;
+
+// `println!` panics when stdout is closed (`mytool | head -1`); writing to a
+// locked handle returns the error instead, so a broken pipe exits cleanly.
+let mut out = std::io::stdout().lock();
 match cli.format {
     OutputFormat::Json => {
-        serde_json::to_writer(std::io::stdout().lock(), &result)?;
-        println!();
+        serde_json::to_writer(&mut out, &result)?;
+        writeln!(out)?;
     }
     OutputFormat::Plain => {
         for row in &result.rows {
-            println!("{}\t{}\t{}", row.a, row.b, row.c);
+            writeln!(out, "{}\t{}\t{}", row.a, row.b, row.c)?;
         }
     }
     OutputFormat::Pretty => {

package/packages/shared-skills/skills/programming/references/rust/concurrency.md

@@ -11,8 +11,8 @@ Highest level          tokio::sync::mpsc / broadcast / watch
                        Arc<Mutex<T>> / Arc<RwLock<T>>
                        (shared mutable state — common, easy to get right)
 
-                       parking_lot::{Mutex, RwLock, Condvar}
-                       (faster sync locks, no poisoning)
+                       std::sync / parking_lot::{Mutex, RwLock, Condvar}
+                       (sync locks for critical sections without .await)
 
                        Atomics (AtomicUsize, AtomicBool, AtomicPtr)
                        (single-word lock-free state)
@@ -43,10 +43,10 @@ Need to share state between tasks?
 │   └── AtomicBool / OnceLock<T> / OnceCell<T>
 ├── State needs mutation across many tasks/threads, cheap critical sections
 │   ├── async context           → tokio::sync::Mutex<T>
-│   └── sync context (no .await held) → parking_lot::Mutex<T>
+│   └── sync context (no .await held) → std::sync::Mutex<T> / parking_lot::Mutex<T>
 ├── State needs mutation, many readers, few writers
 │   ├── async context           → tokio::sync::RwLock<T>
-│   └── sync context            → parking_lot::RwLock<T>
+│   └── sync context            → std::sync::RwLock<T> / parking_lot::RwLock<T>
 └── State is a custom lock-free primitive (channels, hazard pointers)
     └── UnsafeCell + atomics + loom-tested + miri-tested + a co-author
 ```
@@ -83,29 +83,20 @@ let n = c.load(Ordering::Relaxed);
 
 ### Publish-then-load pattern
 
+Write data, then `store(true, Release)` a flag; a reader that `load(Acquire)`s `true` is guaranteed to see the data written before the store. Do not hand-roll it around a `static mut` (the 2024 edition denies references to one, and every access is `unsafe`): `OnceLock<T>` is exactly this pattern behind a safe API.
+
 ```rust
-static READY: AtomicBool = AtomicBool::new(false);
-static mut DATA: Option<Config> = None;
-
-// Producer thread:
-unsafe { DATA = Some(load_config()); }
-READY.store(true, Ordering::Release);
-
-// Consumer thread:
-if READY.load(Ordering::Acquire) {
-    // SAFETY: producer's Release pairs with our Acquire; if we see READY=true,
-    // we are guaranteed to also see the DATA write that happened-before it.
-    let cfg = unsafe { DATA.as_ref().unwrap() };
-}
-```
+static CONFIG: std::sync::OnceLock<Config> = std::sync::OnceLock::new();
 
-This is the canonical Release/Acquire pattern. **Use `OnceLock<Config>` instead** in new code — it encapsulates exactly this with safe API.
+// Producer, once:  CONFIG.set(cfg) returns Err(cfg) if already set.
+// Consumer:        CONFIG.get() is Some only after the publishing set completed.
+```
 
 ## Std vs parking_lot vs tokio for locks
 
 | | std::sync::Mutex | parking_lot::Mutex | tokio::sync::Mutex |
 |---|---|---|---|
-| Speed | Slowest (OS futex direct) | Fastest (smarter parking) | Slow (await-aware) |
+| Speed | Fast (futex-based since 1.62) | Fast (adaptive spinning, smaller) | Slower (await-aware) |
 | Poisoning | Yes (`PoisonError`) | No | No |
 | Hold across `.await` | Dangerous (deadlock under current-thread runtime) | Dangerous | Safe |
 | Drop guard releases | Yes | Yes | Yes |
@@ -115,17 +106,17 @@ This is the canonical Release/Acquire pattern. **Use `OnceLock<Config>` instead*
 
 **Rule of thumb:**
 
-- Hot, short critical section, no await inside → `parking_lot::Mutex`.
+- Short critical section, no await inside → `std::sync::Mutex`, or `parking_lot::Mutex` when the crate already depends on it or you want no poisoning. Neither is universally faster; measure before switching for speed.
 - Shared state held across `.await` → `tokio::sync::Mutex`.
 - Static init / app config → `OnceLock` or `LazyLock`.
-- Avoid `std::sync::Mutex` for new code; the poisoning behavior is more annoying than useful and `parking_lot` is strictly faster.
+- A `PoisonError` from `std` means another thread panicked mid-update; propagate it or recover the data deliberately with `into_inner()`, never `unwrap()` it away.
 
 ### Common deadlock — async + sync mutex
 
 ```rust
-let m = std::sync::Mutex::new(0u64);
-let guard = m.lock().unwrap();
-something_async().await;  // ❌ guard is held across await
+let m = parking_lot::Mutex::new(0u64);
+let mut guard = m.lock();
+something_async().await;  // WRONG: guard is held across await
 *guard += 1;
 ```
 
@@ -135,7 +126,7 @@ Fix:
 
 ```rust
 {
-    let mut guard = m.lock().unwrap();
+    let mut guard = m.lock();
     *guard += 1;
 }  // guard released
 something_async().await;
@@ -172,12 +163,12 @@ tx.send(new_config)?;
 // Consumer:
 loop {
     rx.changed().await?;
-    let cfg = rx.borrow();
-    apply(&cfg);
+    let cfg = rx.borrow_and_update().clone(); // release the read lock before any .await
+    apply(&cfg).await;
 }
 ```
 
-Receivers see only the latest value (older updates are dropped). Perfect for config reload, leadership changes, "current time" propagation.
+Receivers see only the latest value (older updates are dropped). Perfect for config reload, leadership changes, "current time" propagation. The `borrow()` guard blocks the sender while held; never keep it across an `.await`.
 
 ### Broadcast — fanout queue
 
@@ -209,10 +200,11 @@ Bound concurrent operations:
 
 ```rust
 let sem = Arc::new(tokio::sync::Semaphore::new(10));
+let mut set = tokio::task::JoinSet::new();
 
 for task in tasks {
-    let permit = sem.clone().acquire_owned().await?;
-    tokio::spawn(async move {
+    let permit = Arc::clone(&sem).acquire_owned().await?;
+    set.spawn(async move {
         let _hold = permit;       // released when task exits
         process(task).await
     });
@@ -232,13 +224,14 @@ A semaphore with `permits=1` is a mutex. Use the actual `Mutex` for that — cle
 
 ```rust
 let shared = Arc::new(BigData::new());
+let mut set = tokio::task::JoinSet::new();
 for _ in 0..workers {
-    let s = shared.clone();
-    tokio::spawn(async move { use_data(&s).await });
+    let s = Arc::clone(&shared);
+    set.spawn(async move { use_data(&s).await });
 }
 ```
 
-`Arc::clone(&s)` is just a reference-count increment; the data is not copied.
+`Arc::clone(&s)` is just a reference-count increment; the data is not copied. Write it as `Arc::clone(&x)`, never `x.clone()` (`clone_on_ref_ptr`), so a deep clone never hides behind the same spelling.
 
 **Do not clone in hot loops** if you can pass a reference. `&Arc<T>` is fine to pass; only call `Arc::clone` when you need to move ownership across a thread/task boundary.
 
@@ -247,27 +240,25 @@ for _ in 0..workers {
 ## Once-init primitives
 
 ```rust
-use std::sync::{OnceLock, LazyLock};
-
-// Lazy initialization, computed on first read
-static CONFIG: LazyLock<Config> = LazyLock::new(|| Config::load_from_env().unwrap());
+use std::sync::LazyLock;
 
-fn get_config() -> &'static Config {
-    &CONFIG
-}
-
-// One-shot publication, set explicitly
-static DB: OnceLock<sqlx::PgPool> = OnceLock::new();
+// Lazy initialization of an infallible value, computed on first read
+static WORD_RE: LazyLock<regex::Regex> = LazyLock::new(|| {
+    #[expect(clippy::expect_used, reason = "literal pattern; covered by a unit test")]
+    regex::Regex::new(r"\w+").expect("valid regex literal")
+});
 
 #[tokio::main]
-async fn main() {
-    let pool = sqlx::PgPool::connect(&env_url()).await.unwrap();
-    DB.set(pool).expect("only set once");
-    // Now everywhere: DB.get().unwrap()
+async fn main() -> anyhow::Result<()> {
+    // Fallible setup happens in main, where `?` reports it; pass the result down
+    // as a parameter instead of reaching for a global.
+    let config = Config::load_from_env()?;
+    let pool = sqlx::PgPool::connect(&config.database_url).await?;
+    run(&config, &pool).await
 }
 ```
 
-`OnceLock` is `std::sync` and stable. `LazyLock` is in `std::sync` since 1.80. Avoid the older `once_cell` crate for new code.
+`LazyLock` runs its closure on first access, where no caller can handle an error, so it holds only values that cannot fail at runtime. `OnceLock` and `LazyLock` are in `std::sync` (1.70 / 1.80); avoid `once_cell` and `lazy_static!` for new code.
 
 ## Loom — model-checking lock-free code
 
@@ -306,8 +297,8 @@ mod loom_tests {
     fn concurrent_push_pop_preserves_order() {
         loom::model(|| {
             let queue = Arc::new(MyQueue::new());
-            let q1 = queue.clone();
-            let q2 = queue.clone();
+            let q1 = Arc::clone(&queue);
+            let q2 = Arc::clone(&queue);
             let h1 = thread::spawn(move || q1.push(1));
             let h2 = thread::spawn(move || q2.pop());
             h1.join().unwrap();
@@ -324,7 +315,7 @@ Run:
 RUSTFLAGS="--cfg loom" cargo test --release -- --test-threads 1
 ```
 
-Loom explores every legal scheduling of the threads, including those a real scheduler would rarely produce. If your code has a race, loom will find it deterministically.
+Loom systematically explores the thread interleavings its model allows (bounded by `LOOM_MAX_PREEMPTIONS`), including those a real scheduler would rarely produce, and replays a failing schedule deterministically. It is strong evidence within that bound, not a proof over unbounded executions.
 
 ### Loom's limits
 
@@ -333,6 +324,29 @@ Loom explores every legal scheduling of the threads, including those a real sche
 - Doesn't catch UB inside `unsafe` blocks the way miri does. **Run both: miri for memory safety, loom for thread schedules.**
 - Doesn't handle `tokio` directly. Loom replaces stdlib's sync primitives; tokio's are independent.
 
+## Scoped threads and per-thread state
+
+For a fixed number of short-lived threads that borrow local data, `std::thread::scope` joins every thread before it returns, so no `Arc` or `'static` bound is needed:
+
+```rust
+let (left, right) = data.split_at(data.len() / 2);
+let (a, b) = std::thread::scope(|s| {
+    let a = s.spawn(|| checksum(left));
+    let b = s.spawn(|| checksum(right));
+    (a.join(), b.join())
+});
+// a and b are Result<_, panic payload>: a panicked thread surfaces here
+```
+
+For data-parallel work over a collection, `rayon`'s `par_iter()` is simpler. Per-thread scratch state (a reusable buffer, a per-thread RNG) is `thread_local!` with `Cell` / `RefCell`, never a `static mut`:
+
+```rust
+thread_local! {
+    static SCRATCH: std::cell::RefCell<Vec<u8>> = const { std::cell::RefCell::new(Vec::new()) };
+}
+SCRATCH.with_borrow_mut(|buf| { buf.clear(); encode_into(buf, msg) });
+```
+
 ## Send and Sync — what they mean
 
 - `T: Send` — `T` can be moved between threads safely.

package/packages/shared-skills/skills/programming/references/rust/libraries.md

@@ -4,10 +4,10 @@ The opinionated, audited-in-prod stack for 2026 Rust. Every entry has a one-line
 
 ## Async runtime — `tokio`
 
-The default. Use `tokio` for new work. Multi-thread runtime unless you have a measured reason to go single-thread.
+The default. Use `tokio` for new work. Multi-thread runtime with the default worker count unless you have a measured reason otherwise ([async-tokio.md](async-tokio.md)).
 
 ```rust
-#[tokio::main(flavor = "multi_thread", worker_threads = 8)]
+#[tokio::main]
 async fn main() -> anyhow::Result<()> {
     tracing_subscriber::fmt::init();
     run().await
@@ -49,7 +49,7 @@ pub enum ParseError {
 }
 ```
 
-`#[non_exhaustive]` on enums prevents downstream `match` from breaking when you add variants. `#[error(transparent)]` on a wrapper variant forwards Display + cause to the inner error.
+`#[non_exhaustive]` on enums prevents downstream `match` from breaking when you add variants. `#[error(transparent)]` on a wrapper variant forwards Display + cause to the inner error. Keep the cause chain: a variant that wraps another error marks it `#[from]` or `#[source]` so `anyhow`'s `{error:#}` and reporters print every layer. Error messages are lowercase with no trailing period, because they get composed into `context: cause` chains.
 
 ## CLI — `clap` with derive
 
@@ -108,7 +108,7 @@ fn init_tracing() {
         .init();
 }
 
-#[instrument(skip(db), fields(user_id = %user.id))]
+#[instrument(skip_all, fields(user_id = %user.id))]
 async fn process_user(db: &Pool, user: &User) -> anyhow::Result<()> {
     info!("processing user");
     if user.is_banned() {
@@ -122,6 +122,8 @@ async fn process_user(db: &Pool, user: &User) -> anyhow::Result<()> {
 
 Replace `println!` with `info!`/`warn!`/`error!`. Replace `eprintln!` with `tracing::error!`.
 
+`#[instrument]` records every argument it does not skip with `Debug`, so a `&User` argument lands in the span whole, PII included. Default to `skip_all` and whitelist fields explicitly, as above; secrets live in `secrecy::SecretString` so a stray `?value` prints `[REDACTED]`. A **library** emits `tracing` events and spans but never installs a subscriber (`tracing_subscriber::…::init()`): only the binary chooses the output format and filter.
+
 ## Error reporting (binaries) — `color-eyre`
 
 For binary `main()`, hook `color-eyre` to give pretty panics + nice `Result` printing:
@@ -141,19 +143,29 @@ Library code stays on `anyhow`/`thiserror`. `color-eyre` is purely a display lay
 The default for any data crossing a process boundary (file, network, IPC, database column).
 
 ```rust
-#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+// Input we own the schema of (config, our own API): reject typos.
+#[derive(Debug, serde::Deserialize)]
 #[serde(deny_unknown_fields, rename_all = "snake_case")]
-pub struct ApiResponse {
+pub struct CreateUser {
+    pub email: Email,                       // validated newtype, see type-state.md
+    #[serde(default)]
+    pub display_name: Option<String>,
+}
+
+// Payload a newer peer may extend: keep unknown fields instead of rejecting them.
+#[derive(Debug, serde::Serialize, serde::Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub struct Event {
     pub user_id: UserId,
     pub created_at: jiff::Timestamp,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub display_name: Option<String>,
     #[serde(flatten)]
     pub extra: HashMap<String, serde_json::Value>,
 }
 ```
 
-`deny_unknown_fields` catches typos in inputs. `rename_all = "snake_case"` aligns with REST/JSON conventions while keeping idiomatic Rust field names. `#[serde(flatten)]` for forward-compatible extra fields.
+Choose per type: `deny_unknown_fields` for input whose schema you own (a typoed config key fails loudly), `#[serde(flatten)]` catch-all for payloads a newer peer may extend. The two do not combine: serde does not support `deny_unknown_fields` on a struct with a `flatten` field. `rename_all` matches the wire schema you are given, not a house style. Enums get an explicit representation (`#[serde(tag = "type")]`, or `tag` + `content`); `#[serde(untagged)]` tries variants in order and reports only "did not match any variant", so reserve it for shapes that are unambiguous by construction. Validated newtypes deserialize through their checked constructor with `#[serde(try_from = "...")]` ([type-state.md](type-state.md)). For a field whose wire format differs from its Rust type (a duration as seconds, a timestamp as a string), use `#[serde(with = "module")]` or the type's own serde feature instead of a hand-written parallel struct.
 
 Alternatives:
 - `serde_yaml` (YAML — note: YAML's "deserialize anything" surface is a security trap; prefer JSON/TOML where possible)
@@ -306,7 +318,7 @@ type WorldPoint  = Point2D<f32, WorldSpace>;
 let cursor: ScreenPoint = Point2D::new(120.0, 240.0);
 let player: WorldPoint  = Point2D::new(3.5, 1.2);
 
-// let mistake = cursor + player; // ❌ type error
+// let mistake = cursor + player; // compile error: different coordinate spaces
 ```
 
 Generalize the pattern to your own domains (see `references/type-state.md`).
@@ -350,11 +362,12 @@ fn serializes_well() {
 Stable Rust friendly (no nightly `#[bench]`).
 
 ```rust
-use criterion::{black_box, criterion_group, criterion_main, Criterion};
+use criterion::{criterion_group, criterion_main, Criterion};
+use std::hint::black_box;
 
 fn bench_parse(c: &mut Criterion) {
-    let input = std::fs::read_to_string("samples/large.txt").unwrap();
-    c.bench_function("parse_large", |b| b.iter(|| parse(black_box(&input))));
+    let input = include_str!("../samples/large.txt");
+    c.bench_function("parse_large", |b| b.iter(|| parse(black_box(input))));
 }
 
 criterion_group!(benches, bench_parse);
@@ -363,6 +376,8 @@ criterion_main!(benches);
 
 Run with `cargo bench`. HTML reports under `target/criterion/`. Pair with `cargo bench -- --save-baseline main` then `--baseline main` for comparison.
 
+**Profile first, then optimize.** A change made for speed ships with its measurement: the benchmark or profile (`cargo flamegraph`, `samply`) that located the hot spot, and the before/after numbers on a representative input. Source shape alone proves nothing: iterator chains, `#[inline]`, bounds checks, and `Iterator::chain` usually compile to the same code as the "optimized" rewrite. Attributes like `#[inline(always)]` and `#[cold]` go in only when a measurement shows they help, and the `std::hint::black_box` above keeps the compiler from deleting the work being timed.
+
 ## Concurrency model — `loom`
 
 For lock-free or atomic-heavy code (channels, refcounts, hazard pointers). See `references/concurrency.md` for the full pattern.
@@ -378,7 +393,7 @@ let s: &str = bump.alloc_str("hello");
 // All allocations freed at once when `bump` drops.
 ```
 
-For parser nodes, AST construction, per-request scratch. Outperforms heap allocation for short-lived owned data by an order of magnitude.
+For parser nodes, AST construction, per-request scratch: one bump pointer per allocation and one free for the whole arena. Measure the gain on your workload before claiming one.
 
 ## Web client (browser, WASM-bound) — `gloo` ecosystem
 
@@ -386,26 +401,21 @@ If targeting WASM browser, use `gloo-net` for fetch and `gloo-storage` for local
 
 ## Lazy statics — `std::sync::LazyLock` (since 1.80)
 
-```rust
-use std::sync::LazyLock;
-static CONFIG: LazyLock<Config> = LazyLock::new(|| Config::load_from_env().unwrap());
-```
-
-Avoid `lazy_static!` (macro-heavy, predates std), `once_cell` (now in std as `LazyLock`/`OnceLock`).
+`LazyLock` for values that cannot fail at runtime (a compiled literal regex, a static table); fallible setup such as loading config belongs in `main`, where `?` reports it. Pattern → [concurrency.md](concurrency.md#once-init-primitives). Avoid `lazy_static!` (macro-heavy, predates std), `once_cell` (now in std as `LazyLock`/`OnceLock`).
 
-## Hash maps — `std::collections::HashMap` + `ahash` for hot paths
+## Hash maps — `std::collections::HashMap`, a faster hasher only where measured
 
 ```rust
 use std::collections::HashMap;
-use ahash::RandomState;
 
-type FastMap<K, V> = HashMap<K, V, RandomState>;
+// Keys come from trusted code and a profile shows hashing is hot:
+type FastMap<K, V> = HashMap<K, V, foldhash::fast::RandomState>;
 let mut counters: FastMap<String, u64> = FastMap::default();
 ```
 
-`HashMap` defaults to SipHash (DoS-resistant). For internal hot loops where you trust the keys, `ahash` is 2-5x faster.
+std's default hasher (SipHash-1-3 with a random key) resists hash-flooding from attacker-chosen keys; keep it for any map fed by input. For trusted keys on a measured hot path, `foldhash` (the hasher `hashbrown` defaults to) or `rustc-hash` (`FxHashMap`, integer keys) are faster; `rustc-hash` is predictable, so never feed it untrusted keys. Update-or-insert goes through `map.entry(key).or_insert(..)` / `.and_modify(..)`, one lookup instead of `get` + `insert`.
 
-For sorted iteration, use `BTreeMap`. For small keys with known small N, `Vec<(K, V)>` may beat both.
+For sorted iteration, use `BTreeMap`; for insertion order that is part of the contract, `indexmap::IndexMap`. For small keys with known small N, `Vec<(K, V)>` may beat both.
 
 ## File I/O — `tokio::fs` (async) or `std::fs` (sync utility)
 
@@ -413,7 +423,7 @@ For sorted iteration, use `BTreeMap`. For small keys with known small N, `Vec<(K
 let contents = tokio::fs::read_to_string("data.json").await?;
 ```
 
-For large files: `tokio::fs::File` + `tokio::io::BufReader`. For random access, `memmap2` (with the unsafe-discipline wrappers).
+For large files: `tokio::fs::File` + `tokio::io::BufReader`. For random access, `memmap2` (with the unsafe-discipline wrappers). Many small reads or writes (line by line, record by record) go through `BufReader` / `BufWriter`, sync or async. Call `flush()` on a `BufWriter` before dropping it: `Drop` flushes too but has to discard the error.
 
 ## Decision tree
 

package/packages/shared-skills/skills/programming/references/rust/macros.md

@@ -0,0 +1,63 @@
+# Macros
+
+A macro is the last rung of the ladder: reach for one only when a function, a generic, or a trait cannot express the thing (variadic input, new syntax, generating items, compile-time code from a type's shape). Macros cost compile time, error-message quality, and IDE support.
+
+## `macro_rules!`
+
+```rust
+/// Builds a `HashMap` from `key => value` pairs.
+#[macro_export]
+macro_rules! hashmap {
+    ($($key:expr => $value:expr),* $(,)?) => {{
+        let mut map = $crate::__private::HashMap::new();
+        $( map.insert($key, $value); )*
+        map
+    }};
+}
+
+#[doc(hidden)]
+pub mod __private {
+    pub use std::collections::HashMap;
+}
+```
+
+- **`$crate::` for every item of the defining crate.** Callers may rename your crate or lack the import; `$crate` always resolves to the crate that defined the macro.
+- **Narrowest fragment specifier.** `expr`, `ty`, `ident`, `path`, `pat`, `literal` give callers real error messages and parse precedence correctly; `tt` accepts anything and defers the error to a confusing expansion.
+- **Helpers the expansion needs** live in a `#[doc(hidden)] pub mod __private` and are reached through `$crate::__private::...`; they are not API.
+- **`#[macro_export]` puts the macro at the crate root** (`my_crate::hashmap!`). Import it by path (`use my_crate::hashmap;`), not `#[macro_use] extern crate`.
+- Hygiene covers local variables, not items or method calls: a name the expansion uses unqualified resolves at the call site. Qualify everything.
+
+## Procedural macros
+
+A proc macro lives in its own crate (`[lib] proc-macro = true`), which can export nothing else. Ship it as `my-crate-derive` and re-export it from `my-crate` so users depend on one crate and the macro's generated code can refer to `::my_crate::...`.
+
+```rust
+use proc_macro::TokenStream;
+use quote::{format_ident, quote};
+use syn::{parse_macro_input, Data, DeriveInput};
+
+#[proc_macro_derive(Builder)]
+pub fn derive_builder(input: TokenStream) -> TokenStream {
+    let input = parse_macro_input!(input as DeriveInput);
+    expand(&input).unwrap_or_else(syn::Error::into_compile_error).into()
+}
+
+fn expand(input: &DeriveInput) -> syn::Result<proc_macro2::TokenStream> {
+    let Data::Struct(_) = &input.data else {
+        return Err(syn::Error::new_spanned(&input.ident, "Builder supports structs only"));
+    };
+    let name = &input.ident;
+    let builder = format_ident!("{}Builder", name); // quote! cannot paste identifiers
+    Ok(quote! {
+        impl #name {
+            pub fn builder() -> #builder { #builder::default() }
+        }
+    })
+}
+```
+
+- Parse with `syn`, generate with `quote`, work in `proc_macro2` types so the logic is unit-testable outside the compiler.
+- **Never panic.** Report problems as `syn::Error::new_spanned(the_offending_tokens, "...")` and return `into_compile_error()`: the compiler underlines the exact input the user must change. A panic produces one message at the derive site with no location.
+- Build new identifiers with `format_ident!`; `quote!` has no token pasting (`#name##Builder` is not valid).
+- Generated code uses fully qualified paths (`::core::option::Option`, `::my_crate::Trait`) so it compiles regardless of what the caller imported or shadowed.
+- Test expansions with `trybuild` (pass and compile-fail cases, including the error message spans) rather than by asserting on generated token text.