@codenhub/error 0.0.1 → 0.1.0

package/README.md

@@ -10,12 +10,12 @@ pnpm add @codenhub/error
 
 ## Usage
 
-Configure the app-level `AppError.registry` during initialization, then normalize thrown or returned unknown values into a predictable error shape.
+Configure the app-level global registry retrieved by `getErrorRegistry()` during initialization, then normalize thrown or returned unknown values into a predictable error shape using `createAppError()`.
 
 ```ts
-import { AppError, err, ok, type Result } from "@codenhub/error";
+import { createAppError, getErrorRegistry, err, ok, type Result } from "@codenhub/error";
 
-AppError.registry.codes.add("invalid_credentials", {
+getErrorRegistry().codes.add("invalid_credentials", {
   message: "Invalid email or password.",
   messageKey: "error.auth.invalidCredentials",
   source: "auth",
@@ -29,7 +29,7 @@ const signIn = async (): Promise<Result<string>> => {
   }
 };
 
-const appError = new AppError({ code: "invalid_credentials" });
+const appError = createAppError({ code: "invalid_credentials" });
 
 console.log(appError.message, appError.messageKey);
 ```
@@ -37,12 +37,12 @@ console.log(appError.message, appError.messageKey);
 Ready registries are opt-in. Merge them into an app-owned registry when the app wants those classifications.
 
 ```ts
-import { AppError } from "@codenhub/error";
+import { getErrorRegistry } from "@codenhub/error";
 import { browserErrorRegistry } from "@codenhub/error/registries/browser";
 import { supabaseErrorRegistry } from "@codenhub/error/registries/supabase";
 
-AppError.registry.merge(browserErrorRegistry);
-AppError.registry.merge(supabaseErrorRegistry);
+getErrorRegistry().merge(browserErrorRegistry);
+getErrorRegistry().merge(supabaseErrorRegistry);
 ```
 
 ## Reference
@@ -53,11 +53,16 @@ Primary entrypoint for app-owned registries, error normalization, and result hel
 
 ```ts
 import {
-  AppError,
+  createAppError,
+  isAppError,
   DEFAULT_APP_ERROR_MESSAGE,
   createErrorRegistry,
+  getErrorRegistry,
+  setErrorRegistry,
+  freezeRegistry,
   err,
   ok,
+  type AppError,
   type AppErrorOptions,
   type AppErrorSource,
   type AppErrorType,
@@ -70,6 +75,7 @@ import {
   type ErrorRegistry,
   type ErrorRegistryBucket,
   type Ok,
+  type ReadonlyErrorRegistry,
   type Result,
 } from "@codenhub/error";
 ```
@@ -83,15 +89,72 @@ Supported import paths:
 | `@codenhub/error/registries/browser`  | Browser and Web API error mappings.                     |
 | `@codenhub/error/registries/supabase` | Supabase error mappings.                                |
 
+#### `createAppError()`
+
+Normalizes an unknown value into a predictable `AppError` object. By default, it classifies errors with the active global error registry.
+
+```ts
+function createAppError(error: unknown, options?: AppErrorOptions): AppError;
+```
+
+If no registry mapping matches, it uses `DEFAULT_APP_ERROR_MESSAGE` or `fallbackMessage` and classifies the value as `"unknown"`.
+
+#### `isAppError()`
+
+Type guard to check if a value is a normalized `AppError`.
+
+```ts
+function isAppError(value: unknown): value is AppError;
+```
+
+#### `AppError` Interface
+
+Predictable normalized error shape extending the native `Error` class.
+
+```ts
+interface AppError extends Error {
+  readonly type: "known" | "unexpected" | "unknown";
+  readonly message: string;
+  readonly messageKey: string | null;
+  readonly source: string | null;
+  readonly originalError: unknown;
+  readonly isRetryable: boolean;
+}
+```
+
+#### `getErrorRegistry()`
+
+Retrieves the active global error registry.
+
+```ts
+function getErrorRegistry(): ErrorRegistry;
+```
+
+#### `setErrorRegistry()`
+
+Sets the active global error registry.
+
+```ts
+function setErrorRegistry(registry: ErrorRegistry): void;
+```
+
 #### `createErrorRegistry()`
 
