@damiangilgonzalez/harness 1.3.7

package/skills/rust/references/async-tokio.md

@@ -0,0 +1,141 @@
+# Async on tokio
+
+Depth behind SKILL.md's async section. tokio 1.x, edition 2024.
+
+## Runtime model
+
+A future is a state machine that does nothing until polled. `.await` yields control back to the
+executor at each suspension point. `#[tokio::main]` expands to building a multi-thread runtime and
+calling `block_on` on your `main` body:
+
+```rust
+#[tokio::main]                  // multi-thread runtime by default
+async fn main() -> anyhow::Result<()> {
+    // ... build state, serve ...
+    Ok(())
+}
+```
+
+For tests use `#[tokio::test]`; for a single-threaded runtime (e.g. `!Send` work) use
+`#[tokio::main(flavor = "current_thread")]`.
+
+## Structured concurrency with JoinSet
+
+`JoinSet` owns its tasks and lets you bound and drain them — the antidote to a loop of bare
+`tokio::spawn`:
+
+```rust
+use tokio::task::JoinSet;
+
+async fn fetch_all(ids: Vec<i64>) -> anyhow::Result<Vec<Record>> {
+    let mut set = JoinSet::new();
+    for id in ids {
+        set.spawn(async move { fetch_one(id).await });   // spawned task must be Send + 'static
+    }
+    let mut out = Vec::new();
+    while let Some(joined) = set.join_next().await {
+        out.push(joined??);          // first ? = JoinError (panic/cancel), second ? = task error
+    }
+    Ok(out)
+}
+```
+
+To cap *in-flight* tasks (not just collect them), pair spawning with an `Arc<Semaphore>` and acquire a
+permit before each spawn.
+
+## select! and cancellation
+
+`tokio::select!` polls several futures and runs the first to complete, dropping the rest. Wire a
+cancellation token into one arm so a shutdown signal aborts the work:
+
+```rust
+use tokio_util::sync::CancellationToken;
+
+async fn worker(token: CancellationToken) {
+    loop {
+        tokio::select! {
+            _ = token.cancelled() => break,            // shutdown wins -> exit the loop
+            item = next_item() => process(item).await, // otherwise keep working
+        }
+    }
+}
+```
+
+Dropping a future cancels it at its current `.await` point — so make sure anything mid-flight is
+either idempotent or transactional.
+
+## Channels (tokio::sync)
+
+- `mpsc` — many producers, one consumer. Bounded (`channel(n)`) gives backpressure; prefer it over
+  unbounded. The default for a work queue.
+- `oneshot` — a single value back from a spawned task.
+- `broadcast` — fan a value out to many receivers.
+- `watch` — latest-value observation (config reload, shutdown flags).
+
+Prefer a channel over `Arc<Mutex<T>>` when the data flows one direction — it sidesteps the
+lock-across-await trap entirely.
+
+## spawn_blocking
+
+The async worker threads are few; a blocking call on one starves every task scheduled there. Move
+CPU-bound or synchronous-blocking work off the runtime:
+
+```rust
+let hash = tokio::task::spawn_blocking(move || bcrypt_hash(&password)).await?;
+```
+
+For long-lived dedicated threads (not request-scoped) use `std::thread` + a channel back into async.
+
+## Send + Sync across await
+
+A future is `Send` only if every value alive across an `.await` is `Send`. The classic failure:
+
+```rust
+// Bad: std Mutex guard is not Send; held across .await -> "future cannot be sent between threads safely".
+let g = state.lock().unwrap();
+remote_call().await;            // g still alive
+g.update();
+
+// Good: scope the guard so it is dropped before the await.
+{ state.lock().unwrap().update(); }
+remote_call().await;
+
+// Or, when the lock must span the await, use tokio's async Mutex.
+let mut g = async_state.lock().await;
+g.update_after(remote_call().await);
+```
+
+`Rc`, `RefCell`, and raw pointers are not `Send` either — none of them survive an `.await` in a
+spawned task. Use `Arc`/atomics instead.
+
+## Bounded concurrency + jittered retry helper
+
+Cancellation-aware, never retries a 4xx (client errors are not transient):
+
+```rust
+use std::time::Duration;
+use rand::Rng;
+
+async fn with_retry<F, Fut, T>(max: u32, mut op: F) -> anyhow::Result<T>
+where
+    F: FnMut() -> Fut,
+    Fut: std::future::Future<Output = Result<T, AppError>>,
+{
+    let mut attempt = 0;
+    loop {
+        match op().await {
+            Ok(v) => return Ok(v),
+            Err(e) if e.is_client_error() => return Err(e.into()), // 4xx: do not retry
+            Err(_) if attempt + 1 >= max => return Err(anyhow::anyhow!("exhausted {max} retries")),
+            Err(_) => {
+                let base = 50u64 << attempt;                       // exponential
+                let jitter = rand::thread_rng().gen_range(0..base.max(1)); // full jitter
+                tokio::time::sleep(Duration::from_millis(base + jitter)).await;
+                attempt += 1;
+            }
+        }
+    }
+}
+```
+
+Wrap the whole thing in `tokio::time::timeout(dur, fut).await` to cap total wall time.

