@booklib/skills 1.3.2 → 1.4.0

package/skills/effective-typescript/references/practices-catalog.md

@@ -0,0 +1,371 @@
+# Effective TypeScript — Practices Catalog
+
+Deep before/after examples for the 20 most impactful items.
+
+---
+
+## Item 2: Know Which TypeScript Options You're Using
+
+Always use `strict: true`. It enables `noImplicitAny` and `strictNullChecks` which catch the most common TypeScript bugs.
+
+**Before:**
+```json
+{ "compilerOptions": {} }
+```
+**After:**
+```json
+{ "compilerOptions": { "strict": true, "target": "ES2020", "module": "commonjs" } }
+```
+
+---
+
+## Item 9: Prefer Type Declarations to Type Assertions
+
+**Before:**
+```typescript
+const user = {} as User;  // bypasses type checking — user is actually empty
+const input = document.getElementById('name') as HTMLInputElement;
+```
+**After:**
+```typescript
+const user: User = { id: '1', name: 'Alice', email: 'a@example.com' }; // checked
+const input = document.getElementById('name');
+if (input instanceof HTMLInputElement) {
+  console.log(input.value); // narrowed, not asserted
+}
+```
+
+---
+
+## Item 10: Avoid Object Wrapper Types
+
+**Before:**
+```typescript
+function greet(name: String) { // String, not string
+  return 'Hello ' + name;
+}
+const s = new String('world');
+greet(s); // works but s !== 'world' as a primitive
+```
+**After:**
+```typescript
+function greet(name: string) {  // primitive type
+  return 'Hello ' + name;
+}
+```
+
+---
+
+## Item 13: Know the Differences Between `type` and `interface`
+
+- Use `interface` for object shapes that consumers may need to extend (open for augmentation)
+- Use `type` for unions, intersections, tuples, and mapped types (cannot be augmented)
+
+**Before:**
+```typescript
+type User = { id: string; name: string }; // fine, but can't be augmented by consumers
+type StringOrNumber = string | number;     // correct use of type
+```
+**After:**
+```typescript
+interface User { id: string; name: string; }  // open for extension
+type StringOrNumber = string | number;         // unions must be type aliases
+type ReadonlyUser = Readonly<User>;            // mapped type must be type alias
+```
+
+---
+
+## Item 14: Use Type Operations and Generics to Avoid Repeating Yourself
+
+**Before:**
+```typescript
+interface SavedState { userId: string; name: string; lastSaved: Date; }
+interface UnsavedState { userId: string; name: string; }  // repeated fields
+```
+**After:**
+```typescript
+interface State { userId: string; name: string; }
+interface SavedState extends State { lastSaved: Date; }
+// Or with Pick/Omit:
+type UnsavedState = Omit<SavedState, 'lastSaved'>;
+```
+
+---
+
+## Item 17: Use `readonly` to Avoid Errors Associated with Mutation
+
+**Before:**
+```typescript
+function sort(arr: number[]): number[] {
+  return arr.sort(); // mutates the original array!
+}
+```
+**After:**
+```typescript
+function sort(arr: readonly number[]): number[] {
+  return [...arr].sort(); // forced to copy — cannot mutate readonly input
+}
+```
+
+---
+
+## Item 22: Understand Type Narrowing
+
+**Before:**
+```typescript
+function processInput(val: string | null) {
+  console.log(val.toUpperCase()); // error: val is possibly null
+}
+```
+**After:**
+```typescript
+function processInput(val: string | null) {
+  if (val === null) return;
+  console.log(val.toUpperCase()); // narrowed to string
+}
+
+// instanceof narrowing
+function format(val: Date | string) {
+  if (val instanceof Date) return val.toISOString();
+  return val.toUpperCase();
+}
+```
+
+---
+
+## Item 25: Use async Functions Instead of Callbacks for Asynchronous Code
+
+Callbacks produce `any`-typed errors and complex nested types. `async`/`await` lets TypeScript infer `Promise<T>` cleanly.
+
+**Before:**
+```typescript
+function fetchData(url: string, cb: (err: any, data: any) => void) {
+  fetch(url)
+    .then(r => r.json())
+    .then(d => cb(null, d))
+    .catch(e => cb(e, null));
+}
+```
+**After:**
+```typescript
+async function fetchData<T>(url: string): Promise<T> {
+  const response = await fetch(url);
+  if (!response.ok) throw new Error(`HTTP ${response.status}`);
+  return response.json() as T;
+}
+```
+
+---
+
+## Item 28: Prefer Types That Always Represent Valid States
+
+**Before:**
+```typescript
+interface Page {
+  pageText: string;
+  isLoading: boolean;
+  error: string; // What does isLoading:true + error:'...' mean?
+}
+```
+**After:**
+```typescript
+type Page =
+  | { state: 'loading' }
+  | { state: 'success'; pageText: string }
+  | { state: 'error'; error: string };
+// Every combination is meaningful — no impossible states
+```
+
+---
+
+## Item 31: Push Null Values to the Perimeter
+
+**Before:**
+```typescript
+// null scattered throughout
+function getUser(id: string | null): User | null {
+  if (!id) return null;
+  const user: User | null = db.find(id) ?? null;
+  return user;
+}
+```
+**After:**
+```typescript
+// null handled once at the boundary
+function getUser(id: string): User {
+  const user = db.find(id);
+  if (!user) throw new Error(`User ${id} not found`);
+  return user;
+}
+// Callers who might not have an id handle it at their boundary
+```
+
+---
+
+## Item 32: Prefer Unions of Interfaces to Interfaces of Unions
+
+**Before:**
+```typescript
+interface Layer {
+  type: 'fill' | 'line' | 'point';
+  fillColor?: string;   // only for fill
+  lineWidth?: number;   // only for line
+  pointRadius?: number; // only for point
+  // { type: 'fill', lineWidth: 5 } is representable but invalid
+}
+```
+**After:**
+```typescript
+interface FillLayer   { type: 'fill';  fillColor: string; }
+interface LineLayer   { type: 'line';  lineWidth: number; }
+interface PointLayer  { type: 'point'; pointRadius: number; }
+type Layer = FillLayer | LineLayer | PointLayer;
+// Each valid state has exactly the right fields
+```
+
+---
+
+## Item 33: Prefer More Precise Alternatives to String Types
+
+**Before:**
+```typescript
+function setAlignment(align: string) {} // accepts anything
+interface Album { genre: string; }      // 'rock', 'jazz', or 'anything'?
+```
+**After:**
+```typescript
+type Alignment = 'left' | 'center' | 'right';
+function setAlignment(align: Alignment) {}
+
+type Genre = 'rock' | 'jazz' | 'pop' | 'classical';
+interface Album { genre: Genre; }
+```
+
+---
+
+## Item 38: Use the Narrowest Possible Scope for `any` Types
+
+**Before:**
+```typescript
+const config: any = JSON.parse(rawConfig); // entire variable is any
+console.log(config.timeout);               // no type checking from here on
+```
+**After:**
+```typescript
+const config = JSON.parse(rawConfig) as { timeout: number; retries: number };
+// or better — parse with unknown and narrow:
+const raw: unknown = JSON.parse(rawConfig);
+const timeout = (raw as { timeout: number }).timeout; // any scoped to one property access
+```
+
+---
+
+## Item 40: Hide Unsafe Type Assertions in Well-Typed Functions
+
+**Before:**
+```typescript
+// Assertion visible at every call site
+const user = fetchUser() as User;
+```
+**After:**
+```typescript
+// Assertion encapsulated once — all callers get proper types
+async function fetchUser(id: string): Promise<User> {
+  const raw: unknown = await fetch(`/api/users/${id}`).then(r => r.json());
+  return raw as User; // single controlled assertion inside typed boundary
+}
+```
+
+---
+
+## Item 42: Use `unknown` Instead of `any` for Values with an Unknown Type
+
+**Before:**
+```typescript
+function parseYaml(yaml: string): any { // callers never have to narrow
+  return parse(yaml);
+}
+const config = parseYaml(raw);
+config.port.toFixed(); // no error — but crashes if port is missing
+```
+**After:**
+```typescript
+function parseYaml(yaml: string): unknown { // callers must narrow before use
+  return parse(yaml);
+}
+const config = parseYaml(raw);
+if (typeof config === 'object' && config !== null && 'port' in config) {
+  const port = (config as { port: number }).port;
+}
+```
+
+---
+
+## Item 47: Export All Types That Appear in Public APIs
+
+**Before:**
+```typescript
+// Unexported — users have to use ReturnType<typeof getUser> hacks
+interface User { id: string; name: string; }
+export function getUser(id: string): User { ... }
+```
+**After:**
+```typescript
+export interface User { id: string; name: string; } // exported explicitly
+export function getUser(id: string): User { ... }
+```
+
+---
+
+## Item 48: Use TSDoc for API Comments
+
+**Before:**
+```typescript
+// Fetches user by id. Returns null if not found.
+function getUser(id: string): User | null { ... }
+```
+**After:**
+```typescript
+/**
+ * Fetches a user by their unique identifier.
+ *
+ * @param id - The user's unique identifier
+ * @returns The user, or null if no user exists with that id
+ * @throws {NetworkError} If the network request fails
+ */
+function getUser(id: string): User | null { ... }
+```
+
+---
+
+## Item 53: Prefer ECMAScript Features to TypeScript Features
+
+Avoid TypeScript-specific features that don't map cleanly to JavaScript. Prefer standard ES features.
+
+**Before:**
+```typescript
+// TypeScript enums — compiled to objects with side effects, can't be tree-shaken
+enum Direction { North, South, East, West }
+```
+**After:**
+```typescript
+// Const object + type — tree-shakeable, maps cleanly to JS
+const Direction = { North: 'North', South: 'South', East: 'East', West: 'West' } as const;
+type Direction = typeof Direction[keyof typeof Direction];
+```
+
+---
+
+## Item 62: Don't Consider Migration Complete Until You Enable `noImplicitAny`
+
+The final step of any JS→TS migration. Without it, TypeScript silently accepts untyped code.
+
+```json
+// tsconfig.json — final migration milestone
+{
+  "compilerOptions": {
+    "strict": true,          // includes noImplicitAny and strictNullChecks
+    "noImplicitAny": true    // explicit — every value must have a type
+  }
+}
+```

