@booklib/skills 1.3.1 → 1.4.0

package/skills/rust-in-action/SKILL.md

@@ -0,0 +1,290 @@
+---
+name: rust-in-action
+description: >
+  Write and review Rust code using systems programming concepts from "Rust in Action"
+  by Tim McNamara. Covers language foundations, ownership and borrowing, smart pointers,
+  data representation (bits, endianness, floats), memory (stack/heap/virtual), file I/O,
+  networking (TCP/HTTP), concurrency (threads/closures), and OS-level programming.
+  Use when writing systems-level Rust, working with binary data, raw pointers, file formats,
+  network protocols, or low-level memory. Trigger on: "Rust", "systems programming",
+  "smart pointers", "endianness", "bit manipulation", "TCP", "raw pointers", "serde",
+  "borrow checker", "ownership", "concurrency", "kernel", ".rs files", "cargo".
+---
+
+# Rust in Action Skill
+
+Apply the systems programming practices from Tim McNamara's "Rust in Action" to review existing code and write new Rust. This skill operates in two modes: **Review Mode** (analyze code for violations of Rust idioms and systems programming correctness) and **Write Mode** (produce safe, idiomatic, systems-capable Rust from scratch).
+
+The key differentiator of this book: Rust is taught through real systems — a CPU simulator, key-value store, NTP client, raw TCP stack, and OS kernel. Practices focus on correctness at the hardware boundary, not just language syntax.
+
+## Reference Files
+
+- `practices-catalog.md` — Before/after examples for ownership, smart pointers, bit ops, I/O, networking, concurrency, error wrapping, and state machines
+
+## How to Use This Skill
+
+**Before responding**, read `practices-catalog.md` for the topic at hand. For ownership/borrowing issues read the ownership section. For systems/binary data read the data section. For a full review, read all sections.
+
+---
+
+## Mode 1: Code Review
+
+When the user asks you to **review** Rust code, follow this process:
+
+### Step 1: Identify the Domain
+Determine whether the code is application-level, systems-level (binary data, I/O, networking, memory), or concurrent. The review focus shifts accordingly.
+
+### Step 2: Analyze the Code
+
+Check these areas in order of severity:
+
+1. **Ownership & Borrowing** (Ch 4): Unnecessary `.clone()`? Value moved when a borrow would suffice? Use references where full ownership is not required.
+2. **Smart Pointer Choice** (Ch 6): Is the right pointer type used? `Box<T>` for heap, `Rc<T>` for single-thread shared, `Arc<T>` for multi-thread shared, `RefCell<T>` for interior mutability (single-thread), `Mutex<T>` for interior mutability (multi-thread). `Cow<T>` when data is usually read but occasionally mutated.
+3. **Error Handling** (Ch 3, 8): `.unwrap()` or `.expect()` where `?` belongs? For library code, define a custom error type that wraps downstream errors via `From` impl. Never leak internal error types across the public API boundary.
+4. **Binary Data & Endianness** (Ch 5, 7): Are integer byte representations explicit? Use `to_le_bytes()` / `from_le_bytes()` / `to_be_bytes()`. Validate with checksums when writing binary formats. Use `serde` + `bincode` for structured serialization.
+5. **Memory** (Ch 6): Is `unsafe` minimized? Raw pointer use must be bounded by a safe abstraction. Stack vs heap allocation: prefer stack; use `Box` only when size is unknown at compile time or you need heap lifetime.
+6. **File & I/O** (Ch 7): Use `BufReader`/`BufWriter` for large files. Handle `ENOENT`, `EPERM`, `ENOSPC` distinctly — don't collapse I/O errors to strings. Use `std::fs::Path` for type-safe path handling.
+7. **Networking** (Ch 8): TCP state is implicit in OS — model explicit state machines with enums. Use trait objects (`Box<dyn Trait>`) only when heterogeneous runtime dispatch is needed. Prefer `impl Trait` for static dispatch.
+8. **Concurrency** (Ch 10): Closures passed to threads must be `'static` or use `move`. Shared mutable state needs `Arc<Mutex<T>>`. Use channels for message passing over shared state. Thread pool patterns over spawning one thread per task.
+9. **Time** (Ch 9): Don't use `std::time::SystemTime` for elapsed measurement — it can go backwards. Use `std::time::Instant` for durations. For network time, NTP requires epoch conversion (NTP epoch: 1900 vs Unix: 1970 — offset 70 years = 2_208_988_800 seconds).
+10. **Idioms**: Iterator adapters over manual loops. `for item in &collection` not `for i in 0..collection.len()`. `if let`/`while let` for single-variant matching. Exhaustive `match` — no silent wildcard arms.
+
+### Step 3: Report Findings
+For each issue, report:
+- **Chapter reference** (e.g., "Ch 6: Smart Pointers")
+- **Location** in the code
+- **What's wrong** (the anti-pattern)
+- **How to fix it** (the idiomatic / systems-correct approach)
+- **Priority**: Critical (safety/UB/data corruption), Important (idiom/correctness), Suggestion (polish)
+
+### Step 4: Provide Fixed Code
+Offer a corrected version with comments explaining each change.
+
+---
+
+## Mode 2: Writing New Code
+
+When the user asks you to **write** new Rust code, apply these core principles:
+
+### Language Foundations (Ch 2)
+
+1. **Use cargo, not rustc directly** (Ch 2). `cargo new`, `cargo build`, `cargo test`, `cargo doc`. Add third-party crates via `Cargo.toml` — never manually link.
+
+2. **Prefer integer types that match the domain** (Ch 2). Use `u8` for bytes, `u16`/`u32`/`u64` for protocol fields sized to spec, `i64` for timestamps. Avoid default `usize` for domain values.
+
+3. **Use `loop` for retry/event loops; `while` for condition-driven; `for` for iteration** (Ch 2). Never use `loop { if cond { break } }` where `while cond {}` is clearer.
+
+### Compound Types & Traits (Ch 3)
+
+4. **Model domain state with enums, not stringly-typed flags** (Ch 3). Enums with data (`enum Packet { Ack(u32), Data(Vec<u8>) }`) replace boolean + optional pairs and make invalid states unrepresentable.
+
+5. **Implement `new()` as the canonical constructor** (Ch 3). `impl MyStruct { pub fn new(...) -> Self { ... } }`. Use `Default` for zero-value construction.
+
+6. **Implement `std::fmt::Display` for user-facing output, `Debug` via derive** (Ch 3). Derive `Debug`; hand-implement `Display`. Never use `{:?}` in user-facing messages.
+
+7. **Use `pub(crate)` to limit visibility to the crate; keep internals private** (Ch 3). Public API surface should be minimal and intentional.
+
+8. **Document public items with `///` rustdoc comments** (Ch 3). Include examples in doc comments — `cargo test` runs them.
+
+### Ownership, Borrowing & Smart Pointers (Ch 4, 6)
+
+9. **Use references where full ownership is not required** (Ch 4). Pass `&T` for read, `&mut T` for write. Only transfer ownership when the callee must own (e.g., storing in a struct).
+
+10. **Choose smart pointers by use case** (Ch 6):
+    - `Box<T>` — heap allocation, single owner, unknown size at compile time
+    - `Rc<T>` — shared ownership, single-threaded
+    - `Arc<T>` — shared ownership, multi-threaded
+    - `Cell<T>` — interior mutability for `Copy` types, single-threaded
+    - `RefCell<T>` — interior mutability for non-`Copy`, single-threaded, runtime borrow checks
+    - `Cow<'a, T>` — clone-on-write, avoids allocation when data is only read
+    - `Arc<Mutex<T>>` — shared mutable state across threads
+
+11. **Never use `Rc` across thread boundaries** (Ch 6). The compiler enforces this — `Rc` is not `Send`. Use `Arc` instead.
+
+12. **Minimize `unsafe` blocks; wrap them in safe abstractions** (Ch 6). Raw pointers (`*const T`, `*mut T`) must be bounded within a module or function that upholds safety invariants. Document the safety contract with `// SAFETY:` comments.
+
+### Data Representation (Ch 5)
+
+13. **Be explicit about endianness in binary protocols** (Ch 5, 7). Use `u32::to_le_bytes()`, `u32::from_be_bytes()` etc. Never assume native endianness when writing to disk or network.
+
+14. **Use bit operations to inspect and build packed data** (Ch 5). AND (`&`) to isolate bits, OR (`|`) to set bits, shift (`<<`, `>>`) to position. Use named constants for masks: `const SIGN_BIT: u32 = 0x8000_0000`.
+
+15. **Validate binary data with checksums** (Ch 7). For key-value stores and file formats, store a CRC or hash alongside data. Verify on read before trusting.
+
+### Files & Storage (Ch 7)
+
+16. **Use `BufReader`/`BufWriter` for file I/O** (Ch 7). Raw `File::read()` makes a syscall per call. `BufReader` batches reads into user-space buffer.
+
+17. **Use `serde` + `bincode` for binary serialization** (Ch 7). Add `#[derive(Serialize, Deserialize)]`; let `bincode::serialize`/`deserialize` handle encoding. Use `serde_json` for human-readable formats.
+
+18. **Use `std::path::Path` and `PathBuf` for file paths** (Ch 7). Never build paths with string concatenation. Use `path.join()`, `path.extension()`, `path.file_name()`.
+
+### Networking (Ch 8)
+
+19. **Model protocol state explicitly with enums** (Ch 8). A TCP connection has states (SYN_SENT, ESTABLISHED, CLOSE_WAIT, etc.). Encode them as enum variants — the compiler enforces valid transitions.
+
+20. **Wrap library errors in a domain error type** (Ch 8). When a function calls multiple libraries (network + I/O + parse), define an enum that wraps each. Implement `From<LibError> for DomainError` so `?` converts automatically.
+
+21. **Use trait objects only for heterogeneous runtime dispatch** (Ch 8). `Vec<Box<dyn Animal>>` is correct when you have a mixed collection. For a single concrete type, `impl Trait` is zero-cost.
+
+### Concurrency (Ch 10)
+
+22. **Use `move` closures when passing to threads** (Ch 10). `thread::spawn(move || { ... })` transfers ownership of captured variables into the thread. This is required when the closure outlives the current stack frame.
+
+23. **Use `Arc::clone()` explicitly, not `.clone()` on a value** (Ch 10). `Arc::clone(&ptr)` is idiomatic — it's cheap (increments a reference count). Avoid `.clone()` on the inner value.
+
+24. **Use channels for work distribution; `Arc<Mutex<T>>` for shared state** (Ch 10). Channels (`std::sync::mpsc`) are simpler and safer. Use shared state only when channels don't fit (e.g., result collection).
+
+25. **Use thread pools over raw `thread::spawn` per task** (Ch 10). Spawning one thread per request doesn't scale. Use `rayon`, `tokio`, or a manual pool with a bounded queue.
+
+### Time (Ch 9)
+
+26. **Use `Instant` for elapsed time, `SystemTime` for wall clock** (Ch 9). `SystemTime` can go backwards (NTP adjustments, leap seconds). `Instant` is monotonic.
+
+27. **Apply the NTP epoch offset when working with network time** (Ch 9). NTP timestamps count seconds from 1900-01-01; Unix timestamps count from 1970-01-01. Offset: `2_208_988_800u64` seconds.
+
+---
+
+## Smart Pointer Selection Guide (Ch 6)
+
+```
+Is the data shared across threads?
+├── Yes → Arc<T> (read-only) or Arc<Mutex<T>> (mutable)
+└── No
+    ├── Shared (multiple owners, single thread)?
+    │   └── Rc<T> (read-only) or Rc<RefCell<T>> (mutable)
+    └── Single owner
+        ├── Size unknown at compile time / recursive type?
+        │   └── Box<T>
+        ├── Usually read, occasionally cloned/modified?
+        │   └── Cow<'a, T>
+        └── Interior mutability needed?
+            ├── Copy type → Cell<T>
+            └── Non-Copy → RefCell<T>
+```
+
+---
+
+## Code Structure Templates
+
+### Binary Protocol Field (Ch 5, 7)
+```rust
+/// Parse a 4-byte big-endian u32 from a byte buffer at offset.
+fn read_u32_be(buf: &[u8], offset: usize) -> Result<u32, ParseError> {
+    buf.get(offset..offset + 4)
+        .ok_or(ParseError::UnexpectedEof)
+        .map(|b| u32::from_be_bytes(b.try_into().unwrap()))
+}
+
+const FLAGS_MASK: u8 = 0b0000_1111;  // isolate lower 4 bits
+fn extract_flags(byte: u8) -> u8 {
+    byte & FLAGS_MASK
+}
+```
+
+### Library Error Type (Ch 8)
+```rust
+#[derive(Debug)]
+pub enum AppError {
+    Io(std::io::Error),
+    Network(std::net::AddrParseError),
+    Parse(String),
+}
+
+impl std::fmt::Display for AppError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            AppError::Io(e)      => write!(f, "I/O error: {e}"),
+            AppError::Network(e) => write!(f, "network error: {e}"),
+            AppError::Parse(msg) => write!(f, "parse error: {msg}"),
+        }
+    }
+}
+
+impl std::error::Error for AppError {}
+impl From<std::io::Error> for AppError {
+    fn from(e: std::io::Error) -> Self { AppError::Io(e) }
+}
+impl From<std::net::AddrParseError> for AppError {
+    fn from(e: std::net::AddrParseError) -> Self { AppError::Network(e) }
+}
+```
+
+### State Machine with Enum (Ch 8)
+```rust
+#[derive(Debug, Clone, PartialEq)]
+enum ConnectionState {
+    Idle,
+    Connecting { addr: std::net::SocketAddr },
+    Connected { stream: std::net::TcpStream },
+    Closed,
+}
+
+impl ConnectionState {
+    fn connect(addr: std::net::SocketAddr) -> Result<Self, AppError> {
+        let stream = std::net::TcpStream::connect(addr)?;
+        Ok(ConnectionState::Connected { stream })
+    }
+}
+```
+
+### Thread Pool Pattern (Ch 10)
+```rust
+use std::sync::{Arc, Mutex};
+use std::sync::mpsc;
+use std::thread;
+
+type Job = Box<dyn FnOnce() + Send + 'static>;
+
+struct ThreadPool {
+    sender: mpsc::Sender<Job>,
+}
+
+impl ThreadPool {
+    fn new(size: usize) -> Self {
+        let (sender, receiver) = mpsc::channel::<Job>();
+        let receiver = Arc::new(Mutex::new(receiver));
+
+        for _ in 0..size {
+            let rx = Arc::clone(&receiver);
+            thread::spawn(move || loop {
+                let job = rx.lock().expect("mutex poisoned").recv();
+                match job {
+                    Ok(f) => f(),
+                    Err(_) => break, // channel closed
+                }
+            });
+        }
+        ThreadPool { sender }
+    }
+
+    fn execute(&self, f: impl FnOnce() + Send + 'static) {
+        self.sender.send(Box::new(f)).expect("thread pool closed");
+    }
+}
+```
+
+---
+
+## Priority of Practices by Impact
+
+### Critical (Safety, Correctness, UB)
+- Ch 4: Borrow, don't clone — never move when a reference suffices
+- Ch 6: Choose the right smart pointer — `Rc` is not thread-safe; don't share across threads
+- Ch 6: Wrap `unsafe` in safe abstractions — document safety contracts with `// SAFETY:`
+- Ch 5/7: Explicit endianness — wrong byte order silently corrupts binary data
+- Ch 9: Use `Instant` for elapsed time — `SystemTime` can go backwards
+
+### Important (Idiom & Maintainability)
+- Ch 3: Domain enums over stringly-typed state — invalid states should not compile
+- Ch 8: Wrap downstream errors in a domain error type with `From` impls
+- Ch 8: `impl Trait` over `dyn Trait` when types are homogeneous
+- Ch 10: `move` closures for threads — required when closure outlives the stack frame
+- Ch 10: `Arc::clone()` idiom — makes cheap pointer clone explicit
+
+### Suggestions (Systems Polish)
+- Ch 2: Size integer types to the protocol spec — `u8` for bytes, `u16` for ports
+- Ch 5: Named bit-mask constants — `const SIGN_BIT: u32 = 0x8000_0000`
+- Ch 7: `BufReader`/`BufWriter` for all file I/O — syscall batching
+- Ch 7: Checksums on binary writes — detect corruption on read
+- Ch 9: NTP epoch offset constant — `const NTP_UNIX_OFFSET: u64 = 2_208_988_800`

