apiVersion: conventions/v1
version: 0.1.0
updated: "2026-06-29"
name: error_handling_logging
title: Error handling & structured logging (cross-language)
scope: general
status: active
summary: Typed errors with cause chaining, no silent swallows, structured logging (never stdout in libraries), specific exception types. The shared spirit across TS/Py/Rust/GD.
appliesTo: ["**/*"]
rules:
  - id: typed_errors
    level: must
    text: "Domain-specific typed errors (TS Error subclasses, Py exception classes, Rust thiserror enums, GD explicit failure paths). Never a bare string thrown."
  - id: cause_chaining
    level: must
    text: "Errors carry context up the stack: TS `{ cause }`, Py `raise ... from exc`, Rust `#[from]`/source."
  - id: no_silent_swallow
    level: must
    text: "No empty catch / `except: pass` / discarded Result. Handle, rethrow, or log+rethrow — never swallow."
  - id: structured_logging
    level: must
    text: "Structured logger, not stdout, in libraries (no console.log / print() / println!). MCP/stdio processes log to stderr only."
  - id: lazy_log_format
    level: should
    text: "Python: lazy %-formatting in log calls (logger.info('x=%s', x)), not f-strings."
  - id: observable_failures
    level: should
    text: "Failures are observable (logged with context / push_error in GD), never silent returns."