@cullet/erp-core 1.1.0 → 1.2.0

package/dist/validation-code.js

@@ -1,179 +1,3 @@
-//#region src/core/errors/error-codes.ts
-const ErrorCodes = {
-	authentication: {
-		missingToken: "sec.authn.missing_token",
-		invalidToken: "sec.authn.invalid_token",
-		expiredToken: "sec.authn.expired_token",
-		invalidCredentials: "sec.authn.invalid_credentials"
-	},
-	authorization: {
-		forbidden: "sec.authz.forbidden",
-		policyDenied: "sec.authz.policy_denied",
-		missingCapability: "sec.authz.missing_capability",
-		outOfScope: "sec.authz.out_of_scope"
-	},
-	businessRuleViolation: "business_rule_violation",
-	conflict: {
-		alreadyExists: "conf.already_exists",
-		duplicate: "conf.duplicate",
-		uniqueViolation: "conf.unique_violation"
-	},
-	idempotency: {
-		keyMissing: "idemp.key_missing",
-		inProgress: "idemp.in_progress",
-		payloadMismatch: "idemp.payload_mismatch",
-		replayNotSupported: "idemp.replay_not_supported"
-	},
-	integration: {
-		timeout: "int.timeout",
-		unreachable: "int.unreachable",
-		badResponse: "int.bad_response"
-	},
-	legacyIncompatible: "legacy_incompatible",
-	notFound: "not_found",
-	serialization: {
-		deserializePrefix: "ser.des",
-		serializePrefix: "ser.ser"
-	},
-	temporal: {
-		expired: "tmp.expired",
-		notYetValid: "tmp.not_yet_valid"
-	},
-	unexpected: "unexpected",
-	validation: "validation_error"
-};
-function serializationErrorCode(direction, category) {
-	return `${direction === "deserialize" ? ErrorCodes.serialization.deserializePrefix : ErrorCodes.serialization.serializePrefix}.${category}`;
-}
-//#endregion
-//#region src/core/errors/utils/json-safe.ts
-const NON_SERIALIZABLE_PLACEHOLDER = "[NonSerializable]";
-const CIRCULAR_REFERENCE_PLACEHOLDER = "[Circular]";
-function isPlainObject(value) {
-	if (value === null || typeof value !== "object") return false;
-	const proto = Object.getPrototypeOf(value);
-	return proto === Object.prototype || proto === null;
-}
-function sanitizeValue(value, seen) {
-	if (value === null) return null;
-	const type = typeof value;
-	if (type === "string" || type === "number" || type === "boolean") return value;
-	if (type === "bigint" || type === "function" || type === "symbol" || value === void 0) return NON_SERIALIZABLE_PLACEHOLDER;
-	if (Array.isArray(value)) {
-		if (seen.has(value)) return CIRCULAR_REFERENCE_PLACEHOLDER;
-		seen.add(value);
-		const sanitized = value.map((item) => sanitizeValue(item, seen));
-		seen.delete(value);
-		return sanitized;
-	}
-	if (value instanceof Date) return NON_SERIALIZABLE_PLACEHOLDER;
-	if (!isPlainObject(value)) return NON_SERIALIZABLE_PLACEHOLDER;
-	if (seen.has(value)) return CIRCULAR_REFERENCE_PLACEHOLDER;
-	seen.add(value);
-	const result = {};
-	for (const [key, val] of Object.entries(value)) result[key] = sanitizeValue(val, seen);
-	seen.delete(value);
-	return result;
-}
-/**
-* Ensures metadata is JSON-serializable.
-*
-* **Allowed:** string, number, boolean, null, arrays, and plain objects.
-*
-* **Converted to placeholder:** Date, BigInt, class instances, functions,
-* symbols, undefined, and circular references (which would otherwise make
-* `JSON.stringify` throw).
-*
-* @throws {TypeError} If `input` is not a plain object at the root level.
-*/
-function assertJsonSafeMetadata(input) {
-	if (input === void 0) return {};
-	if (!isPlainObject(input)) throw new TypeError("metadata must be a plain object (Record<string, unknown>).");
-	return sanitizeValue(input, /* @__PURE__ */ new WeakSet());
-}
-//#endregion
-//#region src/core/errors/app-error.ts
-/**
-* Root of the application/domain error hierarchy. Every error the system raises
-* on purpose extends `AppError`, which gives callers a single `instanceof` to
-* catch and a uniform, serializable shape to log and transport.
-*
-* Beyond the native `Error` message it carries a stable `code` (the contract the
-* outside world matches on), an optional non-leaking `publicMessage`, a
-* severity, JSON-safe `metadata`, and the correlation/request/command ids that
-* stitch an error back to the request that produced it. The metadata is
-* validated as JSON-safe on construction, so a logger can serialize any
-* `AppError` without hitting a circular reference or a non-serializable value.
-*
-* Abstract on purpose: callers should throw a specific subclass (e.g.
-* {@link ValidationError}, {@link NotFoundError}) so the `code` and shape are
-* meaningful, never a bare `AppError`.
-*/
-var AppError = class extends Error {
-	/**
-	* Builds the common error envelope shared by every subclass.
-	*
-	* `name` is taken from `new.target` so the thrown instance reports its
-	* concrete subclass name (not `"AppError"`), and the prototype is re-pinned
-	* via `setPrototypeOf` so `instanceof` keeps working after transpilation to
-	* older targets where extending built-ins breaks the chain. `createdAtIso`
-	* defaults to now, and `metadata` is validated as JSON-safe so the error is
-	* always serializable.
-	*
-	* Declared `protected`: instantiate a concrete subclass, never `AppError`.
-	*
-	* @param message - The internal, developer-facing message.
-	* @param code - The stable machine-readable code callers match on.
-	* @param options - Optional cause, metadata, severity, and correlation ids.
-	* @throws When `options.metadata` contains a value that is not JSON-safe.
-	*/
-	constructor(message, code, options) {
-		super(message);
-		this.name = new.target.name;
-		this.code = code;
-		this.cause = options?.cause;
-		this.type = options?.type;
-		this.severity = options?.severity;
-		this.correlationId = options?.correlationId;
-		this.requestId = options?.requestId;
-		this.commandId = options?.commandId;
-		this.createdAtIso = options?.createdAtIso ?? (/* @__PURE__ */ new Date()).toISOString();
-		this.publicMessage = options?.publicMessage;
-		this.metadata = options?.metadata ? assertJsonSafeMetadata(options.metadata) : void 0;
-		Object.setPrototypeOf(this, new.target.prototype);
-	}
-	/**
-	* Returns a JSON-safe representation of the error.
-	* Does NOT include `cause` by default (to avoid leaking internal details).
-	*/
-	toJSON() {
-		const payload = {
-			name: this.name,
-			code: this.code,
-			message: this.message,
-			createdAtIso: this.createdAtIso
-		};
-		if (this.type !== void 0) payload.type = this.type;
-		if (this.severity !== void 0) payload.severity = this.severity;
-		if (this.publicMessage !== void 0) payload.publicMessage = this.publicMessage;
-		if (this.metadata !== void 0) payload.metadata = this.metadata;
-		if (this.correlationId !== void 0) payload.correlationId = this.correlationId;
-		if (this.requestId !== void 0) payload.requestId = this.requestId;
-		if (this.commandId !== void 0) payload.commandId = this.commandId;
-		return payload;
-	}
-};
-//#endregion
-//#region src/core/errors/unexpected-error.ts
-var UnexpectedError = class extends AppError {
-	constructor(message = "Unexpected error", cause, options) {
-		super(message, ErrorCodes.unexpected, {
-			cause,
-			...options
-		});
-	}
-};
-//#endregion
 //#region src/core/exceptions/validation-code.ts
 var ValidationCode = class ValidationCode {
 	constructor(value) {
@@ -226,6 +50,6 @@ var ValidationCode = class ValidationCode {
 	}
 };
 //#endregion
-export { ErrorCodes as a, assertJsonSafeMetadata as i, UnexpectedError as n, serializationErrorCode as o, AppError as r, ValidationCode as t };
+export { ValidationCode as t };
 
 //# sourceMappingURL=validation-code.js.map

package/dist/validation-code.js.map

@@ -1 +1 @@
-{"version":3,"file":"validation-code.js","names":[],"sources":["../src/core/errors/error-codes.ts","../src/core/errors/utils/json-safe.ts","../src/core/errors/app-error.ts","../src/core/errors/unexpected-error.ts","../src/core/exceptions/validation-code.ts"],"sourcesContent":["const ErrorCodes = {\n    authentication: {\n        missingToken: \"sec.authn.missing_token\",\n        invalidToken: \"sec.authn.invalid_token\",\n        expiredToken: \"sec.authn.expired_token\",\n        invalidCredentials: \"sec.authn.invalid_credentials\",\n    },\n    authorization: {\n        forbidden: \"sec.authz.forbidden\",\n        policyDenied: \"sec.authz.policy_denied\",\n        missingCapability: \"sec.authz.missing_capability\",\n        outOfScope: \"sec.authz.out_of_scope\",\n    },\n    businessRuleViolation: \"business_rule_violation\",\n    conflict: {\n        alreadyExists: \"conf.already_exists\",\n        duplicate: \"conf.duplicate\",\n        uniqueViolation: \"conf.unique_violation\",\n    },\n    idempotency: {\n        keyMissing: \"idemp.key_missing\",\n        inProgress: \"idemp.in_progress\",\n        payloadMismatch: \"idemp.payload_mismatch\",\n        replayNotSupported: \"idemp.replay_not_supported\",\n    },\n    integration: {\n        timeout: \"int.timeout\",\n        unreachable: \"int.unreachable\",\n        badResponse: \"int.bad_response\",\n    },\n    legacyIncompatible: \"legacy_incompatible\",\n    notFound: \"not_found\",\n    serialization: {\n        deserializePrefix: \"ser.des\",\n        serializePrefix: \"ser.ser\",\n    },\n    temporal: {\n        expired: \"tmp.expired\",\n        notYetValid: \"tmp.not_yet_valid\",\n    },\n    unexpected: \"unexpected\",\n    validation: \"validation_error\",\n} as const;\n\ntype SerializationCodeDirection = \"deserialize\" | \"serialize\";\n\nfunction serializationErrorCode(\n    direction: SerializationCodeDirection,\n    category: string,\n): string {\n    const prefix =\n        direction === \"deserialize\"\n            ? ErrorCodes.serialization.deserializePrefix\n            : ErrorCodes.serialization.serializePrefix;\n\n    return `${prefix}.${category}`;\n}\n\nexport { ErrorCodes, serializationErrorCode };\nexport type { SerializationCodeDirection };\n","// Utilities for ensuring metadata is JSON-serializable.\n\nimport type { JsonSafeRecord, JsonSafeValue } from \"../types.js\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Constants\n// ─────────────────────────────────────────────────────────────────────────────\n\nconst NON_SERIALIZABLE_PLACEHOLDER = \"[NonSerializable]\";\nconst CIRCULAR_REFERENCE_PLACEHOLDER = \"[Circular]\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Internal helpers\n// ─────────────────────────────────────────────────────────────────────────────\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n    if (value === null || typeof value !== \"object\") return false;\n    const proto = Object.getPrototypeOf(value);\n    return proto === Object.prototype || proto === null;\n}\n\n// `seen` tracks the ancestors on the current traversal branch (a DFS path), not\n// every object visited. This collapses true circular references to a placeholder\n// while still serializing the same object referenced more than once across\n// sibling branches (a DAG) — matching `JSON.stringify`, which only rejects\n// cycles, not shared references.\nfunction sanitizeValue(value: unknown, seen: WeakSet<object>): JsonSafeValue {\n    // Null passthrough\n    if (value === null) return null;\n\n    const type = typeof value;\n\n    // Primitives\n    if (type === \"string\" || type === \"number\" || type === \"boolean\") {\n        return value as JsonSafeValue;\n    }\n\n    // Non-serializable primitives\n    if (\n        type === \"bigint\" ||\n        type === \"function\" ||\n        type === \"symbol\" ||\n        value === undefined\n    ) {\n        return NON_SERIALIZABLE_PLACEHOLDER;\n    }\n\n    // Arrays (recursive)\n    if (Array.isArray(value)) {\n        if (seen.has(value)) return CIRCULAR_REFERENCE_PLACEHOLDER;\n        seen.add(value);\n        const sanitized = value.map((item) => sanitizeValue(item, seen));\n        seen.delete(value);\n        return sanitized;\n    }\n\n    // Date → placeholder (could also use .toISOString() if preferred)\n    if (value instanceof Date) {\n        return NON_SERIALIZABLE_PLACEHOLDER;\n    }\n\n    // Class instances and non-plain objects → placeholder\n    if (!isPlainObject(value)) {\n        return NON_SERIALIZABLE_PLACEHOLDER;\n    }\n\n    // Plain object (recursive)\n    if (seen.has(value)) return CIRCULAR_REFERENCE_PLACEHOLDER;\n    seen.add(value);\n    const result: Record<string, JsonSafeValue> = {};\n    for (const [key, val] of Object.entries(value)) {\n        result[key] = sanitizeValue(val, seen);\n    }\n    seen.delete(value);\n    return result;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Public API\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Ensures metadata is JSON-serializable.\n *\n * **Allowed:** string, number, boolean, null, arrays, and plain objects.\n *\n * **Converted to placeholder:** Date, BigInt, class instances, functions,\n * symbols, undefined, and circular references (which would otherwise make\n * `JSON.stringify` throw).\n *\n * @throws {TypeError} If `input` is not a plain object at the root level.\n */\nfunction assertJsonSafeMetadata(input: unknown): JsonSafeRecord {\n    if (input === undefined) {\n        return {};\n    }\n\n    if (!isPlainObject(input)) {\n        throw new TypeError(\n            \"metadata must be a plain object (Record<string, unknown>).\",\n        );\n    }\n\n    return sanitizeValue(input, new WeakSet<object>()) as JsonSafeRecord;\n}\n\nexport {\n    assertJsonSafeMetadata,\n    CIRCULAR_REFERENCE_PLACEHOLDER,\n    NON_SERIALIZABLE_PLACEHOLDER,\n};\n","// Base application error for the domain/application layer.\n// Encapsulates a code, optional cause, and JSON-safe metadata.\n\nimport type {\n    AppErrorOptions,\n    ErrorSeverity,\n    JsonSafeRecord,\n} from \"./types.js\";\nimport { assertJsonSafeMetadata } from \"./utils/index.js\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// AppError (abstract base class)\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Root of the application/domain error hierarchy. Every error the system raises\n * on purpose extends `AppError`, which gives callers a single `instanceof` to\n * catch and a uniform, serializable shape to log and transport.\n *\n * Beyond the native `Error` message it carries a stable `code` (the contract the\n * outside world matches on), an optional non-leaking `publicMessage`, a\n * severity, JSON-safe `metadata`, and the correlation/request/command ids that\n * stitch an error back to the request that produced it. The metadata is\n * validated as JSON-safe on construction, so a logger can serialize any\n * `AppError` without hitting a circular reference or a non-serializable value.\n *\n * Abstract on purpose: callers should throw a specific subclass (e.g.\n * {@link ValidationError}, {@link NotFoundError}) so the `code` and shape are\n * meaningful, never a bare `AppError`.\n */\nabstract class AppError extends Error {\n    public readonly code: string;\n    public readonly cause?: unknown;\n    public readonly metadata?: JsonSafeRecord;\n    public readonly type?: string;\n    public readonly severity?: ErrorSeverity;\n    public readonly createdAtIso: string;\n    public readonly publicMessage?: string;\n    /**\n     * Identifies a single execution \"story\" in the system. All operations\n     * related to the same logical flow must share the same correlationId.\n     */\n    public readonly correlationId?: string;\n    /**\n     * Identifies a specific technical request attempt (each retry may produce\n     * a new requestId), even when the correlationId stays the same.\n     */\n    public readonly requestId?: string;\n    /**\n     * Marks the business intent / idempotency key; stays the same across\n     * technical retries and multiple requests that represent the same intent.\n     */\n    public readonly commandId?: string;\n\n    /**\n     * Builds the common error envelope shared by every subclass.\n     *\n     * `name` is taken from `new.target` so the thrown instance reports its\n     * concrete subclass name (not `\"AppError\"`), and the prototype is re-pinned\n     * via `setPrototypeOf` so `instanceof` keeps working after transpilation to\n     * older targets where extending built-ins breaks the chain. `createdAtIso`\n     * defaults to now, and `metadata` is validated as JSON-safe so the error is\n     * always serializable.\n     *\n     * Declared `protected`: instantiate a concrete subclass, never `AppError`.\n     *\n     * @param message - The internal, developer-facing message.\n     * @param code - The stable machine-readable code callers match on.\n     * @param options - Optional cause, metadata, severity, and correlation ids.\n     * @throws When `options.metadata` contains a value that is not JSON-safe.\n     */\n    protected constructor(\n        message: string,\n        code: string,\n        options?: AppErrorOptions,\n    ) {\n        super(message);\n\n        this.name = new.target.name;\n        this.code = code;\n        this.cause = options?.cause;\n        this.type = options?.type;\n        this.severity = options?.severity;\n        this.correlationId = options?.correlationId;\n        this.requestId = options?.requestId;\n        this.commandId = options?.commandId;\n        this.createdAtIso = options?.createdAtIso ?? new Date().toISOString();\n        this.publicMessage = options?.publicMessage;\n\n        this.metadata = options?.metadata\n            ? assertJsonSafeMetadata(options.metadata)\n            : undefined;\n\n        Object.setPrototypeOf(this, new.target.prototype);\n    }\n\n    /**\n     * Returns a JSON-safe representation of the error.\n     * Does NOT include `cause` by default (to avoid leaking internal details).\n     */\n    public toJSON(): Record<string, unknown> {\n        const payload: Record<string, unknown> = {\n            name: this.name,\n            code: this.code,\n            message: this.message,\n            createdAtIso: this.createdAtIso,\n        };\n\n        // Optional fields are emitted only when defined, so the serialized\n        // shape never carries `undefined`-valued keys (consistent with how the\n        // correlation/request/command ids are handled).\n        if (this.type !== undefined) payload.type = this.type;\n        if (this.severity !== undefined) payload.severity = this.severity;\n        if (this.publicMessage !== undefined)\n            payload.publicMessage = this.publicMessage;\n        if (this.metadata !== undefined) payload.metadata = this.metadata;\n        if (this.correlationId !== undefined)\n            payload.correlationId = this.correlationId;\n        if (this.requestId !== undefined) payload.requestId = this.requestId;\n        if (this.commandId !== undefined) payload.commandId = this.commandId;\n\n        return payload;\n    }\n}\n\nexport { AppError };\n","import { AppError } from \"./app-error.js\";\nimport { ErrorCodes } from \"./error-codes.js\";\nimport type { AppErrorOptions } from \"./types.js\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// UnexpectedError\n// ─────────────────────────────────────────────────────────────────────────────\n\nclass UnexpectedError extends AppError {\n    constructor(\n        message = \"Unexpected error\",\n        cause?: unknown,\n        options?: Omit<AppErrorOptions, \"cause\">,\n    ) {\n        super(message, ErrorCodes.unexpected, {\n            cause,\n            ...options,\n        });\n    }\n}\n\nexport { UnexpectedError };\n","// Object-oriented representation of validation codes (similar to Kotlin inline class).\n// Provides common reusable codes while allowing custom codes via `of`.\n\nclass ValidationCode {\n    public readonly value: string;\n\n    private constructor(value: string) {\n        this.value = value;\n    }\n\n    // Factory for custom codes\n    public static of(value: string): ValidationCode {\n        return new ValidationCode(value);\n    }\n\n    // Common, domain-friendly codes\n    public static readonly BLANK = new ValidationCode(\"blank\");\n    public static readonly REQUIRED = new ValidationCode(\"required\");\n    public static readonly INVALID_FORMAT = new ValidationCode(\n        \"invalid_format\",\n    );\n    public static readonly INVALID_CHARACTERS = new ValidationCode(\n        \"invalid_characters\",\n    );\n    public static readonly INVALID_LENGTH = new ValidationCode(\n        \"invalid_length\",\n    );\n    public static readonly TOO_SHORT = new ValidationCode(\"too_short\");\n    public static readonly TOO_LONG = new ValidationCode(\"too_long\");\n    public static readonly OUT_OF_RANGE = new ValidationCode(\"out_of_range\");\n    public static readonly INVALID_CHECKSUM = new ValidationCode(\n        \"invalid_checksum\",\n    );\n    public static readonly INVALID_CHECKING_DIGIT = new ValidationCode(\n        \"invalid_checking_digit\",\n    );\n    public static readonly ALREADY_EXISTS = new ValidationCode(\n        \"already_exists\",\n    );\n    public static readonly NOT_FOUND = new ValidationCode(\"not_found\");\n    public static readonly NOT_ALLOWED = new ValidationCode(\"not_allowed\");\n    public static readonly UNEXPECTED = new ValidationCode(\"unexpected\");\n}\n\nexport { ValidationCode };\n"],"mappings":"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"}
+{"version":3,"file":"validation-code.js","names":[],"sources":["../src/core/exceptions/validation-code.ts"],"sourcesContent":["// Object-oriented representation of validation codes (similar to Kotlin inline class).\n// Provides common reusable codes while allowing custom codes via `of`.\n\nclass ValidationCode {\n    public readonly value: string;\n\n    private constructor(value: string) {\n        this.value = value;\n    }\n\n    // Factory for custom codes\n    public static of(value: string): ValidationCode {\n        return new ValidationCode(value);\n    }\n\n    // Common, domain-friendly codes\n    public static readonly BLANK = new ValidationCode(\"blank\");\n    public static readonly REQUIRED = new ValidationCode(\"required\");\n    public static readonly INVALID_FORMAT = new ValidationCode(\n        \"invalid_format\",\n    );\n    public static readonly INVALID_CHARACTERS = new ValidationCode(\n        \"invalid_characters\",\n    );\n    public static readonly INVALID_LENGTH = new ValidationCode(\n        \"invalid_length\",\n    );\n    public static readonly TOO_SHORT = new ValidationCode(\"too_short\");\n    public static readonly TOO_LONG = new ValidationCode(\"too_long\");\n    public static readonly OUT_OF_RANGE = new ValidationCode(\"out_of_range\");\n    public static readonly INVALID_CHECKSUM = new ValidationCode(\n        \"invalid_checksum\",\n    );\n    public static readonly INVALID_CHECKING_DIGIT = new ValidationCode(\n        \"invalid_checking_digit\",\n    );\n    public static readonly ALREADY_EXISTS = new ValidationCode(\n        \"already_exists\",\n    );\n    public static readonly NOT_FOUND = new ValidationCode(\"not_found\");\n    public static readonly NOT_ALLOWED = new ValidationCode(\"not_allowed\");\n    public static readonly UNEXPECTED = new ValidationCode(\"unexpected\");\n}\n\nexport { ValidationCode };\n"],"mappings":";AAGA,IAAM,iBAAN,MAAM,eAAe;CAGjB,YAAoB,OAAe;EAC/B,KAAK,QAAQ;CACjB;CAGA,OAAc,GAAG,OAA+B;EAC5C,OAAO,IAAI,eAAe,KAAK;CACnC;;eAG+B,IAAI,eAAe,OAAO;;;kBACvB,IAAI,eAAe,UAAU;;;wBACvB,IAAI,eACxC,gBACJ;;;4BAC4C,IAAI,eAC5C,oBACJ;;;wBACwC,IAAI,eACxC,gBACJ;;;mBACmC,IAAI,eAAe,WAAW;;;kBAC/B,IAAI,eAAe,UAAU;;;sBACzB,IAAI,eAAe,cAAc;;;0BAC7B,IAAI,eAC1C,kBACJ;;;gCACgD,IAAI,eAChD,wBACJ;;;wBACwC,IAAI,eACxC,gBACJ;;;mBACmC,IAAI,eAAe,WAAW;;;qBAC5B,IAAI,eAAe,aAAa;;;oBACjC,IAAI,eAAe,YAAY;;AACvE"}

package/dist/validation-error.d.ts

@@ -1,4 +1,5 @@
 import { a as JsonSafeRecord, n as AppErrorOptions, r as ErrorSeverity, t as AppError } from "./app-error.js";
+import { t as ValidationCode } from "./validation-code.js";
 import { t as ValidationField } from "./validation-field.js";
 
 //#region src/core/errors/error-codes.d.ts
@@ -749,27 +750,6 @@ declare class UnexpectedError extends AppError {
   constructor(message?: string, cause?: unknown, options?: Omit<AppErrorOptions, "cause">);
 }
 //#endregion
-//#region src/core/exceptions/validation-code.d.ts
-declare class ValidationCode {
-  readonly value: string;
-  private constructor();
-  static of(value: string): ValidationCode;
-  static readonly BLANK: ValidationCode;
-  static readonly REQUIRED: ValidationCode;
-  static readonly INVALID_FORMAT: ValidationCode;
-  static readonly INVALID_CHARACTERS: ValidationCode;
-  static readonly INVALID_LENGTH: ValidationCode;
-  static readonly TOO_SHORT: ValidationCode;
-  static readonly TOO_LONG: ValidationCode;
-  static readonly OUT_OF_RANGE: ValidationCode;
-  static readonly INVALID_CHECKSUM: ValidationCode;
-  static readonly INVALID_CHECKING_DIGIT: ValidationCode;
-  static readonly ALREADY_EXISTS: ValidationCode;
-  static readonly NOT_FOUND: ValidationCode;
-  static readonly NOT_ALLOWED: ValidationCode;
-  static readonly UNEXPECTED: ValidationCode;
-}
-//#endregion
 //#region src/core/errors/validation-error.d.ts
 /**
  * Raised when a single input fails a validation rule — the canonical

package/dist/validation-error.js

@@ -1,4 +1,4 @@
-import { a as ErrorCodes, o as serializationErrorCode, r as AppError } from "./validation-code.js";
+import { a as serializationErrorCode, i as ErrorCodes, n as AppError } from "./unexpected-error.js";
 //#region src/core/errors/authentication-error.ts
 var AuthenticationError = class AuthenticationError extends AppError {
 	constructor(params) {

package/dist/validation-exception.d.ts

@@ -0,0 +1,50 @@
+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/business-rule-violation-exception.d.ts
+declare class BusinessRuleViolationException extends DomainException {
+  readonly rule: string;
+  constructor(rule: string, message: string);
+}
+//#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);
+}
+//#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);
+}
+//#endregion
+//#region src/core/exceptions/invariant-violation-exception.d.ts
+declare class InvariantViolationException extends DomainException {
+  constructor(message: string);
+}
+//#endregion
+//#region src/core/exceptions/validation-exception.d.ts
+interface ValidationViolation {
+  readonly field: ValidationField;
+  readonly code: ValidationCode;
+  readonly message: string;
+}
+declare class ValidationException extends DomainException {
+  readonly field: ValidationField;
+  readonly code: ValidationCode;
+  constructor(field: ValidationField, code: ValidationCode, message: string);
+}
+declare class MultipleValidationException extends DomainException {
+  readonly violations: readonly ValidationViolation[];
+  constructor(violations: readonly ValidationViolation[]);
+}
+declare class InvalidValueException extends ValidationException {
+  constructor(field: ValidationField, code: ValidationCode, message: string);
+}
+//#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 };
+//# sourceMappingURL=validation-exception.d.ts.map

package/dist/validation-exception.js

@@ -1,4 +1,4 @@
-import { a as DomainException } from "./temporal-guards.js";
+import { t as DomainException } from "./domain-exception.js";
 //#region src/core/exceptions/validation-exception.ts
 var ValidationException = class extends DomainException {
 	constructor(field, code, message) {
@@ -7,12 +7,18 @@ var ValidationException = class extends DomainException {
 		this.code = code;
 	}
 };
+var MultipleValidationException = class extends DomainException {
+	constructor(violations) {
+		super(violations.map((v) => v.message).join("; "));
+		this.violations = violations;
+	}
+};
 var InvalidValueException = class extends ValidationException {
 	constructor(field, code, message) {
 		super(field, code, message);
 	}
 };
 //#endregion
-export { InvalidValueException as t };
+export { MultipleValidationException as n, ValidationException as r, InvalidValueException as t };
 
 //# sourceMappingURL=validation-exception.js.map

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;AAUA,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 { 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"}

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

@@ -0,0 +1,36 @@
+//#region src/core/domain/rulesets/ruleset.contracts.d.ts
+type RulesetId = `${string}@${number}.${number}`;
+interface Ruleset {
+  readonly id: RulesetId;
+  readonly description: string;
+}
+interface RulesetRegistry$1 {
+  register(ruleset: Ruleset): void;
+  seal(): void;
+  get<T extends Ruleset>(id: string): T;
+  getCurrent<T extends Ruleset>(prefix: string): T;
+}
+//#endregion
+//#region src/core/domain/rulesets/entity-ruleset.contracts.d.ts
+interface CreationRuleset<TData> extends Ruleset {
+  validate(data: TData): void;
+}
+type InvariantRuleset = Ruleset;
+//#endregion
+//#region src/core/domain/rulesets/ruleset-registry.d.ts
+declare class RulesetRegistry implements RulesetRegistry$1 {
+  private readonly _store;
+  private _sealed;
+  register(ruleset: Ruleset): void;
+  seal(): void;
+  get<T extends Ruleset>(id: string): T;
+  getCurrent<T extends Ruleset>(prefix: string): T;
+}
+//#endregion
+//#region src/core/domain/rulesets/value-object-ruleset.contracts.d.ts
+interface ValueObjectRuleset<T> extends Ruleset {
+  validate(value: T): void;
+}
+//#endregion
+export { Ruleset as a, InvariantRuleset as i, RulesetRegistry as n, RulesetId as o, CreationRuleset as r, ValueObjectRuleset as t };
+//# sourceMappingURL=value-object-ruleset.contracts.d.ts.map

package/dist/value-object.js

@@ -0,0 +1,191 @@
+import { t as InvariantViolationException } from "./invariant-violation-exception.js";
+import { i as version, n as __decorate, t as makeImmutable } from "./immutable.js";
+import { n as cloneDate, t as assertValidDate } from "./temporal-guards.js";
+import { t as PluginManager } from "./plugin.js";
+//#region src/core/shared/aggregate-version.ts
+function assertValidAggregateVersion(aggregateVersion) {
+	if (!Number.isInteger(aggregateVersion) || aggregateVersion < 0) throw new InvariantViolationException(`aggregateVersion must be a non-negative integer. Received: ${aggregateVersion}`);
+}
+//#endregion
+//#region src/core/domain/entity.ts
+var _Entity;
+/**
+* Base class for domain entities — objects defined by a stable identity rather
+* than by their attributes. Two entities are "the same" when their `id`
+* matches, even if every other field differs; this is the opposite of a
+* {@link ValueObject}, which is defined entirely by its contents.
+*
+* The class owns the bookkeeping common to every aggregate root: a creation
+* timestamp that never changes, a last-modified timestamp, and an
+* `aggregateVersion` counter used for optimistic concurrency control. All three
+* are validated on construction and the dates are defensively cloned, so an
+* entity can never be built into — or leak — an inconsistent temporal state.
+*
+* @typeParam TIdentifier - The identity type (e.g. a branded string id or a VO).
+*/
+let Entity = class Entity {
+	static {
+		_Entity = this;
+	}
+	/**
+	* Reconstitutes an entity from its persisted {@link EntityState}.
+	*
+	* Validates the temporal invariants up front so an invalid entity is
+	* impossible to construct: both dates must be valid, the aggregate version
+	* must be a non-negative integer, and `updatedAt` may not predate
+	* `createdAt`. Both dates are cloned on the way in so a later mutation of
+	* the caller's `Date` objects cannot reach into the entity's internal state.
+	*
+	* Declared `protected` because entities are reconstituted through a
+	* subclass factory, never instantiated directly by application code.
+	*
+	* @throws {InvariantViolationException} When `updatedAt` is earlier than `createdAt`.
+	*/
+	constructor(state) {
+		assertValidDate("createdAt", state.createdAt);
+		assertValidDate("updatedAt", state.updatedAt);
+		assertValidAggregateVersion(state.aggregateVersion);
+		if (state.updatedAt.getTime() < state.createdAt.getTime()) throw new InvariantViolationException("updatedAt cannot be earlier than createdAt");
+		this._id = state.id;
+		this._createdAt = cloneDate(state.createdAt);
+		this._updatedAt = cloneDate(state.updatedAt);
+		this._aggregateVersion = state.aggregateVersion;
+	}
+	/** The entity's stable identity — the basis for equality between entities. */
+	get id() {
+		return this._id;
+	}
+	/**
+	* When the entity was first created.
+	*
+	* Returns a clone so callers cannot mutate the entity's internal `Date`;
+	* the value is fixed at construction and never changes thereafter.
+	*/
+	get createdAt() {
+		return cloneDate(this._createdAt);
+	}
+	/**
+	* When the entity was last modified.
+	*
+	* Returns a clone for the same encapsulation reason as {@link createdAt};
+	* the underlying value advances only through {@link markAsModified}.
+	*/
+	get updatedAt() {
+		return cloneDate(this._updatedAt);
+	}
+	/**
+	* Monotonic counter incremented on every mutation, used for optimistic
+	* concurrency control: a writer reads this value, and the persistence layer
+	* rejects the write if the stored version has moved on in the meantime.
+	*/
+	get aggregateVersion() {
+		return this._aggregateVersion;
+	}
+	/**
+	* The schema/contract version stamped on this entity type by the
+	* `@version` decorator — used to detect and migrate state persisted under
+	* an older shape.
+	*/
+	get contractVersion() {
+		return _Entity.CONTRACT_VERSION;
+	}
+	/**
+	* The single seam through which an entity records a mutation: it advances
+	* `updatedAt` and bumps {@link aggregateVersion} by one. Subclasses must
+	* call this from every state-changing method so the version counter stays
+	* an accurate optimistic-lock token.
+	*
+	* @param updatedAt - The modification instant; defaults to now. Validated
+	*   and required not to predate `createdAt`, preserving the same invariant
+	*   the constructor enforces.
+	* @returns The new aggregate version after the increment.
+	* @throws {InvariantViolationException} When `updatedAt` is earlier than `createdAt`.
+	*/
+	markAsModified(updatedAt = /* @__PURE__ */ new Date()) {
+		assertValidDate("updatedAt", updatedAt);
+		if (updatedAt.getTime() < this._createdAt.getTime()) throw new InvariantViolationException("updatedAt cannot be earlier than createdAt");
+		this._updatedAt = cloneDate(updatedAt);
+		this._aggregateVersion += 1;
+		return this._aggregateVersion;
+	}
+};
+Entity = _Entity = __decorate([version("1.0")], Entity);
+//#endregion
+//#region src/core/domain/value-object.ts
+var _ValueObject;
+/**
+* Base class for value objects — domain concepts defined entirely by their
+* contents, with no identity of their own. Two value objects are
+* interchangeable when they hold equal data, which is the opposite of an
+* {@link Entity} (compared by id). Money, a CPF, a date range: replacing one
+* instance with an equal one changes nothing about the model.
+*
+* Immutability is the defining guarantee here. The wrapped `value` is
+* deep-frozen on construction, so a value object can be shared freely without
+* any risk of a consumer mutating shared state. Subclasses seal the instance
+* itself with {@link finalize} once their own fields are set.
+*
+* @typeParam T - The shape of the wrapped data.
+* @typeParam P - The primitive form produced by {@link toPrimitive} / {@link toJSON}.
+*/
+let ValueObject = class ValueObject {
+	static {
+		_ValueObject = this;
+	}
+	static {
+		this.plugins = new PluginManager();
+	}
+	/**
+	* Wraps `value`, deep-freezing it so the value object is immutable from the
+	* moment it exists. Declared `protected` because value objects are built
+	* through a validating subclass factory, never instantiated directly.
+	*/
+	constructor(value) {
+		this.value = makeImmutable(value);
+	}
+	/**
+	* The schema/contract version stamped on this value-object type by the
+	* `@version` decorator — used to detect state persisted under an older shape.
+	*/
+	get contractVersion() {
+		return _ValueObject.CONTRACT_VERSION;
+	}
+	/**
+	* Freezes the instance shell, blocking reassignment of any own field.
+	*
+	* `value` is already deep-frozen by the constructor, so the wrapped data is
+	* immutable regardless. The instance itself is NOT frozen automatically
+	* because a subclass may still need to assign its own fields after
+	* `super(value)` runs. Call `finalize()` at the very end of the subclass
+	* constructor (after all fields are set) to make the whole value object
+	* immutable.
+	*/
+	finalize() {
+		Object.freeze(this);
+	}
+	/**
+	* Hook for `JSON.stringify`. Delegates to {@link toPrimitive} so a value
+	* object serializes to its primitive form rather than exposing the internal
+	* `value` wrapper.
+	*/
+	toJSON() {
+		return this.toPrimitive();
+	}
+	/**
+	* Compares this value object with another by content. Because value objects
+	* carry no identity, two independently constructed instances holding the
+	* 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`.
+	* 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) });
+	}
+};
+ValueObject = _ValueObject = __decorate([version("1.0")], ValueObject);
+//#endregion
+export { Entity as n, assertValidAggregateVersion as r, ValueObject as t };
+
+//# sourceMappingURL=value-object.js.map

package/dist/value-object.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"value-object.js","names":[],"sources":["../src/core/shared/aggregate-version.ts","../src/core/domain/entity.ts","../src/core/domain/value-object.ts"],"sourcesContent":["import { InvariantViolationException } from \"../exceptions/invariant-violation-exception.js\";\n\nfunction assertValidAggregateVersion(aggregateVersion: number): void {\n    if (!Number.isInteger(aggregateVersion) || aggregateVersion < 0) {\n        throw new InvariantViolationException(\n            `aggregateVersion must be a non-negative integer. Received: ${aggregateVersion}`,\n        );\n    }\n}\n\nexport { assertValidAggregateVersion };\n","import { InvariantViolationException } from \"../exceptions/invariant-violation-exception.js\";\nimport { assertValidAggregateVersion } from \"../shared/aggregate-version.js\";\nimport { assertValidDate, cloneDate } from \"../shared/temporal-guards.js\";\nimport { type ContractVersion, version } from \"../versioning/version.js\";\n\n/**\n * The minimal persisted shape needed to reconstitute an {@link Entity}.\n *\n * This is the contract between storage and the domain: a repository maps a row\n * (or document) onto these four fields and hands them to a subclass constructor.\n * `aggregateVersion` travels with the state so optimistic-concurrency checks\n * survive a round-trip through the database.\n */\ninterface EntityState<TIdentifier> {\n    readonly id: TIdentifier;\n    readonly createdAt: Date;\n    readonly updatedAt: Date;\n    readonly aggregateVersion: number;\n}\n\n/**\n * Base class for domain entities — objects defined by a stable identity rather\n * than by their attributes. Two entities are \"the same\" when their `id`\n * matches, even if every other field differs; this is the opposite of a\n * {@link ValueObject}, which is defined entirely by its contents.\n *\n * The class owns the bookkeeping common to every aggregate root: a creation\n * timestamp that never changes, a last-modified timestamp, and an\n * `aggregateVersion` counter used for optimistic concurrency control. All three\n * are validated on construction and the dates are defensively cloned, so an\n * entity can never be built into — or leak — an inconsistent temporal state.\n *\n * @typeParam TIdentifier - The identity type (e.g. a branded string id or a VO).\n */\n@version(\"1.0\")\nabstract class Entity<TIdentifier> {\n    declare public static readonly CONTRACT_VERSION: ContractVersion;\n\n    private readonly _id: TIdentifier;\n    private readonly _createdAt: Date;\n    private _updatedAt: Date;\n    private _aggregateVersion: number;\n\n    /**\n     * Reconstitutes an entity from its persisted {@link EntityState}.\n     *\n     * Validates the temporal invariants up front so an invalid entity is\n     * impossible to construct: both dates must be valid, the aggregate version\n     * must be a non-negative integer, and `updatedAt` may not predate\n     * `createdAt`. Both dates are cloned on the way in so a later mutation of\n     * the caller's `Date` objects cannot reach into the entity's internal state.\n     *\n     * Declared `protected` because entities are reconstituted through a\n     * subclass factory, never instantiated directly by application code.\n     *\n     * @throws {InvariantViolationException} When `updatedAt` is earlier than `createdAt`.\n     */\n    protected constructor(state: EntityState<TIdentifier>) {\n        assertValidDate(\"createdAt\", state.createdAt);\n        assertValidDate(\"updatedAt\", state.updatedAt);\n        assertValidAggregateVersion(state.aggregateVersion);\n\n        if (state.updatedAt.getTime() < state.createdAt.getTime()) {\n            throw new InvariantViolationException(\n                \"updatedAt cannot be earlier than createdAt\",\n            );\n        }\n\n        this._id = state.id;\n        this._createdAt = cloneDate(state.createdAt);\n        this._updatedAt = cloneDate(state.updatedAt);\n        this._aggregateVersion = state.aggregateVersion;\n    }\n\n    /** The entity's stable identity — the basis for equality between entities. */\n    public get id(): TIdentifier {\n        return this._id;\n    }\n\n    /**\n     * When the entity was first created.\n     *\n     * Returns a clone so callers cannot mutate the entity's internal `Date`;\n     * the value is fixed at construction and never changes thereafter.\n     */\n    public get createdAt(): Date {\n        return cloneDate(this._createdAt);\n    }\n\n    /**\n     * When the entity was last modified.\n     *\n     * Returns a clone for the same encapsulation reason as {@link createdAt};\n     * the underlying value advances only through {@link markAsModified}.\n     */\n    public get updatedAt(): Date {\n        return cloneDate(this._updatedAt);\n    }\n\n    /**\n     * Monotonic counter incremented on every mutation, used for optimistic\n     * concurrency control: a writer reads this value, and the persistence layer\n     * rejects the write if the stored version has moved on in the meantime.\n     */\n    public get aggregateVersion(): number {\n        return this._aggregateVersion;\n    }\n\n    /**\n     * The schema/contract version stamped on this entity type by the\n     * `@version` decorator — used to detect and migrate state persisted under\n     * an older shape.\n     */\n    public get contractVersion(): ContractVersion {\n        return Entity.CONTRACT_VERSION;\n    }\n\n    /**\n     * The single seam through which an entity records a mutation: it advances\n     * `updatedAt` and bumps {@link aggregateVersion} by one. Subclasses must\n     * call this from every state-changing method so the version counter stays\n     * an accurate optimistic-lock token.\n     *\n     * @param updatedAt - The modification instant; defaults to now. Validated\n     *   and required not to predate `createdAt`, preserving the same invariant\n     *   the constructor enforces.\n     * @returns The new aggregate version after the increment.\n     * @throws {InvariantViolationException} When `updatedAt` is earlier than `createdAt`.\n     */\n    protected markAsModified(updatedAt: Date = new Date()): number {\n        assertValidDate(\"updatedAt\", updatedAt);\n\n        if (updatedAt.getTime() < this._createdAt.getTime()) {\n            throw new InvariantViolationException(\n                \"updatedAt cannot be earlier than createdAt\",\n            );\n        }\n\n        this._updatedAt = cloneDate(updatedAt);\n        this._aggregateVersion += 1;\n\n        return this._aggregateVersion;\n    }\n}\n\nexport { Entity, type EntityState };\n","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":";;;;;AAEA,SAAS,4BAA4B,kBAAgC;CACjE,IAAI,CAAC,OAAO,UAAU,gBAAgB,KAAK,mBAAmB,GAC1D,MAAM,IAAI,4BACN,8DAA8D,kBAClE;AAER;;;;;;;;;;;;;;;;;;AC0BA,IAAA,SAAA,MACe,OAAoB;;;;;;;;;;;;;;;;;;CAsB/B,YAAsB,OAAiC;EACnD,gBAAgB,aAAa,MAAM,SAAS;EAC5C,gBAAgB,aAAa,MAAM,SAAS;EAC5C,4BAA4B,MAAM,gBAAgB;EAElD,IAAI,MAAM,UAAU,QAAQ,IAAI,MAAM,UAAU,QAAQ,GACpD,MAAM,IAAI,4BACN,4CACJ;EAGJ,KAAK,MAAM,MAAM;EACjB,KAAK,aAAa,UAAU,MAAM,SAAS;EAC3C,KAAK,aAAa,UAAU,MAAM,SAAS;EAC3C,KAAK,oBAAoB,MAAM;CACnC;;CAGA,IAAW,KAAkB;EACzB,OAAO,KAAK;CAChB;;;;;;;CAQA,IAAW,YAAkB;EACzB,OAAO,UAAU,KAAK,UAAU;CACpC;;;;;;;CAQA,IAAW,YAAkB;EACzB,OAAO,UAAU,KAAK,UAAU;CACpC;;;;;;CAOA,IAAW,mBAA2B;EAClC,OAAO,KAAK;CAChB;;;;;;CAOA,IAAW,kBAAmC;EAC1C,OAAA,QAAc;CAClB;;;;;;;;;;;;;CAcA,eAAyB,4BAAkB,IAAI,KAAK,GAAW;EAC3D,gBAAgB,aAAa,SAAS;EAEtC,IAAI,UAAU,QAAQ,IAAI,KAAK,WAAW,QAAQ,GAC9C,MAAM,IAAI,4BACN,4CACJ;EAGJ,KAAK,aAAa,UAAU,SAAS;EACrC,KAAK,qBAAqB;EAE1B,OAAO,KAAK;CAChB;AACJ;+BA7GC,QAAQ,KAAK,CAAA,GAAA,MAAA;;;;;;;;;;;;;;;;;;;ACDd,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"}

package/dist/version.d.ts

@@ -0,0 +1,10 @@
+//#region src/core/versioning/version.d.ts
+type ContractVersion = `${number}.${number}`;
+type VersionedTarget = {
+  readonly prototype: object;
+};
+declare const CONTRACT_VERSION_PROPERTY: "CONTRACT_VERSION";
+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 };
+//# sourceMappingURL=version.d.ts.map

package/dist/versioning/index.d.ts

@@ -0,0 +1,3 @@
+import { i as version, n as ContractVersion, r as VersionedTarget, t as CONTRACT_VERSION_PROPERTY } from "../version.js";
+import { a as buildDomainEventContractVersions, i as DomainEventEnvelope, n as DomainEventContractSelection, o as createDomainEventEnvelope, r as DomainEventContractVersions, t as CreateDomainEventEnvelopeInput } from "../domain-event-contracts.js";
+export { CONTRACT_VERSION_PROPERTY, ContractVersion, CreateDomainEventEnvelopeInput, DomainEventContractSelection, DomainEventContractVersions, DomainEventEnvelope, VersionedTarget, buildDomainEventContractVersions, createDomainEventEnvelope, version };

package/dist/versioning/index.js

@@ -0,0 +1,3 @@
+import { i as version, r as CONTRACT_VERSION_PROPERTY } from "../immutable.js";
+import { n as createDomainEventEnvelope, t as buildDomainEventContractVersions } from "../domain-event-contracts.js";
+export { CONTRACT_VERSION_PROPERTY, buildDomainEventContractVersions, createDomainEventEnvelope, version };