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

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

@@ -0,0 +1,190 @@
+# 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, DomainException, Required, StringType } from '@archi-code/ddd/domain';
+import type { SatisfiedBy } from '@archi-code/ddd/domain';
+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/infrastructure';
+
+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` (`ExceptionKind.Invalid`, 422 en HTTP, 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/domain';
+import type { ValidationIssue } from '@archi-code/ddd/domain';
+
+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 `ValueObjectBuilder.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 (`ValueObjectBuilder.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(...)`, recordando la versión de la fila en su propio `WeakMap`, nunca en el agregado) 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`.

package/ddd-skills/ddd-value-objects-entidades/references/ejemplo-ecommerce.md

@@ -0,0 +1,87 @@
+# Ejemplo: Ventas en la tienda online
+
+Objetos del contexto de Ventas, con la decisión razonada. Los límites de agregado se deciden en `ddd-skills/ddd-agregados/GUIA.md`; aquí solo se decide valor o entidad y su comportamiento.
+
+| Concepto | Decisión | Razón | Con el paquete |
+|---|---|---|---|
+| `Money` | Value object | Cuantifica; se reemplaza; igualdad por valor | `Composite({ amount: Cents, currency: Currency })` |
+| `Quantity` | Value object | Regla: entero positivo | `Required(NumberType)` + `@Validations` |
+| `Sku` | Value object | Identifica un producto de otro contexto: integración minimalista | `Required(StringType)` |
+| `OrderLine` | Value object | Dentro del pedido se identifica por su `Sku`; nadie la busca por id propio | `Composite` |
+| `OrderLines` | Value object | Reglas de la colección: al menos una línea y un SKU por línea; `total()` no suma monedas distintas | `Composite({ items: [OrderLine] })` |
+| `ShippingAddress` | Value object | Describe a dónde va este pedido; si el cliente cambia de casa, el pedido no cambia | `Composite` |
+| `OrderStatus` | Tipo estándar con comportamiento | Reglas de transición en un solo sitio | `Required(StatusType)`, `StatusType extends EnumType<Status>` |
+| `Order` | Entidad | Ciclo de vida largo, identidad propia, cambia de estado | `AggregateRoot<OrderId, OrderEvent>` |
+
+`Money`, `Quantity`, `Sku`, `OrderLine`, `OrderLines`, `OrderStatus`, `OrderId` y `CustomerId` están en `ddd-skills/ddd-value-objects-entidades/references/value-objects-ts.md`. Aquí, la dirección:
+
+```ts
+import { Validations } from '@archi-code/validation';
+import { Composite, Required, StringType } from '@archi-code/ddd/domain';
+
+export class Street extends Required(StringType) {}
+export class City extends Required(StringType) {}
+
+@Validations([{ validator: 'isISO31661Alpha2' }])
+export class Country extends Required(StringType) {
+  protected filter(value: unknown): string {
+    return super.filter(value).trim().toUpperCase();
+  }
+}
+
+export class ShippingAddress extends Composite({ street: Street, city: City, country: Country }) {}
+```
+
+La entidad es el `Order` de `ddd-skills/ddd-agregados/references/implementacion-ts.md`, donde está la clase completa con sus eventos y su reloj; no se redefine aquí. Lo que importa para decidir valor o entidad:
+
+```ts
+export class Order extends AggregateRoot<OrderId, OrderEvent> {
+  private constructor(
+    id: OrderId,
+    readonly customerId: CustomerId,
+    private _lines: OrderLines,
+    readonly shippingAddress: ShippingAddress,
+    private _status: OrderStatus,
+    private _stockReservation: ReservationId | null,
+    private _paymentAuthorization: PaymentAuthorization | null,
+  ) {
+    super(id);
+  }
+
+  addLine(line: OrderLine, clock: { now(): Date }): void {
+    if (!this._status.isPending()) {
+      throw new OrderNoLongerEditable(this.id.value);
+    }
+    this._lines = this._lines.withLine(line);
+    this.record(
+      new OrderLineAdded(
+        this.id.value,
+        line.sku.value,
+        line.quantity.value,
+        Order.moneyData(line.unitPrice),
+        Order.moneyData(this.total()),
+        { clock },
+      ),
+    );
+  }
+
+  total(): Money {
+    return this._lines.total();
+  }
+}
+```
+
+La entidad apenas tiene lógica propia: delega en sus valores (`OrderLines.total`, `OrderLines.withLine`, `OrderStatus.isPending`). Es lo que IDDD llama orientar la entidad a contenedor de valores [IDDD cap. 6]. `addLine` reemplaza el `OrderLines` entero por el que devuelve `withLine`; nunca cambia una línea por dentro.
+
+El pedido referencia al cliente por su id (`customerId: CustomerId`), nunca por el objeto. Los eventos que registra (`OrderPlaced`, `OrderLineAdded`…) y el reloj que recibe cada método se explican en `ddd-skills/ddd-eventos-dominio/GUIA.md`.
+
+Un test de ida y vuelta por agregado comprueba que se puede guardar y rehacer `[Fuera de los libros: convención de @archi-code/ddd]`:
+
+```ts
+import { expect, it } from 'vitest';
+
+it('rebuilds the order it stored', () => {
+  const order = Order.place(OrderId.generate(), CustomerId.generate(), lines, address, clock);
+  expect(Order.fromPrimitives(order.toPrimitives()).toPrimitives()).toEqual(order.toPrimitives());
+});
+```

package/ddd-skills/ddd-value-objects-entidades/references/entidades-ts.md

@@ -0,0 +1,218 @@
+# Entidades en TypeScript
+
+## Qué es una entidad
+
+Un concepto que se modela como entidad cuando importa su individualidad: hay que distinguirlo de todos los demás y puede cambiar mucho durante mucho tiempo sin dejar de ser el mismo. Identidad única y mutabilidad son lo que la separa de un value object [IDDD cap. 5].
+
+Antes de crear una, comprueba si el concepto es en realidad un valor. Y si un sistema solo edita datos, un CRUD puede ser la herramienta adecuada; el problema es aplicar CRUD a sistemas complejos que merecen DDD [IDDD cap. 5].
+
+## Descubrir la entidad
+
+* Empieza solo por los atributos que dan identidad y los que sirven para encontrarla; ignora el resto hasta tener eso claro [IDDD cap. 5].
+* Luego busca el comportamiento esencial en los requisitos y nómbralo con el lenguaje. En IDDD, "los tenants pueden estar activos o desactivados" lleva a `activate()` y `deactivate()`, no a `setActive(boolean)` [IDDD cap. 5].
+* El lenguaje no son solo sustantivos: adjetivos describen y verbos indican lo que las cosas hacen [IDDD cap. 5].
+
+## Identidad
+
+### Estrategias [IDDD cap. 5; PHP: Entities]
+
+| Estrategia | Cuándo | Cuidado |
+|---|---|---|
+| La aporta el usuario | El negocio exige un identificador legible (código de campaña) | Puede ser única pero incorrecta. Alternativa: guardar el valor del usuario como atributo para búsquedas y usar otra identidad |
+| La genera la aplicación | Opción por defecto | Generador fiable también en despliegues con varios nodos |
+| La genera la persistencia | Secuencias heredadas | Llega tarde (ver abajo); coste de ir a la base por cada id |
+| La asigna otro contexto | El concepto nace fuera (un cliente del CRM) | Sincronización por eventos; úsala lo menos posible |
+
+Con el paquete, la identidad generada por la aplicación es un `IdType` (`class OrderId extends IdType<'OrderId'> {}`); la que aporta el usuario o asigna otro contexto, un `Required(StringType)` con nombre y sus reglas (`CampaignCode`, en `ddd-skills/ddd-value-objects-entidades/references/value-objects-ts.md`, sección 3), usado como `AggregateRoot<CampaignCode>`.
+
+### Momento: temprana o tardía
+
+* **Tardía** (al persistir): el evento de creación se publicaría sin identidad y, si `equals` compara ids, varios objetos nuevos parecerían el mismo en un `Set` [IDDD cap. 5].
+* **Temprana** (al construir): el id se genera antes de crear la entidad y se pasa al constructor [IDDD cap. 5]. IDDD prefiere esta opción frente a hacer `equals` por atributos.
+* Lo genera el propio value object de identidad, nunca el repositorio: el repositorio solo obtiene y persiste, sin `nextId()` `[Fuera de los libros: convención de @archi-code/ddd]`.
+
+```ts
+import { IdType } from '@archi-code/ddd/domain';
+
+export class OrderId extends IdType<'OrderId'> {}
+
+const order = Order.place(OrderId.generate(), customerId, lines, shippingAddress, clock);
+```
+
+`XId.generate()` crea un value object de la clase sobre la que se llama (`OrderId.generate()` es un `OrderId`) con un UUID v4. Si conviene orden temporal en índices, `new OrderId(uuidv7())` `[Fuera de los libros]`.
+
+### Identidad sustituta
+
+Si el ORM o la base exige su propia clave (un autoincremental), usa dos identidades: la del dominio y una sustituta para la persistencia, oculta al modelo y a sus clientes [IDDD cap. 5]. Con el paquete, la sustituta vive solo en el repositorio: se guarda junto a los primitivos (como la `version`, que también es solo del repositorio), nunca dentro de `toPrimitives()` ni como campo del agregado.
+
+### Estabilidad
+
+La identidad no cambia durante la vida de la entidad. IDDD la protege con un setter interno que solo permite asignarla una vez [IDDD cap. 5]. Con el paquete, el id se pasa a `super(id)` y queda como `readonly id`; no se redeclara (`_id` + getter). Además es siempre un value object obligatorio (`IdType` o `Required(...)`): un id sin valor lanza `RequiredValueException`, así que dos entidades nuevas nunca son iguales por un id vacío [IDDD cap. 5].
+
+## Patrón de implementación
+
+No se escribe una clase base `Entity`: viene de `@archi-code/ddd/domain`. `Entity<Id>` solo guarda `readonly id` y compara por clase e id; `AggregateRoot<Id, Event>` la extiende y añade solo los eventos (`record()`, `pullDomainEvents()`); la versión para concurrencia optimista no está en el agregado, la recuerda cada repositorio en un `WeakMap<Order, number>` `[Fuera de los libros: convención de @archi-code/ddd]`.
+
+Una raíz de agregado extiende `AggregateRoot`. Una entidad hija (una parte con identidad propia dentro del agregado, que se busca por ese id) extiende `Entity`, guarda su id local y value objects, y sus métodos de negocio solo los llama su raíz [IDDD cap. 5 y cap. 10]:
+
+```ts
+import { BooleanType, DomainException, Entity, NumberType, Required, StringType } from '@archi-code/ddd/domain';
+
+export class SeatNumber extends Required(NumberType) {}
+export class SeatLabel extends Required(StringType) {}
+export class Sold extends Required(BooleanType) {}
+
+export class Seat extends Entity<SeatNumber> {
+  constructor(
+    id: SeatNumber,
+    private _label: SeatLabel,
+    readonly sold: Sold,
+  ) {
+    super(id);
+  }
+
+  get label(): SeatLabel {
+    return this._label;
+  }
+
+  relabel(label: SeatLabel): void {
+    if (this.sold.value) {
+      throw new DomainException(`Seat ${this.id.value} is already sold`, ['ROOM001']);
+    }
+    this._label = label;
+  }
+}
+
+new Seat(new SeatNumber(7), new SeatLabel('A1'), new Sold(false)).equals(
+  new Seat(new SeatNumber(7), new SeatLabel('B7'), new Sold(true)),
+); // true: misma clase y mismo id
+```
+
+Si nadie busca la parte por su id (las líneas de un pedido), no es una entidad hija sino un `Composite` (`ddd-skills/ddd-value-objects-entidades/references/value-objects-ts.md`, sección 7).
+
+### Creación frente a reconstitución
+
+Separar dos caminos evita que la carga desde base de datos vuelva a disparar reglas de creación o eventos `[Fuera de los libros como patrón explícito; IDDD lo resuelve con acceso por campo del ORM]`. Con el paquete, los dos caminos son una factoría de negocio y `static fromPrimitives(primitives: PrimitiveTypes<X>)`, con su `toPrimitives()` para guardar `[Fuera de los libros: convención de @archi-code/ddd]`:
+
+```ts
+import { Validations } from '@archi-code/validation';
+import { AggregateRoot, DomainException, EnumType, EventBase, Required, StringType } from '@archi-code/ddd/domain';
+import type { EventMetadata, PrimitiveTypes } from '@archi-code/ddd/domain';
+
+export class CustomerName extends Required(StringType) {}
+
+@Validations([{ validator: 'isLength', properties: { min: 3, max: 200 } }])
+export class BlockReason extends Required(StringType) {}
+
+export enum CustomerState {
+  Active = 'active',
+  Blocked = 'blocked',
+}
+
+export class CustomerStateType extends EnumType<CustomerState> {
+  protected getEnum(): typeof CustomerState {
+    return CustomerState;
+  }
+}
+
+export class CustomerStatus extends Required(CustomerStateType) {
+  isBlocked(): boolean {
+    return this.value === CustomerState.Blocked;
+  }
+}
+
+export class CustomerBlocked extends EventBase {
+  static readonly eventName = 'CustomerBlocked';
+
+  constructor(
+    readonly customerId: string,
+    readonly reason: string,
+    metadata?: EventMetadata,
+  ) {
+    super(metadata);
+  }
+}
+
+export class BlockedCustomerCannotChangeEmail extends DomainException {
+  constructor(customerId: string) {
+    super(`Customer ${customerId} is blocked and cannot change the email`, ['CUS001']);
+  }
+}
+
+export class Customer extends AggregateRoot<CustomerId, CustomerBlocked> {
+  private constructor(
+    id: CustomerId,
+    private _name: CustomerName,
+    private _email: Email,
+    private _status: CustomerStatus,
+  ) {
+    super(id);
+  }
+
+  static register(id: CustomerId, name: CustomerName, email: Email): Customer {
+    return new Customer(id, name, email, new CustomerStatus(CustomerState.Active));
+  }
+
+  static fromPrimitives(primitives: PrimitiveTypes<Customer>): Customer {
+    return new Customer(
+      new CustomerId(primitives.id),
+      new CustomerName(primitives.name),
+      new Email(primitives.email),
+      new CustomerStatus(primitives.status),
+    );
+  }
+
+  get name(): CustomerName {
+    return this._name;
+  }
+
+  get email(): Email {
+    return this._email;
+  }
+
+  get status(): CustomerStatus {
+    return this._status;
+  }
+
+  changeEmail(email: Email): void {
+    if (this._status.isBlocked()) {
+      throw new BlockedCustomerCannotChangeEmail(this.id.value);
+    }
+    this._email = email;
+  }
+
+  block(reason: BlockReason, clock: { now(): Date }): void {
+    if (this._status.isBlocked()) {
+      return;
+    }
+    this._status = new CustomerStatus(CustomerState.Blocked);
+    this.record(new CustomerBlocked(this.id.value, reason.value, { clock }));
+  }
+
+  toPrimitives(): PrimitiveTypes<Customer> {
+    return {
+      id: this.id.value,
+      name: this._name.value,
+      email: this._email.value,
+      status: this._status.value,
+    };
+  }
+}
+```
+
+`CustomerId` y `Email` son los de `ddd-skills/ddd-value-objects-entidades/references/value-objects-ts.md`.
+
+Fíjate en:
+* Constructor privado y dos factorías con nombre: `register` (lenguaje del negocio, puede registrar eventos) y `fromPrimitives` (técnica, solo para repositorios: rehace cada value object desde su primitivo, que vuelve a validar, y no registra nada).
+* Ningún setter; cada cambio es un comportamiento con nombre y sus reglas. `block` es idempotente y registra `CustomerBlocked` con el reloj que recibe, nunca con `new Date()`.
+* Todos los atributos son value objects; cambiar el correo es reemplazar un `Email`.
+* Getters solo para lo que los clientes necesitan leer, dicen los libros. Con el paquete, cada campo que se guarda tiene un getter público con su nombre sin `_`, porque `toPrimitives()` los lee `[Fuera de los libros: convención de @archi-code/ddd]`. Los valores derivados son métodos (`isBlocked()`), nunca getters.
+* El agregado no declara `version` ni la incluye en `toPrimitives()`: la versión es solo del repositorio, que la recuerda por agregado en un `WeakMap` y la guarda junto a los primitivos.
+
+## Seguimiento de cambios
+
+Una entidad no tiene por qué guardar su historial. Si ciertos cambios importan al negocio, la forma práctica es un evento de dominio por cada comando relevante y un almacén de eventos [IDDD cap. 5]. Ver `ddd-skills/ddd-eventos-dominio/GUIA.md`.
+
+## Roles
+
+Un mismo objeto puede jugar varios roles; IDDD discute modelarlo con interfaces por rol y advierte de que se puede complicar [IDDD cap. 5]. Antes de hacerlo, revisa si los roles pertenecen a contextos distintos: suele ser el caso (Cliente en Ventas, Destinatario en Almacén).