first commit

docs/foundation/data/pwa/src/errors/errors.md

@@ -0,0 +1,74 @@
+# `errors/errors.ts`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Defines the `PWA_CODES` stable error-code registry, the `PwaError` base class, and
+the frozen `PWA_ERROR_METADATA` table mapping every code to its HTTP status,
+severity, retryability, and human-readable description. Every error thrown or
+reported by `@suaveplan/pwa` carries one of these codes so retry strategies,
+logger pipelines, and observability sinks can classify failures without
+string-matching on the `Error.message`. Codes are namespaced under `PWA.*`.
+
+## Features
+
+- 8 stable codes covering every documented failure path (service-worker
+  unsupported / registration / update, push unsupported / permission, sync-queue
+  full / validation, manifest validation).
+- `PwaError extends SuaveplanError` so the project's logger and wire serialiser
+  treat the error identically to every other domain error.
+- Frozen `PWA_ERROR_METADATA` table with `{ httpStatus, severity, retryable,
+  description }` per code.
+
+## Usage: Basic
+
+```ts
+import { PWA_CODES, PwaError } from "@suaveplan/pwa";
+
+throw new PwaError(
+    PWA_CODES.SW_REGISTRATION_FAILED,
+    "Service worker registration failed for /sw.js"
+);
+```
+
+## Usage: Advanced
+
+Inspect metadata for retry decisions:
+
+```ts
+import { PWA_ERROR_METADATA, PwaError, PWA_CODES } from "@suaveplan/pwa";
+
+function shouldRetry(err: unknown): boolean {
+    if (!(err instanceof PwaError)) return false;
+    return PWA_ERROR_METADATA[err.code].retryable;
+}
+
+const err = new PwaError(
+    PWA_CODES.SW_UPDATE_FAILED,
+    "ServiceWorkerRegistration.update rejected",
+    { cause: new Error("Network down") }
+);
+console.assert(shouldRetry(err));
+```
+
+## API Reference
+
+- `PWA_CODES` — frozen record of `{ [Reason]: "PWA.<Reason>" }`.
+- `PwaErrorCode` — union of every documented code.
+- `PwaCodeMetadata` — `{ httpStatus, severity, retryable, description }`.
+- `PWA_ERROR_METADATA` — frozen mapping of every `PwaErrorCode` to its metadata.
+- `PwaError` — base error class, subclass of `SuaveplanError`.
+
+## Implementation Notes
+
+`PWA_ERROR_METADATA` is constructed with `Object.freeze` so consumers cannot mutate
+classifications at runtime. The class name is set to `PwaError` in the constructor
+so `error.name` matches the export name across every JS engine (including those
+that minimise class names). Codes are defined via `defineCodes("PWA", [...])`
+from `@suaveplan/error` to keep the namespace prefix in one place and to type the
+returned codes as template-literal strings (`"PWA.SW_UNSUPPORTED"`, etc.). This
+allows literal-typed unions in `PwaError<TCode>` without the implementation
+needing to thread the namespace string through every callsite.