package/skills/programming-with-rust/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: programming-with-rust
+description: >
+  Write and review Rust code using practices from "Programming with Rust" by Donis Marshall.
+  Covers ownership, borrowing, lifetimes, error handling with Result/Option, traits, generics,
+  pattern matching, closures, fearless concurrency, and macros. Use when writing Rust, reviewing
+  Rust code, or learning Rust idioms. Trigger on: "Rust", "ownership", "borrow checker",
+  "lifetimes", "Result", "Option", "traits", "fearless concurrency", ".rs files", "cargo".
+---
+
+# Programming with Rust Skill
+
+Apply the practices from Donis Marshall's "Programming with Rust" to review existing code and write new Rust. This skill operates in two modes: **Review Mode** (analyze code for violations of Rust idioms) and **Write Mode** (produce safe, idiomatic Rust from scratch).
+
+## Reference Files
+
+- `ref-01-fundamentals.md` — Ch 1-3: Rust model, tooling, variables, primitives, references
+- `ref-02-types-strings.md` — Ch 4-5: String vs &str, formatting, Display/Debug traits
+- `ref-03-control-collections.md` — Ch 6-7: Control flow, iterators, arrays, Vec, HashMap
+- `ref-04-ownership-lifetimes.md` — Ch 8-10: Ownership, move semantics, borrowing, lifetimes
+- `ref-05-functions-errors.md` — Ch 11-12: Functions, Result, Option, panics, custom errors
+- `ref-06-structs-generics.md` — Ch 13-14: Structs, impl blocks, generics, bounds
+- `ref-07-patterns-closures.md` — Ch 15-16: Pattern matching, closures, Fn/FnMut/FnOnce
+- `ref-08-traits.md` — Ch 17: Trait definition, dispatch, supertraits, associated types
+- `ref-09-concurrency.md` — Ch 18-19: Threads, channels, Mutex, RwLock, atomics
+- `ref-10-advanced.md` — Ch 20-23: Memory, interior mutability, macros, FFI, modules
+
+## How to Use This Skill
+
+**Before responding**, read the reference files relevant to the code's topic. For ownership/borrowing issues read `ref-04`. For error handling read `ref-05`. For a full review, read all files.
+
+---
+
+## Mode 1: Code Review
+
+When the user asks you to **review** Rust code, follow this process:
+
+### Step 1: Read Relevant References
+Identify which chapters apply. If unsure, read all reference files.
+
+### Step 2: Analyze the Code
+
+Check these areas in order of severity:
+
+1. **Ownership & Borrowing** (Ch 8, 10): Unnecessary `.clone()` calls? Mutable borrow conflicts? Move semantics misunderstood?
+2. **Lifetimes** (Ch 9): Missing or incorrect annotations? Can elision rules eliminate them? `'static` used where a shorter lifetime would do?
+3. **Error Handling** (Ch 12): Is `.unwrap()` or `.expect()` used where `?` operator or proper matching belongs? Are custom error types missing where they'd help callers?
+4. **Traits & Generics** (Ch 14, 17): Are trait bounds as narrow as possible? Is dynamic dispatch (`dyn Trait`) used where static dispatch (`impl Trait`) is better for performance?
+5. **Pattern Matching** (Ch 15): Are `match` arms exhaustive? Can `if let` / `while let` simplify single-arm matches? Are wildcards masking unhandled cases?
+6. **Concurrency** (Ch 18, 19): Is shared state protected by `Mutex` or `RwLock`? Are channels used correctly? Is `Arc` used when `Rc` would suffice (single-threaded)?
+7. **Memory** (Ch 20): Is `RefCell` used outside of single-threaded interior mutability? Is `Box` used unnecessarily when stack allocation would work?
+8. **Idioms**: Is `for item in collection` preferred over manual indexing? Are iterator adapters (`map`, `filter`, `collect`) used over manual loops?
+
+### Step 3: Report Findings
+For each issue, report:
+- **Chapter reference** (e.g., "Ch 12: Error Handling")
+- **Location** in the code
+- **What's wrong** (the anti-pattern)
+- **How to fix it** (the idiomatic Rust approach)
+- **Priority**: Critical (safety/correctness), Important (idiom/maintainability), 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:
+
+### Ownership & Memory Safety
+
+1. **Prefer borrowing over cloning** (Ch 8). Pass `&T` or `&mut T` rather than transferring ownership when the caller still needs the value. Clone only when ownership genuinely needs to be duplicated.
+
+2. **Respect the single-owner rule** (Ch 8). Each value has exactly one owner. When you move a value, the old binding is invalid — design data flow around this.
+
+3. **Use lifetime elision** (Ch 9). Annotate lifetimes only when the compiler cannot infer them. Explicit annotations are for structs holding references and functions with multiple reference parameters where elision is ambiguous.
+
+4. **Prefer `&str` over `String` in function parameters** (Ch 4). Accept `&str` to work with both `String` (via deref coercion) and string literals without allocation.
+
+### Error Handling
+
+5. **Return `Result<T, E>`, never panic in library code** (Ch 12). Panics are for unrecoverable programmer errors. Use `Result` for anything that can fail at runtime.
+
+6. **Use the `?` operator for error propagation** (Ch 12). Replace `.unwrap()` chains with `?` to propagate errors cleanly to callers.
+
+7. **Define custom error types for public APIs** (Ch 12). Implement `std::error::Error` and use `thiserror` or manual `impl` to give callers structured errors they can match on.
+
+8. **Never use `.unwrap()` in production paths** (Ch 12). Use `.expect("reason")` only in tests or where panic is truly the right response. In all other cases, handle with `match`, `if let`, or `?`.
+
+### Traits & Generics
+
+9. **Prefer `impl Trait` over `dyn Trait` for return types** (Ch 17). Static dispatch is zero-cost. Use `dyn Trait` only when you need runtime polymorphism with mixed types in a collection.
+
+10. **Use trait bounds instead of concrete types** (Ch 14). `fn process<T: Display + Debug>(item: T)` is more reusable than accepting a concrete type.
+
+11. **Implement standard traits** (Ch 17). Derive `Debug`, `Clone`, `PartialEq` where appropriate. Implement `Display` for user-facing output, `From`/`Into` for conversions.
+
+### Pattern Matching
+
+12. **Use `match` for exhaustive handling** (Ch 15). The compiler enforces exhaustiveness — treat it as a feature, not a burden.
+
+13. **Use `if let` for single-variant matching** (Ch 15). `if let Some(x) = opt { }` is cleaner than a two-arm `match` when you only care about one case.
+
+14. **Destructure in function parameters** (Ch 15). `fn process(&Point { x, y }: &Point)` avoids manual field access inside the body.
+
+### Concurrency
+
+15. **Use channels for message passing** (Ch 18). Prefer `std::sync::mpsc` channels over shared mutable state when threads can communicate by value.
+
+16. **Wrap shared state in `Arc<Mutex<T>>`** (Ch 19). `Arc` for shared ownership across threads, `Mutex` for mutual exclusion. Use `RwLock` when reads vastly outnumber writes.
+
+17. **Prefer `Mutex::lock().unwrap()` with `.expect()`** (Ch 19). Poisoned mutexes indicate a panic in another thread — `.expect("mutex poisoned")` makes this explicit.
+
+### Code Structure Template
+
+```rust
+use std::fmt;
+
+/// Domain error type for public APIs (Ch 12)
+#[derive(Debug)]
+pub enum AppError {
+    NotFound(String),
+    InvalidInput(String),
+    Io(std::io::Error),
+}
+
+impl fmt::Display for AppError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            AppError::NotFound(msg) => write!(f, "not found: {msg}"),
+            AppError::InvalidInput(msg) => write!(f, "invalid input: {msg}"),
+            AppError::Io(e) => write!(f, "I/O error: {e}"),
+        }
+    }
+}
+
+impl std::error::Error for AppError {}
+
+impl From<std::io::Error> for AppError {
+    fn from(e: std::io::Error) -> Self {
+        AppError::Io(e)
+    }
+}
+
+/// Accept &str, not String (Ch 4)
+pub fn find_user(name: &str) -> Result<User, AppError> {
+    // Use ? for propagation (Ch 12)
+    let data = load_data()?;
+    data.iter()
+        .find(|u| u.name == name)
+        .cloned()  // clone only the found item (Ch 8)
+        .ok_or_else(|| AppError::NotFound(name.to_string()))
+}
+
+/// Derive standard traits (Ch 17)
+#[derive(Debug, Clone, PartialEq)]
+pub struct User {
+    pub name: String,
+    pub role: Role,
+}
+
+/// Enum for valid states (Ch 15)
+#[derive(Debug, Clone, PartialEq)]
+pub enum Role {
+    Admin,
+    Viewer,
+    Editor,
+}
+```
+
+---
+
+## Priority of Practices by Impact
+
+### Critical (Safety & Correctness)
+- Ch 8: Understand ownership — moving vs borrowing, no use-after-move
+- Ch 10: One mutable borrow OR many immutable borrows — never both
+- Ch 12: Never `.unwrap()` in production; use `Result` and `?`
+- Ch 19: Always protect shared mutable state with `Mutex` or `RwLock`
+
+### Important (Idiom & Maintainability)
+- Ch 4: Prefer `&str` params over `String`
+- Ch 9: Rely on lifetime elision; annotate only when required
+- Ch 12: Custom error types for public APIs
+- Ch 14/17: Trait bounds over concrete types; `impl Trait` over `dyn Trait`
+- Ch 15: Exhaustive `match`; use `if let` for single-arm cases
+- Ch 17: Derive/implement standard traits (`Debug`, `Display`, `From`)
+
+### Suggestions (Polish)
+- Ch 6: Use iterator adapters (`map`, `filter`, `flat_map`) over manual loops
+- Ch 16: Use closures with `move` when capturing environment across thread boundaries
+- Ch 20: Prefer stack allocation; use `Box` only when size is unknown at compile time
+- Ch 21: Use `derive` macros before writing manual `impl` blocks

