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

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

@@ -0,0 +1,419 @@
+# 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/infrastructure';
+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`). `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 type { AggregateSaver } from '@archi-code/ddd/domain';
+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';
+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 ValueObjectBuilder.build({
+      orderId: () => OrderId.generate(),
+      customerId: () => new CustomerId(input.customerId),
+      items: () =>
+        ValueObjectBuilder.buildList(input.items, (item) =>
+          ValueObjectBuilder.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 `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 `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 { 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';
+
+export interface GatewayEvent {
+  type: string;
+  created: number;
+  amount: number;
+  currency: string;
+  failure_code?: string;
+  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 logger: Logger,
+  ) {}
+
+  async receive(event: GatewayEvent): Promise<{ status: number }> {
+    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) {
+      const kind = ExceptionClassifier.classify(error);
+      if (kind === ExceptionKind.Internal) {
+        this.logger.error('payment_webhook_failed', { type: event.type, error });
+      }
+      return { status: statusOf(kind) };
+    }
+  }
+}
+```
+
+`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(
+    readonly reservationId: string,
+    readonly orderId: string,
+    metadata?: EventMetadata,
+  ) {
+    super(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.reservationId,
+    });
+  }
+}
+```
+
+```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.reservationId as string, 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,152 @@
+# 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 type { AggregateFinder, AggregateSaver } from '@archi-code/ddd/domain';
+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';
+
+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 ValueObjectBuilder.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 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",
+  "eventId": "6f1c2a3b-8d4e-4f5a-9b6c-7d8e9f0a1b2c",
+  "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` 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").
+
+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].