lazycodex-ai 5.0.0-beta.85 → 5.0.0-beta.87

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.

package/packages/shared-skills/skills/programming/references/rust/one-liners.md

@@ -124,9 +124,9 @@ rust-script --build-only --base-path . ./script.rs
 
 This drops a `target/` next to the script with the prebuilt binary.
 
-## `cargo-script` (RFC 3424, stable since Rust 1.85)
+## `cargo-script` (RFC 3424, nightly-only)
 
-The official replacement that landed in cargo proper. Same idea, slightly different syntax:
+The official replacement being built into cargo. Same idea, slightly different syntax:
 
 ```rust
 #!/usr/bin/env -S cargo +nightly -Zscript
@@ -140,6 +140,8 @@ dependencies:
   reqwest = { version = "0.12", features = ["blocking"] }
 ---
 
+use anyhow::Context as _;
+
 fn main() -> anyhow::Result<()> {
     let url = std::env::args().nth(1).context("url required")?;
     println!("{}", reqwest::blocking::get(&url)?.text()?.len());
@@ -147,7 +149,7 @@ fn main() -> anyhow::Result<()> {
 }
 ```
 
-Status as of 2026-05: stabilization in progress. Use `rust-script` for production now, migrate when `cargo script` is stable everywhere your tools live.
+Stable cargo (1.97) still rejects `-Zscript` and refuses to run a `.rs` file directly. Use `rust-script` now; migrate once `cargo script` reaches the stable channel of every toolchain your scripts run on.
 
 ## Strict mode for scripts
 

package/packages/shared-skills/skills/programming/references/rust/proptest-insta.md

@@ -15,6 +15,14 @@ Two test types every Rust project should have alongside unit tests. Proptest hun
 
 Use all three. They cover different bug classes.
 