-Creates an empty isolated registry. This is also available as `AppError.createRegistry()`.
+Creates an empty isolated registry.
 
 ```ts
-function createErrorRegistry(): ErrorRegistry;
+function createErrorRegistry(presets?: readonly (ErrorRegistry | ReadonlyErrorRegistry)[]): ErrorRegistry;
 ```
 
-Use isolated registries for tests, request scopes, tenant-specific mappings, or integrations where mappings should not use the app-level `AppError.registry`.
+Use isolated registries for tests, request scopes, tenant-specific mappings, or integrations where mappings should not use the active global registry.
+
+#### `freezeRegistry()`
+
+Wraps an ErrorRegistry in a read-only Proxy to prevent future mutations.
+
+```ts
+function freezeRegistry(registry: ErrorRegistry): ReadonlyErrorRegistry;
+```
 
 #### `DEFAULT_APP_ERROR_MESSAGE`
 
@@ -103,7 +166,7 @@ const DEFAULT_APP_ERROR_MESSAGE = "An unexpected error occurred.";
 
 #### `ErrorRegistry`
 
-Stores deterministic and heuristic mappings used by `AppError`.
+Stores deterministic and heuristic mappings used by `createAppError`.
 
 ```ts
 interface ErrorRegistry {
@@ -113,13 +176,27 @@ interface ErrorRegistry {
   prefixes: ErrorPrefixRegistryBucket;
   patterns: ErrorPatternRegistryBucket;
   clear(): void;
-  merge(registry: ErrorRegistry): void;
+  merge(registry: ErrorRegistry | ReadonlyErrorRegistry): void;
+}
+```
+
+#### `ReadonlyErrorRegistry`
+
+Read-only view of a registry returned by `freezeRegistry`. Exposes only the read-facing surface of each bucket. Pass it directly to `createErrorRegistry` presets or `merge`.
+
+```ts
+interface ReadonlyErrorRegistry {
+  readonly codes: Pick<ErrorRegistryBucket, "get" | "values">;
+  readonly names: Pick<ErrorRegistryBucket, "get" | "values">;
+  readonly messages: Pick<ErrorRegistryBucket, "get" | "values">;
+  readonly prefixes: Pick<ErrorPrefixRegistryBucket, "values">;
+  readonly patterns: Pick<ErrorPatternRegistryBucket, "values">;
 }
 ```
 
 Code, name, exact message, and prefix matches are deterministic known errors. When multiple prefixes match the same message, the longest normalized prefix wins. Pattern matches are heuristic and should be treated as unexpected errors with better user-facing feedback.
 
-`AppError.registry` is mutable and starts empty. `createErrorRegistry()` creates another empty registry with the same bucket API.
+The global error registry is mutable and starts empty. `createErrorRegistry()` creates another empty registry with the same bucket API.
 
 Registry buckets support adding one mapping at a time or a tuple list:
 
@@ -128,6 +205,7 @@ interface ErrorRegistryBucket {
   add(identifier: string, feedback: ErrorFeedback): void;
   addList(entries: readonly (readonly [identifier: string, feedback: ErrorFeedback])[]): void;
   clear(): void;
+  delete(identifier: string): boolean;
   get(identifier: string): ErrorFeedback | undefined;
   values(): IterableIterator<[string, ErrorFeedback]>;
 }
@@ -136,6 +214,7 @@ interface ErrorPrefixRegistryBucket {
   add(prefix: string, feedback: ErrorFeedback): void;
   addList(entries: readonly (readonly [prefix: string, feedback: ErrorFeedback])[]): void;
   clear(): void;
+  delete(prefix: string): boolean;
   values(): readonly ErrorPrefixDefinition[];
 }
 
