lazycodex-ai 5.0.0-beta.9 → 5.0.0

package/packages/omo-codex/plugin/skills/programming/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: programming
-description: "MUST USE for ANY work on .py .pyi .rs .ts .tsx .mts .cts .go files. One philosophy: strict types, modern stacks (Pydantic v2 / serde+thiserror / Zod / gin+sqlc+pgx+slog), modern toolchains (uv+basedpyright+ruff / cargo+clippy+miri / Bun+Biome+tsc / gofumpt+golangci-lint v2+nilaway+go-race), parse-don't-validate, exhaustive match, typed errors, no any/unwrap/panic, 250 LOC ceiling, TDD, consumer-routed logging. Routes to references/{python,rust,typescript,rust-ub,go}/ + references/logging.md. Triggers: write/edit Python/Rust/TypeScript/Go code, new project, gin server, bubbletea TUI, CJK IME, connect-go RPC, sqlc pgx, branded ids, exhaustive match, unsafe Rust, miri, oversized file, refactor, TDD, e2e test, logging, log levels, structured logging, observability, arena, allocator, bumpalo, const fn, const generics, comptime, zero-alloc, bitfield, repr, scopeguard, errdefer, Zig-like, zerocopy, packed struct."
+description: "Applies strict, modern language practice (typed errors, exhaustive match, tests that can fail) for Python, Rust, TypeScript, and Go. Use for work on .py, .rs, .ts, or .go files."
 ---
 
 # Programming
@@ -47,23 +47,15 @@ These are not style preferences. They are the seven axioms every recipe in `refe
 
 5. **Trust framework guarantees. Validate only at boundaries.** No null checks for values the type system already proves non-null. No `try/except` around code that cannot raise. No `unwrap`/`!`/`as` to paper over a contract you should have encoded in types. No defensive layer for a scenario you cannot name.
 
-6. **Test-driven, with the right shape of test.** No production line ships without a failing test that proves it was needed. Behavior is locked by tests, not by hope. See the TDD discipline below.
+6. **Tests are the behavior of record, and only tests that can fail count.** READ the tests covering the area BEFORE you change it: do they encode the intent, cover this path, pass? One wrong before your change is a FINDING — never edit it green. Reproduce a bug before fixing it. The run proves the change; add a test ONLY where the repository keeps tests for this behavior AND a regression would otherwise pass unnoticed — sized like its neighbors, never restating the change. See the test discipline below.
 
 ---
 
-## TDD DISCIPLINE — NON-NEGOTIABLE
-
-**Every change follows the red → green → refactor loop.** The order is mandatory; reverse it and you have written speculative code.
-
-### The order
-
-1. **Red.** Write a failing test that names the behavior in `Given / When / Then`. Run it. *Confirm it fails for the right reason* — not a typo, not an import error. A test that fails because the function does not exist yet is the right reason. A test that fails because of a missing import is not.
-2. **Green.** Write the minimum code to make the test pass. Resist adding the second case until the first passes. The second case is the next red.
-3. **Refactor.** With the test green, restructure ruthlessly. The test is your safety net. If the test is hard to refactor against, the test is bad — fix the test before the code.
+## TEST DISCIPLINE
 
 ### The shape of the test pyramid
 
-Every feature ships with all three rungs, sized in this proportion:
+Where the repository keeps these rungs, test at the cheapest rung that observes the behavior:
 
 | Rung | Count | Purpose | Speed budget |
 |---|---|---|---|
@@ -71,7 +63,7 @@ Every feature ships with all three rungs, sized in this proportion:
 | **Integration** | some | The real adapter against the real downstream (DB, queue, HTTP) — via `testcontainers`, `httptest`, or equivalent. NEVER a unit test pretending to be integration. | < 1 s each |
 | **E2E scenario** | few | One narrative per user-visible outcome. Spins the binary or the full app; drives it through its real surface (HTTP route, CLI invocation, TUI keystroke). Asserts the *observable outcome*, not internal state. | seconds, run on CI |
 
-If a feature has zero E2E coverage, it is undone — even if every unit test passes.
+A user-visible outcome you never drove through its real surface is unverified — a green unit suite does not stand in for that run.
 
 ### Given / When / Then is mandatory
 
@@ -121,7 +113,7 @@ If no machine consumes the text, there is no seam: write NO test and say so in t
 
 | Anti-pattern | Why it fails | Fix |
 |---|---|---|
-| Writing code first, tests "to add later" | Tests-after rationalize the existing design, even when wrong. | Red first. Always. |
+| A test that restates the change (pins a constant, a string, a rename, a call) | Cannot fail for any regression; certifies the diff, not the behavior. | The run is the proof. Delete the test. |
 | One mega-test asserting 12 things | First failure hides the next 11. | Split by `Then` clause — one assertion class per test. |
 | Mocking every collaborator | Test passes regardless of real behavior. | Use a fake or the real thing. Mock only true unmockables. |
 | `time.sleep(0.1)` to "let it finish" | Flake guaranteed. | Subscribe to the completion signal; bounded await. |
@@ -143,7 +135,7 @@ Apply unless the per-language reference overrides with something stricter.
 | Immutable by default | `@dataclass(frozen=True, slots=True)` / Pydantic `frozen=True` | every binding is `let` (not `let mut`) unless mutation is the documented purpose | every field is `readonly`; arrays are `readonly T[]` | value types, unexported fields, no mutation methods unless mutation is the purpose |
 | Branded primitives | `UserId = NewType("UserId", int)` | `struct UserId(u64);` (newtype tuple) | `type UserId = Brand<string, "UserId">` | `type UserID string` + smart constructor with unexported field |
 | Exhaustive variant matching | `match` + `assert_never` | `match` (compiler-enforced) | `switch` + `assertNever` | sealed interface + type switch + **`exhaustive` linter** (the compiler will not help) |
-| No untyped escape hatches | no `Any` in public sigs, no `cast`, no `# type: ignore` | no `unwrap`/`expect` outside `main`/tests, no `as` for narrowing, no `#[allow]` to silence real warnings | no `any`, no `as` (except `as const`, `satisfies`), no `!`, no `@ts-ignore`, no `@ts-expect-error` | no `interface{}` / bare `any` in domain sigs; no `_ = err`; no `//nolint` without reason |
+| No untyped escape hatches | no `Any` in public sigs, no `cast`, no `# type: ignore` | no `unwrap`/`expect` outside tests (invariant `expect` only behind `#[expect(clippy::expect_used, reason)]`), no numeric `as`, no `#[allow]` (silence with `#[expect(lint, reason)]`) | no `any`, no `as` (except `as const`, `satisfies`), no `!`, no `@ts-ignore`, no `@ts-expect-error` | no `interface{}` / bare `any` in domain sigs; no `_ = err`; no `//nolint` without reason |
 | No bare error strings | typed exception dataclass with `__str__` | `thiserror` enum (lib) or `anyhow` with `.context(...)` (app) | `Error` subclass with typed fields | sentinel `errors.New` + typed `*XError` struct; wrap with `%w`; check via `errors.Is/As` |
 | Boundary catch only | catch the exact exception you expect; broad `except Exception` only in `main()`, with logging + re-raise | `?` everywhere; never `panic!` in library code | `catch` must narrow with `instanceof` and re-throw or convert; no empty catch | every `(T, error)` checked; `panic` only in `main`/tests; one `httperr.Write` funnel in handlers |
 | Resources via RAII | `with` (sync) / `async with` (async) | `Drop` impl or RAII guard | `using`/`await using` (TC39 explicit resource management) | `defer x.Close()` immediately after acquisition; `bodyclose`/`sqlclosecheck` linters enforce |
