@archi-code/ddd 0.0.0-stage → 3.0.0-alpha.1

package/ddd-skills/ddd-servicios-capa-aplicacion/references/ejemplo-ecommerce.md

@@ -0,0 +1,324 @@
+# Ejemplo: dónde va cada lógica en Ventas
+
+| Lógica | Dónde | Por qué |
+|---|---|---|
+| El total es la suma de las líneas | `OrderLines` (composite `Composite({ items: [OrderLine] })`, método `total()`) | Cálculo sobre valores |
+| Un pedido confirmado no admite líneas nuevas | `Order` (agregado) | Regla sobre su estado |
+| Gastos de envío según zona y promociones | `ShippingCostCalculator` (servicio de dominio) | Necesita el pedido, la zona, las tarifas y la promoción; forzado en cualquiera de ellos |
+| Envío gratis a partir de un importe | `OrderAbove` (`Specification<Order>`) | Regla con nombre que decide si un pedido cumple un criterio |
+| Solo el cliente que hizo el pedido puede cancelarlo | `OrderCancellation` (servicio de dominio), con concepto `Customer`, sobre `Order.cancel` | Regla de negocio [IDDD cap. 2] |
+| Quien pide cancelar tiene permiso para cancelar pedidos (rol, sesión activa) | `SalesPermissions` (puerto de aplicación) consultado por `CancelOrder`, que lanza `NotAllowedException` | Autorización del caso de uso [IDDD cap. 14] |
+| Cargar pedido, cancelar, guardar, publicar | `CancelOrder` (caso de uso) | Coordinación |
+| Cuando Almacén reserva, registrar en el pedido | listener `RegisterReservationOnStockReserved` y su caso de uso `RegisterReservation` `[Fuera de los libros: convención de @archi-code/ddd]` | Reacción a evento; invoca al agregado |
+| Precio vigente de una referencia | `ProductPricing` (puerto de dominio, ACL en infraestructura) | Viene de otro contexto |
+
+## El modelo
+
+`Order` y sus value objects (`OrderId`, `CustomerId`, `Sku`, `Quantity`, `Money`, `OrderLine`, `OrderLines`, `ShippingAddress`, `OrderStatus`, `ReservationId`, `CancellationReason`), sus eventos (`OrderPlaced`, `OrderLineAdded`, `OrderCancelled`…, unidos en `OrderEvent`) y sus errores son los de `ddd-skills/ddd-agregados/references/implementacion-ts.md`; no se redefinen aquí. Lo que usan los ejemplos de esta guía (`ddd-skills/ddd-servicios-capa-aplicacion/references/servicios-dominio-ts.md` y `ddd-skills/ddd-servicios-capa-aplicacion/references/capa-aplicacion-ts.md`):
+
+```ts
+static place(
+  id: OrderId,
+  customerId: CustomerId,
+  lines: OrderLines,
+  address: ShippingAddress,
+  clock: { now(): Date },
+): Order;
+addLine(line: OrderLine, clock: { now(): Date }): void;
+registerStockReservation(reservation: ReservationId, clock: { now(): Date }): void;
+cancel(reason: CancellationReason, clock: { now(): Date }): void;
+total(): Money;
+```
+
+Lo que añade Ventas en esta guía:
+
+```ts
+import { AggregateRoot, BooleanType, Required, Specification, StringType } from '@archi-code/ddd/domain';
+import type { PrimitiveTypes } from '@archi-code/ddd/domain';
+import { DomainException } from '@archi-code/ddd/exceptions';
+
+export class OrderAbove extends Specification<Order> {
+  constructor(private readonly minimum: Money) {
+    super();
+  }
+
+  isSatisfiedBy(order: Order): boolean {
+    return order.total().covers(this.minimum);
+  }
+}
+
+export class CustomerBlocked extends DomainException {
+  constructor(customerId: string) {
+    super(`Customer ${customerId} is blocked and cannot place orders`, ['CUS001']);
+  }
+}
+
+export class CustomerName extends Required(StringType) {}
+export class Blocked extends Required(BooleanType) {}
+
+export class Customer extends AggregateRoot<CustomerId> {
+  private constructor(
+    id: CustomerId,
+    readonly name: CustomerName,
+    private _blocked: Blocked,
+  ) {
+    super(id);
+  }
+
+  static fromPrimitives(primitives: PrimitiveTypes<Customer>): Customer {
+    return new Customer(
+      new CustomerId(primitives.id),
+      new CustomerName(primitives.name),
+      new Blocked(primitives.blocked),
+    );
+  }
+
+  get blocked(): Blocked {
+    return this._blocked;
+  }
+
+  placeOrder(
+    id: OrderId,
+    lines: OrderLines,
+    address: ShippingAddress,
+    clock: { now(): Date },
+  ): Order {
+    if (this._blocked.value) {
+      throw new CustomerBlocked(this.id.value);
+    }
+    return Order.place(id, this.id, lines, address, clock);
+  }
+
+  toPrimitives(): PrimitiveTypes<Customer> {
+    return { id: this.id.value, name: this.name.value, blocked: this._blocked.value };
+  }
+}
+
+export class NotTheCustomerOfOrder extends DomainException {
+  constructor(orderId: string) {
+    super(`Only the customer who placed order ${orderId} can cancel it`, ['ORD004']);
+  }
+}
+
+export class OrderCancellation {
+  cancel(
+    order: Order,
+    requester: CustomerId,
+    reason: CancellationReason,
+    clock: { now(): Date },
+  ): void {
+    if (!order.customerId.equals(requester)) {
+      throw new NotTheCustomerOfOrder(order.id.value);
+    }
+    order.cancel(reason, clock);
+  }
+}
+```
+
+* `OrderAbove` usa `Money.covers` (misma moneda e importe mayor o igual).
+* `OrderCancellation` es un servicio de dominio: la regla relaciona a quien pide con el pedido (`CustomerId`), y el estado lo sigue protegiendo `Order.cancel`, que lanza `OrderCannotBeCancelled` si el pedido ya está cancelado.
+
+## `PlaceOrder`
+
+`ProductPricing` y `ProductNotSellable` son los de `ddd-skills/ddd-servicios-capa-aplicacion/references/capa-aplicacion-ts.md`.
+
+```ts
+import { ValueObjects } from '@archi-code/ddd/domain';
+import type { AggregateFinder, AggregateSaver } from '@archi-code/ddd/domain';
+import { UseCase } from '@archi-code/ddd/application';
+import type { Clock, EventBus } from '@archi-code/ddd/application';
+import { AggregateNotFoundException } from '@archi-code/ddd/exceptions';
+
+export interface PlaceOrderInput {
+  customerId: string;
+  lines: { sku: string; quantity: number }[];
+  shippingAddress: { street: string; city: string; country: string };
+}
+
+interface PlaceOrderCommand {
+  customerId: CustomerId;
+  lines: { sku: Sku; quantity: Quantity }[];
+  shippingAddress: ShippingAddress;
+}
+
+export class PlaceOrder extends UseCase<PlaceOrderInput, PlaceOrderCommand, string> {
+  constructor(
+    private readonly customers: AggregateFinder<Customer>,
+    private readonly orders: AggregateSaver<Order>,
+    private readonly pricing: ProductPricing,
+    private readonly events: EventBus<OrderEvent>,
+    private readonly clock: Clock,
+  ) {
+    super();
+  }
+
+  protected toCommand(input: PlaceOrderInput): PlaceOrderCommand {
+    return ValueObjects.build({
+      customerId: () => new CustomerId(input.customerId),
+      lines: () =>
+        ValueObjects.buildList(input.lines, (line) =>
+          ValueObjects.build({
+            sku: () => new Sku(line.sku),
+            quantity: () => new Quantity(line.quantity),
+          }),
+        ),
+      shippingAddress: () => ShippingAddress.fromPrimitives(input.shippingAddress),
+    });
+  }
+
+  protected async handle(command: PlaceOrderCommand): Promise<string> {
+    const customer = await this.customers.findById(command.customerId);
+    if (customer === null) {
+      throw new AggregateNotFoundException('Customer', command.customerId.value);
+    }
+    const items = await Promise.all(
+      command.lines.map(async ({ sku, quantity }) => {
+        const unitPrice = await this.pricing.priceForSale(sku);
+        if (unitPrice === null) {
+          throw new ProductNotSellable(sku.value);
+        }
+        return new OrderLine({ sku, quantity, unitPrice });
+      }),
+    );
+    const lines = new OrderLines({ items });
+    const order = customer.placeOrder(
+      OrderId.generate(),
+      lines,
+      command.shippingAddress,
+      this.clock,
+    );
+    await this.orders.save(order);
+    await this.events.publish(order.pullDomainEvents());
+    return order.id.value;
+  }
+}
+```
+
+* Las lecturas de otros agregados y contextos (`Customer`, precios) van antes de invocar al dominio [IDDD cap. 10].
+* `Customer` actúa como fábrica (comprueba que no está bloqueado) pero no se modifica ni se guarda: el caso de uso pide `AggregateFinder<Customer>` y `AggregateSaver<Order>`, y solo se guarda `Order`: una escritura atómica, un agregado; que esa escritura sea atómica lo garantiza el repositorio, no el caso de uso `[Fuera de los libros: convención de @archi-code/ddd]`.
+* El id nuevo sale del value object (`OrderId.generate()`), no del repositorio.
+* `toCommand` informa de todos los campos a la vez, también los de cada línea (`lines.0.quantity`).
+
+Los gastos de envío se han dejado fuera de este caso de uso para mantenerlo alineado con el `Order` de `ddd-skills/ddd-agregados/GUIA.md`; si el negocio los incorpora al pedido, el caso de uso carga lo que `ShippingCostCalculator` necesita, lo invoca y pasa el `Money` resultante a `placeOrder`.
+
+## Registrar la reserva de stock
+
+Una reacción a un evento es un listener `<Acción>On<Evento>`, decorado con `@ListensTo` y con un nombre de consumidor estable, que solo traduce el evento a la entrada de un caso de uso. Ese caso de uso registra un hecho que ya ocurrió: si el pedido no existe, retorna en vez de lanzar (el canal lo reentregaría sin fin), y `registerStockReservation` es idempotente, porque la entrega es al menos una vez.
+
+```ts
+import { EventBase, ValueObjects } from '@archi-code/ddd/domain';
+import type { AggregateFinder, AggregateSaver, EventMetadata } from '@archi-code/ddd/domain';
+import { EventListener, ListensTo, UseCase } from '@archi-code/ddd/application';
+import type { Clock, EventBus } from '@archi-code/ddd/application';
+
+export class StockReserved extends EventBase {
+  static readonly eventName = 'StockReserved';
+
+  constructor(
+    reservationId: string,
+    readonly orderId: string,
+    metadata?: EventMetadata,
+  ) {
+    super(reservationId, metadata);
+  }
+}
+
+export interface RegisterReservationInput {
+  orderId: string;
+  reservationId: string;
+}
+
+interface RegisterReservationCommand {
+  orderId: OrderId;
+  reservationId: ReservationId;
+}
+
+export class RegisterReservation extends UseCase<
+  RegisterReservationInput,
+  RegisterReservationCommand,
+  void
+> {
+  constructor(
+    private readonly orders: AggregateFinder<Order> & AggregateSaver<Order>,
+    private readonly events: EventBus<OrderEvent>,
+    private readonly clock: Clock,
+  ) {
+    super();
+  }
+
+  protected toCommand(input: RegisterReservationInput): RegisterReservationCommand {
+    return ValueObjects.build({
+      orderId: () => new OrderId(input.orderId),
+      reservationId: () => new ReservationId(input.reservationId),
+    });
+  }
+
+  protected async handle(command: RegisterReservationCommand): Promise<void> {
+    const order = await this.orders.findById(command.orderId);
+    if (order === null) {
+      return;
+    }
+    order.registerStockReservation(command.reservationId, this.clock);
+    await this.orders.save(order);
+    await this.events.publish(order.pullDomainEvents());
+  }
+}
+
+@ListensTo(StockReserved, { consumer: 'register-reservation-on-stock-reserved' })
+export class RegisterReservationOnStockReserved extends EventListener<StockReserved> {
+  constructor(private readonly registerReservation: RegisterReservation) {
+    super();
+  }
+
+  async handle(event: StockReserved): Promise<void> {
+    await this.registerReservation.execute({
+      orderId: event.orderId,
+      reservationId: event.aggregateId,
+    });
+  }
+}
+```
+
+## Test del flujo
+
+El test comprueba lo que el listener provoca, no que se le llame, y entrega el mismo evento dos veces. `aPendingOrderOf`, `laura` y `orderId` son fábricas y datos de `test/support/` del proyecto, y `InMemoryOrderRepository` es el repositorio en memoria que el proyecto escribe allí (`ddd-skills/ddd-repositorios-persistencia/references/tests-repositorios.md`), como en `ddd-skills/ddd-servicios-capa-aplicacion/references/capa-aplicacion-ts.md`:
+
+```ts
+import { describe, expect, it } from 'vitest';
+import {
+  DomainEventBus,
+  EventRegistry,
+  FixedClock,
+  InMemoryEventChannel,
+} from '@archi-code/ddd/infrastructure';
+import { InMemoryOrderRepository } from '../support/in-memory-order-repository';
+
+const clock = new FixedClock('2026-03-01T09:30:00Z');
+const reservationId = '0f1e2d3c-4b5a-4968-8776-655443322110';
+
+describe('Registering the stock reservation of an order', () => {
+  it('the order keeps the reservation the warehouse made, also when it is delivered twice', async () => {
+    const orders = new InMemoryOrderRepository();
+    const registry = new EventRegistry<StockReserved>().register(
+      StockReserved,
+      (json) => new StockReserved(json.aggregateId, json.orderId as string, json),
+    );
+    const channel = new InMemoryEventChannel();
+    const bus = new DomainEventBus<StockReserved>(channel, registry);
+    const sales = new DomainEventBus<OrderEvent>(channel, new EventRegistry<OrderEvent>());
+    await bus.subscribe(
+      new RegisterReservationOnStockReserved(
+        new RegisterReservation(orders, sales, clock),
+      ),
+    );
+    await orders.save(aPendingOrderOf(laura));
+    const reserved = new StockReserved(reservationId, orderId, { clock });
+
+    await bus.publish([reserved]);
+    await bus.publish([reserved]);
+
+    const order = await orders.findById(new OrderId(orderId));
+    expect(order?.stockReservation?.value).toBe(reservationId);
+  });
+});
+```

