Errors are part of the interface

The code-snippets design brief14 requires an author-facing error for each rejected snippet.

Each error carries:

Invalid metadata keeps its raw values. It has no decoded request yet.

The author needs the rejected input, its location, and a repair instruction. A stack trace alone cannot supply them.

Use the error model36 to separate expected failures from defects. Use schema decoding17 to reject invalid input at the boundary. Use error accumulation9 to report unrelated failures together.

Related reading: Exceptional Ruby and Confident Ruby, both by Avdi Grimm.

See the glossary for diagnostic context and repair instruction.

Sources

  1. Avdi Grimm's books. Avdi Grimm. Author and titles only; no claims about book contents. Accessed 2026-10-02.
  2. Effect Schema. Effect contributors. Typed errors Accessed 2026-10-02.
  3. Code-snippets design brief. Primary source. Proposed diagnostic contract Accessed 2026-10-02.

Last changed 2026-10-07 in 989f258. Source on GitHub. Change log.

Linked from

  1. Accumulate independent errors before writing output. Check every independent job before any job writes an asset.

    Report each failure with diagnostic context.¶

  2. Agent guide. An Effect stack so pure (aspirational) Kit Langton will blush.

    Errors are part of the interface — An author error needs a location, the rejected input, and a repair.

  3. Change log. What changed in the files served here, newest first.

    Errors are part of the interface — edited: fix(lore): re-pin the CLI failure excerpt and link glossary first uses

  4. Code snippets quote a pinned source. Shipped design brief: pinned Git objects, typed diagnostics, and one build-only snippet model for both views.

    Errors are part of the interface.

  5. Full agent guide. An Effect stack so pure (aspirational) Kit Langton will blush.
  6. Handle expected failures without hiding defects. Declare expected failures, preserve their context, and recover by tag without turning crashes into successful outcomes.

    See also: schemas, author-facing diagnostics, independent failures, and lifecycles.¶

  7. Rat Stack lore | rat-stack. Short, source-grounded notes on the ideas and decisions behind rat-stack.

    Errors are part of the interface — An author error needs a location, the rejected input, and a repair.

  8. Source change history (log.md). The generated change log as Markdown.

    Errors are part of the interface — edited: fix(lore): re-pin the CLI failure excerpt and link glossary first uses