# ADR-002: stdlib errors Compatibility

**Status:** Accepted
**Date:** 2026-03-18

## Context

Go's `errors` package defines two key behaviours that all well-behaved error types
must support: `errors.Is` for sentinel comparison and `errors.As` for type
assertion down a cause chain. Code that wraps errors (e.g. a repository that wraps
a database error) must not break these traversal mechanisms when it introduces its
own error type.

Additionally, consumers — particularly HTTP handlers and log enrichers — need to
extract typed information (`Code`, key-value fields) without performing unsafe type
assertions directly in business logic.

## Decision

`*Err` implements `Unwrap() error`, which exposes the optional cause set via
`Wrap(code, msg, cause)` or `.WithError(cause)`. This makes the full cause chain
visible to `errors.Is` and `errors.As`.

Two private duck-typing interfaces are satisfied without any import dependency on
the consumer packages:

- `ErrorCode() string` — returns the string value of the `Code`. logz checks for
  this interface via `errors.As` and, when found, appends an `error_code` field to
  the log record automatically.
- `ErrorContext() map[string]any` — returns the raw context fields map. logz checks
  for this interface via `errors.As` and appends all key-value pairs to the log record.

`*Err` also implements `json.Marshaler`, producing
`{"code":"...","message":"...","fields":{...}}` suitable for direct use in API
error responses.

The compliance test (`compliance_test.go`) uses compile-time nil-pointer assertions
to enforce these contracts. If any method is removed or its signature changes, the
build fails immediately rather than at a distant call site in another module.

## Consequences

- `errors.Is(err, io.ErrUnexpectedEOF)` and `errors.As(err, &target)` work through
  `*Err` boundaries without any special casing.
- logz and xerrors are fully decoupled at the import level: neither imports the
  other. The duck-type bridge is maintained by the private interfaces.
- `Fields()` returns a shallow copy for safe external use; `ErrorContext()` returns
  the raw map for logz's internal read-only use — a deliberate split to avoid
  allocating a copy on every log call.
- The `MarshalJSON` shape (`code`, `message`, `fields`) is part of the public API
  contract. Changing field names is a breaking change for any caller that depends on
  the JSON representation.