@@ -143,13 +222,14 @@ interface ErrorPatternRegistryBucket {
   add(pattern: RegExp, feedback: ErrorFeedback): void;
   addList(entries: readonly (readonly [pattern: RegExp, feedback: ErrorFeedback])[]): void;
   clear(): void;
+  delete(pattern: RegExp): boolean;
   values(): readonly ErrorPatternDefinition[];
 }
 ```
 
 `values()` returns defensive copies. Pattern buckets clone `RegExp` values so global or sticky regex state does not leak across classifications.
 
-`add()` and `addList()` validate entries immediately and throw `TypeError` for invalid input. Exact and prefix identifiers must be non-empty strings after trimming whitespace and trailing sentence punctuation. Exact identifiers are stored and looked up in that normalized form. Feedback must be an object with a non-empty `message`; optional `messageKey` and `source` values must be strings, and optional `retryable` must be a boolean. Pattern buckets only accept `RegExp` patterns.
+`add()` and `addList()` validate entries immediately and throw `TypeError` for invalid input. Exact and prefix identifiers must be non-empty strings after trimming whitespace and trailing sentence punctuation. Exact identifiers are stored and looked up in that normalized form. Feedback must be an object with a non-empty `message`; optional `messageKey` and `source` values must be strings, and optional `isRetryable` must be a boolean. Pattern buckets only accept `RegExp` patterns.
 
 #### `ErrorFeedback`
 
@@ -160,11 +240,11 @@ interface ErrorFeedback {
   message: string;
   messageKey?: string;
   source?: string;
-  retryable?: boolean;
+  isRetryable?: boolean;
 }
 ```
 
-`message` should be safe to show to users. `messageKey`, `source`, and `retryable` are optional metadata copied onto matched `AppError` instances.
+`message` should be safe to show to users. `messageKey`, `source`, and `isRetryable` are optional metadata copied onto matched `AppError` instances.
 
 #### `ErrorPrefixDefinition` and `ErrorPatternDefinition`
 
