Initial Commit

packages/foundation/random/noise/src/errors/index.ts

@@ -0,0 +1 @@
+export { NOISE_CODES, type NoiseCode, NoiseError } from "./noise-error";

packages/foundation/random/noise/src/errors/noise-error.md

@@ -0,0 +1,65 @@
+# noise-error
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+The `noise-error` module exports the `NoiseError` class and `NOISE_CODES` registry used by every public function in `@suaveplan/noise`. Centralising validation failures here keeps upstream error handling simple: callers only need to match on a single `NOISE.*` code prefix regardless of which noise function raised the error.
+
+## Features
+
+- Stable, namespaced error codes via `defineCodes("NOISE", [...])`
+- `NoiseError` extends `SuaveplanError<NoiseCode>` with the usual cause-chain, redaction, and OTel integrations
+- Coverage for argument validation, blue-noise termination guards and fBm octave validation
+
+## Usage: Basic Example
+
+```ts
+import { NoiseError, NOISE_CODES } from "@suaveplan/noise/errors";
+
+throw new NoiseError(
+  NOISE_CODES["ARG.INVALID"],
+  "noise.arg.invalid",
+  { context: { field: "frequency" } },
+);
+```
+
+## Usage: Advanced Example
+
+```ts
+import { NoiseError, NOISE_CODES } from "@suaveplan/noise/errors";
+
+try {
+  // ... sample blue noise over a huge radius ...
+} catch (err) {
+  if (err instanceof NoiseError && err.code === NOISE_CODES["BLUE.MAX_SAMPLES_EXCEEDED"]) {
+    // back off and retry with a larger spacing
+  }
+  throw err;
+}
+```
+
+## API Reference
+
+- `NOISE_CODES` — frozen registry.
+- `NoiseError(code, messageKey, options?)` — structured error with `context`, `cause`, `traceId`, `clock` options.
+
+## Implementation Notes
+
+All codes sit under the `NOISE.*` namespace so they don't collide with `@suaveplan/pseudo-random` or `@suaveplan/random` codes. Adding new codes is strictly additive — removing them requires a major version bump.
+
+### Subclasses & Codes
+
+`NoiseError` is the `instanceof` pivot for every error thrown by `@suaveplan/noise`. Concrete subclasses cover invalid seed, invalid octave count, out-of-range frequency, and invalid amplitude. Every subclass carries a stable code from the `NOISE` namespace (`NOISE.INVALID_SEED`, `NOISE.OCTAVES.OUT_OF_RANGE`, etc.) so callers can type-narrow on `error.code` without string-matching the message. Inherits wire serialisation and OTel span-event support from `SuaveplanError`.
+
+## Further Usage: Basic Example
+
+```ts
+import { NoiseError } from "@suaveplan/noise/errors/noise-error";
+try {
+    throw new NoiseError("invalid seed", { code: "NOISE.INVALID_SEED" });
+} catch (e) {
+    if (e instanceof NoiseError) console.log(e.code);
+}
+```

packages/foundation/random/noise/src/errors/noise-error.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from "@suaveplan/testing/runner";
+import { NOISE_CODES, NoiseError } from "./noise-error.js";
+
+describe("NoiseError", () => {
+    it("carries namespaced code", { timeout: 5000 }, () => {
+        const err = new NoiseError(
+            NOISE_CODES["ARG.INVALID"],
+            "noise.arg.invalid"
+        );
+        expect(err.code).toBe("NOISE.ARG.INVALID");
+        expect(err).toBeInstanceOf(NoiseError);
+    });
+
+    it("accepts context + cause", { timeout: 5000 }, () => {
+        const cause = new Error("x");
+        const err = new NoiseError(
+            NOISE_CODES["FBM.INVALID_OCTAVES"],
+            "noise.fbm.invalid_octaves",
+            { context: { octaves: 0 }, cause }
+        );
+        expect(err.context).toEqual({ octaves: 0 });
+        expect(err.cause).toBe(cause);
+    });
+});

packages/foundation/random/noise/src/errors/noise-error.ts

@@ -0,0 +1,25 @@
+import {
+    defineCodes,
+    SuaveplanError,
+    type SuaveplanErrorOptions,
+} from "@suaveplan/error";
+
+export const NOISE_CODES = defineCodes("NOISE", [
+    "ARG.INVALID",
+    "ARG.OUT_OF_RANGE",
+    "BLUE.MAX_SAMPLES_EXCEEDED",
+    "FBM.INVALID_OCTAVES",
+] as const);
+
+export type NoiseCode = (typeof NOISE_CODES)[keyof typeof NOISE_CODES];
+
+export class NoiseError extends SuaveplanError<NoiseCode> {
+    // biome-ignore lint/complexity/noUselessConstructor: widens visibility
+    public constructor(
+        code: NoiseCode,
+        messageKey: string,
+        options?: SuaveplanErrorOptions
+    ) {
+        super(code, messageKey, options);
+    }
+}