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

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

@@ -0,0 +1,404 @@
+# Implementar una capa anticorrupción en TypeScript
+
+## Estructura
+
+IDDD propone tres piezas [IDDD cap. 3 y cap. 13]:
+
+1. **Interfaz de la capa en el dominio:** un servicio de dominio con nombre del lenguaje local (en IDDD, `MemberService` que proporciona `ProductOwner` y `TeamMember`).
+2. **Adaptador:** cliente del sistema remoto; habla su protocolo (en IDDD, `IdentityAccessNotificationAdapter`).
+3. **Traductor:** convierte el Published Language remoto en objetos del modelo local (en IDDD, `MemberTranslator`).
+
+El dominio solo ve la interfaz. Adaptador y traductor viven en infraestructura. Así el modelo usa datos de otro contexto para expresar sus propios conceptos sin contaminarse [IDDD cap. 3].
+
+`@archi-code/ddd` no trae ninguna de las tres piezas: se escriben en el proyecto con sus value objects, sus excepciones y sus puertos `[Fuera de los libros: convención de @archi-code/ddd]`.
+
+```
+src/contexts/sales/
+  domain/
+    catalog/ProductPricing.ts          ← puerto con lenguaje de Ventas (SellableProduct, ProductPricing)
+    order/...
+  infrastructure/
+    catalog/
+      CatalogHttpProductPricing.ts     ← adaptador: habla HTTP con Catálogo
+      CatalogTranslator.ts             ← traductor: JSON de Catálogo → value objects de Ventas
+      CatalogProductV2.ts              ← forma del Published Language de Catálogo que Ventas lee
+```
+
+## Ejemplo: Ventas consulta precios a Catálogo
+
+Catálogo expone un OHS con fichas completas (fotos, descripciones, variantes, tarifas por canal). Ventas solo necesita saber si una referencia se puede vender y a qué precio en el canal web.
+
+### 1. Puerto en el dominio de Ventas
+
+```ts
+// src/contexts/sales/domain/catalog/ProductPricing.ts
+import { Composite, Required, StringType } from '@archi-code/ddd/domain';
+import { Money } from '../shared/Money';
+import { Sku } from '../order/OrderLine';
+
+export class ProductName extends Required(StringType) {}
+
+export class SellableProduct extends Composite({ sku: Sku, name: ProductName, unitPrice: Money }) {}
+
+export interface ProductPricing {
+  priceForSale(sku: Sku): Promise<SellableProduct | null>;
+}
+```
+
+Fíjate en el nombre: `ProductPricing` y `SellableProduct`, no `CatalogClient` ni `CatalogProductDto`. El dominio pregunta con su lenguaje y recibe value objects ya válidos (`SellableProduct` es un `Composite` de `Sku`, `ProductName` y `Money`); `null` significa que la referencia no se puede vender ahora en el canal web.
+
+### 2. Forma del Published Language
+
+```ts
+// src/contexts/sales/infrastructure/catalog/CatalogProductV2.ts
+export interface CatalogProductV2 {
+  sku: string;
+  displayName: string;
+  lifecycle: 'DRAFT' | 'ACTIVE' | 'DISCONTINUED';
+  channelPrices: { channel: string; amountMinor: number; currency: string }[];
+}
+```
+
+Solo lo que Ventas lee; el resto de campos de Catálogo se ignora. El adaptador comprueba solo la forma; los valores los validan los value objects al construirse (`Sku`, `Money`). Si prefieres validar con JSON Schema, cualquier validador sirve en este punto `[Fuera de los libros: elección de librería]`.
+
+### 3. Traductor
+
+```ts
+// src/contexts/sales/infrastructure/catalog/CatalogTranslator.ts
+import { SellableProduct } from '../../domain/catalog/ProductPricing';
+import type { CatalogProductV2 } from './CatalogProductV2';
+
+export class CatalogTranslator {
+  static isProductV2(body: unknown): body is CatalogProductV2 {
+    const candidate = body as Partial<CatalogProductV2> | null;
+    return (
+      typeof candidate === 'object' &&
+      candidate !== null &&
+      typeof candidate.sku === 'string' &&
+      typeof candidate.displayName === 'string' &&
+      typeof candidate.lifecycle === 'string' &&
+      Array.isArray(candidate.channelPrices)
+    );
+  }
+
+  toSellableProduct(remote: CatalogProductV2): SellableProduct | null {
+    if (remote.lifecycle !== 'ACTIVE') {
+      return null;
+    }
+    const web = remote.channelPrices.find((price) => price.channel === 'WEB');
+    if (web === undefined) {
+      return null;
+    }
+    return SellableProduct.fromPrimitives({
+      sku: remote.sku,
+      name: remote.displayName,
+      unitPrice: { amount: web.amountMinor, currency: web.currency },
+    });
+  }
+}
+```
+
+La regla "solo se vende lo activo con precio web" es una decisión de traducción. Si se convierte en regla del negocio de Ventas con matices propios, muévela al dominio. `SellableProduct.fromPrimitives` construye cada value object y, si Catálogo envía un valor que el modelo de Ventas no acepta, lanza una `ValidationException` con todos los campos afectados.
+
+### 4. Adaptador
+
+```ts
+// src/contexts/sales/infrastructure/catalog/CatalogHttpProductPricing.ts
+import { InfrastructureException } from '@archi-code/ddd/exceptions';
+import type { ProductPricing, SellableProduct } from '../../domain/catalog/ProductPricing';
+import type { Sku } from '../../domain/order/OrderLine';
+import { CatalogTranslator } from './CatalogTranslator';
+
+export class CatalogUnavailable extends InfrastructureException {
+  constructor(sku: string, options: { cause?: unknown } = {}) {
+    super(`Catalog did not answer for ${sku}`, ['CAT001'], options);
+  }
+}
+
+export class CatalogContractViolation extends InfrastructureException {
+  constructor(sku: string, options: { cause?: unknown } = {}) {
+    super(`Catalog answered ${sku} outside its published contract`, ['CAT002'], options);
+  }
+}
+
+export interface CatalogHttp {
+  get(
+    path: string,
+    options: { headers: Record<string, string>; signal: AbortSignal },
+  ): Promise<{ status: number; ok: boolean; json(): Promise<unknown> }>;
+}
+
+export class CatalogHttpProductPricing implements ProductPricing {
+  constructor(
+    private readonly http: CatalogHttp,
+    private readonly translator = new CatalogTranslator(),
+  ) {}
+
+  async priceForSale(sku: Sku): Promise<SellableProduct | null> {
+    let response: Awaited<ReturnType<CatalogHttp['get']>>;
+    try {
+      response = await this.http.get(`/products/${encodeURIComponent(sku.value)}`, {
+        headers: { Accept: 'application/vnd.catalog.product.v2+json' },
+        signal: AbortSignal.timeout(800),
+      });
+    } catch (error) {
+      throw new CatalogUnavailable(sku.value, { cause: error });
+    }
+    if (response.status === 404) {
+      return null;
+    }
+    if (!response.ok) {
+      throw new CatalogUnavailable(sku.value);
+    }
+    const body = await response.json();
+    if (!CatalogTranslator.isProductV2(body)) {
+      throw new CatalogContractViolation(sku.value);
+    }
+    try {
+      return this.translator.toSellableProduct(body);
+    } catch (error) {
+      throw new CatalogContractViolation(sku.value, { cause: error });
+    }
+  }
+}
+```
+
+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).
+
+### 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 type { Clock, EventBus } from '@archi-code/ddd/application';
+import type { ProductPricing } from '../../domain/catalog/ProductPricing';
+import { CustomerId } from '../../domain/customer/CustomerId';
+import { Order, OrderEvent, OrderId } from '../../domain/order/Order';
+import { OrderLine, OrderLines, Quantity, Sku } from '../../domain/order/OrderLine';
+import { ShippingAddress } from '../../domain/order/ShippingAddress';
+import { ProductNotSellable } from '../../domain/order/ProductNotSellable';
+
+interface PlaceOrderInput {
+  customerId: string;
+  items: { sku: string; quantity: number }[];
+  shippingAddress: { street: string; city: string; country: string };
+}
+
+interface PlaceOrderCommand {
+  orderId: OrderId;
+  customerId: CustomerId;
+  items: { sku: Sku; quantity: Quantity }[];
+  shippingAddress: ShippingAddress;
+}
+
+export class PlaceOrder extends UseCase<PlaceOrderInput, PlaceOrderCommand, string> {
+  constructor(
+    private readonly orders: AggregateSaver<Order>,
+    private readonly pricing: ProductPricing,
+    private readonly events: EventBus<OrderEvent>,
+    private readonly clock: Clock,
+  ) {
+    super();
+  }
+
+  protected toCommand(input: PlaceOrderInput): PlaceOrderCommand {
+    return ValueObjects.build({
+      orderId: () => OrderId.generate(),
+      customerId: () => new CustomerId(input.customerId),
+      items: () =>
+        ValueObjects.buildList(input.items, (item) =>
+          ValueObjects.build({
+            sku: () => new Sku(item.sku),
+            quantity: () => new Quantity(item.quantity),
+          }),
+        ),
+      shippingAddress: () => ShippingAddress.fromPrimitives(input.shippingAddress),
+    });
+  }
+
+  protected async handle(command: PlaceOrderCommand): Promise<string> {
+    const lines: OrderLine[] = [];
+    for (const item of command.items) {
+      const product = await this.pricing.priceForSale(item.sku);
+      if (product === null) {
+        throw new ProductNotSellable(item.sku.value);
+      }
+      lines.push(
+        new OrderLine({ sku: product.sku, quantity: item.quantity, unitPrice: product.unitPrice }),
+      );
+    }
+    const order = Order.place(
+      command.orderId,
+      command.customerId,
+      new OrderLines({ items: lines }),
+      command.shippingAddress,
+      this.clock,
+    );
+    await this.orders.save(order);
+    await this.events.publish(order.pullDomainEvents());
+    return order.id.value;
+  }
+}
+```
+
+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.
+
+## 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]`.
+
+```ts
+// src/contexts/payments/interfaces/http/PaymentGatewayWebhook.ts
+import { HttpErrorMapper } from '@archi-code/ddd/infrastructure';
+import type { HttpErrorBody } from '@archi-code/ddd/infrastructure';
+import type { RecordPaymentAuthorization } from '../../application/record-payment-authorization/RecordPaymentAuthorization';
+import type { RecordPaymentRejection } from '../../application/record-payment-rejection/RecordPaymentRejection';
+
+export interface GatewayEvent {
+  type: string;
+  created: number;
+  amount: number;
+  currency: string;
+  failure_code?: string;
+  metadata: { paymentId: string };
+}
+
+export class PaymentGatewayWebhook {
+  constructor(
+    private readonly recordAuthorization: RecordPaymentAuthorization,
+    private readonly recordRejection: RecordPaymentRejection,
+    private readonly errors: HttpErrorMapper,
+  ) {}
+
+  async receive(event: GatewayEvent): Promise<{ status: number; body?: HttpErrorBody }> {
+    try {
+      switch (event.type) {
+        case 'charge.authorized':
+          await this.recordAuthorization.execute({
+            paymentId: event.metadata.paymentId,
+            amount: { amount: event.amount, currency: event.currency },
+            authorizedAt: new Date(event.created * 1000).toISOString(),
+          });
+          break;
+        case 'charge.failed':
+          await this.recordRejection.execute({
+            paymentId: event.metadata.paymentId,
+            reason: event.failure_code ?? 'unknown',
+          });
+          break;
+      }
+      return { status: 204 };
+    } catch (error) {
+      return this.errors.map(error);
+    }
+  }
+}
+```
+
+`charge.authorized` es lenguaje de la pasarela; `RecordPaymentAuthorization` es lenguaje de Pagos. Cada tipo de evento que interesa va a un caso de uso distinto, que construye sus value objects en `toCommand` (`PaymentId`, `Money`) y registra un hecho: no lo rechaza y es idempotente, porque la pasarela reintenta. Los tipos que este contexto no necesita se ignoran con 204.
+
+## ACL con eventos de otro contexto
+
+Si el upstream publica eventos (con el mismo paquete o no), el downstream los lee con su propia clase: un `EventBase` con el nombre publicado y solo los campos que usa, nunca la clase del otro contexto importada de su código `[Fuera de los libros: convención de @archi-code/ddd]`. La factoría de `EventRegistry` es el traductor del mensaje, y el listener convierte el evento en la entrada de un caso de uso:
+
+```ts
+// src/contexts/sales/application/register-stock-reservation/StockReserved.ts
+import { EventBase } from '@archi-code/ddd/domain';
+import type { EventMetadata } from '@archi-code/ddd/domain';
+
+export class StockReserved extends EventBase {
+  static readonly eventName = 'warehouse.stock.StockReserved';
+
+  constructor(
+    reservationId: string,
+    readonly orderId: string,
+    metadata?: EventMetadata,
+  ) {
+    super(reservationId, metadata);
+  }
+}
+```
+
+```ts
+// src/contexts/sales/application/register-stock-reservation/RegisterStockReservationOnStockReserved.ts
+import { EventListener, ListensTo } from '@archi-code/ddd/application';
+import { RegisterStockReservation } from './RegisterStockReservation';
+import { StockReserved } from './StockReserved';
+
+@ListensTo(StockReserved, { consumer: 'sales.register-stock-reservation-on-stock-reserved' })
+export class RegisterStockReservationOnStockReserved extends EventListener<StockReserved> {
+  constructor(private readonly registerStockReservation: RegisterStockReservation) {
+    super();
+  }
+
+  async handle(event: StockReserved): Promise<void> {
+    await this.registerStockReservation.execute({
+      orderId: event.orderId,
+      reservationId: event.aggregateId,
+    });
+  }
+}
+```
+
+```ts
+// src/contexts/sales/composition.ts (extracto)
+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),
+);
+const warehouseBus = new DomainEventBus<StockReserved>(
+  new RabbitMqEventChannel(amqpChannel, 'warehouse.published'),
+  warehouseEvents,
+);
+await warehouseBus.subscribe(
+  new RegisterStockReservationOnStockReserved(
+    new RegisterStockReservation(orders, salesBus, clock),
+  ),
+);
+```
+
+`RabbitMqEventChannel` es el canal de broker del proyecto (el de `ddd-skills/archi-code-ddd/patterns.md`), aquí suscrito al exchange donde Almacén publica su Published Language. La factoría pasa `json` como metadatos para conservar el `eventId` con el que se deduplica. Leer `json.orderId as string` no valida nada: el caso de uso construye `OrderId` y `ReservationId` en `toCommand`, y si el mensaje no cumple el contrato lanza una `ValidationException` con cada campo, el listener falla y el canal lo aparta (en RabbitMQ, `nack` a la cola de mensajes muertos). El caso de uso `RegisterStockReservation` y su idempotencia están en `ddd-skills/ddd-context-mapping/references/estilos-integracion.md`.
+
+## Tests de la capa
+
+`[Fuera de los libros]`
+* **Traductor:** tests unitarios con respuestas reales anonimizadas del sistema remoto.
+* **Adaptador:** tests de contrato contra el esquema publicado o un entorno de pruebas del upstream.
+* **Dominio y casos de uso:** usan una implementación en memoria del puerto; nunca se prueban contra el sistema remoto:
+
+```ts
+import type { ProductPricing } from '../../src/contexts/sales/domain/catalog/ProductPricing';
+import { SellableProduct } from '../../src/contexts/sales/domain/catalog/ProductPricing';
+import type { Sku } from '../../src/contexts/sales/domain/order/OrderLine';
+
+export class InMemoryProductPricing implements ProductPricing {
+  private readonly products = new Map<string, SellableProduct>();
+
+  add(product: SellableProduct): this {
+    this.products.set(product.sku.value, product);
+    return this;
+  }
+
+  async priceForSale(sku: Sku): Promise<SellableProduct | null> {
+    return this.products.get(sku.value) ?? null;
+  }
+}
+```
+
+Con ella, `PlaceOrder` se prueba con `new InMemoryOrderRepository()` (el repositorio en memoria que el proyecto escribe en `test/support/`, como en `ddd-skills/ddd-repositorios-persistencia/references/tests-repositorios.md`), un `DomainEventBus` sobre `InMemoryEventChannel` y `new FixedClock('2026-03-01T09:30:00Z')`, comprobando `channel.sent` y lo guardado.
+
+## Errores frecuentes
+
+* El puerto devuelve el DTO remoto "por comodidad" en vez de value objects. La capa ya no protege nada.
+* El traductor vive en el dominio porque "es lógica". Si conoce el formato remoto, es infraestructura.
+* Una única ACL genérica para todos los sistemas externos. Cada relación tiene su traducción.
+* Copiar todos los campos remotos "por si acaso" en vez del estado mínimo.
+* Dejar que una `ValidationException` provocada por datos del sistema remoto salga como si fuera un error del usuario (422): el adaptador la envuelve en su propia `InfrastructureException`.
+* Importar la clase de evento del otro contexto para el `@ListensTo`: el downstream declara la suya, con el nombre publicado.

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

