@cullet/erp-core 1.4.0 → 2.0.0

package/dist/validation-exception.d.cts

@@ -1,30 +1,45 @@
 import { t as ValidationCode } from "./validation-code.cjs";
 import { t as ValidationField } from "./validation-field.cjs";
-import { t as DomainException } from "./domain-exception.cjs";
 
+//#region src/core/exceptions/domain-exception.d.ts
+declare abstract class DomainException extends Error {
+  readonly cause?: unknown;
+  constructor(message: string, options?: {
+    cause?: unknown;
+  });
+}
+//#endregion
 //#region src/core/exceptions/business-rule-violation-exception.d.ts
 declare class BusinessRuleViolationException extends DomainException {
   readonly rule: string;
-  constructor(rule: string, message: string);
+  constructor(rule: string, message: string, options?: {
+    cause?: unknown;
+  });
 }
 //#endregion
 //#region src/core/exceptions/entity-not-found-exception.d.ts
 declare class EntityNotFoundException extends DomainException {
   readonly entityName: string;
   readonly identifier: string;
-  constructor(entityName: string, identifier: string);
+  constructor(entityName: string, identifier: string, options?: {
+    cause?: unknown;
+  });
 }
 //#endregion
 //#region src/core/exceptions/invalid-state-transition-exception.d.ts
 declare class InvalidStateTransitionException<TState extends string = string> extends DomainException {
   readonly from: TState;
   readonly to: TState;
-  constructor(from: TState, to: TState, message: string);
+  constructor(from: TState, to: TState, message?: string, options?: {
+    cause?: unknown;
+  });
 }
 //#endregion
 //#region src/core/exceptions/invariant-violation-exception.d.ts
 declare class InvariantViolationException extends DomainException {
-  constructor(message: string);
+  constructor(message: string, options?: {
+    cause?: unknown;
+  });
 }
 //#endregion
 //#region src/core/exceptions/validation-exception.d.ts
