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

package/ddd-skills/ddd-arquitectura/references/estructura-hexagonal-ts.md

@@ -48,6 +48,7 @@ src/
       interfaces/
         http/
           ordersRouter.ts
+          httpError.ts             (traduce ExceptionKind a estado HTTP)
         messaging/
           StockReservedConsumer.ts (traduce el contrato publicado por Almacén al input de un caso de uso)
       composition.ts               ← composition root del contexto
@@ -64,7 +65,7 @@ test/
     infrastructure/                (integración con BD real o contenedor)
 ```
 
-Lo que no aparece porque lo da `@archi-code/ddd`: clases base (`AggregateRoot`, `Entity`, `EventBase`, los tipos de value object, `Composite`), una interfaz `OrderRepository` (los roles `AggregateFinder`, `AggregateSaver` y `AggregateRemover` vienen de `@archi-code/ddd/domain`), un `OrderMapper` (la conversión es del agregado, `toPrimitives()` y `static fromPrimitives()`, y cada repositorio los llama directamente: guarda `order.toPrimitives()` con `order.version + 1` y carga con `Order.fromPrimitives(row).restoreVersion(row.version)`), un publicador de eventos (`DomainEventBus` implementa `EventBus`) y el puerto `Clock`. Tampoco hay un runner de transacciones ni una unidad de trabajo: la transacción es del repositorio `[Fuera de los libros: convención de @archi-code/ddd]`.
+Lo que no aparece porque lo da `@archi-code/ddd`: clases base (`AggregateRoot`, `Entity`, `EventBase`, los tipos de value object, `Composite`), una interfaz `OrderRepository` (los roles `AggregateFinder`, `AggregateSaver` y `AggregateRemover` vienen de `@archi-code/ddd/domain`), un `OrderMapper` (la conversión es del agregado, `toPrimitives()` y `static fromPrimitives()`, y cada repositorio los llama directamente: guarda `order.toPrimitives()` con la versión siguiente al lado y carga con `Order.fromPrimitives(row.primitives)`; la versión la recuerda el propio repositorio en un `WeakMap<Order, number>`, nunca el agregado), un publicador de eventos (`DomainEventBus` implementa `EventBus`) y el puerto `Clock`. Tampoco hay un runner de transacciones ni una unidad de trabajo: la transacción es del repositorio `[Fuera de los libros: convención de @archi-code/ddd]`.
 
 Lo que el paquete no da y escribe el proyecto: cada repositorio, uno por agregado. Su constructor recibe solo las dependencias de su tecnología (la `collection` de Mongo, el `pool` de Postgres), nunca la clase del agregado ni un mapper; el agregado solo entra y sale por sus métodos. Nada comprueba en ejecución la forma del agregado: que su estado sean value objects expuestos por getters y que `toPrimitives()`/`fromPrimitives()` no pierdan campos lo garantizan el agregado y su test de ida y vuelta. El repositorio en memoria también es del proyecto y es un doble de test: vive en `test/support/`, nunca en `src/` (ver `InMemoryOrderRepository` en `ddd-skills/ddd-repositorios-persistencia/references/tests-repositorios.md`) `[Fuera de los libros: convención de @archi-code/ddd]`.
 
@@ -116,7 +117,6 @@ import { MongoClient } from 'mongodb';
 import {
   DomainEventBus,
   EventRegistry,
-  HttpErrorMapper,
   SystemClock,
 } from '@archi-code/ddd/infrastructure';
 import { OrderLineAdded, OrderPlaced } from './domain/order/events';
@@ -152,7 +152,7 @@ export async function composeSales(
       OrderPlaced,
       (json) =>
         new OrderPlaced(
-          json.aggregateId,
+          json.orderId as string,
           json.customerId as string,
           json.lines as OrderLineData[],
           json.total as MoneyData,
@@ -163,7 +163,7 @@ export async function composeSales(
       OrderLineAdded,
       (json) =>
         new OrderLineAdded(
-          json.aggregateId,
+          json.orderId as string,
           json.sku as string,
           json.quantity as number,
           json.unitPrice as MoneyData,
@@ -188,10 +188,7 @@ export async function composeSales(
   ];
 
   return {
-    httpRouter: ordersRouter(
-      { placeOrder, addOrderLine },
-      new HttpErrorMapper({ statusByCode: { ORD001: 409 }, logger: deps.logger }),
-    ),
+    httpRouter: ordersRouter({ placeOrder, addOrderLine }, deps.logger),
     close: async () => {
       await Promise.all(subscriptions.map((subscription) => subscription.unsubscribe()));
       await mongo.close();
@@ -201,8 +198,8 @@ export async function composeSales(
 ```
 
 Qué hace cada pieza:
-* Del paquete, en `@archi-code/ddd/infrastructure`: `EventRegistry` (reconstruye cada evento desde su JSON; la factoría pasa el JSON como metadata para conservar `eventId` y `occurredOn`), `DomainEventBus` (implementa `EventBus`, lo único que reciben los casos de uso; su `subscribe(listener)` solo lo llama el composition root), `SystemClock` (implementa `Clock`) y `HttpErrorMapper` (códigos propios como `ORD001` se sobrescriben por código).
-* Código del proyecto sobre los puertos del paquete `[Fuera de los libros: convención de @archi-code/ddd]`: `MongoOrderRepository` (roles de repositorio de `Order`; su constructor recibe solo la `collection`; llama a `order.toPrimitives()` y a `Order.fromPrimitives(row).restoreVersion(row.version)` y controla la `version`; responsable de toda la persistencia: cada `save`/`remove` es una escritura atómica de un documento, y si un agregado ocupara varias tablas SQL abriría y cerraría la transacción de la base de datos dentro de `save`/`remove`; ver `ddd-skills/ddd-repositorios-persistencia/GUIA.md`), `RabbitMqEventChannel` (implementa `EventChannel`, ver `ddd-skills/ddd-eventos-dominio/GUIA.md`) y `HttpWarehouse` (implementa el puerto `Warehouse`).
+* Del paquete, en `@archi-code/ddd/infrastructure`: `EventRegistry` (reconstruye cada evento desde su JSON; la factoría pasa el JSON como metadata para conservar `eventId` y `occurredOn`), `DomainEventBus` (implementa `EventBus`, lo único que reciben los casos de uso; su `subscribe(listener)` solo lo llama el composition root), y `SystemClock` (implementa `Clock`).
+* Código del proyecto sobre los puertos del paquete `[Fuera de los libros: convención de @archi-code/ddd]`: `MongoOrderRepository` (roles de repositorio de `Order`; su constructor recibe solo la `collection`; llama a `order.toPrimitives()` y a `Order.fromPrimitives(row.primitives)` y controla la versión, que recuerda por agregado en un `WeakMap` y guarda junto a los primitivos; responsable de toda la persistencia: cada `save`/`remove` es una escritura atómica de un documento, y si un agregado ocupara varias tablas SQL abriría y cerraría la transacción de la base de datos dentro de `save`/`remove`; ver `ddd-skills/ddd-repositorios-persistencia/GUIA.md`), `RabbitMqEventChannel` (implementa `EventChannel`, ver `ddd-skills/ddd-eventos-dominio/GUIA.md`) y `HttpWarehouse` (implementa el puerto `Warehouse`).
 * Cada listener se suscribe con `bus.subscribe(listener)`, que lee su `@ListensTo(OrderLineAdded, { consumer: 'prepare-shipment-on-order-line-added' })` y rechaza un evento que el registro no sabe reconstruir.
 * Cambiar RabbitMQ por un outbox o por memoria cambia solo la línea del canal.
 * Ni los casos de uso ni los repositorios reciben un runner de transacciones: el composition root no construye ninguno.