@@ -0,0 +1,155 @@
+# Estilos de integración
+
+## Comparativa
+
+| Estilo | Acoplamiento temporal | Robustez | Cuándo |
+|---|---|---|---|
+| RPC (SOAP, gRPC, HTTP con procedimientos) | Alto: si el otro cae, fallas | Baja. Parece una llamada local y no lo es [Destilado cap. 4] | Consultas rápidas a servicios muy disponibles; siempre con ACL |
+| REST | Alto en peticiones directas | Media. Se apoya en la fiabilidad probada de la web [Destilado cap. 4] | OHS para varios consumidores; consultas de detalle (query-back) |
+| Mensajería con eventos | Bajo | La más robusta: elimina gran parte del acoplamiento temporal y obliga a diseñar contando con latencia [Destilado cap. 4] | Notificar hechos, coordinar procesos entre contextos |
+| Base de datos o ficheros compartidos | Estructural | Pésima. Evitar [Destilado cap. 4; IDDD cap. 13] | Solo heredados sin alternativa, con ACL |
+
+## Principios de la computación distribuida
+
+IDDD los formula como principios, no como falacias, para subrayar que hay que diseñar contando con ellos [IDDD cap. 13]: la red no es fiable; siempre hay latencia; el ancho de banda no es infinito; la red no es segura; la topología cambia; el conocimiento y las políticas están repartidos entre varios administradores; el transporte tiene coste; la red es heterogénea.
+
+## REST
+
+* El contexto que ofrece REST debe proporcionar un OHS con Published Language; los recursos son el idioma publicado [Destilado cap. 4].
+* Recursos **sintéticos**: con la forma que necesita el caso de uso del cliente, no la del agregado. Reflejar los agregados fuerza a todos los clientes a ser Conformist ante cualquier cambio del modelo [Destilado cap. 4].
+* Para reducir la dependencia temporal aunque solo haya REST: llama al sistema remoto desde un temporizador o al recibir un mensaje propio, con reintentos y espera creciente, en lugar de hacerlo dentro de la petición del usuario [IDDD cap. 13].
+
+### REST asíncrono (notification log)
+
+Publicar los eventos de dominio como un feed de recursos (al estilo Atom) que los clientes sondean periódicamente. Si el servicio no está disponible, el cliente reintenta más tarde [Destilado cap. 4]. IDDD lo implementa con un log de notificaciones actual y logs archivados navegables; cada cliente es responsable de no consumir duplicados [IDDD cap. 3 y cap. 13].
+
+## Mensajería
+
+* El contexto suscrito reacciona a eventos de dominio publicados por otros, y eso suele crear o modificar un agregado propio [Destilado cap. 4].
+* Si el cliente necesita forzar una acción, envía un **mensaje de comando** y recibe el resultado como un evento publicado [Destilado cap. 4].
+* **Entrega al menos una vez** en el mecanismo y **receptor idempotente** en el consumidor: deduplicar o reaplicar con el mismo resultado [Destilado cap. 4].
+* Las peticiones no deben bloquearse esperando respuesta; siempre habrá algo de latencia y hay que planificarla [Destilado cap. 4].
+
+### Publicar de forma fiable
+
+`[Fuera de los libros como nombre; la idea de guardar eventos en la misma transacción está en IDDD cap. 8]`. Patrón **outbox transaccional**: en la misma transacción que guarda el agregado, se guardan sus eventos en una tabla; un proceso aparte los lee y los publica en el bus, marcándolos como enviados. Evita perder eventos si el bus falla tras confirmar la transacción, o publicar eventos de cambios que luego se revierten. Se desarrolla en `ddd-skills/ddd-eventos-dominio/GUIA.md`. Con `@archi-code/ddd` la aplicación no abre transacciones: el caso de uso sigue llamando a `EventBus.publish` después de `save`, y el outbox lo escribe el adaptador del repositorio, que guarda el agregado y sus eventos pendientes en la misma escritura atómica de `save` (el mismo documento o la misma transacción de base de datos); un reenviador los entrega después por un `EventChannel` `[Fuera de los libros: convención de @archi-code/ddd]`.
+
+### Receptor idempotente en TypeScript
+
+El evento de Almacén llega por un `EventChannel` a un listener (`RegisterStockReservationOnStockReserved`, en `ddd-skills/ddd-context-mapping/references/anticorrupcion-ts.md`), que ejecuta un solo caso de uso. Ese caso de uso registra un hecho: no lo rechaza, vuelve sin error si el pedido no existe (un error haría que el canal lo reentregara sin fin) y el método del agregado es idempotente:
+
+```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 type { Clock, EventBus } from '@archi-code/ddd/application';
+import { Order, OrderEvent, OrderId, ReservationId } from '../../domain/order/Order';
+
+interface RegisterStockReservationInput {
+  orderId: string;
+  reservationId: string;
+}
+
+interface RegisterStockReservationCommand {
+  orderId: OrderId;
+  reservationId: ReservationId;
+}
+
+export class RegisterStockReservation extends UseCase<
+  RegisterStockReservationInput,
+  RegisterStockReservationCommand,
+  void
+> {
+  constructor(
+    private readonly orders: AggregateFinder<Order> & AggregateSaver<Order>,
+    private readonly events: EventBus<OrderEvent>,
+    private readonly clock: Clock,
+  ) {
+    super();
+  }
+
+  protected toCommand(input: RegisterStockReservationInput): RegisterStockReservationCommand {
+    return ValueObjects.build({
+      orderId: () => new OrderId(input.orderId),
+      reservationId: () => new ReservationId(input.reservationId),
+    });
+  }
+
+  protected async handle(command: RegisterStockReservationCommand): Promise<void> {
+    const order = await this.orders.findById(command.orderId);
+    if (order === null) {
+      return;
+    }
+    order.registerStockReservation(command.reservationId, this.clock);
+    await this.orders.save(order);
+    await this.events.publish(order.pullDomainEvents());
+  }
+}
+```
+
+El método de `Order` (el de `ddd-skills/ddd-agregados/references/implementacion-ts.md`), que guarda la reserva en `private _stockReservation: ReservationId | null` (`null` porque al principio no hay reserva) y confirma el pedido cuando también tiene la autorización de pago:
+
+```ts
+registerStockReservation(reservation: ReservationId, clock: { now(): Date }): void {
+  if (!this._status.isPending()) {
+    return;
+  }
+  this._stockReservation = reservation;
+  this.tryToConfirm(clock);
+}
+```
+
+Aplicar dos veces "reserva registrada" no cambia nada la segunda vez ni graba un segundo evento. Cuando la operación no es idempotente por naturaleza, el `eventId` del mensaje se guarda como procesado en la misma escritura atómica que el cambio, y si ya estaba no se hace nada `[Fuera de los libros]`; con el paquete esa escritura la hace el adaptador que persiste el cambio, no el caso de uso, que solo le pasa el `eventId` (ver "Consumidor idempotente" en `ddd-skills/ddd-eventos-dominio/references/publicacion-ts.md`) `[Fuera de los libros: convención de @archi-code/ddd]`. Si dos mensajes del mismo pedido llegan a la vez, `save` lanza `ConcurrencyException` en uno de ellos y el listener falla; lo que pase después lo decide el canal (reintento o cola de mensajes muertos), y en el reintento el caso de uso vuelve a cargar el pedido y la operación idempotente no cambia nada.
+
+## Contratos y versionado
+
+* Dos opciones para intercambiar estructuras: distribuir clases e interfaces a todos los sistemas (tipado fuerte, pero recompilaciones y riesgo de usar objetos ajenos como propios) o un contrato basado en estándar, un media type propio que es un Published Language [IDDD cap. 13].
+* Con contrato, el consumidor solo lee datos; no tiene acceso a comportamiento del otro modelo, y IDDD lo ve como protección, no como carencia. Los cálculos los hace el productor y los envía como atributos del evento [IDDD cap. 13].
+* 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]`:
+
+```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",
+  "lines": [
+    { "sku": "TORCH-01", "quantity": 2, "unitPrice": { "amount": 850, "currency": "EUR" } }
+  ],
+  "total": { "amount": 1700, "currency": "EUR" }
+}
+```
+
+`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).
+
+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").
+
+El consumidor no valida el mensaje con un esquema aparte: lo lee con su propia clase `extends EventBase` (solo los campos que usa) y el caso de uso que ejecuta su listener construye cada valor como value object en `toCommand`, que lanza una `ValidationException` con todos los campos que no cumplen el contrato. El ejemplo completo está en `ddd-skills/ddd-context-mapping/references/anticorrupcion-ts.md`.
+
+## Evento enriquecido o consulta al origen
+
+| | Evento enriquecido | Evento ligero + query-back |
+|---|---|---|
+| Autonomía del consumidor | Alta | Depende de que el origen responda |
+| Previsión de necesidades | Difícil acertar con todo | No hace falta |
+| Seguridad | Riesgo de exponer datos de más | El origen controla el acceso en cada consulta |
+
+Hay casos que piden una mezcla [Destilado cap. 4]. En el ejemplo del libro, `PolicyIssued` lleva el identificador de la póliza; el consumidor lo guarda como `issuedPolicyId` para trazabilidad y consulta al origen con `GET` si necesita más [Destilado cap. 4].
+
+Pauta `[Fuera de los libros]`: incluye en el evento lo que el consumidor necesita para decidir y que no cambiará (identificadores, importes cerrados, fechas del hecho); deja fuera datos personales que el consumidor no necesite (minimización de datos) y datos que cambian a menudo.
+
+## Procesos de larga duración
+
+Cuando un proceso implica a varios contextos, se coordina con eventos y un objeto que guarda el estado del proceso, con un rastreador de tiempos para detectar respuestas que no llegan (estados como no completado, completado normalmente o agotado por tiempo) [IDDD cap. 13]. En la práctica actual se llama a esto process manager o saga `[Fuera de los libros como nombres]`. Reglas:
+
+* El estado del proceso es un concepto del dominio con nombre del lenguaje (`ConfirmaciónDePedido`), no un `SagaState` genérico.
+* Cada paso tiene un resultado esperado y un plazo.
+* Las acciones compensatorias (liberar reserva, anular autorización) son comandos de negocio, no "rollbacks".
+* Cuando un recurso remoto aún no existe, modela esa situación como estado. En IDDD, una discusión remota tiene estados de disponibilidad: complemento no contratado, no solicitada, solicitada y lista [IDDD cap. 3].

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