package/skills/rust-in-action/evals/evals.json

@@ -0,0 +1,38 @@
+{
+  "evals": [
+    {
+      "id": "eval-01-endianness-unwrap-static-mut",
+      "prompt": "Review this Rust code:\n\n```rust\nstatic mut PACKET_COUNT: u32 = 0;\n\nfn parse_header(bytes: &[u8]) -> u32 {\n    let id = u32::from_ne_bytes([bytes[0], bytes[1], bytes[2], bytes[3]]);\n    unsafe { PACKET_COUNT += 1; }\n    id\n}\n\nfn read_data(path: &str) -> Vec<u8> {\n    std::fs::read(path).unwrap()\n}\n\nfn write_id(id: u32) -> Vec<u8> {\n    id.to_ne_bytes().to_vec()\n}\n```",
+      "expectations": [
+        "Flag Ch 5/7: from_ne_bytes uses native endianness — silently produces wrong results on big-endian hosts; use from_le_bytes or from_be_bytes to match the protocol spec",
+        "Flag Ch 6/10: static mut PACKET_COUNT is a data race in concurrent code — replace with Arc<Mutex<u32>> or an atomic (std::sync::atomic::AtomicU32)",
+        "Flag Ch 3: .unwrap() in read_data will panic on I/O error — return Result<Vec<u8>, std::io::Error> and use ?",
+        "Flag Ch 7: to_ne_bytes in write_id — same endianness problem as parse_header; must match the parse side",
+        "Note that parse_header does no bounds checking before indexing bytes[0..3] — should use bytes.get(0..4).ok_or(...) to avoid a panic on short input",
+        "Provide corrected versions using from_le_bytes/to_le_bytes, AtomicU32 or Arc<Mutex<u32>>, and Result"
+      ]
+    },
+    {
+      "id": "eval-02-smart-pointer-choice",
+      "prompt": "Review this Rust code:\n\n```rust\nuse std::rc::Rc;\nuse std::thread;\n\nstruct Cache {\n    data: Rc<Vec<String>>,\n}\n\nimpl Cache {\n    fn spawn_reader(&self) {\n        let d = Rc::clone(&self.data);\n        thread::spawn(move || {\n            println!(\"{:?}\", d);\n        });\n    }\n}\n\nfn make_buffer(large: bool) -> Box<Vec<u8>> {\n    if large {\n        Box::new(vec![0u8; 1024 * 1024])\n    } else {\n        Box::new(vec![0u8; 64])\n    }\n}\n```",
+      "expectations": [
+        "Flag Ch 6: Rc is not Send — sharing Rc across thread boundaries is a compile error; replace Rc<Vec<String>> with Arc<Vec<String>>",
+        "Flag Ch 6: Box<Vec<u8>> is redundant — Vec<u8> already heap-allocates; Box<Vec<T>> is a double-indirection with no benefit; return Vec<u8> directly",
+        "Note that Arc::clone(&self.data) is the correct idiom for incrementing an Arc refcount — it makes the cheap clone explicit",
+        "Note that spawn_reader returns no JoinHandle — callers cannot join the thread or detect panics; suggest returning thread::JoinHandle<()>",
+        "Provide corrected versions using Arc<Vec<String>>, returning Vec<u8> directly, and returning JoinHandle from spawn_reader"
+      ]
+    },
+    {
+      "id": "eval-03-idiomatic-systems-rust",
+      "prompt": "Review this Rust code:\n\n```rust\nuse std::sync::{Arc, Mutex};\nuse std::sync::atomic::{AtomicU64, Ordering};\nuse std::path::Path;\nuse std::io::{BufReader, Read};\nuse std::fs::File;\n\n#[derive(Debug)]\npub enum StoreError {\n    Io(std::io::Error),\n    Corrupt { offset: usize },\n}\n\nimpl std::fmt::Display for StoreError {\n    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {\n        match self {\n            StoreError::Io(e) => write!(f, \"io: {e}\"),\n            StoreError::Corrupt { offset } => write!(f, \"corrupt at byte {offset}\"),\n        }\n    }\n}\n\nimpl std::error::Error for StoreError {}\nimpl From<std::io::Error> for StoreError {\n    fn from(e: std::io::Error) -> Self { StoreError::Io(e) }\n}\n\nstruct Store {\n    reads: AtomicU64,\n    data: Arc<Mutex<Vec<u8>>>,\n}\n\nimpl Store {\n    fn new() -> Self {\n        Store { reads: AtomicU64::new(0), data: Arc::new(Mutex::new(vec![])) }\n    }\n\n    fn load(&self, path: &Path) -> Result<(), StoreError> {\n        let f = File::open(path)?;\n        let mut reader = BufReader::new(f);\n        let mut buf = vec![];\n        reader.read_to_end(&mut buf)?;\n        *self.data.lock().expect(\"mutex poisoned\") = buf;\n        Ok(())\n    }\n\n    fn read(&self, offset: usize, len: usize) -> Result<Vec<u8>, StoreError> {\n        self.reads.fetch_add(1, Ordering::Relaxed);\n        let data = self.data.lock().expect(\"mutex poisoned\");\n        data.get(offset..offset + len)\n            .map(|s| s.to_vec())\n            .ok_or(StoreError::Corrupt { offset })\n    }\n}\n```",
+      "expectations": [
+        "Recognize this code is idiomatic systems Rust — do NOT manufacture issues",
+        "Acknowledge: StoreError with Display + Error + From<io::Error> for ? propagation (Ch 3, 8); BufReader for batched I/O (Ch 7); &Path parameter (Ch 7); Arc<Mutex<T>> for shared mutable data (Ch 6, 10); AtomicU64 for lock-free counter (Ch 10); .expect('mutex poisoned') with reason (Ch 10)",
+        "At most suggest: reads counter could use Ordering::SeqCst if cross-thread visibility of exact count matters; or note that Relaxed is fine for approximate telemetry",
+        "At most suggest: Default could be derived or implemented for Store alongside new(), enabling Store::default() construction",
+        "Do NOT flag AtomicU64 with Relaxed ordering as a bug — it is appropriate for a read counter where exact ordering across threads is not required"
+      ]
+    }
+  ]
+}

