@cullet/erp-core 1.3.0 → 1.5.0

package/dist/value-object.d.cts

@@ -0,0 +1,97 @@
+import { t as PluginManager } from "./plugin.cjs";
+import { t as DeepReadonly } from "./immutable.cjs";
+import { n as ContractVersion } from "./version.cjs";
+
+//#region src/core/domain/value-object.d.ts
+
+/**
+ * Extension point for value-object equality. A plugin implementing this
+ * contract overrides how any two value objects are compared, letting the host
+ * application swap in a structural comparator (e.g. `lodash.isEqual` over the
+ * wrapped `value`) without every value object having to implement `equals` by
+ * hand.
+ */
+type ValueObjectPluginContract = {
+  equals: (a: ValueObject<unknown, unknown>, b: ValueObject<unknown, unknown>) => boolean;
+};
+/**
+ * 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.
+ *
+ * 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}.
+ */
+declare abstract class ValueObject<T, P> {
+  static readonly CONTRACT_VERSION: ContractVersion;
+  /**
+   * Registry of equality plugins shared by every value object. Empty by
+   * 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.
+   */
+  static readonly plugins: PluginManager<ValueObjectPluginContract>;
+  /** The wrapped data, deep-frozen so it can never be mutated after construction. */
+  readonly value: DeepReadonly<T>;
+  /**
+   * 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.
+   */
+  protected constructor(value: T);
+  /**
+   * 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(): ContractVersion;
+  /**
+   * 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.
+   */
+  protected finalize(): void;
+  /**
+   * 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(): P;
+  /**
+   * 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`,
+   * with object keys sorted so insertion order (e.g. code-built vs
+   * JSON-rehydrated) never affects the result.
+   * Subclasses may still override for a faster or domain-specific comparison.
+   */
+  equals(other: this): boolean;
+  /**
+   * Projects the value object down to a plain, serializable primitive form —
+   * the representation suitable for persistence, transport, or comparison.
+   */
+  abstract toPrimitive(): P;
+}
+//#endregion
+export { ValueObjectPluginContract as n, ValueObject as t };
+//# sourceMappingURL=value-object.d.cts.map

package/dist/value-object.d.ts

@@ -0,0 +1,97 @@
+import { t as PluginManager } from "./plugin.js";
+import { t as DeepReadonly } from "./immutable.js";
+import { n as ContractVersion } from "./version.js";
+
+//#region src/core/domain/value-object.d.ts
+
+/**
+ * Extension point for value-object equality. A plugin implementing this
+ * contract overrides how any two value objects are compared, letting the host
+ * application swap in a structural comparator (e.g. `lodash.isEqual` over the
+ * wrapped `value`) without every value object having to implement `equals` by
+ * hand.
+ */
+type ValueObjectPluginContract = {
+  equals: (a: ValueObject<unknown, unknown>, b: ValueObject<unknown, unknown>) => boolean;
+};
+/**
+ * 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.
+ *
+ * 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}.
+ */
+declare abstract class ValueObject<T, P> {
+  static readonly CONTRACT_VERSION: ContractVersion;
+  /**
+   * Registry of equality plugins shared by every value object. Empty by
+   * 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.
+   */
+  static readonly plugins: PluginManager<ValueObjectPluginContract>;
+  /** The wrapped data, deep-frozen so it can never be mutated after construction. */
+  readonly value: DeepReadonly<T>;
+  /**
+   * 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.
+   */
+  protected constructor(value: T);
+  /**
+   * 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(): ContractVersion;
+  /**
+   * 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.
+   */
+  protected finalize(): void;
+  /**
+   * 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(): P;
+  /**
+   * 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`,
+   * with object keys sorted so insertion order (e.g. code-built vs
+   * JSON-rehydrated) never affects the result.
+   * Subclasses may still override for a faster or domain-specific comparison.
+   */
+  equals(other: this): boolean;
+  /**
+   * Projects the value object down to a plain, serializable primitive form —
+   * the representation suitable for persistence, transport, or comparison.
+   */
+  abstract toPrimitive(): P;
+}
+//#endregion
+export { ValueObjectPluginContract as n, ValueObject as t };
+//# sourceMappingURL=value-object.d.ts.map

