@cullet/erp-core 1.4.0 → 2.0.0

package/src/core/shared/stable-stringify.ts

@@ -0,0 +1,144 @@
+import { isValidDate } from "./temporal-guards.js";
+
+const CIRCULAR_STRUCTURE_MESSAGE =
+    "Cannot stably stringify a circular structure";
+
+// `seen` holds the current traversal branch so true cycles are rejected while
+// repeated (acyclic) references are still serialized — matching JSON.stringify.
+function sortKeysDeep(value: unknown, seen: WeakSet<object>): unknown {
+    if (Array.isArray(value)) {
+        if (seen.has(value)) {
+            throw new TypeError(CIRCULAR_STRUCTURE_MESSAGE);
+        }
+        seen.add(value);
+        const mapped = value.map((item) => sortKeysDeep(item, seen));
+        seen.delete(value);
+        return mapped;
+    }
+
+    if (value instanceof Date) {
+        return value;
+    }
+
+    if (value && typeof value === "object") {
+        if (seen.has(value)) {
+            throw new TypeError(CIRCULAR_STRUCTURE_MESSAGE);
+        }
+        seen.add(value);
+        const record = value as Record<string, unknown>;
+        const ordered = Object.create(null) as Record<string, unknown>;
+
+        for (const key of Object.keys(record).sort()) {
+            ordered[key] = sortKeysDeep(record[key], seen);
+        }
+        seen.delete(value);
+
+        return ordered;
+    }
+
+    return value;
+}
+
+/**
+ * Deterministic JSON string with object keys sorted recursively, so key order
+ * does not affect the output.
+ *
+ * Follows `JSON.stringify` semantics for the values it serializes: `undefined`,
+ * functions and symbols are dropped, non-finite numbers become `null`, `bigint`
+ * throws, and `Map`/`Set` serialize as `{}`. Distinct payloads can therefore
+ * collapse to the same string — this is fine for the structural-equality use it
+ * serves (comparing two value objects), but **not** for hashing. For a
+ * collision-resistant canonical form use {@link canonicalStringify}, which
+ * rejects those lossy values up front.
+ *
+ * @throws {TypeError} On circular references (mirroring `JSON.stringify`).
+ */
+function stableStringify(value: unknown): string {
+    return JSON.stringify(sortKeysDeep(value, new WeakSet<object>()));
+}
+
+// Rejects every value `JSON.stringify` would silently drop or coerce, so
+// semantically different payloads can never collapse to the same canonical
+// string. Owned here (rather than in policies) so `payloadHash` and
+// `PolicyHashing` share one strict definition instead of each re-implementing
+// the deep guard.
+function assertHashable(
+    value: unknown,
+    path: string,
+    seen: WeakSet<object>,
+): void {
+    if (value === null) {
+        return;
+    }
+
+    const type = typeof value;
+
+    if (type === "undefined") {
+        throw new TypeError(
+            `canonicalStringify does not accept undefined values (at ${path})`,
+        );
+    }
+
+    if (type === "number" && !Number.isFinite(value)) {
+        throw new TypeError(
+            `canonicalStringify does not accept non-finite numbers (at ${path}, value: ${String(value)})`,
+        );
+    }
+
+    if (type === "bigint" || type === "function" || type === "symbol") {
+        throw new TypeError(
+            `canonicalStringify does not accept ${type} values (at ${path})`,
+        );
+    }
+
+    if (type !== "object") {
+        return;
+    }
+
+    if (value instanceof Date) {
+        if (!isValidDate(value)) {
+            throw new TypeError(
+                `canonicalStringify does not accept Invalid Date (at ${path})`,
+            );
+        }
+        return;
+    }
+
+    if (seen.has(value as object)) {
+        throw new TypeError(
+            `canonicalStringify does not accept circular references (at ${path})`,
+        );
+    }
+    seen.add(value as object);
+
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => {
+            assertHashable(item, `${path}[${index}]`, seen);
+        });
+    } else {
+        for (const [key, nested] of Object.entries(
+            value as Record<string, unknown>,
+        )) {
+            assertHashable(nested, `${path}.${key}`, seen);
+        }
+    }
+
+    seen.delete(value as object);
+}
+
+/**
+ * Strict counterpart to {@link stableStringify}: same deterministic output, but
+ * throws on any value `JSON.stringify` would drop or coerce (`undefined`,
+ * non-finite numbers, `bigint`, functions, symbols, `Invalid Date`) and on
+ * circular references. Use this whenever the string feeds a hash or integrity
+ * check, so distinct payloads cannot collide.
+ *
+ * @throws {TypeError} On lossy values or circular references.
+ */
+function canonicalStringify(value: unknown): string {
+    assertHashable(value, "$", new WeakSet<object>());
+
+    return stableStringify(value);
+}
+
+export { assertHashable, canonicalStringify, stableStringify };