package/ddd-skills/ddd-servicios-capa-aplicacion/references/servicios-dominio-ts.md

@@ -0,0 +1,191 @@
+# Servicios de dominio en TypeScript
+
+## Cuándo
+
+IDDD enumera tres situaciones [IDDD cap. 7]:
+* realizar un proceso de negocio significativo;
+* transformar un objeto de dominio de una composición a otra;
+* calcular un valor que requiere datos de más de un objeto de dominio (el caso más común).
+
+Ejemplo de IDDD: autenticar a un usuario solo si su tenant está activo. Ponerlo en `User` obliga al cliente a conocer `Tenant` y las reglas de cifrado; un servicio `AuthenticationService` expresa la operación del lenguaje y oculta los detalles [IDDD cap. 7].
+
+## Forma
+
+El paquete no trae una clase base para servicios de dominio: son clases normales en `domain/`, con el nombre de la operación de negocio. Reciben agregados ya cargados y value objects, y devuelven un value object.
+
+```ts
+import { Composite, Required, StringType } from '@archi-code/ddd/domain';
+import type { SatisfiedBy } from '@archi-code/ddd/domain';
+import { DomainException } from '@archi-code/ddd/exceptions';
+import { Validations } from '@archi-code/validation';
+
+@Validations([{ validator: 'isIn', properties: { values: ['PENINSULA', 'BALEARES', 'CANARIAS'] } }])
+export class ShippingZone extends Required(StringType) {}
+
+export class ShippingRate extends Composite({ zone: ShippingZone, price: Money }) {}
+
+export class NoShippingToZone extends DomainException {
+  constructor(zone: string) {
+    super(`There is no shipping rate for ${zone}`, ['SHP001']);
+  }
+}
+
+export class ShippingRates extends Composite({ items: [ShippingRate] }) {
+  priceFor(zone: ShippingZone): Money {
+    const rate = this.items.find((candidate) => candidate.zone.equals(zone));
+    if (rate === undefined) {
+      throw new NoShippingToZone(zone.value);
+    }
+    return rate.price;
+  }
+}
+
+export class ShippingCostCalculator {
+  costFor(
+    order: Order,
+    zone: ShippingZone,
+    rates: ShippingRates,
+    freeShipping: SatisfiedBy<Order>,
+  ): Money {
+    const price = rates.priceFor(zone);
+    if (!freeShipping.isSatisfiedBy(order)) {
+      return price;
+    }
+    return new Money({ amount: new Cents(0), currency: price.currency });
+  }
+}
+```
+
+* Sin estado; recibe objetos de dominio (`Order`, la tabla de tarifas como composite, la zona) y devuelve un value object (`Money`, el composite de `Cents` y `Currency`).
+* La condición de envío gratis es una `Specification<Order>` que recibe ya construida (`new OrderAbove(euros(5000))`); `SatisfiedBy<Order>` acepta también cualquier objeto con `isSatisfiedBy`, y se combina con `and`, `or` y `not`.
+* El nombre de la clase y del método salen del lenguaje ubicuo.
+* No guarda nada ni publica nada; eso lo hace el caso de uso que lo invoca.
+* El servicio puede leer por repositorio [IDDD cap. 7]: con el paquete recibe un `AggregateFinder` (solo lectura) o los agregados ya cargados por el caso de uso, como aquí; nunca guarda ni elimina.
+
+## Interfaz separada o no
+
+Si solo habrá una implementación y no depende de infraestructura, una clase concreta basta. IDDD discute la interfaz separada y advierte contra nombres de implementación sin significado como `Impl`: si hay interfaz, la implementación se nombra por lo que la distingue [IDDD cap. 7].
+
+Cuando la implementación necesita tecnología (consultar otro contexto, un servicio de tipos de cambio), la interfaz va en el dominio, con value objects, y la implementación en infraestructura [IDDD cap. 7]. El adaptador envuelve los errores del cliente en `InternalErrorException` con `cause` y redondea de forma explícita (el dinero va en céntimos enteros):
+
+```ts
+import { DateType, Required } from '@archi-code/ddd/domain';
+
+export class RateDay extends Required(DateType) {}
+
+export interface ExchangeRates {
+  convert(amount: Money, to: Currency, on: RateDay): Promise<Money>;
+}
+```
+
+```ts
+import { InternalErrorException } from '@archi-code/ddd/exceptions';
+
+interface EcbClient {
+  rate(from: string, to: string, day: string): Promise<number>;
+}
+
+export class EcbExchangeRates implements ExchangeRates {
+  constructor(private readonly ecb: EcbClient) {}
+
+  async convert(amount: Money, to: Currency, on: RateDay): Promise<Money> {
+    let rate: number;
+    try {
+      rate = await this.ecb.rate(amount.currency.value, to.value, on.value.toISOString().slice(0, 10));
+    } catch (error) {
+      throw new InternalErrorException('reading the ECB exchange rates', { cause: error });
+    }
+    return new Money({ amount: new Cents(Math.round(amount.amount.value * rate)), currency: to });
+  }
+}
+```
+
+## Validación de composiciones
+
+Un servicio de dominio es buen sitio para validar que varios agregados sean coherentes entre sí [IDDD cap. 5]. Recibe los agregados que el caso de uso ya cargó y comprueba. Si detecta un problema, informa (error o evento); no corrige varios agregados a la vez: cada agregado se guarda en su propia escritura atómica.
+
+Para informar de todos los problemas a la vez, reúne `ValidationIssue`s y lanza una sola `ValidationException` (HTTP 422 con `HttpErrorMapper`, cada problema con su `field` y su `code`); si basta con uno, lanza una `DomainException` con nombre y código propio:
+
+```ts
+import { ValidationException } from '@archi-code/ddd/exceptions';
+import type { ValidationIssue } from '@archi-code/ddd/exceptions';
+
+export class ShipmentCheck {
+  assertCanShip(order: Order, customer: Customer): void {
+    const issues: ValidationIssue[] = [];
+    if (!order.customerId.equals(customer.id)) {
+      issues.push({ field: 'customer', code: 'SHP002', message: `Order ${order.id.value} belongs to another customer` });
+    }
+    if (customer.blocked.value) {
+      issues.push({ field: 'customer', code: 'CUS001', message: `Customer ${customer.id.value} is blocked` });
+    }
+    if (!order.status.isPending()) {
+      issues.push({ field: 'order', code: 'ORD001', message: `Order ${order.id.value} is no longer pending` });
+    }
+    if (issues.length > 0) {
+      throw new ValidationException(issues);
+    }
+  }
+}
+```
+
+## Tests
+
+Los servicios se prueban como cualquier objeto de dominio, con datos realistas y nombres del lenguaje [IDDD cap. 7]. Con Vitest, las fábricas de datos de prueba (`anOrderWorth`, `euros`, `standardRates`) viven en `test/support/` del proyecto:
+
+```ts
+import { describe, expect, it } from 'vitest';
+
+describe('ShippingCostCalculator', () => {
+  it('ships for free to the peninsula from 50 EUR', () => {
+    const cost = new ShippingCostCalculator().costFor(
+      anOrderWorth(5200),
+      new ShippingZone('PENINSULA'),
+      standardRates(),
+      new OrderAbove(euros(5000)),
+    );
+
+    expect(cost.toPrimitives()).toEqual({ amount: 0, currency: 'EUR' });
+  });
+
+  it('charges the rate of the Canary Islands below the minimum', () => {
+    const cost = new ShippingCostCalculator().costFor(
+      anOrderWorth(3000),
+      new ShippingZone('CANARIAS'),
+      standardRates(),
+      new OrderAbove(euros(5000)),
+    );
+
+    expect(cost.equals(euros(1295))).toBe(true);
+  });
+});
+```
+
+```ts
+import { FixedClock } from '@archi-code/ddd/infrastructure';
+
+const clock = new FixedClock('2026-03-01T09:30:00Z');
+
+export const euros = (cents: number): Money => Money.fromPrimitives({ amount: cents, currency: 'EUR' });
+
+export const anOrderWorth = (cents: number): Order =>
+  Order.place(
+    OrderId.generate(),
+    new CustomerId('3c1d2e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f'),
+    OrderLines.fromPrimitives({
+      items: [{ sku: 'TORCH-01', quantity: 1, unitPrice: { amount: cents, currency: 'EUR' } }],
+    }),
+    ShippingAddress.fromPrimitives({ street: 'Calle Mayor 1', city: 'Huelva', country: 'ES' }),
+    clock,
+  );
+
+export const standardRates = (): ShippingRates =>
+  ShippingRates.fromPrimitives({
+    items: [
+      { zone: 'PENINSULA', price: { amount: 495, currency: 'EUR' } },
+      { zone: 'CANARIAS', price: { amount: 1295, currency: 'EUR' } },
+    ],
+  });
+```
+
+`Order`, `OrderLines`, `ShippingAddress`, `Money` y `Cents` son los de `ddd-skills/ddd-agregados/references/implementacion-ts.md`, y `OrderAbove` y `Customer`, los de `ddd-skills/ddd-servicios-capa-aplicacion/references/ejemplo-ecommerce.md`.

