# `error-codes` — `AUTH_ANON.*` registry

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

## Purpose

Stable error-code registry for `@suaveplan/api-auth-anonymous`. The anonymous
resolver has no per-request failure modes — every request resolves to `null` by
construction. The single `AUTH_ANON.INVALID_OPTIONS` code covers the only thing
that can fail, which is rejecting malformed options handed to
`createAnonymousResolver(opts)` at construction time. Keeping a dedicated
code-namespace per package (rather than re-using `AUTH.*`) means consumers can
disambiguate anonymous-side problems from general session-resolver issues when
multiple resolvers are mounted on the same chain.

## Features

- Defined via `defineCodes("AUTH_ANON", [...])` from `@suaveplan/error` so the
  literal value is always `"AUTH_ANON.INVALID_OPTIONS"`.
- `AuthAnonError extends SuaveplanError<AuthAnonErrorCode>` — instance checks
  narrow `error.code` to the registry type at the type level.
- Carries `authAnonCode` as a non-discriminating mirror so adapter code can
  branch on `err.authAnonCode === AUTH_ANON_CODES.INVALID_OPTIONS` without
  re-typing the parent class.

## Usage: Basic

```ts
import { AUTH_ANON_CODES, AuthAnonError } from "@suaveplan/api-auth-anonymous/error-codes";

throw new AuthAnonError(
    AUTH_ANON_CODES.INVALID_OPTIONS,
    "createAnonymousResolver: options is not an object"
);
```

## Usage: Advanced

Wrap a parser failure (e.g. zod) and forward its details into the
`context.issues` slot so observability pipelines can render the schema diff:

```ts
import { AUTH_ANON_CODES, AuthAnonError } from "@suaveplan/api-auth-anonymous/error-codes";
import z from "zod";

const OptionsSchema = z.object({}).strict();

export function parseOptions(input: unknown): Record<string, never> {
    const out = OptionsSchema.safeParse(input);
    if (!out.success) {
        throw new AuthAnonError(
            AUTH_ANON_CODES.INVALID_OPTIONS,
            "Anonymous resolver options failed schema validation",
            { context: { issues: out.error.issues } }
        );
    }
    return out.data;
}
```

## API Reference

| Symbol               | Kind     | Description                                                |
|----------------------|----------|------------------------------------------------------------|
| `AUTH_ANON_CODES`    | const    | `{ INVALID_OPTIONS: "AUTH_ANON.INVALID_OPTIONS" }`         |
| `AuthAnonErrorCode`  | type     | Union of values in `AUTH_ANON_CODES`.                      |
| `AuthAnonError`      | class    | `extends SuaveplanError<AuthAnonErrorCode>`.               |

## Implementation Notes

- The single code is deliberate. The resolver is documented to never reject a
  request; adding speculative codes for "unrecognised credential" or
  "principal lookup failed" would be lying about a contract that the
  implementation cannot break by construction.
- Tested in `error-codes.test.ts` for both string value and instance shape.