@vytches/ddd-value-objects 0.30.0 → 0.31.0

package/LLMGUIDE.md

@@ -55,13 +55,107 @@ const textId = EntityId.fromText('order-slug');
 
 ### `BaseValueObject<T>` method reference
 
-| Method                              | Description                                        |
-| ----------------------------------- | -------------------------------------------------- |
-| `getValue(): T`                     | Returns the raw wrapped value                      |
-| `equals(other): boolean`            | Structural equality by raw value (`===`)           |
-| `toString(): string`                | `String(value)`                                    |
-| `toJSON(): string`                  | `JSON.stringify(value)`                            |
-| `abstract validate(value): boolean` | Must be implemented; called in subclass `create()` |
+| Method                                                     | Description                                                                                                                                                                                                                                                        |
+| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `getValue(): T`                                            | Returns the raw wrapped value                                                                                                                                                                                                                                      |
+| `equals(other): boolean`                                   | `===` for primitives, `LibUtils.deepEqual` for objects — unless `getIdentityComponents()` is overridden on both sides, in which case identity components decide equality instead (VF-036)                                                                          |
+| `toString(): string`                                       | `String(value)`                                                                                                                                                                                                                                                    |
+| `toJSON(): unknown`                                        | Returns the raw value (not a JSON string)                                                                                                                                                                                                                          |
+| `abstract validate(value): boolean`                        | Must be implemented; called in subclass `create()`                                                                                                                                                                                                                 |
+| `getIdentityComponents(): readonly unknown[] \| undefined` | Protected opt-in hook (VF-036). Default returns `undefined` (raw comparison, unchanged). Override to compare by a subset/projection of fields instead of the full raw value; if either side returns `undefined`, `equals()` falls back to the raw comparison above |
+
+## Partial-identity equality: `getIdentityComponents()` (VF-036)
+
+**When to use it:** override this protected hook when only a subset of a value
+object's `value` should participate in equality (e.g. exclude a display flag,
+audit timestamp, or cache key from identity). Leave it unimplemented (default
+returns `undefined`) when the full raw `value` should decide equality — that is
+the common case.
+
+```ts compile-check
+import { BaseValueObject } from '@vytches/ddd-value-objects';
+
+interface MoneyProps {
+  amount: number;
+  currency: string;
+  displayFormat: 'symbol' | 'code';
+}
+
+class Money extends BaseValueObject<MoneyProps> {
+  validate(value: unknown): boolean {
+    const v = value as MoneyProps;
+    return v.amount >= 0 && v.currency.length === 3;
+  }
+
+  // string-literal discriminator ('Money') scopes equality to this type —
+  // see "Type-scoped equality" below; displayFormat is excluded on purpose.
+  protected override getIdentityComponents(): readonly unknown[] {
+    return ['Money', this.value.amount, this.value.currency];
+  }
+}
+```
+
+**Dispatch rule:** `equals()` calls the hook on both sides. Both defined →
+compare components (same length, then element-wise, dispatching to nested
+`.equals()` for value objects, `LibUtils.deepEqual` otherwise). Either side
+`undefined` → unchanged raw comparison (`===` / `LibUtils.deepEqual`).
+
+**Non-transitivity in mixed populations (collection hazard).** The fallback is
+symmetric but not transitive: with A (no override), B (override, same raw
+`value` as A), C (override, same components as B), `A.equals(B)` and
+`B.equals(C)` can both be `true` while `A.equals(C)` is `false`. Code that
+assumes an equivalence relation — `list.some(x => x.equals(y))`, de-duplication
+by `.equals()` — breaks silently when raw-comparison and component-override
+instances of the same base type are mixed. Migrate a whole hierarchy together
+(see MIGRATION.md), never partially.
+
+**`[]` footgun.** `[]` is defined-and-empty, not "opt out" — two `[]`- returning
+instances are always equal to each other. Return `undefined` to opt out, never
+`[]`.
+
+**Fixed arity.** A class must always return the same number of components in the
+same order. Comparison begins with a length check, so a conditional push
+(`if (this.scope) parts.push(this.scope)`) makes two instances of one class
+unequal because of an unset optional field rather than a real data difference.
+Use a stable placeholder — `[this.tenant, this.scope ?? null, this.key]`. A
+subclass that adds a component changes the arity of every comparison against its
+parent; decide that deliberately.
+
+**Undefined-because-uninitialized is a different trap than it sounds.** Only a
+literal `undefined` returned _by the hook itself_ triggers the raw fallback; an
+`undefined` _component value_ inside a defined array does not. The real trap is
+a _conditional_ override that sometimes returns `undefined` — that silently and
+intermittently downgrades the same class to raw comparison. Always return an
+array once a class opts in.
+
+**Throw propagation.** A throwing override propagates out of `equals()` uncaught
+— no try/catch, by design (`equals()` is a hot path; the library logger is
+diagnostics-only). `equals()` is no longer a total function for a subclass whose
+override can throw.
+
+**Frozen/readonly state only.** The constructor deep-freezes `value`, not any
+subclass field assigned after `super(value)`. Components must derive only from
+`value` or from subclass fields the subclass itself keeps immutable — deriving
+from mutable state breaks equality stability over the instance's lifetime.
+
+**Type-scoped equality idiom.** No type/`instanceof` check is performed —
+cross-subclass equality with matching components stays `true`, same as raw
+comparison today. To scope equality to one type, add a string literal as the
+first component (`['Money', ...]`), never `this.constructor.name`
+(minification-unsafe) or the class object itself (unsafe across duplicate
+package copies).
+
+**`toString()`/`toJSON()` stay value-based** regardless of this hook — both
+always serialize the raw `value`. An override that narrows equality can desync
+serialization from equality; keeping that coherent is the consumer's
+responsibility.
+
+> **Permanent note:** `getEqualityComponents()` — a similarly-named hook from an
+> early (2025) documentation draft — was **never implemented** in any released
+> version and will not be added as an alias/shim/fallback.
+> `getIdentityComponents()` is the real hook, under a deliberately new name. Any
+> existing `getEqualityComponents()` override has always been dead code; see
+> root `MIGRATION.md` to migrate it.
 
 ## Patterns
 

package/README.md

@@ -17,20 +17,20 @@ pnpm add @vytches/ddd-value-objects
 
 ## What's included
 
