# `errors/errors.ts` — typed error hierarchy

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

This module exposes the typed error surface for `@suaveplan/emblem-solver`.
It defines the stable, namespaced code registry `EMBLEM_SOLVER_CODES` and
the `EmblemSolverError` class that extends `SuaveplanError`. Every failure
path inside the package — schema validation, grid validation, IO checks —
funnels through this hierarchy so callers can pattern-match on `error.code`
to distinguish user input mistakes from defensive guards.

## Features

- Codes are produced by `defineCodes("EMBLEM_SOLVER", [...] as const)`,
  yielding the namespaced strings `EMBLEM_SOLVER.INVALID_GRID`,
  `EMBLEM_SOLVER.INVALID_OPTIONS`, and `EMBLEM_SOLVER.INVALID_PIXEL`.
- The registry is frozen — consumers can rely on identity equality across
  the module.
- `EmblemSolverError` extends `SuaveplanError<EmblemSolverCode>`, so
  `error.code` narrows the union and `instanceof EmblemSolverError`
  discriminates the throw site.
- Supports the full `SuaveplanErrorOptions` bag: `cause`, `context`,
  `traceId`, and `clock` for testing.

## Usage: Basic

```ts
import {
    EMBLEM_SOLVER_CODES,
    EmblemSolverError,
} from "@suaveplan/emblem-solver/errors";

if (badInput) {
    throw new EmblemSolverError(
        EMBLEM_SOLVER_CODES.INVALID_GRID,
        "emblem-solver.invalid_grid"
    );
}
```

## Usage: Advanced

```ts
try {
    convert(pixels, w, h, options);
} catch (err) {
    if (err instanceof EmblemSolverError) {
        switch (err.code) {
            case EMBLEM_SOLVER_CODES.INVALID_OPTIONS:
                return reportInputProblem(err);
            case EMBLEM_SOLVER_CODES.INVALID_GRID:
                return reportShapeProblem(err);
            case EMBLEM_SOLVER_CODES.INVALID_PIXEL:
                return reportPixelProblem(err);
        }
    }
    throw err;
}
```

## API Reference

| Symbol | Kind | Description |
|---|---|---|
| `EMBLEM_SOLVER_CODES` | const | Frozen `{ INVALID_GRID, INVALID_OPTIONS, INVALID_PIXEL }` map |
| `EmblemSolverCode` | type | Union of the namespaced strings |
| `EmblemSolverError` | class | `extends SuaveplanError<EmblemSolverCode>` |

## Implementation Notes

`defineCodes` runs at module load and `Object.freeze`s the registry,
guaranteeing identity stability — consumers that import via the root barrel
or the `./errors` subpath see the same object. The class constructor is
deliberately thin: it forwards to `SuaveplanError`'s `protected` constructor
and sets `name = "EmblemSolverError"` so stack frames disambiguate. The
`INVALID_PIXEL` code is reserved for future use (it appears in the code
registry so consumers can switch on it ahead of any algorithmic change that
introduces an unrepresentable RGBA value); the test suite exercises it via
the round-trip code coverage check.