@cullet/erp-core 1.4.0 → 1.5.0

package/dist/validation-error.d.cts

@@ -54,11 +54,14 @@ declare function serializationErrorCode(direction: SerializationCodeDirection, c
 /**
  * Ensures metadata is JSON-serializable.
  *
- * **Allowed:** string, number, boolean, null, arrays, and plain objects.
+ * **Allowed:** finite number, string, boolean, null, arrays, and plain objects.
+ *
+ * **Dropped (mirroring `JSON.stringify`):** object properties whose value is
+ * `undefined` (the key is omitted); an `undefined` array item becomes `null`.
  *
  * **Converted to placeholder:** Date, BigInt, class instances, functions,
- * symbols, undefined, and circular references (which would otherwise make
- * `JSON.stringify` throw).
+ * symbols, non-finite numbers (`NaN`/`Infinity`), and circular references
+ * (which would otherwise make `JSON.stringify` throw).
  *
  * @throws {TypeError} If `input` is not a plain object at the root level.
  */
@@ -266,8 +269,7 @@ declare function translateUniqueViolationToDuplicate(input: {
   cause?: unknown;
 }): DuplicateError;
 //#endregion
-//#region src/core/shared/hashing.d.ts
-declare function sha256Hex(value: string): string;
+//#region src/core/shared/stable-stringify.d.ts
 /**
  * Deterministic JSON string with object keys sorted recursively, so key order
  * does not affect the output.
@@ -282,6 +284,9 @@ declare function sha256Hex(value: string): string;
  * @throws {TypeError} On circular references (mirroring `JSON.stringify`).
  */
 declare function stableStringify(value: unknown): string;
+//#endregion
+//#region src/core/shared/hashing.d.ts
+declare function sha256Hex(value: string): string;
 declare function payloadHash(value: unknown): string;
 //#endregion
 //#region src/core/errors/idempotency-error.d.ts

package/dist/validation-error.d.ts

@@ -54,11 +54,14 @@ declare function serializationErrorCode(direction: SerializationCodeDirection, c
 /**
  * Ensures metadata is JSON-serializable.
  *
- * **Allowed:** string, number, boolean, null, arrays, and plain objects.
+ * **Allowed:** finite number, string, boolean, null, arrays, and plain objects.
+ *
+ * **Dropped (mirroring `JSON.stringify`):** object properties whose value is
+ * `undefined` (the key is omitted); an `undefined` array item becomes `null`.
  *
  * **Converted to placeholder:** Date, BigInt, class instances, functions,
- * symbols, undefined, and circular references (which would otherwise make
- * `JSON.stringify` throw).
+ * symbols, non-finite numbers (`NaN`/`Infinity`), and circular references
+ * (which would otherwise make `JSON.stringify` throw).
  *
  * @throws {TypeError} If `input` is not a plain object at the root level.
  */
@@ -266,8 +269,7 @@ declare function translateUniqueViolationToDuplicate(input: {
   cause?: unknown;
 }): DuplicateError;
 //#endregion
-//#region src/core/shared/hashing.d.ts
-declare function sha256Hex(value: string): string;
+//#region src/core/shared/stable-stringify.d.ts
 /**
  * Deterministic JSON string with object keys sorted recursively, so key order
  * does not affect the output.
@@ -282,6 +284,9 @@ declare function sha256Hex(value: string): string;
  * @throws {TypeError} On circular references (mirroring `JSON.stringify`).
  */
 declare function stableStringify(value: unknown): string;
+//#endregion
+//#region src/core/shared/hashing.d.ts
+declare function sha256Hex(value: string): string;
 declare function payloadHash(value: unknown): string;
 //#endregion
 //#region src/core/errors/idempotency-error.d.ts

package/dist/value-object.cjs

@@ -1,3 +1,4 @@
+const require_stable_stringify = require("./stable-stringify.cjs");
 const require_immutable = require("./immutable.cjs");
 const require_plugin = require("./plugin.cjs");
 //#region src/core/domain/value-object.ts
@@ -14,6 +15,12 @@ var _ValueObject;
 * any risk of a consumer mutating shared state. Subclasses seal the instance
 * itself with {@link finalize} once their own fields are set.
 *
+* One exception: nested `Date` instances are cloned but NOT frozen —
+* `Object.freeze` does not block `setTime`/`setFullYear`, so a consumer of
+* `value` can still mutate an inner `Date` in place. Store instants as ISO
+* strings or epoch timestamps in the wrapped state (converting to `Date` only
+* in an accessor) when that guarantee matters.
+*
 * @typeParam T - The shape of the wrapped data.
 * @typeParam P - The primitive form produced by {@link toPrimitive} / {@link toJSON}.
 */
@@ -37,7 +44,7 @@ let ValueObject = class ValueObject {
 	* `@version` decorator — used to detect state persisted under an older shape.
 	*/
 	get contractVersion() {
-		return _ValueObject.CONTRACT_VERSION;
+		return this.constructor.CONTRACT_VERSION;
 	}
 	/**
 	* Freezes the instance shell, blocking reassignment of any own field.
@@ -66,11 +73,13 @@ let ValueObject = class ValueObject {
 	* same data are considered equal.
 	*
 	* Delegates to the registered equality {@link plugins}; with no plugin
-	* registered it falls back to comparing the serialized wrapped `value`.
+	* registered it falls back to comparing the serialized wrapped `value`,
+	* with object keys sorted so insertion order (e.g. code-built vs
+	* JSON-rehydrated) never affects the result.
 	* Subclasses may still override for a faster or domain-specific comparison.
 	*/
 	equals(other) {
-		return _ValueObject.plugins.invoke("equals", [this, other], { fallback: (a, b) => JSON.stringify(a.value) === JSON.stringify(b.value) });
+		return _ValueObject.plugins.invoke("equals", [this, other], { fallback: (a, b) => require_stable_stringify.stableStringify(a.value) === require_stable_stringify.stableStringify(b.value) });
 	}
 };
 ValueObject = _ValueObject = require_immutable.__decorate([require_immutable.version("1.0")], ValueObject);

package/dist/value-object.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"value-object.cjs","names":["PluginManager","makeImmutable","version"],"sources":["../src/core/domain/value-object.ts"],"sourcesContent":["import { PluginManager } from \"../plugins/index.js\";\nimport { type DeepReadonly, makeImmutable } from \"../shared/immutable.js\";\nimport { type ContractVersion, version } from \"../versioning/version.js\";\n\n/**\n * Extension point for value-object equality. A plugin implementing this\n * contract overrides how any two value objects are compared, letting the host\n * application swap in a structural comparator (e.g. `lodash.isEqual` over the\n * wrapped `value`) without every value object having to implement `equals` by\n * hand.\n */\ntype ValueObjectPluginContract = {\n    equals: (\n        a: ValueObject<unknown, unknown>,\n        b: ValueObject<unknown, unknown>,\n    ) => boolean;\n};\n\n/**\n * Base class for value objects — domain concepts defined entirely by their\n * contents, with no identity of their own. Two value objects are\n * interchangeable when they hold equal data, which is the opposite of an\n * {@link Entity} (compared by id). Money, a CPF, a date range: replacing one\n * instance with an equal one changes nothing about the model.\n *\n * Immutability is the defining guarantee here. The wrapped `value` is\n * deep-frozen on construction, so a value object can be shared freely without\n * any risk of a consumer mutating shared state. Subclasses seal the instance\n * itself with {@link finalize} once their own fields are set.\n *\n * @typeParam T - The shape of the wrapped data.\n * @typeParam P - The primitive form produced by {@link toPrimitive} / {@link toJSON}.\n */\n@version(\"1.0\")\nabstract class ValueObject<T, P> {\n    declare public static readonly CONTRACT_VERSION: ContractVersion;\n\n    /**\n     * Registry of equality plugins shared by every value object. Empty by\n     * default — when nothing is registered, {@link equals} falls back to a\n     * structural comparison of the wrapped `value`. Hosts register a plugin\n     * (e.g. `lodash.isEqual`) once at startup to customise equality globally.\n     */\n    public static readonly plugins =\n        new PluginManager<ValueObjectPluginContract>();\n\n    /** The wrapped data, deep-frozen so it can never be mutated after construction. */\n    public readonly value: DeepReadonly<T>;\n\n    /**\n     * Wraps `value`, deep-freezing it so the value object is immutable from the\n     * moment it exists. Declared `protected` because value objects are built\n     * through a validating subclass factory, never instantiated directly.\n     */\n    protected constructor(value: T) {\n        this.value = makeImmutable(value);\n    }\n\n    /**\n     * The schema/contract version stamped on this value-object type by the\n     * `@version` decorator — used to detect state persisted under an older shape.\n     */\n    public get contractVersion(): ContractVersion {\n        return ValueObject.CONTRACT_VERSION;\n    }\n\n    /**\n     * Freezes the instance shell, blocking reassignment of any own field.\n     *\n     * `value` is already deep-frozen by the constructor, so the wrapped data is\n     * immutable regardless. The instance itself is NOT frozen automatically\n     * because a subclass may still need to assign its own fields after\n     * `super(value)` runs. Call `finalize()` at the very end of the subclass\n     * constructor (after all fields are set) to make the whole value object\n     * immutable.\n     */\n    protected finalize(): void {\n        Object.freeze(this);\n    }\n\n    /**\n     * Hook for `JSON.stringify`. Delegates to {@link toPrimitive} so a value\n     * object serializes to its primitive form rather than exposing the internal\n     * `value` wrapper.\n     */\n    public toJSON(): P {\n        return this.toPrimitive();\n    }\n\n    /**\n     * Compares this value object with another by content. Because value objects\n     * carry no identity, two independently constructed instances holding the\n     * same data are considered equal.\n     *\n     * Delegates to the registered equality {@link plugins}; with no plugin\n     * registered it falls back to comparing the serialized wrapped `value`.\n     * Subclasses may still override for a faster or domain-specific comparison.\n     */\n    public equals(other: this): boolean {\n        return ValueObject.plugins.invoke(\"equals\", [this, other], {\n            fallback: (a, b) =>\n                JSON.stringify(a.value) === JSON.stringify(b.value),\n        });\n    }\n\n    /**\n     * Projects the value object down to a plain, serializable primitive form —\n     * the representation suitable for persistence, transport, or comparison.\n     */\n    public abstract toPrimitive(): P;\n}\n\nexport { type DeepReadonly, ValueObject, type ValueObjectPluginContract };\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAiCA,IAAA,cAAA,MACe,YAAkB;;;;;iBAUzB,IAAIA,eAAAA,cAAyC;;;;;;;CAUjD,YAAsB,OAAU;EAC5B,KAAK,QAAQC,kBAAAA,cAAc,KAAK;CACpC;;;;;CAMA,IAAW,kBAAmC;EAC1C,OAAA,aAAmB;CACvB;;;;;;;;;;;CAYA,WAA2B;EACvB,OAAO,OAAO,IAAI;CACtB;;;;;;CAOA,SAAmB;EACf,OAAO,KAAK,YAAY;CAC5B;;;;;;;;;;CAWA,OAAc,OAAsB;EAChC,OAAA,aAAmB,QAAQ,OAAO,UAAU,CAAC,MAAM,KAAK,GAAG,EACvD,WAAW,GAAG,MACV,KAAK,UAAU,EAAE,KAAK,MAAM,KAAK,UAAU,EAAE,KAAK,EAC1D,CAAC;CACL;AAOJ;2DA7ECC,kBAAAA,QAAQ,KAAK,CAAA,GAAA,WAAA"}
+{"version":3,"file":"value-object.cjs","names":["PluginManager","makeImmutable","stableStringify","version"],"sources":["../src/core/domain/value-object.ts"],"sourcesContent":["import { PluginManager } from \"../plugins/index.js\";\nimport { type DeepReadonly, makeImmutable } from \"../shared/immutable.js\";\nimport { stableStringify } from \"../shared/stable-stringify.js\";\nimport { type ContractVersion, version } from \"../versioning/version.js\";\n\n/**\n * Extension point for value-object equality. A plugin implementing this\n * contract overrides how any two value objects are compared, letting the host\n * application swap in a structural comparator (e.g. `lodash.isEqual` over the\n * wrapped `value`) without every value object having to implement `equals` by\n * hand.\n */\ntype ValueObjectPluginContract = {\n    equals: (\n        a: ValueObject<unknown, unknown>,\n        b: ValueObject<unknown, unknown>,\n    ) => boolean;\n};\n\n/**\n * Base class for value objects — domain concepts defined entirely by their\n * contents, with no identity of their own. Two value objects are\n * interchangeable when they hold equal data, which is the opposite of an\n * {@link Entity} (compared by id). Money, a CPF, a date range: replacing one\n * instance with an equal one changes nothing about the model.\n *\n * Immutability is the defining guarantee here. The wrapped `value` is\n * deep-frozen on construction, so a value object can be shared freely without\n * any risk of a consumer mutating shared state. Subclasses seal the instance\n * itself with {@link finalize} once their own fields are set.\n *\n * One exception: nested `Date` instances are cloned but NOT frozen —\n * `Object.freeze` does not block `setTime`/`setFullYear`, so a consumer of\n * `value` can still mutate an inner `Date` in place. Store instants as ISO\n * strings or epoch timestamps in the wrapped state (converting to `Date` only\n * in an accessor) when that guarantee matters.\n *\n * @typeParam T - The shape of the wrapped data.\n * @typeParam P - The primitive form produced by {@link toPrimitive} / {@link toJSON}.\n */\n@version(\"1.0\")\nabstract class ValueObject<T, P> {\n    declare public static readonly CONTRACT_VERSION: ContractVersion;\n\n    /**\n     * Registry of equality plugins shared by every value object. Empty by\n     * default — when nothing is registered, {@link equals} falls back to a\n     * structural comparison of the wrapped `value`. Hosts register a plugin\n     * (e.g. `lodash.isEqual`) once at startup to customise equality globally.\n     */\n    public static readonly plugins =\n        new PluginManager<ValueObjectPluginContract>();\n\n    /** The wrapped data, deep-frozen so it can never be mutated after construction. */\n    public readonly value: DeepReadonly<T>;\n\n    /**\n     * Wraps `value`, deep-freezing it so the value object is immutable from the\n     * moment it exists. Declared `protected` because value objects are built\n     * through a validating subclass factory, never instantiated directly.\n     */\n    protected constructor(value: T) {\n        this.value = makeImmutable(value);\n    }\n\n    /**\n     * The schema/contract version stamped on this value-object type by the\n     * `@version` decorator — used to detect state persisted under an older shape.\n     */\n    public get contractVersion(): ContractVersion {\n        return (this.constructor as typeof ValueObject).CONTRACT_VERSION;\n    }\n\n    /**\n     * Freezes the instance shell, blocking reassignment of any own field.\n     *\n     * `value` is already deep-frozen by the constructor, so the wrapped data is\n     * immutable regardless. The instance itself is NOT frozen automatically\n     * because a subclass may still need to assign its own fields after\n     * `super(value)` runs. Call `finalize()` at the very end of the subclass\n     * constructor (after all fields are set) to make the whole value object\n     * immutable.\n     */\n    protected finalize(): void {\n        Object.freeze(this);\n    }\n\n    /**\n     * Hook for `JSON.stringify`. Delegates to {@link toPrimitive} so a value\n     * object serializes to its primitive form rather than exposing the internal\n     * `value` wrapper.\n     */\n    public toJSON(): P {\n        return this.toPrimitive();\n    }\n\n    /**\n     * Compares this value object with another by content. Because value objects\n     * carry no identity, two independently constructed instances holding the\n     * same data are considered equal.\n     *\n     * Delegates to the registered equality {@link plugins}; with no plugin\n     * registered it falls back to comparing the serialized wrapped `value`,\n     * with object keys sorted so insertion order (e.g. code-built vs\n     * JSON-rehydrated) never affects the result.\n     * Subclasses may still override for a faster or domain-specific comparison.\n     */\n    public equals(other: this): boolean {\n        return ValueObject.plugins.invoke(\"equals\", [this, other], {\n            fallback: (a, b) =>\n                stableStringify(a.value) === stableStringify(b.value),\n        });\n    }\n\n    /**\n     * Projects the value object down to a plain, serializable primitive form —\n     * the representation suitable for persistence, transport, or comparison.\n     */\n    public abstract toPrimitive(): P;\n}\n\nexport { type DeepReadonly, ValueObject, type ValueObjectPluginContract };\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,IAAA,cAAA,MACe,YAAkB;;;;;iBAUzB,IAAIA,eAAAA,cAAyC;;;;;;;CAUjD,YAAsB,OAAU;EAC5B,KAAK,QAAQC,kBAAAA,cAAc,KAAK;CACpC;;;;;CAMA,IAAW,kBAAmC;EAC1C,OAAQ,KAAK,YAAmC;CACpD;;;;;;;;;;;CAYA,WAA2B;EACvB,OAAO,OAAO,IAAI;CACtB;;;;;;CAOA,SAAmB;EACf,OAAO,KAAK,YAAY;CAC5B;;;;;;;;;;;;CAaA,OAAc,OAAsB;EAChC,OAAA,aAAmB,QAAQ,OAAO,UAAU,CAAC,MAAM,KAAK,GAAG,EACvD,WAAW,GAAG,MACVC,yBAAAA,gBAAgB,EAAE,KAAK,MAAMA,yBAAAA,gBAAgB,EAAE,KAAK,EAC5D,CAAC;CACL;AAOJ;2DA/ECC,kBAAAA,QAAQ,KAAK,CAAA,GAAA,WAAA"}

package/dist/value-object.d.cts

@@ -26,6 +26,12 @@ type ValueObjectPluginContract = {
  * any risk of a consumer mutating shared state. Subclasses seal the instance
  * itself with {@link finalize} once their own fields are set.
  *
+ * One exception: nested `Date` instances are cloned but NOT frozen —
+ * `Object.freeze` does not block `setTime`/`setFullYear`, so a consumer of
+ * `value` can still mutate an inner `Date` in place. Store instants as ISO
+ * strings or epoch timestamps in the wrapped state (converting to `Date` only
+ * in an accessor) when that guarantee matters.
+ *
  * @typeParam T - The shape of the wrapped data.
  * @typeParam P - The primitive form produced by {@link toPrimitive} / {@link toJSON}.
  */
@@ -74,7 +80,9 @@ declare abstract class ValueObject<T, P> {
    * same data are considered equal.
    *
    * Delegates to the registered equality {@link plugins}; with no plugin
-   * registered it falls back to comparing the serialized wrapped `value`.
+   * registered it falls back to comparing the serialized wrapped `value`,
+   * with object keys sorted so insertion order (e.g. code-built vs
+   * JSON-rehydrated) never affects the result.
    * Subclasses may still override for a faster or domain-specific comparison.
    */
   equals(other: this): boolean;

package/dist/value-object.d.ts

@@ -26,6 +26,12 @@ type ValueObjectPluginContract = {
  * any risk of a consumer mutating shared state. Subclasses seal the instance
  * itself with {@link finalize} once their own fields are set.
  *
+ * One exception: nested `Date` instances are cloned but NOT frozen —
+ * `Object.freeze` does not block `setTime`/`setFullYear`, so a consumer of
+ * `value` can still mutate an inner `Date` in place. Store instants as ISO
+ * strings or epoch timestamps in the wrapped state (converting to `Date` only
+ * in an accessor) when that guarantee matters.
+ *
  * @typeParam T - The shape of the wrapped data.
  * @typeParam P - The primitive form produced by {@link toPrimitive} / {@link toJSON}.
  */
@@ -74,7 +80,9 @@ declare abstract class ValueObject<T, P> {
    * same data are considered equal.
    *
    * Delegates to the registered equality {@link plugins}; with no plugin
-   * registered it falls back to comparing the serialized wrapped `value`.
+   * registered it falls back to comparing the serialized wrapped `value`,
+   * with object keys sorted so insertion order (e.g. code-built vs
+   * JSON-rehydrated) never affects the result.
    * Subclasses may still override for a faster or domain-specific comparison.
    */
   equals(other: this): boolean;

package/dist/value-object.js

@@ -1,3 +1,4 @@
+import { t as stableStringify } from "./stable-stringify.js";
 import { i as version, n as __decorate, t as makeImmutable } from "./immutable.js";
 import { t as PluginManager } from "./plugin.js";
 //#region src/core/domain/value-object.ts
@@ -14,6 +15,12 @@ var _ValueObject;
 * any risk of a consumer mutating shared state. Subclasses seal the instance
 * itself with {@link finalize} once their own fields are set.
 *
+* One exception: nested `Date` instances are cloned but NOT frozen —
+* `Object.freeze` does not block `setTime`/`setFullYear`, so a consumer of
+* `value` can still mutate an inner `Date` in place. Store instants as ISO
+* strings or epoch timestamps in the wrapped state (converting to `Date` only
+* in an accessor) when that guarantee matters.
+*
 * @typeParam T - The shape of the wrapped data.
 * @typeParam P - The primitive form produced by {@link toPrimitive} / {@link toJSON}.
 */
@@ -37,7 +44,7 @@ let ValueObject = class ValueObject {
 	* `@version` decorator — used to detect state persisted under an older shape.
 	*/
 	get contractVersion() {
-		return _ValueObject.CONTRACT_VERSION;
+		return this.constructor.CONTRACT_VERSION;
 	}
 	/**
 	* Freezes the instance shell, blocking reassignment of any own field.
@@ -66,11 +73,13 @@ let ValueObject = class ValueObject {
 	* same data are considered equal.
 	*
 	* Delegates to the registered equality {@link plugins}; with no plugin
-	* registered it falls back to comparing the serialized wrapped `value`.
+	* registered it falls back to comparing the serialized wrapped `value`,
+	* with object keys sorted so insertion order (e.g. code-built vs
+	* JSON-rehydrated) never affects the result.
 	* Subclasses may still override for a faster or domain-specific comparison.
 	*/
 	equals(other) {
-		return _ValueObject.plugins.invoke("equals", [this, other], { fallback: (a, b) => JSON.stringify(a.value) === JSON.stringify(b.value) });
+		return _ValueObject.plugins.invoke("equals", [this, other], { fallback: (a, b) => stableStringify(a.value) === stableStringify(b.value) });
 	}
 };
 ValueObject = _ValueObject = __decorate([version("1.0")], ValueObject);

package/dist/value-object.js.map

@@ -1 +1 @@
-{"version":3,"file":"value-object.js","names":[],"sources":["../src/core/domain/value-object.ts"],"sourcesContent":["import { PluginManager } from \"../plugins/index.js\";\nimport { type DeepReadonly, makeImmutable } from \"../shared/immutable.js\";\nimport { type ContractVersion, version } from \"../versioning/version.js\";\n\n/**\n * Extension point for value-object equality. A plugin implementing this\n * contract overrides how any two value objects are compared, letting the host\n * application swap in a structural comparator (e.g. `lodash.isEqual` over the\n * wrapped `value`) without every value object having to implement `equals` by\n * hand.\n */\ntype ValueObjectPluginContract = {\n    equals: (\n        a: ValueObject<unknown, unknown>,\n        b: ValueObject<unknown, unknown>,\n    ) => boolean;\n};\n\n/**\n * Base class for value objects — domain concepts defined entirely by their\n * contents, with no identity of their own. Two value objects are\n * interchangeable when they hold equal data, which is the opposite of an\n * {@link Entity} (compared by id). Money, a CPF, a date range: replacing one\n * instance with an equal one changes nothing about the model.\n *\n * Immutability is the defining guarantee here. The wrapped `value` is\n * deep-frozen on construction, so a value object can be shared freely without\n * any risk of a consumer mutating shared state. Subclasses seal the instance\n * itself with {@link finalize} once their own fields are set.\n *\n * @typeParam T - The shape of the wrapped data.\n * @typeParam P - The primitive form produced by {@link toPrimitive} / {@link toJSON}.\n */\n@version(\"1.0\")\nabstract class ValueObject<T, P> {\n    declare public static readonly CONTRACT_VERSION: ContractVersion;\n\n    /**\n     * Registry of equality plugins shared by every value object. Empty by\n     * default — when nothing is registered, {@link equals} falls back to a\n     * structural comparison of the wrapped `value`. Hosts register a plugin\n     * (e.g. `lodash.isEqual`) once at startup to customise equality globally.\n     */\n    public static readonly plugins =\n        new PluginManager<ValueObjectPluginContract>();\n\n    /** The wrapped data, deep-frozen so it can never be mutated after construction. */\n    public readonly value: DeepReadonly<T>;\n\n    /**\n     * Wraps `value`, deep-freezing it so the value object is immutable from the\n     * moment it exists. Declared `protected` because value objects are built\n     * through a validating subclass factory, never instantiated directly.\n     */\n    protected constructor(value: T) {\n        this.value = makeImmutable(value);\n    }\n\n    /**\n     * The schema/contract version stamped on this value-object type by the\n     * `@version` decorator — used to detect state persisted under an older shape.\n     */\n    public get contractVersion(): ContractVersion {\n        return ValueObject.CONTRACT_VERSION;\n    }\n\n    /**\n     * Freezes the instance shell, blocking reassignment of any own field.\n     *\n     * `value` is already deep-frozen by the constructor, so the wrapped data is\n     * immutable regardless. The instance itself is NOT frozen automatically\n     * because a subclass may still need to assign its own fields after\n     * `super(value)` runs. Call `finalize()` at the very end of the subclass\n     * constructor (after all fields are set) to make the whole value object\n     * immutable.\n     */\n    protected finalize(): void {\n        Object.freeze(this);\n    }\n\n    /**\n     * Hook for `JSON.stringify`. Delegates to {@link toPrimitive} so a value\n     * object serializes to its primitive form rather than exposing the internal\n     * `value` wrapper.\n     */\n    public toJSON(): P {\n        return this.toPrimitive();\n    }\n\n    /**\n     * Compares this value object with another by content. Because value objects\n     * carry no identity, two independently constructed instances holding the\n     * same data are considered equal.\n     *\n     * Delegates to the registered equality {@link plugins}; with no plugin\n     * registered it falls back to comparing the serialized wrapped `value`.\n     * Subclasses may still override for a faster or domain-specific comparison.\n     */\n    public equals(other: this): boolean {\n        return ValueObject.plugins.invoke(\"equals\", [this, other], {\n            fallback: (a, b) =>\n                JSON.stringify(a.value) === JSON.stringify(b.value),\n        });\n    }\n\n    /**\n     * Projects the value object down to a plain, serializable primitive form —\n     * the representation suitable for persistence, transport, or comparison.\n     */\n    public abstract toPrimitive(): P;\n}\n\nexport { type DeepReadonly, ValueObject, type ValueObjectPluginContract };\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAiCA,IAAA,cAAA,MACe,YAAkB;;;;;iBAUzB,IAAI,cAAyC;;;;;;;CAUjD,YAAsB,OAAU;EAC5B,KAAK,QAAQ,cAAc,KAAK;CACpC;;;;;CAMA,IAAW,kBAAmC;EAC1C,OAAA,aAAmB;CACvB;;;;;;;;;;;CAYA,WAA2B;EACvB,OAAO,OAAO,IAAI;CACtB;;;;;;CAOA,SAAmB;EACf,OAAO,KAAK,YAAY;CAC5B;;;;;;;;;;CAWA,OAAc,OAAsB;EAChC,OAAA,aAAmB,QAAQ,OAAO,UAAU,CAAC,MAAM,KAAK,GAAG,EACvD,WAAW,GAAG,MACV,KAAK,UAAU,EAAE,KAAK,MAAM,KAAK,UAAU,EAAE,KAAK,EAC1D,CAAC;CACL;AAOJ;yCA7EC,QAAQ,KAAK,CAAA,GAAA,WAAA"}
+{"version":3,"file":"value-object.js","names":[],"sources":["../src/core/domain/value-object.ts"],"sourcesContent":["import { PluginManager } from \"../plugins/index.js\";\nimport { type DeepReadonly, makeImmutable } from \"../shared/immutable.js\";\nimport { stableStringify } from \"../shared/stable-stringify.js\";\nimport { type ContractVersion, version } from \"../versioning/version.js\";\n\n/**\n * Extension point for value-object equality. A plugin implementing this\n * contract overrides how any two value objects are compared, letting the host\n * application swap in a structural comparator (e.g. `lodash.isEqual` over the\n * wrapped `value`) without every value object having to implement `equals` by\n * hand.\n */\ntype ValueObjectPluginContract = {\n    equals: (\n        a: ValueObject<unknown, unknown>,\n        b: ValueObject<unknown, unknown>,\n    ) => boolean;\n};\n\n/**\n * Base class for value objects — domain concepts defined entirely by their\n * contents, with no identity of their own. Two value objects are\n * interchangeable when they hold equal data, which is the opposite of an\n * {@link Entity} (compared by id). Money, a CPF, a date range: replacing one\n * instance with an equal one changes nothing about the model.\n *\n * Immutability is the defining guarantee here. The wrapped `value` is\n * deep-frozen on construction, so a value object can be shared freely without\n * any risk of a consumer mutating shared state. Subclasses seal the instance\n * itself with {@link finalize} once their own fields are set.\n *\n * One exception: nested `Date` instances are cloned but NOT frozen —\n * `Object.freeze` does not block `setTime`/`setFullYear`, so a consumer of\n * `value` can still mutate an inner `Date` in place. Store instants as ISO\n * strings or epoch timestamps in the wrapped state (converting to `Date` only\n * in an accessor) when that guarantee matters.\n *\n * @typeParam T - The shape of the wrapped data.\n * @typeParam P - The primitive form produced by {@link toPrimitive} / {@link toJSON}.\n */\n@version(\"1.0\")\nabstract class ValueObject<T, P> {\n    declare public static readonly CONTRACT_VERSION: ContractVersion;\n\n    /**\n     * Registry of equality plugins shared by every value object. Empty by\n     * default — when nothing is registered, {@link equals} falls back to a\n     * structural comparison of the wrapped `value`. Hosts register a plugin\n     * (e.g. `lodash.isEqual`) once at startup to customise equality globally.\n     */\n    public static readonly plugins =\n        new PluginManager<ValueObjectPluginContract>();\n\n    /** The wrapped data, deep-frozen so it can never be mutated after construction. */\n    public readonly value: DeepReadonly<T>;\n\n    /**\n     * Wraps `value`, deep-freezing it so the value object is immutable from the\n     * moment it exists. Declared `protected` because value objects are built\n     * through a validating subclass factory, never instantiated directly.\n     */\n    protected constructor(value: T) {\n        this.value = makeImmutable(value);\n    }\n\n    /**\n     * The schema/contract version stamped on this value-object type by the\n     * `@version` decorator — used to detect state persisted under an older shape.\n     */\n    public get contractVersion(): ContractVersion {\n        return (this.constructor as typeof ValueObject).CONTRACT_VERSION;\n    }\n\n    /**\n     * Freezes the instance shell, blocking reassignment of any own field.\n     *\n     * `value` is already deep-frozen by the constructor, so the wrapped data is\n     * immutable regardless. The instance itself is NOT frozen automatically\n     * because a subclass may still need to assign its own fields after\n     * `super(value)` runs. Call `finalize()` at the very end of the subclass\n     * constructor (after all fields are set) to make the whole value object\n     * immutable.\n     */\n    protected finalize(): void {\n        Object.freeze(this);\n    }\n\n    /**\n     * Hook for `JSON.stringify`. Delegates to {@link toPrimitive} so a value\n     * object serializes to its primitive form rather than exposing the internal\n     * `value` wrapper.\n     */\n    public toJSON(): P {\n        return this.toPrimitive();\n    }\n\n    /**\n     * Compares this value object with another by content. Because value objects\n     * carry no identity, two independently constructed instances holding the\n     * same data are considered equal.\n     *\n     * Delegates to the registered equality {@link plugins}; with no plugin\n     * registered it falls back to comparing the serialized wrapped `value`,\n     * with object keys sorted so insertion order (e.g. code-built vs\n     * JSON-rehydrated) never affects the result.\n     * Subclasses may still override for a faster or domain-specific comparison.\n     */\n    public equals(other: this): boolean {\n        return ValueObject.plugins.invoke(\"equals\", [this, other], {\n            fallback: (a, b) =>\n                stableStringify(a.value) === stableStringify(b.value),\n        });\n    }\n\n    /**\n     * Projects the value object down to a plain, serializable primitive form —\n     * the representation suitable for persistence, transport, or comparison.\n     */\n    public abstract toPrimitive(): P;\n}\n\nexport { type DeepReadonly, ValueObject, type ValueObjectPluginContract };\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,IAAA,cAAA,MACe,YAAkB;;;;;iBAUzB,IAAI,cAAyC;;;;;;;CAUjD,YAAsB,OAAU;EAC5B,KAAK,QAAQ,cAAc,KAAK;CACpC;;;;;CAMA,IAAW,kBAAmC;EAC1C,OAAQ,KAAK,YAAmC;CACpD;;;;;;;;;;;CAYA,WAA2B;EACvB,OAAO,OAAO,IAAI;CACtB;;;;;;CAOA,SAAmB;EACf,OAAO,KAAK,YAAY;CAC5B;;;;;;;;;;;;CAaA,OAAc,OAAsB;EAChC,OAAA,aAAmB,QAAQ,OAAO,UAAU,CAAC,MAAM,KAAK,GAAG,EACvD,WAAW,GAAG,MACV,gBAAgB,EAAE,KAAK,MAAM,gBAAgB,EAAE,KAAK,EAC5D,CAAC;CACL;AAOJ;yCA/EC,QAAQ,KAAK,CAAA,GAAA,WAAA"}

package/meta.json

@@ -1,7 +1,7 @@
 {
     "schemaVersion": "2",
     "name": "erp-core",
-    "version": "1.4.0",
+    "version": "1.5.0",
     "description": "Núcleo arquitetural para ERP em TypeScript — entidades, value objects, erros tipados e policies declaráveis sobre clean architecture.",
     "compatibility": {
         "engines": {
@@ -83,6 +83,7 @@
         "PermissionSet",
         "RbacAuthorizer",
         "AuthorizerPort",
+        "rbacContextFields",
         "AbacRule",
         "AbacPolicySet",
         "AbacAuthorizer",
@@ -105,7 +106,8 @@
         "1.1.0 - **New: `ResultRepository`, `UseCaseObservability`, and `./application` subpath**",
         "1.2.0 - Add zod-free subpaths for the stable core primitives and a value-object equality plugin system.",
         "1.3.0 - Add zod-free subpaths for the stable core primitives and a value-object equality plugin system.",
-        "1.4.0 - Add a zod-free ABAC module and the `./abac` subpath."
+        "1.4.0 - Add a zod-free ABAC module and the `./abac` subpath.",
+        "1.5.0 - Add a zod-free ABAC module and the `./abac` subpath."
     ],
     "deprecated": false
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cullet/erp-core",
-    "version": "1.4.0",
+    "version": "1.5.0",
     "description": "Núcleo arquitetural para ERP em TypeScript — entidades, value objects, erros tipados e policies declaráveis sobre clean architecture.",
     "type": "module",
     "repository": {

package/src/core/application/commands/requested-by.ts

@@ -1,10 +1,12 @@
 import { ValidationCode } from "../../exceptions/validation-code.js";
 import { InvalidValueException } from "../../exceptions/validation-exception.js";
 import { ValidationField } from "../../exceptions/validation-field.js";
+import { UUID_PATTERN } from "../../shared/uuid.js";
 
 // Identifies who triggered a Command.
 // Two valid formats:
-//   - Human user: UUID v4 (e.g.: "550e8400-e29b-41d4-a716-446655440000")
+//   - Human user: canonical RFC-4122 UUID, versions 1–5 — the same pattern
+//     `UuidIdentifier` enforces (e.g.: "550e8400-e29b-41d4-a716-446655440000")
 //   - System identity: "system:<job>" where <job> is [a-z][a-z0-9]*(-[a-z0-9]+)*
 //     (e.g.: "system:late-fee-job", "system:email-sender")
 //
@@ -15,9 +17,6 @@ type RequestedByKind = "user" | "system";
 
 const REQUESTED_BY_FIELD = ValidationField.of("requestedBy");
 
-const UUID_PATTERN =
-    /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-
 // system:<job> where <job> starts with a lowercase letter and may have hyphens between segments
 const SYSTEM_IDENTITY_PATTERN = /^system:[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 

package/src/core/application/queries/query.ts

@@ -44,7 +44,12 @@ abstract class Query<
     Data extends QueryOutput = never,
     Failure = AppError,
 > extends UseCase<Input, Result<Data, Failure>> {
-    protected cacheStrategy(): CacheStrategy {
+    /**
+     * Declares how infrastructure should cache this query's result. Public so
+     * a caching adapter can actually read it off the instance; overrides must
+     * stay public.
+     */
+    public cacheStrategy(): CacheStrategy {
         return { kind: "NO_CACHE" };
     }
 }

package/src/core/application/use-case.ts

@@ -34,7 +34,7 @@ abstract class UseCase<
     declare public static readonly CONTRACT_VERSION: ContractVersion;
 
     public get contractVersion(): ContractVersion {
-        return UseCase.CONTRACT_VERSION;
+        return (this.constructor as typeof UseCase).CONTRACT_VERSION;
     }
 
     /**

package/src/core/domain/entity.ts

@@ -112,7 +112,7 @@ abstract class Entity<TIdentifier> {
      * an older shape.
      */
     public get contractVersion(): ContractVersion {
-        return Entity.CONTRACT_VERSION;
+        return (this.constructor as typeof Entity).CONTRACT_VERSION;
     }
 
     /**

package/src/core/domain/uuid-identifier.ts

@@ -1,13 +1,6 @@
+import { UUID_PATTERN } from "../shared/uuid.js";
 import { ValueObject } from "./value-object.js";
 
-/**
- * Canonical RFC-4122 UUID (versions 1–5), matched case-insensitively. Declared
- * once here so the dozens of typed identifiers a domain accumulates never have
- * to re-state the pattern.
- */
-const UUID_PATTERN =
-    /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-
 /**
  * Base class for UUID-backed identity value objects.
  *

package/src/core/domain/value-object.ts

@@ -1,5 +1,6 @@
 import { PluginManager } from "../plugins/index.js";
 import { type DeepReadonly, makeImmutable } from "../shared/immutable.js";
+import { stableStringify } from "../shared/stable-stringify.js";
 import { type ContractVersion, version } from "../versioning/version.js";
 
 /**
@@ -28,6 +29,12 @@ type ValueObjectPluginContract = {
  * any risk of a consumer mutating shared state. Subclasses seal the instance
  * itself with {@link finalize} once their own fields are set.
  *
+ * One exception: nested `Date` instances are cloned but NOT frozen —
+ * `Object.freeze` does not block `setTime`/`setFullYear`, so a consumer of
+ * `value` can still mutate an inner `Date` in place. Store instants as ISO
+ * strings or epoch timestamps in the wrapped state (converting to `Date` only
+ * in an accessor) when that guarantee matters.
+ *
  * @typeParam T - The shape of the wrapped data.
  * @typeParam P - The primitive form produced by {@link toPrimitive} / {@link toJSON}.
  */
@@ -61,7 +68,7 @@ abstract class ValueObject<T, P> {
      * `@version` decorator — used to detect state persisted under an older shape.
      */
     public get contractVersion(): ContractVersion {
-        return ValueObject.CONTRACT_VERSION;
+        return (this.constructor as typeof ValueObject).CONTRACT_VERSION;
     }
 
     /**
@@ -93,13 +100,15 @@ abstract class ValueObject<T, P> {
      * same data are considered equal.
      *
      * Delegates to the registered equality {@link plugins}; with no plugin
-     * registered it falls back to comparing the serialized wrapped `value`.
+     * registered it falls back to comparing the serialized wrapped `value`,
+     * with object keys sorted so insertion order (e.g. code-built vs
+     * JSON-rehydrated) never affects the result.
      * Subclasses may still override for a faster or domain-specific comparison.
      */
     public equals(other: this): boolean {
         return ValueObject.plugins.invoke("equals", [this, other], {
             fallback: (a, b) =>
-                JSON.stringify(a.value) === JSON.stringify(b.value),
+                stableStringify(a.value) === stableStringify(b.value),
         });
     }
 

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

@@ -30,18 +30,23 @@ function sanitizeValue(value: unknown, seen: WeakSet<object>): JsonSafeValue {
 
     const type = typeof value;
 
-    // Primitives
-    if (type === "string" || type === "number" || type === "boolean") {
+    // Primitives (non-finite numbers are not JSON-representable — placeholder)
+    if (type === "number") {
+        return Number.isFinite(value)
+            ? (value as number)
+            : NON_SERIALIZABLE_PLACEHOLDER;
+    }
+    if (type === "string" || type === "boolean") {
         return value as JsonSafeValue;
     }
 
+    // `undefined` only reaches here as an array item: object properties with
+    // undefined values are omitted by the plain-object branch below. Both
+    // mirror `JSON.stringify` semantics.
+    if (value === undefined) return null;
+
     // Non-serializable primitives
-    if (
-        type === "bigint" ||
-        type === "function" ||
-        type === "symbol" ||
-        value === undefined
-    ) {
+    if (type === "bigint" || type === "function" || type === "symbol") {
         return NON_SERIALIZABLE_PLACEHOLDER;
     }
 
@@ -69,6 +74,7 @@ function sanitizeValue(value: unknown, seen: WeakSet<object>): JsonSafeValue {
     seen.add(value);
     const result: Record<string, JsonSafeValue> = {};
     for (const [key, val] of Object.entries(value)) {
+        if (val === undefined) continue;
         result[key] = sanitizeValue(val, seen);
     }
     seen.delete(value);
@@ -82,11 +88,14 @@ function sanitizeValue(value: unknown, seen: WeakSet<object>): JsonSafeValue {
 /**
  * Ensures metadata is JSON-serializable.
  *
- * **Allowed:** string, number, boolean, null, arrays, and plain objects.
+ * **Allowed:** finite number, string, boolean, null, arrays, and plain objects.
+ *
+ * **Dropped (mirroring `JSON.stringify`):** object properties whose value is
+ * `undefined` (the key is omitted); an `undefined` array item becomes `null`.
  *
  * **Converted to placeholder:** Date, BigInt, class instances, functions,
- * symbols, undefined, and circular references (which would otherwise make
- * `JSON.stringify` throw).
+ * symbols, non-finite numbers (`NaN`/`Infinity`), and circular references
+ * (which would otherwise make `JSON.stringify` throw).
  *
  * @throws {TypeError} If `input` is not a plain object at the root level.
  */

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

@@ -1,5 +1,8 @@
 import { PolicyContextPath } from "../../context/index.js";
-import { PolicyDateUtils } from "../../utils/index.js";
+// Import the date util directly (not the utils barrel): the barrel re-exports
+// PolicyHashing, whose node:crypto import would needlessly drag a Node-only
+// API into the zod-free ./abac subpath.
+import { PolicyDateUtils } from "../../utils/date.js";
 import { Result } from "../../../result/result.js";
 
 import type {
@@ -213,6 +216,32 @@ export class ConditionEvaluatorV1 {
         return Result.err(message);
     }
 
+    private static containsInvalidDate(value: unknown): boolean {
+        if (value instanceof Date) {
+            return !PolicyDateUtils.isValid(value);
+        }
+        if (Array.isArray(value)) {
+            return value.some((item) =>
+                ConditionEvaluatorV1.containsInvalidDate(item),
+            );
+        }
+        return false;
+    }
+
+    // Valid Dates become their ISO string so equality/set operators compare
+    // instants instead of references; every other value passes through.
+    private static normalizeDateOperand(value: unknown): unknown {
+        if (value instanceof Date) {
+            return value.toISOString();
+        }
+        if (Array.isArray(value)) {
+            return value.map((item) =>
+                ConditionEvaluatorV1.normalizeDateOperand(item),
+            );
+        }
+        return value;
+    }
+
     private reportDateOperandError(
         node: ConditionLeafNode,
         actual: unknown,
@@ -527,6 +556,32 @@ export class ConditionEvaluatorV1 {
                 return this.reportInvalidSetOperand(node, actual);
             }
 
+            if (
+                node.op === "eq" ||
+                node.op === "neq" ||
+                node.op === "in" ||
+                node.op === "notIn"
+            ) {
+                // A Date operand would otherwise compare by reference and
+                // silently never match. Normalize valid Dates (either side,
+                // including set items) to their ISO string; an invalid Date is
+                // a context/configuration error, like the relational path.
+                if (
+                    ConditionEvaluatorV1.containsInvalidDate(actual) ||
+                    ConditionEvaluatorV1.containsInvalidDate(node.value)
+                ) {
+                    return this.reportDateOperandError(node, actual);
+                }
+
+                return Result.ok(
+                    this.evaluateOperator(
+                        ConditionEvaluatorV1.normalizeDateOperand(actual),
+                        node.op,
+                        ConditionEvaluatorV1.normalizeDateOperand(node.value),
+                    ),
+                );
+            }
+
             return Result.ok(
                 this.evaluateOperator(actual, node.op, node.value),
             );

package/src/core/shared/hashing.ts

@@ -1,65 +1,11 @@
 import { createHash } from "node:crypto";
 
-const CIRCULAR_STRUCTURE_MESSAGE =
-    "Cannot stably stringify a circular structure";
+import { stableStringify } from "./stable-stringify.js";
 
 function sha256Hex(value: string): string {
     return createHash("sha256").update(value, "utf8").digest("hex");
 }
 
-// `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)) {
-        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 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], 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: unknown): string {
-    return JSON.stringify(sortKeysDeep(value, new WeakSet<object>()));
-}
-
 function payloadHash(value: unknown): string {
     return sha256Hex(stableStringify(value));
 }