package/skills/rust-in-action/examples/after.md

@@ -0,0 +1,156 @@
+# After: Rust in Action
+
+The same utility rewritten with idiomatic systems Rust — explicit endianness, buffered I/O, a domain error type, checksum validation, thread pool, and safe shared state.
+
+```rust
+use std::fmt;
+use std::fs::File;
+use std::io::{BufReader, Read};
+use std::path::Path;
+use std::sync::{Arc, Mutex};
+use std::sync::mpsc;
+use std::thread;
+
+// Domain error type — wraps all downstream errors (Ch 3, 8)
+#[derive(Debug)]
+pub enum LogError {
+    Io(std::io::Error),
+    InvalidRecord { offset: usize, reason: &'static str },
+    ChecksumMismatch { expected: u32, got: u32 },
+}
+
+impl fmt::Display for LogError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            LogError::Io(e) => write!(f, "I/O: {e}"),
+            LogError::InvalidRecord { offset, reason } =>
+                write!(f, "invalid record at {offset}: {reason}"),
+            LogError::ChecksumMismatch { expected, got } =>
+                write!(f, "checksum mismatch: expected {expected:#010x}, got {got:#010x}"),
+        }
+    }
+}
+
+impl std::error::Error for LogError {}
+impl From<std::io::Error> for LogError {
+    fn from(e: std::io::Error) -> Self { LogError::Io(e) }
+}
+
+// BufReader for batched I/O syscalls; &Path for type-safe path (Ch 7)
+// Returns Result — caller decides how to handle failure (Ch 3)
+fn read_log(path: &Path) -> Result<Vec<u8>, LogError> {
+    let file = File::open(path)?;  // ? converts io::Error → LogError (Ch 8)
+    let mut reader = BufReader::new(file);  // batched reads (Ch 7)
+    let mut buf = Vec::new();
+    reader.read_to_end(&mut buf)?;
+    Ok(buf)
+}
+
+// Explicit little-endian — deterministic across all hosts (Ch 5, 7)
+fn parse_record_id(bytes: &[u8], offset: usize) -> Result<u32, LogError> {
+    bytes.get(offset..offset + 4)
+        .ok_or(LogError::InvalidRecord { offset, reason: "not enough bytes for id" })
+        .map(|b| u32::from_le_bytes(b.try_into().unwrap()))
+}
+
+// Simulate a simple CRC32-like checksum (Ch 7)
+fn checksum(data: &[u8]) -> u32 {
+    data.iter().fold(0u32, |acc, &b| acc.wrapping_add(b as u32))
+}
+
+// Explicit little-endian write + checksum (Ch 5, 7)
+fn write_record(id: u32, data: &[u8]) -> Vec<u8> {
+    let mut out = Vec::with_capacity(4 + data.len() + 4);
+    out.extend_from_slice(&id.to_le_bytes());  // SAFETY: LE is the protocol spec
+    out.extend_from_slice(data);
+    let crc = checksum(&out);
+    out.extend_from_slice(&crc.to_le_bytes());  // append checksum
+    out
+}
+
+fn read_record(buf: &[u8]) -> Result<(u32, &[u8]), LogError> {
+    let id = parse_record_id(buf, 0)?;
+    let payload = buf.get(4..buf.len() - 4)
+        .ok_or(LogError::InvalidRecord { offset: 4, reason: "too short for payload + checksum" })?;
+    let stored_crc = u32::from_le_bytes(buf[buf.len() - 4..].try_into().unwrap());
+    let computed = checksum(&buf[..buf.len() - 4]);
+    if computed != stored_crc {
+        return Err(LogError::ChecksumMismatch { expected: stored_crc, got: computed });
+    }
+    Ok((id, payload))
+}
+
+// Thread pool via channel — no unbounded thread spawning (Ch 10)
+type Job = Box<dyn FnOnce() + Send + 'static>;
+
+struct Pool {
+    tx: mpsc::Sender<Job>,
+}
+
+impl Pool {
+    fn new(workers: usize) -> Self {
+        let (tx, rx) = mpsc::channel::<Job>();
+        let rx = Arc::new(Mutex::new(rx));
+        for _ in 0..workers {
+            let rx = Arc::clone(&rx);
+            thread::spawn(move || loop {
+                match rx.lock().expect("mutex poisoned").recv() {
+                    Ok(job) => job(),
+                    Err(_) => break,  // sender dropped — shut down
+                }
+            });
+        }
+        Pool { tx }
+    }
+
+    fn submit(&self, job: impl FnOnce() + Send + 'static) {
+        self.tx.send(Box::new(job)).expect("pool closed");
+    }
+}
+
+// Safe shared error counter via Arc<Mutex<T>> (Ch 6, 10)
+fn make_error_counter() -> Arc<Mutex<u32>> {
+    Arc::new(Mutex::new(0))
+}
+
+fn record_error(counter: &Arc<Mutex<u32>>) {
+    *counter.lock().expect("mutex poisoned") += 1;
+}
+
+fn main() -> Result<(), LogError> {
+    let path = Path::new("data.log");
+    let bytes = read_log(path)?;
+
+    let id = parse_record_id(&bytes, 0)?;
+    println!("id: {id}");
+
+    let pool = Pool::new(4);
+    let errors = make_error_counter();
+
+    // move — closure owns record + error counter clone (Ch 10)
+    let record = bytes.clone();
+    let err_counter = Arc::clone(&errors);
+    pool.submit(move || {
+        println!("processing {} bytes, id={}", record.len(), id);
+        if record.len() < 8 {
+            record_error(&err_counter);
+        }
+    });
+
+    // Give threads time to finish (production code would use join handles)
+    std::thread::sleep(std::time::Duration::from_millis(10));
+    println!("errors: {}", errors.lock().unwrap());
+
+    Ok(())
+}
+```
+
+**Key improvements:**
+- `LogError` wraps all downstream errors with `From` impls — `?` converts automatically (Ch 3, 8)
+- `BufReader` batches file I/O syscalls — essential for large files (Ch 7)
+- `u32::from_le_bytes()` / `to_le_bytes()` — explicit endianness, correct across all hosts (Ch 5)
+- Checksum appended and verified on read — corruption is detectable (Ch 7)
+- Thread pool via `mpsc::channel` + `Arc<Mutex<Receiver>>` — bounded concurrency (Ch 10)
+- `Arc<Mutex<u32>>` replaces `unsafe static mut` — safe shared mutable state (Ch 6, 10)
+- `move` closures transfer ownership into threads — required for `'static` bound (Ch 10)
+- `&Path` instead of `String` for file path — type-safe, works with literals (Ch 7)

