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

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,220 @@
+# 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`), 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 eventos (`record()`, `pullDomainEvents()`) y la `version` para concurrencia optimista, que solo tocan los repositorios.
+
+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, Entity, NumberType, Required, StringType } from '@archi-code/ddd/domain';
+import { DomainException } from '@archi-code/ddd/exceptions';
+
+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, EnumType, EventBase, Required, StringType } from '@archi-code/ddd/domain';
+import type { EventMetadata, PrimitiveTypes } from '@archi-code/ddd/domain';
+import { DomainException } from '@archi-code/ddd/exceptions';
+
+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(
+    customerId: string,
+    readonly reason: string,
+    metadata?: EventMetadata,
+  ) {
+    super(customerId, 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 lleva la base y la gestionan los repositorios.
+
+## 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).

package/ddd-skills/ddd-value-objects-entidades/references/persistencia-valores.md

@@ -0,0 +1,88 @@
+# Persistir value objects sin deformar el modelo
+
+## Principio
+
+El modelo de datos se subordina al de dominio. Claves, integridad referencial e índices no deben dictar cómo se modelan los objetos [IDDD cap. 6]. El informe y la analítica, mejor sobre un modelo de datos propio y no sobre las tablas de producción [IDDD cap. 6].
+
+Antes de convertir un valor en entidad "porque tiene tabla", responde [IDDD cap. 6]:
+1. ¿Es una cosa del dominio o mide, cuantifica o describe una cosa?
+2. ¿Tiene la mayoría de las características de valor?
+3. ¿Lo hago entidad solo porque el modelo de datos lo guarda como entidad?
+4. ¿El dominio exige identidad única, me importan los ejemplares y su continuidad de cambio?
+
+"Describe, sí, sí, no" → value object.
+
+## Opciones
+
+| Opción | Cuándo | Notas |
+|---|---|---|
+| Columnas en la fila del padre | Un único value object (`total_amount`, `total_currency`) | La opción por defecto y la más limpia [IDDD cap. 6] |
+| Varios valores serializados en una columna (JSON) | Colecciones pequeñas que no se consultan por dentro | Cuidado con el tamaño de columna y la consulta [IDDD cap. 6]. En PostgreSQL, `jsonb` |
+| Tabla propia para una colección | Colecciones grandes o que se consultan | La fila tiene clave técnica, pero en el modelo sigue siendo valor [IDDD cap. 6] |
+| Tabla de unión | Colecciones referenciadas | Variante de la anterior [IDDD cap. 6] |
+| Estado como enum | Tipos estándar | Guarda el código, no un objeto [IDDD cap. 6] |
+
+*DDD in PHP* resume las mismas alternativas (valor embebido, serialización como LOB y mapeo ad hoc con el ORM) [PHP: Value Objects].
+
+## En TypeScript
+
+`[Fuera de los libros: convención de @archi-code/ddd]`
+* Nada de mappers escritos a mano ni decoradores de ORM en las clases de dominio. El agregado da sus datos planos con `toPrimitives()` y se rehace con `static fromPrimitives()`; el repositorio solo llama a `order.toPrimitives()` y `Order.fromPrimitives(row).restoreVersion(version)`. Nada comprueba en ejecución que no se pierda ningún campo privado: lo prueba el spec del agregado con el viaje de ida y vuelta (`Order.fromPrimitives(order.toPrimitives()).toPrimitives()` igual a `order.toPrimitives()`).
+* Los primitivos ya dan la forma de cada opción de la tabla: un value object simple es su valor, un `Composite` es un objeto (`shippingAddress: { street, city, country }`), una lista de composites es una lista de objetos (`lines: { items: [...] }`) y un `EnumType` es la opción del enum (`status: 'pending'`).
+* Con un almacén de documentos (MongoDB), los primitivos se guardan tal cual. Con tablas, el repositorio decide cómo se reparten en columnas: el formato de la fila sigue en infraestructura y no deforma el modelo.
+
+```ts
+import type { PrimitiveTypes } from '@archi-code/ddd/domain';
+
+type OrderPrimitives = PrimitiveTypes<Order>;
+
+interface OrderRow {
+  id: string;
+  customer_id: string;
+  ship_street: string;
+  ship_city: string;
+  ship_country: string;
+  lines: OrderPrimitives['lines']['items'];
+  status: string;
+  stock_reservation: string | null;
+  payment_authorization: OrderPrimitives['paymentAuthorization'];
+  version: number;
+}
+
+function rowOf(order: Order): OrderRow {
+  const primitives = order.toPrimitives();
+  return {
+    id: primitives.id,
+    customer_id: primitives.customerId,
+    ship_street: primitives.shippingAddress.street,
+    ship_city: primitives.shippingAddress.city,
+    ship_country: primitives.shippingAddress.country,
+    lines: primitives.lines.items,
+    status: primitives.status,
+    stock_reservation: primitives.stockReservation,
+    payment_authorization: primitives.paymentAuthorization,
+    version: order.version + 1,
+  };
+}
+
+function orderOf(row: OrderRow): Order {
+  return Order.fromPrimitives({
+    id: row.id,
+    customerId: row.customer_id,
+    lines: { items: row.lines },
+    shippingAddress: {
+      street: row.ship_street,
+      city: row.ship_city,
+      country: row.ship_country,
+    },
+    status: row.status as Status,
+    stockReservation: row.stock_reservation,
+    paymentAuthorization: row.payment_authorization,
+  }).restoreVersion(row.version);
+}
+```
+
+`Order`, `ShippingAddress` y `Status` son los de `ddd-skills/ddd-agregados/references/implementacion-ts.md`. La dirección va en columnas de la fila del padre, las líneas y la autorización de pago en columnas JSON (`jsonb` en PostgreSQL) y el estado como su código. Con el driver `pg`, una columna `jsonb` se lee ya como objeto (la fecha de caducidad de la autorización llega como texto ISO, que `ExpiresAt` convierte), y al escribir el parámetro se pasa como `JSON.stringify(row.lines)` (un array sin convertir lo enviaría como array de PostgreSQL). La `version` se guarda junto a los primitivos, nunca dentro; la consulta con la condición de versión y `markPersisted()` están en `ddd-skills/ddd-repositorios-persistencia/GUIA.md`.
+
+* Al cargar, `fromPrimitives` rehace cada value object con su constructor, que valida: un dato corrupto falla al cargar (`ValidationException`) en vez de propagarse. No se repiten reglas de creación ni se registran eventos.
+* Con Prisma o Drizzle, el esquema es de infraestructura y el repositorio sigue pasando por `order.toPrimitives()` y `Order.fromPrimitives()`.

package/ddd-skills/ddd-value-objects-entidades/references/specification-y-diseno-flexible.md

@@ -0,0 +1,119 @@
+# Specification y diseño flexible (Supple Design)
+
+Contenido: 1. Diseño flexible · 2. Specification · 3. Specification para consultar · 4. Errores frecuentes
+
+## 1. Diseño flexible
+
+Conjunto de patrones de Evans para que el modelo sea fácil de usar y de cambiar. IDDD aplica varios de ellos de forma explícita; los que no aparecen en las fuentes del proyecto se marcan `[Fuera de los libros: Evans, Domain-Driven Design, 2003]`.
+
+### Intention Revealing Interfaces
+
+Los nombres de clases y métodos dicen **qué** consiguen, en el lenguaje ubicuo, no **cómo**. IDDD lo ilustra con `Tenant.activate()` y `deactivate()` en lugar de `setActive(boolean)`: varios setters para una sola petición vuelven ambigua la intención y complican publicar un único evento con significado [IDDD cap. 5, citando a Evans]. IDDD defiende también nombres fluidos (`valuePercentage()` frente a `getValuePercentage()`) [IDDD cap. 6].
+
+```ts
+order.setStatus('cancelled');
+price.amount.value * 21 / 100;
+```
+
+```ts
+order.cancel(new CancellationReason('customer request'), clock);
+price.percentage('21');
+```
+
+El primero revela cómo; el segundo, la intención (`CancellationReason` es un `Required(StringType)` con nombre y `percentage` el de `Money` en `ddd-skills/ddd-value-objects-entidades/references/value-objects-ts.md`).
+
+### Side-Effect-Free Functions
+
+Las operaciones que devuelven un resultado no cambian estado observable. En los value objects todos los métodos lo son, porque son inmutables [IDDD cap. 6]. Pasa solo valores como argumentos, no entidades: así se puede demostrar que no hay efectos secundarios [IDDD cap. 6]. Aplica también a entidades: separa consultas (devuelven algo, no cambian nada) de comandos (cambian estado, no devuelven datos de negocio).
+
+### Assertions
+
+`[Fuera de los libros: Evans 2003]`. Cuando una operación sí tiene efectos, haz explícitos sus resultados y las invariantes que mantiene: en los tests (tests de aceptación con lenguaje del negocio) y en guardas del código. IDDD trata las guardas de autoencapsulación como aserciones que protegen el estado [IDDD cap. 5].
+
+### Conceptual Contours
+
+`[Fuera de los libros: Evans 2003]`. Divide los objetos y operaciones siguiendo las líneas naturales del dominio, de modo que los cambios habituales del negocio afecten a una sola pieza. Señal práctica: si cada cambio de regla toca muchas clases a la vez, los contornos están mal trazados. Es la misma intuición que lleva a los "todos conceptuales" de los value objects [IDDD cap. 6].
+
+### Standalone Classes
+
+`[Fuera de los libros: Evans 2003]`. Reduce las dependencias de cada clase al mínimo imprescindible. Los value objects que solo dependen de su propio tipo y de sus atributos son el caso ideal, y IDDD recomienda exactamente eso [IDDD cap. 6].
+
+### Closure of Operations
+
+`[Fuera de los libros: Evans 2003]`. Cuando sea natural, una operación devuelve el mismo tipo que recibe: `Money.add(Money): Money`, `DateRange.extendTo(EndDate): DateRange`, `Specification.and(Specification): Specification`. Permite combinar operaciones sin introducir conceptos nuevos.
+
+## 2. Specification
+
+Un objeto que responde si otro objeto cumple un criterio del negocio. Evans y Fowler lo describen; IDDD lo propone como forma de implementar validadores de objetos completos [IDDD cap. 5, citando a Evans y Fowler] y *DDD in PHP* lo usa para consultar repositorios [PHP: Repositories; PHP: Factories].
+
+Tres usos clásicos `[Fuera de los libros: Evans 2003]`:
+1. **Validar:** ¿este objeto cumple la regla?
+2. **Seleccionar:** ¿qué objetos de una colección la cumplen?
+3. **Construir a la carta:** crear algo que cumpla la regla.
+
+Cuándo merece la pena: la regla tiene nombre en el lenguaje ("cliente moroso", "pedido apto para envío urgente"), se usa en varios sitios o se combina con otras. Si es una condición de una línea usada una vez, un método del agregado basta.
+
+No se escribe la base ni las combinaciones: `Specification<T>` viene de `@archi-code/ddd/domain`. Declara `isSatisfiedBy` como abstracto y da `and`, `or` y `not`, que devuelven otra `Specification<T>` (clausura de operaciones: se pueden seguir encadenando) y cortan en cuanto la respuesta está decidida. `and` y `or` aceptan cualquier `SatisfiedBy<T>` (un objeto con `isSatisfiedBy`), que es la interfaz `Specification` de los libros [IDDD cap. 5].
+
+Reglas de negocio con nombre:
+
+```ts
+import { Specification } from '@archi-code/ddd/domain';
+
+export interface StockSnapshot {
+  covers(sku: Sku, quantity: Quantity): boolean;
+}
+
+export class EligibleForExpressShipping extends Specification<Order> {
+  constructor(private readonly centralStock: StockSnapshot) {
+    super();
+  }
+
+  isSatisfiedBy(order: Order): boolean {
+    return (
+      order.shippingAddress.country.value === 'ES' &&
+      order.lines.items.every((line) => this.centralStock.covers(line.sku, line.quantity))
+    );
+  }
+}
+
+export class OrderAbove extends Specification<Order> {
+  constructor(private readonly threshold: Money) {
+    super();
+  }
+
+  isSatisfiedBy(order: Order): boolean {
+    return order.total().covers(this.threshold);
+  }
+}
+
+const freeExpress = new EligibleForExpressShipping(stock).and(
+  new OrderAbove(Money.fromPrimitives({ amount: 5000, currency: 'EUR' })),
+);
+freeExpress.isSatisfiedBy(order);
+```
+
+`Order`, `Money`, `Sku` y `Quantity` son los de `ddd-skills/ddd-agregados/references/implementacion-ts.md`. La especificación recibe datos de otros agregados ya cargados (`StockSnapshot`), no repositorios: misma regla que para los agregados [IDDD cap. 10].
+
+## 3. Specification para consultar
+
+*DDD in PHP* propone sustituir los métodos `find...` que crecen sin fin en los repositorios por un método `query(specification)` [PHP: Repositories; PHP: Factories]. Aquí no se hace: el repositorio solo obtiene y persiste, sin lógica ni consultas de negocio `[Fuera de los libros: convención de @archi-code/ddd]`. Una selección con nombre del negocio ("pedidos pendientes desde hace más de un día") es una consulta de lectura: una interfaz en `application/`, implementada en infraestructura directamente sobre la base de datos, que devuelve ids o DTOs.
+
+```ts
+export interface StaleOrders {
+  ids(pendingSince: Date, limit: number): Promise<OrderId[]>;
+}
+```
+
+La interfaz vive en `application/` y su implementación (`PgStaleOrders`, una consulta SQL; los filtros pueden escribirse con `@archi-code/criteria`) en infraestructura. Quien la usa (un programador de tareas, por ejemplo) ejecuta un caso de uso por cada id, y ese caso de uso carga el pedido con `AggregateFinder<Order>`.
+
+La Specification se queda para validar, seleccionar sobre datos ya cargados o construir.
+
+Úsalo con mesura `[Fuera de los libros]`: si acabas construyendo un lenguaje de consultas genérico, has reinventado el ORM. Para pantallas, mejor consultas de lectura (`ddd-skills/ddd-repositorios-persistencia/GUIA.md`).
+
+## 4. Errores frecuentes
+
+* Especificaciones genéricas sin nombre de negocio (`FieldEqualsSpecification`).
+* Especificaciones que cargan datos por su cuenta (inyectan repositorios).
+* Usar Specification para invariantes del agregado: la invariante se protege dentro del agregado, siempre; la especificación sirve para validar, seleccionar o construir.
+* Interfaces que revelan intención en el nombre pero no en el comportamiento: `confirm()` que en realidad también envía correos.

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

@@ -0,0 +1,96 @@
+# Validación
+
+## Tres niveles
+
+Que todos los atributos sean válidos no implica que el objeto lo sea, y que cada objeto sea válido no implica que su composición lo sea [IDDD cap. 5]. Por eso hay tres niveles [IDDD cap. 5; PHP: Entities]:
+
+| Nivel | Qué comprueba | Dónde |
+|---|---|---|
+| Atributo | Un valor aislado: formato, rango, obligatoriedad | Constructor del value object (`Required(...)` y `@Validations`); un `Composite` con reglas `custom` para lo que combina sus campos |
+| Objeto completo | Combinaciones de atributos de una entidad | La propia entidad en sus métodos, o un validador separado en el mismo módulo (un servicio de dominio o `Specification`s) |
+| Composición | Varios objetos o agregados juntos | Servicio de dominio que recibe lo cargado o lee por `AggregateFinder` |
+
+IDDD llama a lo del primer nivel más bien **aserciones** que protegen el estado, no "validación" en el sentido de un framework [IDDD cap. 5]. Con el paquete, un value object que existe es válido: su constructor convierte, comprueba `Required` y ejecuta todas sus reglas, y si falla alguna lanza una `ValidationException` con todas `[Fuera de los libros: convención de @archi-code/ddd]`. A eso se suma la autorización, que no es validación del modelo: la comprueba el caso de uso (`NotAllowedException`).
+
+## Objeto completo: ¿dentro o fuera de la entidad?
+
+IDDD advierte que meter toda la validación en la entidad le da demasiadas responsabilidades y que la validación suele cambiar más que la entidad; propone un validador separado (Specification o Strategy) en el mismo módulo, con validación diferida [IDDD cap. 5].
+
+Criterio práctico `[Fuera de los libros]`:
+* **Invariantes** (lo que nunca puede ser falso: un pedido sin líneas) → en la entidad o el agregado, siempre. Se tratan en `ddd-skills/ddd-agregados/GUIA.md`.
+* **Reglas de completitud o calidad** que dependen del momento ("para publicar, la ficha necesita al menos tres fotos") → validador separado, invocado cuando toca.
+
+## Patrón de notificación
+
+Para devolver todos los errores en vez de parar en el primero, IDDD y *DDD in PHP* usan un manejador de notificación que recibe los fallos [IDDD cap. 5; PHP: Entities]. Con el paquete no se escribe ese manejador `[Fuera de los libros: convención de @archi-code/ddd]`:
+
+* **Entrada de un caso de uso:** `ValueObjects.build({...})` ejecuta todas las factorías y lanza una sola `ValidationException` cuyos `errors` (`ValidationIssue`: `{ field, code, message }`) llevan el campo y el código de cada problema; `ValueObjects.buildList` nombra los elementos de una lista por su posición (`lines.1.quantity`).
+
+```ts
+import { ValueObjects } from '@archi-code/ddd/domain';
+
+const command = ValueObjects.build({
+  customerId: () => new CustomerId(input.customerId),
+  email: () => new Email(input.email),
+  lines: () => ValueObjects.buildList(input.lines, (line) => OrderLine.fromPrimitives(line)),
+});
+// input { customerId: 'x', email: 'ana', lines: [...] } → una ValidationException:
+// errors: [
+//   { field: 'customerId', code: 'DOM003', message: 'Validation Error: Expected a valid UUID, but received "x".' },
+//   { field: 'email', code: 'isEmail', message: 'Email: Value does not satisfy isEmail' },
+// ]
+```
+
+* **Un objeto ya construido** (la ficha de un producto que se quiere publicar, en el contexto de Catálogo): un servicio de dominio recoge los `ValidationIssue` y lanza una sola `new ValidationException(issues)`.
+
+```ts
+import { ValidationException } from '@archi-code/ddd/exceptions';
+import type { ValidationIssue } from '@archi-code/ddd/exceptions';
+
+export class ListingReadyToPublish {
+  check(listing: ProductListing): void {
+    const issues: ValidationIssue[] = [];
+    if (listing.photos.value < 3) {
+      issues.push({ field: 'photos', code: 'tooFewPhotos', message: 'At least 3 photos' });
+    }
+    if (!listing.description.isLongEnough()) {
+      issues.push({ field: 'description', code: 'tooShort', message: 'Describe the product' });
+    }
+    if (listing.price.isZero()) {
+      issues.push({ field: 'price', code: 'zeroPrice', message: 'A listing needs a price' });
+    }
+    if (issues.length > 0) {
+      throw new ValidationException(issues);
+    }
+  }
+}
+```
+
+`ProductListing` es un agregado con `photos` (`PhotoCount`), `description` (`ListingDescription`, con su método `isLongEnough()`) y `price` (`Money`). Nunca captures la `ValidationException` de un value object para quedarte con un valor inválido.
+
+## Validación diferida y estados intermedios
+
+Un agregado puede estar en un estado intermedio legítimo en el que no procede validar. Se puede modelar con un estado y publicar un evento cuando la validación ya tiene sentido [IDDD cap. 5].
+
+## Interfaz frente a dominio
+
+* La interfaz valida formato para dar buena experiencia (campo vacío, longitud). Eso no sustituye a la validación del modelo, donde vive el conocimiento profundo [IDDD cap. 4].
+* No dupliques reglas de negocio en el esquema del DTO. Si el DTO comprueba "email válido" y `new Email(...)` también, que el DTO solo compruebe que es un `string` y deje la regla al value object `[Fuera de los libros]`. La entrada de un caso de uso llega sin validar a propósito: `toCommand` construye los value objects, así que todos los adaptadores pasan por las mismas reglas.
+
+## Errores con nombre
+
+`[Fuera de los libros]`
+* Una clase de error por regla de negocio (`OrderMustHaveLines`, `CurrencyMismatch`), con un código estable para traducir a mensajes de usuario y a códigos HTTP en el adaptador. Con el paquete, una subclase de `DomainException` (de `@archi-code/ddd/exceptions`) con su código en el segundo argumento.
+* No uses `Error('invalid')` en el dominio.
+
+```ts
+import { DomainException } from '@archi-code/ddd/exceptions';
+
+export class OrderMustHaveLines extends DomainException {
+  constructor() {
+    super('An order needs at least one line', ['ORD002']);
+  }
+}
+```
+
+`error.code` es `'ORD002'`. En la entrada, `HttpErrorMapper` (de `@archi-code/ddd/infrastructure`) traduce sin tablas escritas a mano: 422 para una `ValidationException` o cualquier `DomainException`, 400 para un error de conversión u obligatoriedad lanzado solo, y cambios por código cuando el negocio lo pide (`new HttpErrorMapper({ statusByCode: { ORD001: 409 } })`).