@vytches/ddd-value-objects 0.31.0-alpha.0 → 0.31.1

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
 
@@ -224,6 +318,13 @@ cancelOrder(orderId); // OK
 Available factories: `createBrandedId<Tag>(entityId)`, `newBrandedId<Tag>()`,
 `brandedIdFromUUID<Tag>(uuid)`, `brandedIdFromText<Tag>(text)`.
 
+## Related Guides
+
+- [`docs/guides/specification-vs-policy.md`](../../docs/guides/specification-vs-policy.md)
+  — "where do I validate what" decision tree: when a rule belongs in a VO's
+  `validate()` constructor invariant vs `Specification` /
+  `BusinessRuleValidator` / `PolicyBuilder`.
+
 ## Package Dependencies
 
 **Depends on:** `@vytches/ddd-contracts`, `@vytches/ddd-domain-primitives`,

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,289 @@ shipOrder(orderId); // OK
 shipOrder(customerId); // TypeScript compile error!
 ```
 
+## Keeping a specific validation error with `getInvalidValueMessage()`
+
+_Since VF-023 — the constructor validates, see
+[`CHANGELOG.md`](./CHANGELOG.md)._
+
+`BaseValueObject`'s constructor calls `validate()` and throws on failure, before
+the subclass constructor body runs. `validate()` returns a boolean, so any value
+object whose real validation produces a _rich_ error — which field, which rule,
+which expected checksum — has to swallow that error to satisfy the signature.
+What reaches the caller is then the generic default:
+
+```
+Error: Invalid value for Regon
+```
+
+Override `getInvalidValueMessage()` to put the specific message back. It is
+called only on the failing path, so re-running the detailed validation there
+costs nothing in the happy case:
+
+```typescript
+export abstract class NationalIdentifier extends BaseValueObject<IdentifierProps> {
+  /** Throws a rich, typed error. Called by validate() and, on failure, here. */
+  protected abstract assertValid(value: string): void;
+
+  validate(props: IdentifierProps): boolean {
+    try {
+      this.assertValid(props.value);
+      return props.locale === this.expectedLocale;
+    } catch {
+      return false; // the detail is lost here — recovered below
+    }
+  }
+
+  protected override getInvalidValueMessage(props: IdentifierProps): string {
+    try {
+      this.assertValid(props.value);
+    } catch (error) {
+      // "REGON has invalid checksum: expected 5, got 6"
+      return error instanceof Error ? error.message : String(error);
+    }
+    return `${this.typeName} requires locale '${this.expectedLocale}', got '${props.locale}'`;
+  }
+}
+```
+
+Two constraints apply, both from the undefined-during-`super()` trap: the
+override may read only its `value` parameter and state the base constructor has
+already set (`this.value` is assigned before the throw), never a field
+initialized in the subclass constructor — that field is still `undefined` here.
+
+A `Result`-returning factory keeps the typed error by re-wrapping what the
+constructor threw:
+
+```typescript
+static create(value: string): Result<Regon, IdentifierValidationError> {
+  try {
+    return Result.ok(new Regon({ value, locale: 'pl-PL' }));
+  } catch (error) {
+    if (error instanceof IdentifierValidationError) return Result.fail(error);
+    // Generic Error from the base constructor — message already specific,
+    // thanks to getInvalidValueMessage() above.
+    return Result.fail(
+      new IdentifierValidationError(
+        error instanceof Error ? error.message : 'Unknown error',
+        'REGON'
+      )
+    );
+  }
+}
+```
+
+**Migration note.** Before VF-023 the common shape was `new X(props)` followed
+by `x.assertValid(...)` in the factory — the constructor did not validate, so
+the factory's own call produced the error. That second call is now unreachable:
+the base class throws first. A factory relying on it silently changes its error
+type from the typed one to a plain `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,8 +1,28 @@
 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
@@ -24,9 +44,141 @@ export declare abstract class BaseValueObject<T> implements ValueObjectValidator
      * 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
@@ -79,3 +231,4 @@ export declare abstract class BaseValueObject<T> implements ValueObjectValidator
      */
     protected getInvalidValueMessage(value: T): string;
 }
+export {};

