# `error-codes` — stable code registry for the static-principal adapter

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

## Purpose

Defines the `AUTH_STATIC_PRINCIPAL.*` error-code namespace and the
`AuthStaticPrincipalError` concrete subclass of
`@suaveplan/error/SuaveplanError`. This module is the single source of truth
for every failure code the package can surface to a caller — wiring this
registry into the host's error envelope is how a malformed test-time
Principal configuration reaches the developer rather than silently producing a
broken auth chain.

Codes are produced via `defineCodes("AUTH_STATIC_PRINCIPAL", [...])` so the
full literal value is e.g. `"AUTH_STATIC_PRINCIPAL.INVALID_OPTIONS"`. The
class augments the base error with `authStaticPrincipalCode`, providing a
narrowed code property when consumers have already discriminated by
`instanceof`.

## Features

- Stable, frozen `AUTH_STATIC_PRINCIPAL_CODES` map built via `defineCodes` so
  the prefix can't drift.
- Discriminated-union friendly: `AuthStaticPrincipalErrorCode` is a literal
  union over the registry entries.
- Carries arbitrary `context` (Zod issues, the offending field path) via the
  base `SuaveplanError` options bag.

## Usage: Basic

```ts
import {
    AUTH_STATIC_PRINCIPAL_CODES,
    AuthStaticPrincipalError,
} from "@suaveplan/api-auth-static-principal/error-codes";

throw new AuthStaticPrincipalError(
    AUTH_STATIC_PRINCIPAL_CODES.INVALID_OPTIONS,
    "createStaticPrincipalResolver: options failed schema validation"
);
```

## Usage: Advanced

Attach Zod issues so the caller can pinpoint the bad field without re-running
validation:

```ts
import {
    AUTH_STATIC_PRINCIPAL_CODES,
    AuthStaticPrincipalError,
} from "@suaveplan/api-auth-static-principal/error-codes";
import z from "zod";

const parsed = OptionsSchema.safeParse(input);
if (!parsed.success) {
    throw new AuthStaticPrincipalError(
        AUTH_STATIC_PRINCIPAL_CODES.INVALID_PRINCIPAL,
        "principal failed schema validation",
        { context: { issues: parsed.error.issues } }
    );
}
```

## API Reference

| Symbol                              | Kind     | Description                                                              |
| ----------------------------------- | -------- | ------------------------------------------------------------------------ |
| `AUTH_STATIC_PRINCIPAL_CODES`       | constant | Frozen map of code constants. Keys are the short names; values are full. |
| `AuthStaticPrincipalErrorCode`      | type     | Literal union over the registry values.                                  |
| `AuthStaticPrincipalError`          | class    | `SuaveplanError` subclass typed against the code registry.               |

## Implementation Notes

`defineCodes` joins the prefix with each suffix using a single `.` so the
resulting strings match the host's structured-log code field. The class
stores the code twice — once in the inherited `code` slot and once in the
narrower `authStaticPrincipalCode` slot — so callers that already narrowed by
`instanceof` get a precisely-typed code field without a follow-up `as`.

The package's static-principal resolver never throws at request time; both
codes are construction-time only. This is deliberate — every per-request
failure for fixed-principal tests should manifest in the test assertion, not
in the auth pipeline.