@archi-code/ddd 3.0.0-alpha.1 → 3.0.0-alpha.2

package/ddd-skills/ddd-repositorios-persistencia/references/transacciones-ts.md

@@ -11,10 +11,10 @@ Un caso de uso modifica un solo agregado y lo guarda una vez [IDDD cap. 10]. El
 Lo que hace el adaptador del repositorio, y nadie más:
 
 * Que cada `save` y cada `remove` sea atómico. En MongoDB, un documento por agregado: una sola escritura, atómica por sí misma. Si el agregado ocupa varias tablas SQL, el repositorio abre la transacción de la base de datos **dentro** de `save`/`remove`, con su propia conexión o sesión, y la confirma o la revierte antes de volver.
-* La comprobación optimista de la versión: una versión almacenada distinta de `order.version` (o un id ya ocupado al dar de alta) es `ConcurrencyException('Order', order.id.value, order.version)`.
+* La versión de concurrencia optimista, que es solo suya: recuerda la de cada agregado que cargó o guardó en un `WeakMap<Order, number>` privado (`versions`; `0` si no lo conoce, es nuevo). Una versión almacenada distinta de la recordada (o un id ya ocupado al dar de alta) es `ConcurrencyException('Order', order.id.value, version)`.
 * La conexión, la sesión y el pool.
 * Envolver los errores del driver en `InternalErrorException` con `{ cause }`.
-* `markPersisted()` tras escribir con éxito y, al cargar, `Order.fromPrimitives(row).restoreVersion(version)`.
+* `this.versions.set(order, version + 1)` solo tras escribir con éxito y, al cargar, `Order.fromPrimitives(...)` seguido de `this.versions.set(order, row.version)`. El agregado no declara ni mapea la versión y el caso de uso nunca la ve.
 
 ## Varias tablas en PostgreSQL
 
@@ -55,7 +55,8 @@ En `infrastructure/persistence/postgres-order-repository.ts`:
 
 ```ts
 import type { AggregateFinder, AggregateSaver, PrimitiveTypes } from '@archi-code/ddd/domain';
-import { ConcurrencyException, InternalErrorException } from '@archi-code/ddd/exceptions';
+import { ConcurrencyException } from '@archi-code/ddd/application';
+import { InternalErrorException } from '@archi-code/ddd/infrastructure';
 import { Order, OrderId } from '../../domain/order/order';
 import type { PgPool } from './pg-pool';
 
@@ -68,6 +69,8 @@ interface OrderRow {
 }
 
 export class PostgresOrderRepository implements AggregateFinder<Order>, AggregateSaver<Order> {
+  private readonly versions = new WeakMap<Order, number>();
+
   constructor(private readonly pool: PgPool) {}
 
   async findById(id: OrderId): Promise<Order | null> {
@@ -87,27 +90,33 @@ export class PostgresOrderRepository implements AggregateFinder<Order>, Aggregat
       [id.value],
     );
     const row = rows[0];
-    return row ? Order.fromPrimitives({ ...row.data, lines: { items: row.items } }).restoreVersion(row.version) : null;
+    if (row === undefined) {
+      return null;
+    }
+    const order = Order.fromPrimitives({ ...row.data, lines: { items: row.items } });
+    this.versions.set(order, row.version);
+    return order;
   }
 
   async save(order: Order): Promise<void> {
+    const version = this.versions.get(order) ?? 0;
     const { lines, ...data } = order.toPrimitives();
     const client = await this.pool.connect();
     let broken = false;
     try {
       await client.query('BEGIN');
       const { rowCount } =
-        order.version === 0
+        version === 0
           ? await client.query(
               'INSERT INTO orders (id, version, customer_id, status, data) VALUES ($1, 1, $2, $3, $4) ON CONFLICT (id) DO NOTHING',
               [data.id, data.customerId, data.status, data],
             )
           : await client.query(
               'UPDATE orders SET version = version + 1, status = $3, data = $4 WHERE id = $1 AND version = $2',
-              [data.id, order.version, data.status, data],
+              [data.id, version, data.status, data],
             );
       if (rowCount === 0) {
-        throw new ConcurrencyException('Order', order.id.value, order.version);
+        throw new ConcurrencyException('Order', order.id.value, version);
       }
       await client.query('DELETE FROM order_lines WHERE order_id = $1', [data.id]);
       for (const [position, line] of lines.items.entries()) {
@@ -128,14 +137,14 @@ export class PostgresOrderRepository implements AggregateFinder<Order>, Aggregat
     } finally {
       client.release(broken);
     }
-    order.markPersisted();
+    this.versions.set(order, version + 1);
   }
 }
 ```
 
 * La transacción empieza y termina dentro de `save`: el caso de uso solo ve una escritura que se hace entera o no se hace.
 * El `UPDATE` con `version = $2` bloquea la fila del pedido hasta el `COMMIT`; otro `save` del mismo pedido espera y después no casa ninguna fila, así que recibe `ConcurrencyException`.
