first commit

docs/api-stack/api/api-auth/src/error-codes/error-codes.md

@@ -0,0 +1,84 @@
+# `error-codes` — `AUTH_CODES` registry
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Defines the stable, namespaced error-code registry for the `@suaveplan/api-auth`
+package and the concrete `AuthError` class. Every code is reachable from a
+production throw site somewhere in the package (chain construction, chain
+execution, adapter registration, or principal-shape validation). The registry
+is frozen via `defineCodes("AUTH", […])` so accidental drift between thrown
+codes and the documented set is impossible.
+
+Consumers — including downstream concrete resolvers in Stages 4/6/8 such as
+`api-auth-jwt`, `api-auth-anonymous`, and `api-auth-bearer-static` — branch on
+the string literal (`"AUTH.RESOLVER_THREW"` etc.) or compare to the constant
+(`AUTH_CODES.RESOLVER_THREW`). The literal form is preferred at the API
+boundary; the constant is preferred inside the package itself so the linter
+flags typos as type errors.
+
+## Features
+
+- Frozen string-literal union of all four codes.
+- `AuthError` extends `SuaveplanError<AuthErrorCode>` so `instanceof AuthError`
+  narrows `code` correctly.
+- Cause-chain propagation: the optional `options.cause` field is forwarded to
+  the base class.
+- Public constructor (the base class is `protected`).
+
+## Usage: Basic
+
+```ts
+import { AUTH_CODES, AuthError } from "@suaveplan/api-auth/error-codes";
+
+if (chain.length === 0) {
+    throw new AuthError(AUTH_CODES.CHAIN_EMPTY, "at least one resolver required");
+}
+```
+
+## Usage: Advanced
+
+Re-throw a resolver error with a cause chain and inspect it downstream:
+
+```ts
+import { AUTH_CODES, AuthError } from "@suaveplan/api-auth/error-codes";
+
+try {
+    await resolver.resolve(req);
+} catch (cause) {
+    throw new AuthError(AUTH_CODES.RESOLVER_THREW, "resolver A threw", {
+        cause,
+        context: { resolverIndex: 0 },
+    });
+}
+```
+
+```ts
+import { AuthError } from "@suaveplan/api-auth/error-codes";
+
+if (err instanceof AuthError && err.code === "AUTH.RESOLVER_THREW") {
+    logger.warn("upstream session resolver failed", { cause: err.cause });
+}
+```
+
+## API Reference
+
+| Symbol         | Kind   | Description                                                     |
+|----------------|--------|-----------------------------------------------------------------|
+| `AUTH_CODES`   | const  | Frozen lookup `{ RESOLVER_THREW, CHAIN_EMPTY, … }`.             |
+| `AuthErrorCode`| type   | Literal union of the four code strings.                          |
+| `AuthError`    | class  | Concrete `SuaveplanError` subclass narrowed to `AuthErrorCode`. |
+
+## Implementation Notes
+
+- `defineCodes("AUTH", [...] as const)` produces an object literal with
+  string-literal value types, which is what gives `AuthErrorCode` its narrow
+  union. Removing `as const` would widen the type to `string`.
+- The class field `authCode` mirrors `code` for ergonomic narrowing on
+  pre-instantiated error objects (some test runners obscure the inherited
+  `code` field via Proxy wrappers).
+- Code values follow the `AUTH.<UPPER_SNAKE>` template enforced by
+  `@suaveplan/api-types`' `ErrorCode` template literal type.