package/ddd-skills/ddd-value-objects-entidades/GUIA.md

@@ -0,0 +1,118 @@
+# Value Objects y entidades
+
+> Parte del skill `archi-code-ddd`: léela solo cuando ese skill te dirija aquí. Los ejemplos están escritos con la API de `@archi-code/ddd` (las clases de su `src`) y se copian tal cual; las guías son la fuente de verdad: el paquete solo se aparta de ellas donde lo marca `[Fuera de los libros: convención de @archi-code/ddd]`, y cualquier otra discrepancia es un defecto del paquete.
+>
+> **Cuándo consultar esta guía.** Diseño táctico DDD de Value Objects y entidades en TypeScript. Decide si un concepto es value object o entidad, cómo implementar value objects inmutables con igualdad por valor y comportamiento sin efectos secundarios (Money, identificadores, rangos, direcciones, tipos estándar y estados), cómo diseñar entidades con identidad estable y comportamiento con nombres del negocio en lugar de setters, estrategias y momento de generación de identidad, los tres niveles de validación (atributo, objeto completo, composición) y cómo persistir value objects sin que la base de datos deforme el modelo. Consúltala siempre que se cree o revise una clase del dominio, aparezcan primitivos sueltos (string para emails, number para dinero), getters y setters públicos, dudas sobre igualdad, ids o validaciones, o se pregunte "¿esto es una entidad?", aunque no se mencione DDD.
+
+## Con @archi-code/ddd
+
+[Fuera de los libros: convención de @archi-code/ddd]
+
+* Un value object es una subclase con nombre de un tipo del paquete (`class Email extends Required(StringType) {}`) con sus reglas en `@Validations` (de `@archi-code/validation`): se crea con `new` y su constructor lo deja siempre válido; no hay factorías `of()` ni `assertValid()`, y la normalización va en `filter`.
+* Un valor de varios atributos (`Money`, `DateRange`, `OrderLine`, `OrderLines`) es `Composite({...})`, con las reglas que combinan campos como `custom`; un estado, un `EnumType`; un id, `IdType`, generado por el propio value object (`OrderId.generate()`), nunca por el repositorio.
+* `Money` va en céntimos enteros (`Cents`, `Required(NumberType)` con `isInt`) en lugar de `bigint`: exacto hasta `Number.MAX_SAFE_INTEGER` (9.007.199.254.740.991 céntimos); el paquete no tiene tipo `bigint`.
+* Los errores de una entrada se recogen con `ValueObjects.build({...})` y `ValidationException.errors`, no con un manejador de notificación.
+* Un value object es opcional por defecto (`value: T | null`) y `Required(XType)` lo hace obligatorio. Los libros crean siempre el valor con contenido y modelan lo opcional en el campo (`reservation: ReservationId | null`); con el paquete valen las dos formas.
+* La identidad de una entidad o raíz siempre es un value object obligatorio (`IdType` o `Required(...)`): un id sin valor lanza `RequiredValueException`, así dos entidades nuevas nunca son iguales por un id vacío [IDDD cap. 5].
+* Todo el estado de un agregado es value objects (también un booleano), cada campo guardado tiene un getter público con su nombre sin `_` y los valores derivados son métodos, nunca getters. La reconstitución es `static fromPrimitives(PrimitiveTypes<X>)` con su `toPrimitives()`, que el repositorio llama directamente y cuyo viaje de ida y vuelta prueba el spec del agregado (nada lo comprueba en ejecución). Los libros solo piden getters donde hacen falta y un mapper en infraestructura.
+
+Dos piezas básicas del modelo. Vernon insiste en un sesgo concreto: **modela con value objects siempre que puedas**. Incluso una entidad debería ser sobre todo un contenedor de value objects, no de entidades hijas, porque los valores son más fáciles de crear, probar, usar, optimizar y mantener [IDDD cap. 6].
+
+
+## Paso 1. ¿Value object o entidad?
+
+Aplica estas preguntas en orden [IDDD cap. 5 y cap. 6]:
+
+1. ¿Importa distinguir **este** ejemplar de cualquier otro, aunque todos sus atributos coincidan, y seguirlo a lo largo de cambios? Sí → **entidad**.
+2. Si no, comprueba las características de valor. Si cumple la mayoría → **value object**:
+   * mide, cuantifica o describe algo del dominio (no es una cosa en sí);
+   * puede ser inmutable;
+   * forma un todo conceptual con atributos que solo tienen sentido juntos;
+   * se reemplaza entero cuando cambia la descripción;
+   * se compara por igualdad de valor;
+   * ofrece comportamiento sin efectos secundarios.
+3. ¿Te inclinas por entidad solo porque la base de datos lo guarda en su propia tabla? Entonces sigue siendo un value object. El modelo de datos se subordina al de dominio, no al revés [IDDD cap. 6].
+
+Si dudas, empieza por value object: es más barato pasar de valor a entidad que deshacer una red de entidades [IDDD cap. 6].
+
+| Concepto | Decisión típica | Por qué |
+|---|---|---|
+| Importe con moneda | Value object `Money` | Cuantifica; dos "17,00 €" son intercambiables |
+| Dirección de envío de un pedido | Value object | Describe el pedido; si cambia, se reemplaza entera |
+| Dirección en una agenda de clientes con historial y verificación | Puede ser entidad | Se sigue su ciclo de vida |
+| Línea de pedido | Normalmente value object | Se identifica por su producto dentro del pedido |
+| Pedido, Cliente, Pago | Entidad (y raíz de agregado) | Ciclo de vida e identidad propios |
+| `OrderId`, `CustomerId` | Value object que contiene la identidad | Inmutable y estable [IDDD cap. 5] |
+| Estado del pedido | Tipo estándar como value object | Describe el tipo de estado y puede llevar comportamiento [IDDD cap. 6] |
+
+## Paso 2. Implementar
+
+* Value objects: `ddd-skills/ddd-value-objects-entidades/references/value-objects-ts.md`. Qué clase del paquete usar en cada caso y ejemplos de `Money`, identificadores, `Email`, `DateRange`, colecciones de valores y estados.
+* Entidades: `ddd-skills/ddd-value-objects-entidades/references/entidades-ts.md`. Identidad, `Entity` y `AggregateRoot`, constructor completo, comportamiento con nombres del lenguaje, protección de invariantes, reconstitución con `fromPrimitives`.
+
+Reglas mínimas que no se negocian (los nombres de los métodos son interfaces que revelan intención, ver Paso 5):
+
+**Value objects**
+* Inmutables: propiedades `readonly`, sin métodos que muten. Las operaciones devuelven nuevas instancias [IDDD cap. 6].
+* Válidos desde su creación: el constructor rechaza estados imposibles (`Required(...)` y `@Validations`) [IDDD cap. 5; PHP: Value Objects].
+* Igualdad por valor con `equals`, que el paquete ya da (clase y valor; fechas por instante, listas por contenido); en TypeScript `===` compara referencias `[Fuera de los libros]`.
+* Los métodos reciben otros value objects, no entidades, para garantizar que no hay efectos secundarios [IDDD cap. 6].
+* Nada de primitivos sueltos para conceptos del dominio: un `string` no puede tener comportamiento del negocio [IDDD cap. 6; PHP: Entities, "Objects vs. Primitive Types"].
+
+**Entidades**
+* Identidad estable, protegida contra cambios: se pasa a `super(id)` y queda `readonly` [IDDD cap. 5].
+* Igualdad por identidad: `equals` de `Entity` y `AggregateRoot` compara clase e id.
+* Sin setters públicos: métodos con verbos del negocio que protegen reglas: `backlogItem.commitTo(sprint)` y no `setSprintId(...)` + `setStatus(Committed)`, que deja la regla en cada cliente y el objeto a medias [IDDD cap. 1 y cap. 5].
+* Diseño inicial mínimo: identidad, lo que sirve para encontrarla y el comportamiento esencial con los atributos que ese comportamiento necesita. El resto, después [IDDD cap. 5].
+
+## Paso 3. Identidad
+
+Elige la estrategia con `ddd-skills/ddd-value-objects-entidades/references/entidades-ts.md` (sección Identidad). Resumen [IDDD cap. 5; PHP: Entities]:
+
+| Estrategia | Riesgo principal |
+|---|---|
+| La aporta el usuario | Única pero incorrecta; cambiarla después es caro |
+| La genera la aplicación (UUID) | Ninguno relevante; requiere un generador fiable |
+| La genera la base de datos (secuencia) | Llega tarde: el evento de creación sale sin id, y los objetos nuevos parecen iguales en colecciones |
+| La asigna otro contexto | Sincronización con el origen; la más compleja |
+
+Recomendación por defecto: identidad generada por la aplicación, **temprana** (antes de persistir), generada por el propio value object de identidad (`OrderId.generate()`), nunca por el repositorio [IDDD cap. 5 para la identidad temprana; `[Fuera de los libros: convención de @archi-code/ddd]` para quién la genera]. Si conviene orden temporal en índices, `new OrderId(uuidv7())`: `IdType` acepta cualquier versión de UUID `[Fuera de los libros]`.
+
+## Paso 4. Validación en tres niveles
+
+[IDDD cap. 5; PHP: Entities]
+
+1. **Atributo:** en el constructor del value object (`Required(...)` y `@Validations`).
+2. **Objeto completo:** reglas que combinan atributos (las de un valor de varios atributos, reglas `custom` de su `Composite`). IDDD sugiere un validador separado cuando esa validación cambia más que la entidad.
+3. **Composición:** reglas sobre varios objetos o agregados. Un servicio de dominio que recibe lo cargado o lee lo necesario con `AggregateFinder`.
+
+Detalle, cómo acumular todos los errores (`ValueObjects.build` en lugar del patrón de notificación) y qué validar en la interfaz frente al dominio en `ddd-skills/ddd-value-objects-entidades/references/validacion.md`.
+
+## Paso 5. Diseño flexible y Specification
+
+Revisa el diseño con los patrones de diseño flexible (Supple Design): interfaces que revelan intención, funciones sin efectos secundarios, aserciones, contornos conceptuales, clases autónomas y clausura de operaciones [IDDD cap. 5 y cap. 6 aplican varios]. Cuando una regla tiene nombre en el negocio, se usa en varios sitios o se combina con otras, modélala como **Specification** (`Specification<T>` de `@archi-code/ddd/domain`) para validar, seleccionar o construir [IDDD cap. 5; PHP: Repositories]. Guía y código en `ddd-skills/ddd-value-objects-entidades/references/specification-y-diseno-flexible.md`.
+
+## Paso 6. Persistencia sin fugas
+
+Cómo guardar value objects (columnas embebidas, JSON, tabla propia para colecciones) sin convertirlos en entidades del modelo: `ddd-skills/ddd-value-objects-entidades/references/persistencia-valores.md`. La regla: diseña el modelo de datos al servicio del modelo de dominio [IDDD cap. 6]. Con el paquete, el repositorio parte de `order.toPrimitives()` (y carga con `Order.fromPrimitives(row).restoreVersion(version)`) y decide en infraestructura cómo reparte los primitivos en columnas.
+
+## Señales de alarma
+
+* Clases con todos los campos públicos y `get`/`set` por cada uno: modelo anémico [IDDD cap. 1].
+* `amount: number` para dinero, `email: string`, `status: string`.
+* Métodos `update(dto)` que copian campos del DTO a la entidad.
+* Entidades hijas con id propio que nadie busca por ese id (deberían ser valores).
+* `equals` que compara ids `undefined` de objetos aún no guardados [IDDD cap. 5].
+* Clases base propias (`ValueObject`, `Entity`, `deepEqual`) escritas en el proyecto: vienen del paquete. Tampoco factorías `of()`: un value object se crea con `new`.
+* Getters calculados (`get total()`) en agregados, entidades o composites: rompen `toPrimitives()`; escribe un método.
+* Un value object con un método que modifica una entidad recibida por parámetro [IDDD cap. 6].
+* Validaciones de negocio repetidas en controlador, DTO y entidad, con criterios distintos.
+
+## Ejemplo
+
+`ddd-skills/ddd-value-objects-entidades/references/ejemplo-ecommerce.md` diseña `Money`, `Quantity`, `OrderLine`, `OrderLines`, `ShippingAddress` y `OrderStatus`, y explica por qué `Order` es una entidad (la clase completa, con sus límites de agregado, está en `ddd-skills/ddd-agregados/references/implementacion-ts.md`; los límites se deciden en `ddd-skills/ddd-agregados/GUIA.md`).
+
+## Siguiente guía
+
+* Dónde termina cada objeto y qué se guarda junto → `ddd-skills/ddd-agregados/GUIA.md`.
+* Cómo se guardan → `ddd-skills/ddd-repositorios-persistencia/GUIA.md`.