first commit

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

@@ -0,0 +1,77 @@
+# `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.