first commit

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

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