-* `markPersisted()` se llama solo después del `COMMIT`: si la transacción se revierte, el objeto conserva su versión y el caso de uso puede descartarlo y volver a cargarlo.
+* `this.versions.set(order, version + 1)` se hace solo después del `COMMIT`: si la transacción se revierte, el repositorio sigue recordando la versión anterior y el caso de uso puede descartar el objeto y volver a cargarlo.
 * Si el `ROLLBACK` falla (la conexión se cayó), se relanza el error del trabajo, no el del `ROLLBACK`, y `release(true)` destruye la conexión en vez de devolver al pool una con la transacción a medias.
 * La lectura es una sola sentencia, así que ve el pedido y sus líneas en el mismo instante.
 * Un `remove` sigue el mismo patrón: `DELETE FROM orders WHERE id = $1 AND version = $2` dentro de su propia transacción (las líneas caen con `ON DELETE CASCADE`).
@@ -152,7 +161,7 @@ Cuando un evento no puede perderse, el repositorio escribe el agregado y sus eve
 for (const event of order.pullDomainEvents()) {
   await client.query('INSERT INTO order_outbox (event_id, body) VALUES ($1, $2)', [
     event.eventId,
-    event.toJSON(),
+    { ...event },
   ]);
 }
 ```
@@ -164,11 +173,9 @@ El repositorio toma los eventos con `pullDomainEvents()`, así que el `publish`
 El caso de uso carga, cambia, guarda y publica, sin abrir nada. Si el comando es seguro de repetir contra el estado recargado, la aplicación puede reintentar una o dos veces ante `ConcurrencyException`; si no, el conflicto llega al usuario como 409 [IDDD cap. 10; IDDD apéndice A]. Cada intento vuelve a cargar y vuelve a guardar dentro de `handle`, en un bucle con límite `[Fuera de los libros: convención de @archi-code/ddd]`. Un caso de uso que ejecuta un listener no reintenta por su cuenta: reintenta la reentrega del canal.
 
 ```ts
-import { UseCase } from '@archi-code/ddd/application';
+import { AggregateNotFoundException, ConcurrencyException, UseCase, ValueObjectBuilder } from '@archi-code/ddd/application';
 import type { Clock, EventBus } from '@archi-code/ddd/application';
-import { ValueObjects } from '@archi-code/ddd/domain';
 import type { AggregateFinder, AggregateSaver } from '@archi-code/ddd/domain';
-import { AggregateNotFoundException, ConcurrencyException } from '@archi-code/ddd/exceptions';
 import { Order, OrderId, OrderLine } from '../../domain/order/order';
 import type { OrderEvent } from '../../domain/order/order';
 