package/src/core/shared/uuid.ts

@@ -0,0 +1,16 @@
+/**
+ * Canonical RFC-4122 / RFC-9562 UUID, matched case-insensitively. Accepts
+ * versions 1–8 (variant 8/9/a/b) — notably UUIDv7, the time-ordered default for
+ * sortable primary keys in modern schemas. The nil (`0000…`) and max (`ffff…`)
+ * UUIDs are intentionally rejected: they are sentinels, not real identities, and
+ * a domain id should never carry one.
+ *
+ * The single source of truth for the UUID format — `UuidIdentifier` (domain ids)
+ * and `RequestedBy` (command actor) both validate against this pattern, so an
+ * identity accepted at the application boundary is always one the domain also
+ * considers valid.
+ */
+const UUID_PATTERN =
+    /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+export { UUID_PATTERN };

package/src/core/versioning/domain-event-contracts.ts

@@ -1,27 +1,52 @@
-import { UseCase } from "../application/use-case.js";
-import { Entity } from "../domain/entity.js";
-import { ValueObject } from "../domain/value-object.js";
 import { assertValidAggregateVersion } from "../shared/aggregate-version.js";
+import { deepFreeze } from "../shared/immutable.js";
 import { type ContractVersion } from "./version.js";
 
+/** Anything carrying a `CONTRACT_VERSION` — a class decorated with `@version`. */
+interface ContractVersioned {
+    readonly CONTRACT_VERSION: ContractVersion;
+}
+
+/**
+ * The classes whose contract version should be recorded on the envelope.
+ *
+ * Pass the **concrete** aggregate/value-object/use-case class (not the base),
+ * so the envelope records the version the caller actually annotated with
+ * `@version`. A base class handed here would report only the framework's
+ * version, not the concrete shape that produced the event.
+ */
 interface DomainEventContractSelection {
-    readonly entity?: boolean;
-    readonly valueObject?: boolean;
-    readonly useCase?: boolean;
+    readonly entity?: ContractVersioned;
+    readonly valueObject?: ContractVersioned;
+    readonly useCase?: ContractVersioned;
 }
 
+// Wire-format shape: `snake_case` keys, deliberately distinct from the
+// `camelCase` builder input above — these travel in the serialized event.
 interface DomainEventContractVersions {
     readonly entity_contract?: ContractVersion;
     readonly value_object_contract?: ContractVersion;
     readonly use_case_contract?: ContractVersion;
 }
 
+type MutableContractVersions = {
+    -readonly [K in keyof DomainEventContractVersions]: DomainEventContractVersions[K];
+};
+
 interface CreateDomainEventEnvelopeInput<TPayload> {
     readonly aggregateVersion: number;
     readonly payload: TPayload;
     readonly contracts: DomainEventContractSelection;
 }
 
