# `IMESSAGE_*` error registry

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

## Purpose

Defines the stable, fully-qualified error-code registry for
`@suaveplan/imessage-adapter`. Every error class in this module
inherits from `@suaveplan/error`'s `SuaveplanError` base and carries
one of the ten `IMESSAGE.*` codes returned by `defineCodes("IMESSAGE",
[...])`. Consumers downstream — loggers, problem+json renderers, retry
wrappers, OTel attribute writers — map on the code, never on the
message or class identity, so the codes are part of the public API.

## Features

- Ten production codes, each thrown from at least one real call site:
  `DB_OPEN_FAILED`, `DB_QUERY_FAILED`, `WATCHER_NOT_RUNNING`,
  `WATCHER_ALREADY_RUNNING`, `ADAPTER_NOT_INITIALIZED`,
  `INVALID_CONFIG`, `POLL_ABORTED`, `POLL_FAILED`,
  `ATTACHMENT_PARSE_FAILED`, `APPLE_DATE_PARSE_FAILED`.
- One typed error class per code, all extending the abstract
  `IMessageError` so consumers can pattern-match via `instanceof
  IMessageError` for a single catch site.
- `IMessageInvalidConfigError` accepts a `issues` payload that is
  merged into `context` so callers can recover the Zod issue array
  from problem+json bodies.
- Frozen `IMESSAGE_CODES` record keeps the literal-typed union
  reachable through the public surface.

## Usage: Basic

```ts
import {
    IMessageAdapterNotInitializedError,
} from "@suaveplan/imessage-adapter";

throw new IMessageAdapterNotInitializedError();
```

## Usage: Advanced

```ts
import {
    IMessageError,
    IMessageInvalidConfigError,
    IMESSAGE_CODES,
} from "@suaveplan/imessage-adapter";

try {
    parseWatcherConfig(input);
} catch (err) {
    if (err instanceof IMessageInvalidConfigError) {
        console.error(err.code, err.context["issues"]);
    } else if (err instanceof IMessageError) {
        switch (err.code) {
            case IMESSAGE_CODES.WATCHER_ALREADY_RUNNING:
            case IMESSAGE_CODES.WATCHER_NOT_RUNNING:
                // recoverable
                break;
            default:
                throw err;
        }
    } else {
        throw err;
    }
}
```

## API Reference

- `const IMESSAGE_CODES`: frozen record `{ DB_OPEN_FAILED:
  "IMESSAGE.DB_OPEN_FAILED", ... }`.
- `type IMessageErrorCode`: union of every fully-qualified code.
- `abstract class IMessageError extends SuaveplanError<IMessageErrorCode>`.
- One concrete class per code, each accepting `{ cause?, context?,
  traceId?, message? }`.

## Implementation Notes

The module side-effect-imports nothing; the registry is purely
declarative. The package barrel (`src/index.ts`) side-effect-imports
`./error-codes/index.js` so subpath consumers also observe the
registration. Messages default to i18n keys (`imessage.errors.*`) so
callers can supply their own resolver if they wish.