@@ -0,0 +1,92 @@
+# Event Sourcing y CQRS
+
+> Parte del skill `archi-code-ddd`: léela solo cuando ese skill te dirija aquí. Los ejemplos están escritos con la API de `@archi-code/ddd` (las clases de su `src`) y se copian tal cual; las guías son la fuente de verdad: el paquete solo se aparta de ellas donde lo marca `[Fuera de los libros: convención de @archi-code/ddd]`, y cualquier otra discrepancia es un defecto del paquete.
+>
+> **Cuándo consultar esta guía.** Event Sourcing (agregados persistidos como secuencia de eventos, A+ES) y CQRS (modelo de comandos separado de modelos de lectura) con DDD en TypeScript. Empieza por decidir si compensan, y cubre stream de eventos por agregado, reconstitución, control de concurrencia con versión esperada, event store, snapshots, proyecciones y read models reconstruibles, consistencia eventual en la interfaz, enriquecimiento y versionado de eventos, y cómo cumplir el RGPD con eventos inmutables. Consúltala siempre que alguien mencione event sourcing, CQRS, read models, proyecciones, auditoría completa de cambios, "volver a un estado anterior", event store, o pantallas lentas que cruzan muchos agregados, aunque la pregunta sea solo "¿debería usar...?".
+
+## Con @archi-code/ddd
+
+[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()`.
+* 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.
+
+Dos patrones distintos que a menudo van juntos. **CQRS** separa el modelo que ejecuta comandos (agregados) de los modelos que responden consultas [IDDD cap. 4]. **Event Sourcing** guarda el estado de un agregado como la secuencia de eventos que le han ocurrido y lo reconstruye aplicándolos [Destilado cap. 6; IDDD apéndice A]. Event Sourcing casi siempre exige alguna forma de CQRS, porque los streams de eventos son difíciles de consultar [IDDD apéndice A; Destilado cap. 6]. CQRS no exige Event Sourcing.
+
+
+## Paso 1. Decidir (la mayoría de las veces, no)
+
+Ningún estilo es para todo: se usa donde mitiga un riesgo concreto [IDDD cap. 4].
+
+### CQRS
+
+| A favor | En contra |
+|---|---|
+| Vistas que cruzan muchos agregados y no encajan en repositorios [IDDD cap. 4] | Interfaz sencilla que sigue a un agregado: CQRS añade complejidad accidental [IDDD cap. 4] |
+| Volumen de lectura muy superior al de escritura `[Fuera de los libros]` | Usuarios que necesitan ver al instante lo que acaban de escribir, sin margen de diseño |
+| Muchos `findBy` en repositorios: señal de IDDD [IDDD cap. 12] | |
+
+Antes de CQRS completo, prueba el paso intermedio: consultas SQL de solo lectura sobre las mismas tablas (`ddd-skills/ddd-arquitectura/GUIA.md`).
+
+### Event Sourcing
+
+Beneficios [IDDD apéndice A; Destilado cap. 6]:
+* No se pierde el motivo de ningún cambio: auditoría completa, análisis, depuración mirando atrás.
+* Escritura solo por anexión, muy rápida.
+* Libertad estructural: la forma interna del agregado puede cambiar sin migrar datos; el stream se puede reproducir en otra infraestructura para depurar un error.
+* Tiende a producir agregados más pequeños.
+
+Inconvenientes que el propio apéndice reconoce [IDDD apéndice A]:
+* Definir buenos eventos exige conocer el dominio a fondo; solo compensa en modelos complejos que dan ventaja competitiva.
+* Obliga a CQRS: más carga cognitiva y curva de aprendizaje.
+
+Recomendación de estas fuentes `[Fuera de los libros]`: Event Sourcing solo en agregados del Core Domain donde el historial es un requisito de negocio (o legal) o donde las preguntas "¿cómo llegó a este estado?" son frecuentes. No en todo el sistema. Si solo hace falta auditoría, el outbox de `ddd-skills/ddd-eventos-dominio/GUIA.md` ya deja un registro de eventos sin cambiar la persistencia. Con el paquete, un `EventChannel` entrega los eventos pero no los conserva: para auditar, tu canal duradero (o un listener) guarda cada `SerializedEvent` en una tabla propia que no se borre `[Fuera de los libros: convención de @archi-code/ddd]`.
+
+## Paso 2. Implementar Event Sourcing
+
+Guía completa en `ddd-skills/ddd-event-sourcing-cqrs/references/event-sourcing-ts.md`. Esquema:
+
+1. El agregado (`extends AggregateRoot<PaymentId, PaymentEvent>`) separa **decidir** (métodos de comando que comprueban reglas y emiten eventos con `record`) de **aplicar** (un `apply` privado que cambia estado a partir de un evento). IDDD propone incluso dos clases, una de estado y otra de comportamiento, que solo colaboran a través de `apply` [IDDD apéndice A].
+2. Cargar: leer el stream del agregado, reconstruir cada evento con `EventRegistry.fromJSON` y aplicarlos en orden (`Payment.fromHistory`).
+3. Ejecutar el comando: genera eventos nuevos, que `pullDomainEvents()` devuelve como cambios pendientes.
+4. Guardar: anexar los cambios con la **versión esperada** del stream (`streamVersion()`); si otro escribió antes, conflicto (`ConcurrencyException`) [IDDD apéndice A].
+5. Ante conflicto: reintentar recargando y reejecutando, o propagar al cliente [IDDD apéndice A]. Con el paquete, el bucle va en el `handle` del caso de uso, con un límite de intentos, y cada intento vuelve a cargar el stream y vuelve a anexar; un caso de uso que lanza un listener no reintenta por sí mismo, lo hace la reentrega del canal.
+6. Publicar: un proceso en segundo plano lee lo anexado y lo publica [IDDD apéndice A]. Con el paquete, el caso de uso publica con `EventBus` después de `append`; para no perder eventos si `publish` falla, el propio event store hace de bandeja (el `append` atómico ya los guardó) y un reenviador los entrega por un `EventChannel`.
+
+Rendimiento: caché de streams en memoria (los eventos son inmutables) y **snapshots** para streams largos [IDDD apéndice A; Destilado cap. 6].
+
+## Paso 3. Proyecciones y read models
+
+Suscriptores que reciben eventos y mantienen modelos de lectura persistentes (con el paquete, `EventListener` suscritos al `DomainEventBus` e idempotentes por `eventId`); parecidos a un agregado, pero para consultar [IDDD apéndice A]. Se pueden **reconstruir** reproduciendo todos los eventos, lo que permite cambiar una vista sin tocar el agregado [IDDD apéndice A]. También sirven para dar a un agregado datos de otro de forma desacoplada, a través de un servicio de dominio que consulta la proyección [IDDD apéndice A].
+
+Guía en `ddd-skills/ddd-event-sourcing-cqrs/references/proyecciones-cqrs-ts.md`.
+
+## Paso 4. La interfaz con un modelo de lectura eventual
+
+Diseña para el peor caso: la vista siguiente puede no reflejar todavía el comando [IDDD cap. 4]. Opciones de IDDD: mostrar temporalmente lo enviado; mostrar la antigüedad de los datos; actualizaciones push; o avisar de que la operación se está procesando [IDDD cap. 4].
+
+## Paso 5. Eventos con doble función
+
+En Event Sourcing los eventos sirven para persistir el agregado **y** para comunicar al resto de la empresa. Eso crea tensión: lo que necesita el agregado no es lo que necesitan los consumidores. IDDD lo trata como enriquecimiento de eventos [IDDD apéndice A]. Pauta `[Fuera de los libros]`: eventos internos del stream con lo mínimo para reconstruir, y eventos publicados traducidos al Published Language (igual que en `ddd-skills/ddd-eventos-dominio/GUIA.md`).
+
+## Datos personales e inmutabilidad
+
+`[Fuera de los libros]` Un stream inmutable choca con el derecho de supresión del RGPD. Opciones: no guardar datos personales en los eventos (solo identificadores y los datos en un almacén borrable); o cifrar los datos personales con una clave por persona y destruir la clave al suprimir ("crypto-shredding"). Decide esto antes de escribir el primer evento.
+
+## Señales de alarma
+
+* Event Sourcing en todo el sistema "por si acaso".
+* 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()`.
+* 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.
+
+## Siguiente guía
+
+* Revisar un sistema existente → `ddd-skills/ddd-auditoria-refactorizacion/GUIA.md`.