igmarin/agent-profiles/error-handling

Error handling

Apply the execution contract before this procedure.

Goal

Recoverable failure is Result. Panics are bugs, not control flow.

Inputs / outputs

• In: a fallible operation
• Out: Result<T, E> with a useful E, or a typed panic only for invariants

Reads / writes

• Read: the fallible fn and its callers
• Write: none unless a playbook opened the task

Approval

Adding thiserror / anyhow if they are not already in Cargo.toml.

RULES — no exceptions

1. Library crates: preserve the existing typed error API; use a small handwritten enum or existing thiserror dependency implementing Error and needed conversions
2. Binary / app crates: use the existing error convention; anyhow with .context() is an option when already installed, not a required dependency
3. ? to propagate; From impls make ? work
4. No .unwrap() on user/IO/parse paths
5. .expect("…") only for proven invariants (a bug if it fires)
6. Messages: lowercase, no trailing punctuation
7. Preserve source (#[source] / .context())
8. Document # Errors on public fallible fns

Example

use std::num::NonZeroU16;
 
// ❌
let n: u16 = s.parse().unwrap();
 
// ✅ lib
#[derive(Debug, thiserror::Error)]
enum ParsePortError {
    #[error("not a number")]
    Num(#[from] std::num::ParseIntError),
    #[error("port must be non-zero")]
    Zero,
}
 
fn parse_port(s: &str) -> Result<NonZeroU16, ParsePortError> {
    let n: u16 = s.parse()?;
    NonZeroU16::new(n).ok_or(ParsePortError::Zero)
}

Steps

1. Classify: recoverable vs invariant
2. Recoverable → Result + ?
3. If the crate is a lib, keep E typed; if a bin, anyhow is enough

Validation

No new unwrap/expect on IO/parse. cargo test covers the error variant.

Pitfalls

Integration

Predecessor: rust-essentials. Successor: none.