+## Where tests live
+
+- **Unit tests of private behavior**: `#[cfg(test)] mod tests { use super::*; ... }` at the bottom of the module they test.
+- **Public-API behavior**: `tests/*.rs`. Each file is a separate crate that sees only `pub` items, so it fails when the public contract breaks, not when an internal changes.
+- **Examples in rustdoc**: doctests. They compile and run, so a documented example that drifts from the API fails the build. `cargo nextest run` skips them; the gate runs `cargo test --doc` too. Write examples with `?` and hide setup behind `# ` lines ([api-design.md](api-design.md#rustdoc-sections)).
+- **Panics**: `#[should_panic(expected = "...")]` only when panicking is the documented contract (an out-of-bounds index on a slice-like type). An invalid input that returns `Err` is asserted as that `Err` value.
+- **Environment and globals**: `std::env::set_var` is `unsafe` in the 2024 edition because another thread may read the environment at the same moment, and tests run in parallel threads. Inject configuration as a parameter instead of mutating process state; a test that must touch the real environment runs in its own process (`tests/` binary, or nextest's process-per-test).
+
 ## Proptest — setup
 
 `Cargo.toml`:

package/packages/shared-skills/skills/programming/references/rust/type-state.md

@@ -92,9 +92,8 @@ Now:
 ```rust
 let distance: Quantity<Meters> = Quantity::new(100.0);
 let height: Quantity<Feet> = Quantity::new(50.0);
-let combined = distance + height; // ❌ compile error
-let combined = distance + height.to_feet().to_meters_oops(); // ❌ no such method
-let combined = distance + distance; // ✅
+let combined = distance + height;   // compile error: Quantity<Meters> + Quantity<Feet>
+let combined = distance + distance; // compiles
 ```
 
 The agent cannot accidentally mix units. Refactors that change a quantity's underlying unit are caught at compile time everywhere the type flows.
@@ -109,12 +108,13 @@ pub struct ByteOffset(pub u32);
 pub struct CharOffset(pub u32);
 
 impl ByteOffset {
-    pub fn add(self, delta: u32) -> Self { Self(self.0 + delta) }
+    pub fn checked_add(self, delta: u32) -> Option<Self> { self.0.checked_add(delta).map(Self) }
 }
 
 // Converting between them is a function on the actual text.
 pub fn byte_to_char(text: &str, byte: ByteOffset) -> Option<CharOffset> {
-    text.get(..byte.0 as usize).map(|prefix| CharOffset(prefix.chars().count() as u32))
+    let prefix = text.get(..usize::try_from(byte.0).ok()?)?;
+    u32::try_from(prefix.chars().count()).ok().map(CharOffset)
 }
 ```
 
@@ -193,6 +193,41 @@ impl ProjectRel {
 
 The agent's path-handling code now distinguishes between project-relative and home-relative paths at the type level. A function taking `ProjectRel` cannot be called with a `HomeRel`.
 
+### Validated Newtypes — Parse Once, Every Path
+
+A newtype that carries an invariant has exactly one way in: a fallible constructor over a private field. Every other entry point (`FromStr`, serde, `TryFrom`) routes through it, so no path can build an unchecked value.
+
+```rust
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+#[serde(try_from = "String", into = "String")]
+pub struct Email(String); // private field: no `Email(raw)` from outside
+
+#[derive(Debug, thiserror::Error)]
+#[error("not an email address: {0:?}")]
+pub struct InvalidEmail(String);
+
+impl TryFrom<String> for Email {
+    type Error = InvalidEmail;
+    fn try_from(raw: String) -> Result<Self, Self::Error> {
+        match raw.split_once('@') {
+            Some((user, host)) if !user.is_empty() && host.contains('.') => Ok(Self(raw)),
+            _ => Err(InvalidEmail(raw)),
+        }
+    }
+}
+
+impl std::str::FromStr for Email {
+    type Err = InvalidEmail;
+    fn from_str(raw: &str) -> Result<Self, Self::Err> { Self::try_from(raw.to_owned()) }
+}
+
+impl From<Email> for String {
+    fn from(email: Email) -> Self { email.0 }
+}
+```
+
+`#[serde(try_from = "String")]` makes deserialization run the same check, so JSON cannot smuggle in an invalid `Email`. Never add `impl From<String> for Email`: an infallible conversion into an invariant-bearing type is a bypass.
+
 ## Type-State State Machines
 
 Encode the lifecycle of a value as a sequence of types. Each transition consumes the previous state and returns the next.
@@ -313,6 +348,7 @@ Downstream code cannot add new `impl Renderer for Whatever` because they cannot
 ## NonEmpty Collections
 
 ```rust
+#[derive(Debug)]
 pub struct NonEmptyVec<T> {
     head: T,
     tail: Vec<T>,
@@ -322,16 +358,16 @@ pub struct NonEmptyVec<T> {
 #[error("vector was empty")]
 pub struct Empty;
 
+#[expect(clippy::len_without_is_empty, reason = "never empty by construction")]
 impl<T> NonEmptyVec<T> {
-    pub fn try_from_vec(mut v: Vec<T>) -> Result<Self, Empty> {
-        if v.is_empty() { return Err(Empty); }
-        let tail = v.split_off(1);
-        let head = v.into_iter().next().expect("checked non-empty");
-        Ok(Self { head, tail })
+    pub fn try_from_vec(v: Vec<T>) -> Result<Self, Empty> {
+        let mut items = v.into_iter();
+        let Some(head) = items.next() else { return Err(Empty) };
+        Ok(Self { head, tail: items.collect() })
     }
 
-    pub fn first(&self) -> &T { &self.head }
-    pub fn len(&self) -> usize { self.tail.len() + 1 }
+    pub const fn first(&self) -> &T { &self.head }
+    pub fn len(&self) -> usize { self.tail.len().saturating_add(1) }
 }
 ```
 
@@ -343,6 +379,8 @@ Functions taking `NonEmptyVec<T>` cannot receive an empty vector. The `first()`
 - When the wrapper does not change behavior or invariants vs. the underlying type (e.g., a `struct Count(u32)` that is only ever used in one struct).
 - When `From`/`Into` conversions would be ergonomic but would defeat the purpose (if you find yourself wanting `impl From<UserId> for Uuid`, you do not want a newtype - you want a type alias).
 
+A domain newtype never implements `Deref` to its inner type: that re-exposes every method the wrapper exists to fence off, and method resolution silently picks the inner one. `Deref` is for pointer-like wrappers (`Box`, guards, smart handles); a newtype exposes the operations it means to allow.
+
 The cost of a newtype is one tuple struct + the impls you need. The break-even is around three uses across different functions, or any use that crosses an API boundary.
 
 ## When NOT to Use Type-State