@@ -182,29 +262,6 @@ interface ErrorPatternDefinition extends ErrorFeedback {
 
 Most consumers only need these when inspecting, copying, or testing registry contents.
 
-#### `AppError`
-
-Normalizes an unknown value into a predictable error object. By default, it classifies errors with `AppError.registry`.
-
-```ts
-class AppError extends Error {
-  static readonly registry: ErrorRegistry;
-
-  static createRegistry(): ErrorRegistry;
-
-  readonly type: "known" | "unexpected" | "unknown";
-  readonly message: string;
-  readonly messageKey: string | null;
-  readonly source: string | null;
-  readonly originalError: unknown;
-  readonly retryable: boolean;
-
-  constructor(error: unknown, options?: AppErrorOptions);
-}
-```
-
-`AppError` does not throw during construction. If no registry mapping matches, it uses `DEFAULT_APP_ERROR_MESSAGE` or `fallbackMessage` and classifies the value as `"unknown"`.
-
 #### `AppErrorType` and `AppErrorSource`
 
 Reusable property types for consumers that store or pass around normalized error metadata.
@@ -220,13 +277,15 @@ type AppErrorSource = string | null;
 interface AppErrorOptions {
   fallbackMessage?: string;
   registry?: ErrorRegistry;
+  maxDepth?: number;
 }
 ```
 
-| Option            | Type            | Default                     | Description                                   |
-| ----------------- | --------------- | --------------------------- | --------------------------------------------- |
-| `fallbackMessage` | `string`        | `DEFAULT_APP_ERROR_MESSAGE` | Message used when no mapping matches.         |
-| `registry`        | `ErrorRegistry` | `AppError.registry`         | Registry used to classify the provided error. |
+| Option            | Type            | Default           | Description                                                                           |
+| ----------------- | --------------- | ----------------- | ------------------------------------------------------------------------------------- |
+| `fallbackMessage` | `string`        | `DEFAULT_APP_...` | Message used when no mapping matches.                                                 |
+| `registry`        | `ErrorRegistry` | Global registry   | Registry used to classify the provided error.                                         |
+| `maxDepth`        | `number`        | `3`               | Maximum depth when unwrapping nested error wrappers (`cause`, `originalError`, etc.). |
 
 #### `ok()`
 
@@ -258,6 +317,36 @@ Represents success or failure without exceptions.
 type Result<T> = { ok: true; value: T } | { ok: false; error: AppError };
 ```
 
+#### `unwrap()`
+
+Unwraps a `Result`, returning the value if successful, or throwing the normalized `AppError` if failed.
+
+```ts
+function unwrap<T>(result: Result<T>): T;
+```
+
+#### `map()`
+
+Maps the success value of a `Result` using the provided mapper function.
+
+```ts
+function map<T, U>(result: Result<T>, mapper: (value: T) => U): Result<U>;
+```
+
+#### `match()`
+
+Pattern matches on a `Result`, executing the corresponding callback based on the outcome.
+
+```ts
+function match<T, U>(
+  result: Result<T>,
+  callbacks: {
+    readonly onOk: (value: T) => U;
+    readonly onErr: (error: AppError) => U;
+  },
+): U;
+```
+
 ### `@codenhub/error/registries`
 
 Index entrypoint for ready registry presets.
@@ -266,9 +355,9 @@ Index entrypoint for ready registry presets.
 import { browserErrorRegistry, supabaseErrorRegistry } from "@codenhub/error/registries";
 ```
 
-Ready registries are plain `ErrorRegistry` values intended to be merged into `AppError.registry` or another app-owned registry. Importing a preset does not mutate `AppError.registry`.
+Ready registries are plain `ErrorRegistry` values intended to be merged into the global registry or another app-owned registry. Importing a preset does not mutate the global registry.
 
-The preset registry objects are mutable like any other `ErrorRegistry`. Treat imported presets as shared read-only inputs and merge them into an app-owned registry before adding app-specific mappings.
+The preset registry objects are frozen and read-only. Merge them into an app-owned registry before adding app-specific mappings.
 
 ### `@codenhub/error/registries/browser`
 
@@ -314,19 +403,19 @@ const result = err(new DOMException("Aborted", "AbortError"), { registry: errors
 ### Merge Presets
 
 ```ts
-import { AppError } from "@codenhub/error";
+import { getErrorRegistry } from "@codenhub/error";
 import { browserErrorRegistry, supabaseErrorRegistry } from "@codenhub/error/registries";
 
-AppError.registry.merge(browserErrorRegistry);
-AppError.registry.merge(supabaseErrorRegistry);
+getErrorRegistry().merge(browserErrorRegistry);
+getErrorRegistry().merge(supabaseErrorRegistry);
 ```
 
 ### Add Multiple Mappings
 
 ```ts
-import { AppError } from "@codenhub/error";
+import { getErrorRegistry } from "@codenhub/error";
 
-AppError.registry.codes.addList([
+getErrorRegistry().codes.addList([
   ["invalid_credentials", { message: "Invalid email or password.", source: "auth" }],
   ["email_not_confirmed", { message: "Email address is not confirmed.", source: "auth" }],
 ]);
@@ -342,5 +431,9 @@ AppError.registry.codes.addList([
 ## Notes
 
 - Registries are opt-in by design. Consumers start from a blank registry to avoid hidden global classifications.
-- Registries, including `AppError.registry` and ready registry presets, are currently mutable. Configure shared registries during app initialization and avoid mutating imported presets at runtime. A future version is expected to provide stronger mutation safeguards.
+- The global error registry is mutable. Ready registry presets are frozen and read-only. Configure registries during app initialization.
 - Preset registries should prefer stable error codes or names over message matching when a library provides them.
+
+## License
+
+This project is licensed under the [Apache-2.0](LICENSE) license.

package/dist/bucket.js

@@ -0,0 +1,167 @@
+//#region src/bucket.ts
+const ERROR_IDENTIFIER_TRAILING_PUNCTUATION_PATTERN = /[.!?]+$/;
+/**
+* Normalizes an error identifier by trimming whitespace and stripping trailing punctuation (like `.`, `!`, `?`).
+*
+* @internal
+* @param identifier - The raw error identifier string.
+* @returns The normalized error identifier string.
+*/
+const normalizeErrorIdentifier = (identifier) => {
+	return identifier.trim().replace(ERROR_IDENTIFIER_TRAILING_PUNCTUATION_PATTERN, "");
+};
+/**
+* Asserts that an identifier normalizes to a non-empty string.
+*
+* @throws TypeError - If the identifier is empty after normalization.
+* @internal
+*/
+const assertNonEmptyIdentifier = (identifier, label) => {
+	if (typeof identifier !== "string" || normalizeErrorIdentifier(identifier).length === 0) throw new TypeError(`Error registry ${label} must be a non-empty string.`);
+};
+/**
+* Validates that a feedback object has the required shape and field types.
+*
+* @throws TypeError - If feedback is missing or has invalid field types.
+* @internal
+*/
+const assertFeedback = (feedback) => {
+	if (typeof feedback !== "object" || feedback === null) throw new TypeError("Error registry feedback must be an object.");
+	if (typeof feedback.message !== "string" || feedback.message.trim().length === 0) throw new TypeError("Error registry feedback.message must be a non-empty string.");
+	if (feedback.messageKey !== void 0 && typeof feedback.messageKey !== "string") throw new TypeError("Error registry feedback.messageKey must be a string when provided.");
+	if (feedback.source !== void 0 && typeof feedback.source !== "string") throw new TypeError("Error registry feedback.source must be a string when provided.");
+	if (feedback.isRetryable !== void 0 && typeof feedback.isRetryable !== "boolean") throw new TypeError("Error registry feedback.isRetryable must be a boolean when provided.");
+};
+/** @internal */
+const cloneFeedback = (feedback) => ({ ...feedback });
+/**
+* Creates a feedback map bucket for exact identifier matching (codes, names, messages).
+*
+* @internal
+*/
+const createFeedbackMapBucket = () => {
+	const entries = /* @__PURE__ */ new Map();
+	const add = (identifier, feedback) => {
+		assertNonEmptyIdentifier(identifier, "identifier");
+		assertFeedback(feedback);
+		entries.set(normalizeErrorIdentifier(identifier), cloneFeedback(feedback));
+	};
+	return {
+		add,
+		addList(errorEntries) {
+			for (const [identifier, feedback] of errorEntries) add(identifier, feedback);
+		},
+		clear() {
+			entries.clear();
+		},
+		delete(identifier) {
+			assertNonEmptyIdentifier(identifier, "identifier");
+			return entries.delete(normalizeErrorIdentifier(identifier));
+		},
+		get(identifier) {
+			const feedback = entries.get(normalizeErrorIdentifier(identifier));
+			return feedback === void 0 ? void 0 : cloneFeedback(feedback);
+		},
+		*values() {
+			for (const [identifier, feedback] of entries) yield [identifier, cloneFeedback(feedback)];
+		}
+	};
+};
+/**
+* Creates a prefix bucket for longest-prefix message matching.
+*
+* @internal
+*/
+const createPrefixBucket = () => {
+	const entries = /* @__PURE__ */ new Map();
+	let sortedCache = null;
+	const rebuildCache = () => {
+		sortedCache = Array.from(entries.entries(), ([prefix, feedback]) => ({
+			...cloneFeedback(feedback),
+			prefix
+		})).sort((a, b) => b.prefix.length - a.prefix.length);
+	};
+	const getSortedCache = () => {
+		if (sortedCache === null) rebuildCache();
+		return sortedCache;
+	};
+	const add = (prefix, feedback) => {
+		assertNonEmptyIdentifier(prefix, "prefix");
+		assertFeedback(feedback);
+		entries.set(normalizeErrorIdentifier(prefix), cloneFeedback(feedback));
+		sortedCache = null;
+	};
+	return {
+		add,
+		addList(errorEntries) {
+			for (const [prefix, feedback] of errorEntries) add(prefix, feedback);
+		},
+		clear() {
+			entries.clear();
+			sortedCache = [];
+		},
+		delete(prefix) {
+			assertNonEmptyIdentifier(prefix, "prefix");
+			const deleted = entries.delete(normalizeErrorIdentifier(prefix));
+			if (deleted) sortedCache = null;
+			return deleted;
+		},
+		values() {
+			return getSortedCache();
+		}
+	};
+};
+/**
+* Creates a pattern bucket for heuristic regex-based error matching.
+* Strips `g`/`y` flags from stored patterns to prevent stateful `lastIndex` drift.
+*
+* @internal
+*/
+const createPatternBucket = () => {
+	const entries = [];
+	let cachedValues = null;
+	const add = (pattern, feedback) => {
+		if (!(pattern instanceof RegExp)) throw new TypeError("Error registry pattern must be a RegExp.");
+		assertFeedback(feedback);
+		const source = pattern.source;
+		const flags = pattern.flags.replace(/[gy]/g, "");
+		const existingIndex = entries.findIndex((entry) => entry.pattern.source === source && entry.pattern.flags === flags);
+		const definition = {
+			...cloneFeedback(feedback),
+			pattern: new RegExp(source, flags)
+		};
+		if (existingIndex !== -1) entries[existingIndex] = definition;
+		else entries.push(definition);
+		cachedValues = null;
+	};
+	return {
+		add,
+		addList(errorEntries) {
+			for (const [pattern, feedback] of errorEntries) add(pattern, feedback);
+		},
+		clear() {
+			entries.length = 0;
+			cachedValues = [];
+		},
+		delete(pattern) {
+			if (!(pattern instanceof RegExp)) throw new TypeError("Error registry pattern must be a RegExp.");
+			let isDeleted = false;
+			const flags = pattern.flags.replace(/[gy]/g, "");
+			for (let i = entries.length - 1; i >= 0; i--) if (entries[i].pattern.source === pattern.source && entries[i].pattern.flags === flags) {
+				entries.splice(i, 1);
+				isDeleted = true;
+			}
+			if (isDeleted) cachedValues = null;
+			return isDeleted;
+		},
+		values() {
+			if (cachedValues === null) cachedValues = entries.map((entry) => ({
+				...entry,
+				pattern: new RegExp(entry.pattern.source, entry.pattern.flags)
+			}));
+			return cachedValues;
+		}
+	};
+};
+//#endregion
+export { assertFeedback, assertNonEmptyIdentifier, cloneFeedback, createFeedbackMapBucket, createPatternBucket, createPrefixBucket, normalizeErrorIdentifier };

package/dist/create-app-error.d.ts

@@ -0,0 +1,33 @@
+import { AppError, AppErrorOptions } from "./types.js";
+
+//#region src/create-app-error.d.ts
+/** Default message used when no registry entry or fallback message can describe an error. */
+declare const DEFAULT_APP_ERROR_MESSAGE = "An unexpected error occurred.";
+/**
+ * Normalizes an unknown error value into a predictable, structured AppError shape.
+ *
+ * This function processes the error value by unrolling nested wrappers (e.g., `cause` or `originalError`)
+ * up to a fixed depth to locate a registered classification.
+ *
+ * Classifications are resolved in priority order across all candidates:
+ * 1. Known AppError or deterministic registry match (code, name, message, prefix).
+ * 2. Unexpected AppError or heuristic registry match (pattern).
+ * 3. Any remaining AppError candidate.
+ * 4. Fallback unknown error.
+ *
+ * @param error - The raw error value to normalize (e.g., Error instances, plain objects, or strings).
+ * @param options - Configuration options controlling fallback message and registry source.
+ * @returns A normalized AppError instance. If the input is already a normalized AppError, it is returned as-is.
+ */
+declare function createAppError(error: unknown, options?: AppErrorOptions): AppError;
+/**
+ * Type guard to determine if an unknown value is a normalized AppError instance.
+ *
+ * Checks the value's prototype chain and verifies the unique internal AppError brand symbol.
+ *
+ * @param value - The value to inspect.
+ * @returns True if the value is a normalized AppError; otherwise, false.
+ */
+declare function isAppError(value: unknown): value is AppError;
+//#endregion
+export { DEFAULT_APP_ERROR_MESSAGE, createAppError, isAppError };

package/dist/create-app-error.js

@@ -0,0 +1,104 @@
+import { classifyErrorCandidateKnown, classifyErrorCandidateUnexpected, getErrorCandidates } from "./normalize.js";
+import { getErrorRegistry } from "./registry.js";
+//#region src/create-app-error.ts
+/** Default message used when no registry entry or fallback message can describe an error. */
+const DEFAULT_APP_ERROR_MESSAGE = "An unexpected error occurred.";
+const APP_ERROR_BRAND = Symbol.for("@codenhub/error/AppError");
+var AppErrorImpl = class extends Error {
+	[APP_ERROR_BRAND] = true;
+	type;
+	messageKey;
+	source;
+	originalError;
+	isRetryable;
+	constructor(resolved) {
+		super(resolved.message, { cause: resolved.originalError });
+		Object.setPrototypeOf(this, new.target.prototype);
+		this.name = "AppError";
+		this.type = resolved.type;
+		this.messageKey = resolved.messageKey;
+		this.source = resolved.source;
+		this.originalError = resolved.originalError;
+		this.isRetryable = resolved.isRetryable;
+	}
+};
+const resolveFromAppError = (appError, originalError) => ({
+	type: appError.type,
+	message: appError.message,
+	messageKey: appError.messageKey,
+	source: appError.source,
+	originalError,
+	isRetryable: appError.isRetryable
+});
+/**
+* Normalizes an unknown error value into a predictable, structured AppError shape.
+*
+* This function processes the error value by unrolling nested wrappers (e.g., `cause` or `originalError`)
+* up to a fixed depth to locate a registered classification.
+*
+* Classifications are resolved in priority order across all candidates:
+* 1. Known AppError or deterministic registry match (code, name, message, prefix).
+* 2. Unexpected AppError or heuristic registry match (pattern).
+* 3. Any remaining AppError candidate.
+* 4. Fallback unknown error.
+*
+* @param error - The raw error value to normalize (e.g., Error instances, plain objects, or strings).
+* @param options - Configuration options controlling fallback message and registry source.
+* @returns A normalized AppError instance. If the input is already a normalized AppError, it is returned as-is.
+*/
+function createAppError(error, options = {}) {
+	const hasCustomOptions = options.fallbackMessage !== void 0 || options.registry !== void 0 || options.maxDepth !== void 0;
+	if (isAppError(error) && !hasCustomOptions) return error;
+	const fallbackMessage = options.fallbackMessage ?? "An unexpected error occurred.";
+	const errorCandidates = getErrorCandidates(isAppError(error) ? error.originalError : error, options.maxDepth);
+	const registry = options.registry ?? getErrorRegistry();
+	let knownResult = null;
+	let unexpectedResult = null;
+	let appErrorFallback = null;
+	for (const candidate of errorCandidates) {
+		if (isAppError(candidate)) {
+			if (candidate.type === "known") {
+				knownResult = resolveFromAppError(candidate, error);
+				break;
+			} else if (candidate.type === "unexpected" && unexpectedResult === null) unexpectedResult = resolveFromAppError(candidate, error);
+			else if (appErrorFallback === null) appErrorFallback = resolveFromAppError(candidate, error);
+			continue;
+		}
+		const classification = classifyErrorCandidateKnown(registry, candidate);
+		if (classification !== null) {
+			knownResult = {
+				...classification,
+				originalError: error
+			};
+			break;
+		}
+		if (unexpectedResult === null) {
+			const classification = classifyErrorCandidateUnexpected(registry, candidate);
+			if (classification !== null) unexpectedResult = {
+				...classification,
+				originalError: error
+			};
+		}
+	}
+	return new AppErrorImpl(knownResult ?? unexpectedResult ?? appErrorFallback ?? {
+		type: "unknown",
+		message: fallbackMessage,
+		messageKey: null,
+		source: null,
+		originalError: error,
+		isRetryable: false
+	});
+}
+/**
+* Type guard to determine if an unknown value is a normalized AppError instance.
+*
+* Checks the value's prototype chain and verifies the unique internal AppError brand symbol.
+*
+* @param value - The value to inspect.
+* @returns True if the value is a normalized AppError; otherwise, false.
+*/
+function isAppError(value) {
+	return value !== null && (typeof value === "object" || typeof value === "function") && APP_ERROR_BRAND in value && value[APP_ERROR_BRAND] === true;
+}
+//#endregion
+export { DEFAULT_APP_ERROR_MESSAGE, createAppError, isAppError };