package/skills/programming-with-rust/evals/evals.json

@@ -0,0 +1,37 @@
+{
+  "evals": [
+    {
+      "id": "eval-01-unwrap-clone-ownership",
+      "prompt": "Review this Rust code:\n\n```rust\nfn process_users(users: Vec<String>) -> Vec<String> {\n    let copy = users.clone();\n    let mut result = Vec::new();\n    for i in 0..copy.len() {\n        result.push(copy[i].clone());\n    }\n    result\n}\n\nfn read_file(path: String) -> String {\n    std::fs::read_to_string(path).unwrap()\n}\n\nfn find(map: HashMap<String, u32>, key: String) -> u32 {\n    map.get(&key).unwrap().clone()\n}\n```",
+      "expectations": [
+        "Flag Ch 8: users.clone() is unnecessary — borrow &[String] instead of taking ownership of Vec<String>",
+        "Flag Ch 6: manual index loop should be replaced with iterator adapters (.iter().cloned().collect())",
+        "Flag Ch 12: .unwrap() in read_file will panic on I/O error — should return Result<String, std::io::Error> and use ?",
+        "Flag Ch 8: find takes owned HashMap — borrows &HashMap<String, u32> instead",
+        "Flag Ch 12: .unwrap() in find panics on missing key — return Option<u32> or Result",
+        "Provide corrected versions using &[String], iterators, Result, ?, and &HashMap"
+      ]
+    },
+    {
+      "id": "eval-02-subtle-trait-dispatch",
+      "prompt": "Review this Rust code:\n\n```rust\nuse std::fmt;\n\ntrait Summarize {\n    fn summary(&self) -> String;\n}\n\nstruct Article { title: String, body: String }\nstruct Tweet { content: String }\n\nimpl Summarize for Article {\n    fn summary(&self) -> String { self.title.clone() }\n}\nimpl Summarize for Tweet {\n    fn summary(&self) -> String { self.content.clone() }\n}\n\n// Returns a trait object\nfn make_summary(is_article: bool) -> Box<dyn Summarize> {\n    if is_article {\n        Box::new(Article { title: String::from(\"news\"), body: String::from(\"...\") })\n    } else {\n        Box::new(Tweet { content: String::from(\"hello\") })\n    }\n}\n\n// Takes a trait object\nfn print_all(items: &Vec<Box<dyn Summarize>>) {\n    for item in items {\n        println!(\"{}\", item.summary());\n    }\n}\n```",
+      "expectations": [
+        "Note that Box<dyn Summarize> in make_summary is actually appropriate here because the function must return one of two different concrete types — this is a valid use of dynamic dispatch (Ch 17)",
+        "Flag &Vec<Box<dyn Summarize>> in print_all — prefer &[Box<dyn Summarize>] (a slice reference is more general than a Vec reference)",
+        "Suggest that if only one type were returned, impl Summarize would be preferred over Box<dyn Summarize> for zero-cost static dispatch (Ch 17)",
+        "Note .clone() in summary() implementations — title/body could be returned as &str with lifetime annotation to avoid allocation (Ch 8, 9)",
+        "Do NOT flag the dynamic dispatch in make_summary as wrong — it is the correct choice when returning heterogeneous types"
+      ]
+    },
+    {
+      "id": "eval-03-idiomatic-rust-already-good",
+      "prompt": "Review this Rust code:\n\n```rust\nuse std::fmt;\nuse std::sync::{Arc, Mutex};\n\n#[derive(Debug)]\npub enum StoreError {\n    NotFound(String),\n    Io(std::io::Error),\n}\n\nimpl fmt::Display for StoreError {\n    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {\n        match self {\n            StoreError::NotFound(k) => write!(f, \"key not found: {k}\"),\n            StoreError::Io(e) => write!(f, \"io error: {e}\"),\n        }\n    }\n}\n\nimpl std::error::Error for StoreError {}\n\nimpl From<std::io::Error> for StoreError {\n    fn from(e: std::io::Error) -> Self { StoreError::Io(e) }\n}\n\n#[derive(Debug, Clone)]\npub struct Record {\n    pub key: String,\n    pub value: String,\n}\n\npub struct Store {\n    records: Arc<Mutex<Vec<Record>>>,\n}\n\nimpl Store {\n    pub fn new() -> Self {\n        Store { records: Arc::new(Mutex::new(Vec::new())) }\n    }\n\n    pub fn insert(&self, key: &str, value: &str) {\n        let mut records = self.records.lock().expect(\"mutex poisoned\");\n        records.push(Record { key: key.to_string(), value: value.to_string() });\n    }\n\n    pub fn find(&self, key: &str) -> Result<Record, StoreError> {\n        let records = self.records.lock().expect(\"mutex poisoned\");\n        records\n            .iter()\n            .find(|r| r.key == key)\n            .cloned()\n            .ok_or_else(|| StoreError::NotFound(key.to_string()))\n    }\n}\n```",
+      "expectations": [
+        "Recognize this code is idiomatic Rust — do NOT manufacture issues",
+        "Acknowledge: custom StoreError with Display + Error + From (Ch 12), Arc<Mutex<T>> for shared state (Ch 19), &str parameters with .to_string() conversion (Ch 4), iterator .find().cloned() over manual loops (Ch 6), .expect('mutex poisoned') with reason string (Ch 19)",
+        "At most note that Default could be derived or implemented for Store alongside new()",
+        "Do not flag .cloned() on the found record — cloning a single found item is correct and intentional"
+      ]
+    }
+  ]
+}