package/dist/value-object.js

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

package/dist/value-object.js.map

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

package/meta.json

@@ -1,7 +1,7 @@
 {
     "schemaVersion": "2",
     "name": "erp-core",
-    "version": "1.3.0",
+    "version": "1.5.0",
     "description": "Núcleo arquitetural para ERP em TypeScript — entidades, value objects, erros tipados e policies declaráveis sobre clean architecture.",
     "compatibility": {
         "engines": {
@@ -14,7 +14,7 @@
                     "name": "zod",
                     "range": ">=3.22.0 <5",
                     "optional": true,
-                    "notes": "Only required by the `./policies` subpath (gate/compute engines). The domain/result/errors/exceptions/rulesets/versioning/plugins subpaths are zod-free."
+                    "notes": "Only required by the `./policies` subpath (gate/compute engines). The domain/result/errors/exceptions/rulesets/versioning/plugins/rbac/abac subpaths are zod-free."
                 }
             ]
         },
@@ -75,7 +75,21 @@
         "PolicyDecision",
         "PolicyResolver",
         "PolicyService",
-        "mapPolicyEvaluationError"
+        "mapPolicyEvaluationError",
+        "Permission",
+        "Role",
+        "Grant",
+        "Scope",
+        "PermissionSet",
+        "RbacAuthorizer",
+        "AuthorizerPort",
+        "rbacContextFields",
+        "AbacRule",
+        "AbacPolicySet",
+        "AbacAuthorizer",
+        "AbacAuthorizerPort",
+        "abacContext",
+        "CompositeAuthorizer"
     ],
     "changelog": [
         "1.0.1 - Corrige os exemplos de consumo nos READMEs dos kits: o import direto usa o nome npm com escopo (`@cullet/<kit>`) e o argumento do `npx cullet fc` é o nome do kit no registry (`erp-core`), não o nome com escopo. Adiciona a nota explicando o que o `fc` faz no `erp-core`.",
@@ -91,7 +105,9 @@
         "1.0.11 - Document the public API surface with TSDoc.",
         "1.1.0 - **New: `ResultRepository`, `UseCaseObservability`, and `./application` subpath**",
         "1.2.0 - Add zod-free subpaths for the stable core primitives and a value-object equality plugin system.",
-        "1.3.0 - Add zod-free subpaths for the stable core primitives and a value-object equality plugin system."
+        "1.3.0 - Add zod-free subpaths for the stable core primitives and a value-object equality plugin system.",
+        "1.4.0 - Add a zod-free ABAC module and the `./abac` subpath.",
+        "1.5.0 - Add a zod-free ABAC module and the `./abac` subpath."
     ],
     "deprecated": false
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cullet/erp-core",
-    "version": "1.3.0",
+    "version": "1.5.0",
     "description": "Núcleo arquitetural para ERP em TypeScript — entidades, value objects, erros tipados e policies declaráveis sobre clean architecture.",
     "type": "module",
     "repository": {
@@ -13,6 +13,9 @@
     "types": "./dist/index.d.ts",
     "typesVersions": {
         "*": {
+            "abac": [
+                "./dist/abac/index.d.ts"
+            ],
             "application": [
                 "./dist/application/index.d.ts"
             ],
@@ -40,6 +43,9 @@
             "policies/engines/v1/gate": [
                 "./dist/policies/engines/v1/gate/index.d.ts"
             ],
+            "rbac": [
+                "./dist/rbac/index.d.ts"
+            ],
             "result": [
                 "./dist/result/index.d.ts"
             ],
@@ -62,6 +68,16 @@
                 "default": "./dist/index.cjs"
             }
         },
+        "./abac": {
+            "import": {
+                "types": "./dist/abac/index.d.ts",
+                "default": "./dist/abac/index.js"
+            },
+            "require": {
+                "types": "./dist/abac/index.d.cts",
+                "default": "./dist/abac/index.cjs"
+            }
+        },
         "./application": {
             "import": {
                 "types": "./dist/application/index.d.ts",
@@ -152,6 +168,16 @@
                 "default": "./dist/policies/engines/v1/gate/index.cjs"
             }
         },
+        "./rbac": {
+            "import": {
+                "types": "./dist/rbac/index.d.ts",
+                "default": "./dist/rbac/index.js"
+            },
+            "require": {
+                "types": "./dist/rbac/index.d.cts",
+                "default": "./dist/rbac/index.cjs"
+            }
+        },
         "./result": {
             "import": {
                 "types": "./dist/result/index.d.ts",

package/src/abac/index.ts

@@ -0,0 +1 @@
+export * from "../core/abac/index.js";

package/src/core/abac/abac-request.ts

@@ -0,0 +1,29 @@
+import type { RequestedBy } from "../application/commands/requested-by.js";
+
+/**
+ * The attribute bags an ABAC decision reasons over, grouped by the four standard
+ * categories. Each is a flat record; {@link abacContext} nests them under
+ * `subject` / `resource` / `action` / `env` so a rule's condition can reference
+ * fields like `resource.status` or `env.businessHours`.
+ */
+type AbacAttributes = {
+    readonly subject?: Record<string, unknown>;
+    readonly resource?: Record<string, unknown>;
+    readonly action?: Record<string, unknown>;
+    readonly environment?: Record<string, unknown>;
+};
+
+/**
+ * The question put to the {@link AbacAuthorizer}: *do these attributes authorize
+ * this action?* Carries the acting {@link RequestedBy} (reused as the subject),
+ * an audit-friendly `action` label, an optional type/id resource reference, and
+ * the {@link AbacAttributes} the rules evaluate.
+ */
+interface AbacRequest {
+    readonly actor: RequestedBy;
+    readonly action: string;
+    readonly resource?: { readonly type: string; readonly id?: string };
+    readonly attributes: AbacAttributes;
+}
+
+export type { AbacAttributes, AbacRequest };

package/src/core/abac/attributes.ts

@@ -0,0 +1,39 @@
+import type { PolicyContext } from "../policies/engines/gate-types.js";
+
+import type { AbacRequest } from "./abac-request.js";
+
+/**
+ * Flattens an {@link AbacRequest} into the nested {@link PolicyContext} the
+ * condition evaluator reads (it resolves dotted fields like `resource.status` by
+ * walking nested objects). The actor lands as `subject.id`; the four attribute
+ * bags nest under `subject` / `resource` / `action` / `env`; a `resource`
+ * reference adds `resource.type` / `resource.id`. The actor id and the resource
+ * reference win over any same-named keys in the attribute bags.
+ *
+ * Consumers fold dynamic facts (e.g. RBAC roles/permissions derived from grants,
+ * or a computed `ownerIsActor` flag) into `attributes.subject` / `resource` so
+ * rules can reference `subject.roles`, `resource.ownerIsActor`, and the like.
+ */
+export function abacContext(request: AbacRequest): PolicyContext {
+    const attributes = request.attributes;
+
+    const subject: Record<string, unknown> = {
+        ...attributes.subject,
+        id: request.actor.raw,
+    };
+
+    const resource: Record<string, unknown> = { ...attributes.resource };
+    if (request.resource) {
+        resource.type = request.resource.type;
+        if (request.resource.id !== undefined) {
+            resource.id = request.resource.id;
+        }
+    }
+
+    return {
+        subject,
+        resource,
+        action: { ...attributes.action },
+        env: { ...attributes.environment },
+    };
+}