@@ -189,7 +181,7 @@ A bare default constructor for any of these (no timeouts, no pool tuning, no sch
 | UB / soundness gate | (n/a) | **nightly miri** with strict provenance + Tree Borrows pass | (n/a) | **`nilaway`** + `-race` detector + `goleak` are the equivalent gate |
 | Disposable scripts | **PEP 723** inline metadata + `uv run script.py` | **rust-script** with inline `Cargo.toml` block | `bun run script.ts` | `//go:build ignore` + `go run script.go` |
 | Bootstrap a new project | `scripts/python/new-project.py` | `scripts/rust/new-project.py` | `scripts/typescript/new-project.ts` | `scripts/go/new-project.py` |
-| Pre-commit / CI gate | `ruff check . && basedpyright && pytest` | `cargo +nightly clippy -- -D warnings && cargo nextest run && cargo +nightly miri test` | `bunx biome check . && bunx tsc --noEmit && bun test` | `gofumpt -l . && golangci-lint run ./... && nilaway ./... && go test -race -shuffle=on -count=1 ./...` |
+| Pre-commit / CI gate | `ruff check . && basedpyright && pytest` | `cargo clippy --all-targets -- -D warnings && cargo nextest run && cargo test --doc && cargo +nightly miri nextest run` | `bunx biome check . && bunx tsc --noEmit && bun test` | `gofumpt -l . && golangci-lint run ./... && nilaway ./... && go test -race -shuffle=on -count=1 ./...` |
 
 A `tsconfig.json` with `"strict": true` alone is **not** strict. The reference enumerates the additional flags. Same for `pyproject.toml` and `Cargo.toml` - the references contain the canonical full configuration.
 
@@ -281,7 +273,7 @@ After every code-writing session, answer these out loud (in your reply) before d
 1. **Single responsibility?** Can I name what this file owns in one short noun phrase? If the answer needs the word "and", split.
 2. **Boundary purity?** Did I parse untrusted input into a typed value at the boundary, or did I pass `dict[str, Any]` / `serde_json::Value` / `unknown` past the boundary? If the latter, fix it.
 3. **Variant discrimination?** Did I use `if`/`elif`/`else` (or `switch` without `assertNever`, or `match` without `assert_never`) anywhere to discriminate on a tagged type or enum? If yes, rewrite as exhaustive match.
-4. **Escape hatches?** Any `Any`, `# type: ignore`, `unwrap`, `expect` outside `main`/tests, `as` numeric cast, `!`, `@ts-ignore`, `@ts-expect-error`, `#[allow]` on a real warning? If yes, fix the type or document why with a comment.
+4. **Escape hatches?** Any `Any`, `# type: ignore`, `unwrap`, `expect` outside tests, `as` numeric cast, `!`, `@ts-ignore`, `@ts-expect-error`, a Rust `#[allow]` instead of `#[expect(lint, reason)]`? If yes, fix the type or document why with a comment.
 5. **Defensive layer?** Any null check, try/except, or `isinstance` guarding a value the type system already proves? If yes, delete.
 6. **Helpers for one-off?** Any function, class, or trait introduced for a single caller that will never get a second caller? If yes, inline — axiom 0 should have caught it pre-write; this is the backstop.
 7. **Tests?** Is the behavior I just introduced locked by a test that would fail if I revert this commit?
@@ -349,7 +341,9 @@ These two skills are not optional cosmetics. They are the recovery path for the
 | Concurrency primitives (locks, atomics, channels, loom) | `references/rust/concurrency.md` |
 | axum + sqlx + tracing + tower HTTP stack | `references/rust/axum-stack.md` |
 | clap + color-eyre + tracing + indicatif CLI stack | `references/rust/clap-stack.md` |
-| Property tests (proptest) + snapshot tests (insta) | `references/rust/proptest-insta.md` |
+| Public API design (naming, conversions, traits, rustdoc sections) | `references/rust/api-design.md` |
+| Declarative and procedural macros | `references/rust/macros.md` |
+| Property tests (proptest) + snapshot tests (insta), test placement, doctests | `references/rust/proptest-insta.md` |
 | Disposable `rust-script` scripts | `references/rust/one-liners.md` |
 | Canonical library defaults | `references/rust/libraries.md` |
 | **ANY `unsafe` / FFI / `MaybeUninit` / lock-free work** | **`references/rust-ub/` (full directory)** |

package/packages/omo-codex/plugin/skills/programming/references/rust/README.md

@@ -35,6 +35,10 @@ let val = map.get("key").unwrap();
 let val = map.get("key").context("missing 'key' in config")?;
 ```
 
+The one exception is a failure that can only mean a bug in this crate (a proven invariant): `.expect("<the invariant>")` behind `#[expect(clippy::expect_used, reason = "<why it cannot fail>")]` on that statement. Clippy's `expect_used` deny and `scripts/rust/check-no-excuse-rules.sh` both honor exactly that form.
+
+**Discarding is handling too.** `let _ = fallible();` and `.ok();` that drop an error are forbidden (`let_underscore_must_use`). A best-effort call (cleanup in `Drop`, a rollback on an error path) logs the error it cannot return.
+
 Typed errors for libraries ([thiserror](https://docs.rs/thiserror)), ad-hoc errors for binaries ([anyhow](https://docs.rs/anyhow) / [color-eyre](https://docs.rs/color-eyre)). Full stack → [libraries.md](libraries.md).
 
 ### 2. No `unsafe` Without Miri Proof
@@ -73,30 +77,31 @@ fn process(input: &str) -> Cow<'_, str> { ... }
 fn process(input: &[u8], output: &mut [u8]) -> usize { ... }
 ```
 
-### 4. Compile-Time First — const fn Everything Const-Eligible
+### 4. Compile-Time First — Compute What Is Known at Build Time
 
-If a function CAN be `const fn`, it MUST be `const fn`. Full recipes → [zero-cost-safety.md §2](zero-cost-safety.md).
+Lookup tables, size assertions, and buffer sizes are computed at compile time. A function is `const fn` when a `const` context needs it or it is trivially const-eligible; never contort runtime logic to be const. Full recipes → [zero-cost-safety.md §2](zero-cost-safety.md).
 
 ```rust
 // Lookup tables computed at compile time — zero runtime cost
+#[expect(clippy::indexing_slicing, reason = "const evaluation: an out-of-bounds index is a compile error")]
 const CRC_TABLE: [u32; 256] = {
     let mut table = [0u32; 256];
-    let mut i = 0;
+    let mut i: u32 = 0;
     while i < 256 {
-        let mut crc = i as u32;
+        let mut crc = i;
         let mut j = 0;
         while j < 8 {
-            crc = if crc & 1 != 0 { (crc >> 1) ^ 0xEDB88320 } else { crc >> 1 };
+            crc = if crc & 1 != 0 { (crc >> 1) ^ 0xEDB8_8320 } else { crc >> 1 };
             j += 1;
         }
-        table[i] = crc;
+        table[i as usize] = crc; // u32 -> usize widens: the one cast `const` allows
         i += 1;
     }
     table
 };
 
 // Compile-time assertions — catch violations at build time, not runtime
-const { assert!(std::mem::size_of::<Header>() == 12, "Header must be 12 bytes") };
+const _: () = assert!(std::mem::size_of::<Header>() == 12, "Header must be 12 bytes");
 ```
 
 Use `const generics` for stack-allocated buffers with compile-time size:
@@ -119,7 +124,11 @@ use scopeguard::guard;
 fn deploy(artifact: &Path) -> Result<(), DeployError> {
     let backup = snapshot_current()?;
     // errdefer: restore on failure
-    let rollback = guard(backup, |b| { let _ = restore(&b); });
+    let rollback = guard(backup, |b| {
+        if let Err(error) = restore(&b) {
+            tracing::error!(%error, "rollback failed");
+        }
+    });
 
     upload(artifact)?;
     health_check()?;
@@ -185,6 +194,21 @@ impl Order<Validated> {
 // Order<Draft> has no .pay() method. Compiler enforces the workflow.
 ```
 
+### 9. Numbers State What Overflow and Conversion Mean
+
+`+` panics in debug and wraps in release: it states nothing. Pick the operation that says what the domain wants, and convert through the trait that says whether it can fail.
+
+```rust
+let total = a.checked_add(b).ok_or(Error::Overflow)?; // overflow is an error
+let level = volume.saturating_add(step);              // clamp at the bound
+let slot = seq.wrapping_add(1) % RING;                // modular by design
+let wide = u64::from(small);                          // lossless: From
+let port = u16::try_from(raw).map_err(|_| Error::Port(raw))?; // lossy: TryFrom
+scores.sort_by(f64::total_cmp);                        // NaN-safe total order
+```
+
+Never `as` for numeric conversion (the only exception is a lossless widening inside `const`, where `From` is unavailable; see [zero-cost-safety.md §2](zero-cost-safety.md)). Compare floats with an explicit tolerance chosen by the domain, never `==`. A value that can never be zero is `NonZeroU32` (and `Option<NonZeroU32>` costs no extra space).
+
 ---
 
 ## Standard Library Defaults
@@ -217,7 +241,7 @@ Every new project gets the strict lint config from [cargo-strict.md](cargo-stric
 ```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  # when unsafe is involved
 ```
 
@@ -231,19 +255,21 @@ Run through this list after writing any Rust code. Every item links to its recip
 |---|---|---|
 | 1 | Every function signature prefers `&[T]`/`&str`/`Cow` over owned types | [zero-cost-safety.md §3](zero-cost-safety.md) |
 | 2 | Hot-path allocations use arena (`bumpalo`) not scattered `Box`/`Vec` | [zero-cost-safety.md §1](zero-cost-safety.md) |
-| 3 | Const-eligible functions are `const fn` | [zero-cost-safety.md §2](zero-cost-safety.md) |
-| 4 | Lookup tables / config constants computed at compile time | [zero-cost-safety.md §2](zero-cost-safety.md) |
+| 3 | Values known at build time (tables, size asserts, buffer sizes) are computed at compile time | [zero-cost-safety.md §2](zero-cost-safety.md) |
+| 4 | Arithmetic states its overflow intent; numeric conversions use `From`/`TryFrom` | This file §9 |
 | 5 | Binary format parsing uses `zerocopy`, not `transmute` | [zero-cost-safety.md §4](zero-cost-safety.md) |
 | 6 | Cleanup logic uses `scopeguard` or `Drop`, never manual `if err` cleanup | [zero-cost-safety.md §5](zero-cost-safety.md) |
 | 7 | Distinct semantic units are newtypes, not primitive aliases | [type-state.md](type-state.md) |
 | 8 | State machines use type-state, not runtime `if state ==` | [type-state.md](type-state.md) |
-| 9 | No `unwrap()`/`expect()` outside `#[cfg(test)]` | [libraries.md](libraries.md) |
+| 9 | No `unwrap()`/`expect()` outside tests (invariant `expect` only behind `#[expect(clippy::expect_used, reason)]`); no discarded `Result` | This file §1 |
 | 10 | Every `unsafe` has SAFETY comment + miri test | [unsafe-discipline.md](unsafe-discipline.md), [../rust-ub/](../rust-ub/) |
 | 11 | Match on owned enums is exhaustive (no `_ =>`) | This file §7 |
 | 12 | Clippy pedantic passes with zero warnings | [cargo-strict.md](cargo-strict.md) |
 | 13 | Property tests exist for any function with a nontrivial domain | [proptest-insta.md](proptest-insta.md) |
 | 14 | Concurrency uses channels first, locks second, atomics last | [concurrency.md](concurrency.md) |
-| 15 | Async code uses `JoinSet` for structured concurrency | [async-tokio.md](async-tokio.md) |
+| 15 | Async code uses `JoinSet` for structured concurrency; no lock guard, `watch` borrow, or entered span held across `.await` | [async-tokio.md](async-tokio.md) |
+| 16 | Public API follows the naming, conversion, and trait rules; `From` never bypasses a newtype invariant | [api-design.md](api-design.md) |
+| 17 | A performance-motivated change carries its before/after measurement | [libraries.md](libraries.md) (criterion) |
 
 ---
 
@@ -274,7 +300,9 @@ zerocopy = { version = "0.8", features = ["derive"] }
 | File | When to Load |
 |---|---|
 | [zero-cost-safety.md](zero-cost-safety.md) | Arena, allocator, const fn, comptime, zero-alloc, bitfield, repr, scopeguard, errdefer, Zig-like patterns |
-| [type-state.md](type-state.md) | Newtype wrappers, type-state machines, branded IDs, phantom types |
+| [type-state.md](type-state.md) | Newtype wrappers, validated construction, type-state machines, branded IDs, phantom types |
+| [api-design.md](api-design.md) | Public API: naming, conversions, trait design, `#[must_use]`, `#[non_exhaustive]`, visibility, rustdoc sections |
+| [macros.md](macros.md) | `macro_rules!` hygiene, proc-macro crates (`syn`/`quote`), spanned compile errors |
 | [unsafe-discipline.md](unsafe-discipline.md) | Any `unsafe` block — SAFETY comments, safe wrappers, miri proof |
 | [libraries.md](libraries.md) | Library selection, crate decision tree, dependency audit |
 | [cargo-strict.md](cargo-strict.md) | Project bootstrap, lint config, CI gate commands |
@@ -297,7 +325,7 @@ zerocopy = { version = "0.8", features = ["derive"] }
 ///
 /// # Errors
 /// Returns `FooError::Bar` when the input is invalid.
-const fn frobnicate<'a>(
+fn frobnicate<'a>(
     arena: &'a Bump,        // explicit allocator when arena is in play
     input: &[u8],           // borrow, not owned
     output: &mut [u8],      // caller-provided buffer

package/packages/omo-codex/plugin/skills/programming/references/rust/api-design.md

@@ -0,0 +1,81 @@
+# Public API Design
+
+What a caller sees: names, conversions, traits, attributes, visibility, and rustdoc. Every rule here exists so a call site reads correctly without opening the implementation.
+
+## Naming says cost and ownership
+
+| Prefix / form | Meaning | Example |
+|---|---|---|
+| `as_x(&self) -> &X` | Borrowed view, no allocation | `str::as_bytes`, `PathBuf::as_path` |
+| `to_x(&self) -> X` | Builds a new owned value (may allocate or compute) | `str::to_lowercase`, `Path::to_path_buf` |
+| `into_x(self) -> X` | Consumes `self`, reuses its buffers | `String::into_bytes`, `Vec::into_boxed_slice` |
+| `x(&self)` | Plain accessor, no `get_` prefix | `len()`, `name()`, `user_id()` |
+| `get(&self, key)` | Fallible lookup that returns `Option` | `HashMap::get`, `slice::get` |
+| `iter()` / `iter_mut()` / `IntoIterator` | Borrowing, mutable, and consuming iteration | implement the ones the type actually needs |
+| `is_x()` / `has_x()` / `can_x()` | `bool` query, named for the positive state | `is_empty()`, `has_children()` |
+
+Types, traits, and enum variants are `UpperCamelCase` with acronyms as one word (`HttpClient`, `Json`, not `HTTPClient`); functions, modules, and locals `snake_case`; constants and statics `SCREAMING_SNAKE_CASE`; simple generics `T`, `E`, `K`, `V`, lifetimes short (`'a`, `'de`). Return `impl Iterator<Item = T>` instead of a named iterator struct unless callers need to name the type.
+
+## Conversions
+
+| Conversion | Trait | Rule |
+|---|---|---|
+| Always succeeds, no invariant can break | `From<T>` | Implement `From`; callers get `Into` for free. Never implement `Into` directly. |
+| Can fail | `TryFrom<T>` | `type Error` is a real error type, never `()` or `String`. |
+| Parses text | `FromStr` | Routes through the same checked constructor as `TryFrom`. |
+| Cheap borrowed view for a generic parameter | `AsRef<T>` | Accept `impl AsRef<Path>` only where callers really pass several types; a plain `&Path` is simpler otherwise. |
+
+Validated types expose `TryFrom` / `FromStr` only; an infallible `From` into them bypasses the invariant ([type-state.md](type-state.md)). Units convert through named methods (`to_feet()`), never `From`, so the conversion is visible.
+
+Generic parameters that only convert (`fn new(name: impl Into<String>)`) hide an allocation at the call site; take `&str` or `String` explicitly unless the constructor is called with both often.
+
+## Trait design
+
+- **Generic by default, `dyn` for heterogeneity.** `fn run<R: Renderer>(r: &R)` monomorphizes and inlines; `&dyn Renderer` or `Box<dyn Renderer>` is for a collection of mixed implementors or a deliberate code-size trade. `dyn` needs indirection, not necessarily a heap allocation: `&dyn Trait` borrows.
+- **Associated type vs generic parameter.** One natural output per implementor (`Iterator::Item`, a parser's `Output`) is an associated type. A generic parameter (`From<T>`) is for traits a type implements several times.
+- **Minimal required methods.** Require the few methods that carry the contract; provide the rest as default methods built on them. A default method must be correct for every implementor, not merely convenient.
+- **Blanket impls are a semver commitment.** A public `impl<T: Display> MyTrait for T` forbids downstream crates, and your own future versions, from writing a more specific impl. Add one only when it is permanently right for every `T`.
+- **Orphan rule.** You cannot implement a foreign trait for a foreign type. Wrap the type in a local newtype and implement the trait on the wrapper; do not add `Deref` to the inner type to make it convenient.
+- **Closed sets are sealed.** A public trait whose implementations only you may add uses the sealed-trait pattern ([type-state.md](type-state.md#sealed-traits)).
+- **Bounds live on impls, not structs.** `struct Cache<K, V> { .. }` stays unbounded; `impl<K: Hash + Eq, V> Cache<K, V>` carries the bounds, so every mention of `Cache` does not repeat them.
+- **Callables take the weakest bound.** `FnOnce` if called once, `FnMut` if called repeatedly with mutation, `Fn` for shared repeated calls. Return a closure as `impl Fn(..)`; box it (`Box<dyn Fn(..)>`) only to store closures of different types together.
+
+## Attributes that protect callers
+
+- **`#[must_use]`** on builder methods that return `Self` (a dropped builder silently loses configuration), on pure constructors of values whose drop is a bug, and on functions whose whole point is the return value. `Result` is already `must_use`; do not blanket-annotate every function.
+- **`#[non_exhaustive]`** on public enums and structs that will grow (error enums, config structs, event types). Downstream matches get a required `_` arm and your next variant is not a breaking change. Keep a public enum exhaustive only when its closed set is part of the contract (`Ordering`). `exhaustive_enums` / `exhaustive_structs` in [cargo-strict.md](cargo-strict.md) flag the choice.
+
+## Visibility
+
+Start private. Widen one step at a time, only for a caller that exists: private -> `pub(super)` (sibling modules) -> `pub(crate)` -> `pub`. The `unreachable_pub` lint catches `pub` items no one outside the crate can reach. Shape the public surface with deliberate re-exports (`pub use crate::parse::Parser;` in `lib.rs`), never `pub use module::*`, which exports whatever a later edit adds.
+
+## Rustdoc sections
+
+Every public item has a doc comment (`missing_docs`). Public fallible, panicking, or `unsafe` functions carry the section a caller needs:
+
+```rust
+/// Parses a `key=value` line.
+///
+/// # Errors
+///
+/// Returns [`ParseError::MissingSeparator`] when the line has no `=`.
+///
+/// # Examples
+///
+/// ```
+/// # use my_crate::{parse_pair, ParseError};
+/// # fn main() -> Result<(), ParseError> {
+/// let (key, value) = parse_pair("port=8080")?;
+/// assert_eq!((key, value), ("port", "8080"));
+/// # Ok(())
+/// # }
+/// ```
+pub fn parse_pair(line: &str) -> Result<(&str, &str), ParseError> {
+    line.split_once('=').ok_or(ParseError::MissingSeparator)
+}
+```
+
+- `# Errors` for every public `Result`-returning function (`missing_errors_doc`), `# Panics` for every reachable panic (`missing_panics_doc`), `# Safety` for every public `unsafe fn` or `unsafe trait`, listing each obligation the caller takes on.
+- Examples use `?`, never `unwrap`; lines starting with `# ` compile but stay hidden, which is where imports and the `fn main() -> Result` wrapper go.
+- Link types with intra-doc links (``[`ParseError`]``). `RUSTDOCFLAGS="-D warnings" cargo doc` fails on a broken link, and `cargo test --doc` runs every example.
+- A crate's front page can be its README: `#![doc = include_str!("../README.md")]` makes the README's code blocks doctests too.

package/packages/omo-codex/plugin/skills/programming/references/rust/async-tokio.md

@@ -5,8 +5,8 @@ Structured concurrency, cancellation, blocking-work isolation, channel selection
 ## Runtime selection
 
 ```rust
-// Default for services and CLIs that do real work
-#[tokio::main(flavor = "multi_thread", worker_threads = 8)]
+// Default for services and CLIs that do real work: multi-thread, one worker per core
+#[tokio::main]
 async fn main() -> anyhow::Result<()> { ... }
 
 // For tiny CLIs or wasm where you measured single-thread is enough
@@ -14,7 +14,7 @@ async fn main() -> anyhow::Result<()> { ... }
 async fn main() -> anyhow::Result<()> { ... }
 ```
 
-Pick worker count explicitly. The default (`num_cpus`) is fine for servers; for desktop tools you usually want 2-4.
+Keep the default worker count. Set `worker_threads` only for a measured reason or a deployment constraint (a container CPU quota the runtime cannot see, a desktop tool sharing the machine). CPU-heavy work does not get more workers; it leaves the runtime (see Blocking work).
 
 ## Spawning
 
@@ -48,13 +48,14 @@ while let Some(joined) = set.join_next().await {
 - Dropping the set aborts every still-running task.
 - Lets you handle failures one by one rather than all-or-nothing.
 
-For wait-for-all semantics with one type, `join!`:
+For a fixed set of independent futures, `join!` waits for all; for fallible ones, `try_join!` returns on the first `Err`:
 
 ```rust
-let (a, b, c) = tokio::join!(load_a(), load_b(), load_c());
-let a = a?; let b = b?; let c = c?;
+let (a, b, c) = tokio::try_join!(load_a(), load_b(), load_c())?;
 ```
 
+On that first error `try_join!` drops the other futures mid-flight. Dropping is cancellation, not rollback: side effects they already started stay started (see Cancellation).
+
 For first-of-many, `select!`:
 
 ```rust
@@ -76,19 +77,19 @@ Without `biased`, branches are polled in random order each iteration (good for f
 
 A future is cancelled when it is dropped (e.g., the `select!` arm wins another branch). **Always think: if this future is dropped mid-await, what state is left behind?**
 
-Cancel-safe futures (you can drop without lasting effect):
-- `recv()` on channels
-- `accept()` on listeners
-- `wait_for` on `watch::Receiver`
-- `read_buf`/`write_all` on streams **only when buffers are owned by the future**, otherwise no
+Cancel-safe futures (you can drop them without losing data):
+- `recv()` on channels, `accept()` on listeners
+- `changed()` / `wait_for` on `watch::Receiver`
+- `AsyncReadExt::read` / `read_buf`: bytes land in your buffer only when the call completes
 
-Cancel-unsafe futures (dropping mid-way leaves partial state):
-- Manual `read_exact` into an external buffer
-- Custom futures that perform partial side effects before suspending
+Cancel-unsafe futures (dropping mid-way loses data or leaves partial state):
+- `read_exact`, `read_to_end`, `read_to_string`: bytes already read are gone
+- `write_all` / `write_all_buf`: an unknown prefix was already written
+- Custom futures that perform side effects before suspending
 
-If a function is cancel-unsafe, document it in a rustdoc `# Cancel Safety` section.
+Tokio documents cancel safety per method; check it for every future used as a `select!` branch in a loop. When an operation is cancel-unsafe, keep its progress outside the future (a buffer that lives across loop iterations) or move it into its own task. If your own function is cancel-unsafe, document it in a rustdoc `# Cancel Safety` section.
 
-To explicitly opt out of cancellation, use `tokio_util::sync::CancellationToken`:
+Cooperative cancellation of a whole task tree uses `tokio_util::sync::CancellationToken`: tasks watch the token and exit at a point they choose, so cleanup runs.
 
 ```rust
 use tokio_util::sync::CancellationToken;
@@ -135,7 +136,7 @@ let result = tokio::task::spawn_blocking(|| {
 }).await?;
 ```
 
-Long-running blocking jobs (more than ~1 second of CPU) → use a dedicated thread pool (`rayon`), not tokio's blocking pool which is sized for short bursts.
+Sustained CPU parallelism → a dedicated pool (`rayon`), not tokio's blocking pool, which is sized for many short blocking calls. The same rule covers the blocking std APIs that look harmless inside `async fn`: `std::thread::sleep` (use `tokio::time::sleep`), `std::fs::*` (use `tokio::fs`, or batch it into one `spawn_blocking`), and `blocking_recv` / `blocking_lock` (they panic inside a runtime).
 
 ## Channels
 
@@ -199,21 +200,31 @@ serve_sse(stream).await
 ```rust
 use tokio::signal;
 
+/// Resolves on Ctrl-C or SIGTERM. A signal source that cannot be installed is
+/// logged and never fires, so the other source still works.
 async fn shutdown_signal() {
-    let ctrl_c = async { signal::ctrl_c().await.expect("ctrl_c handler") };
+    let ctrl_c = async {
+        if let Err(error) = signal::ctrl_c().await {
+            tracing::error!(%error, "cannot listen for ctrl-c");
+            std::future::pending::<()>().await;
+        }
+    };
     #[cfg(unix)]
     let terminate = async {
-        signal::unix::signal(signal::unix::SignalKind::terminate())
-            .expect("install signal handler")
-            .recv()
-            .await;
+        match signal::unix::signal(signal::unix::SignalKind::terminate()) {
+            Ok(mut sigterm) => { sigterm.recv().await; }
+            Err(error) => {
+                tracing::error!(%error, "cannot listen for SIGTERM");
+                std::future::pending::<()>().await;
+            }
+        }
     };
     #[cfg(not(unix))]
     let terminate = std::future::pending::<()>();
 
     tokio::select! {
-        _ = ctrl_c => {},
-        _ = terminate => {},
+        () = ctrl_c => {},
+        () = terminate => {},
     }
     tracing::info!("shutdown signal received");
 }
@@ -224,7 +235,10 @@ async fn main() -> anyhow::Result<()> {
     let server = tokio::spawn(run_server(token.child_token()));
     shutdown_signal().await;
     token.cancel();
-    let _ = tokio::time::timeout(Duration::from_secs(10), server).await;
+    match tokio::time::timeout(Duration::from_secs(10), server).await {
+        Ok(joined) => joined??, // JoinError (panic) and the server's own error both surface
+        Err(_elapsed) => tracing::warn!("server did not stop within 10s"),
+    }
     Ok(())
 }
 ```
@@ -235,14 +249,16 @@ Pattern: catch signal → cancel a token shared with the server → server's `se
 
 - `tokio::sync::Mutex` — async mutex. Use for state shared between async tasks. **Do not hold across `.await` without thinking** (you'll serialize the whole system).
 - `tokio::sync::RwLock` — async read-write lock. Same caveat.
-- `parking_lot::Mutex` — sync mutex, faster than `std::sync::Mutex`, no poisoning. Use when the lock is held briefly and you do not need to `.await` while holding it.
+- `std::sync::Mutex` / `parking_lot::Mutex` — sync mutex for a critical section that never spans an `.await` (see [concurrency.md](concurrency.md) for choosing between them).
+- Nothing guard-like lives across an `.await`: not a sync lock guard, not a `watch` borrow ([concurrency.md](concurrency.md)), not a `span.enter()` guard. Instrument the future instead: `fut.instrument(span).await`.
 - `tokio::sync::Semaphore` — bound concurrent operations. Perfect for "max 10 in-flight HTTP requests" or "max 3 DB writers".
 
 ```rust
 let sem = Arc::new(tokio::sync::Semaphore::new(10));
+let mut set = JoinSet::new();
 for url in urls {
-    let permit = sem.clone().acquire_owned().await?;
-    tokio::spawn(async move {
+    let permit = Arc::clone(&sem).acquire_owned().await?;
+    set.spawn(async move {
         let _permit = permit;  // released on task end
         fetch(&url).await
     });
@@ -278,6 +294,8 @@ async fn fetches_and_parses() {
 async fn parallel_work() { ... }
 ```
 
+`current_thread` is the default test runtime; it chooses a scheduler, it does not make a test deterministic. Wait on the exact event (a channel message, a `Notify`, a `watch` change) or on paused virtual time below, never on a real `sleep`.
+
 For time-sensitive tests, advance virtual time:
 
 ```rust
@@ -290,6 +308,20 @@ async fn time_travel() {
 }
 ```
 
+## Async traits and async closures
+
+`async fn` in traits is stable (1.75) and dispatches statically:
+
+```rust
+trait Store {
+    async fn get(&self, key: &str) -> Result<Option<Vec<u8>>, StoreError>;
+}
+```
+
+Two limits: callers cannot require the returned future to be `Send` (spawning a generic `S: Store` call fails), and the trait is not `dyn`-compatible. For `Send` futures, declare the method as `fn get(&self, key: &str) -> impl Future<Output = ...> + Send;`. For `dyn Store`, box the future (`Pin<Box<dyn Future<Output = T> + Send + '_>>`) or use `async-trait`; pick `dyn` only for runtime heterogeneity.
+
+A parameter that is an async callback borrowing from its caller takes `F: AsyncFn(&Request) -> Response` (1.85, `std::ops::AsyncFn`), not `F: Fn(&Request) -> Fut`: the `Fut` form cannot name a future that borrows its argument.
+
 ## When NOT to use async
 
 - Single-threaded CPU-heavy code that does no I/O — plain `fn` + `rayon` is simpler and often faster.

package/packages/omo-codex/plugin/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