-| Export                         | Kind      | Description                                                                                                                                  |
-| ------------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| `BaseValueObject<T>`           | class     | Abstract base for value objects; deep-freezes internal value; implements `equals()` via structural comparison                                |
-| `ValueObjectValidator<T>`      | interface | `validate(value: T): boolean` — implement to add invariant checking                                                                          |
-| `EntityId<T>`                  | class     | Enhanced entity identifier extending the contracts `EntityId`; adds UUID/integer/text validation, `create()`, `fromString()`, `fromNumber()` |
-| `EntityIdFactory`              | class     | **Deprecated** — will be removed in v1.0.0; use `EntityId.create()` directly                                                                 |
-| `BrandedId<Tag>`               | type      | Compile-time branded `EntityId<string>` — prevents mixing IDs across aggregate types                                                         |
-| `createBrandedId<Tag>(id)`     | function  | Casts an `EntityId` to `BrandedId<Tag>`                                                                                                      |
-| `newBrandedId<Tag>()`          | function  | Creates a new UUID-based `BrandedId<Tag>`                                                                                                    |
-| `brandedIdFromUUID<Tag>(uuid)` | function  | Creates a `BrandedId<Tag>` from an existing UUID string                                                                                      |
-| `brandedIdFromText<Tag>(text)` | function  | Creates a `BrandedId<Tag>` from a text string                                                                                                |
-| `IEntityId<T>`                 | interface | Re-exported from `@vytches/ddd-contracts`                                                                                                    |
-| `IEntityIdFactory`             | interface | Re-exported from `@vytches/ddd-contracts`                                                                                                    |
-| `IdType`                       | type      | Re-exported from `@vytches/ddd-contracts` — `'uuid' \| 'integer' \| 'text'`                                                                  |
+| Export                         | Kind      | Description                                                                                                                                                                                                                                           |
+| ------------------------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BaseValueObject<T>`           | class     | Abstract base for value objects; deep-freezes internal value; implements `equals()` via structural comparison, with an opt-in [`getIdentityComponents()`](#partial-identity-equality-with-getidentitycomponents) hook for partial-identity comparison |
+| `ValueObjectValidator<T>`      | interface | `validate(value: T): boolean` — implement to add invariant checking                                                                                                                                                                                   |
+| `EntityId<T>`                  | class     | Enhanced entity identifier extending the contracts `EntityId`; adds UUID/integer/text validation, `create()`, `fromString()`, `fromNumber()`                                                                                                          |
+| `EntityIdFactory`              | class     | **Deprecated** — will be removed in v1.0.0; use `EntityId.create()` directly                                                                                                                                                                          |
+| `BrandedId<Tag>`               | type      | Compile-time branded `EntityId<string>` — prevents mixing IDs across aggregate types                                                                                                                                                                  |
+| `createBrandedId<Tag>(id)`     | function  | Casts an `EntityId` to `BrandedId<Tag>`                                                                                                                                                                                                               |
+| `newBrandedId<Tag>()`          | function  | Creates a new UUID-based `BrandedId<Tag>`                                                                                                                                                                                                             |
+| `brandedIdFromUUID<Tag>(uuid)` | function  | Creates a `BrandedId<Tag>` from an existing UUID string                                                                                                                                                                                               |
+| `brandedIdFromText<Tag>(text)` | function  | Creates a `BrandedId<Tag>` from a text string                                                                                                                                                                                                         |
+| `IEntityId<T>`                 | interface | Re-exported from `@vytches/ddd-contracts`                                                                                                                                                                                                             |
+| `IEntityIdFactory`             | interface | Re-exported from `@vytches/ddd-contracts`                                                                                                                                                                                                             |
+| `IdType`                       | type      | Re-exported from `@vytches/ddd-contracts` — `'uuid' \| 'integer' \| 'text'`                                                                                                                                                                           |
 
 ## Note on bundled domain examples
 
@@ -121,6 +121,212 @@ shipOrder(orderId); // OK
 shipOrder(customerId); // TypeScript compile error!
 ```
 
+## Partial-identity equality with `getIdentityComponents()`
+
+_Since VF-036 — additive minor, see [`CHANGELOG.md`](./CHANGELOG.md)._
+
+By default, `equals()` compares the **entire** stored value: `===` for
+primitives, `LibUtils.deepEqual` for objects. Override the protected
+`getIdentityComponents()` hook when only a subset of a value object's state
+should participate in equality — for example, a `Money` value object that
+carries a display-formatting flag that must not affect equality, or a value
+object that should compare a derived/normalized projection of its state rather
+than the raw stored shape.
+
+```ts compile-check
+import { BaseValueObject } from '@vytches/ddd-value-objects';
+
+interface MoneyProps {
+  amount: number;
+  currency: string;
+  displayFormat: 'symbol' | 'code';
+}
+
+class Money extends BaseValueObject<MoneyProps> {
+  constructor(props: MoneyProps) {
+    super(props);
+  }
+
+  validate(value: MoneyProps): boolean {
+    return (
+      typeof value === 'object' &&
+      value !== null &&
+      value.amount >= 0 &&
+      value.currency.length === 3
+    );
+  }
+
+  // 'Money' is a type-scoped discriminator (see below); displayFormat is
+  // intentionally excluded from identity.
+  protected override getIdentityComponents(): readonly unknown[] {
+    return ['Money', this.value.amount, this.value.currency];
+  }
+}
+
+const a = new Money({ amount: 10, currency: 'USD', displayFormat: 'symbol' });
+const b = new Money({ amount: 10, currency: 'USD', displayFormat: 'code' });
+
+a.equals(b); // true — displayFormat is not an identity component
+```
+
+### When to reach for this instead of full-value equality
+
+Use `getIdentityComponents()` when a value object's raw stored value carries
+fields that are _incidental_ to identity — audit metadata, cache keys,
+presentation flags — while the _value_ the domain actually cares about is
+narrower. If every field of `value` matters for equality, leave the hook
+unimplemented; the default `undefined` return keeps the unmodified raw
+comparison.
+
+### The asymmetric fallback — and why it breaks transitivity in mixed populations
+
+`equals()` calls `getIdentityComponents()` on **both** sides being compared.
+Component comparison only runs if **both** sides return a defined array; if
+**either** side returns `undefined`, `equals()` falls back to the unchanged raw
+comparison. This fallback is symmetric — `a.equals(b)` and `b.equals(a)` always
+agree, since both directions see the same two results — but it is deliberately
+**not transitive** once a raw-comparison instance and a component-override
+instance coexist in the same population:
+
+- `A` — no override, raw comparison.
+- `B` — component override, whose raw `value` happens to equal `A`'s.
+- `C` — component override, whose components match `B`'s.
+
+`A.equals(B)` can be `true` (raw fallback matches), `B.equals(C)` can be `true`
+(components match), yet `A.equals(C)` can be `false` (raw fallback, different
+`value`). This is an accepted, test-pinned limitation — it is not "fixed" with
+`instanceof`/type gating.
+
+**Collection-level consequence:** code such as `list.some(x => x.equals(y))` or
+de-duplication by `.equals()` implicitly assumes equality is an equivalence
+relation — reflexive, symmetric, and **transitive**. Mixing component-identity
+subclasses with raw-comparison subclasses of the same base type inside one
+collection breaks that assumption silently. Migrate a whole class hierarchy to
+`getIdentityComponents()` together, or not at all — see the root
+[`MIGRATION.md`](../../MIGRATION.md) for the atomic-codemod guidance.
+
+### The empty-array footgun
+
+Returning `[]` is **defined-and-empty**, not "opt out." Two value objects that
+both return `[]` are equal to each other regardless of what their `value` holds
+(same length — zero — so the element-wise comparison is vacuously true for
+both). To opt out of component comparison, return `undefined` (the base
+default); never return `[]` to mean "not applicable."
+
+### The fixed-arity rule
+
+A class must **always return the same number of components**, in the same order.
+Comparison starts with a length check, so a conditional push —
+`if (this.scope) parts.push(this.scope)` — makes two instances of the same class
+unequal purely because one had an optional field set. That reads as a data
+difference when it is actually an arity difference. Push a stable placeholder
+instead:
+
+```ts compile-check
+import { BaseValueObject } from '@vytches/ddd-value-objects';
+
+interface GrantProps {
+  tenant: string;
+  scope?: string;
+  key: string;
+}
+
+class GrantRef extends BaseValueObject<GrantProps> {
+  validate(value: GrantProps): boolean {
+    return typeof value === 'object' && value !== null;
+  }
+
+  protected override getIdentityComponents(): readonly unknown[] {
+    // Always three slots, whatever is populated. Never push conditionally.
+    return [this.value.tenant, this.value.scope ?? null, this.value.key];
+  }
+}
+```
+
+The same applies across a hierarchy: if a subclass adds a component, it has
+changed the arity of every comparison against its parent — a design decision to
+make deliberately rather than discover.
+
+### The "sometimes undefined" downgrade trap
+
+Only a **literal `undefined`/omitted return from the hook itself** triggers the
+raw-comparison fallback — a component _value_ inside a returned array being
+`undefined` (e.g. an unset optional field) does not; the array is still
+"defined" and comparison proceeds element-wise. The trap is the reverse case: a
+_conditional_ override — "return components once some field is set, otherwise
+return `undefined`" — will silently and intermittently downgrade the very same
+class to raw comparison across different instances or different points in an
+instance's lifecycle. Prefer an override that always returns an array once a
+class opts in.
+
+### Throw propagation — `equals()` is no longer total
+
+A `getIdentityComponents()` override that throws propagates straight out of
+`equals()`, uncaught. This is deliberate: `equals()` is a hot path, and this
+library's internal logger is diagnostics-only and not meant to intercept
+consumer logic (see the logging-removal note in the root `MIGRATION.md`), so
+silently swallowing the throw into a wrong-but-quiet `false`/`true` would hide a
+real bug in the override. Once a subclass overrides this hook with logic that
+can throw, `equals()` is no longer a total function for that subclass.
+
+### Components must come from frozen or readonly state
+
+The base constructor deep-freezes the `value` passed to `super()` — but it does
+**not** freeze any additional fields a subclass declares and assigns after
+`super(value)`; those remain ordinary mutable class fields unless the subclass
+itself keeps them readonly/frozen. Derive components only from state that cannot
+change after construction (the frozen `value`, or subclass fields the subclass
+itself keeps immutable). Deriving a component from mutable state breaks the
+invariant that a value object's equality is stable for its lifetime.
+
+### Type-scoped equality: the sanctioned idiom
+
+`getIdentityComponents()` performs no type or `instanceof` check — two different
+subclasses returning matching components are still considered equal, exactly as
+cross-subclass raw comparison behaves today. If equality should be scoped to a
+specific type, add a **string-literal discriminator** as the first component (as
+in the `Money` example above):
+
+```ts compile-check
+import { BaseValueObject } from '@vytches/ddd-value-objects';
+
+class OrderNumber extends BaseValueObject<string> {
+  validate(value: unknown): boolean {
+    return typeof value === 'string' && value.length > 0;
+  }
+
+  protected override getIdentityComponents(): readonly unknown[] {
+    return ['OrderNumber', this.value];
+  }
+}
+```
+
+Do **not** use `this.constructor.name` (unsafe under minification, which can
+rename classes inconsistently) and do **not** use the class object itself
+(unsafe across duplicate package copies — the same hazard `instanceof` has).
+
+### `toString()`/`toJSON()` stay value-based
+
+Overriding `getIdentityComponents()` does not change `toString()` or `toJSON()`
+— both continue to serialize the raw `value`, unfiltered. If your override
+narrows equality to a subset of fields, serialization may now surface
+information that equality ignores (or the reverse). Keeping any resulting
+equals/serialization desync coherent is the consumer's responsibility.
+
+> **A permanent note: `getEqualityComponents` was never real.** An early (2025)
+> documentation draft described a similarly-named `getEqualityComponents()`
+> hook. It was **never implemented** in any released version of this library —
+> every `equals()` call has always used the raw `value`-based comparison
+> described above. The name was removed from docs in a later accuracy pass, but
+> some consumers had already written overrides against it, which were (and
+> always had been) dead code. `getIdentityComponents()` is the real, supported
+> hook, under a deliberately different name. `getEqualityComponents` will
+> **not** be added as an alias, shim, or runtime-detected fallback — doing so
+> would silently activate every dormant consumer override on upgrade, which is
+> exactly the behavioral break this design avoids. If you are holding a dead
+> `getEqualityComponents` override, see the root
+> [`MIGRATION.md`](../../MIGRATION.md).
+
 ## Package boundaries
 
 `@vytches/ddd-value-objects` depends on:

package/dist/base-value-object.d.ts

@@ -1,12 +1,195 @@
 export interface ValueObjectValidator<T> {
     validate(value: T): boolean;
 }
+/**
+ * VF-036 (D3): module-private brand used to recognize "this is a
+ * `BaseValueObject`" without `instanceof`. `instanceof` breaks silently
+ * across duplicate package copies (e.g. a failed `pnpm dedupe`, or two
+ * versions of this library resolved by a bundler/monorepo tool) because
+ * each copy has its own distinct class reference. `Symbol.for` reads from
+ * the *global* symbol registry, so every copy of this module — regardless
+ * of which physical `node_modules` install produced it — resolves the same
+ * symbol and agrees on the brand. The symbol is intentionally not exported:
+ * consumers never need to reference it directly, only the boolean brand
+ * check performed internally by `componentEquals`.
+ */
+declare const VALUE_OBJECT_BRAND: unique symbol;
 export declare abstract class BaseValueObject<T> implements ValueObjectValidator<T> {
     protected readonly value: T;
+    /**
+     * VF-036 (D3): marks every instance with the module-private brand symbol
+     * so `componentEquals` can recognize nested value objects without
+     * `instanceof`. Declared as an instance property (not on the prototype)
+     * so `in` works uniformly regardless of how a subclass is constructed.
+     */
+    protected readonly [VALUE_OBJECT_BRAND] = true;
+    /**
+     * VF-023 (D-1, AC1, BREAKING): validates `value` via the polymorphic
+     * `validate()` hook and throws synchronously on failure. This replaces
+     * the previous convention where every subclass repeated
+     * `if (!this.validate(value)) throw ...` in its own constructor after
+     * `super(value)` — that boilerplate is now centralized here and enforced
+     * for ALL subclasses, including any that previously forgot it.
+     *
+     * MIGRATION NOTE (undefined-during-super() trap): `validate()` is called
+     * via prototype dispatch from *this* base constructor, i.e. before the
+     * subclass constructor body (and therefore any subclass field
+     * initializers declared after `super(value)`) has run. A `validate()`
+     * override that reads `this.someOtherField` set up elsewhere in the
+     * subclass constructor will see `undefined` for that field. Overrides
+     * must only depend on the `value` parameter passed in, not on
+     * subclass instance state. Existing subclasses that already call
+     * `this.validate(value)` redundantly after `super(value)` are
+     * unaffected — the base class throws first, before that redundant call
+     * is ever reached.
+     */
     constructor(value: T);
+    /**
+     * VF-036 (D1/D4): opt-in hook letting a subclass declare which fields
+     * make up its *identity*, so `equals()` compares those fields instead of
+     * the raw `value` this class stores. Ships under the name
+     * `getIdentityComponents` — an earlier, never-implemented name for a
+     * similar idea (`getEqualityComponents`) circulated in docs and MUST NOT
+     * be revived as an alias, shim, or runtime-detected fallback; it never
+     * existed in source and never will.
+     *
+     * ## When component identity beats full-value equality
+     * The default raw comparison (`this.value === valueObject.value`, then
+     * `LibUtils.deepEqual` for objects) treats the *entire* stored value as
+     * significant. Override this hook when only a subset of fields should
+     * participate — e.g. a `Money` VO whose `value` also carries a
+     * display-formatting flag that must not affect equality, or a VO that
+     * wants to compare by a derived/normalized projection of its state
+     * rather than the raw stored shape.
+     *
+     * ## The asymmetric fallback, and why it is not transitive
+     * The dispatch rule in `equals()` is: if BOTH sides return a defined
+     * array, compare components; if EITHER side returns `undefined`, run the
+     * completely unchanged raw comparison. This rule is symmetric (`a.equals(b)`
+     * and `b.equals(a)` agree, since both directions see the same two
+     * `getIdentityComponents()` results) but deliberately **not transitive**:
+     * given A (raw comparison, no override), B (component override, happens
+     * to have the same raw `value` as A), and C (component override, same
+     * components as B), `A.equals(B)` may be `true` (raw fallback matches),
+     * `B.equals(C)` may be `true` (components match), yet `A.equals(C)` can
+     * be `false` (raw fallback, different `value`). This is an accepted,
+     * documented, test-pinned limitation — do not "fix" it by adding
+     * type/instanceof gating; see D6. It matters most for collection code
+     * such as `list.some(x => x.equals(y))` or de-duplication by `.equals`:
+     * such code implicitly assumes an equivalence relation, and mixing
+     * component-identity subclasses with raw-comparison subclasses in the
+     * same collection breaks that assumption.
+     *
+     * ## The empty-array footgun
+     * Returning `[]` is **defined-and-empty**, not "opt out". An empty array
+     * means "this VO has no identity-relevant fields", so it is equal to
+     * every other VO whose `getIdentityComponents()` also returns `[]`
+     * (same length: zero, vacuously equal element-wise) — regardless of what
+     * their respective `value`s hold. To opt out, return `undefined` (the
+     * base default), not `[]`.
+     *
+     * ## The undefined-because-field-not-initialized trap
+     * `undefined` silently downgrades to the raw comparison. If an override
+     * reads a subclass field that has not been initialized yet (see the
+     * undefined-during-`super()` trap documented on the constructor) and
+     * that read produces `undefined` as a *component value* (not as the
+     * hook's own return value), the surrounding array is still "defined" —
+     * only a *literal* `undefined`/omitted return from the override itself
+     * triggers the fallback. Conversely, a conditional override that
+     * sometimes returns `undefined` (e.g. "only compare by components once
+     * some field is set") will silently and intermittently fall back to raw
+     * comparison for the same class — prefer always returning an array once
+     * a class opts in.
+     *
+     * ## Throw propagation
+     * A throwing override propagates out of `equals()` uncaught (D5).
+     * `equals()` is a hot path and this library's logger is
+     * diagnostics-only, so there is no try/catch here — catching would
+     * silently convert a loud consumer bug (e.g. a component accessor that
+     * dereferences something absent) into a wrong-but-quiet `false`/`true`
+     * answer. `equals()` stops being a total function for classes that
+     * override this hook with logic that can throw.
+     *
+     * ## Fixed arity
+     * A class must always return the same number of components on every
+     * call (do not vary the array length based on instance state). Two
+     * defined arrays of different lengths are treated as unequal without
+     * inspecting elements, so a class whose arity drifts will get
+     * inconsistent, order-of-comparison-dependent results.
+     *
+     * ## Components must come from frozen/readonly state
+     * The constructor deep-freezes the `value` passed to `super()`, but it
+     * does **not** freeze any additional fields a subclass declares and
+     * assigns after `super(value)` — those are ordinary mutable class
+     * fields unless the subclass itself makes them readonly/frozen.
+     * Components must be derived only from state that cannot change after
+     * construction (the frozen `value`, or subclass fields the subclass
+     * itself keeps immutable); deriving a component from mutable state
+     * breaks the invariant that a VO's equality is stable for its lifetime.
+     *
+     * ## Type-scoped equality: the sanctioned idiom
+     * This hook performs no type or `instanceof` check (D6) — cross-subclass
+     * equality behaves exactly as it does today, and two different
+     * subclasses returning matching components are considered equal. For
+     * consumers who want type-scoped equality, the sanctioned opt-in is a
+     * string literal as the first component (e.g. `['Money', this.amount,
+     * this.currency]`), NOT `this.constructor.name` (unsafe under
+     * minification, which can rename classes inconsistently) and NOT the
+     * class object itself (unsafe across duplicate package copies, the same
+     * hazard `instanceof` has — see the brand-symbol note above).
+     *
+     * ## toString()/toJSON() stay value-based
+     * Overriding this hook does not change `toString()` or `toJSON()` — both
+     * continue to reflect the raw `value`. If an override narrows equality
+     * to a subset of fields, `toString()`/`toJSON()` may now serialize
+     * information that equality ignores (or vice versa); keeping any
+     * resulting equals/hash/serialization desync coherent is the
+     * consumer's responsibility.
+     *
+     * @returns `undefined` (the base default) to opt out and keep the raw
+     *   `value`-based comparison; a readonly array of identity-relevant
+     *   values to opt in to component-wise comparison.
+     */
+    protected getIdentityComponents(): readonly unknown[] | undefined;
     /**
      * Compares this value object with another for equality.
-     * Uses deep structural comparison for object values, === for primitives.
+     *
+     * VF-036 (D1/D2): first consults `getIdentityComponents()` on both
+     * sides. If BOTH return a defined array, equality is decided by that
+     * array alone: same length, then element-wise via `componentEquals`
+     * (which itself dispatches to nested `.equals()` for branded value
+     * objects, `LibUtils.deepEqual` otherwise). If EITHER side returns
+     * `undefined`, this method falls through to the exact, unmodified raw
+     * comparison that existed before VF-036 — see the block below and the
+     * `getIdentityComponents` doc comment for the full rationale, including
+     * why this fallback is symmetric but not transitive.
+     *
+     * The hook is consulted for primitive `T` as well as object `T`; nothing
+     * about this dispatch depends on `typeof this.value`.
+     *
+     * HARD CONSTRAINT: there is intentionally no unconditional
+     * `this === valueObject` shortcut at the top of this method — the only
+     * reflexivity shortcut this class takes lives inside the raw-comparison
+     * branch below (`this.value === valueObject.value`, which briefly
+     * predates any `getIdentityComponents` check on that branch only because
+     * neither side opted in). When neither side returns components, the
+     * executed code path is bit-for-bit identical to the pre-VF-036
+     * behavior, which is what keeps this a non-breaking, additive minor
+     * release rather than a breaking major.
+     *
+     * Uses deep structural comparison for object values, === for primitives,
+     * in the fallback branch.
+     *
+     * VF-023 (D-3, AC2/AC3, BREAKING): deep comparison now uses
+     * `LibUtils.deepEqual` instead of `JSON.stringify` equality. This fixes
+     * false negatives/positives inherent to JSON-based comparison — key
+     * order sensitivity is gone (already true before, since JSON.stringify
+     * of plain objects is insertion-order, not truly key-order-independent
+     * in all engines), values like `undefined`, `Date`, `Map`, `Set`, and
+     * `NaN` inside nested structures now compare by actual value semantics
+     * instead of silently dropping (`undefined`) or losing type
+     * (`Date`/`Map`/`Set` stringify to structurally different, sometimes
+     * colliding, JSON shapes).
      * @param valueObject - The value object to compare with
      * @returns True if they are equal, false otherwise
      */
@@ -32,4 +215,20 @@ export declare abstract class BaseValueObject<T> implements ValueObjectValidator
      * @returns True if valid, false otherwise
      */
     abstract validate(value: unknown): boolean;
+    /**
+     * VF-023 (D-1 regression fix): produces the message used when the
+     * constructor's synchronous `validate()` call fails. Because the base
+     * constructor now throws BEFORE the subclass constructor body runs (see
+     * the class-level doc comment), a subclass can no longer rely on its own
+     * post-`super(value)` `throw new Error('...')` — that code is
+     * unreachable, since the base class has already thrown by the time
+     * control would return to the subclass. Override this hook instead to
+     * provide a validation-error message specific to the subclass. Only
+     * `value` (the parameter, not subclass instance state — see the
+     * undefined-during-super() trap note above) is safe to use here.
+     * @param value The value that failed validation
+     * @returns The message to use for the thrown `Error`
+     */
+    protected getInvalidValueMessage(value: T): string;
 }