package/skills/rust/references/axum-service.md

@@ -0,0 +1,132 @@
+# axum 0.8 service skeleton
+
+The full HTTP surface behind SKILL.md's essentials. axum 0.8, tokio 1.x, tower middleware.
+
+## Shared state
+
+`AppState` holds the dependencies (DB pool, config, clients). Wrap in `Arc`, inject via `State`:
+
+```rust
+use std::sync::Arc;
+use sqlx::PgPool;
+
+#[derive(Clone)]
+pub struct AppState {
+    pub pool: PgPool,            // PgPool is itself an Arc internally; clone is cheap
+}
+
+pub type Shared = Arc<AppState>;
+```
+
+## Error enum -> IntoResponse
+
+One enum, one mapping. Pattern-match the variant; log only the unexpected; never leak internals.
+
+```rust
+use axum::{http::StatusCode, response::{IntoResponse, Response}, Json};
+use serde_json::json;
+use thiserror::Error;
+
+#[derive(Debug, Error)]
+pub enum ApiError {
+    #[error("not found")]
+    NotFound,
+    #[error("invalid input: {0}")]
+    BadRequest(String),
+    #[error(transparent)]
+    Db(#[from] sqlx::Error),     // `?` on a query lifts sqlx::Error into ApiError
+}
+
+impl IntoResponse for ApiError {
+    fn into_response(self) -> Response {
+        let (status, msg) = match &self {
+            ApiError::NotFound => (StatusCode::NOT_FOUND, "not found".to_string()),
+            ApiError::BadRequest(m) => (StatusCode::BAD_REQUEST, m.clone()),
+            ApiError::Db(e) => {
+                tracing::error!(error = %e, "db error"); // log server-side only
+                (StatusCode::INTERNAL_SERVER_ERROR, "internal error".to_string())
+            }
+        };
+        (status, Json(json!({ "error": msg }))).into_response()
+    }
+}
+```
+
+## Handlers and router
+
+```rust
+use axum::{extract::{Path, State}, routing::get, Json, Router};
+
+async fn get_user(
+    State(state): State<Shared>,
+    Path(id): Path<i64>,                          // {id} parsed to i64; bad input -> 400 automatically
+) -> Result<Json<User>, ApiError> {
+    let user = sqlx::query_as!(User, "SELECT id, name FROM users WHERE id = $1", id)
+        .fetch_optional(&state.pool)
+        .await?                                   // sqlx::Error -> ApiError::Db
+        .ok_or(ApiError::NotFound)?;              // None -> 404
+    Ok(Json(user))
+}
+
+async fn healthz() -> StatusCode { StatusCode::OK }
+
+async fn readyz(State(state): State<Shared>) -> StatusCode {
+    match sqlx::query("SELECT 1").execute(&state.pool).await {
+        Ok(_) => StatusCode::OK,
+        Err(_) => StatusCode::SERVICE_UNAVAILABLE, // 503 when the DB is unreachable
+    }
+}
+
+pub fn build_router(state: Shared) -> Router {
+    Router::new()
+        .route("/users/{id}", get(get_user))      // axum 0.8: {id}, not :id
+        .route("/healthz", get(healthz))
+        .route("/readyz", get(readyz))
+        .with_state(state)
+}
+```
+
+## Tower middleware
+
+Compose cross-cutting concerns as layers (outermost runs first on the request):
+
+```rust
+use std::time::Duration;
+use tower_http::{trace::TraceLayer, timeout::TimeoutLayer, request_id::PropagateRequestIdLayer};
+
+let app = build_router(state)
+    .layer(TraceLayer::new_for_http())            // span + structured access logs via tracing
+    .layer(TimeoutLayer::new(Duration::from_secs(10)))
+    .layer(PropagateRequestIdLayer::x_request_id());
+```
+
+## main + graceful shutdown
+
+```rust
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    tracing_subscriber::fmt().json().init();
+
+    let pool = PgPool::connect(&std::env::var("DATABASE_URL")?).await?;
+    let state = Arc::new(AppState { pool });
+    let app = build_router(state);
+
+    let listener = tokio::net::TcpListener::bind("0.0.0.0:8080").await?;
+    axum::serve(listener, app)
+        .with_graceful_shutdown(shutdown_signal())  // drain in-flight requests on SIGTERM/Ctrl-C
+        .await?;
+    Ok(())
+}
+
+async fn shutdown_signal() {
+    let ctrl_c = async { tokio::signal::ctrl_c().await.expect("install Ctrl-C handler"); };
+    #[cfg(unix)]
+    let term = async {
+        tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate())
+            .expect("install SIGTERM handler").recv().await;
+    };
+    #[cfg(not(unix))]
+    let term = std::future::pending::<()>();
+    tokio::select! { _ = ctrl_c => {}, _ = term => {} }
+}
+```