@@ -196,7 +203,7 @@ export class AddOrderLine extends UseCase<AddOrderLineInput, AddOrderLineCommand
   }
 
   protected toCommand(input: AddOrderLineInput): AddOrderLineCommand {
-    return ValueObjects.build({
+    return ValueObjectBuilder.build({
       orderId: () => new OrderId(input.orderId),
       line: () =>
         OrderLine.fromPrimitives({

package/ddd-skills/ddd-servicios-capa-aplicacion/GUIA.md

@@ -8,10 +8,10 @@
 
 [Fuera de los libros: convención de @archi-code/ddd]
 
-* Un caso de uso extiende `UseCase<Input, Command, Output>`: un `Input` de primitivos, un `Command` de value objects que construye `toCommand` con `ValueObjects.build` (informa de todos los campos a la vez), y `handle`, sin ayudas de la clase base, carga, cambia, guarda (`await this.orders.save(order)`) y publica (`await this.events.publish(order.pullDomainEvents())`). No hay puerto de transacciones: el caso de uso recibe solo los roles de repositorio que usa (`AggregateFinder`, `AggregateSaver`, `AggregateRemover`), `EventBus`, `Clock` y sus puertos propios, y el repositorio garantiza que cada `save` o `remove` es una escritura atómica. Una acción de negocio por caso de uso, con nombre de verbo del negocio (`PlaceOrder`, `AddOrderLine`).
+* Un caso de uso extiende `UseCase<Input, Command, Output>`: un `Input` de primitivos, un `Command` de value objects que construye `toCommand` con `ValueObjectBuilder.build` (informa de todos los campos a la vez), y `handle`, sin ayudas de la clase base, carga, cambia, guarda (`await this.orders.save(order)`) y publica (`await this.events.publish(order.pullDomainEvents())`). No hay puerto de transacciones: el caso de uso recibe solo los roles de repositorio que usa (`AggregateFinder`, `AggregateSaver`, `AggregateRemover`), `EventBus`, `Clock` y sus puertos propios, y el repositorio garantiza que cada `save` o `remove` es una escritura atómica. Una acción de negocio por caso de uso, con nombre de verbo del negocio (`PlaceOrder`, `AddOrderLine`).
 * Un caso de uso nunca importa ni llama a otro: las acciones se encadenan con eventos y listeners `<Acción>On<Evento>` decorados con `@ListensTo`, que solo mapean el evento a la entrada de un caso de uso. No hay bus de comandos: el punto de entrada llama a `execute(input)`.
 * Los servicios de dominio son clases sin base en `domain/` que reciben agregados y value objects, y pueden leer con un contrato `AggregateFinder` o un puerto de dominio; nunca guardan ni publican, y no tocan la persistencia.
-* Errores: `AggregateNotFoundException` (404) y `NotAllowedException` (403) en el caso de uso, `DomainException` con código propio en el dominio, y `HttpErrorMapper` en los puntos de entrada; `execute` envuelve cualquier error ajeno al paquete en `InternalErrorException` con `cause`.
+* Errores: `AggregateNotFoundException` (404) y `NotAllowedException` (403) en el caso de uso, `DomainException` con código propio en el dominio, y en los puntos de entrada `ExceptionClassifier.classify(error)`, cuyo `ExceptionKind` cada protocolo traduce a sus códigos; `execute` envuelve cualquier error ajeno al paquete en `UnexpectedErrorException` con `cause`.
 * Un `ConcurrencyException` se reintenta, si el comando es seguro de repetir, con un bucle en `handle` con un límite de intentos en el que cada intento vuelve a cargar el agregado y vuelve a guardarlo. Un caso de uso que ejecuta un listener no reintenta por sí mismo: reintenta la reentrega del canal.
 * Un caso de uso que ejecuta un listener para registrar un hecho no lanza si falta el agregado: retorna, para que el canal no lo reentregue sin fin.
 

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

@@ -5,11 +5,9 @@
 Un caso de uso extiende `UseCase<Input, Command, Output>` de `@archi-code/ddd/application`. `execute(input)` llama a `toCommand(input)` y después a `handle(command)`; no hay que escribir `execute`.
 
 ```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 { AggregateNotFoundException, NotAllowedException, UseCase, ValueObjectBuilder } from '@archi-code/ddd/application';
 import type { Clock, EventBus } from '@archi-code/ddd/application';
-import { AggregateNotFoundException, NotAllowedException } from '@archi-code/ddd/exceptions';
 
 export interface SalesPermissions {
   canCancelOrders(requester: CustomerId): Promise<boolean>;
@@ -18,7 +16,7 @@ export interface SalesPermissions {
 export interface CancelOrderInput {
   orderId: string;
   requesterId: string;
-  reason: string;
+  reason: string | null;
 }
 
 interface CancelOrderCommand {
@@ -40,10 +38,10 @@ export class CancelOrder extends UseCase<CancelOrderInput, CancelOrderCommand, v
   }
 
   protected toCommand(input: CancelOrderInput): CancelOrderCommand {
-    return ValueObjects.build({
+    return ValueObjectBuilder.build({
       orderId: () => new OrderId(input.orderId),
       requester: () => new CustomerId(input.requesterId),
-      reason: () => new CancellationReason(input.reason),
+      reason: () => new CancellationReason(input.reason as string),
     });
   }
 
@@ -72,7 +70,7 @@ Autorizar, cargar, invocar el dominio, guardar y publicar, y ninguna regla de ne
 ## Entrada
 
 * Primitivos o DTO o comando [PHP: Application, citando a Vernon]. Con el paquete, dos tipos por caso de uso `[Fuera de los libros: convención de @archi-code/ddd]`: el `Input`, plano y de primitivos (se puede serializar y encolar si un día hace falta [PHP: Application]), y el `Command`, de value objects, que construye `toCommand`.
-* La conversión a value objects ocurre en `toCommand` con `ValueObjects.build`: si algún campo no es válido lanza una sola `ValidationException` con el `field` y el `code` de cada problema (`ValueObjects.buildList` nombra los elementos de una lista por posición, `lines.1.quantity`), y `handle` no llega a ejecutarse.
+* La conversión a value objects ocurre en `toCommand` con `ValueObjectBuilder.build`: si algún campo no es válido lanza una sola `ValidationException` con el `field` y el `code` de cada problema (`ValueObjectBuilder.buildList` nombra los elementos de una lista por posición, `lines.1.quantity`), y `handle` no llega a ejecutarse.
 * El adaptador de entrada solo comprueba la forma de la petición (que un campo sea texto); las reglas de cada valor son de los value objects.
 * Nunca recibas el agregado desde el controlador.
 
@@ -93,7 +91,7 @@ Para pantallas, mejor una consulta de lectura aparte que devuelve un DTO sin pas
 
 ## Command bus
 
-*DDD in PHP* presenta el bus de comandos (Tactician) para enlazar cada comando con su manejador; los objetos request se parecen ya a comandos [PHP: Application]. El paquete no trae bus de comandos `[Fuera de los libros: convención de @archi-code/ddd]`: el composition root construye cada caso de uso y se lo pasa al punto de entrada, que llama a `execute(input)`. Lo común a todos los casos de uso ya está en `UseCase.execute` (dejar pasar las excepciones del paquete y envolver cualquier otro error en `InternalErrorException` con `cause`), y la atomicidad de cada escritura es del repositorio.
+*DDD in PHP* presenta el bus de comandos (Tactician) para enlazar cada comando con su manejador; los objetos request se parecen ya a comandos [PHP: Application]. El paquete no trae bus de comandos `[Fuera de los libros: convención de @archi-code/ddd]`: el composition root construye cada caso de uso y se lo pasa al punto de entrada, que llama a `execute(input)`. Lo común a todos los casos de uso ya está en `UseCase.execute` (dejar pasar las excepciones del paquete y envolver cualquier otro error en `UnexpectedErrorException` con `cause`), y la atomicidad de cada escritura es del repositorio.
 
 ## Eventos en la capa de aplicación
 
@@ -105,7 +103,8 @@ Para pantallas, mejor una consulta de lectura aparte que devuelve un DTO sin pas
 Cada repositorio comprueba la versión del agregado y lanza `ConcurrencyException` (409) si otro lo cambió después de cargarlo. Si el comando es seguro de repetir sobre el nuevo estado, el caso de uso puede reintentarlo [IDDD cap. 10; IDDD apéndice A]: un bucle en `handle` en el que cada intento vuelve a cargar el agregado y vuelve a guardarlo; pocos intentos y después se relanza. Un caso de uso que ejecuta un listener no reintenta por sí mismo: reintenta la reentrega del canal.
 
 ```ts
-import { ConcurrencyException, DomainException } from '@archi-code/ddd/exceptions';
+import { DomainException } from '@archi-code/ddd/domain';
+import { ConcurrencyException } from '@archi-code/ddd/application';
 
 export interface ProductPricing {
   priceForSale(sku: Sku): Promise<Money | null>;
@@ -130,7 +129,7 @@ export class AddOrderLine extends UseCase<AddOrderLineInput, AddOrderLineCommand
   }
 
   protected toCommand(input: AddOrderLineInput): AddOrderLineCommand {
-    return ValueObjects.build({
+    return ValueObjectBuilder.build({
       orderId: () => new OrderId(input.orderId),
       sku: () => new Sku(input.sku),
       quantity: () => new Quantity(input.quantity),
@@ -167,13 +166,14 @@ export class AddOrderLine extends UseCase<AddOrderLineInput, AddOrderLineCommand
 
 ## Errores
 
-* El dominio lanza `DomainException` con nombre y código propio (`class OrderCannotBeCancelled extends DomainException`, `super(message, ['ORD002'])`); los value objects y `ValueObjects.build` lanzan `ValidationException`.
+* El dominio lanza `DomainException` con nombre y código propio (`class OrderCannotBeCancelled extends DomainException`, `super(message, ['ORD002'])`); los value objects y `ValueObjectBuilder.build` lanzan `ValidationException`.
 * La aplicación añade las suyas: `AggregateNotFoundException('Order', id)` cuando `findById` devuelve `null`, `NotAllowedException(message)` cuando el solicitante no puede ejecutar la acción, `ApplicationException` para otros errores de aplicación. Al traducir otro error, siempre con `{ cause: error }`.
-* Los errores se dejan propagar: no se capturan en `handle` para relanzarlos; `execute` deja pasar las excepciones del paquete y envuelve el resto en `InternalErrorException`.
-* El punto de entrada los traduce con `HttpErrorMapper` de `@archi-code/ddd/infrastructure`: 404 `AggregateNotFoundException`, 403 `NotAllowedException`, 409 `ConcurrencyException`, 422 `ValidationException` y cualquier otra `DomainException` (regla de negocio), 400 otros errores de aplicación y 500, con mensaje genérico, para lo demás. Los códigos propios se ajustan por código (`new HttpErrorMapper({ statusByCode: { ORD001: 409 } })`) `[Fuera de los libros: convención de @archi-code/ddd]`.
+* Los errores se dejan propagar: no se capturan en `handle` para relanzarlos; `execute` deja pasar las excepciones del paquete y envuelve el resto en `UnexpectedErrorException` (de `@archi-code/ddd/application`).
+* El punto de entrada los clasifica con `ExceptionClassifier.classify(error)` de `@archi-code/ddd/infrastructure`, que no sabe de ningún protocolo: `NotFound` (`AggregateNotFoundException`), `NotAllowed` (`NotAllowedException`), `Conflict` (`ConcurrencyException`), `Malformed` (`TypePrimitiveException`, `RequiredValueException`), `Invalid` (`ValidationException` y cualquier otra `DomainException`), `Rejected` (otros errores de aplicación) e `Internal` (`UnexpectedErrorException`, `InvalidEventDefinitionException` y lo demás). Cada protocolo traduce el `ExceptionKind` a sus códigos (en HTTP: 404, 403, 409, 400, 422, 400 y 500), usa `error.code` para los códigos propios (`ORD001` → 409), oculta el mensaje de `Internal`, devuelve los `errors` de una `ValidationException` y registra él mismo los fallos internos `[Fuera de los libros: convención de @archi-code/ddd]`. Un controlador HTTP usa el `toHttpError` del proyecto (en `interfaces/http/`; completo en `ddd-skills/ddd-arquitectura/references/estructura-hexagonal-ts.md`):
 
 ```ts
-import type { HttpErrorMapper } from '@archi-code/ddd/infrastructure';
+import type { Logger } from '@archi-code/ddd/application';
+import { toHttpError } from './httpError';
 
 interface HttpRequest {
   params: { orderId: string };
@@ -189,7 +189,7 @@ interface HttpResponse {
 export class CancelOrderController {
   constructor(
     private readonly cancelOrder: CancelOrder,
-    private readonly errors: HttpErrorMapper,
+    private readonly logger: Logger,
   ) {}
 
   async cancel(request: HttpRequest): Promise<HttpResponse> {
@@ -197,11 +197,11 @@ export class CancelOrderController {
       await this.cancelOrder.execute({
         orderId: request.params.orderId,
         requesterId: request.auth.customerId,
-        reason: typeof request.body.reason === 'string' ? request.body.reason : '',
+        reason: typeof request.body.reason === 'string' ? request.body.reason : null,
       });
       return { status: 204 };
     } catch (error) {
-      return this.errors.map(error);
+      return toHttpError(error, this.logger);
     }
   }
 }
@@ -215,7 +215,7 @@ Con adaptadores en memoria: `InMemoryOrderRepository`, que el proyecto escribe e
 
 ```ts
 import { describe, expect, it } from 'vitest';
-import { NotAllowedException } from '@archi-code/ddd/exceptions';
+import { NotAllowedException } from '@archi-code/ddd/application';
 import {
   DomainEventBus,
   EventRegistry,
@@ -245,7 +245,7 @@ describe('Cancelling an order', () => {
     await cancelOrder.execute({ orderId, requesterId: laura, reason: 'Wrong size' });
 
     expect(channel.sent).toMatchObject([
-      { eventName: 'OrderCancelled', aggregateId: orderId, reason: 'Wrong size' },
+      { eventName: 'OrderCancelled', orderId, reason: 'Wrong size' },
     ]);
   });
 

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

@@ -33,9 +33,8 @@ total(): Money;
 Lo que añade Ventas en esta guía:
 
 ```ts
-import { AggregateRoot, BooleanType, Required, Specification, StringType } from '@archi-code/ddd/domain';
+import { AggregateRoot, BooleanType, DomainException, 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) {
@@ -123,11 +122,9 @@ export class OrderCancellation {
 `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 { AggregateNotFoundException, UseCase, ValueObjectBuilder } 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;
@@ -153,11 +150,11 @@ export class PlaceOrder extends UseCase<PlaceOrderInput, PlaceOrderCommand, stri
   }
 
   protected toCommand(input: PlaceOrderInput): PlaceOrderCommand {
-    return ValueObjects.build({
+    return ValueObjectBuilder.build({
       customerId: () => new CustomerId(input.customerId),
       lines: () =>
-        ValueObjects.buildList(input.lines, (line) =>
-          ValueObjects.build({
+        ValueObjectBuilder.buildList(input.lines, (line) =>
+          ValueObjectBuilder.build({
             sku: () => new Sku(line.sku),
             quantity: () => new Quantity(line.quantity),
           }),
@@ -206,20 +203,20 @@ Los gastos de envío se han dejado fuera de este caso de uso para mantenerlo ali
 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 { EventBase } 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 { EventListener, ListensTo, UseCase, ValueObjectBuilder } 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 reservationId: string,
     readonly orderId: string,
     metadata?: EventMetadata,
   ) {
-    super(reservationId, metadata);
+    super(metadata);
   }
 }
 
@@ -247,7 +244,7 @@ export class RegisterReservation extends UseCase<
   }
 
   protected toCommand(input: RegisterReservationInput): RegisterReservationCommand {
-    return ValueObjects.build({
+    return ValueObjectBuilder.build({
       orderId: () => new OrderId(input.orderId),
       reservationId: () => new ReservationId(input.reservationId),
     });
@@ -273,7 +270,7 @@ export class RegisterReservationOnStockReserved extends EventListener<StockReser
   async handle(event: StockReserved): Promise<void> {
     await this.registerReservation.execute({
       orderId: event.orderId,
-      reservationId: event.aggregateId,
+      reservationId: event.reservationId,
     });
   }
 }
@@ -301,7 +298,7 @@ describe('Registering the stock reservation of an order', () => {
     const orders = new InMemoryOrderRepository();
     const registry = new EventRegistry<StockReserved>().register(
       StockReserved,
-      (json) => new StockReserved(json.aggregateId, json.orderId as string, json),
+      (json) => new StockReserved(json.reservationId as string, json.orderId as string, json),
     );
     const channel = new InMemoryEventChannel();
     const bus = new DomainEventBus<StockReserved>(channel, registry);

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

@@ -14,9 +14,8 @@ Ejemplo de IDDD: autenticar a un usuario solo si su tenant está activo. Ponerlo
 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 { Composite, DomainException, 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'] } }])
@@ -79,7 +78,7 @@ export interface ExchangeRates {
 ```
 
 ```ts
-import { InternalErrorException } from '@archi-code/ddd/exceptions';
+import { InternalErrorException } from '@archi-code/ddd/infrastructure';
 
 interface EcbClient {
   rate(from: string, to: string, day: string): Promise<number>;
@@ -104,11 +103,11 @@ export class EcbExchangeRates implements ExchangeRates {
 
 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:
+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/exceptions';
-import type { ValidationIssue } from '@archi-code/ddd/exceptions';
+import { ValidationException } from '@archi-code/ddd/domain';
+import type { ValidationIssue } from '@archi-code/ddd/domain';
 
 export class ShipmentCheck {
   assertCanShip(order: Order, customer: Customer): void {

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

@@ -11,7 +11,7 @@
 * 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.
+* 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.
@@ -86,7 +86,7 @@ Recomendación por defecto: identidad generada por la aplicación, **temprana**
 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`.
+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
 
@@ -94,7 +94,7 @@ Revisa el diseño con los patrones de diseño flexible (Supple Design): interfac
 
 ## 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.
+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
 

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

@@ -43,7 +43,7 @@ const order = Order.place(OrderId.generate(), customerId, lines, shippingAddress
 
 ### 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.
+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
 
@@ -51,13 +51,12 @@ La identidad no cambia durante la vida de la entidad. IDDD la protege con un set
 
 ## 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.
+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, Entity, NumberType, Required, StringType } from '@archi-code/ddd/domain';
-import { DomainException } from '@archi-code/ddd/exceptions';
+import { BooleanType, DomainException, Entity, NumberType, Required, StringType } from '@archi-code/ddd/domain';
 
 export class SeatNumber extends Required(NumberType) {}
 export class SeatLabel extends Required(StringType) {}
@@ -97,9 +96,8 @@ Separar dos caminos evita que la carga desde base de datos vuelva a disparar reg
 
 ```ts
 import { Validations } from '@archi-code/validation';
-import { AggregateRoot, EnumType, EventBase, Required, StringType } from '@archi-code/ddd/domain';
+import { AggregateRoot, DomainException, 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) {}
 
@@ -127,11 +125,11 @@ export class CustomerBlocked extends EventBase {
   static readonly eventName = 'CustomerBlocked';
 
   constructor(
-    customerId: string,
+    readonly customerId: string,
     readonly reason: string,
     metadata?: EventMetadata,
   ) {
-    super(customerId, metadata);
+    super(metadata);
   }
 }
 
@@ -209,7 +207,7 @@ Fíjate en:
 * 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.
+* 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
 

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

@@ -27,7 +27,7 @@ Antes de convertir un valor en entidad "porque tiene tabla", responde [IDDD cap.
 ## 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()`).
+* 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(...)`, y la versión de concurrencia la recuerda él mismo en un `WeakMap<Order, number>`, nunca el agregado. 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.
 
@@ -49,7 +49,7 @@ interface OrderRow {
   version: number;
 }
 
-function rowOf(order: Order): OrderRow {
+function rowOf(order: Order, version: number): OrderRow {
   const primitives = order.toPrimitives();
   return {
     id: primitives.id,
@@ -61,7 +61,7 @@ function rowOf(order: Order): OrderRow {
     status: primitives.status,
     stock_reservation: primitives.stockReservation,
     payment_authorization: primitives.paymentAuthorization,
-    version: order.version + 1,
+    version: version + 1,
   };
 }
 
@@ -78,11 +78,11 @@ function orderOf(row: OrderRow): Order {
     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`.
+`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: `rowOf` recibe la que el repositorio recuerda para ese agregado en su `WeakMap` (`0` si es nuevo) y, tras cargar con `orderOf`, el repositorio anota `row.version` en ese `WeakMap`; la consulta con la condición de versión y cuándo se actualiza el `WeakMap` 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/validacion.md

@@ -24,15 +24,15 @@ Criterio práctico `[Fuera de los libros]`:
 
 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`).
+* **Entrada de un caso de uso:** `ValueObjectBuilder.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; `ValueObjectBuilder.buildList` nombra los elementos de una lista por su posición (`lines.1.quantity`).
 
 ```ts
-import { ValueObjects } from '@archi-code/ddd/domain';
+import { ValueObjectBuilder } from '@archi-code/ddd/application';
 
-const command = ValueObjects.build({
+const command = ValueObjectBuilder.build({
   customerId: () => new CustomerId(input.customerId),
   email: () => new Email(input.email),
-  lines: () => ValueObjects.buildList(input.lines, (line) => OrderLine.fromPrimitives(line)),
+  lines: () => ValueObjectBuilder.buildList(input.lines, (line) => OrderLine.fromPrimitives(line)),
 });
 // input { customerId: 'x', email: 'ana', lines: [...] } → una ValidationException:
 // errors: [
@@ -44,8 +44,8 @@ const command = ValueObjects.build({
 * **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';
+import { ValidationException } from '@archi-code/ddd/domain';
+import type { ValidationIssue } from '@archi-code/ddd/domain';
 
 export class ListingReadyToPublish {
   check(listing: ProductListing): void {
@@ -80,11 +80,11 @@ Un agregado puede estar en un estado intermedio legítimo en el que no procede v
 ## 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.
+* 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/domain`) con su código en el segundo argumento.
 * No uses `Error('invalid')` en el dominio.
 
 ```ts
-import { DomainException } from '@archi-code/ddd/exceptions';
+import { DomainException } from '@archi-code/ddd/domain';
 
 export class OrderMustHaveLines extends DomainException {
   constructor() {
@@ -93,4 +93,4 @@ export class OrderMustHaveLines extends DomainException {
 }
 ```
 
-`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 } })`).
+`error.code` es `'ORD002'`. En la entrada, `ExceptionClassifier.classify(error)` (de `@archi-code/ddd/infrastructure`) da el tipo de fallo sin tablas por excepción: `ExceptionKind.Invalid` para una `ValidationException` o cualquier `DomainException` (422 en HTTP) y `ExceptionKind.Malformed` para un error de conversión u obligatoriedad lanzado solo (400); el punto de entrada cambia el estado de un código cuando el negocio lo pide (`ORD001` → 409).

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

@@ -39,8 +39,7 @@ El ejemplo canónico de *DDD in PHP* (moneda e importe juntos) [PHP: Value Objec
 
 ```ts
 import { Validations } from '@archi-code/validation';
-import { Composite, NumberType, Required, StringType } from '@archi-code/ddd/domain';
-import { DomainException } from '@archi-code/ddd/exceptions';
+import { Composite, DomainException, NumberType, Required, StringType } from '@archi-code/ddd/domain';
 
 export class CurrencyMismatch extends DomainException {
   constructor(expected: string, received: string) {
@@ -374,4 +373,4 @@ describe('Money', () => {
 });
 ```
 
-`ValidationException` se importa de `@archi-code/ddd/exceptions`.
+`ValidationException` se importa de `@archi-code/ddd/domain`.