package/dist/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("@vytches/ddd-utils"),s=require("@vytches/ddd-contracts"),r=require("@vytches/ddd-domain-primitives");class l{constructor(t){if(this.value=t!==null&&typeof t=="object"?e.LibUtils.deepFreeze(t):t,!this.validate(this.value))throw new Error(this.getInvalidValueMessage(this.value))}equals(t){return t?this.value===t.value?!0:typeof this.value=="object"&&this.value!==null?e.LibUtils.deepEqual(this.value,t.value):!1:!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 s.EntityId{constructor(t,n){super(t,n)}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 n=e.LibUtils.normalizeIdToString(t);if(!e.LibUtils.isValidBigInt(n))throw r.InvalidParameterError.withParameter("entity identifier must be a valid bigint");return new i(n,"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 n=e.LibUtils.normalizeIdToString(t);return e.LibUtils.isValidBigInt(n)?e.Result.ok(new i(n,"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 u(a){return a}function d(){return i.create()}function o(a){return i.fromUUID(a)}function f(a){return i.fromText(a)}exports.BaseValueObject=l;exports.EntityId=i;exports.brandedIdFromText=f;exports.brandedIdFromUUID=o;exports.createBrandedId=u;exports.newBrandedId=d;
+"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.js

@@ -1,7 +1,15 @@
-import { LibUtils as e, Result as r } from "@vytches/ddd-utils";
-import { EntityId as o } from "@vytches/ddd-contracts";
-import { InvalidParameterError as n, MissingValueError as u } from "@vytches/ddd-domain-primitives";
-class h {
+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
@@ -23,12 +31,145 @@ class h {
    * is ever reached.
    */
   constructor(t) {
-    if (this.value = t !== null && typeof t == "object" ? e.deepFreeze(t) : t, !this.validate(this.value))
+    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
@@ -44,7 +185,18 @@ class h {
    * @returns True if they are equal, false otherwise
    */
   equals(t) {
-    return t ? this.value === t.value ? !0 : typeof this.value == "object" && this.value !== null ? e.deepEqual(this.value, 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
@@ -85,9 +237,9 @@ class h {
     return `Invalid value for ${this.constructor.name}`;
   }
 }
-class i extends o {
-  constructor(t, a) {
-    super(t, a);
+class i extends h {
+  constructor(t, n) {
+    super(t, n);
   }
   validate(t) {
     switch (this.getType()) {
@@ -100,7 +252,7 @@ class i extends o {
       case "text":
         return e.isValidTextId(t);
       default:
-        throw new n(`Unsupported IdType: ${this.getType()}`);
+        throw new s(`Unsupported IdType: ${this.getType()}`);
     }
   }
   /**
@@ -130,25 +282,25 @@ class i extends o {
     if (!e.hasValue(t))
       throw u.withValue("entity identifier");
     if (!e.isValidUUID(t))
-      throw n.withParameter("entity identifier");
+      throw s.withParameter("entity identifier");
     return new i(t, "uuid");
   }
   static fromInteger(t) {
     if (!e.isValidInteger(t))
-      throw n.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 n.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 u.withValue("entity identifier");
     if (!e.isValidTextId(t))
-      throw n.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) ---
@@ -159,7 +311,7 @@ class i extends o {
    * @since 0.24.0
    */
   static tryFromUUID(t) {
-    return e.hasValue(t) ? e.isValidUUID(t) ? r.ok(new i(t, "uuid")) : r.fail(n.withParameter("entity identifier")) : r.fail(u.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.
@@ -168,8 +320,8 @@ class i extends o {
    * @since 0.24.0
    */
   static tryFromInteger(t) {
-    return e.isValidInteger(t) ? r.ok(new i(t.toString(), "integer")) : r.fail(
-      n.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")
     );
   }
   /**
@@ -179,9 +331,9 @@ class i extends o {
    * @since 0.24.0
    */
   static tryFromBigInt(t) {
-    const a = e.normalizeIdToString(t);
-    return e.isValidBigInt(a) ? r.ok(new i(a, "bigint")) : r.fail(
-      n.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")
     );
   }
   /**
@@ -191,28 +343,28 @@ class i extends o {
    * @since 0.24.0
    */
   static tryFromText(t) {
-    return e.hasValue(t) ? e.isValidTextId(t) ? r.ok(new i(t, "text")) : r.fail(
-      n.withParameter("entity identifier contains invalid characters")
-    ) : r.fail(u.withValue("entity identifier"));
+    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 c(s) {
-  return s;
+function V(r) {
+  return r;
 }
-function g() {
+function p() {
   return i.create();
 }
-function m(s) {
-  return i.fromUUID(s);
+function y(r) {
+  return i.fromUUID(r);
 }
-function w(s) {
-  return i.fromText(s);
+function U(r) {
+  return i.fromText(r);
 }
 export {
-  h as BaseValueObject,
+  I as BaseValueObject,
   i as EntityId,
-  w as brandedIdFromText,
-  m as brandedIdFromUUID,
-  c as createBrandedId,
-  g 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.31.0-alpha.0",
+  "version": "0.31.1",
   "description": "Enhanced value objects and EntityId implementations",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -34,9 +34,9 @@
     "directory": "packages/value-objects"
   },
   "dependencies": {
-    "@vytches/ddd-contracts": "0.31.0-alpha.0",
-    "@vytches/ddd-utils": "0.31.0-alpha.0",
-    "@vytches/ddd-domain-primitives": "0.31.0-alpha.0"
+    "@vytches/ddd-domain-primitives": "0.31.1",
+    "@vytches/ddd-utils": "0.31.1",
+    "@vytches/ddd-contracts": "0.31.1"
   },
   "devDependencies": {
     "typescript": "^5.0.0",