@cullet/erp-core 1.0.10 → 1.1.0

package/dist/validation-code.js

@@ -1,4 +1,3 @@
-import { createHash } from "node:crypto";
 //#region src/core/errors/error-codes.ts
 const ErrorCodes = {
 	authentication: {
@@ -94,7 +93,40 @@ function assertJsonSafeMetadata(input) {
 }
 //#endregion
 //#region src/core/errors/app-error.ts
+/**
+* Root of the application/domain error hierarchy. Every error the system raises
+* on purpose extends `AppError`, which gives callers a single `instanceof` to
+* catch and a uniform, serializable shape to log and transport.
+*
+* Beyond the native `Error` message it carries a stable `code` (the contract the
+* outside world matches on), an optional non-leaking `publicMessage`, a
+* severity, JSON-safe `metadata`, and the correlation/request/command ids that
+* stitch an error back to the request that produced it. The metadata is
+* validated as JSON-safe on construction, so a logger can serialize any
+* `AppError` without hitting a circular reference or a non-serializable value.
+*
+* Abstract on purpose: callers should throw a specific subclass (e.g.
+* {@link ValidationError}, {@link NotFoundError}) so the `code` and shape are
+* meaningful, never a bare `AppError`.
+*/
 var AppError = class extends Error {
+	/**
+	* Builds the common error envelope shared by every subclass.
+	*
+	* `name` is taken from `new.target` so the thrown instance reports its
+	* concrete subclass name (not `"AppError"`), and the prototype is re-pinned
+	* via `setPrototypeOf` so `instanceof` keeps working after transpilation to
+	* older targets where extending built-ins breaks the chain. `createdAtIso`
+	* defaults to now, and `metadata` is validated as JSON-safe so the error is
+	* always serializable.
+	*
+	* Declared `protected`: instantiate a concrete subclass, never `AppError`.
+	*
+	* @param message - The internal, developer-facing message.
+	* @param code - The stable machine-readable code callers match on.
+	* @param options - Optional cause, metadata, severity, and correlation ids.
+	* @throws When `options.metadata` contains a value that is not JSON-safe.
+	*/
 	constructor(message, code, options) {
 		super(message);
 		this.name = new.target.name;
@@ -132,51 +164,6 @@ var AppError = class extends Error {
 	}
 };
 //#endregion
-//#region src/core/shared/hashing.ts
-const CIRCULAR_STRUCTURE_MESSAGE = "Cannot stably stringify a circular structure";
-function sha256Hex(value) {
-	return createHash("sha256").update(value, "utf8").digest("hex");
-}
-function sortKeysDeep(value, seen) {
-	if (Array.isArray(value)) {
-		if (seen.has(value)) throw new TypeError(CIRCULAR_STRUCTURE_MESSAGE);
-		seen.add(value);
-		const mapped = value.map((item) => sortKeysDeep(item, seen));
-		seen.delete(value);
-		return mapped;
-	}
-	if (value instanceof Date) return value;
-	if (value && typeof value === "object") {
-		if (seen.has(value)) throw new TypeError(CIRCULAR_STRUCTURE_MESSAGE);
-		seen.add(value);
-		const record = value;
-		const ordered = Object.create(null);
-		for (const key of Object.keys(record).sort()) ordered[key] = sortKeysDeep(record[key], seen);
-		seen.delete(value);
-		return ordered;
-	}
-	return value;
-}
-/**
-* Deterministic JSON string with object keys sorted recursively, so key order
-* does not affect the output.
-*
-* Follows `JSON.stringify` semantics for the values it serializes: `undefined`,
-* functions and symbols are dropped, non-finite numbers become `null`, `bigint`
-* throws, and `Map`/`Set` serialize as `{}`. Distinct payloads can therefore
-* collapse to the same string — for collision-resistant hashing use
-* `PolicyHashing.canonicalJson` (policies/utils), which rejects those values
-* up front.
-*
-* @throws {TypeError} On circular references (mirroring `JSON.stringify`).
-*/
-function stableStringify(value) {
-	return JSON.stringify(sortKeysDeep(value, /* @__PURE__ */ new WeakSet()));
-}
-function payloadHash(value) {
-	return sha256Hex(stableStringify(value));
-}
-//#endregion
 //#region src/core/errors/unexpected-error.ts
 var UnexpectedError = class extends AppError {
 	constructor(message = "Unexpected error", cause, options) {
@@ -239,6 +226,6 @@ var ValidationCode = class ValidationCode {
 	}
 };
 //#endregion
-export { stableStringify as a, ErrorCodes as c, sha256Hex as i, serializationErrorCode as l, UnexpectedError as n, AppError as o, payloadHash as r, assertJsonSafeMetadata as s, ValidationCode as t };
+export { ErrorCodes as a, assertJsonSafeMetadata as i, UnexpectedError as n, serializationErrorCode as o, AppError as r, ValidationCode as t };
 
 //# sourceMappingURL=validation-code.js.map

package/dist/validation-code.js.map

@@ -1 +1 @@
-{"version":3,"file":"validation-code.js","names":[],"sources":["../src/core/errors/error-codes.ts","../src/core/errors/utils/json-safe.ts","../src/core/errors/app-error.ts","../src/core/shared/hashing.ts","../src/core/errors/unexpected-error.ts","../src/core/exceptions/validation-code.ts"],"sourcesContent":["const ErrorCodes = {\n    authentication: {\n        missingToken: \"sec.authn.missing_token\",\n        invalidToken: \"sec.authn.invalid_token\",\n        expiredToken: \"sec.authn.expired_token\",\n        invalidCredentials: \"sec.authn.invalid_credentials\",\n    },\n    authorization: {\n        forbidden: \"sec.authz.forbidden\",\n        policyDenied: \"sec.authz.policy_denied\",\n        missingCapability: \"sec.authz.missing_capability\",\n        outOfScope: \"sec.authz.out_of_scope\",\n    },\n    businessRuleViolation: \"business_rule_violation\",\n    conflict: {\n        alreadyExists: \"conf.already_exists\",\n        duplicate: \"conf.duplicate\",\n        uniqueViolation: \"conf.unique_violation\",\n    },\n    idempotency: {\n        keyMissing: \"idemp.key_missing\",\n        inProgress: \"idemp.in_progress\",\n        payloadMismatch: \"idemp.payload_mismatch\",\n        replayNotSupported: \"idemp.replay_not_supported\",\n    },\n    integration: {\n        timeout: \"int.timeout\",\n        unreachable: \"int.unreachable\",\n        badResponse: \"int.bad_response\",\n    },\n    legacyIncompatible: \"legacy_incompatible\",\n    notFound: \"not_found\",\n    serialization: {\n        deserializePrefix: \"ser.des\",\n        serializePrefix: \"ser.ser\",\n    },\n    temporal: {\n        expired: \"tmp.expired\",\n        notYetValid: \"tmp.not_yet_valid\",\n    },\n    unexpected: \"unexpected\",\n    validation: \"validation_error\",\n} as const;\n\ntype SerializationCodeDirection = \"deserialize\" | \"serialize\";\n\nfunction serializationErrorCode(\n    direction: SerializationCodeDirection,\n    category: string,\n): string {\n    const prefix =\n        direction === \"deserialize\"\n            ? ErrorCodes.serialization.deserializePrefix\n            : ErrorCodes.serialization.serializePrefix;\n\n    return `${prefix}.${category}`;\n}\n\nexport { ErrorCodes, serializationErrorCode };\nexport type { SerializationCodeDirection };\n","// Utilities for ensuring metadata is JSON-serializable.\n\nimport type { JsonSafeRecord, JsonSafeValue } from \"../types.js\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Constants\n// ─────────────────────────────────────────────────────────────────────────────\n\nconst NON_SERIALIZABLE_PLACEHOLDER = \"[NonSerializable]\";\nconst CIRCULAR_REFERENCE_PLACEHOLDER = \"[Circular]\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Internal helpers\n// ─────────────────────────────────────────────────────────────────────────────\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n    if (value === null || typeof value !== \"object\") return false;\n    const proto = Object.getPrototypeOf(value);\n    return proto === Object.prototype || proto === null;\n}\n\n// `seen` tracks the ancestors on the current traversal branch (a DFS path), not\n// every object visited. This collapses true circular references to a placeholder\n// while still serializing the same object referenced more than once across\n// sibling branches (a DAG) — matching `JSON.stringify`, which only rejects\n// cycles, not shared references.\nfunction sanitizeValue(value: unknown, seen: WeakSet<object>): JsonSafeValue {\n    // Null passthrough\n    if (value === null) return null;\n\n    const type = typeof value;\n\n    // Primitives\n    if (type === \"string\" || type === \"number\" || type === \"boolean\") {\n        return value as JsonSafeValue;\n    }\n\n    // Non-serializable primitives\n    if (\n        type === \"bigint\" ||\n        type === \"function\" ||\n        type === \"symbol\" ||\n        value === undefined\n    ) {\n        return NON_SERIALIZABLE_PLACEHOLDER;\n    }\n\n    // Arrays (recursive)\n    if (Array.isArray(value)) {\n        if (seen.has(value)) return CIRCULAR_REFERENCE_PLACEHOLDER;\n        seen.add(value);\n        const sanitized = value.map((item) => sanitizeValue(item, seen));\n        seen.delete(value);\n        return sanitized;\n    }\n\n    // Date → placeholder (could also use .toISOString() if preferred)\n    if (value instanceof Date) {\n        return NON_SERIALIZABLE_PLACEHOLDER;\n    }\n\n    // Class instances and non-plain objects → placeholder\n    if (!isPlainObject(value)) {\n        return NON_SERIALIZABLE_PLACEHOLDER;\n    }\n\n    // Plain object (recursive)\n    if (seen.has(value)) return CIRCULAR_REFERENCE_PLACEHOLDER;\n    seen.add(value);\n    const result: Record<string, JsonSafeValue> = {};\n    for (const [key, val] of Object.entries(value)) {\n        result[key] = sanitizeValue(val, seen);\n    }\n    seen.delete(value);\n    return result;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Public API\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Ensures metadata is JSON-serializable.\n *\n * **Allowed:** string, number, boolean, null, arrays, and plain objects.\n *\n * **Converted to placeholder:** Date, BigInt, class instances, functions,\n * symbols, undefined, and circular references (which would otherwise make\n * `JSON.stringify` throw).\n *\n * @throws {TypeError} If `input` is not a plain object at the root level.\n */\nfunction assertJsonSafeMetadata(input: unknown): JsonSafeRecord {\n    if (input === undefined) {\n        return {};\n    }\n\n    if (!isPlainObject(input)) {\n        throw new TypeError(\n            \"metadata must be a plain object (Record<string, unknown>).\",\n        );\n    }\n\n    return sanitizeValue(input, new WeakSet<object>()) as JsonSafeRecord;\n}\n\nexport {\n    assertJsonSafeMetadata,\n    CIRCULAR_REFERENCE_PLACEHOLDER,\n    NON_SERIALIZABLE_PLACEHOLDER,\n};\n","// Base application error for the domain/application layer.\n// Encapsulates a code, optional cause, and JSON-safe metadata.\n\nimport type {\n    AppErrorOptions,\n    ErrorSeverity,\n    JsonSafeRecord,\n} from \"./types.js\";\nimport { assertJsonSafeMetadata } from \"./utils/index.js\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// AppError (abstract base class)\n// ─────────────────────────────────────────────────────────────────────────────\n\nabstract class AppError extends Error {\n    public readonly code: string;\n    public readonly cause?: unknown;\n    public readonly metadata?: JsonSafeRecord;\n    public readonly type?: string;\n    public readonly severity?: ErrorSeverity;\n    public readonly createdAtIso: string;\n    public readonly publicMessage?: string;\n    /**\n     * Identifies a single execution \"story\" in the system. All operations\n     * related to the same logical flow must share the same correlationId.\n     */\n    public readonly correlationId?: string;\n    /**\n     * Identifies a specific technical request attempt (each retry may produce\n     * a new requestId), even when the correlationId stays the same.\n     */\n    public readonly requestId?: string;\n    /**\n     * Marks the business intent / idempotency key; stays the same across\n     * technical retries and multiple requests that represent the same intent.\n     */\n    public readonly commandId?: string;\n\n    protected constructor(\n        message: string,\n        code: string,\n        options?: AppErrorOptions,\n    ) {\n        super(message);\n\n        this.name = new.target.name;\n        this.code = code;\n        this.cause = options?.cause;\n        this.type = options?.type;\n        this.severity = options?.severity;\n        this.correlationId = options?.correlationId;\n        this.requestId = options?.requestId;\n        this.commandId = options?.commandId;\n        this.createdAtIso = options?.createdAtIso ?? new Date().toISOString();\n        this.publicMessage = options?.publicMessage;\n\n        this.metadata = options?.metadata\n            ? assertJsonSafeMetadata(options.metadata)\n            : undefined;\n\n        Object.setPrototypeOf(this, new.target.prototype);\n    }\n\n    /**\n     * Returns a JSON-safe representation of the error.\n     * Does NOT include `cause` by default (to avoid leaking internal details).\n     */\n    public toJSON(): Record<string, unknown> {\n        const payload: Record<string, unknown> = {\n            name: this.name,\n            code: this.code,\n            message: this.message,\n            createdAtIso: this.createdAtIso,\n        };\n\n        // Optional fields are emitted only when defined, so the serialized\n        // shape never carries `undefined`-valued keys (consistent with how the\n        // correlation/request/command ids are handled).\n        if (this.type !== undefined) payload.type = this.type;\n        if (this.severity !== undefined) payload.severity = this.severity;\n        if (this.publicMessage !== undefined)\n            payload.publicMessage = this.publicMessage;\n        if (this.metadata !== undefined) payload.metadata = this.metadata;\n        if (this.correlationId !== undefined)\n            payload.correlationId = this.correlationId;\n        if (this.requestId !== undefined) payload.requestId = this.requestId;\n        if (this.commandId !== undefined) payload.commandId = this.commandId;\n\n        return payload;\n    }\n}\n\nexport { AppError };\n","import { createHash } from \"node:crypto\";\n\nconst CIRCULAR_STRUCTURE_MESSAGE =\n    \"Cannot stably stringify a circular structure\";\n\nfunction sha256Hex(value: string): string {\n    return createHash(\"sha256\").update(value, \"utf8\").digest(\"hex\");\n}\n\n// `seen` holds the current traversal branch so true cycles are rejected while\n// repeated (acyclic) references are still serialized — matching JSON.stringify.\nfunction sortKeysDeep(value: unknown, seen: WeakSet<object>): unknown {\n    if (Array.isArray(value)) {\n        if (seen.has(value)) {\n            throw new TypeError(CIRCULAR_STRUCTURE_MESSAGE);\n        }\n        seen.add(value);\n        const mapped = value.map((item) => sortKeysDeep(item, seen));\n        seen.delete(value);\n        return mapped;\n    }\n\n    if (value instanceof Date) {\n        return value;\n    }\n\n    if (value && typeof value === \"object\") {\n        if (seen.has(value)) {\n            throw new TypeError(CIRCULAR_STRUCTURE_MESSAGE);\n        }\n        seen.add(value);\n        const record = value as Record<string, unknown>;\n        const ordered = Object.create(null) as Record<string, unknown>;\n\n        for (const key of Object.keys(record).sort()) {\n            ordered[key] = sortKeysDeep(record[key], seen);\n        }\n        seen.delete(value);\n\n        return ordered;\n    }\n\n    return value;\n}\n\n/**\n * Deterministic JSON string with object keys sorted recursively, so key order\n * does not affect the output.\n *\n * Follows `JSON.stringify` semantics for the values it serializes: `undefined`,\n * functions and symbols are dropped, non-finite numbers become `null`, `bigint`\n * throws, and `Map`/`Set` serialize as `{}`. Distinct payloads can therefore\n * collapse to the same string — for collision-resistant hashing use\n * `PolicyHashing.canonicalJson` (policies/utils), which rejects those values\n * up front.\n *\n * @throws {TypeError} On circular references (mirroring `JSON.stringify`).\n */\nfunction stableStringify(value: unknown): string {\n    return JSON.stringify(sortKeysDeep(value, new WeakSet<object>()));\n}\n\nfunction payloadHash(value: unknown): string {\n    return sha256Hex(stableStringify(value));\n}\n\nexport { payloadHash, sha256Hex, stableStringify };\n","import { AppError } from \"./app-error.js\";\nimport { ErrorCodes } from \"./error-codes.js\";\nimport type { AppErrorOptions } from \"./types.js\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// UnexpectedError\n// ─────────────────────────────────────────────────────────────────────────────\n\nclass UnexpectedError extends AppError {\n    constructor(\n        message = \"Unexpected error\",\n        cause?: unknown,\n        options?: Omit<AppErrorOptions, \"cause\">,\n    ) {\n        super(message, ErrorCodes.unexpected, {\n            cause,\n            ...options,\n        });\n    }\n}\n\nexport { UnexpectedError };\n","// Object-oriented representation of validation codes (similar to Kotlin inline class).\n// Provides common reusable codes while allowing custom codes via `of`.\n\nclass ValidationCode {\n    public readonly value: string;\n\n    private constructor(value: string) {\n        this.value = value;\n    }\n\n    // Factory for custom codes\n    public static of(value: string): ValidationCode {\n        return new ValidationCode(value);\n    }\n\n    // Common, domain-friendly codes\n    public static readonly BLANK = new ValidationCode(\"blank\");\n    public static readonly REQUIRED = new ValidationCode(\"required\");\n    public static readonly INVALID_FORMAT = new ValidationCode(\n        \"invalid_format\",\n    );\n    public static readonly INVALID_CHARACTERS = new ValidationCode(\n        \"invalid_characters\",\n    );\n    public static readonly INVALID_LENGTH = new ValidationCode(\n        \"invalid_length\",\n    );\n    public static readonly TOO_SHORT = new ValidationCode(\"too_short\");\n    public static readonly TOO_LONG = new ValidationCode(\"too_long\");\n    public static readonly OUT_OF_RANGE = new ValidationCode(\"out_of_range\");\n    public static readonly INVALID_CHECKSUM = new ValidationCode(\n        \"invalid_checksum\",\n    );\n    public static readonly INVALID_CHECKING_DIGIT = new ValidationCode(\n        \"invalid_checking_digit\",\n    );\n    public static readonly ALREADY_EXISTS = new ValidationCode(\n        \"already_exists\",\n    );\n    public static readonly NOT_FOUND = new ValidationCode(\"not_found\");\n    public static readonly NOT_ALLOWED = new ValidationCode(\"not_allowed\");\n    public static readonly UNEXPECTED = new ValidationCode(\"unexpected\");\n}\n\nexport { ValidationCode };\n"],"mappings":"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"}
+{"version":3,"file":"validation-code.js","names":[],"sources":["../src/core/errors/error-codes.ts","../src/core/errors/utils/json-safe.ts","../src/core/errors/app-error.ts","../src/core/errors/unexpected-error.ts","../src/core/exceptions/validation-code.ts"],"sourcesContent":["const ErrorCodes = {\n    authentication: {\n        missingToken: \"sec.authn.missing_token\",\n        invalidToken: \"sec.authn.invalid_token\",\n        expiredToken: \"sec.authn.expired_token\",\n        invalidCredentials: \"sec.authn.invalid_credentials\",\n    },\n    authorization: {\n        forbidden: \"sec.authz.forbidden\",\n        policyDenied: \"sec.authz.policy_denied\",\n        missingCapability: \"sec.authz.missing_capability\",\n        outOfScope: \"sec.authz.out_of_scope\",\n    },\n    businessRuleViolation: \"business_rule_violation\",\n    conflict: {\n        alreadyExists: \"conf.already_exists\",\n        duplicate: \"conf.duplicate\",\n        uniqueViolation: \"conf.unique_violation\",\n    },\n    idempotency: {\n        keyMissing: \"idemp.key_missing\",\n        inProgress: \"idemp.in_progress\",\n        payloadMismatch: \"idemp.payload_mismatch\",\n        replayNotSupported: \"idemp.replay_not_supported\",\n    },\n    integration: {\n        timeout: \"int.timeout\",\n        unreachable: \"int.unreachable\",\n        badResponse: \"int.bad_response\",\n    },\n    legacyIncompatible: \"legacy_incompatible\",\n    notFound: \"not_found\",\n    serialization: {\n        deserializePrefix: \"ser.des\",\n        serializePrefix: \"ser.ser\",\n    },\n    temporal: {\n        expired: \"tmp.expired\",\n        notYetValid: \"tmp.not_yet_valid\",\n    },\n    unexpected: \"unexpected\",\n    validation: \"validation_error\",\n} as const;\n\ntype SerializationCodeDirection = \"deserialize\" | \"serialize\";\n\nfunction serializationErrorCode(\n    direction: SerializationCodeDirection,\n    category: string,\n): string {\n    const prefix =\n        direction === \"deserialize\"\n            ? ErrorCodes.serialization.deserializePrefix\n            : ErrorCodes.serialization.serializePrefix;\n\n    return `${prefix}.${category}`;\n}\n\nexport { ErrorCodes, serializationErrorCode };\nexport type { SerializationCodeDirection };\n","// Utilities for ensuring metadata is JSON-serializable.\n\nimport type { JsonSafeRecord, JsonSafeValue } from \"../types.js\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Constants\n// ─────────────────────────────────────────────────────────────────────────────\n\nconst NON_SERIALIZABLE_PLACEHOLDER = \"[NonSerializable]\";\nconst CIRCULAR_REFERENCE_PLACEHOLDER = \"[Circular]\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Internal helpers\n// ─────────────────────────────────────────────────────────────────────────────\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n    if (value === null || typeof value !== \"object\") return false;\n    const proto = Object.getPrototypeOf(value);\n    return proto === Object.prototype || proto === null;\n}\n\n// `seen` tracks the ancestors on the current traversal branch (a DFS path), not\n// every object visited. This collapses true circular references to a placeholder\n// while still serializing the same object referenced more than once across\n// sibling branches (a DAG) — matching `JSON.stringify`, which only rejects\n// cycles, not shared references.\nfunction sanitizeValue(value: unknown, seen: WeakSet<object>): JsonSafeValue {\n    // Null passthrough\n    if (value === null) return null;\n\n    const type = typeof value;\n\n    // Primitives\n    if (type === \"string\" || type === \"number\" || type === \"boolean\") {\n        return value as JsonSafeValue;\n    }\n\n    // Non-serializable primitives\n    if (\n        type === \"bigint\" ||\n        type === \"function\" ||\n        type === \"symbol\" ||\n        value === undefined\n    ) {\n        return NON_SERIALIZABLE_PLACEHOLDER;\n    }\n\n    // Arrays (recursive)\n    if (Array.isArray(value)) {\n        if (seen.has(value)) return CIRCULAR_REFERENCE_PLACEHOLDER;\n        seen.add(value);\n        const sanitized = value.map((item) => sanitizeValue(item, seen));\n        seen.delete(value);\n        return sanitized;\n    }\n\n    // Date → placeholder (could also use .toISOString() if preferred)\n    if (value instanceof Date) {\n        return NON_SERIALIZABLE_PLACEHOLDER;\n    }\n\n    // Class instances and non-plain objects → placeholder\n    if (!isPlainObject(value)) {\n        return NON_SERIALIZABLE_PLACEHOLDER;\n    }\n\n    // Plain object (recursive)\n    if (seen.has(value)) return CIRCULAR_REFERENCE_PLACEHOLDER;\n    seen.add(value);\n    const result: Record<string, JsonSafeValue> = {};\n    for (const [key, val] of Object.entries(value)) {\n        result[key] = sanitizeValue(val, seen);\n    }\n    seen.delete(value);\n    return result;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Public API\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Ensures metadata is JSON-serializable.\n *\n * **Allowed:** string, number, boolean, null, arrays, and plain objects.\n *\n * **Converted to placeholder:** Date, BigInt, class instances, functions,\n * symbols, undefined, and circular references (which would otherwise make\n * `JSON.stringify` throw).\n *\n * @throws {TypeError} If `input` is not a plain object at the root level.\n */\nfunction assertJsonSafeMetadata(input: unknown): JsonSafeRecord {\n    if (input === undefined) {\n        return {};\n    }\n\n    if (!isPlainObject(input)) {\n        throw new TypeError(\n            \"metadata must be a plain object (Record<string, unknown>).\",\n        );\n    }\n\n    return sanitizeValue(input, new WeakSet<object>()) as JsonSafeRecord;\n}\n\nexport {\n    assertJsonSafeMetadata,\n    CIRCULAR_REFERENCE_PLACEHOLDER,\n    NON_SERIALIZABLE_PLACEHOLDER,\n};\n","// Base application error for the domain/application layer.\n// Encapsulates a code, optional cause, and JSON-safe metadata.\n\nimport type {\n    AppErrorOptions,\n    ErrorSeverity,\n    JsonSafeRecord,\n} from \"./types.js\";\nimport { assertJsonSafeMetadata } from \"./utils/index.js\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// AppError (abstract base class)\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Root of the application/domain error hierarchy. Every error the system raises\n * on purpose extends `AppError`, which gives callers a single `instanceof` to\n * catch and a uniform, serializable shape to log and transport.\n *\n * Beyond the native `Error` message it carries a stable `code` (the contract the\n * outside world matches on), an optional non-leaking `publicMessage`, a\n * severity, JSON-safe `metadata`, and the correlation/request/command ids that\n * stitch an error back to the request that produced it. The metadata is\n * validated as JSON-safe on construction, so a logger can serialize any\n * `AppError` without hitting a circular reference or a non-serializable value.\n *\n * Abstract on purpose: callers should throw a specific subclass (e.g.\n * {@link ValidationError}, {@link NotFoundError}) so the `code` and shape are\n * meaningful, never a bare `AppError`.\n */\nabstract class AppError extends Error {\n    public readonly code: string;\n    public readonly cause?: unknown;\n    public readonly metadata?: JsonSafeRecord;\n    public readonly type?: string;\n    public readonly severity?: ErrorSeverity;\n    public readonly createdAtIso: string;\n    public readonly publicMessage?: string;\n    /**\n     * Identifies a single execution \"story\" in the system. All operations\n     * related to the same logical flow must share the same correlationId.\n     */\n    public readonly correlationId?: string;\n    /**\n     * Identifies a specific technical request attempt (each retry may produce\n     * a new requestId), even when the correlationId stays the same.\n     */\n    public readonly requestId?: string;\n    /**\n     * Marks the business intent / idempotency key; stays the same across\n     * technical retries and multiple requests that represent the same intent.\n     */\n    public readonly commandId?: string;\n\n    /**\n     * Builds the common error envelope shared by every subclass.\n     *\n     * `name` is taken from `new.target` so the thrown instance reports its\n     * concrete subclass name (not `\"AppError\"`), and the prototype is re-pinned\n     * via `setPrototypeOf` so `instanceof` keeps working after transpilation to\n     * older targets where extending built-ins breaks the chain. `createdAtIso`\n     * defaults to now, and `metadata` is validated as JSON-safe so the error is\n     * always serializable.\n     *\n     * Declared `protected`: instantiate a concrete subclass, never `AppError`.\n     *\n     * @param message - The internal, developer-facing message.\n     * @param code - The stable machine-readable code callers match on.\n     * @param options - Optional cause, metadata, severity, and correlation ids.\n     * @throws When `options.metadata` contains a value that is not JSON-safe.\n     */\n    protected constructor(\n        message: string,\n        code: string,\n        options?: AppErrorOptions,\n    ) {\n        super(message);\n\n        this.name = new.target.name;\n        this.code = code;\n        this.cause = options?.cause;\n        this.type = options?.type;\n        this.severity = options?.severity;\n        this.correlationId = options?.correlationId;\n        this.requestId = options?.requestId;\n        this.commandId = options?.commandId;\n        this.createdAtIso = options?.createdAtIso ?? new Date().toISOString();\n        this.publicMessage = options?.publicMessage;\n\n        this.metadata = options?.metadata\n            ? assertJsonSafeMetadata(options.metadata)\n            : undefined;\n\n        Object.setPrototypeOf(this, new.target.prototype);\n    }\n\n    /**\n     * Returns a JSON-safe representation of the error.\n     * Does NOT include `cause` by default (to avoid leaking internal details).\n     */\n    public toJSON(): Record<string, unknown> {\n        const payload: Record<string, unknown> = {\n            name: this.name,\n            code: this.code,\n            message: this.message,\n            createdAtIso: this.createdAtIso,\n        };\n\n        // Optional fields are emitted only when defined, so the serialized\n        // shape never carries `undefined`-valued keys (consistent with how the\n        // correlation/request/command ids are handled).\n        if (this.type !== undefined) payload.type = this.type;\n        if (this.severity !== undefined) payload.severity = this.severity;\n        if (this.publicMessage !== undefined)\n            payload.publicMessage = this.publicMessage;\n        if (this.metadata !== undefined) payload.metadata = this.metadata;\n        if (this.correlationId !== undefined)\n            payload.correlationId = this.correlationId;\n        if (this.requestId !== undefined) payload.requestId = this.requestId;\n        if (this.commandId !== undefined) payload.commandId = this.commandId;\n\n        return payload;\n    }\n}\n\nexport { AppError };\n","import { AppError } from \"./app-error.js\";\nimport { ErrorCodes } from \"./error-codes.js\";\nimport type { AppErrorOptions } from \"./types.js\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// UnexpectedError\n// ─────────────────────────────────────────────────────────────────────────────\n\nclass UnexpectedError extends AppError {\n    constructor(\n        message = \"Unexpected error\",\n        cause?: unknown,\n        options?: Omit<AppErrorOptions, \"cause\">,\n    ) {\n        super(message, ErrorCodes.unexpected, {\n            cause,\n            ...options,\n        });\n    }\n}\n\nexport { UnexpectedError };\n","// Object-oriented representation of validation codes (similar to Kotlin inline class).\n// Provides common reusable codes while allowing custom codes via `of`.\n\nclass ValidationCode {\n    public readonly value: string;\n\n    private constructor(value: string) {\n        this.value = value;\n    }\n\n    // Factory for custom codes\n    public static of(value: string): ValidationCode {\n        return new ValidationCode(value);\n    }\n\n    // Common, domain-friendly codes\n    public static readonly BLANK = new ValidationCode(\"blank\");\n    public static readonly REQUIRED = new ValidationCode(\"required\");\n    public static readonly INVALID_FORMAT = new ValidationCode(\n        \"invalid_format\",\n    );\n    public static readonly INVALID_CHARACTERS = new ValidationCode(\n        \"invalid_characters\",\n    );\n    public static readonly INVALID_LENGTH = new ValidationCode(\n        \"invalid_length\",\n    );\n    public static readonly TOO_SHORT = new ValidationCode(\"too_short\");\n    public static readonly TOO_LONG = new ValidationCode(\"too_long\");\n    public static readonly OUT_OF_RANGE = new ValidationCode(\"out_of_range\");\n    public static readonly INVALID_CHECKSUM = new ValidationCode(\n        \"invalid_checksum\",\n    );\n    public static readonly INVALID_CHECKING_DIGIT = new ValidationCode(\n        \"invalid_checking_digit\",\n    );\n    public static readonly ALREADY_EXISTS = new ValidationCode(\n        \"already_exists\",\n    );\n    public static readonly NOT_FOUND = new ValidationCode(\"not_found\");\n    public static readonly NOT_ALLOWED = new ValidationCode(\"not_allowed\");\n    public static readonly UNEXPECTED = new ValidationCode(\"unexpected\");\n}\n\nexport { ValidationCode };\n"],"mappings":";AAAA,MAAM,aAAa;CACf,gBAAgB;EACZ,cAAc;EACd,cAAc;EACd,cAAc;EACd,oBAAoB;CACxB;CACA,eAAe;EACX,WAAW;EACX,cAAc;EACd,mBAAmB;EACnB,YAAY;CAChB;CACA,uBAAuB;CACvB,UAAU;EACN,eAAe;EACf,WAAW;EACX,iBAAiB;CACrB;CACA,aAAa;EACT,YAAY;EACZ,YAAY;EACZ,iBAAiB;EACjB,oBAAoB;CACxB;CACA,aAAa;EACT,SAAS;EACT,aAAa;EACb,aAAa;CACjB;CACA,oBAAoB;CACpB,UAAU;CACV,eAAe;EACX,mBAAmB;EACnB,iBAAiB;CACrB;CACA,UAAU;EACN,SAAS;EACT,aAAa;CACjB;CACA,YAAY;CACZ,YAAY;AAChB;AAIA,SAAS,uBACL,WACA,UACM;CAMN,OAAO,GAJH,cAAc,gBACR,WAAW,cAAc,oBACzB,WAAW,cAAc,gBAElB,GAAG;AACxB;;;AChDA,MAAM,+BAA+B;AACrC,MAAM,iCAAiC;AAMvC,SAAS,cAAc,OAAkD;CACrE,IAAI,UAAU,QAAQ,OAAO,UAAU,UAAU,OAAO;CACxD,MAAM,QAAQ,OAAO,eAAe,KAAK;CACzC,OAAO,UAAU,OAAO,aAAa,UAAU;AACnD;AAOA,SAAS,cAAc,OAAgB,MAAsC;CAEzE,IAAI,UAAU,MAAM,OAAO;CAE3B,MAAM,OAAO,OAAO;CAGpB,IAAI,SAAS,YAAY,SAAS,YAAY,SAAS,WACnD,OAAO;CAIX,IACI,SAAS,YACT,SAAS,cACT,SAAS,YACT,UAAU,KAAA,GAEV,OAAO;CAIX,IAAI,MAAM,QAAQ,KAAK,GAAG;EACtB,IAAI,KAAK,IAAI,KAAK,GAAG,OAAO;EAC5B,KAAK,IAAI,KAAK;EACd,MAAM,YAAY,MAAM,KAAK,SAAS,cAAc,MAAM,IAAI,CAAC;EAC/D,KAAK,OAAO,KAAK;EACjB,OAAO;CACX;CAGA,IAAI,iBAAiB,MACjB,OAAO;CAIX,IAAI,CAAC,cAAc,KAAK,GACpB,OAAO;CAIX,IAAI,KAAK,IAAI,KAAK,GAAG,OAAO;CAC5B,KAAK,IAAI,KAAK;CACd,MAAM,SAAwC,CAAC;CAC/C,KAAK,MAAM,CAAC,KAAK,QAAQ,OAAO,QAAQ,KAAK,GACzC,OAAO,OAAO,cAAc,KAAK,IAAI;CAEzC,KAAK,OAAO,KAAK;CACjB,OAAO;AACX;;;;;;;;;;;;AAiBA,SAAS,uBAAuB,OAAgC;CAC5D,IAAI,UAAU,KAAA,GACV,OAAO,CAAC;CAGZ,IAAI,CAAC,cAAc,KAAK,GACpB,MAAM,IAAI,UACN,4DACJ;CAGJ,OAAO,cAAc,uBAAO,IAAI,QAAgB,CAAC;AACrD;;;;;;;;;;;;;;;;;;;AC1EA,IAAe,WAAf,cAAgC,MAAM;;;;;;;;;;;;;;;;;;CAyClC,YACI,SACA,MACA,SACF;EACE,MAAM,OAAO;EAEb,KAAK,OAAO,IAAI,OAAO;EACvB,KAAK,OAAO;EACZ,KAAK,QAAQ,SAAS;EACtB,KAAK,OAAO,SAAS;EACrB,KAAK,WAAW,SAAS;EACzB,KAAK,gBAAgB,SAAS;EAC9B,KAAK,YAAY,SAAS;EAC1B,KAAK,YAAY,SAAS;EAC1B,KAAK,eAAe,SAAS,iCAAgB,IAAI,KAAK,GAAE,YAAY;EACpE,KAAK,gBAAgB,SAAS;EAE9B,KAAK,WAAW,SAAS,WACnB,uBAAuB,QAAQ,QAAQ,IACvC,KAAA;EAEN,OAAO,eAAe,MAAM,IAAI,OAAO,SAAS;CACpD;;;;;CAMA,SAAyC;EACrC,MAAM,UAAmC;GACrC,MAAM,KAAK;GACX,MAAM,KAAK;GACX,SAAS,KAAK;GACd,cAAc,KAAK;EACvB;EAKA,IAAI,KAAK,SAAS,KAAA,GAAW,QAAQ,OAAO,KAAK;EACjD,IAAI,KAAK,aAAa,KAAA,GAAW,QAAQ,WAAW,KAAK;EACzD,IAAI,KAAK,kBAAkB,KAAA,GACvB,QAAQ,gBAAgB,KAAK;EACjC,IAAI,KAAK,aAAa,KAAA,GAAW,QAAQ,WAAW,KAAK;EACzD,IAAI,KAAK,kBAAkB,KAAA,GACvB,QAAQ,gBAAgB,KAAK;EACjC,IAAI,KAAK,cAAc,KAAA,GAAW,QAAQ,YAAY,KAAK;EAC3D,IAAI,KAAK,cAAc,KAAA,GAAW,QAAQ,YAAY,KAAK;EAE3D,OAAO;CACX;AACJ;;;ACnHA,IAAM,kBAAN,cAA8B,SAAS;CACnC,YACI,UAAU,oBACV,OACA,SACF;EACE,MAAM,SAAS,WAAW,YAAY;GAClC;GACA,GAAG;EACP,CAAC;CACL;AACJ;;;AChBA,IAAM,iBAAN,MAAM,eAAe;CAGjB,YAAoB,OAAe;EAC/B,KAAK,QAAQ;CACjB;CAGA,OAAc,GAAG,OAA+B;EAC5C,OAAO,IAAI,eAAe,KAAK;CACnC;;eAG+B,IAAI,eAAe,OAAO;;;kBACvB,IAAI,eAAe,UAAU;;;wBACvB,IAAI,eACxC,gBACJ;;;4BAC4C,IAAI,eAC5C,oBACJ;;;wBACwC,IAAI,eACxC,gBACJ;;;mBACmC,IAAI,eAAe,WAAW;;;kBAC/B,IAAI,eAAe,UAAU;;;sBACzB,IAAI,eAAe,cAAc;;;0BAC7B,IAAI,eAC1C,kBACJ;;;gCACgD,IAAI,eAChD,wBACJ;;;wBACwC,IAAI,eACxC,gBACJ;;;mBACmC,IAAI,eAAe,WAAW;;;qBAC5B,IAAI,eAAe,aAAa;;;oBACjC,IAAI,eAAe,YAAY;;AACvE"}

package/dist/validation-error.d.ts

@@ -1,46 +1,6 @@
+import { a as JsonSafeRecord, n as AppErrorOptions, r as ErrorSeverity, t as AppError } from "./app-error.js";
 import { t as ValidationField } from "./validation-field.js";
 
-//#region src/core/errors/types.d.ts
-type ErrorSeverity = "low" | "medium" | "high" | "critical";
-type JsonSafePrimitive = string | number | boolean | null;
-type JsonSafeValue = JsonSafePrimitive | JsonSafeValue[] | {
-  [key: string]: JsonSafeValue;
-};
-type JsonSafeRecord = Record<string, JsonSafeValue>;
-/**
- * Options accepted by the AppError constructor.
- * Subclasses can extend or pick from this type.
- */
-type AppErrorOptions = {
-  /** Original error or exception that caused this error. */
-  cause?: unknown;
-  /** Arbitrary key-value metadata (will be sanitized to JSON-safe values). */
-  metadata?: Record<string, unknown>;
-  /** Error category/type for grouping (e.g., "authentication", "validation"). */
-  type?: string;
-  /** severity level for alerting/logging prioritization. */
-  severity?: ErrorSeverity;
-  /**
-   * Identifies a single execution "story" in the system. All operations
-   * related to the same logical flow must share the same correlationId.
-   */
-  correlationId?: string;
-  /**
-   * Identifies a specific technical request attempt (each retry may produce
-   * a new requestId), even when the correlationId stays the same.
-   */
-  requestId?: string;
-  /**
-   * Identifies a unique business intent (idempotency key); stays the same
-   * across technical retries and multiple requests that represent the same intent.
-   */
-  commandId?: string;
-  /** ISO timestamp of when the error was created (defaults to now). */
-  createdAtIso?: string;
-  /** Safe message that can be exposed to end users (no internal details). */
-  publicMessage?: string;
-};
-//#endregion
 //#region src/core/errors/error-codes.d.ts
 declare const ErrorCodes: {
   readonly authentication: {
@@ -102,38 +62,6 @@ declare function serializationErrorCode(direction: SerializationCodeDirection, c
  */
 declare function assertJsonSafeMetadata(input: unknown): JsonSafeRecord;
 //#endregion
-//#region src/core/errors/app-error.d.ts
-declare abstract class AppError extends Error {
-  readonly code: string;
-  readonly cause?: unknown;
-  readonly metadata?: JsonSafeRecord;
-  readonly type?: string;
-  readonly severity?: ErrorSeverity;
-  readonly createdAtIso: string;
-  readonly publicMessage?: string;
-  /**
-   * Identifies a single execution "story" in the system. All operations
-   * related to the same logical flow must share the same correlationId.
-   */
-  readonly correlationId?: string;
-  /**
-   * Identifies a specific technical request attempt (each retry may produce
-   * a new requestId), even when the correlationId stays the same.
-   */
-  readonly requestId?: string;
-  /**
-   * Marks the business intent / idempotency key; stays the same across
-   * technical retries and multiple requests that represent the same intent.
-   */
-  readonly commandId?: string;
-  protected constructor(message: string, code: string, options?: AppErrorOptions);
-  /**
-   * Returns a JSON-safe representation of the error.
-   * Does NOT include `cause` by default (to avoid leaking internal details).
-   */
-  toJSON(): Record<string, unknown>;
-}
-//#endregion
 //#region src/core/errors/authentication-error.d.ts
 type AuthenticationErrorReason = "missing_token" | "malformed_token" | "invalid_token" | "expired_token" | "revoked_token" | "invalid_credentials" | "session_not_found" | "session_expired" | "unknown";
 type AuthenticationErrorMetadata = {
@@ -196,18 +124,61 @@ type AuthorizationErrorMetadata = {
  * Combines metadata fields (except 'reason') with common AppError options.
  */
 type AuthorizationErrorFactoryOptions = Omit<AuthorizationErrorMetadata, "reason"> & Omit<AppErrorOptions, "metadata">;
+/**
+ * Raised when an authenticated actor is not allowed to perform a business
+ * action — the "you may not" error, distinct from authentication ("who are
+ * you"). Maps to an HTTP 403 at the edge.
+ *
+ * The discriminating {@link reason} records *why* access was denied (a flat
+ * forbid, a missing role/capability, an out-of-scope target, or a policy
+ * decision) so the boundary can shape the response without re-deriving it. The
+ * metadata is deliberately built around a stable business `action` and a
+ * type/id resource reference rather than an HTTP route or full payload, keeping
+ * sensitive data out of logs. Instances are frozen. Construct through the
+ * static factories, never directly.
+ */
 declare class AuthorizationError extends AppError {
   readonly reason: AuthorizationErrorReason;
   private constructor();
+  /**
+   * A flat denial with no more specific reason — the actor simply may not
+   * perform this action. Reach for a more precise factory
+   * ({@link AuthorizationError.missingCapability}, {@link AuthorizationError.outOfScope},
+   * {@link AuthorizationError.policyDenied}) when the cause is known.
+   */
   static forbidden(input: AuthorizationErrorFactoryOptions): AuthorizationError;
+  /**
+   * The action was denied by an evaluated policy. Captures the deciding
+   * policy's id, version, and evaluation instant into the metadata (with
+   * `decision: "deny"`) so the denial is auditable back to the exact policy
+   * that produced it.
+   *
+   * @param input - Factory options plus the required `policyId`,
+   *   `policyVersion`, and `evaluatedAtIso` of the deciding policy.
+   */
   static policyDenied(input: AuthorizationErrorFactoryOptions & {
     policyId: string;
     policyVersion: number;
     evaluatedAtIso: string;
   }): AuthorizationError;
+  /**
+   * The actor lacks a required role or capability. The expected
+   * {@link AuthorizationRequirement} is recorded so the boundary can tell the
+   * caller precisely what grant is missing.
+   *
+   * @param input - Factory options plus the `required` role/capability/scope.
+   */
   static missingCapability(input: AuthorizationErrorFactoryOptions & {
     required: AuthorizationRequirement;
   }): AuthorizationError;
+  /**
+   * The actor may perform the action in general, but not on *this* target —
+   * the resource falls outside the actor's permitted scope (e.g. a different
+   * school or tenant than the one they are bound to).
+   *
+   * @param input - Factory options plus the optional `required` scope that the
+   *   target failed to satisfy.
+   */
   static outOfScope(input: AuthorizationErrorFactoryOptions & {
     required?: AuthorizationRequirement;
   }): AuthorizationError;
@@ -241,12 +212,28 @@ type ConflictErrorMetadata = {
   commandId?: string;
   hint?: string;
 };
+/**
+ * Storage-level description of a unique-constraint breach, as reported by a
+ * database driver. Used to translate a raw DB error into a domain
+ * {@link DuplicateError} via {@link translateUniqueViolationToDuplicate}.
+ */
 type UniqueConstraintViolation = {
   kind: "unique_violation";
   constraintName?: string;
   table?: string;
   columns?: string[];
 };
+/**
+ * Base for errors that signal a state conflict — the request collides with data
+ * that already exists. Common at an HTTP 409 boundary.
+ *
+ * The discriminating {@link kind} lets a handler branch on *why* it conflicted
+ * (an already-existing record, a domain duplicate, or a raw storage uniqueness
+ * breach) without `instanceof` chains. Abstract: construct one of the concrete
+ * subclasses through its `detected(...)` factory, which fills in the right code,
+ * message, and metadata. Instances are frozen, so a conflict error can be shared
+ * and rethrown without risk of tampering.
+ */
 declare abstract class ConflictError extends AppError {
   readonly kind: ConflictKind;
   protected constructor(params: {
@@ -257,8 +244,21 @@ declare abstract class ConflictError extends AppError {
     cause?: unknown;
   } & AppErrorOptions);
 }
+/**
+ * The operation cannot proceed because a matching record already exists —
+ * e.g. creating something whose natural key is already taken. Construct via
+ * {@link AlreadyExistsError.detected}.
+ */
 declare class AlreadyExistsError extends ConflictError {
   private constructor();
+  /**
+   * Builds an {@link AlreadyExistsError} for a detected collision. `operation`
+   * defaults to `"create"` and a generic retry `hint` is supplied when none is
+   * given, so the error is actionable even from a minimal call site.
+   *
+   * @param input - The conflicting entity plus optional non-sensitive context
+   *   (operation, field, existing id, value hash/preview, correlation ids).
+   */
   static detected(input: {
     entity: string;
     operation?: string;
@@ -274,8 +274,22 @@ declare class AlreadyExistsError extends ConflictError {
     cause?: unknown;
   }): AlreadyExistsError;
 }
+/**
+ * A domain-level duplicate: the data being written would duplicate an existing
+ * record under the model's own uniqueness rules. Use this when the duplication
+ * is recognized in the domain, as opposed to a raw DB constraint
+ * ({@link UniqueConstraintViolationError}). Construct via
+ * {@link DuplicateError.detected}.
+ */
 declare class DuplicateError extends ConflictError {
   private constructor();
+  /**
+   * Builds a {@link DuplicateError} for a detected duplicate, defaulting to a
+   * "adjust the data so it does not duplicate" hint when none is provided.
+   *
+   * @param input - The conflicting entity plus optional non-sensitive context
+   *   (field, constraint name, existing id, value hash/preview, correlation ids).
+   */
   static detected(input: {
     entity: string;
     operation?: string;
@@ -292,8 +306,23 @@ declare class DuplicateError extends ConflictError {
     cause?: unknown;
   }): DuplicateError;
 }
+/**
+ * A uniqueness breach surfaced by the storage layer itself (a database unique
+ * index), carrying the raw {@link UniqueConstraintViolation} (constraint, table,
+ * columns). Keep this distinct from {@link DuplicateError}: this one is the
+ * infrastructure signal; translate it into a domain duplicate at the boundary
+ * with {@link translateUniqueViolationToDuplicate} when the model should own the
+ * message. Construct via {@link UniqueConstraintViolationError.detected}.
+ */
 declare class UniqueConstraintViolationError extends ConflictError {
   private constructor();
+  /**
+   * Builds a {@link UniqueConstraintViolationError} from the constraint details
+   * a driver reports, packaging them into a nested `violation` payload.
+   *
+   * @param input - The entity plus the offending constraint name, table, and
+   *   columns, and optional correlation ids.
+   */
   static detected(input: {
     entity: string;
     operation?: string;
@@ -307,6 +336,17 @@ declare class UniqueConstraintViolationError extends ConflictError {
     cause?: unknown;
   }): UniqueConstraintViolationError;
 }
+/**
+ * Translates a raw storage {@link UniqueConstraintViolation} into a domain-level
+ * {@link DuplicateError}. This is the seam where an infrastructure concern (a DB
+ * unique index firing) is re-expressed in the language of the model, so callers
+ * upstream catch a `DuplicateError` and never have to know a database was
+ * involved.
+ *
+ * @param input - The entity, the driver-reported `violation`, and optional
+ *   request context (`ctx`) carrying correlation ids and a clock instant.
+ * @returns A {@link DuplicateError} carrying the constraint name as its field hint.
+ */
 declare function translateUniqueViolationToDuplicate(input: {
   entity: string;
   operation?: string;
@@ -522,11 +562,36 @@ type IntegrationErrorMetadata = {
   statusCode?: number;
   responseCode?: string;
 };
+/**
+ * Raised when a call to an external provider fails — a timeout, an unreachable
+ * endpoint, or a malformed response. This is the boundary error that separates
+ * "our code is fine, the outside world misbehaved" from internal faults, which
+ * matters for retry and alerting decisions.
+ *
+ * Every instance records the `provider`, the `operation`, and timing
+ * (`startedAtIso` / `durationMs`) so failures are correlatable across services
+ * and a slow dependency is visible in the metadata. The discriminating
+ * {@link reason} lets callers decide whether a failure is worth retrying.
+ * Instances are frozen; construct through the static factories.
+ */
 declare class IntegrationError extends AppError {
   readonly reason: IntegrationErrorReason;
   private constructor();
+  /**
+   * The provider did not respond within the allotted time. Usually retryable,
+   * since a timeout leaves the outcome unknown rather than known-failed.
+   */
   static timeout(options: IntegrationErrorTimeoutOptions): IntegrationError;
+  /**
+   * The provider could not be reached at all (connection refused, DNS
+   * failure, network partition) — the request never landed.
+   */
   static unreachable(options: IntegrationErrorEndpointOptions): IntegrationError;
+  /**
+   * The provider answered, but with something the system cannot use — an
+   * unexpected status, an unparsable body, or a contract mismatch. Unlike a
+   * timeout this is a definite failure, so blind retries rarely help.
+   */
   static badResponse(options: IntegrationErrorEndpointOptions): IntegrationError;
 }
 type IntegrationErrorBaseOptions = {
@@ -556,7 +621,21 @@ declare class LegacyIncompatibleError extends AppError {
 }
 //#endregion
 //#region src/core/errors/not-found-error.d.ts
+/**
+ * Raised when a requested resource does not exist. Maps naturally onto an HTTP
+ * 404 at the edge, but stays transport-agnostic here.
+ *
+ * The `resource` name builds the message (`"<resource> not found"`) and, with
+ * the optional lookup `criteria`, lands in the metadata so logs show *what* was
+ * searched for without the caller having to restate it in the message.
+ */
 declare class NotFoundError extends AppError {
+  /**
+   * @param resource - Human-readable name of the missing resource (e.g. `"Order"`).
+   * @param criteria - Optional lookup keys used in the search; recorded in
+   *   metadata to aid debugging. Avoid putting sensitive values here.
+   * @param options - Optional cause, correlation ids, and extra metadata.
+   */
   constructor(resource: string, criteria?: Record<string, unknown>, options?: AppErrorOptions);
 }
 //#endregion
@@ -692,9 +771,27 @@ declare class ValidationCode {
 }
 //#endregion
 //#region src/core/errors/validation-error.d.ts
+/**
+ * Raised when a single input fails a validation rule — the canonical
+ * "this field is wrong, and here is why" error.
+ *
+ * It pins the offending `field` and a machine-readable `validationCode` into
+ * the metadata (merged ahead of any caller-supplied metadata) so an API layer
+ * can map the failure straight onto a form field without parsing the message.
+ * The fixed {@link ErrorCodes.validation} code lets callers catch all
+ * validation failures uniformly while still distinguishing the specific rule
+ * through `validationCode`.
+ */
 declare class ValidationError extends AppError {
+  /**
+   * @param field - The input that failed validation; surfaced as `metadata.field`.
+   * @param code - The specific rule that was violated; surfaced as `metadata.validationCode`.
+   * @param message - The developer-facing description of the failure.
+   * @param options - Optional cause, correlation ids, and extra metadata
+   *   (merged over the field/code metadata, never overwriting it by accident).
+   */
   constructor(field: ValidationField, code: ValidationCode, message: string, options?: AppErrorOptions);
 }
 //#endregion
-export { ErrorCodes as $, IdempotencyPayloadMismatchError as A, UniqueConstraintViolation as B, IntegrationErrorMetadata as C, IdempotencyFailureKind as D, IdempotencyErrorMetadata as E, AlreadyExistsError as F, AuthorizationErrorMetadata as G, translateUniqueViolationToDuplicate as H, ConflictError as I, AuthenticationError as J, AuthorizationErrorReason as K, ConflictErrorMetadata as L, payloadHash as M, sha256Hex as N, IdempotencyInProgressError as O, stableStringify as P, assertJsonSafeMetadata as Q, ConflictKind as R, IntegrationError as S, IdempotencyError as T, BusinessRuleViolationError as U, UniqueConstraintViolationError as V, AuthorizationError as W, AuthenticationErrorReason as X, AuthenticationErrorMetadata as Y, AppError as Z, SerializationMessages as _, TemporalError as a, JsonSafeValue as at, NotFoundError as b, TemporalPrecision as c, SerializationCodes as d, serializationErrorCode as et, SerializationDirection as f, SerializationInError as g, SerializationFailureCategory as h, NotYetValidError as i, JsonSafeRecord as it, IdempotencyReplayNotSupportedError as j, IdempotencyKeyMissingError as k, evaluateTemporalWindow as l, SerializationErrorMetadata as m, UnexpectedError as n, ErrorSeverity as nt, TemporalErrorMetadata as o, SerializationError as p, AuthorizationRequirement as q, ExpiredError as r, JsonSafePrimitive as rt, TemporalKind as s, ValidationError as t, AppErrorOptions as tt, SerializationBoundary as u, SerializationOutError as v, IntegrationErrorReason as w, LegacyIncompatibleError as x, safePreview as y, DuplicateError as z };
+export { serializationErrorCode as $, IdempotencyPayloadMismatchError as A, UniqueConstraintViolation as B, IntegrationErrorMetadata as C, IdempotencyFailureKind as D, IdempotencyErrorMetadata as E, AlreadyExistsError as F, AuthorizationErrorMetadata as G, translateUniqueViolationToDuplicate as H, ConflictError as I, AuthenticationError as J, AuthorizationErrorReason as K, ConflictErrorMetadata as L, payloadHash as M, sha256Hex as N, IdempotencyInProgressError as O, stableStringify as P, ErrorCodes as Q, ConflictKind as R, IntegrationError as S, IdempotencyError as T, BusinessRuleViolationError as U, UniqueConstraintViolationError as V, AuthorizationError as W, AuthenticationErrorReason as X, AuthenticationErrorMetadata as Y, assertJsonSafeMetadata as Z, SerializationMessages as _, TemporalError as a, NotFoundError as b, TemporalPrecision as c, SerializationCodes as d, SerializationDirection as f, SerializationInError as g, SerializationFailureCategory as h, NotYetValidError as i, IdempotencyReplayNotSupportedError as j, IdempotencyKeyMissingError as k, evaluateTemporalWindow as l, SerializationErrorMetadata as m, UnexpectedError as n, TemporalErrorMetadata as o, SerializationError as p, AuthorizationRequirement as q, ExpiredError as r, TemporalKind as s, ValidationError as t, SerializationBoundary as u, SerializationOutError as v, IntegrationErrorReason as w, LegacyIncompatibleError as x, safePreview as y, DuplicateError as z };
 //# sourceMappingURL=validation-error.d.ts.map