+export {};

package/dist/id.value-object.d.ts

@@ -1,4 +1,4 @@
-import { EntityId as BaseEntityId, IEntityIdFactory, IdType } from '@vytches/ddd-contracts';
+import { EntityId as BaseEntityId, IdType } from '@vytches/ddd-contracts';
 import { Result } from '@vytches/ddd-utils';
 export declare class EntityId<T = string> extends BaseEntityId<T> {
     constructor(value: T, type: IdType);
@@ -55,52 +55,3 @@ export declare class EntityId<T = string> extends BaseEntityId<T> {
      */
     static tryFromText(value: string): Result<EntityId<string>, Error>;
 }
-/**
- * @deprecated Use EntityId static methods directly instead. This class will be removed in the next major version.
- * @example
- * ```typescript
- * // Before (deprecated):
- * const id = EntityIdFactory.createWithRandomUUID();
- *
- * // After (recommended):
- * const id = EntityId.create();
- * ```
- */
-export declare class EntityIdFactory implements IEntityIdFactory {
-    /**
-     * @deprecated Use EntityId.create() instead. Will be removed in v1.0.0.
-     */
-    static createWithRandomUUID(): EntityId<string>;
-    /**
-     * @deprecated Use EntityId.fromUUID() instead. Will be removed in v1.0.0.
-     * @throws {MissingValueError} if value is empty
-     * @throws {InvalidParameterError} if value is empty
-     */
-    static fromUUID(value: string): EntityId<string>;
-    /**
-     * @deprecated Use EntityId.fromInteger() instead. Will be removed in v1.0.0.
-     * @throws {InvalidParameterError} if value is empty
-     */
-    static fromInteger(value: number): EntityId<string>;
-    /**
-     * @deprecated Use EntityId.fromBigInt() instead. Will be removed in v1.0.0.
-     * @throws {InvalidParameterError} if value is empty
-     */
-    static fromBigInt(value: string | bigint): EntityId<string>;
-    /**
-     * @deprecated Use EntityId.fromText() instead. Will be removed in v1.0.0.
-     * @throws {MissingValueError} if value is empty
-     * @throws {InvalidParameterError} if value is empty
-     */
-    static fromText(value: string): EntityId<string>;
-    /** @deprecated Use EntityId.create() instead */
-    createWithRandomUUID(): EntityId<string>;
-    /** @deprecated Use EntityId.fromUUID() instead */
-    fromUUID(value: string): EntityId<string>;
-    /** @deprecated Use EntityId.fromInteger() instead */
-    fromInteger(value: number): EntityId<string>;
-    /** @deprecated Use EntityId.fromBigInt() instead */
-    fromBigInt(value: string | bigint): EntityId<string>;
-    /** @deprecated Use EntityId.fromText() instead */
-    fromText(value: string): EntityId<string>;
-}

package/dist/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const l=require("@vytches/ddd-contracts"),r=require("@vytches/ddd-domain-primitives"),e=require("@vytches/ddd-utils");class u{constructor(t){t!==null&&typeof t=="object"?this.value=Object.freeze(t):this.value=t}equals(t){return t?this.value===t.value?!0:typeof this.value=="object"&&this.value!==null?JSON.stringify(this.value)===JSON.stringify(t.value):!1:!1}toString(){return String(this.value)}toJSON(){return this.value}getValue(){return this.value}}const d=new Set;function o(n,t){d.has(n)||(d.add(n),console.warn(`[@vytches/ddd-value-objects] EntityIdFactory.${n}() is deprecated and will be removed in v1.0.0. Use ${t} instead. See https://github.com/vytches/ddd/blob/main/CHANGELOG.md for migration details.`))}class i extends l.EntityId{constructor(t,a){super(t,a)}validate(t){switch(this.getType()){case"uuid":return e.LibUtils.isValidUUID(t);case"integer":return e.LibUtils.isValidInteger(t);case"bigint":return e.LibUtils.isValidBigInt(t);case"text":return e.LibUtils.isValidTextId(t);default:throw new r.InvalidParameterError(`Unsupported IdType: ${this.getType()}`)}}static create(){return new i(e.LibUtils.getUUID(),"uuid")}static createWithRandomUUID(){return i.create()}static fromUUID(t){if(!e.LibUtils.hasValue(t))throw r.MissingValueError.withValue("entity identifier");if(!e.LibUtils.isValidUUID(t))throw r.InvalidParameterError.withParameter("entity identifier");return new i(t,"uuid")}static fromInteger(t){if(!e.LibUtils.isValidInteger(t))throw r.InvalidParameterError.withParameter("entity identifier must be a non-negative integer");return new i(t.toString(),"integer")}static fromBigInt(t){const a=e.LibUtils.normalizeIdToString(t);if(!e.LibUtils.isValidBigInt(a))throw r.InvalidParameterError.withParameter("entity identifier must be a valid bigint");return new i(a,"bigint")}static fromText(t){if(!e.LibUtils.hasValue(t))throw r.MissingValueError.withValue("entity identifier");if(!e.LibUtils.isValidTextId(t))throw r.InvalidParameterError.withParameter("entity identifier contains invalid characters");return new i(t,"text")}static tryFromUUID(t){return e.LibUtils.hasValue(t)?e.LibUtils.isValidUUID(t)?e.Result.ok(new i(t,"uuid")):e.Result.fail(r.InvalidParameterError.withParameter("entity identifier")):e.Result.fail(r.MissingValueError.withValue("entity identifier"))}static tryFromInteger(t){return e.LibUtils.isValidInteger(t)?e.Result.ok(new i(t.toString(),"integer")):e.Result.fail(r.InvalidParameterError.withParameter("entity identifier must be a non-negative integer"))}static tryFromBigInt(t){const a=e.LibUtils.normalizeIdToString(t);return e.LibUtils.isValidBigInt(a)?e.Result.ok(new i(a,"bigint")):e.Result.fail(r.InvalidParameterError.withParameter("entity identifier must be a valid bigint"))}static tryFromText(t){return e.LibUtils.hasValue(t)?e.LibUtils.isValidTextId(t)?e.Result.ok(new i(t,"text")):e.Result.fail(r.InvalidParameterError.withParameter("entity identifier contains invalid characters")):e.Result.fail(r.MissingValueError.withValue("entity identifier"))}}class s{static createWithRandomUUID(){return o("createWithRandomUUID","EntityId.create()"),i.create()}static fromUUID(t){if(o("fromUUID","EntityId.fromUUID()"),!e.LibUtils.hasValue(t))throw r.MissingValueError.withValue("entity identifier");if(!e.LibUtils.isValidUUID(t))throw r.InvalidParameterError.withParameter("entity identifier");return new i(t,"uuid")}static fromInteger(t){if(o("fromInteger","EntityId.fromInteger()"),!e.LibUtils.isValidInteger(t))throw r.InvalidParameterError.withParameter("entity identifier must be a non-negative integer");return new i(t.toString(),"integer")}static fromBigInt(t){o("fromBigInt","EntityId.fromBigInt()");const a=e.LibUtils.normalizeIdToString(t);if(!e.LibUtils.isValidBigInt(a))throw r.InvalidParameterError.withParameter("entity identifier must be a valid bigint");return new i(a,"bigint")}static fromText(t){if(o("fromText","EntityId.fromText()"),!e.LibUtils.hasValue(t))throw r.MissingValueError.withValue("entity identifier");if(!e.LibUtils.isValidTextId(t))throw r.InvalidParameterError.withParameter("entity identifier contains invalid characters");return new i(t,"text")}createWithRandomUUID(){return i.create()}fromUUID(t){return s.fromUUID(t)}fromInteger(t){return s.fromInteger(t)}fromBigInt(t){return s.fromBigInt(t)}fromText(t){return s.fromText(t)}}function f(n){return n}function m(){return i.create()}function c(n){return i.fromUUID(n)}function I(n){return i.fromText(n)}exports.BaseValueObject=u;exports.EntityId=i;exports.EntityIdFactory=s;exports.brandedIdFromText=I;exports.brandedIdFromUUID=c;exports.createBrandedId=f;exports.newBrandedId=m;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("@vytches/ddd-utils"),d=require("@vytches/ddd-contracts"),r=require("@vytches/ddd-domain-primitives");var u;const o=Symbol.for("@vytches/ddd.valueObject");function f(n,t){return typeof n=="object"&&n!==null&&o in n&&typeof t=="object"&&t!==null&&o in t?n.equals(t):e.LibUtils.deepEqual(n,t,new WeakMap)}u=o;class c{constructor(t){if(this[u]=!0,this.value=t!==null&&typeof t=="object"?e.LibUtils.deepFreeze(t):t,!this.validate(this.value))throw new Error(this.getInvalidValueMessage(this.value))}getIdentityComponents(){}equals(t){if(!t)return!1;const a=this.getIdentityComponents(),l=t.getIdentityComponents();if(a!==void 0&&l!==void 0){if(a.length!==l.length)return!1;for(let s=0;s<a.length;s++)if(!f(a[s],l[s]))return!1;return!0}return this.value===t.value?!0:typeof this.value=="object"&&this.value!==null?e.LibUtils.deepEqual(this.value,t.value):!1}toString(){return String(this.value)}toJSON(){return this.value}getValue(){return this.value}getInvalidValueMessage(t){return`Invalid value for ${this.constructor.name}`}}class i extends d.EntityId{constructor(t,a){super(t,a)}validate(t){switch(this.getType()){case"uuid":return e.LibUtils.isValidUUID(t);case"integer":return e.LibUtils.isValidInteger(t);case"bigint":return e.LibUtils.isValidBigInt(t);case"text":return e.LibUtils.isValidTextId(t);default:throw new r.InvalidParameterError(`Unsupported IdType: ${this.getType()}`)}}static create(){return new i(e.LibUtils.getUUID(),"uuid")}static createWithRandomUUID(){return i.create()}static fromUUID(t){if(!e.LibUtils.hasValue(t))throw r.MissingValueError.withValue("entity identifier");if(!e.LibUtils.isValidUUID(t))throw r.InvalidParameterError.withParameter("entity identifier");return new i(t,"uuid")}static fromInteger(t){if(!e.LibUtils.isValidInteger(t))throw r.InvalidParameterError.withParameter("entity identifier must be a non-negative integer");return new i(t.toString(),"integer")}static fromBigInt(t){const a=e.LibUtils.normalizeIdToString(t);if(!e.LibUtils.isValidBigInt(a))throw r.InvalidParameterError.withParameter("entity identifier must be a valid bigint");return new i(a,"bigint")}static fromText(t){if(!e.LibUtils.hasValue(t))throw r.MissingValueError.withValue("entity identifier");if(!e.LibUtils.isValidTextId(t))throw r.InvalidParameterError.withParameter("entity identifier contains invalid characters");return new i(t,"text")}static tryFromUUID(t){return e.LibUtils.hasValue(t)?e.LibUtils.isValidUUID(t)?e.Result.ok(new i(t,"uuid")):e.Result.fail(r.InvalidParameterError.withParameter("entity identifier")):e.Result.fail(r.MissingValueError.withValue("entity identifier"))}static tryFromInteger(t){return e.LibUtils.isValidInteger(t)?e.Result.ok(new i(t.toString(),"integer")):e.Result.fail(r.InvalidParameterError.withParameter("entity identifier must be a non-negative integer"))}static tryFromBigInt(t){const a=e.LibUtils.normalizeIdToString(t);return e.LibUtils.isValidBigInt(a)?e.Result.ok(new i(a,"bigint")):e.Result.fail(r.InvalidParameterError.withParameter("entity identifier must be a valid bigint"))}static tryFromText(t){return e.LibUtils.hasValue(t)?e.LibUtils.isValidTextId(t)?e.Result.ok(new i(t,"text")):e.Result.fail(r.InvalidParameterError.withParameter("entity identifier contains invalid characters")):e.Result.fail(r.MissingValueError.withValue("entity identifier"))}}function g(n){return n}function h(){return i.create()}function m(n){return i.fromUUID(n)}function U(n){return i.fromText(n)}exports.BaseValueObject=c;exports.EntityId=i;exports.brandedIdFromText=U;exports.brandedIdFromUUID=m;exports.createBrandedId=g;exports.newBrandedId=h;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { BaseValueObject, type ValueObjectValidator } from './base-value-object';
-export { EntityId, EntityIdFactory } from './id.value-object';
+export { EntityId } from './id.value-object';
 export type { BrandedId } from './branded-id';
 export { createBrandedId, newBrandedId, brandedIdFromUUID, brandedIdFromText } from './branded-id';
 export type { IEntityId, IEntityIdFactory, IdType } from '@vytches/ddd-contracts';

package/dist/index.js

@@ -1,18 +1,202 @@
-import { EntityId as m } from "@vytches/ddd-contracts";
-import { InvalidParameterError as r, MissingValueError as o } from "@vytches/ddd-domain-primitives";
-import { LibUtils as e, Result as s } from "@vytches/ddd-utils";
-class l {
+import { LibUtils as e, Result as a } from "@vytches/ddd-utils";
+import { EntityId as h } from "@vytches/ddd-contracts";
+import { InvalidParameterError as s, MissingValueError as u } from "@vytches/ddd-domain-primitives";
+var f;
+const d = Symbol.for("@vytches/ddd.valueObject");
+function c(r, t) {
+  return typeof r == "object" && r !== null && d in r && typeof t == "object" && t !== null && d in t ? r.equals(
+    t
+  ) : e.deepEqual(r, t, /* @__PURE__ */ new WeakMap());
+}
+f = d;
+class I {
+  /**
+   * VF-023 (D-1, AC1, BREAKING): validates `value` via the polymorphic
+   * `validate()` hook and throws synchronously on failure. This replaces
+   * the previous convention where every subclass repeated
+   * `if (!this.validate(value)) throw ...` in its own constructor after
+   * `super(value)` — that boilerplate is now centralized here and enforced
+   * for ALL subclasses, including any that previously forgot it.
+   *
+   * MIGRATION NOTE (undefined-during-super() trap): `validate()` is called
+   * via prototype dispatch from *this* base constructor, i.e. before the
+   * subclass constructor body (and therefore any subclass field
+   * initializers declared after `super(value)`) has run. A `validate()`
+   * override that reads `this.someOtherField` set up elsewhere in the
+   * subclass constructor will see `undefined` for that field. Overrides
+   * must only depend on the `value` parameter passed in, not on
+   * subclass instance state. Existing subclasses that already call
+   * `this.validate(value)` redundantly after `super(value)` are
+   * unaffected — the base class throws first, before that redundant call
+   * is ever reached.
+   */
   constructor(t) {
-    t !== null && typeof t == "object" ? this.value = Object.freeze(t) : this.value = t;
+    if (this[f] = !0, this.value = t !== null && typeof t == "object" ? e.deepFreeze(t) : t, !this.validate(this.value))
+      throw new Error(this.getInvalidValueMessage(this.value));
+  }
+  /**
+   * VF-036 (D1/D4): opt-in hook letting a subclass declare which fields
+   * make up its *identity*, so `equals()` compares those fields instead of
+   * the raw `value` this class stores. Ships under the name
+   * `getIdentityComponents` — an earlier, never-implemented name for a
+   * similar idea (`getEqualityComponents`) circulated in docs and MUST NOT
+   * be revived as an alias, shim, or runtime-detected fallback; it never
+   * existed in source and never will.
+   *
+   * ## When component identity beats full-value equality
+   * The default raw comparison (`this.value === valueObject.value`, then
+   * `LibUtils.deepEqual` for objects) treats the *entire* stored value as
+   * significant. Override this hook when only a subset of fields should
+   * participate — e.g. a `Money` VO whose `value` also carries a
+   * display-formatting flag that must not affect equality, or a VO that
+   * wants to compare by a derived/normalized projection of its state
+   * rather than the raw stored shape.
+   *
+   * ## The asymmetric fallback, and why it is not transitive
+   * The dispatch rule in `equals()` is: if BOTH sides return a defined
+   * array, compare components; if EITHER side returns `undefined`, run the
+   * completely unchanged raw comparison. This rule is symmetric (`a.equals(b)`
+   * and `b.equals(a)` agree, since both directions see the same two
+   * `getIdentityComponents()` results) but deliberately **not transitive**:
+   * given A (raw comparison, no override), B (component override, happens
+   * to have the same raw `value` as A), and C (component override, same
+   * components as B), `A.equals(B)` may be `true` (raw fallback matches),
+   * `B.equals(C)` may be `true` (components match), yet `A.equals(C)` can
+   * be `false` (raw fallback, different `value`). This is an accepted,
+   * documented, test-pinned limitation — do not "fix" it by adding
+   * type/instanceof gating; see D6. It matters most for collection code
+   * such as `list.some(x => x.equals(y))` or de-duplication by `.equals`:
+   * such code implicitly assumes an equivalence relation, and mixing
+   * component-identity subclasses with raw-comparison subclasses in the
+   * same collection breaks that assumption.
+   *
+   * ## The empty-array footgun
+   * Returning `[]` is **defined-and-empty**, not "opt out". An empty array
+   * means "this VO has no identity-relevant fields", so it is equal to
+   * every other VO whose `getIdentityComponents()` also returns `[]`
+   * (same length: zero, vacuously equal element-wise) — regardless of what
+   * their respective `value`s hold. To opt out, return `undefined` (the
+   * base default), not `[]`.
+   *
+   * ## The undefined-because-field-not-initialized trap
+   * `undefined` silently downgrades to the raw comparison. If an override
+   * reads a subclass field that has not been initialized yet (see the
+   * undefined-during-`super()` trap documented on the constructor) and
+   * that read produces `undefined` as a *component value* (not as the
+   * hook's own return value), the surrounding array is still "defined" —
+   * only a *literal* `undefined`/omitted return from the override itself
+   * triggers the fallback. Conversely, a conditional override that
+   * sometimes returns `undefined` (e.g. "only compare by components once
+   * some field is set") will silently and intermittently fall back to raw
+   * comparison for the same class — prefer always returning an array once
+   * a class opts in.
+   *
+   * ## Throw propagation
+   * A throwing override propagates out of `equals()` uncaught (D5).
+   * `equals()` is a hot path and this library's logger is
+   * diagnostics-only, so there is no try/catch here — catching would
+   * silently convert a loud consumer bug (e.g. a component accessor that
+   * dereferences something absent) into a wrong-but-quiet `false`/`true`
+   * answer. `equals()` stops being a total function for classes that
+   * override this hook with logic that can throw.
+   *
+   * ## Fixed arity
+   * A class must always return the same number of components on every
+   * call (do not vary the array length based on instance state). Two
+   * defined arrays of different lengths are treated as unequal without
+   * inspecting elements, so a class whose arity drifts will get
+   * inconsistent, order-of-comparison-dependent results.
+   *
+   * ## Components must come from frozen/readonly state
+   * The constructor deep-freezes the `value` passed to `super()`, but it
+   * does **not** freeze any additional fields a subclass declares and
+   * assigns after `super(value)` — those are ordinary mutable class
+   * fields unless the subclass itself makes them readonly/frozen.
+   * Components must be derived only from state that cannot change after
+   * construction (the frozen `value`, or subclass fields the subclass
+   * itself keeps immutable); deriving a component from mutable state
+   * breaks the invariant that a VO's equality is stable for its lifetime.
+   *
+   * ## Type-scoped equality: the sanctioned idiom
+   * This hook performs no type or `instanceof` check (D6) — cross-subclass
+   * equality behaves exactly as it does today, and two different
+   * subclasses returning matching components are considered equal. For
+   * consumers who want type-scoped equality, the sanctioned opt-in is a
+   * string literal as the first component (e.g. `['Money', this.amount,
+   * this.currency]`), NOT `this.constructor.name` (unsafe under
+   * minification, which can rename classes inconsistently) and NOT the
+   * class object itself (unsafe across duplicate package copies, the same
+   * hazard `instanceof` has — see the brand-symbol note above).
+   *
+   * ## toString()/toJSON() stay value-based
+   * Overriding this hook does not change `toString()` or `toJSON()` — both
+   * continue to reflect the raw `value`. If an override narrows equality
+   * to a subset of fields, `toString()`/`toJSON()` may now serialize
+   * information that equality ignores (or vice versa); keeping any
+   * resulting equals/hash/serialization desync coherent is the
+   * consumer's responsibility.
+   *
+   * @returns `undefined` (the base default) to opt out and keep the raw
+   *   `value`-based comparison; a readonly array of identity-relevant
+   *   values to opt in to component-wise comparison.
+   */
+  getIdentityComponents() {
   }
   /**
    * Compares this value object with another for equality.
-   * Uses deep structural comparison for object values, === for primitives.
+   *
+   * VF-036 (D1/D2): first consults `getIdentityComponents()` on both
+   * sides. If BOTH return a defined array, equality is decided by that
+   * array alone: same length, then element-wise via `componentEquals`
+   * (which itself dispatches to nested `.equals()` for branded value
+   * objects, `LibUtils.deepEqual` otherwise). If EITHER side returns
+   * `undefined`, this method falls through to the exact, unmodified raw
+   * comparison that existed before VF-036 — see the block below and the
+   * `getIdentityComponents` doc comment for the full rationale, including
+   * why this fallback is symmetric but not transitive.
+   *
+   * The hook is consulted for primitive `T` as well as object `T`; nothing
+   * about this dispatch depends on `typeof this.value`.
+   *
+   * HARD CONSTRAINT: there is intentionally no unconditional
+   * `this === valueObject` shortcut at the top of this method — the only
+   * reflexivity shortcut this class takes lives inside the raw-comparison
+   * branch below (`this.value === valueObject.value`, which briefly
+   * predates any `getIdentityComponents` check on that branch only because
+   * neither side opted in). When neither side returns components, the
+   * executed code path is bit-for-bit identical to the pre-VF-036
+   * behavior, which is what keeps this a non-breaking, additive minor
+   * release rather than a breaking major.
+   *
+   * Uses deep structural comparison for object values, === for primitives,
+   * in the fallback branch.
+   *
+   * VF-023 (D-3, AC2/AC3, BREAKING): deep comparison now uses
+   * `LibUtils.deepEqual` instead of `JSON.stringify` equality. This fixes
+   * false negatives/positives inherent to JSON-based comparison — key
+   * order sensitivity is gone (already true before, since JSON.stringify
+   * of plain objects is insertion-order, not truly key-order-independent
+   * in all engines), values like `undefined`, `Date`, `Map`, `Set`, and
+   * `NaN` inside nested structures now compare by actual value semantics
+   * instead of silently dropping (`undefined`) or losing type
+   * (`Date`/`Map`/`Set` stringify to structurally different, sometimes
+   * colliding, JSON shapes).
    * @param valueObject - The value object to compare with
    * @returns True if they are equal, false otherwise
    */
   equals(t) {
-    return t ? this.value === t.value ? !0 : typeof this.value == "object" && this.value !== null ? JSON.stringify(this.value) === JSON.stringify(t.value) : !1 : !1;
+    if (!t)
+      return !1;
+    const n = this.getIdentityComponents(), l = t.getIdentityComponents();
+    if (n !== void 0 && l !== void 0) {
+      if (n.length !== l.length)
+        return !1;
+      for (let o = 0; o < n.length; o++)
+        if (!c(n[o], l[o]))
+          return !1;
+      return !0;
+    }
+    return this.value === t.value ? !0 : typeof this.value == "object" && this.value !== null ? e.deepEqual(this.value, t.value) : !1;
   }
   /**
    * Returns a string representation of the value object
@@ -35,16 +219,27 @@ class l {
   getValue() {
     return this.value;
   }
+  /**
+   * VF-023 (D-1 regression fix): produces the message used when the
+   * constructor's synchronous `validate()` call fails. Because the base
+   * constructor now throws BEFORE the subclass constructor body runs (see
+   * the class-level doc comment), a subclass can no longer rely on its own
+   * post-`super(value)` `throw new Error('...')` — that code is
+   * unreachable, since the base class has already thrown by the time
+   * control would return to the subclass. Override this hook instead to
+   * provide a validation-error message specific to the subclass. Only
+   * `value` (the parameter, not subclass instance state — see the
+   * undefined-during-super() trap note above) is safe to use here.
+   * @param value The value that failed validation
+   * @returns The message to use for the thrown `Error`
+   */
+  getInvalidValueMessage(t) {
+    return `Invalid value for ${this.constructor.name}`;
+  }
 }
-const u = /* @__PURE__ */ new Set();
-function f(n, t) {
-  u.has(n) || (u.add(n), console.warn(
-    `[@vytches/ddd-value-objects] EntityIdFactory.${n}() is deprecated and will be removed in v1.0.0. Use ${t} instead. See https://github.com/vytches/ddd/blob/main/CHANGELOG.md for migration details.`
-  ));
-}
-class i extends m {
-  constructor(t, a) {
-    super(t, a);
+class i extends h {
+  constructor(t, n) {
+    super(t, n);
   }
   validate(t) {
     switch (this.getType()) {
@@ -57,7 +252,7 @@ class i extends m {
       case "text":
         return e.isValidTextId(t);
       default:
-        throw new r(`Unsupported IdType: ${this.getType()}`);
+        throw new s(`Unsupported IdType: ${this.getType()}`);
     }
   }
   /**
@@ -85,27 +280,27 @@ class i extends m {
    */
   static fromUUID(t) {
     if (!e.hasValue(t))
-      throw o.withValue("entity identifier");
+      throw u.withValue("entity identifier");
     if (!e.isValidUUID(t))
-      throw r.withParameter("entity identifier");
+      throw s.withParameter("entity identifier");
     return new i(t, "uuid");
   }
   static fromInteger(t) {
     if (!e.isValidInteger(t))
-      throw r.withParameter("entity identifier must be a non-negative integer");
+      throw s.withParameter("entity identifier must be a non-negative integer");
     return new i(t.toString(), "integer");
   }
   static fromBigInt(t) {
-    const a = e.normalizeIdToString(t);
-    if (!e.isValidBigInt(a))
-      throw r.withParameter("entity identifier must be a valid bigint");
-    return new i(a, "bigint");
+    const n = e.normalizeIdToString(t);
+    if (!e.isValidBigInt(n))
+      throw s.withParameter("entity identifier must be a valid bigint");
+    return new i(n, "bigint");
   }
   static fromText(t) {
     if (!e.hasValue(t))
-      throw o.withValue("entity identifier");
+      throw u.withValue("entity identifier");
     if (!e.isValidTextId(t))
-      throw r.withParameter("entity identifier contains invalid characters");
+      throw s.withParameter("entity identifier contains invalid characters");
     return new i(t, "text");
   }
   // --- Result-returning factory methods (non-throwing) ---
@@ -116,7 +311,7 @@ class i extends m {
    * @since 0.24.0
    */
   static tryFromUUID(t) {
-    return e.hasValue(t) ? e.isValidUUID(t) ? s.ok(new i(t, "uuid")) : s.fail(r.withParameter("entity identifier")) : s.fail(o.withValue("entity identifier"));
+    return e.hasValue(t) ? e.isValidUUID(t) ? a.ok(new i(t, "uuid")) : a.fail(s.withParameter("entity identifier")) : a.fail(u.withValue("entity identifier"));
   }
   /**
    * Create EntityId from integer, returning Result instead of throwing.
@@ -125,8 +320,8 @@ class i extends m {
    * @since 0.24.0
    */
   static tryFromInteger(t) {
-    return e.isValidInteger(t) ? s.ok(new i(t.toString(), "integer")) : s.fail(
-      r.withParameter("entity identifier must be a non-negative integer")
+    return e.isValidInteger(t) ? a.ok(new i(t.toString(), "integer")) : a.fail(
+      s.withParameter("entity identifier must be a non-negative integer")
     );
   }
   /**
@@ -136,9 +331,9 @@ class i extends m {
    * @since 0.24.0
    */
   static tryFromBigInt(t) {
-    const a = e.normalizeIdToString(t);
-    return e.isValidBigInt(a) ? s.ok(new i(a, "bigint")) : s.fail(
-      r.withParameter("entity identifier must be a valid bigint")
+    const n = e.normalizeIdToString(t);
+    return e.isValidBigInt(n) ? a.ok(new i(n, "bigint")) : a.fail(
+      s.withParameter("entity identifier must be a valid bigint")
     );
   }
   /**
@@ -148,101 +343,28 @@ class i extends m {
    * @since 0.24.0
    */
   static tryFromText(t) {
-    return e.hasValue(t) ? e.isValidTextId(t) ? s.ok(new i(t, "text")) : s.fail(
-      r.withParameter("entity identifier contains invalid characters")
-    ) : s.fail(o.withValue("entity identifier"));
-  }
-}
-class d {
-  /**
-   * @deprecated Use EntityId.create() instead. Will be removed in v1.0.0.
-   */
-  static createWithRandomUUID() {
-    return f("createWithRandomUUID", "EntityId.create()"), i.create();
-  }
-  /**
-   * @deprecated Use EntityId.fromUUID() instead. Will be removed in v1.0.0.
-   * @throws {MissingValueError} if value is empty
-   * @throws {InvalidParameterError} if value is empty
-   */
-  static fromUUID(t) {
-    if (f("fromUUID", "EntityId.fromUUID()"), !e.hasValue(t))
-      throw o.withValue("entity identifier");
-    if (!e.isValidUUID(t))
-      throw r.withParameter("entity identifier");
-    return new i(t, "uuid");
-  }
-  /**
-   * @deprecated Use EntityId.fromInteger() instead. Will be removed in v1.0.0.
-   * @throws {InvalidParameterError} if value is empty
-   */
-  static fromInteger(t) {
-    if (f("fromInteger", "EntityId.fromInteger()"), !e.isValidInteger(t))
-      throw r.withParameter("entity identifier must be a non-negative integer");
-    return new i(t.toString(), "integer");
-  }
-  /**
-   * @deprecated Use EntityId.fromBigInt() instead. Will be removed in v1.0.0.
-   * @throws {InvalidParameterError} if value is empty
-   */
-  static fromBigInt(t) {
-    f("fromBigInt", "EntityId.fromBigInt()");
-    const a = e.normalizeIdToString(t);
-    if (!e.isValidBigInt(a))
-      throw r.withParameter("entity identifier must be a valid bigint");
-    return new i(a, "bigint");
-  }
-  /**
-   * @deprecated Use EntityId.fromText() instead. Will be removed in v1.0.0.
-   * @throws {MissingValueError} if value is empty
-   * @throws {InvalidParameterError} if value is empty
-   */
-  static fromText(t) {
-    if (f("fromText", "EntityId.fromText()"), !e.hasValue(t))
-      throw o.withValue("entity identifier");
-    if (!e.isValidTextId(t))
-      throw r.withParameter("entity identifier contains invalid characters");
-    return new i(t, "text");
-  }
-  /** @deprecated Use EntityId.create() instead */
-  createWithRandomUUID() {
-    return i.create();
-  }
-  /** @deprecated Use EntityId.fromUUID() instead */
-  fromUUID(t) {
-    return d.fromUUID(t);
-  }
-  /** @deprecated Use EntityId.fromInteger() instead */
-  fromInteger(t) {
-    return d.fromInteger(t);
-  }
-  /** @deprecated Use EntityId.fromBigInt() instead */
-  fromBigInt(t) {
-    return d.fromBigInt(t);
-  }
-  /** @deprecated Use EntityId.fromText() instead */
-  fromText(t) {
-    return d.fromText(t);
+    return e.hasValue(t) ? e.isValidTextId(t) ? a.ok(new i(t, "text")) : a.fail(
+      s.withParameter("entity identifier contains invalid characters")
+    ) : a.fail(u.withValue("entity identifier"));
   }
 }
-function w(n) {
-  return n;
+function V(r) {
+  return r;
 }
-function I() {
+function p() {
   return i.create();
 }
-function U(n) {
-  return i.fromUUID(n);
+function y(r) {
+  return i.fromUUID(r);
 }
-function V(n) {
-  return i.fromText(n);
+function U(r) {
+  return i.fromText(r);
 }
 export {
-  l as BaseValueObject,
+  I as BaseValueObject,
   i as EntityId,
-  d as EntityIdFactory,
-  V as brandedIdFromText,
-  U as brandedIdFromUUID,
-  w as createBrandedId,
-  I as newBrandedId
+  U as brandedIdFromText,
+  y as brandedIdFromUUID,
+  V as createBrandedId,
+  p as newBrandedId
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vytches/ddd-value-objects",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "Enhanced value objects and EntityId implementations",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -17,7 +17,8 @@
   "files": [
     "dist",
     "README.md",
-    "LLMGUIDE.md"
+    "LLMGUIDE.md",
+    "LICENSE"
   ],
   "keywords": [
     "ddd",
@@ -33,15 +34,15 @@
     "directory": "packages/value-objects"
   },
   "dependencies": {
-    "@vytches/ddd-contracts": "0.30.0",
-    "@vytches/ddd-domain-primitives": "0.30.0",
-    "@vytches/ddd-utils": "0.30.0"
+    "@vytches/ddd-contracts": "0.31.0",
+    "@vytches/ddd-utils": "0.31.0",
+    "@vytches/ddd-domain-primitives": "0.31.0"
   },
   "devDependencies": {
     "typescript": "^5.0.0",
     "vite": "^7.3.2",
     "vite-plugin-dts": "^4.0.0",
-    "vitest": "^4.0.0"
+    "vitest": "^4.1.0"
   },
   "nx": {
     "tags": [