@cullet/erp-core 1.0.4 → 1.0.6

package/dist/validation-code.js

@@ -49,21 +49,31 @@ function serializationErrorCode(direction, category) {
 //#endregion
 //#region src/core/errors/utils/json-safe.ts
 const NON_SERIALIZABLE_PLACEHOLDER = "[NonSerializable]";
+const CIRCULAR_REFERENCE_PLACEHOLDER = "[Circular]";
 function isPlainObject(value) {
 	if (value === null || typeof value !== "object") return false;
 	const proto = Object.getPrototypeOf(value);
 	return proto === Object.prototype || proto === null;
 }
-function sanitizeValue(value) {
+function sanitizeValue(value, seen) {
 	if (value === null) return null;
 	const type = typeof value;
 	if (type === "string" || type === "number" || type === "boolean") return value;
 	if (type === "bigint" || type === "function" || type === "symbol" || value === void 0) return NON_SERIALIZABLE_PLACEHOLDER;
-	if (Array.isArray(value)) return value.map(sanitizeValue);
+	if (Array.isArray(value)) {
+		if (seen.has(value)) return CIRCULAR_REFERENCE_PLACEHOLDER;
+		seen.add(value);
+		const sanitized = value.map((item) => sanitizeValue(item, seen));
+		seen.delete(value);
+		return sanitized;
+	}
 	if (value instanceof Date) return NON_SERIALIZABLE_PLACEHOLDER;
 	if (!isPlainObject(value)) return NON_SERIALIZABLE_PLACEHOLDER;
+	if (seen.has(value)) return CIRCULAR_REFERENCE_PLACEHOLDER;
+	seen.add(value);
 	const result = {};
-	for (const [key, val] of Object.entries(value)) result[key] = sanitizeValue(val);
+	for (const [key, val] of Object.entries(value)) result[key] = sanitizeValue(val, seen);
+	seen.delete(value);
 	return result;
 }
 /**
@@ -72,14 +82,15 @@ function sanitizeValue(value) {
 * **Allowed:** string, number, boolean, null, arrays, and plain objects.
 *
 * **Converted to placeholder:** Date, BigInt, class instances, functions,
-* symbols, undefined.
+* symbols, undefined, and circular references (which would otherwise make
+* `JSON.stringify` throw).
 *
 * @throws {TypeError} If `input` is not a plain object at the root level.
 */
 function assertJsonSafeMetadata(input) {
 	if (input === void 0) return {};
 	if (!isPlainObject(input)) throw new TypeError("metadata must be a plain object (Record<string, unknown>).");
-	return sanitizeValue(input);
+	return sanitizeValue(input, /* @__PURE__ */ new WeakSet());
 }
 //#endregion
 //#region src/core/errors/app-error.ts
@@ -122,22 +133,45 @@ 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) {
-	if (Array.isArray(value)) return value.map((item) => sortKeysDeep(item));
+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]);
+		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));
+	return JSON.stringify(sortKeysDeep(value, /* @__PURE__ */ new WeakSet()));
 }
 function payloadHash(value) {
 	return sha256Hex(stableStringify(value));

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\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Constants\n// ─────────────────────────────────────────────────────────────────────────────\n\nconst NON_SERIALIZABLE_PLACEHOLDER = \"[NonSerializable]\";\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\nfunction sanitizeValue(value: unknown): 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        return value.map(sanitizeValue);\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    const result: Record<string, JsonSafeValue> = {};\n    for (const [key, val] of Object.entries(value)) {\n        result[key] = sanitizeValue(val);\n    }\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.\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) as JsonSafeRecord;\n}\n\nexport { assertJsonSafeMetadata, NON_SERIALIZABLE_PLACEHOLDER };\n","// Base application error for the domain/application layer.\n// Encapsulates a code, optional cause, and JSON-safe metadata.\n\nimport type { AppErrorOptions, ErrorSeverity, JsonSafeRecord } from \"./types\";\nimport { assertJsonSafeMetadata } from \"./utils\";\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            type: this.type,\n            severity: this.severity,\n            message: this.message,\n            publicMessage: this.publicMessage,\n            createdAtIso: this.createdAtIso,\n            metadata: this.metadata,\n        };\n\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\nfunction sha256Hex(value: string): string {\n    return createHash(\"sha256\").update(value, \"utf8\").digest(\"hex\");\n}\n\nfunction sortKeysDeep(value: unknown): unknown {\n    if (Array.isArray(value)) {\n        return value.map((item) => sortKeysDeep(item));\n    }\n\n    if (value instanceof Date) {\n        return value;\n    }\n\n    if (value && typeof value === \"object\") {\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]);\n        }\n\n        return ordered;\n    }\n\n    return value;\n}\n\nfunction stableStringify(value: unknown): string {\n    return JSON.stringify(sortKeysDeep(value));\n}\n\nfunction payloadHash(value: unknown): string {\n    return sha256Hex(stableStringify(value));\n}\n\nexport { payloadHash, sha256Hex, stableStringify };\n","import { AppError } from \"./app-error\";\nimport { ErrorCodes } from \"./error-codes\";\nimport type { AppErrorOptions } from \"./types\";\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/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\";\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 { AppErrorOptions, ErrorSeverity, JsonSafeRecord } from \"./types\";\nimport { assertJsonSafeMetadata } from \"./utils\";\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            type: this.type,\n            severity: this.severity,\n            message: this.message,\n            publicMessage: this.publicMessage,\n            createdAtIso: this.createdAtIso,\n            metadata: this.metadata,\n        };\n\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\";\nimport { ErrorCodes } from \"./error-codes\";\nimport type { AppErrorOptions } from \"./types\";\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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"}

package/dist/validation-error.d.ts

@@ -95,7 +95,8 @@ declare function serializationErrorCode(direction: SerializationCodeDirection, c
  * **Allowed:** string, number, boolean, null, arrays, and plain objects.
  *
  * **Converted to placeholder:** Date, BigInt, class instances, functions,
- * symbols, undefined.
+ * symbols, undefined, and circular references (which would otherwise make
+ * `JSON.stringify` throw).
  *
  * @throws {TypeError} If `input` is not a plain object at the root level.
  */
@@ -322,6 +323,19 @@ declare function translateUniqueViolationToDuplicate(input: {
 //#endregion
 //#region src/core/shared/hashing.d.ts
 declare function sha256Hex(value: string): string;
+/**
+ * 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`).
+ */
 declare function stableStringify(value: unknown): string;
 declare function payloadHash(value: unknown): string;
 //#endregion

package/meta.json

@@ -1,7 +1,7 @@
 {
     "schemaVersion": "2",
     "name": "erp-core",
-    "version": "1.0.4",
+    "version": "1.0.6",
     "description": "Core ERP com clean architecture, policies, erros e services de aplicação.",
     "compatibility": {
         "engines": {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cullet/erp-core",
-    "version": "1.0.4",
+    "version": "1.0.6",
     "description": "Core ERP with clean architecture, temporality, policies, and rule sets",
     "type": "module",
     "repository": {

package/src/core/domain/entity.ts

@@ -59,6 +59,12 @@ abstract class Entity<TIdentifier> {
     protected markAsModified(updatedAt: Date = new Date()): number {
         assertValidDate("updatedAt", updatedAt);
 
+        if (updatedAt.getTime() < this._createdAt.getTime()) {
+            throw new InvariantViolationException(
+                "updatedAt cannot be earlier than createdAt",
+            );
+        }
+
         this._updatedAt = cloneDate(updatedAt);
         this._aggregateVersion += 1;
 

package/src/core/errors/utils/index.ts

@@ -1,4 +1,5 @@
 export {
     assertJsonSafeMetadata,
+    CIRCULAR_REFERENCE_PLACEHOLDER,
     NON_SERIALIZABLE_PLACEHOLDER,
 } from "./json-safe";

package/src/core/errors/utils/json-safe.ts

@@ -7,6 +7,7 @@ import type { JsonSafeRecord, JsonSafeValue } from "../types";
 // ─────────────────────────────────────────────────────────────────────────────
 
 const NON_SERIALIZABLE_PLACEHOLDER = "[NonSerializable]";
+const CIRCULAR_REFERENCE_PLACEHOLDER = "[Circular]";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Internal helpers
@@ -18,7 +19,12 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
     return proto === Object.prototype || proto === null;
 }
 
-function sanitizeValue(value: unknown): JsonSafeValue {
+// `seen` tracks the ancestors on the current traversal branch (a DFS path), not
+// every object visited. This collapses true circular references to a placeholder
+// while still serializing the same object referenced more than once across
+// sibling branches (a DAG) — matching `JSON.stringify`, which only rejects
+// cycles, not shared references.
+function sanitizeValue(value: unknown, seen: WeakSet<object>): JsonSafeValue {
     // Null passthrough
     if (value === null) return null;
 
@@ -41,7 +47,11 @@ function sanitizeValue(value: unknown): JsonSafeValue {
 
     // Arrays (recursive)
     if (Array.isArray(value)) {
-        return value.map(sanitizeValue);
+        if (seen.has(value)) return CIRCULAR_REFERENCE_PLACEHOLDER;
+        seen.add(value);
+        const sanitized = value.map((item) => sanitizeValue(item, seen));
+        seen.delete(value);
+        return sanitized;
     }
 
     // Date → placeholder (could also use .toISOString() if preferred)
@@ -55,10 +65,13 @@ function sanitizeValue(value: unknown): JsonSafeValue {
     }
 
     // Plain object (recursive)
+    if (seen.has(value)) return CIRCULAR_REFERENCE_PLACEHOLDER;
+    seen.add(value);
     const result: Record<string, JsonSafeValue> = {};
     for (const [key, val] of Object.entries(value)) {
-        result[key] = sanitizeValue(val);
+        result[key] = sanitizeValue(val, seen);
     }
+    seen.delete(value);
     return result;
 }
 
@@ -72,7 +85,8 @@ function sanitizeValue(value: unknown): JsonSafeValue {
  * **Allowed:** string, number, boolean, null, arrays, and plain objects.
  *
  * **Converted to placeholder:** Date, BigInt, class instances, functions,
- * symbols, undefined.
+ * symbols, undefined, and circular references (which would otherwise make
+ * `JSON.stringify` throw).
  *
  * @throws {TypeError} If `input` is not a plain object at the root level.
  */
@@ -87,7 +101,11 @@ function assertJsonSafeMetadata(input: unknown): JsonSafeRecord {
         );
     }
 
-    return sanitizeValue(input) as JsonSafeRecord;
+    return sanitizeValue(input, new WeakSet<object>()) as JsonSafeRecord;
 }
 
-export { assertJsonSafeMetadata, NON_SERIALIZABLE_PLACEHOLDER };
+export {
+    assertJsonSafeMetadata,
+    CIRCULAR_REFERENCE_PLACEHOLDER,
+    NON_SERIALIZABLE_PLACEHOLDER,
+};

package/src/core/policies/defs/policy-semver.ts

@@ -12,16 +12,23 @@ interface ParsedSemver {
 
 function parseSemver(version: string): ParsedSemver {
     const withoutBuild = version.split("+")[0];
-    const [core, preRelease = null] = withoutBuild.split("-") as [
-        string,
-        string | undefined,
-    ];
+
+    // Split on the first hyphen only. A pre-release identifier may itself
+    // contain hyphens (e.g. "1.0.0-x-1"); `split("-")` would drop everything
+    // after the first one and corrupt the comparison.
+    const dashIndex = withoutBuild.indexOf("-");
+    const core =
+        dashIndex === -1 ? withoutBuild : withoutBuild.slice(0, dashIndex);
+    const preRelease =
+        dashIndex === -1 ? null : withoutBuild.slice(dashIndex + 1);
+
     const [major, minor, patch] = core.split(".").map(Number) as [
         number,
         number,
         number,
     ];
-    return { major, minor, patch, preRelease: preRelease ?? null };
+
+    return { major, minor, patch, preRelease };
 }
 
 function comparePreRelease(a: string, b: string): number {

package/src/core/policies/engines/condition-evaluator-reporter.ts

@@ -10,6 +10,8 @@ export type ConditionEvaluationReportTag =
     | "NULLISH_NUMERIC_OPERAND_NOT_ALLOWED"
     | "NULLISH_DATE_OPERAND_NOT_ALLOWED"
     | "INVALID_DATE_OPERAND"
+    | "INVALID_NUMERIC_OPERAND"
+    | "INVALID_SET_OPERAND"
     | "CONDITION_EVAL_THREW";
 
 export interface ConditionEvaluationReport {

package/src/core/policies/engines/v1/condition-evaluator.ts

@@ -21,6 +21,8 @@ const NULLISH_NUMERIC_OPERAND_NOT_ALLOWED_TAG =
     "NULLISH_NUMERIC_OPERAND_NOT_ALLOWED";
 const NULLISH_DATE_OPERAND_NOT_ALLOWED_TAG = "NULLISH_DATE_OPERAND_NOT_ALLOWED";
 const INVALID_DATE_OPERAND_TAG = "INVALID_DATE_OPERAND";
+const INVALID_NUMERIC_OPERAND_TAG = "INVALID_NUMERIC_OPERAND";
+const INVALID_SET_OPERAND_TAG = "INVALID_SET_OPERAND";
 const EMPTY_OR_CONDITION_TAG = "EMPTY_OR_CONDITION";
 const EMPTY_AND_CONDITION_TAG = "EMPTY_AND_CONDITION";
 const ISO_8601_UTC_DATE_PATTERN =
@@ -110,6 +112,18 @@ export class ConditionEvaluatorV1 {
         return `${INVALID_DATE_OPERAND_TAG}: "${node.field}" with operator "${node.op}" requires Date or ISO 8601 UTC string operands`;
     }
 
+    private static buildInvalidNumericOperandMessage(
+        node: ConditionLeafNode,
+    ): string {
+        return `${INVALID_NUMERIC_OPERAND_TAG}: "${node.field}" with operator "${node.op}" requires numeric operands`;
+    }
+
+    private static buildInvalidSetOperandMessage(
+        node: ConditionLeafNode,
+    ): string {
+        return `${INVALID_SET_OPERAND_TAG}: "${node.field}" with operator "${node.op}" requires an array operand`;
+    }
+
     private static buildEmptyOrConditionMessage(): string {
         return `${EMPTY_OR_CONDITION_TAG}: OR nodes must contain at least one child condition`;
     }
@@ -224,6 +238,56 @@ export class ConditionEvaluatorV1 {
         return Result.err(message);
     }
 
+    private reportInvalidNumericOperand(
+        node: ConditionLeafNode,
+        actual: unknown,
+    ): Result<boolean, string> {
+        const message =
+            ConditionEvaluatorV1.buildInvalidNumericOperandMessage(node);
+
+        this.options.reporter.error(
+            this.buildReport({
+                level: "error",
+                tag: INVALID_NUMERIC_OPERAND_TAG,
+                message,
+                details: {
+                    field: node.field,
+                    op: node.op,
+                    actual,
+                    expected: node.value,
+                    node,
+                },
+            }),
+        );
+
+        return Result.err(message);
+    }
+
+    private reportInvalidSetOperand(
+        node: ConditionLeafNode,
+        actual: unknown,
+    ): Result<boolean, string> {
+        const message =
+            ConditionEvaluatorV1.buildInvalidSetOperandMessage(node);
+
+        this.options.reporter.error(
+            this.buildReport({
+                level: "error",
+                tag: INVALID_SET_OPERAND_TAG,
+                message,
+                details: {
+                    field: node.field,
+                    op: node.op,
+                    actual,
+                    expected: node.value,
+                    node,
+                },
+            }),
+        );
+
+        return Result.err(message);
+    }
+
     private evaluateDateRelationalNode(
         node: ConditionLeafNode,
         actual: unknown,
@@ -406,6 +470,19 @@ export class ConditionEvaluatorV1 {
             return Result.err(message);
         }
 
+        // null + allowNull: a relational comparison against a missing value
+        // never matches.
+        if (actual === null) {
+            return Result.ok(false);
+        }
+
+        // Both operands must be numbers. A present but wrong-typed operand is a
+        // context/configuration error, surfaced like the date path instead of
+        // silently collapsing to "no match".
+        if (typeof actual !== "number" || typeof node.value !== "number") {
+            return this.reportInvalidNumericOperand(node, actual);
+        }
+
         return Result.ok(this.evaluateOperator(actual, node.op, node.value));
     }
 
@@ -443,6 +520,13 @@ export class ConditionEvaluatorV1 {
                 return this.evaluateNumericRelationalNode(node, actual);
             }
 
+            if (
+                (node.op === "in" || node.op === "notIn") &&
+                !Array.isArray(node.value)
+            ) {
+                return this.reportInvalidSetOperand(node, actual);
+            }
+
             return Result.ok(
                 this.evaluateOperator(actual, node.op, node.value),
             );

package/src/core/policies/utils/hash.ts

@@ -16,7 +16,11 @@ export class PolicyHashing {
         return sha256Hex(input);
     }
 
-    private static assertHashable(value: unknown, path: string): void {
+    private static assertHashable(
+        value: unknown,
+        path: string,
+        seen: WeakSet<object>,
+    ): void {
         if (value === null) {
             return;
         }
@@ -54,22 +58,30 @@ export class PolicyHashing {
             return;
         }
 
+        if (seen.has(value as object)) {
+            throw new TypeError(
+                `canonicalJson does not accept circular references (at ${path})`,
+            );
+        }
+        seen.add(value as object);
+
         if (Array.isArray(value)) {
             value.forEach((item, index) => {
-                PolicyHashing.assertHashable(item, `${path}[${index}]`);
+                PolicyHashing.assertHashable(item, `${path}[${index}]`, seen);
             });
-            return;
+        } else {
+            for (const [key, nested] of Object.entries(
+                value as Record<string, unknown>,
+            )) {
+                PolicyHashing.assertHashable(nested, `${path}.${key}`, seen);
+            }
         }
 
-        for (const [key, nested] of Object.entries(
-            value as Record<string, unknown>,
-        )) {
-            PolicyHashing.assertHashable(nested, `${path}.${key}`);
-        }
+        seen.delete(value as object);
     }
 
     static canonicalJson(value: unknown): string {
-        PolicyHashing.assertHashable(value, "$");
+        PolicyHashing.assertHashable(value, "$", new WeakSet<object>());
 
         return stableStringify(value);
     }

package/src/core/shared/hashing.ts

@@ -1,12 +1,23 @@
 import { createHash } from "node:crypto";
 
+const CIRCULAR_STRUCTURE_MESSAGE =
+    "Cannot stably stringify a circular structure";
+
 function sha256Hex(value: string): string {
     return createHash("sha256").update(value, "utf8").digest("hex");
 }
 
-function sortKeysDeep(value: unknown): unknown {
+// `seen` holds the current traversal branch so true cycles are rejected while
+// repeated (acyclic) references are still serialized — matching JSON.stringify.
+function sortKeysDeep(value: unknown, seen: WeakSet<object>): unknown {
     if (Array.isArray(value)) {
-        return value.map((item) => sortKeysDeep(item));
+        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) {
@@ -14,12 +25,17 @@ function sortKeysDeep(value: unknown): unknown {
     }
 
     if (value && typeof value === "object") {
+        if (seen.has(value)) {
+            throw new TypeError(CIRCULAR_STRUCTURE_MESSAGE);
+        }
+        seen.add(value);
         const record = value as Record<string, unknown>;
         const ordered = Object.create(null) as Record<string, unknown>;
 
         for (const key of Object.keys(record).sort()) {
-            ordered[key] = sortKeysDeep(record[key]);
+            ordered[key] = sortKeysDeep(record[key], seen);
         }
+        seen.delete(value);
 
         return ordered;
     }
@@ -27,8 +43,21 @@ function sortKeysDeep(value: unknown): unknown {
     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: unknown): string {
-    return JSON.stringify(sortKeysDeep(value));
+    return JSON.stringify(sortKeysDeep(value, new WeakSet<object>()));
 }
 
 function payloadHash(value: unknown): string {

package/src/core/shared/immutable.ts

@@ -14,13 +14,24 @@ type DeepReadonly<T> = T extends PrimitiveValue | Date
       : { readonly [TKey in keyof T]: DeepReadonly<T[TKey]> };
 
 function deepFreeze<T>(value: T): T {
+    return deepFreezeInternal(value, new WeakSet<object>());
+}
+
+function deepFreezeInternal<T>(value: T, seen: WeakSet<object>): T {
     if (typeof value !== "object" || value === null || value instanceof Date) {
         return value;
     }
 
+    // A value already on `seen` has been visited on this pass (cyclic graph or a
+    // shared reference); revisiting it would recurse forever.
+    if (seen.has(value)) {
+        return value;
+    }
+    seen.add(value);
+
     if (Array.isArray(value)) {
         for (const item of value) {
-            deepFreeze(item);
+            deepFreezeInternal(item, seen);
         }
 
         return Object.freeze(value);
@@ -29,7 +40,7 @@ function deepFreeze<T>(value: T): T {
     const objectValue = value as Record<PropertyKey, object | PrimitiveValue>;
 
     for (const propertyKey of Reflect.ownKeys(objectValue)) {
-        deepFreeze(objectValue[propertyKey]);
+        deepFreezeInternal(objectValue[propertyKey], seen);
     }
 
     return Object.freeze(value);

package/src/version.ts

@@ -4,4 +4,4 @@
 // Mantemos a versao aqui, dentro de src/, para que a copia full-control seja
 // auto-contida: ao copiar so o conteudo de src/, o entry nao depende de um
 // `../package.json` que deixaria de existir no projeto consumidor.
-export const version = "1.0.4";
+export const version = "1.0.6";