package/skills/rust-in-action/examples/before.md

@@ -0,0 +1,56 @@
+# Before: Rust in Action
+
+A systems utility that reads a binary log file, parses records, and processes them concurrently — with common systems-level anti-patterns.
+
+```rust
+use std::fs::File;
+use std::io::Read;
+use std::thread;
+
+// Silently panics on any I/O failure; no error type
+fn read_log(path: String) -> Vec<u8> {
+    let mut file = File::open(path).unwrap();
+    let mut buf = vec![];
+    file.read_to_end(&mut buf).unwrap();
+    buf
+}
+
+// Assumes native endianness — corrupts data on big-endian hosts
+fn parse_record_id(bytes: &[u8]) -> u32 {
+    let arr = [bytes[0], bytes[1], bytes[2], bytes[3]];
+    u32::from_ne_bytes(arr)  // native endian — wrong for protocol
+}
+
+// Spawns one thread per record — no pooling
+fn process_all(records: Vec<Vec<u8>>) {
+    for record in records {
+        thread::spawn(|| {
+            println!("processing {} bytes", record.len());
+        });
+    }
+    // No join — threads may not finish before main exits
+}
+
+// Shared mutable state with unsafe global
+static mut ERROR_COUNT: u32 = 0;
+
+fn record_error() {
+    unsafe {
+        ERROR_COUNT += 1;  // data race — undefined behavior
+    }
+}
+
+// No endianness comment, no checksum, no error type
+fn write_record(id: u32, data: &[u8]) -> Vec<u8> {
+    let mut out = vec![];
+    out.extend_from_slice(&id.to_ne_bytes()); // native endian — wrong
+    out.extend_from_slice(data);
+    out  // no checksum — corruption undetectable
+}
+
+fn main() {
+    let bytes = read_log(String::from("data.log"));
+    let id = parse_record_id(&bytes);
+    println!("id: {}", id);
+}
+```