package/skills/rust/references/ownership.md

@@ -0,0 +1,86 @@
+# Ownership, borrowing, lifetimes
+
+Deep dive on the model SKILL.md front-loads. Read this when the borrow checker is in your way.
+
+## Move vs borrow vs clone
+
+Every value has exactly one owner. Three things can happen when you pass it:
+
+- **Move** — ownership transfers; the source binding is dead afterward. Default for non-`Copy` types
+  (`String`, `Vec<T>`, structs holding them).
+- **Borrow** — `&T` (shared, many at once, read-only) or `&mut T` (exclusive, exactly one, read-write).
+  No transfer; the owner keeps the value.
+- **Clone** — `.clone()` makes an independent copy. Real cost (allocation for heap types). Legitimate
+  when you genuinely need two independent owners; a smell when used only to dodge a borrow error.
+
+`Copy` types (`i32`, `bool`, `f64`, `char`, small tuples of `Copy`) are bitwise-copied on assignment, so
+they are never "moved away" — no E0382 for them.
+
+Rule of thumb for APIs: **borrow on the way in, own on the way out.** Take `&str`/`&[T]`, return
+`String`/`Vec<T>`. Take `impl AsRef<str>` when you want to accept both `&str` and `String` ergonomically.
+
+## The borrow-checker error catalog
+
+| Error | Meaning | Typical fix |
+| --- | --- | --- |
+| E0382 "value moved here" / "borrow of moved value" | Used a value after moving it | Borrow instead of move; clone only if two owners are truly needed |
+| E0499 "cannot borrow as mutable more than once" | Two `&mut` overlap | Scope the first borrow so it ends before the second |
+| E0502 "already borrowed as immutable" | `&mut` while a `&` is live | Don't mutate through one path while reading through another; collect first, mutate after |
+| E0505 "cannot move out … borrowed" | Moved a value that is still borrowed | End the borrow (drop/scope) before moving |
+| E0597 "does not live long enough" | A reference outlives its referent | Return an owned value, or make the owner outlive the borrow |
+| E0515 "returns a reference to data owned by the current function" | Returning a borrow of a local | Return the owned value, or take the buffer as a `&mut` param |
+
+Non-lexical lifetimes mean a borrow ends at its last *use*, not at the end of the block — so often just
+reordering statements (move the read before the write) resolves E0502 with no restructuring.
+
+## Lifetimes & `'static`
+
+A lifetime annotation (`'a`) names how long a reference is valid; the compiler infers most of them
+(elision). You only annotate when a function returns a reference whose lifetime ties to an input:
+
+```rust
+// The returned &str lives as long as the input slice.
+fn first_word<'a>(s: &'a str) -> &'a str {
+    s.split_whitespace().next().unwrap_or("")
+}
+```
+
+`'static` means "valid for the whole program" — string literals are `&'static str`. `T: 'static` as a
+bound (common in `tokio::spawn`) means "contains no non-`'static` references", i.e. it owns its data; it
+does **not** mean the value lives forever. Prefer owned data over lifetime-threaded structs when the
+lifetimes get noisy — a `String` field is simpler than a `&'a str` field that infects every caller.
+
+## `Cow` — clone on write
+
+`Cow<'_, str>` lets a function return a borrow when it can and an owned value only when it must:
+
+```rust
+use std::borrow::Cow;
+fn normalize(input: &str) -> Cow<'_, str> {
+    if input.contains(' ') { Cow::Owned(input.replace(' ', "_")) } // allocate only when changed
+    else { Cow::Borrowed(input) }                                  // zero-copy fast path
+}
+```
+
+## Smart pointers — the full tree
+
+```text
+Need a value on the heap / a trait object / recursion?  -> Box<T>
+Shared ownership, single-threaded?                       -> Rc<T>
+Shared ownership, across threads or .await?              -> Arc<T>
+Mutate through a shared ref, single-threaded?            -> RefCell<T>   (runtime borrow check)
+Mutate through a shared ref, single-threaded + Rc?       -> Rc<RefCell<T>>
+Mutate shared state across threads (sync)?               -> Arc<Mutex<T>> / Arc<RwLock<T>>
+Mutate shared state across .await?                       -> Arc<tokio::sync::Mutex<T>> (or a channel)
+```
+
+`Rc`/`RefCell` are **not** thread-safe and will not compile across threads — the compiler enforces it via
+`Send`/`Sync`. Reach for `Arc` the moment a value crosses a thread or an `.await` point.
+
+## Interior mutability
+
+`RefCell<T>` moves the borrow check to runtime: `.borrow()` / `.borrow_mut()` panic on a violation
+(two mutable borrows). Use it only when the compile-time check is genuinely too strict (e.g. a graph,
+an observer registry). For atomics and counters prefer `std::sync::atomic` types or `Mutex`; for
+shared async state prefer a channel (message passing) over `Arc<Mutex<T>>` (shared memory) whenever the
+data really flows in one direction.