+/**
+ * A deliberately minimal domain-event envelope: it carries only the aggregate
+ * version and the structural contract versions needed for state/event
+ * migration. It intentionally omits `eventId`, `eventType`, `occurredAt` and
+ * correlation ids — those require a clock/id source and belong to the
+ * consumer's event infrastructure. Treat this as a versioning core to extend,
+ * not a complete event record.
+ */
 interface DomainEventEnvelope<TPayload> extends DomainEventContractVersions {
     readonly aggregate_version: number;
     readonly payload: TPayload;
@@ -30,33 +55,35 @@ interface DomainEventEnvelope<TPayload> extends DomainEventContractVersions {
 function buildDomainEventContractVersions(
     selection: DomainEventContractSelection,
 ): DomainEventContractVersions {
-    const contractVersions: {
-        entity_contract?: ContractVersion;
-        value_object_contract?: ContractVersion;
-        use_case_contract?: ContractVersion;
-    } = {};
+    const contractVersions: MutableContractVersions = {};
 
     if (selection.entity) {
-        contractVersions.entity_contract = Entity.CONTRACT_VERSION;
+        contractVersions.entity_contract = selection.entity.CONTRACT_VERSION;
     }
 
     if (selection.valueObject) {
-        contractVersions.value_object_contract = ValueObject.CONTRACT_VERSION;
+        contractVersions.value_object_contract =
+            selection.valueObject.CONTRACT_VERSION;
     }
 
     if (selection.useCase) {
-        contractVersions.use_case_contract = UseCase.CONTRACT_VERSION;
+        contractVersions.use_case_contract = selection.useCase.CONTRACT_VERSION;
     }
 
     return Object.freeze(contractVersions);
 }
 
+/**
+ * Builds a frozen domain-event envelope. The whole envelope is deep-frozen,
+ * so the `payload` handed in becomes immutable too — an event is an immutable
+ * fact, and the caller must not mutate the payload after wrapping it.
+ */
 function createDomainEventEnvelope<TPayload>(
     input: CreateDomainEventEnvelopeInput<TPayload>,
 ): DomainEventEnvelope<TPayload> {
     assertValidAggregateVersion(input.aggregateVersion);
 
-    return Object.freeze({
+    return deepFreeze({
         aggregate_version: input.aggregateVersion,
         payload: input.payload,
         ...buildDomainEventContractVersions(input.contracts),
@@ -66,6 +93,7 @@ function createDomainEventEnvelope<TPayload>(
 export {
     buildDomainEventContractVersions,
     createDomainEventEnvelope,
+    type ContractVersioned,
     type CreateDomainEventEnvelopeInput,
     type DomainEventContractSelection,
     type DomainEventContractVersions,

package/src/core/versioning/index.ts

@@ -1,6 +1,7 @@
 export {
     buildDomainEventContractVersions,
     createDomainEventEnvelope,
+    type ContractVersioned,
     type CreateDomainEventEnvelopeInput,
     type DomainEventContractSelection,
     type DomainEventContractVersions,

package/src/core/versioning/version.ts

@@ -1,5 +1,16 @@
+import { InvariantViolationException } from "../exceptions/invariant-violation-exception.js";
+
+/**
+ * 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;
 };
@@ -7,11 +18,29 @@ type VersionedTarget = {
 const CONTRACT_VERSION_PROPERTY = "CONTRACT_VERSION" as const;
 const CONTRACT_VERSION_PATTERN = /^\d+\.\d+$/;
 
+/**
+ * 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).
+ */
 function version<const TVersion extends ContractVersion>(
     contractVersion: TVersion,
 ) {
     if (!CONTRACT_VERSION_PATTERN.test(contractVersion)) {
-        throw new TypeError(
+        throw new InvariantViolationException(
             `Invalid contract version "${contractVersion}". Expected MAJOR.MINOR.`,
         );
     }

package/src/domain/index.ts

@@ -5,3 +5,8 @@ export {
     ValueObject,
     type ValueObjectPluginContract,
 } from "../core/domain/value-object.js";
+// Bitemporal primitives. Published on this subpath (not the root barrel)
+// because the public `TemporalRepository` port already exposes
+// `TemporalSnapshot` — implementers need the validating factories that build
+// it, not just the type.
+export * from "../core/domain/temporal/index.js";

package/src/examples/rulesets/entity/order-creation-rules-v1.ts

@@ -1,4 +1,4 @@
-import { DomainException } from "../../../core/domain/rulesets/entity-ruleset.contracts.js";
+import { DomainException } from "../../../core/exceptions/domain-exception.js";
 import { type OrderCreationData, type OrderCreationRuleset } from "./order.js";
 
 class OrderCreationValidationError extends DomainException {}

package/src/examples/rulesets/entity/order-invariants-v1.ts

@@ -1,7 +1,5 @@
-import {
-    DomainException,
-    type RulesetId,
-} from "../../../core/domain/rulesets/entity-ruleset.contracts.js";
+import { DomainException } from "../../../core/exceptions/domain-exception.js";
+import { type RulesetId } from "../../../core/domain/rulesets/entity-ruleset.contracts.js";
 import {
     type Order,
     type OrderInvariantRuleset,

package/src/examples/rulesets/entity/order-invariants-v2.ts

@@ -1,7 +1,5 @@
-import {
-    DomainException,
-    type RulesetId,
-} from "../../../core/domain/rulesets/entity-ruleset.contracts.js";
+import { DomainException } from "../../../core/exceptions/domain-exception.js";
+import { type RulesetId } from "../../../core/domain/rulesets/entity-ruleset.contracts.js";
 import { type Order } from "./order.js";
 import { OrderInvariantsV1 } from "./order-invariants-v1.js";
 

package/src/examples/rulesets/value-object/cpf-rules-v1.ts

@@ -1,7 +1,5 @@
-import {
-    DomainException,
-    type ValueObjectRuleset,
-} from "../../../core/domain/rulesets/value-object-ruleset.contracts.js";
+import { DomainException } from "../../../core/exceptions/domain-exception.js";
+import { type ValueObjectRuleset } from "../../../core/domain/rulesets/value-object-ruleset.contracts.js";
 
 class CPFValidationError extends DomainException {}
 

package/src/examples/rulesets/value-object/cpf-rules-v2.ts

@@ -1,7 +1,5 @@
-import {
-    DomainException,
-    type ValueObjectRuleset,
-} from "../../../core/domain/rulesets/value-object-ruleset.contracts.js";
+import { DomainException } from "../../../core/exceptions/domain-exception.js";
+import { type ValueObjectRuleset } from "../../../core/domain/rulesets/value-object-ruleset.contracts.js";
 import { CPFRulesV1 } from "./cpf-rules-v1.js";
 
 class CPFBlocklistError extends DomainException {}

package/src/examples/rulesets/value-object/person-name-rules-v1.ts

@@ -1,7 +1,5 @@
-import {
-    DomainException,
-    type ValueObjectRuleset,
-} from "../../../core/domain/rulesets/value-object-ruleset.contracts.js";
+import { DomainException } from "../../../core/exceptions/domain-exception.js";
+import { type ValueObjectRuleset } from "../../../core/domain/rulesets/value-object-ruleset.contracts.js";
 
 class PersonNameValidationError extends DomainException {}
 

package/src/examples/rulesets/value-object/person-name-rules-v2.ts

@@ -1,7 +1,5 @@
-import {
-    DomainException,
-    type ValueObjectRuleset,
-} from "../../../core/domain/rulesets/value-object-ruleset.contracts.js";
+import { DomainException } from "../../../core/exceptions/domain-exception.js";
+import { type ValueObjectRuleset } from "../../../core/domain/rulesets/value-object-ruleset.contracts.js";
 import { PersonNameRulesV1 } from "./person-name-rules-v1.js";
 
 class PersonNameCharacterError extends DomainException {}

package/src/result/index.ts

@@ -1,2 +1,7 @@
-export { type CommonOutcomeStatus, Outcome } from "../core/result/outcome.js";
-export { Err, Ok, Result } from "../core/result/result.js";
+export {
+    type CommonOutcomeStatus,
+    Err,
+    Ok,
+    Outcome,
+    Result,
+} from "../core/result/index.js";

package/src/version.ts

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

package/dist/domain-exception.d.cts

@@ -1,7 +0,0 @@
-//#region src/core/exceptions/domain-exception.d.ts
-declare abstract class DomainException extends Error {
-  constructor(message: string);
-}
-//#endregion
-export { DomainException as t };
-//# sourceMappingURL=domain-exception.d.cts.map

package/dist/domain-exception.d.ts

@@ -1,7 +0,0 @@
-//#region src/core/exceptions/domain-exception.d.ts
-declare abstract class DomainException extends Error {
-  constructor(message: string);
-}
-//#endregion
-export { DomainException as t };
-//# sourceMappingURL=domain-exception.d.ts.map

package/dist/entity.cjs

@@ -1,126 +0,0 @@
-const require_invariant_violation_exception = require("./invariant-violation-exception.cjs");
-const require_immutable = require("./immutable.cjs");
-const require_temporal_guards = require("./temporal-guards.cjs");
-//#region src/core/shared/aggregate-version.ts
-function assertValidAggregateVersion(aggregateVersion) {
-	if (!Number.isInteger(aggregateVersion) || aggregateVersion < 0) throw new require_invariant_violation_exception.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) {
-		require_temporal_guards.assertValidDate("createdAt", state.createdAt);
-		require_temporal_guards.assertValidDate("updatedAt", state.updatedAt);
-		assertValidAggregateVersion(state.aggregateVersion);
-		if (state.updatedAt.getTime() < state.createdAt.getTime()) throw new require_invariant_violation_exception.InvariantViolationException("updatedAt cannot be earlier than createdAt");
-		this._id = state.id;
-		this._createdAt = require_temporal_guards.cloneDate(state.createdAt);
-		this._updatedAt = require_temporal_guards.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 require_temporal_guards.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 require_temporal_guards.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()) {
-		require_temporal_guards.assertValidDate("updatedAt", updatedAt);
-		if (updatedAt.getTime() < this._createdAt.getTime()) throw new require_invariant_violation_exception.InvariantViolationException("updatedAt cannot be earlier than createdAt");
-		this._updatedAt = require_temporal_guards.cloneDate(updatedAt);
-		this._aggregateVersion += 1;
-		return this._aggregateVersion;
-	}
-};
-Entity = _Entity = require_immutable.__decorate([require_immutable.version("1.0")], Entity);
-//#endregion
-Object.defineProperty(exports, "Entity", {
-	enumerable: true,
-	get: function() {
-		return Entity;
-	}
-});
-Object.defineProperty(exports, "assertValidAggregateVersion", {
-	enumerable: true,
-	get: function() {
-		return assertValidAggregateVersion;
-	}
-});
-
-//# sourceMappingURL=entity.cjs.map

package/dist/entity.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"entity.cjs","names":["InvariantViolationException","InvariantViolationException","cloneDate","version"],"sources":["../src/core/shared/aggregate-version.ts","../src/core/domain/entity.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"],"mappings":";;;;AAEA,SAAS,4BAA4B,kBAAgC;CACjE,IAAI,CAAC,OAAO,UAAU,gBAAgB,KAAK,mBAAmB,GAC1D,MAAM,IAAIA,sCAAAA,4BACN,8DAA8D,kBAClE;AAER;;;;;;;;;;;;;;;;;;AC0BA,IAAA,SAAA,MACe,OAAoB;;;;;;;;;;;;;;;;;;CAsB/B,YAAsB,OAAiC;EACnD,wBAAA,gBAAgB,aAAa,MAAM,SAAS;EAC5C,wBAAA,gBAAgB,aAAa,MAAM,SAAS;EAC5C,4BAA4B,MAAM,gBAAgB;EAElD,IAAI,MAAM,UAAU,QAAQ,IAAI,MAAM,UAAU,QAAQ,GACpD,MAAM,IAAIC,sCAAAA,4BACN,4CACJ;EAGJ,KAAK,MAAM,MAAM;EACjB,KAAK,aAAaC,wBAAAA,UAAU,MAAM,SAAS;EAC3C,KAAK,aAAaA,wBAAAA,UAAU,MAAM,SAAS;EAC3C,KAAK,oBAAoB,MAAM;CACnC;;CAGA,IAAW,KAAkB;EACzB,OAAO,KAAK;CAChB;;;;;;;CAQA,IAAW,YAAkB;EACzB,OAAOA,wBAAAA,UAAU,KAAK,UAAU;CACpC;;;;;;;CAQA,IAAW,YAAkB;EACzB,OAAOA,wBAAAA,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,wBAAA,gBAAgB,aAAa,SAAS;EAEtC,IAAI,UAAU,QAAQ,IAAI,KAAK,WAAW,QAAQ,GAC9C,MAAM,IAAID,sCAAAA,4BACN,4CACJ;EAGJ,KAAK,aAAaC,wBAAAA,UAAU,SAAS;EACrC,KAAK,qBAAqB;EAE1B,OAAO,KAAK;CAChB;AACJ;iDA7GCC,kBAAAA,QAAQ,KAAK,CAAA,GAAA,MAAA"}