@@ -236,7 +233,7 @@ export async function salesForTests(warehouse: Warehouse) {
     OrderLineAdded,
     (json) =>
       new OrderLineAdded(
-        json.aggregateId,
+        json.orderId as string,
         json.sku as string,
         json.quantity as number,
         json.unitPrice as MoneyData,
@@ -264,18 +261,19 @@ El test comprueba lo que causó el listener (el `Warehouse` de prueba) y lo que
 // src/contexts/sales/interfaces/http/ordersRouter.ts
 import { Router } from 'express';
 import type { Response } from 'express';
-import type { HttpErrorMapper } from '@archi-code/ddd/infrastructure';
+import type { Logger } from '@archi-code/ddd/application';
 import type { AddOrderLine } from '../../application/add-order-line/AddOrderLine';
 import type { PlaceOrder } from '../../application/place-order/PlaceOrder';
+import { toHttpError } from './httpError';
 
 export function ordersRouter(
   useCases: { placeOrder: PlaceOrder; addOrderLine: AddOrderLine },
-  errors: HttpErrorMapper,
+  logger: Logger,
 ): Router {
   const router = Router();
 
   const fail = (res: Response, error: unknown) => {
-    const { status, body } = errors.map(error);
+    const { status, body } = toHttpError(error, logger);
     return res.status(status).json(body);
   };
 
@@ -340,13 +338,69 @@ export function ordersRouter(
 }
 ```
 
-El controlador no sabe qué es un `Order`. Comprueba solo la forma de la petición (un campo es texto o número) [IDDD cap. 4]; las reglas de cada valor son de los value objects que `toCommand` construye con `ValueObjects.build`, y llegan como una `ValidationException` con todos los campos (422). La identidad del cliente sale del token, no del body. `HttpErrorMapper` traduce los errores: 404 `AggregateNotFoundException`, 403 `NotAllowedException`, 409 `ConcurrencyException`, 422 `ValidationException` y cualquier otra `DomainException`, 500 con un mensaje genérico para lo demás. Con `logger`, el mapper registra cada 5xx una vez como `error` (con su causa) y los 4xx solo en `debug`; el controlador no vuelve a registrarlos.
+El controlador no sabe qué es un `Order`. Comprueba solo la forma de la petición (un campo es texto o número) [IDDD cap. 4]; las reglas de cada valor son de los value objects que `toCommand` construye con `ValueObjectBuilder.build`, y llegan como una `ValidationException` con todos los campos (422). La identidad del cliente sale del token, no del body. `toHttpError` traduce los errores. El paquete no trae nada de HTTP: `ExceptionClassifier.classify(error)` de `@archi-code/ddd/infrastructure` devuelve el `ExceptionKind` del fallo y cada protocolo (HTTP, un consumidor de mensajes, una CLI) lo traduce a sus códigos `[Fuera de los libros: convención de @archi-code/ddd]`:
+
+```ts
+// src/contexts/sales/interfaces/http/httpError.ts
+import { DomainException, ValidationException } from '@archi-code/ddd/domain';
+import type { ValidationIssue } from '@archi-code/ddd/domain';
+import { ApplicationException, ApplicationExceptionCode } from '@archi-code/ddd/application';
+import type { Logger } from '@archi-code/ddd/application';
+import {
+  ExceptionClassifier,
+  ExceptionKind,
+  InfrastructureException,
+} from '@archi-code/ddd/infrastructure';
+
+export interface HttpError {
+  status: number;
+  body: { code: string; message: string; errors?: readonly ValidationIssue[] };
+}
+
+const STATUS_BY_KIND: Readonly<Record<ExceptionKind, number>> = {
+  [ExceptionKind.NotFound]: 404,
+  [ExceptionKind.NotAllowed]: 403,
+  [ExceptionKind.Conflict]: 409,
+  [ExceptionKind.Malformed]: 400,
+  [ExceptionKind.Invalid]: 422,
+  [ExceptionKind.Rejected]: 400,
+  [ExceptionKind.Internal]: 500,
+};
+
+const STATUS_BY_CODE = new Map<string, number>([['ORD001', 409]]);
+
+type PackageException = DomainException | ApplicationException | InfrastructureException;
+
+function isPackageException(error: unknown): error is PackageException {
+  return (
+    error instanceof DomainException ||
+    error instanceof ApplicationException ||
+    error instanceof InfrastructureException
+  );
+}
+
+export function toHttpError(error: unknown, logger: Logger): HttpError {
+  const code = isPackageException(error) ? error.code : ApplicationExceptionCode.UnexpectedError;
+  const status = STATUS_BY_CODE.get(code) ?? STATUS_BY_KIND[ExceptionClassifier.classify(error)];
+  if (status >= 500 || !isPackageException(error)) {
+    logger.error('http_request_failed', { status, code, error });
+    return { status, body: { code, message: 'Internal server error' } };
+  }
+  logger.debug('http_request_rejected', { status, code });
+  if (error instanceof ValidationException) {
+    return { status, body: { code, message: error.message, errors: error.errors } };
+  }
+  return { status, body: { code, message: error.message } };
+}
+```
+
+En HTTP: 404 `AggregateNotFoundException`, 403 `NotAllowedException`, 409 `ConcurrencyException`, 400 un error de conversión u obligatoriedad, 422 `ValidationException` y cualquier otra `DomainException`, 400 otros errores de aplicación y 500 con un mensaje genérico para lo demás (también `UnexpectedErrorException`, el error ajeno que `UseCase.execute` envuelve); los códigos propios (`ORD001`) se resuelven antes que el tipo. Cada 5xx se registra una vez como `error` (con su causa) y los 4xx solo en `debug`; el controlador no vuelve a registrarlos. Un consumidor de mensajes traduce el mismo `ExceptionKind` a confirmar, descartar o reintentar.
 
 ## Configuración de TypeScript
 
 `[Fuera de los libros]`
 * `strict: true`. El dominio se apoya en el tipado para expresar invariantes.
 * `experimentalDecorators: true`: `@Validations` (value objects) y `@ListensTo` (listeners) son decoradores de clase.
-* `moduleResolution` `node16`, `nodenext` o `bundler` para resolver los subpaths `@archi-code/ddd/domain`, `/application`, `/infrastructure` y `/exceptions`; con `node` los resuelve el `typesVersions` del paquete.
+* `moduleResolution` `node16`, `nodenext` o `bundler` para resolver los subpaths `@archi-code/ddd/domain`, `/application` y `/infrastructure` (cada uno exporta las excepciones de su capa); con `node` los resuelve el `typesVersions` del paquete.
 * Alias por contexto (`"@sales/*": ["src/contexts/sales/*"]`, usado como `@sales/domain/order/Order`) para que los imports revelen la zona.
 * `exactOptionalPropertyTypes` y `noUncheckedIndexedAccess` ayudan a que los value objects no acepten estados a medias.

package/ddd-skills/ddd-auditoria-refactorizacion/GUIA.md

@@ -9,7 +9,7 @@
 [Fuera de los libros: convención de @archi-code/ddd]
 
 * En código hecho con el paquete, aplica además cada punto de `ddd-skills/archi-code-ddd/what-not-to-do.md` como lista de comprobación: el paquete da las clases base, pero no impide un agregado anémico con setters, un caso de uso CRUD, dos agregados guardados en el mismo caso de uso o un caso de uso que abre su propia transacción (la transacción es del repositorio).
-* La dirección de dependencias es la del paquete: el dominio importa solo `@archi-code/ddd/domain`, `@archi-code/ddd/exceptions` y `@archi-code/validation`; importar `/application` o `/infrastructure` (por ejemplo `SystemClock`) o un adaptador de `infrastructure/` del proyecto desde el dominio es un hallazgo de severidad alta (A8 de la lista).
+* La dirección de dependencias es la del paquete: el dominio importa solo `@archi-code/ddd/domain` (que exporta también las excepciones de dominio) y `@archi-code/validation`; importar `/application` o `/infrastructure` (por ejemplo `SystemClock`) o un adaptador de `infrastructure/` del proyecto desde el dominio es un hallazgo de severidad alta (A8 de la lista).
 * El reloj es un puerto (`Clock`; `FixedClock` en tests): `new Date()` en dominio o aplicación es un hallazgo (A9).
 * El escáner detecta guardados de cualquier variable (`this.orders.save(...)`, `this.customers.remove(...)`) dentro del mismo bloque transaccional o de la misma clase de aplicación, transacciones abiertas o recibidas en dominio y aplicación (bloques transaccionales, `startSession`, runners de transacciones, unidades de trabajo), imports de `@archi-code/ddd/application` o `/infrastructure` desde el dominio, `new Date()` en dominio y aplicación, y campos de estado primitivos con el prefijo `_` del paquete (`private _status: string`). Marca `amount: number` o `status: string` también dentro de los eventos: ahí son esperables, porque el payload de un evento son primitivos.
 

package/ddd-skills/ddd-auditoria-refactorizacion/references/ejemplo-auditoria.md

@@ -85,7 +85,7 @@ class PlaceOrder extends UseCase<PlaceOrderInput, PlaceOrderCommand, void> {
 | 5 | Estado y total como primitivos (`_status: string`, `_total: number`) en vez de value objects | `domain/order/order.ts:5-6` | Media |
 | 6 | `toCommand` devuelve el input tal cual: ningún value object se construye ni valida antes de `handle` | `application/update-order/update-order.ts:14` | Media |
 | 7 | `new Date()` en el agregado: fechas no deterministas en tests | `domain/order/order.ts:10` | Media |
-| 8 | `throw new Error(...)` en vez de una `DomainException` con código: el `HttpErrorMapper` responde 500 | `application/update-order/update-order.ts:18` | Media |
+| 8 | `throw new Error(...)` en vez de una `DomainException` con código: `ExceptionClassifier` lo clasifica como `ExceptionKind.Internal` y el cliente recibe 500 | `application/update-order/update-order.ts:18` | Media |
 | 9 | Los casos de uso reciben un `UnitOfWork` del proyecto y abren la transacción con `unitOfWork.run`: la transacción y todo lo de persistencia son del adaptador del repositorio, que hace atómico cada `save` | `application/update-order/update-order.ts:17`, `application/place-order/place-order.ts:27` | Media |
 
 Los hallazgos 2, 3 y 6 se cruzan además con `ddd-skills/archi-code-ddd/what-not-to-do.md` (casos de uso CRUD, value objects fuera de `toCommand`, reglas de negocio fuera del agregado).
@@ -108,10 +108,8 @@ addLine(line: OrderLine, clock: { now(): Date }): void;
 Enviar no es trabajo del pedido de Ventas: lo hace `Shipment` en Almacén, que publica `ShipmentDispatched` (`ddd-skills/ddd-agregados/references/ejemplo-ecommerce.md`), así que `status: 'shipped'` y su errata desaparecen de Ventas. `UpdateOrder` se parte en un caso de uso por acción de negocio (`AddOrderLine` aquí; el envío, en Almacén); cada uno construye sus value objects en `toCommand` y guarda un solo agregado:
 
 ```ts
-import { ValueObjects } from '@archi-code/ddd/domain';
 import type { AggregateFinder, AggregateSaver } from '@archi-code/ddd/domain';
-import { AggregateNotFoundException } from '@archi-code/ddd/exceptions';
-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';
 
 interface AddOrderLineInput {
@@ -136,7 +134,7 @@ class AddOrderLine extends UseCase<AddOrderLineInput, AddOrderLineCommand, void>
   }
 
   protected toCommand(input: AddOrderLineInput): AddOrderLineCommand {
-    return ValueObjects.build({
+    return ValueObjectBuilder.build({
       orderId: () => new OrderId(input.orderId),
       line: () =>
         OrderLine.fromPrimitives({
@@ -198,7 +196,7 @@ class PlaceOrder extends UseCase<PlaceOrderInput, PlaceOrderCommand, void> {
   }
 
   protected toCommand(input: PlaceOrderInput): PlaceOrderCommand {
-    return ValueObjects.build({
+    return ValueObjectBuilder.build({
       orderId: () => new OrderId(input.orderId),
       customerId: () => new CustomerId(input.customerId),
       lines: () => OrderLines.fromPrimitives({ items: input.lines }),
@@ -225,7 +223,7 @@ class AwardLoyaltyPoints extends UseCase<AwardLoyaltyPointsInput, AwardLoyaltyPo
   }
 
   protected toCommand(input: AwardLoyaltyPointsInput): AwardLoyaltyPointsCommand {
-    return ValueObjects.build({
+    return ValueObjectBuilder.build({
       customerId: () => new CustomerId(input.customerId),
       orderId: () => new OrderId(input.orderId),
     });
@@ -250,7 +248,7 @@ class AwardLoyaltyPointsOnOrderPlaced extends EventListener<OrderPlaced> {
   async handle(event: OrderPlaced): Promise<void> {
     await this.awardLoyaltyPoints.execute({
       customerId: event.customerId,
-      orderId: event.aggregateId,
+      orderId: event.orderId,
     });
   }
 }
@@ -266,7 +264,7 @@ import {
   FixedClock,
   InMemoryEventChannel,
 } from '@archi-code/ddd/infrastructure';
-import { ValidationException } from '@archi-code/ddd/exceptions';
+import { ValidationException } from '@archi-code/ddd/domain';
 import { InMemoryCustomerRepository } from '../support/in-memory-customer-repository';
 import { InMemoryOrderRepository } from '../support/in-memory-order-repository';
 
@@ -276,7 +274,7 @@ const registry = new EventRegistry<OrderEvent>().register(
   OrderPlaced,
   (json) =>
     new OrderPlaced(
-      json.aggregateId,
+      json.orderId as string,
       json.customerId as string,
       json.lines as OrderLineData[],
       json.total as MoneyData,
@@ -311,6 +309,6 @@ await expect(
 ## Plan
 
 * **Fase 0:** tests de caracterización de alta, envío y puntos de fidelidad sobre `InMemoryOrderRepository` e `InMemoryCustomerRepository` (dobles de test del proyecto en `test/support/`), `InMemoryEventChannel` y `FixedClock`.
-* **Fase 1:** borrar `OrderMapper`: la conversión pasa al agregado (`toPrimitives()` y `static fromPrimitives()`, con un test de ida y vuelta) y `MongoOrderRepository` la llama directamente (su constructor recibe solo la `collection`), sustituir `new Date()` por el `Clock` inyectado y `Error` por `DomainException` con código; `HttpErrorMapper` responde 422 a las reglas de negocio. Quitar el `UnitOfWork` de los casos de uso: `MongoOrderRepository` hace atómico cada `save` (una escritura de un documento con condición de versión) y los casos de uso solo reciben roles de repositorio, `EventBus` y `Clock`.
+* **Fase 1:** borrar `OrderMapper`: la conversión pasa al agregado (`toPrimitives()` y `static fromPrimitives()`, con un test de ida y vuelta) y `MongoOrderRepository` la llama directamente (su constructor recibe solo la `collection`), sustituir `new Date()` por el `Clock` inyectado y `Error` por `DomainException` con código; `ExceptionClassifier` clasifica las reglas de negocio como `ExceptionKind.Invalid` (422 en HTTP). Quitar el `UnitOfWork` de los casos de uso: `MongoOrderRepository` hace atómico cada `save` (una escritura de un documento con condición de versión) y los casos de uso solo reciben roles de repositorio, `EventBus` y `Clock`.
 * **Fase 2:** `OrderStatus`, `OrderLines` (con `OrderLine` y `Money`) como value objects; `addLine` sustituye a los setters; `UpdateOrder` se parte en `AddOrderLine` y el envío pasa a `Shipment` en Almacén.
 * **Fase 3:** `PlaceOrder` guarda solo el pedido; `AwardLoyaltyPointsOnOrderPlaced` ejecuta `AwardLoyaltyPoints` por evento. Para que `OrderPlaced` no se pierda si el proceso cae entre `save` y `publish`, `MongoOrderRepository` escribe el pedido y sus eventos pendientes en el mismo documento (outbox) y un relay los entrega después por el `EventChannel`; los casos de uso no cambian.

package/ddd-skills/ddd-auditoria-refactorizacion/references/lista-comprobacion.md

@@ -12,7 +12,7 @@ La columna "Script" indica si `scan_ddd_smells.py` lo detecta (sí / parcial / n
 | E4 | ¿Las integraciones con sistemas externos pasan por una ACL (puerto del dominio con value objects, adaptador y traductor en `infrastructure/`)? | [Destilado cap. 4] | no | Alta |
 | E5 | ¿Hay cadenas de llamadas síncronas entre servicios dentro de una petición? | [Destilado cap. 4] | no | Alta |
 | E6 | ¿Usuarios y permisos mezclados en el modelo del núcleo? La autorización va en el caso de uso (`NotAllowedException`), no en el agregado | [IDDD cap. 2] | no | Media |
-| E7 | ¿Se envía `event.toJSON()` de un evento de dominio a otro contexto en vez de un contrato publicado y versionado? | [IDDD cap. 13] | no | Alta |
+| E7 | ¿Se envía un evento de dominio tal cual (`{ ...event }`) a otro contexto en vez de un contrato publicado y versionado? | [IDDD cap. 13] | no | Alta |
 
 ## Arquitectura
 
@@ -20,7 +20,7 @@ La columna "Script" indica si `scan_ddd_smells.py` lo detecta (sí / parcial / n
 |---|---|---|---|---|
 | A1 | ¿El dominio importa frameworks, ORM o clientes HTTP? | [Destilado cap. 2; IDDD cap. 4] | sí | Alta |
 | A2 | ¿Decoradores del ORM en clases de dominio? | [IDDD cap. 6] | sí | Alta |
-| A3 | ¿Controladores con lógica de negocio, que importan repositorios o acceden a la base de datos? Un punto de entrada solo llama a casos de uso y traduce errores con `HttpErrorMapper` | [IDDD cap. 4] | parcial | Alta |
+| A3 | ¿Controladores con lógica de negocio, que importan repositorios o acceden a la base de datos? Un punto de entrada solo llama a casos de uso y traduce errores según el `ExceptionKind` de `ExceptionClassifier` | [IDDD cap. 4] | parcial | Alta |
 | A4 | ¿Un caso de uso, servicio de aplicación o el dominio abre o maneja transacciones (`BEGIN`/`COMMIT`, `startSession`, `withTransaction`) o recibe un runner de transacciones o una unidad de trabajo? IDDD pone la transacción en la aplicación [IDDD cap. 12; IDDD cap. 14]; con el paquete se mueve al adaptador del repositorio, que hace atómico cada `save`/`remove` | `[Fuera de los libros: convención de @archi-code/ddd]` | sí | Media |
 | A5 | ¿Un caso de uso devuelve el agregado al controlador o la API expone `toPrimitives()` tal cual? | [IDDD cap. 4; Destilado cap. 4] | no | Media |
 | A6 | ¿Módulos nombrados por patrón (`entities/`, `services/`, `listeners/`)? | [PHP: Modules] | no | Baja |
@@ -39,7 +39,7 @@ La columna "Script" indica si `scan_ddd_smells.py` lo detecta (sí / parcial / n
 | T4 | ¿Agregados con colecciones que crecen sin límite? | [IDDD cap. 10] | no | Alta |
 | T5 | ¿Referencias a objetos de otros agregados en vez de identidades (`CustomerId extends IdType<'CustomerId'>`)? | [Destilado cap. 5] | no | Media |
 | T6 | ¿Un caso de uso guarda más de un agregado (o los junta en una misma transacción) sin una excepción de IDDD cap. 10 escrita como decisión? Una escritura atómica por agregado, garantizada por el repositorio | [Destilado cap. 5; IDDD cap. 10] | parcial | Alta |
-| T7 | ¿El repositorio usa la `version` de `AggregateRoot`: guarda con condición de versión, lanza `ConcurrencyException`, guarda `order.toPrimitives()` con `order.version + 1`, llama a `markPersisted()` y carga con `Order.fromPrimitives(row).restoreVersion(row.version)`? | [IDDD cap. 10] | no | Alta si hay concurrencia |
+| T7 | ¿El repositorio lleva la versión de concurrencia optimista él mismo: recuerda la de cada agregado que carga o guarda en un `WeakMap<Order, number>` (`0` si es nuevo), guarda con condición de versión, lanza `ConcurrencyException`, guarda `order.toPrimitives()` con `version + 1` al lado (nunca dentro) y actualiza el `WeakMap` solo tras escribir con éxito? ¿El agregado no declara ni mapea ninguna versión? | [IDDD cap. 10]; `[Fuera de los libros: convención de @archi-code/ddd]` para el `WeakMap` | no | Alta si hay concurrencia |
 | T8 | ¿Repositorios de partes internas, una interfaz `Repository` todo en uno, métodos con nombres o reglas de negocio, o lecturas que cargan agregados? Solo `AggregateFinder`/`AggregateSaver`/`AggregateRemover`, y las lecturas son consultas de aplicación | [IDDD cap. 12] | parcial | Media |
 | T9 | ¿Casos de uso con nombres CRUD o técnicos (`UpdateOrder`, `OrderService`), que hacen varias cosas según el input, que llaman a otro caso de uso, o clases `Manager`/`Helper`? | [IDDD cap. 14; Destilado cap. 5] | parcial | Media |
 | T10 | ¿Eventos con nombre en pasado y del lenguaje (`static readonly eventName = 'OrderPlaced'`)? ¿O `OrderUpdated` con todo el estado o con value objects en el payload? | [Destilado cap. 6] | no | Media |
@@ -48,7 +48,7 @@ La columna "Script" indica si `scan_ddd_smells.py` lo detecta (sí / parcial / n
 | T13 | ¿Identidad generada temprano (`OrderId.generate()` antes de crear) y pasada a `super(id)`? ¿Algún id opcional (`extends StringType` sin `Required`)? | [IDDD cap. 5] | no | Media |
 | T14 | ¿Tests de aceptación con lenguaje del negocio y datos realistas (el `InMemoryOrderRepository` del proyecto en `test/support/`, `FixedClock`, `channel.sent`)? | [Destilado cap. 2; IDDD cap. 1] | no | Media |
 | T15 | ¿Cada listener se llama `<Action>On<Event>`, tiene `@ListensTo(Event, { consumer: '…' })` con un nombre literal estable y solo traduce el evento a la entrada de un caso de uso? | `[Fuera de los libros: convención de @archi-code/ddd]` | no | Media |
-| T16 | ¿Los value objects se construyen en `toCommand` con `ValueObjects.build` (todos los campos a la vez) y no en `handle` ni en el controlador? | `[Fuera de los libros: convención de @archi-code/ddd]` | no | Media |
+| T16 | ¿Los value objects se construyen en `toCommand` con `ValueObjectBuilder.build` (todos los campos a la vez) y no en `handle` ni en el controlador? | `[Fuera de los libros: convención de @archi-code/ddd]` | no | Media |
 | T17 | ¿Un repositorio genérico compartido por varios agregados, o un repositorio cuyo constructor recibe la clase del agregado o un mapper? Cada repositorio es de un agregado (`MongoOrderRepository` implementa los roles de `Order`), su constructor recibe solo las dependencias de su tecnología (`collection`, `pool`) y llama directamente a `toPrimitives()`/`fromPrimitives()` del agregado | `[Fuera de los libros: convención de @archi-code/ddd]` | no | Media |
 | T18 | ¿La conversión a o desde primitivos está fuera del agregado (un servicio de dominio o un mapper escrito a mano)? Es del agregado: `toPrimitives()` y `static fromPrimitives()`, que el repositorio llama directamente; un test de ida y vuelta por agregado comprueba que no se pierde ningún campo | `[Fuera de los libros: convención de @archi-code/ddd]` | no | Media |
 | T19 | ¿Un repositorio en memoria en `src/`? Es un doble de test del proyecto (`InMemoryOrderRepository`, ver `ddd-skills/ddd-repositorios-persistencia/references/tests-repositorios.md`): se mueve a `test/support/` | `[Fuera de los libros: convención de @archi-code/ddd]` | no | Baja |

package/ddd-skills/ddd-auditoria-refactorizacion/references/plan-migracion.md

@@ -17,7 +17,7 @@ export interface ProductPricing {
 ```
 
 ```ts
-import { InternalErrorException } from '@archi-code/ddd/exceptions';
+import { InternalErrorException } from '@archi-code/ddd/infrastructure';
 
 interface LegacyArticleRow {
   article_code: string;
@@ -60,7 +60,7 @@ La idea de Evans de un **contexto burbuja** (bubble context): un pequeño contex
 ## Fase 3. Refactorizar el táctico dentro de cada contexto
 
 Orden recomendado `[Fuera de los libros, basado en dependencias entre reglas]`:
-1. Separar dominio de infraestructura: el agregado expone `static fromPrimitives(PrimitiveTypes<X>)` y `toPrimitives()`, los repositorios implementan `AggregateFinder`/`AggregateSaver`/`AggregateRemover` de un solo agregado en `infrastructure/`, que llaman directamente a `x.toPrimitives()` y a `X.fromPrimitives(row).restoreVersion(row.version)`, con un constructor que recibe solo las dependencias de su tecnología (nunca la clase del agregado ni un mapper), sin decoradores del ORM ni imports de `/infrastructure` en el dominio. Un repositorio genérico compartido por varios agregados se parte en uno por agregado; un servicio de dominio o un mapper escrito a mano que convierte a primitivos se sustituye por `toPrimitives()`/`fromPrimitives()` del agregado, con un test de ida y vuelta por agregado; un repositorio en memoria que esté en `src/` se mueve a `test/support/` `[Fuera de los libros: convención de @archi-code/ddd]`.
+1. Separar dominio de infraestructura: el agregado expone `static fromPrimitives(PrimitiveTypes<X>)` y `toPrimitives()`, los repositorios implementan `AggregateFinder`/`AggregateSaver`/`AggregateRemover` de un solo agregado en `infrastructure/`, que llaman directamente a `x.toPrimitives()` y a `X.fromPrimitives(row.primitives)` y recuerdan la versión de cada agregado en un `WeakMap` propio (el agregado no la declara ni la mapea), con un constructor que recibe solo las dependencias de su tecnología (nunca la clase del agregado ni un mapper), sin decoradores del ORM ni imports de `/infrastructure` en el dominio. Un repositorio genérico compartido por varios agregados se parte en uno por agregado; un servicio de dominio o un mapper escrito a mano que convierte a primitivos se sustituye por `toPrimitives()`/`fromPrimitives()` del agregado, con un test de ida y vuelta por agregado; un repositorio en memoria que esté en `src/` se mueve a `test/support/` `[Fuera de los libros: convención de @archi-code/ddd]`.
 2. Introducir value objects para los primitivos más usados: `Money` como `Composite({ amount: Cents, currency: Currency })`, identificadores `class OrderId extends IdType<'OrderId'>` (la marca hace que no se confundan ids de agregados distintos), estados `extends Required(StatusType)` sobre `EnumType`.
 3. Sustituir setters por métodos de negocio con nombres del lenguaje (`ship`, `addLine`) que comprueban la invariante y llaman a `record()`, moviendo la lógica desde los casos de uso; partir los casos de uso CRUD (`UpdateOrder`) en uno por acción (`ShipOrder`, `AddOrderLine`).
 4. Partir agregados grandes con el procedimiento de `ddd-skills/ddd-agregados/GUIA.md` (plazos de consistencia).

package/ddd-skills/ddd-context-mapping/GUIA.md

@@ -8,10 +8,10 @@
 
 [Fuera de los libros: convención de @archi-code/ddd]
 
-* El paquete no trae capa anticorrupción, Open Host Service ni Published Language: se escriben en el proyecto sobre sus clases y puertos. El puerto hacia otro contexto (`ProductPricing`) es una interfaz en `domain/` que recibe y devuelve value objects (`Sku`, un `Composite` `SellableProduct`); adaptador (`CatalogHttpProductPricing`) y traductor (`CatalogTranslator`) van en `infrastructure/` y lanzan una `InfrastructureException` con código propio (`CAT001`), que `HttpErrorMapper` traduce (`new HttpErrorMapper({ statusByCode: { CAT001: 503 } })`).
-* Un webhook entrante es un punto de entrada en `interfaces/` que traduce el lenguaje del emisor a la entrada de un `UseCase` y responde con `HttpErrorMapper`.
-* Los mensajes entre contextos viajan como `SerializedEvent` plano (`{ eventName, eventVersion, eventId, aggregateId, occurredOn, ...datos }`) por un `EventChannel` (tu canal de broker o de outbox), no con el envoltorio de IDDD `{ notificationId, typeName, version, occurredOn, event }`: `eventName` hace de `typeName` (`'sales.order.OrderPlaced'`), `eventVersion` de `version` y `eventId` identifica el mensaje para deduplicar. No hay `notificationId` secuencial: si un feed REST lo necesita, lo asigna tu canal duradero.
-* Lo que sale se traduce al Published Language en infraestructura, con un `EventChannel` propio en el adaptador del broker (`ContractPublishingChannel` + `SalesContracts`, en `ddd-skills/ddd-eventos-dominio/references/publicacion-ts.md`); nunca se publica fuera del contexto el `toJSON()` de un evento interno tal cual.
+* El paquete no trae capa anticorrupción, Open Host Service ni Published Language: se escriben en el proyecto sobre sus clases y puertos. El puerto hacia otro contexto (`ProductPricing`) es una interfaz en `domain/` que recibe y devuelve value objects (`Sku`, un `Composite` `SellableProduct`); adaptador (`CatalogHttpProductPricing`) y traductor (`CatalogTranslator`) van en `infrastructure/` y lanzan una `InfrastructureException` con código propio (`CAT001`), que el punto de entrada traduce por su código (`CAT001` → 503 en HTTP; sin traducción propia, `ExceptionClassifier.classify` la clasifica como `ExceptionKind.Internal`).
+* Un webhook entrante es un punto de entrada en `interfaces/` que traduce el lenguaje del emisor a la entrada de un `UseCase` y responde según el `ExceptionKind` que devuelve `ExceptionClassifier.classify(error)` (de `@archi-code/ddd/infrastructure`).
+* Los mensajes entre contextos viajan como `SerializedEvent` plano (`{ eventName, eventId, occurredOn, ...datos }`, con la identidad del agregado entre los datos, como `orderId`) por un `EventChannel` (tu canal de broker o de outbox), no con el envoltorio de IDDD `{ notificationId, typeName, version, occurredOn, event }`: `eventName` hace de `typeName` (`'sales.order.OrderPlaced'`) y también identifica la versión del contrato (una versión incompatible se publica con otro nombre, como `'sales.order.OrderPlacedV2'`), y `eventId` identifica el mensaje para deduplicar. No hay `notificationId` secuencial: si un feed REST lo necesita, lo asigna tu canal duradero.
+* Lo que sale se traduce al Published Language en infraestructura, con un `EventChannel` propio en el adaptador del broker (`ContractPublishingChannel` + `SalesContracts`, en `ddd-skills/ddd-eventos-dominio/references/publicacion-ts.md`); nunca se publica fuera del contexto un evento interno tal cual (`{ ...event }`).
 * Lo que entra de otro contexto se lee con una clase propia `extends EventBase` que lleva el nombre publicado y solo los campos que este contexto usa; la factoría de `EventRegistry` es el traductor, y un `EventListener` con `@ListensTo(Evento, { consumer })` ejecuta un caso de uso, que valida cada campo con value objects en `toCommand`.
 * Los procesos entre contextos se encadenan con eventos y listeners, cada uno con su caso de uso.
 
@@ -72,7 +72,7 @@ Para cada evento que cruza un contexto, decide entre **evento enriquecido** (má
 * API REST que devuelve el agregado serializado con todos sus campos.
 * Una petición de usuario que atraviesa tres servicios en cadena de forma síncrona.
 * Un consumidor de eventos sin control de duplicados.
-* Un contexto publica hacia fuera el `toJSON()` de sus eventos internos, o un listener recibe la clase de evento de otro contexto importada de su código.
+* Un contexto publica hacia fuera sus eventos internos tal cual (`{ ...event }`), o un listener recibe la clase de evento de otro contexto importada de su código.
 * "Shared Kernel" usado como excusa para compartir una librería de modelos que crece sin acuerdo [IDDD cap. 13].
 * El código copia sin traducir el modelo de un proveedor.
 

package/ddd-skills/ddd-context-mapping/references/anticorrupcion-ts.md

@@ -104,7 +104,7 @@ La regla "solo se vende lo activo con precio web" es una decisión de traducció
 
 ```ts
 // src/contexts/sales/infrastructure/catalog/CatalogHttpProductPricing.ts
-import { InfrastructureException } from '@archi-code/ddd/exceptions';
+import { InfrastructureException } from '@archi-code/ddd/infrastructure';
 import type { ProductPricing, SellableProduct } from '../../domain/catalog/ProductPricing';
 import type { Sku } from '../../domain/order/OrderLine';
 import { CatalogTranslator } from './CatalogTranslator';
@@ -166,15 +166,14 @@ export class CatalogHttpProductPricing implements ProductPricing {
 Decisiones visibles:
 * Timeout explícito: la red falla y hay latencia [IDDD cap. 13].
 * Validación del contrato al entrar: si Catálogo rompe el esquema, el error se detecta en el borde y no dentro del modelo. Un valor inválido de Catálogo no llega al usuario como `ValidationException` de Ventas: el adaptador la envuelve en `CatalogContractViolation` con la original como `cause`.
-* Errores con nombre y código propios (`InfrastructureException` con `CAT001`, `CAT002`). El punto de entrada los traduce con `HttpErrorMapper`, que responde 500 por defecto a cualquier error de infraestructura; para avisar de que Catálogo no está disponible se configura por código: `new HttpErrorMapper({ statusByCode: { CAT001: 503 } })` (con 5xx el cuerpo lleva un mensaje genérico, nunca el del error).
+* Errores con nombre y código propios (`InfrastructureException` con `CAT001`, `CAT002`). `ExceptionClassifier.classify(error)` clasifica cualquier error de infraestructura como `ExceptionKind.Internal` (500 en HTTP); para avisar de que Catálogo no está disponible, el punto de entrada traduce su código (`CAT001` → 503) antes de mirar el tipo (con 5xx el cuerpo lleva un mensaje genérico, nunca el del error).
 
 ### 5. Uso desde la capa de aplicación
 
 ```ts
 // src/contexts/sales/application/place-order/PlaceOrder.ts
-import { ValueObjects } from '@archi-code/ddd/domain';
 import type { AggregateSaver } from '@archi-code/ddd/domain';
-import { UseCase } from '@archi-code/ddd/application';
+import { UseCase, ValueObjectBuilder } from '@archi-code/ddd/application';
 import type { Clock, EventBus } from '@archi-code/ddd/application';
 import type { ProductPricing } from '../../domain/catalog/ProductPricing';
 import { CustomerId } from '../../domain/customer/CustomerId';
@@ -207,12 +206,12 @@ export class PlaceOrder extends UseCase<PlaceOrderInput, PlaceOrderCommand, stri
   }
 
   protected toCommand(input: PlaceOrderInput): PlaceOrderCommand {
-    return ValueObjects.build({
+    return ValueObjectBuilder.build({
       orderId: () => OrderId.generate(),
       customerId: () => new CustomerId(input.customerId),
       items: () =>
-        ValueObjects.buildList(input.items, (item) =>
-          ValueObjects.build({
+        ValueObjectBuilder.buildList(input.items, (item) =>
+          ValueObjectBuilder.build({
             sku: () => new Sku(item.sku),
             quantity: () => new Quantity(item.quantity),
           }),
@@ -246,16 +245,16 @@ export class PlaceOrder extends UseCase<PlaceOrderInput, PlaceOrderCommand, stri
 }
 ```
 
-El precio se copia en la línea del pedido: Ventas guarda el estado remoto **mínimo** que necesita y deja de depender de Catálogo para ese pedido [IDDD cap. 3]. La consulta a Catálogo va antes de crear y guardar el pedido; como la transacción solo existe dentro del `save` del repositorio, nunca queda una abierta mientras se espera a la red `[Fuera de los libros: convención de @archi-code/ddd]`. `ProductNotSellable` es una `DomainException` de Ventas con código propio (`ORD003`), que `HttpErrorMapper` responde con 422.
+El precio se copia en la línea del pedido: Ventas guarda el estado remoto **mínimo** que necesita y deja de depender de Catálogo para ese pedido [IDDD cap. 3]. La consulta a Catálogo va antes de crear y guardar el pedido; como la transacción solo existe dentro del `save` del repositorio, nunca queda una abierta mientras se espera a la red `[Fuera de los libros: convención de @archi-code/ddd]`. `ProductNotSellable` es una `DomainException` de Ventas con código propio (`ORD003`), que `ExceptionClassifier` clasifica como `ExceptionKind.Invalid` (422 en HTTP).
 
 ## ACL con un webhook entrante
 
-Mismo patrón con un producto externo que llama a este contexto: el punto de entrada es el adaptador, la forma del mensaje es el contrato y la traducción produce la entrada de un caso de uso en el lenguaje local. Vive en `interfaces/` (como cualquier controlador) y solo conoce casos de uso y `HttpErrorMapper` [IDDD cap. 4]. El router ya ha comprobado la firma del emisor y la forma del cuerpo antes de llamarlo `[Fuera de los libros]`.
+Mismo patrón con un producto externo que llama a este contexto: el punto de entrada es el adaptador, la forma del mensaje es el contrato y la traducción produce la entrada de un caso de uso en el lenguaje local. Vive en `interfaces/` (como cualquier controlador) y solo conoce casos de uso y `ExceptionClassifier` de `@archi-code/ddd/infrastructure` [IDDD cap. 4]. Traduce cada `ExceptionKind` a lo que entiende el emisor: lo que merece reintento (un conflicto, un error interno) responde 5xx para que la pasarela vuelva a enviarlo, y lo que no cambiaría al reintentar responde 4xx `[Fuera de los libros]`. El router ya ha comprobado la firma del emisor y la forma del cuerpo antes de llamarlo `[Fuera de los libros]`.
 
 ```ts
 // src/contexts/payments/interfaces/http/PaymentGatewayWebhook.ts
-import { HttpErrorMapper } from '@archi-code/ddd/infrastructure';
-import type { HttpErrorBody } from '@archi-code/ddd/infrastructure';
+import { ExceptionClassifier, ExceptionKind } from '@archi-code/ddd/infrastructure';
+import type { Logger } from '@archi-code/ddd/application';
 import type { RecordPaymentAuthorization } from '../../application/record-payment-authorization/RecordPaymentAuthorization';
 import type { RecordPaymentRejection } from '../../application/record-payment-rejection/RecordPaymentRejection';
 
@@ -268,14 +267,26 @@ export interface GatewayEvent {
   metadata: { paymentId: string };
 }
 
+function statusOf(kind: ExceptionKind): number {
+  switch (kind) {
+    case ExceptionKind.Conflict:
+    case ExceptionKind.Internal:
+      return 503;
+    case ExceptionKind.NotFound:
+      return 404;
+    default:
+      return 422;
+  }
+}
+
 export class PaymentGatewayWebhook {
   constructor(
     private readonly recordAuthorization: RecordPaymentAuthorization,
     private readonly recordRejection: RecordPaymentRejection,
-    private readonly errors: HttpErrorMapper,
+    private readonly logger: Logger,
   ) {}
 
-  async receive(event: GatewayEvent): Promise<{ status: number; body?: HttpErrorBody }> {
+  async receive(event: GatewayEvent): Promise<{ status: number }> {
     try {
       switch (event.type) {
         case 'charge.authorized':
@@ -294,7 +305,11 @@ export class PaymentGatewayWebhook {
       }
       return { status: 204 };
     } catch (error) {
-      return this.errors.map(error);
+      const kind = ExceptionClassifier.classify(error);
+      if (kind === ExceptionKind.Internal) {
+        this.logger.error('payment_webhook_failed', { type: event.type, error });
+      }
+      return { status: statusOf(kind) };
     }
   }
 }
@@ -315,11 +330,11 @@ export class StockReserved extends EventBase {
   static readonly eventName = 'warehouse.stock.StockReserved';
 
   constructor(
-    reservationId: string,
+    readonly reservationId: string,
     readonly orderId: string,
     metadata?: EventMetadata,
   ) {
-    super(reservationId, metadata);
+    super(metadata);
   }
 }
 ```
@@ -339,7 +354,7 @@ export class RegisterStockReservationOnStockReserved extends EventListener<Stock
   async handle(event: StockReserved): Promise<void> {
     await this.registerStockReservation.execute({
       orderId: event.orderId,
-      reservationId: event.aggregateId,
+      reservationId: event.reservationId,
     });
   }
 }
@@ -351,7 +366,7 @@ import { DomainEventBus, EventRegistry } from '@archi-code/ddd/infrastructure';
 
 const warehouseEvents = 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 warehouseBus = new DomainEventBus<StockReserved>(
   new RabbitMqEventChannel(amqpChannel, 'warehouse.published'),

package/ddd-skills/ddd-context-mapping/references/estilos-integracion.md

@@ -40,9 +40,8 @@ El evento de Almacén llega por un `EventChannel` a un listener (`RegisterStockR
 
 ```ts
 // src/contexts/sales/application/register-stock-reservation/RegisterStockReservation.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 { UseCase, ValueObjectBuilder } from '@archi-code/ddd/application';
 import type { Clock, EventBus } from '@archi-code/ddd/application';
 import { Order, OrderEvent, OrderId, ReservationId } from '../../domain/order/Order';
 
@@ -70,7 +69,7 @@ export class RegisterStockReservation extends UseCase<
   }
 
   protected toCommand(input: RegisterStockReservationInput): RegisterStockReservationCommand {
-    return ValueObjects.build({
+    return ValueObjectBuilder.build({
       orderId: () => new OrderId(input.orderId),
       reservationId: () => new ReservationId(input.reservationId),
     });
@@ -109,14 +108,12 @@ Aplicar dos veces "reserva registrada" no cambia nada la segunda vez ni graba un
 * Los eventos y notificaciones llevan versión. Si se diseñan con cuidado, muchos consumidores pueden leer cualquier versión como si fuera la 1 y no necesitan cambiar [IDDD cap. 13].
 * Los value objects estables (identificadores) se pueden incluir en el evento; quedan congelados en la estructura [IDDD cap. 13]. Con el paquete, el payload lleva solo primitivos tomados de los value objects (`orderId: string`), también los identificadores `[Fuera de los libros: convención de @archi-code/ddd]`.
 
-La notificación de IDDD envuelve el evento en `{ notificationId, typeName, version, occurredOn, event }` [IDDD cap. 13]. Con el paquete, el mensaje publicado es un `SerializedEvent` plano, con el nombre y la versión del Published Language `[Fuera de los libros: convención de @archi-code/ddd]`:
+La notificación de IDDD envuelve el evento en `{ notificationId, typeName, version, occurredOn, event }` [IDDD cap. 13]. Con el paquete, el mensaje publicado es un `SerializedEvent` plano, con el nombre del Published Language, que también identifica su versión `[Fuera de los libros: convención de @archi-code/ddd]`:
 
 ```json
 {
   "eventName": "sales.order.OrderPlaced",
-  "eventVersion": 1,
   "eventId": "6f1c2a3b-8d4e-4f5a-9b6c-7d8e9f0a1b2c",
-  "aggregateId": "9b2f6c1e-4d3a-4f8b-a1c2-3e4d5f6a7b8c",
   "occurredOn": "2026-10-18T10:15:00.000Z",
   "orderId": "9b2f6c1e-4d3a-4f8b-a1c2-3e4d5f6a7b8c",
   "customerId": "1c5e7a90-2b3d-4e6f-8a1b-2c3d4e5f6a7b",
@@ -127,7 +124,7 @@ La notificación de IDDD envuelve el evento en `{ notificationId, typeName, vers
 }
 ```
 
-`eventName` hace de `typeName`, `eventVersion` de `version` y `eventId` es el identificador con el que el consumidor deduplica. No hay `notificationId` secuencial: si publicas un feed REST de notificaciones, la secuencia la asigna tu canal duradero (la fila del outbox).
+`eventName` hace de `typeName` y de `version`: el mensaje no lleva campo de versión, y una versión incompatible del contrato se publica con otro nombre (`sales.order.OrderPlacedV2`) mientras los consumidores migran. `eventId` es el identificador con el que el consumidor deduplica. No hay `notificationId` secuencial: si publicas un feed REST de notificaciones, la secuencia la asigna tu canal duradero (la fila del outbox).
 
 El evento interno no sale tal cual. La traducción al Published Language vive en infraestructura, en el adaptador que habla con el broker: un `EventChannel` del proyecto (`ContractPublishingChannel`) que pasa cada `SerializedEvent` por `SalesContracts` (qué eventos salen y con qué contrato, uno por versión publicada, con `messageId` = `eventId`) y entrega todos al canal interno. El código está en `ddd-skills/ddd-eventos-dominio/references/publicacion-ts.md` ("Lenguaje publicado en el adaptador del broker"); los casos de uso siguen viendo solo `EventBus`, y un evento sin contrato es interno y no sale del contexto. Para no perder mensajes, la publicación al broker la hace el reenviador del outbox después del commit (ver "Publicar de forma fiable").
 

package/ddd-skills/ddd-event-sourcing-cqrs/GUIA.md

@@ -9,7 +9,7 @@
 [Fuera de los libros: convención de @archi-code/ddd]
 
 * El paquete no trae event store, repositorios con Event Sourcing, snapshots ni proyecciones con checkpoint: se construyen en la infraestructura del proyecto sobre sus clases, y solo si la tabla de decisión de esta guía lo justifica.
-* La `version` de `AggregateRoot` crece 1 por guardado, no por evento: un agregado con Event Sourcing lleva su propia versión de stream (`streamVersion()`), se reconstruye con `fromHistory` a partir de los eventos que reconstruye `EventRegistry` y no usa `toPrimitives()`/`fromPrimitives()`.
+* `AggregateRoot` no lleva versión: la de concurrencia optimista de los repositorios de instantáneas la recuerda cada repositorio en un `WeakMap` y crece 1 por guardado, no por evento. Un agregado con Event Sourcing lleva su propia versión de stream (`streamVersion()`), se reconstruye con `fromHistory` a partir de los eventos que reconstruye `EventRegistry` y no usa `toPrimitives()`/`fromPrimitives()`.
 * El contrato del stream (`load`/`append`) lo declara el dominio y no es `AggregateFinder`/`AggregateSaver`; su adaptador es responsable de la persistencia: anexa los eventos de un `append` en una sola escritura atómica con la versión esperada y lanza `ConcurrencyException` si otro escribió antes. La aplicación no abre transacciones; el reintento ante `ConcurrencyException` va en el `handle` del caso de uso, cada intento vuelve a cargar y vuelve a anexar.
 * Una proyección es un `EventListener` con `@ListensTo(Event, { consumer })` que llama a un puerto de proyección (no a un caso de uso), idempotente por `eventId`; un `EventChannel` no guarda historial, así que reconstruirla exige un log de eventos propio (con Event Sourcing, el propio event store).
 * Una consulta de lectura es una interfaz en `application/` implementada en infraestructura directamente sobre la base de datos.
@@ -82,7 +82,7 @@ En Event Sourcing los eventos sirven para persistir el agregado **y** para comun
 * Eventos tipo `OrderUpdated` con el estado completo en el stream.
 * Proyecciones que no se pueden reconstruir (dependen de estado externo no reproducible).
 * Proyecciones no idempotentes (sin comprobar el `eventId` ya aplicado).
-* Un agregado con Event Sourcing que usa la `version` de `AggregateRoot` como versión de stream o se guarda como instantánea con `toPrimitives()`.
+* Un agregado con Event Sourcing que usa la versión de guardados de un repositorio de instantáneas como versión de stream o se guarda como instantánea con `toPrimitives()`.
 * Agregados que consultan read models para proteger invariantes (las invariantes viven en el agregado).
 * Datos personales en eventos sin estrategia de supresión.
 * CQRS con dos bases de datos para un CRUD de cinco pantallas.