@@ -36,15 +51,24 @@ interface ValidationViolation {
 declare class ValidationException extends DomainException {
   readonly field: ValidationField;
   readonly code: ValidationCode;
-  constructor(field: ValidationField, code: ValidationCode, message: string);
+  constructor(field: ValidationField, code: ValidationCode, message: string, options?: {
+    cause?: unknown;
+  });
 }
 declare class MultipleValidationException extends DomainException {
   readonly violations: readonly ValidationViolation[];
-  constructor(violations: readonly ValidationViolation[]);
+  constructor(violations: readonly ValidationViolation[], options?: {
+    cause?: unknown;
+  });
+  get count(): number;
+  get first(): ValidationViolation;
+  byField(field: ValidationField): readonly ValidationViolation[];
 }
 declare class InvalidValueException extends ValidationException {
-  constructor(field: ValidationField, code: ValidationCode, message: string);
+  constructor(field: ValidationField, code: ValidationCode, message: string, options?: {
+    cause?: unknown;
+  });
 }
 //#endregion
-export { InvariantViolationException as a, BusinessRuleViolationException as c, ValidationViolation as i, MultipleValidationException as n, InvalidStateTransitionException as o, ValidationException as r, EntityNotFoundException as s, InvalidValueException as t };
+export { InvariantViolationException as a, BusinessRuleViolationException as c, ValidationViolation as i, DomainException as l, MultipleValidationException as n, InvalidStateTransitionException as o, ValidationException as r, EntityNotFoundException as s, InvalidValueException as t };
 //# sourceMappingURL=validation-exception.d.cts.map

package/dist/validation-exception.d.ts

@@ -1,30 +1,45 @@
 import { t as ValidationCode } from "./validation-code.js";
 import { t as ValidationField } from "./validation-field.js";
-import { t as DomainException } from "./domain-exception.js";
 
+//#region src/core/exceptions/domain-exception.d.ts
+declare abstract class DomainException extends Error {
+  readonly cause?: unknown;
+  constructor(message: string, options?: {
+    cause?: unknown;
+  });
+}
+//#endregion
 //#region src/core/exceptions/business-rule-violation-exception.d.ts
 declare class BusinessRuleViolationException extends DomainException {
   readonly rule: string;
-  constructor(rule: string, message: string);
+  constructor(rule: string, message: string, options?: {
+    cause?: unknown;
+  });
 }
 //#endregion
 //#region src/core/exceptions/entity-not-found-exception.d.ts
 declare class EntityNotFoundException extends DomainException {
   readonly entityName: string;
   readonly identifier: string;
-  constructor(entityName: string, identifier: string);
+  constructor(entityName: string, identifier: string, options?: {
+    cause?: unknown;
+  });
 }
 //#endregion
 //#region src/core/exceptions/invalid-state-transition-exception.d.ts
 declare class InvalidStateTransitionException<TState extends string = string> extends DomainException {
   readonly from: TState;
   readonly to: TState;
-  constructor(from: TState, to: TState, message: string);
+  constructor(from: TState, to: TState, message?: string, options?: {
+    cause?: unknown;
+  });
 }
 //#endregion
 //#region src/core/exceptions/invariant-violation-exception.d.ts
 declare class InvariantViolationException extends DomainException {
-  constructor(message: string);
+  constructor(message: string, options?: {
+    cause?: unknown;
+  });
 }
 //#endregion
 //#region src/core/exceptions/validation-exception.d.ts
@@ -36,15 +51,24 @@ interface ValidationViolation {
 declare class ValidationException extends DomainException {
   readonly field: ValidationField;
   readonly code: ValidationCode;
-  constructor(field: ValidationField, code: ValidationCode, message: string);
+  constructor(field: ValidationField, code: ValidationCode, message: string, options?: {
+    cause?: unknown;
+  });
 }
 declare class MultipleValidationException extends DomainException {
   readonly violations: readonly ValidationViolation[];
-  constructor(violations: readonly ValidationViolation[]);
+  constructor(violations: readonly ValidationViolation[], options?: {
+    cause?: unknown;
+  });
+  get count(): number;
+  get first(): ValidationViolation;
+  byField(field: ValidationField): readonly ValidationViolation[];
 }
 declare class InvalidValueException extends ValidationException {
-  constructor(field: ValidationField, code: ValidationCode, message: string);
+  constructor(field: ValidationField, code: ValidationCode, message: string, options?: {
+    cause?: unknown;
+  });
 }
 //#endregion
-export { InvariantViolationException as a, BusinessRuleViolationException as c, ValidationViolation as i, MultipleValidationException as n, InvalidStateTransitionException as o, ValidationException as r, EntityNotFoundException as s, InvalidValueException as t };
+export { InvariantViolationException as a, BusinessRuleViolationException as c, ValidationViolation as i, DomainException as l, MultipleValidationException as n, InvalidStateTransitionException as o, ValidationException as r, EntityNotFoundException as s, InvalidValueException as t };
 //# sourceMappingURL=validation-exception.d.ts.map

package/dist/validation-exception.js

@@ -1,21 +1,32 @@
 import { t as DomainException } from "./domain-exception.js";
+import { t as InvariantViolationException } from "./invariant-violation-exception.js";
 //#region src/core/exceptions/validation-exception.ts
 var ValidationException = class extends DomainException {
-	constructor(field, code, message) {
-		super(message);
+	constructor(field, code, message, options) {
+		super(message, options);
 		this.field = field;
 		this.code = code;
 	}
 };
 var MultipleValidationException = class extends DomainException {
-	constructor(violations) {
-		super(violations.map((v) => v.message).join("; "));
+	constructor(violations, options) {
+		if (violations.length === 0) throw new InvariantViolationException("MultipleValidationException requires at least one violation.");
+		super(violations.map((v) => v.message).join("; "), options);
 		this.violations = violations;
 	}
+	get count() {
+		return this.violations.length;
+	}
+	get first() {
+		return this.violations[0];
+	}
+	byField(field) {
+		return this.violations.filter((v) => v.field.equals(field));
+	}
 };
 var InvalidValueException = class extends ValidationException {
-	constructor(field, code, message) {
-		super(field, code, message);
+	constructor(field, code, message, options) {
+		super(field, code, message, options);
 	}
 };
 //#endregion

package/dist/validation-exception.js.map

@@ -1 +1 @@
-{"version":3,"file":"validation-exception.js","names":[],"sources":["../src/core/exceptions/validation-exception.ts"],"sourcesContent":["import { DomainException } from \"./domain-exception.js\";\nimport { ValidationCode } from \"./validation-code.js\";\nimport { ValidationField } from \"./validation-field.js\";\n\nexport interface ValidationViolation {\n    readonly field: ValidationField;\n    readonly code: ValidationCode;\n    readonly message: string;\n}\n\nclass ValidationException extends DomainException {\n    constructor(\n        public readonly field: ValidationField,\n        public readonly code: ValidationCode,\n        message: string,\n    ) {\n        super(message);\n    }\n}\n\n// Carries multiple validation violations from a single operation (e.g. bulk validation).\n// Use when you need to report all field errors at once rather than failing on the first.\nclass MultipleValidationException extends DomainException {\n    constructor(public readonly violations: readonly ValidationViolation[]) {\n        super(violations.map((v) => v.message).join(\"; \"));\n    }\n}\n\nclass InvalidValueException extends ValidationException {\n    constructor(field: ValidationField, code: ValidationCode, message: string) {\n        super(field, code, message);\n    }\n}\n\nexport {\n    InvalidValueException,\n    MultipleValidationException,\n    ValidationException,\n};\n"],"mappings":";;AAUA,IAAM,sBAAN,cAAkC,gBAAgB;CAC9C,YACI,OACA,MACA,SACF;EACE,MAAM,OAAO;EAJG,KAAA,QAAA;EACA,KAAA,OAAA;CAIpB;AACJ;AAIA,IAAM,8BAAN,cAA0C,gBAAgB;CACtD,YAAY,YAA4D;EACpE,MAAM,WAAW,KAAK,MAAM,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;EADzB,KAAA,aAAA;CAE5B;AACJ;AAEA,IAAM,wBAAN,cAAoC,oBAAoB;CACpD,YAAY,OAAwB,MAAsB,SAAiB;EACvE,MAAM,OAAO,MAAM,OAAO;CAC9B;AACJ"}
+{"version":3,"file":"validation-exception.js","names":[],"sources":["../src/core/exceptions/validation-exception.ts"],"sourcesContent":["import { DomainException } from \"./domain-exception.js\";\nimport { InvariantViolationException } from \"./invariant-violation-exception.js\";\nimport { ValidationCode } from \"./validation-code.js\";\nimport { ValidationField } from \"./validation-field.js\";\n\nexport interface ValidationViolation {\n    readonly field: ValidationField;\n    readonly code: ValidationCode;\n    readonly message: string;\n}\n\n// Extensible base for a single-field validation failure. Prefer throwing the\n// concrete InvalidValueException below so callers can `instanceof` the common\n// case; extend this directly only when you need a distinct validation subtype.\nclass ValidationException extends DomainException {\n    constructor(\n        public readonly field: ValidationField,\n        public readonly code: ValidationCode,\n        message: string,\n        options?: { cause?: unknown },\n    ) {\n        super(message, options);\n    }\n}\n\n// Carries multiple validation violations from a single operation (e.g. bulk validation).\n// Use when you need to report all field errors at once rather than failing on the first.\nclass MultipleValidationException extends DomainException {\n    constructor(\n        public readonly violations: readonly ValidationViolation[],\n        options?: { cause?: unknown },\n    ) {\n        // An aggregate with no violations is a caller bug: it produces a\n        // messageless, contentless exception. Fail fast as a broken invariant.\n        if (violations.length === 0) {\n            throw new InvariantViolationException(\n                \"MultipleValidationException requires at least one violation.\",\n            );\n        }\n        super(violations.map((v) => v.message).join(\"; \"), options);\n    }\n\n    // Number of accumulated violations (always >= 1).\n    get count(): number {\n        return this.violations.length;\n    }\n\n    // The first accumulated violation.\n    get first(): ValidationViolation {\n        return this.violations[0];\n    }\n\n    // Violations targeting the given field.\n    byField(field: ValidationField): readonly ValidationViolation[] {\n        return this.violations.filter((v) => v.field.equals(field));\n    }\n}\n\n// The canonical concrete validation exception, thrown across the domain\n// (rbac/abac/policies/commands) when a single input value is invalid. Its\n// identity is exactly that: the named, catchable \"a value was invalid\" case,\n// versus ValidationException as the open base.\nclass InvalidValueException extends ValidationException {\n    constructor(\n        field: ValidationField,\n        code: ValidationCode,\n        message: string,\n        options?: { cause?: unknown },\n    ) {\n        super(field, code, message, options);\n    }\n}\n\nexport {\n    InvalidValueException,\n    MultipleValidationException,\n    ValidationException,\n};\n"],"mappings":";;;AAcA,IAAM,sBAAN,cAAkC,gBAAgB;CAC9C,YACI,OACA,MACA,SACA,SACF;EACE,MAAM,SAAS,OAAO;EALN,KAAA,QAAA;EACA,KAAA,OAAA;CAKpB;AACJ;AAIA,IAAM,8BAAN,cAA0C,gBAAgB;CACtD,YACI,YACA,SACF;EAGE,IAAI,WAAW,WAAW,GACtB,MAAM,IAAI,4BACN,8DACJ;EAEJ,MAAM,WAAW,KAAK,MAAM,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,OAAO;EAV1C,KAAA,aAAA;CAWpB;CAGA,IAAI,QAAgB;EAChB,OAAO,KAAK,WAAW;CAC3B;CAGA,IAAI,QAA6B;EAC7B,OAAO,KAAK,WAAW;CAC3B;CAGA,QAAQ,OAAwD;EAC5D,OAAO,KAAK,WAAW,QAAQ,MAAM,EAAE,MAAM,OAAO,KAAK,CAAC;CAC9D;AACJ;AAMA,IAAM,wBAAN,cAAoC,oBAAoB;CACpD,YACI,OACA,MACA,SACA,SACF;EACE,MAAM,OAAO,MAAM,SAAS,OAAO;CACvC;AACJ"}

package/dist/validation-field.cjs

@@ -13,6 +13,9 @@ var ValidationField = class ValidationField {
 	toString() {
 		return this.value;
 	}
+	toJSON() {
+		return this.value;
+	}
 	equals(other) {
 		return this.value === other.value;
 	}

package/dist/validation-field.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"validation-field.cjs","names":[],"sources":["../src/core/exceptions/validation-field.ts"],"sourcesContent":["// Object-oriented representation of validation fields.\n// Indicates WHERE a validation error occurred.\n// This is a minimal base class — field catalogs are defined per domain/module.\n\nclass ValidationField {\n    public readonly value: string;\n\n    private constructor(value: string) {\n        this.value = value;\n    }\n\n    // Factory for custom or domain-specific fields\n    public static of(value: string): ValidationField {\n        return new ValidationField(value);\n    }\n\n    // Creates a nested field path: parent.nested('child') -> 'parent.child'\n    public nested(child: string | ValidationField): ValidationField {\n        const childValue =\n            child instanceof ValidationField ? child.value : child;\n        return new ValidationField(`${this.value}.${childValue}`);\n    }\n\n    public toString(): string {\n        return this.value;\n    }\n\n    public equals(other: ValidationField): boolean {\n        return this.value === other.value;\n    }\n}\n\nexport { ValidationField };\n"],"mappings":";AAIA,IAAM,kBAAN,MAAM,gBAAgB;CAGlB,YAAoB,OAAe;EAC/B,KAAK,QAAQ;CACjB;CAGA,OAAc,GAAG,OAAgC;EAC7C,OAAO,IAAI,gBAAgB,KAAK;CACpC;CAGA,OAAc,OAAkD;EAC5D,MAAM,aACF,iBAAiB,kBAAkB,MAAM,QAAQ;EACrD,OAAO,IAAI,gBAAgB,GAAG,KAAK,MAAM,GAAG,YAAY;CAC5D;CAEA,WAA0B;EACtB,OAAO,KAAK;CAChB;CAEA,OAAc,OAAiC;EAC3C,OAAO,KAAK,UAAU,MAAM;CAChC;AACJ"}
+{"version":3,"file":"validation-field.cjs","names":[],"sources":["../src/core/exceptions/validation-field.ts"],"sourcesContent":["// Object-oriented representation of validation fields.\n// Indicates WHERE a validation error occurred.\n// This is a minimal base class — field catalogs are defined per domain/module.\n\nclass ValidationField {\n    public readonly value: string;\n\n    private constructor(value: string) {\n        this.value = value;\n    }\n\n    // Factory for custom or domain-specific fields\n    public static of(value: string): ValidationField {\n        return new ValidationField(value);\n    }\n\n    // Creates a nested field path: parent.nested('child') -> 'parent.child'.\n    // The separator is a literal '.' and segments are NOT escaped, so\n    // of('a.b') and of('a').nested('b') collapse to the same path and compare\n    // equal — a field name that itself contains '.' is indistinguishable from\n    // a nested path. Keep segment names dot-free if that distinction matters.\n    public nested(child: string | ValidationField): ValidationField {\n        const childValue =\n            child instanceof ValidationField ? child.value : child;\n        return new ValidationField(`${this.value}.${childValue}`);\n    }\n\n    public toString(): string {\n        return this.value;\n    }\n\n    // Serialize to the bare field path, so JSON.stringify of a violation yields\n    // \"email\" rather than { \"value\": \"email\" }. Mirrors ValidationCode.\n    public toJSON(): string {\n        return this.value;\n    }\n\n    public equals(other: ValidationField): boolean {\n        return this.value === other.value;\n    }\n}\n\nexport { ValidationField };\n"],"mappings":";AAIA,IAAM,kBAAN,MAAM,gBAAgB;CAGlB,YAAoB,OAAe;EAC/B,KAAK,QAAQ;CACjB;CAGA,OAAc,GAAG,OAAgC;EAC7C,OAAO,IAAI,gBAAgB,KAAK;CACpC;CAOA,OAAc,OAAkD;EAC5D,MAAM,aACF,iBAAiB,kBAAkB,MAAM,QAAQ;EACrD,OAAO,IAAI,gBAAgB,GAAG,KAAK,MAAM,GAAG,YAAY;CAC5D;CAEA,WAA0B;EACtB,OAAO,KAAK;CAChB;CAIA,SAAwB;EACpB,OAAO,KAAK;CAChB;CAEA,OAAc,OAAiC;EAC3C,OAAO,KAAK,UAAU,MAAM;CAChC;AACJ"}

package/dist/validation-field.d.cts

@@ -5,6 +5,7 @@ declare class ValidationField {
   static of(value: string): ValidationField;
   nested(child: string | ValidationField): ValidationField;
   toString(): string;
+  toJSON(): string;
   equals(other: ValidationField): boolean;
 }
 //#endregion

package/dist/validation-field.d.ts

@@ -5,6 +5,7 @@ declare class ValidationField {
   static of(value: string): ValidationField;
   nested(child: string | ValidationField): ValidationField;
   toString(): string;
+  toJSON(): string;
   equals(other: ValidationField): boolean;
 }
 //#endregion

package/dist/validation-field.js

@@ -13,6 +13,9 @@ var ValidationField = class ValidationField {
 	toString() {
 		return this.value;
 	}
+	toJSON() {
+		return this.value;
+	}
 	equals(other) {
 		return this.value === other.value;
 	}

package/dist/validation-field.js.map

@@ -1 +1 @@
-{"version":3,"file":"validation-field.js","names":[],"sources":["../src/core/exceptions/validation-field.ts"],"sourcesContent":["// Object-oriented representation of validation fields.\n// Indicates WHERE a validation error occurred.\n// This is a minimal base class — field catalogs are defined per domain/module.\n\nclass ValidationField {\n    public readonly value: string;\n\n    private constructor(value: string) {\n        this.value = value;\n    }\n\n    // Factory for custom or domain-specific fields\n    public static of(value: string): ValidationField {\n        return new ValidationField(value);\n    }\n\n    // Creates a nested field path: parent.nested('child') -> 'parent.child'\n    public nested(child: string | ValidationField): ValidationField {\n        const childValue =\n            child instanceof ValidationField ? child.value : child;\n        return new ValidationField(`${this.value}.${childValue}`);\n    }\n\n    public toString(): string {\n        return this.value;\n    }\n\n    public equals(other: ValidationField): boolean {\n        return this.value === other.value;\n    }\n}\n\nexport { ValidationField };\n"],"mappings":";AAIA,IAAM,kBAAN,MAAM,gBAAgB;CAGlB,YAAoB,OAAe;EAC/B,KAAK,QAAQ;CACjB;CAGA,OAAc,GAAG,OAAgC;EAC7C,OAAO,IAAI,gBAAgB,KAAK;CACpC;CAGA,OAAc,OAAkD;EAC5D,MAAM,aACF,iBAAiB,kBAAkB,MAAM,QAAQ;EACrD,OAAO,IAAI,gBAAgB,GAAG,KAAK,MAAM,GAAG,YAAY;CAC5D;CAEA,WAA0B;EACtB,OAAO,KAAK;CAChB;CAEA,OAAc,OAAiC;EAC3C,OAAO,KAAK,UAAU,MAAM;CAChC;AACJ"}
+{"version":3,"file":"validation-field.js","names":[],"sources":["../src/core/exceptions/validation-field.ts"],"sourcesContent":["// Object-oriented representation of validation fields.\n// Indicates WHERE a validation error occurred.\n// This is a minimal base class — field catalogs are defined per domain/module.\n\nclass ValidationField {\n    public readonly value: string;\n\n    private constructor(value: string) {\n        this.value = value;\n    }\n\n    // Factory for custom or domain-specific fields\n    public static of(value: string): ValidationField {\n        return new ValidationField(value);\n    }\n\n    // Creates a nested field path: parent.nested('child') -> 'parent.child'.\n    // The separator is a literal '.' and segments are NOT escaped, so\n    // of('a.b') and of('a').nested('b') collapse to the same path and compare\n    // equal — a field name that itself contains '.' is indistinguishable from\n    // a nested path. Keep segment names dot-free if that distinction matters.\n    public nested(child: string | ValidationField): ValidationField {\n        const childValue =\n            child instanceof ValidationField ? child.value : child;\n        return new ValidationField(`${this.value}.${childValue}`);\n    }\n\n    public toString(): string {\n        return this.value;\n    }\n\n    // Serialize to the bare field path, so JSON.stringify of a violation yields\n    // \"email\" rather than { \"value\": \"email\" }. Mirrors ValidationCode.\n    public toJSON(): string {\n        return this.value;\n    }\n\n    public equals(other: ValidationField): boolean {\n        return this.value === other.value;\n    }\n}\n\nexport { ValidationField };\n"],"mappings":";AAIA,IAAM,kBAAN,MAAM,gBAAgB;CAGlB,YAAoB,OAAe;EAC/B,KAAK,QAAQ;CACjB;CAGA,OAAc,GAAG,OAAgC;EAC7C,OAAO,IAAI,gBAAgB,KAAK;CACpC;CAOA,OAAc,OAAkD;EAC5D,MAAM,aACF,iBAAiB,kBAAkB,MAAM,QAAQ;EACrD,OAAO,IAAI,gBAAgB,GAAG,KAAK,MAAM,GAAG,YAAY;CAC5D;CAEA,WAA0B;EACtB,OAAO,KAAK;CAChB;CAIA,SAAwB;EACpB,OAAO,KAAK;CAChB;CAEA,OAAc,OAAiC;EAC3C,OAAO,KAAK,UAAU,MAAM;CAChC;AACJ"}

package/dist/value-object-ruleset.contracts.d.cts

@@ -23,7 +23,17 @@ declare class RulesetRegistry implements RulesetRegistry$1 {
   private _sealed;
   register(ruleset: Ruleset): void;
   seal(): void;
+  /**
+   * Looks up a ruleset by exact id. The `T` parameter is a caller-asserted
+   * cast, not a runtime check: asking for the wrong `T` compiles and returns
+   * the object mistyped — the standard registry trade-off. Keep the id and
+   * the expected type paired at the call site.
+   */
   get<T extends Ruleset>(id: string): T;
+  /**
+   * Returns the highest `major.minor` version registered under `prefix`.
+   * The same caller-asserted `T` cast as {@link get} applies.
+   */
   getCurrent<T extends Ruleset>(prefix: string): T;
 }
 //#endregion

package/dist/value-object-ruleset.contracts.d.ts

@@ -23,7 +23,17 @@ declare class RulesetRegistry implements RulesetRegistry$1 {
   private _sealed;
   register(ruleset: Ruleset): void;
   seal(): void;
+  /**
+   * Looks up a ruleset by exact id. The `T` parameter is a caller-asserted
+   * cast, not a runtime check: asking for the wrong `T` compiles and returns
+   * the object mistyped — the standard registry trade-off. Keep the id and
+   * the expected type paired at the call site.
+   */
   get<T extends Ruleset>(id: string): T;
+  /**
+   * Returns the highest `major.minor` version registered under `prefix`.
+   * The same caller-asserted `T` cast as {@link get} applies.
+   */
   getCurrent<T extends Ruleset>(prefix: string): T;
 }
 //#endregion

package/dist/value-object.cjs

@@ -1,4 +1,6 @@
+const require_stable_stringify = require("./stable-stringify.cjs");
 const require_immutable = require("./immutable.cjs");
+const require_decorate = require("./decorate.cjs");
 const require_plugin = require("./plugin.cjs");
 //#region src/core/domain/value-object.ts
 var _ValueObject;
@@ -14,6 +16,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 +45,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,14 +74,25 @@ 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.
+	*
+	* The fallback also requires both sides to be the same concrete class, so
+	* an `OrderId` never equals a `CustomerId` that wraps the same string —
+	* `other: this` only guards at compile time, and a cast would otherwise
+	* slip through. And because the fallback serializes via `stableStringify`,
+	* it inherits `JSON.stringify` semantics: `undefined` properties are
+	* dropped (`{a: 1, b: undefined}` equals `{a: 1}`) and `Map`/`Set` collapse
+	* to `{}` — see the caveats in `shared/stable-stringify.ts`. Override
+	* `equals` when the wrapped value relies on such shapes.
 	*/
 	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) => a.constructor === b.constructor && require_stable_stringify.stableStringify(a.value) === require_stable_stringify.stableStringify(b.value) });
 	}
 };
-ValueObject = _ValueObject = require_immutable.__decorate([require_immutable.version("1.0")], ValueObject);
+ValueObject = _ValueObject = require_decorate.__decorate([require_immutable.version("1.0")], ValueObject);
 //#endregion
 Object.defineProperty(exports, "ValueObject", {
 	enumerable: true,

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     * \"Globally\" is literal: this static registry is process-wide and shared\n     * by **every** `ValueObject` subclass, including the value objects the kit\n     * itself ships (RBAC's `Permission`, `Scope`, …). A registered plugin\n     * therefore redefines equality for those too — it must honour generic\n     * value-object semantics, not the quirks of one host type. For a\n     * type-specific comparison, override `equals` on that subclass instead.\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     * The fallback also requires both sides to be the same concrete class, so\n     * an `OrderId` never equals a `CustomerId` that wraps the same string —\n     * `other: this` only guards at compile time, and a cast would otherwise\n     * slip through. And because the fallback serializes via `stableStringify`,\n     * it inherits `JSON.stringify` semantics: `undefined` properties are\n     * dropped (`{a: 1, b: undefined}` equals `{a: 1}`) and `Map`/`Set` collapse\n     * to `{}` — see the caveats in `shared/stable-stringify.ts`. Override\n     * `equals` when the wrapped value relies on such shapes.\n     */\n    public equals(other: this): boolean {\n        return ValueObject.plugins.invoke(\"equals\", [this, other], {\n            fallback: (a, b) =>\n                a.constructor === b.constructor &&\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;;;;;iBAiBzB,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;;;;;;;;;;;;;;;;;;;;;CAsBA,OAAc,OAAsB;EAChC,OAAA,aAAmB,QAAQ,OAAO,UAAU,CAAC,MAAM,KAAK,GAAG,EACvD,WAAW,GAAG,MACV,EAAE,gBAAgB,EAAE,eACpBC,yBAAAA,gBAAgB,EAAE,KAAK,MAAMA,yBAAAA,gBAAgB,EAAE,KAAK,EAC5D,CAAC;CACL;AAOJ;0DAhGCC,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}.
  */
@@ -36,6 +42,13 @@ declare abstract class ValueObject<T, P> {
    * default — when nothing is registered, {@link equals} falls back to a
    * structural comparison of the wrapped `value`. Hosts register a plugin
    * (e.g. `lodash.isEqual`) once at startup to customise equality globally.
+   *
+   * "Globally" is literal: this static registry is process-wide and shared
+   * by **every** `ValueObject` subclass, including the value objects the kit
+   * itself ships (RBAC's `Permission`, `Scope`, …). A registered plugin
+   * therefore redefines equality for those too — it must honour generic
+   * value-object semantics, not the quirks of one host type. For a
+   * type-specific comparison, override `equals` on that subclass instead.
    */
   static readonly plugins: PluginManager<ValueObjectPluginContract>;
   /** The wrapped data, deep-frozen so it can never be mutated after construction. */
@@ -74,8 +87,19 @@ 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.
+   *
+   * The fallback also requires both sides to be the same concrete class, so
+   * an `OrderId` never equals a `CustomerId` that wraps the same string —
+   * `other: this` only guards at compile time, and a cast would otherwise
+   * slip through. And because the fallback serializes via `stableStringify`,
+   * it inherits `JSON.stringify` semantics: `undefined` properties are
+   * dropped (`{a: 1, b: undefined}` equals `{a: 1}`) and `Map`/`Set` collapse
+   * to `{}` — see the caveats in `shared/stable-stringify.ts`. Override
+   * `equals` when the wrapped value relies on such shapes.
    */
   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}.
  */
@@ -36,6 +42,13 @@ declare abstract class ValueObject<T, P> {
    * default — when nothing is registered, {@link equals} falls back to a
    * structural comparison of the wrapped `value`. Hosts register a plugin
    * (e.g. `lodash.isEqual`) once at startup to customise equality globally.
+   *
+   * "Globally" is literal: this static registry is process-wide and shared
+   * by **every** `ValueObject` subclass, including the value objects the kit
+   * itself ships (RBAC's `Permission`, `Scope`, …). A registered plugin
+   * therefore redefines equality for those too — it must honour generic
+   * value-object semantics, not the quirks of one host type. For a
+   * type-specific comparison, override `equals` on that subclass instead.
    */
   static readonly plugins: PluginManager<ValueObjectPluginContract>;
   /** The wrapped data, deep-frozen so it can never be mutated after construction. */
@@ -74,8 +87,19 @@ 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.
+   *
+   * The fallback also requires both sides to be the same concrete class, so
+   * an `OrderId` never equals a `CustomerId` that wraps the same string —
+   * `other: this` only guards at compile time, and a cast would otherwise
+   * slip through. And because the fallback serializes via `stableStringify`,
+   * it inherits `JSON.stringify` semantics: `undefined` properties are
+   * dropped (`{a: 1, b: undefined}` equals `{a: 1}`) and `Map`/`Set` collapse
+   * to `{}` — see the caveats in `shared/stable-stringify.ts`. Override
+   * `equals` when the wrapped value relies on such shapes.
    */
   equals(other: this): boolean;
   /**

package/dist/value-object.js

@@ -1,4 +1,6 @@
-import { i as version, n as __decorate, t as makeImmutable } from "./immutable.js";
+import { n as stableStringify } from "./stable-stringify.js";
+import { i as version, n as makeImmutable } from "./immutable.js";
+import { t as __decorate } from "./decorate.js";
 import { t as PluginManager } from "./plugin.js";
 //#region src/core/domain/value-object.ts
 var _ValueObject;
@@ -14,6 +16,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 +45,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 +74,22 @@ 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.
+	*
+	* The fallback also requires both sides to be the same concrete class, so
+	* an `OrderId` never equals a `CustomerId` that wraps the same string —
+	* `other: this` only guards at compile time, and a cast would otherwise
+	* slip through. And because the fallback serializes via `stableStringify`,
+	* it inherits `JSON.stringify` semantics: `undefined` properties are
+	* dropped (`{a: 1, b: undefined}` equals `{a: 1}`) and `Map`/`Set` collapse
+	* to `{}` — see the caveats in `shared/stable-stringify.ts`. Override
+	* `equals` when the wrapped value relies on such shapes.
 	*/
 	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) => a.constructor === b.constructor && 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     * \"Globally\" is literal: this static registry is process-wide and shared\n     * by **every** `ValueObject` subclass, including the value objects the kit\n     * itself ships (RBAC's `Permission`, `Scope`, …). A registered plugin\n     * therefore redefines equality for those too — it must honour generic\n     * value-object semantics, not the quirks of one host type. For a\n     * type-specific comparison, override `equals` on that subclass instead.\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     * The fallback also requires both sides to be the same concrete class, so\n     * an `OrderId` never equals a `CustomerId` that wraps the same string —\n     * `other: this` only guards at compile time, and a cast would otherwise\n     * slip through. And because the fallback serializes via `stableStringify`,\n     * it inherits `JSON.stringify` semantics: `undefined` properties are\n     * dropped (`{a: 1, b: undefined}` equals `{a: 1}`) and `Map`/`Set` collapse\n     * to `{}` — see the caveats in `shared/stable-stringify.ts`. Override\n     * `equals` when the wrapped value relies on such shapes.\n     */\n    public equals(other: this): boolean {\n        return ValueObject.plugins.invoke(\"equals\", [this, other], {\n            fallback: (a, b) =>\n                a.constructor === b.constructor &&\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;;;;;iBAiBzB,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;;;;;;;;;;;;;;;;;;;;;CAsBA,OAAc,OAAsB;EAChC,OAAA,aAAmB,QAAQ,OAAO,UAAU,CAAC,MAAM,KAAK,GAAG,EACvD,WAAW,GAAG,MACV,EAAE,gBAAgB,EAAE,eACpB,gBAAgB,EAAE,KAAK,MAAM,gBAAgB,EAAE,KAAK,EAC5D,CAAC;CACL;AAOJ;yCAhGC,QAAQ,KAAK,CAAA,GAAA,WAAA"}

package/dist/version.d.cts

@@ -1,9 +1,36 @@
 //#region src/core/versioning/version.d.ts
+/**
+ * A structural contract version in `MAJOR.MINOR` form (e.g. `"1.0"`, `"2.5"`).
+ *
+ * The template-literal type is intentionally loose — it also accepts strings
+ * the module rejects at runtime (e.g. `"1.0.0"` matches as `1` · `.` · `0.0`).
+ * The runtime regex in {@link version} is the real guard; the type is only a
+ * light hint.
+ */
 type ContractVersion = `${number}.${number}`;
+/** Anything a class decorator can stamp a static property onto. */
 type VersionedTarget = {
   readonly prototype: object;
 };
 declare const CONTRACT_VERSION_PROPERTY: "CONTRACT_VERSION";
+/**
+ * Class decorator that stamps a `MAJOR.MINOR` structural contract version onto
+ * the class as a static `CONTRACT_VERSION` property.
+ *
+ * The property is defined **non-writable, non-configurable and non-enumerable**
+ * on purpose: it must not be reassigned or redefined (tampering with a contract
+ * version silently corrupts migration decisions), and keeping it off enumeration
+ * excludes it from `JSON.stringify`/`for..in`. A consequence of
+ * `configurable: false` is that decorating the same class twice throws
+ * `TypeError: Cannot redefine property` — a deliberate fail-fast.
+ *
+ * Note on inheritance: a subclass that is not re-decorated inherits its base's
+ * `CONTRACT_VERSION` through the static prototype chain. Re-decorate any
+ * subclass whose persisted shape diverges from its base.
+ *
+ * @throws {InvariantViolationException} When `contractVersion` is not
+ *   `MAJOR.MINOR` (validated at module-load time, when the decorator runs).
+ */
 declare function version<const TVersion extends ContractVersion>(contractVersion: TVersion): (target: VersionedTarget) => void;
 //#endregion
 export { version as i, ContractVersion as n, VersionedTarget as r, CONTRACT_VERSION_PROPERTY as t };