package/skills/rust/references/testing.md

@@ -0,0 +1,108 @@
+# Testing Rust services
+
+Behind SKILL.md's testing essentials. Unit, integration, doctests, async, fakes.
+
+## Unit tests
+
+Co-locate in a `#[cfg(test)] mod tests` block; they can reach private items in the same module.
+
+```rust
+fn slugify(s: &str) -> String { s.trim().to_lowercase().replace(' ', "-") }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn slugify_lowercases_and_dashes() {
+        assert_eq!(slugify("  Hello World "), "hello-world");
+    }
+}
+```
+
+A data-driven shape (Rust's "table test"): iterate over a slice of cases.
+
+```rust
+#[test]
+fn parse_cases() {
+    let cases = [("42", Some(42)), ("x", None)];
+    for (input, want) in cases {
+        assert_eq!(parse(input), want, "input = {input}");
+    }
+}
+```
+
+## Async tests
+
+```rust
+#[tokio::test]
+async fn fetch_returns_record() {
+    let repo = FakeRepo::with(vec![Record::new(1)]);
+    let got = service::fetch(&repo, 1).await.unwrap();
+    assert_eq!(got.id, 1);
+}
+```
+
+## Integration tests against the Router
+
+Files in `tests/` are separate crates that link the **public** API (so logic must live in `lib.rs`, not
+`main.rs`). Drive the real `Router` with `tower::ServiceExt::oneshot` — no network, no port:
+
+```rust
+// tests/users_api.rs
+use axum::{body::Body, http::{Request, StatusCode}};
+use tower::ServiceExt;
+use my_service::{build_router, test_state};
+
+#[tokio::test]
+async fn get_user_404_when_missing() {
+    let app = build_router(test_state());
+    let res = app
+        .oneshot(Request::get("/users/999").body(Body::empty()).unwrap())
+        .await
+        .unwrap();
+    assert_eq!(res.status(), StatusCode::NOT_FOUND);
+}
+```
+
+## Fakes via traits
+
+Depend on a trait, not a concrete DB type, so unit tests inject a fake without a database:
+
+```rust
+#[async_trait::async_trait]      // still needed for `dyn` trait objects in some versions; native async fn covers static dispatch
+pub trait UserRepo: Send + Sync {
+    async fn find(&self, id: i64) -> Result<Option<User>, ApiError>;
+}
+
+struct FakeRepo(Vec<User>);
+#[async_trait::async_trait]
+impl UserRepo for FakeRepo {
+    async fn find(&self, id: i64) -> Result<Option<User>, ApiError> {
+        Ok(self.0.iter().find(|u| u.id == id).cloned())
+    }
+}
+```
+
+For sqlx integration tests against a real DB, `#[sqlx::test]` provisions an isolated test database per
+test and rolls it back.
+
+## Doctests
+
+Examples in `///` docs are compiled and run by `cargo test --doc` — they cannot rot silently:
+
+```rust
+/// Slugifies a title.
+///
+/// ```
+/// assert_eq!(my_service::slugify("Hello World"), "hello-world");
+/// ```
+pub fn slugify(s: &str) -> String { /* ... */ }
+```
+
+## Tooling
+
+- `cargo nextest run` — faster, isolated, clearer parallel test output than `cargo test` (it does not
+  run doctests; keep `cargo test --doc` in the gate).
+- `insta` — snapshot testing for JSON/response bodies; `cargo insta review` to accept diffs.
+- Run the whole gate via `scripts/verify.sh` (fmt + clippy + test + audit).

package/skills/rust/scripts/verify.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+#
+# verify.sh - local quality gate for a Rust crate/workspace (superset of CI).
+#
+# Usage:
+#   cd <your-crate-root>      # the directory containing Cargo.toml
+#   ./verify.sh
+#
+# Runs: cargo fmt --check, cargo clippy -D warnings, cargo test, and cargo audit (if installed).
+# Read-only: it never mutates your source.
+# Degrades gracefully: if there is no Cargo.toml or no `cargo` on PATH, it prints a skip
+# note and exits 0 (a clean/empty target is not a failure). Tools that are not installed
+# are skipped with a warning, not a failure. Real problems exit non-zero.
+#
+# Portability: stock macOS bash 3.2 (no mapfile, no associative arrays).
+
+set -euo pipefail
+
+# Colors only when stdout is a TTY (keeps logs/CI output clean).
+if [ -t 1 ]; then
+  YELLOW=$'\033[33m'; RED=$'\033[31m'; GREEN=$'\033[32m'; RESET=$'\033[0m'
+else
+  YELLOW=''; RED=''; GREEN=''; RESET=''
+fi
+
+failed=0
+
+have()  { command -v "$1" >/dev/null 2>&1; }
+warn()  { printf '%s[skip]%s %s\n' "$YELLOW" "$RESET" "$*"; }
+fail()  { printf '%s[fail]%s %s\n' "$RED" "$RESET" "$*"; failed=1; }
+ok()    { printf '%s[ ok ]%s %s\n' "$GREEN" "$RESET" "$*"; }
+info()  { printf -- '----- %s\n' "$*"; }
+
+# No manifest? Nothing to verify - skip cleanly (do not fail an empty target).
+if [ ! -f Cargo.toml ]; then
+  warn "no Cargo.toml in $(pwd) - nothing to verify (cd into your crate root to run the gate)."
+  exit 0
+fi
+
+# No toolchain? Skip cleanly.
+if ! have cargo; then
+  warn "cargo not found - install the Rust toolchain (https://rustup.rs) to run the gate."
+  exit 0
+fi
+
+# 1. cargo fmt --check - formatting is non-negotiable; --check never rewrites files.
+info "cargo fmt --check"
+if cargo fmt --all -- --check; then
+  ok "formatting clean"
+else
+  fail "unformatted code (run: cargo fmt --all)"
+fi
+
+# 2. cargo clippy -D warnings - lints are correctness gates here, not style suggestions.
+info "cargo clippy -- -D warnings"
+if have cargo-clippy || cargo clippy --version >/dev/null 2>&1; then
+  if cargo clippy --all-targets --all-features -- -D warnings; then
+    ok "clippy clean"
+  else
+    fail "clippy reported warnings/errors"
+  fi
+else
+  warn "clippy not found (rustup component add clippy)"
+fi
+
+# 3. cargo test - unit + integration; add --doc separately for doctests if desired.
+info "cargo test"
+if cargo test --all-targets; then
+  ok "tests pass"
+else
+  fail "tests failed"
+fi
+
+# 4. cargo audit - optional; RustSec advisory findings are a real failure.
+info "cargo audit"
+if have cargo-audit || cargo audit --version >/dev/null 2>&1; then
+  if cargo audit; then
+    ok "no known vulnerabilities"
+  else
+    fail "cargo audit found advisories"
+  fi
+else
+  warn "cargo audit not found (cargo install cargo-audit)"
+fi
+
+echo
+if [ "$failed" -ne 0 ]; then
+  printf '%sFAIL:%s one or more checks failed.\n' "$RED" "$RESET"
+  exit 1
+fi
+printf '%sPASS:%s all checks passed.\n' "$GREEN" "$RESET"