# `errors/errors.ts`

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

## Purpose

Defines the stable error-code registry and the concrete `OverviewError`
subclass of `SuaveplanError`. Every public entry point in `@suaveplan/overview`
that throws does so through this class, so callers can rely on a single
`instanceof OverviewError` check and a literal-typed `code` field for
discrimination.

The registry has six entries — one per failure mode that the package can
detect — and the §2c "never delete spec elements to satisfy a gate" rule means
each entry is exercised by a real call site somewhere in `src/`, asserted by
the static test `every code has a real call site in src/`.

## Features

- Six stable codes registered through `defineCodes("OVERVIEW", [...])`
- Frozen, fully-inferred code record — `OVERVIEW_CODES.PARSE_FAILED` is the
  literal `"OVERVIEW.PARSE_FAILED"`
- `OverviewCode` closed union for exhaustive switch statements
- `OverviewError` extends `SuaveplanError<OverviewCode>` so `instanceof`
  narrows `error.code`
- Preserves cause chain, context, and trace-id propagation via
  `SuaveplanErrorOptions`

## Usage: Basic

```ts
import { OverviewError, OVERVIEW_CODES } from "@suaveplan/overview";

throw new OverviewError(
  OVERVIEW_CODES.UNKNOWN_PACKAGE,
  "overview.unknown_package",
  { context: { pkg: "@suaveplan/missing" } },
);
```

## Usage: Advanced

```ts
import { OverviewError } from "@suaveplan/overview";

try {
  // ...
} catch (err) {
  if (err instanceof OverviewError) {
    switch (err.code) {
      case "OVERVIEW.CYCLE_DETECTED":
        // type-narrowed; safe to read err.context?.cycle
        break;
      case "OVERVIEW.PARSE_FAILED":
        break;
      default:
        break;
    }
  }
  throw err;
}
```

The exhaustive `switch` benefits from `OverviewCode` being a closed union —
adding a new code without handling it in a downstream `switch` is a TypeScript
error.

## API Reference

- `OVERVIEW_CODES` — `Readonly<{PARSE_FAILED, INVALID_RECORD, CYCLE_DETECTED,
  UNKNOWN_PACKAGE, DISCOVERY_ABORTED, INVALID_TIER}>` with literal `OVERVIEW.<X>`
  values
- `type OverviewCode` — closed union of every value in `OVERVIEW_CODES`
- `class OverviewError extends SuaveplanError<OverviewCode>` — constructor
  `(code, messageKey, options?)`

## Implementation Notes

The `defineCodes` helper from `@suaveplan/error` freezes its return value so the
registry cannot be mutated at runtime. `OverviewError` deliberately re-exposes
the `protected` constructor of `SuaveplanError` as `public` (the language
requires each subclass to do this explicitly) so callers can `new` an instance
directly without a factory. The class is final by convention — sub-classing it
would dilute `instanceof` narrowing.