spec: M092_001 — structured error codes and context for cache_kit::Error

[indykish]

Summary

First v0.9.2 milestone spec. Converts the 850-line proposal at plans/error-codes-improvement.md into a 284-line goal-contract spec following the freshly-updated dotfiles/docs/TEMPLATE.md (see indykish/dotfiles#16).

No code yet — this PR is the spec only. Implementation happens after the spec lands on main, on a separate feat/m092-error-codes branch per the lifecycle.

What the spec defines

Additive-only changes to the v0.9.x error surface — no breaking changes, ships in 0.9.2:

• ErrorCode enum (#[repr(u32)]) with stable codes in documented numeric ranges.
• ErrorContext struct (cache_key, operation) via builder methods on Error.
• New accessors on Error: code(), context(), is_retryable(), http_status().
• Backwire codes through every existing Err(Error::...) construction site in src/.
• User-facing error-handling page at site/content/integration/error-handling.mdx (hand-authored catalog).

Existing Error variant tuple shapes are preserved → consumers' match patterns keep compiling.

What's deliberately out of scope

• Wire format / JSON serialization of errors. Deferred to v1.0 alongside a settled wire format.
• Breaking changes to existing variant shapes. v1.0 concern.
• i18n translation tables. Stable codes deliver this benefit indirectly; tables are downstream.
• Catalog page codegen from the enum. Hand-authored for v0.9.2; v1.0 concern.
• The other 11 items in plans/comprehensive-code-review.md (circuit breaker, observability, cache warming, etc.) — each gets its own spec when picked up.

How this spec is shaped

Five sections in the prologue point the implementing agent at the exact files to read before touching anything (src/error.rs, src/expander.rs, both backend mappers, examples/actixsqlx/, plus the source proposal for intent only). The spec does not contain Rust pseudocode — every interface is named at contract level, every test is named with prose-only assertions, every invariant names its enforcement mechanism (compile-time exhaustive match, golden-blob test, runtime check).

Invariants worth highlighting

1. Code stability — once shipped, ErrorCode::Foo.as_u32() never changes. Enforced by a golden-blob test pinned to tests/fixtures/error_codes.golden.
2. Exhaustive variant mapping — Error::code() must map every variant. Adding a new variant without updating the mapping fails to compile.
3. Tuple-shape preservation — every existing variant's tuple/struct shape is byte-identical to 0.9.0. Regression-tested via pattern-match on every variant.
4. is_retryable() matches the retry loop — src/expander.rs::retry_with_backoff retries iff error.code().is_retryable(). Drift between the two breaks production retry behavior.

Test plan

• Read the spec top-to-bottom. Confirm the prologue (5 file pointers) gives enough context to plan implementation without 20-questions.
• Confirm no inlined Rust code blocks in section bodies (Anti-Patterns gate).
• Confirm every Failure Modes row has a matching test in Test Specification.
• Confirm Acceptance Criteria are command-verifiable, not vibes.
• Confirm Out of Scope explicitly carves out the v1.0 work (wire format, breaking changes).
• Once spec lands on `main`: open `feat/m092-error-codes` per CHORE(open), move spec to `docs/v0.9.2/active/`, set Status: IN_PROGRESS.

🤖 Generated with Claude Code

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (main@2be07bf). Learn more about missing BASE report.
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@           Coverage Diff           @@
##             main       #3   +/-   ##
=======================================
  Coverage        ?   73.03%           
=======================================
  Files           ?       14           
  Lines           ?     2173           
  Branches        ?        0           
=======================================
  Hits            ?     1587           
  Misses          ?      586           
  Partials        ?        0           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[indykish]

Consolidated into #2 (docs/nextjs-netlify-migration). Same spec content, single PR.