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

package/ddd-skills/ddd-event-sourcing-cqrs/references/proyecciones-cqrs-ts.md

@@ -0,0 +1,285 @@
+# Proyecciones y CQRS en TypeScript
+
+El paquete da las piezas de la entrega (`EventListener`, `@ListensTo`, `DomainEventBus`, `EventRegistry`, `EventChannel`); el modelo de lectura, su escritura idempotente, la reconstrucción y las consultas son código del proyecto. Los ejemplos usan los eventos `OrderPlaced` (`customerId`, `lines`, `total`) y `OrderLineAdded` (`sku`, `quantity`, `unitPrice`, `total`) del pedido de `ddd-skills/ddd-agregados/references/implementacion-ts.md`, subclases de `EventBase` como en `ddd-skills/ddd-eventos-dominio/GUIA.md`.
+
+## Modelo de lectura
+
+Pensado para la pantalla: desnormalizado, una tabla o documento por vista, tantas vistas como hagan falta (sin caer en una por usuario: IDDD recomienda filtros cuando el número de vistas sería impracticable) [IDDD cap. 4].
+
+```sql
+CREATE TABLE order_summaries (
+  order_id    TEXT PRIMARY KEY,
+  customer    TEXT        NOT NULL,
+  line_count  INT         NOT NULL,
+  units       INT         NOT NULL,
+  total_cents BIGINT      NOT NULL,
+  currency    TEXT        NOT NULL,
+  updated_at  TIMESTAMPTZ NOT NULL
+);
+CREATE TABLE projection_inbox (
+  projection  TEXT NOT NULL,
+  event_id    UUID NOT NULL,
+  PRIMARY KEY (projection, event_id)
+);
+```
+
+`updated_at` (el `occurredOn` del último evento aplicado) permite mostrar la antigüedad del dato [IDDD cap. 4]. `projection_inbox` guarda el `eventId` de cada evento ya aplicado: la entrega es al menos una vez, así que la proyección es idempotente por `eventId`.
+
+## Proyección idempotente
+
+`[Fuera de los libros: convención de @archi-code/ddd]` Una proyección se suscribe al bus como cualquier listener: un `EventListener` por evento, marcado con `@ListensTo(Event, { consumer })`, con nombre `<Action>On<Event>`. Como no cambia ningún agregado, no ejecuta un caso de uso: llama a un puerto de la aplicación (`OrderSummaryProjection`) que la infraestructura implementa sobre la tabla de lectura.
+
+```ts
+import { EventListener, ListensTo } from '@archi-code/ddd/application';
+
+export interface OrderSummaryProjection {
+  orderPlaced(event: OrderPlaced): Promise<void>;
+  orderLineAdded(event: OrderLineAdded): Promise<void>;
+}
+
+@ListensTo(OrderPlaced, { consumer: 'order-summaries.v1.order-placed' })
+export class ProjectOrderSummaryOnOrderPlaced extends EventListener<OrderPlaced> {
+  constructor(private readonly summaries: OrderSummaryProjection) {
+    super();
+  }
+
+  handle(event: OrderPlaced): Promise<void> {
+    return this.summaries.orderPlaced(event);
+  }
+}
+
+@ListensTo(OrderLineAdded, { consumer: 'order-summaries.v1.order-line-added' })
+export class ProjectOrderSummaryOnOrderLineAdded extends EventListener<OrderLineAdded> {
+  constructor(private readonly summaries: OrderSummaryProjection) {
+    super();
+  }
+
+  handle(event: OrderLineAdded): Promise<void> {
+    return this.summaries.orderLineAdded(event);
+  }
+}
+```
+
+La implementación registra el `eventId` en `projection_inbox` y aplica el cambio en la misma transacción; si el `eventId` ya estaba, no hace nada `[Fuera de los libros]`:
+
+```ts
+import type { EventBase } from '@archi-code/ddd/domain';
+import { InfrastructureException } from '@archi-code/ddd/exceptions';
+
+interface Sql {
+  query<Row>(text: string, values: readonly unknown[]): Promise<{ rows: Row[]; rowCount: number }>;
+}
+
+interface SqlDatabase {
+  transaction<Result>(work: (sql: Sql) => Promise<Result>): Promise<Result>;
+}
+
+export class PgOrderSummaryProjection implements OrderSummaryProjection {
+  constructor(
+    private readonly database: SqlDatabase,
+    private readonly table = 'order_summaries',
+  ) {}
+
+  orderPlaced(event: OrderPlaced): Promise<void> {
+    return this.once(event, async (sql) => {
+      await sql.query(
+        `INSERT INTO ${this.table}
+           (order_id, customer, line_count, units, total_cents, currency, updated_at)
+         VALUES ($1, $2, $3, $4, $5, $6, $7) ON CONFLICT (order_id) DO NOTHING`,
+        [
+          event.aggregateId,
+          event.customerId,
+          event.lines.length,
+          event.lines.reduce((units, line) => units + line.quantity, 0),
+          event.total.amount,
+          event.total.currency,
+          event.occurredOn,
+        ],
+      );
+    });
+  }
+
+  orderLineAdded(event: OrderLineAdded): Promise<void> {
+    return this.once(event, async (sql) => {
+      const { rowCount } = await sql.query(
+        `UPDATE ${this.table}
+         SET line_count = line_count + 1, units = units + $2, total_cents = total_cents + $3,
+             updated_at = GREATEST(updated_at, $4)
+         WHERE order_id = $1`,
+        [
+          event.aggregateId,
+          event.quantity,
+          event.quantity * event.unitPrice.amount,
+          event.occurredOn,
+        ],
+      );
+      if (rowCount === 0) {
+        throw new InfrastructureException(
+          `${this.table}: order ${event.aggregateId} is not projected yet`,
+        );
+      }
+    });
+  }
+
+  private once(event: EventBase, work: (sql: Sql) => Promise<void>): Promise<void> {
+    return this.database.transaction(async (sql) => {
+      const { rowCount } = await sql.query(
+        'INSERT INTO projection_inbox (projection, event_id) VALUES ($1, $2) ON CONFLICT DO NOTHING',
+        [this.table, event.eventId],
+      );
+      if (rowCount === 1) {
+        await work(sql);
+      }
+    });
+  }
+}
+```
+
+* Sumar unidades e importes no es idempotente por sí mismo; la bandeja por `eventId` lo hace idempotente. Se suma el subtotal de la línea (`quantity` × `unitPrice`) en vez de copiar el `total` del evento, para que dos `OrderLineAdded` del mismo pedido entregados en otro orden dejen el mismo resultado.
+* Un canal solo garantiza el orden de los eventos de un mismo `send` para un consumidor. Si `OrderLineAdded` llega antes que `OrderPlaced`, la actualización no encuentra fila: lanzar deshace la transacción (también la marca en la bandeja) y el canal lo entrega de nuevo más tarde.
+* El listener recibe siempre el evento reconstruido por el `EventRegistry` desde su JSON, también en memoria: lo que funciona con `InMemoryEventChannel` funciona igual con un broker.
+
+En la composición se suscriben como cualquier listener (`channel` es el `EventChannel` del proyecto: `InMemoryEventChannel` en pruebas, tu canal duradero o de broker en producción):
+
+```ts
+import { DomainEventBus, EventRegistry } from '@archi-code/ddd/infrastructure';
+
+export const orderEvents = new EventRegistry<OrderEvent>()
+  .register(
+    OrderPlaced,
+    (json) =>
+      new OrderPlaced(
+        json.aggregateId,
+        json.customerId as string,
+        json.lines as OrderLineData[],
+        json.total as MoneyData,
+        json,
+      ),
+  )
+  .register(
+    OrderLineAdded,
+    (json) =>
+      new OrderLineAdded(
+        json.aggregateId,
+        json.sku as string,
+        json.quantity as number,
+        json.unitPrice as MoneyData,
+        json.total as MoneyData,
+        json,
+      ),
+  );
+
+const bus = new DomainEventBus<OrderEvent>(channel, orderEvents);
+const projection = new PgOrderSummaryProjection(database);
+await bus.subscribe(new ProjectOrderSummaryOnOrderPlaced(projection));
+await bus.subscribe(new ProjectOrderSummaryOnOrderLineAdded(projection));
+```
+
+## Reconstruir
+
+Para cambiar una vista: crear `order_summaries_v2`, proyectar desde la posición 0 en segundo plano, cambiar la consulta cuando alcance el presente y borrar la antigua. Es la ventaja que destaca IDDD: cambiar lo que se ofrece sin modificar el agregado [IDDD apéndice A].
+
+`[Fuera de los libros: convención de @archi-code/ddd]` Un `EventChannel` es un camino de entrega, no un historial: reconstruir exige un log de eventos propio, ordenado. Con Event Sourcing es el propio event store (por `global_seq`, ver `ddd-skills/ddd-event-sourcing-cqrs/references/event-sourcing-ts.md`); sin él, una tabla donde tu canal duradero o un listener anexa cada `SerializedEvent` y que nunca se borra. Para reproducirlo con los mismos listeners, súbelos a un `DomainEventBus` sobre un `InMemoryEventChannel` aparte y envía el log por páginas:
+
+```ts
+import type { SerializedEvent } from '@archi-code/ddd/domain';
+import type { EventRegistry } from '@archi-code/ddd/infrastructure';
+import { DomainEventBus, InMemoryEventChannel } from '@archi-code/ddd/infrastructure';
+
+export interface EventLog {
+  read(after: number, limit: number): Promise<{ position: number; event: SerializedEvent }[]>;
+}
+
+export async function rebuild(
+  log: EventLog,
+  projection: OrderSummaryProjection,
+  registry: EventRegistry<OrderEvent>,
+): Promise<void> {
+  const replay = new InMemoryEventChannel();
+  const bus = new DomainEventBus<OrderEvent>(replay, registry);
+  const subscriptions = [
+    await bus.subscribe(new ProjectOrderSummaryOnOrderPlaced(projection)),
+    await bus.subscribe(new ProjectOrderSummaryOnOrderLineAdded(projection)),
+  ];
+  for (let after = 0; ; ) {
+    const page = await log.read(after, 500);
+    if (page.length === 0) {
+      break;
+    }
+    await replay.send(page.map((entry) => entry.event));
+    after = page[page.length - 1].position;
+  }
+  await Promise.all(subscriptions.map((subscription) => subscription.unsubscribe()));
+}
+```
+
+`rebuild(log, new PgOrderSummaryProjection(database, 'order_summaries_v2'), orderEvents)` llena la tabla nueva; el canal en memoria entrega en serie y en orden, y si un evento falla, `send` rechaza y la reconstrucción se detiene. Al desplegar la versión 2, cambia también el `consumer` de sus listeners (`order-summaries.v2.order-placed`): es su identidad en el canal (su cola en un broker), y la bandeja por `eventId` absorbe los eventos que lleguen por las dos vías mientras la reconstrucción alcanza el presente.
+
+## Lado de consulta
+
+Una consulta de lectura es una interfaz de la aplicación que devuelve DTOs, implementada en infraestructura directamente sobre la base de datos:
+
+```ts
+import { InternalErrorException } from '@archi-code/ddd/exceptions';
+
+export interface OrderSummary {
+  readonly id: string;
+  readonly customer: string;
+  readonly lines: number;
+  readonly units: number;
+  readonly total: { readonly amount: number; readonly currency: string };
+  readonly updatedAt: string;
+}
+
+export interface OrderSummaries {
+  ofCustomer(customer: string, page: { limit: number; offset: number }): Promise<OrderSummary[]>;
+}
+
+interface SummaryRow {
+  order_id: string;
+  customer: string;
+  line_count: number;
+  units: number;
+  total_cents: string;
+  currency: string;
+  updated_at: Date;
+}
+
+export class PgOrderSummaries implements OrderSummaries {
+  constructor(private readonly sql: Sql) {}
+
+  async ofCustomer(
+    customer: string,
+    page: { limit: number; offset: number },
+  ): Promise<OrderSummary[]> {
+    try {
+      const { rows } = await this.sql.query<SummaryRow>(
+        `SELECT order_id, customer, line_count, units, total_cents, currency, updated_at
+         FROM order_summaries
+         WHERE customer = $1 ORDER BY updated_at DESC, order_id LIMIT $2 OFFSET $3`,
+        [customer, page.limit, page.offset],
+      );
+      return rows.map((row) => ({
+        id: row.order_id,
+        customer: row.customer,
+        lines: row.line_count,
+        units: row.units,
+        total: { amount: Number(row.total_cents), currency: row.currency },
+        updatedAt: row.updated_at.toISOString(),
+      }));
+    } catch (error) {
+      throw new InternalErrorException('reading order summaries', { cause: error });
+    }
+  }
+}
+```
+
+Las consultas no pasan por agregados ni repositorios (`AggregateFinder`). Los comandos sí. Si la pantalla filtra y ordena por campos que elige el usuario, describe la búsqueda con `@archi-code/criteria` (`Criteria<OrderSummary>`, con `defineCriteriaSchema` para la entrada de fuera) en vez de añadir un método por combinación.
+
+## CQRS sin Event Sourcing
+
+Con persistencia de estado normal (repositorios que guardan `toPrimitives()` de cada agregado), las proyecciones se alimentan de los mismos eventos que los casos de uso publican con `EventBus.publish(aggregate.pullDomainEvents())` (`ddd-skills/ddd-eventos-dominio/GUIA.md`). Mismo patrón: idempotencia por `eventId` y reconstrucción desde un log de eventos guardados. `[Fuera de los libros: convención de @archi-code/ddd]` El canal no conserva historial legible: si la vista debe poder reconstruirse desde cero, guarda cada evento en un log propio desde el primer día.
+
+## Proyecciones para otros agregados
+
+IDDD muestra una proyección (`CustomerBillingView`) que un agregado `Invoice` consulta a través de un servicio de dominio para obtener datos de cliente sin acoplarse al agregado `Customer` [IDDD apéndice A]. Con el paquete, el servicio de dominio declara un puerto en `domain/` con value objects, la infraestructura lo implementa sobre la tabla de la proyección y el caso de uso pasa los datos ya cargados al método del agregado. Úsalo para datos de referencia, nunca para proteger invariantes que exijan consistencia inmediata.

package/ddd-skills/ddd-eventos-dominio/GUIA.md

@@ -0,0 +1,106 @@
+# Eventos de dominio
+
+> 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.** Eventos de dominio en DDD con TypeScript. Cubre cómo nombrarlos en pasado con el lenguaje ubicuo, decidir qué datos llevan (ni el objeto entero ni eventos "XxxUpdated"), eventos causados por el paso del tiempo, diferencia entre comando y evento, registrarlos en el agregado, guardarlos en la misma escritura atómica que el agregado (event store u outbox) y publicarlos después, consumidores idempotentes, orden causal, versionado y eventos internos frente a eventos publicados a otros contextos. Consúltala siempre que se diseñe un evento, un mensaje entre servicios, una notificación de "cuando pase X", un webhook propio, una cola o un bus, que se pierdan o dupliquen mensajes, o que un cambio deba disparar acciones en otra parte del sistema, aunque no se diga "domain event".
+
+## Con @archi-code/ddd
+
+[Fuera de los libros: convención de @archi-code/ddd]
+
+* Los eventos extienden `EventBase`, declaran `static readonly eventName` con el nombre de su clase en pasado (`'OrderPlaced'`) y `static readonly eventVersion` cuando sus datos cambian de forma incompatible (1 si no se declara); llaman a `super(aggregateId, { clock })` y la base pone `eventId` (UUID v4) y `occurredOn`. El payload son primitivos sacados de los value objects (el dinero como `{ amount, currency }`), nunca value objects ni `toPrimitives()` del agregado.
+* El agregado registra con `record()` (que congela el evento) y el caso de uso publica con `await this.events.publish(order.pullDomainEvents())` justo después de `await this.orders.save(order)`. La aplicación nunca abre, une ni cierra transacciones y no hay puerto para ello: cada `save` es una escritura atómica que garantiza el repositorio. Si `publish` falla después de `save`, el evento se puede perder; cuando un evento no puede perderse, el adaptador del repositorio escribe el agregado y sus eventos pendientes en la misma escritura atómica (un outbox en el mismo documento o en la misma transacción de base de datos de `save`) y un reenviador los entrega después por un `EventChannel`. Es persistencia, así que va en el repositorio, y el caso de uso no cambia. Fuera de ese caso, el repositorio no toca los eventos.
+* La aplicación solo tiene el contrato de eventos, en `@archi-code/ddd/application`: para publicar, el puerto `EventBus` (lo único que ve el caso de uso); para escuchar, `EventListener` + `@ListensTo` (`ListensTo.subscriptionOf(listener)` da `{ eventName, consumer }`). Lo que mueve los eventos es infraestructura y lo usa solo el composition root, desde `@archi-code/ddd/infrastructure`: `DomainEventBus(channel, registry)` implementa `EventBus` sobre un `EventChannel` (con `ChannelHandler` y `ChannelSubscription`), que es lo único que implementa cada tecnología (`InMemoryEventChannel` en el paquete; un outbox o un broker en tu infraestructura). Los listeners reciben siempre el evento reconstruido desde su JSON por `EventRegistry`, cuya fábrica pasa el JSON como metadatos para conservar `eventId` y `occurredOn`.
+* Un listener extiende `EventListener<Event>`, escucha un único evento con `@ListensTo(EventClass, { consumer })` (un nombre de consumidor estable y explícito, su identidad en el canal), se llama `<Acción>On<Evento>` y solo traduce el evento a la entrada de un caso de uso.
+* El paquete no trae outbox, canal de broker, deduplicación ni traducción al lenguaje publicado: se escriben en el proyecto sobre el puerto `EventChannel` y los puertos propios, como en `ddd-skills/ddd-eventos-dominio/references/publicacion-ts.md`.
+* `InMemoryEventChannel` entrega en cuanto se llama a `publish`, antes de que termine el `execute` del caso de uso que publica: sirve para tests (`channel.sent` lista lo publicado; `{ delivery: 'parallel' }` ejecuta juntos los listeners de un evento), nunca como entrega durable en producción.
+
+Un evento de dominio es el registro de algo que ha ocurrido y que importa al negocio en un Bounded Context [Destilado cap. 6]. Es parte de pleno derecho del modelo [IDDD cap. 8, citando a Evans] y la pieza que hace posible la consistencia eventual entre agregados y la integración entre contextos.
+
+
+## Paso 1. Diseñarlos
+
+Guía completa y ejemplos en `ddd-skills/ddd-eventos-dominio/references/diseno-eventos.md`. Lo esencial:
+
+* **Nombre:** verbo en pasado, con el lenguaje del contexto que lo origina, normalmente derivado del comando (`commitTo` → `BacklogItemCommitted`) [Destilado cap. 6; IDDD cap. 8].
+* **Datos:** cuándo ocurrió, la identidad del agregado afectado y de los implicados, y lo necesario para entender qué pasó: a menudo los parámetros del comando y algún valor del estado resultante [Destilado cap. 6; IDDD cap. 8].
+* **Sin el estado completo:** un evento lleno de datos pierde su significado, y un `XxxUpdated` con todo el estado obliga al consumidor a comparar versiones para adivinar qué cambió [Destilado cap. 6].
+* **Inmutables**, con constructor completo y solo lectura [IDDD cap. 8].
+* **El tiempo también causa eventos:** el fin de un periodo es un hecho, no un comando, y suele tener nombre en el lenguaje ("cierre de mercado", "fin de ejercicio fiscal") [Destilado cap. 6].
+* **Comando ≠ evento:** un comando se puede rechazar; un evento es un hecho y no se puede negar [Destilado cap. 6].
+
+## Paso 2. Guardar y publicar sin perder ni inventar
+
+Regla de oro: el agregado modificado y su evento se guardan **en la misma transacción**; después se publica [Destilado cap. 6]. IDDD da tres formas de mantener modelo y mensajería consistentes [IDDD cap. 8]:
+
+| Opción | Ventaja | Inconveniente |
+|---|---|---|
+| Modelo y mensajería comparten almacén | Una transacción local | Tablas del bus en tu base; no siempre posible |
+| Transacción global (XA, dos fases) | Almacenes separados | Cara, lenta, no siempre soportada |
+| **Event store propio en la base del modelo + reenviador** | Consistencia garantizada en una transacción local; permite feeds REST | Hay que construir el reenviador y los consumidores deben deduplicar |
+
+Recomendación de estas fuentes: la tercera, conocida hoy como **outbox transaccional** `[Fuera de los libros como nombre]`. `[Fuera de los libros: convención de @archi-code/ddd]` Con el paquete, "la misma transacción" es la escritura atómica del repositorio: el adaptador guarda el agregado y sus eventos pendientes juntos dentro de su `save`, y la aplicación no ve ninguna transacción. Implementación en `ddd-skills/ddd-eventos-dominio/references/publicacion-ts.md`.
+
+## Paso 3. Consumirlos bien
+
+* El suscriptor que reacciona dentro de la misma transacción **no debe modificar otro agregado**; eso rompe la regla de un agregado por transacción. Las reacciones que modifican agregados van fuera de banda, cada una en su transacción [IDDD cap. 8].
+* Entrega al menos una vez → consumidor idempotente. Identidad única del mensaje o del evento para deduplicar [IDDD cap. 8; Destilado cap. 4].
+* Guardar en orden causal no garantiza recibir en ese orden en otros nodos. El consumidor es responsable de respetar la causalidad, usando el tipo de evento o metadatos (secuencia, identificador de causa); a veces puede ignorar eventos ya superados por otros posteriores [Destilado cap. 6].
+* Los consumidores de otros contextos no copian objetos: ejecutan comportamiento de **su** modelo según el significado del evento en su contexto [IDDD cap. 8].
+* Si un evento no lleva lo que un suscriptor necesita, el contrato debe cambiar, probablemente con una nueva versión o un evento distinto [IDDD cap. 8].
+
+Con el paquete, la reacción es un listener que lanza un caso de uso, y ese caso de uso carga y guarda su propio agregado con su repositorio, en su propia escritura atómica. Con `InMemoryEventChannel` el listener corre antes de que termine el `execute` del caso de uso que publicó, lo que solo vale en tests; en producción un canal durable lo entrega después de que la escritura del primero se haya confirmado, y cada reacción hace su propia escritura [IDDD cap. 8] `[Fuera de los libros: convención de @archi-code/ddd]`. El listener le pasa el `eventId` para que el caso de uso pueda saltarse una entrega repetida (ver "Consumidor idempotente" en `ddd-skills/ddd-eventos-dominio/references/publicacion-ts.md`):
+
+```ts
+import { EventListener, ListensTo } from '@archi-code/ddd/application';
+
+@ListensTo(OrderLineAdded, { consumer: 'prepare-shipment-on-order-line-added' })
+export class PrepareShipmentOnOrderLineAdded extends EventListener<OrderLineAdded> {
+  constructor(private readonly prepareShipment: PrepareShipment) {
+    super();
+  }
+
+  async handle(event: OrderLineAdded): Promise<void> {
+    await this.prepareShipment.execute({
+      eventId: event.eventId,
+      orderId: event.aggregateId,
+      sku: event.sku,
+      quantity: event.quantity,
+    });
+  }
+}
+```
+
+## Eventos internos y eventos publicados
+
+`[Fuera de los libros como terminología; la idea está en IDDD cap. 13 (Published Language) y cap. 8]`
+
+| | Evento de dominio interno | Evento publicado (integración) |
+|---|---|---|
+| Consumidores | El propio contexto | Otros contextos |
+| Forma | Clase `EventBase` del dominio | Esquema JSON versionado (Published Language), `sales.order.OrderPlaced` |
+| Puede cambiar | Con el modelo | Solo con versión nueva y compatibilidad |
+| Contenido | Lo que el modelo necesita | Lo que el contrato promete; sin datos personales innecesarios |
+
+No publiques las clases de dominio ni su `toJSON()` tal cual hacia fuera. Traduce el evento serializado (`SerializedEvent`) al contrato publicado en el adaptador que habla con el broker, con `messageId` = `eventId` [IDDD cap. 13]; el paquete no trae esa traducción (ver "Lenguaje publicado en el adaptador del broker" en `ddd-skills/ddd-eventos-dominio/references/publicacion-ts.md`).
+
+## Señales de alarma
+
+* Eventos en presente o imperativo (`CreateOrder`, `OrderUpdate`).
+* `OrderUpdated` con el pedido entero [Destilado cap. 6].
+* Publicar al bus dentro del método del agregado o antes de `save`; abrir o recibir una transacción en el caso de uso para "publicar dentro"; o confiar en que `InMemoryEventChannel` es una entrega durable. Un evento que no puede perderse va al outbox en la misma escritura atómica del repositorio.
+* Escribir en el proyecto `DomainEvent`, `EventPublisher` o un segundo bus (`RabbitMqEventBus`): los eventos extienden `EventBase` y cada tecnología implementa solo `EventChannel`.
+* Una fábrica de `EventRegistry` que no pasa el JSON como metadatos: el evento reconstruido tendría otro `eventId` y no se podría deduplicar (`fromJSON` lo rechaza).
+* Un handler síncrono que modifica otro agregado en la misma transacción o escritura [IDDD cap. 8].
+* Consumidores sin deduplicación.
+* Eventos con datos personales que el consumidor no necesita.
+* Otros contextos que importan la clase del evento del productor.
+
+## Ejemplo
+
+`ddd-skills/ddd-eventos-dominio/references/ejemplo-ecommerce.md` contiene el catálogo de eventos de la tienda online con sus decisiones.
+
+## Siguiente guía
+
+* Persistir el agregado como secuencia de eventos → `ddd-skills/ddd-event-sourcing-cqrs/GUIA.md`.
+* Cómo encaja la publicación en el caso de uso → `ddd-skills/ddd-servicios-capa-aplicacion/GUIA.md`.

package/ddd-skills/ddd-eventos-dominio/references/diseno-eventos.md

@@ -0,0 +1,131 @@
+# Diseñar eventos de dominio
+
+## Nombre
+
+* Pasado, con el lenguaje del contexto de origen [Destilado cap. 6; IDDD cap. 8].
+* Normalmente derivado del comando que lo causa: `PlaceOrder` → `OrderPlaced`, `AddOrderLine` → `OrderLineAdded` [Destilado cap. 6].
+* Tan compacto como permita el lenguaje. IDDD prefiere `BacklogItemCommitted` a `BacklogItemCommittedToSprint` porque en Scrum un elemento solo se compromete en un sprint; si el equipo prefiere el nombre largo en algún caso, vale [IDDD cap. 8].
+* La combinación del nombre y sus propiedades cuenta por completo lo que pasó en el modelo [Destilado cap. 6].
+* Con el paquete, el nombre es la clase y su `static readonly eventName` (`'OrderPlaced'`); el nombre `sales.order.OrderPlaced` queda para el contrato publicado a otros contextos [IDDD cap. 13] `[Fuera de los libros: convención de @archi-code/ddd]`.
+
+| Mal | Bien | Por qué |
+|---|---|---|
+| `OrderUpdated` | `OrderLineAdded`, `ShippingAddressChanged` | Dice qué cambió |
+| `PlaceOrder` | `OrderPlaced` | Es un hecho, no una orden |
+| `OrderStatusChangedToConfirmed` | `OrderConfirmed` | El lenguaje ya tiene la palabra |
+| `PaymentWebhookReceived` | `PaymentAuthorized` | Lenguaje del dominio, no del transporte |
+| `TimerElapsed` | `PaymentAuthorizationExpired` | El paso del tiempo con nombre de negocio [Destilado cap. 6] |
+
+## Datos
+
+Pregunta guía: ¿qué estimuló la publicación del evento? Normalmente un comando, y el evento debería llevar las propiedades que llevaba ese comando [Destilado cap. 6]. IDDD añade [IDDD cap. 8]:
+
+* Marca de tiempo de cuándo ocurrió (`occurredOn`, que pone `EventBase`).
+* Lo necesario para "volver a disparar" el evento: identidad del agregado (`aggregateId`, el primer argumento de `super`) y de los agregados implicados.
+* Parámetros del comando si se demuestran útiles.
+* Valores del estado resultante que ayuden a los suscriptores.
+* En entornos multi-tenant, siempre el `tenantId`, aunque no viniera en el comando.
+
+Ejemplo de IDDD: `BacklogItemCommitted` lleva `tenantId`, `backlogItemId` y `sprintId`. El `sprintId` es imprescindible porque el requisito dice que el sprint debe enterarse [IDDD cap. 8].
+
+Lista de comprobación `[Fuera de los libros]`:
+* ¿Un consumidor puede decidir qué hacer sin consultar al origen? Si no, ¿es aceptable que consulte (query-back)?
+* ¿Hay datos personales? ¿Los necesita cada consumidor?
+* ¿Los importes llevan moneda? ¿Las fechas, zona horaria?
+* ¿Algún valor cambia a menudo y quedará obsoleto enseguida? Mejor fuera.
+
+## Forma en TypeScript
+
+Un evento extiende `EventBase` de `@archi-code/ddd/domain`, declara `static readonly eventName` y recibe sus datos como primitivos sacados de los value objects (el dinero como `{ amount, currency }` en céntimos), nunca value objects ni el `toPrimitives()` del agregado `[Fuera de los libros: convención de @archi-code/ddd]`:
+
+```ts
+import { EventBase } from '@archi-code/ddd/domain';
+import type { EventMetadata } from '@archi-code/ddd/domain';
+
+export interface MoneyData {
+  readonly amount: number;
+  readonly currency: string;
+}
+
+export class OrderConfirmed extends EventBase {
+  static readonly eventName = 'OrderConfirmed';
+
+  constructor(
+    orderId: string,
+    readonly total: MoneyData,
+    metadata?: EventMetadata,
+  ) {
+    super(orderId, metadata);
+  }
+}
+```
+
+El agregado lo registra en el método que causa el hecho, pasando el reloj que recibió para que `occurredOn` sea determinista en los tests. En el `Order` de `ddd-skills/ddd-agregados/references/implementacion-ts.md` el pedido se confirma solo cuando ya tiene reserva y autorización, desde `registerStockReservation` o `registerPaymentAuthorization`:
+
+```ts
+private tryToConfirm(clock: { now(): Date }): void {
+  if (this._stockReservation !== null && this._paymentAuthorization !== null) {
+    this._status = new OrderStatus(Status.Confirmed);
+    this.record(new OrderConfirmed(this.id.value, Order.moneyData(this.total()), { clock }));
+  }
+}
+```
+
+`EventBase` pone `eventId` (UUID v4) y `occurredOn` (del `clock`, o la hora del sistema), y `record()` congela el evento: inmutable y con constructor completo [IDDD cap. 8]. No generes tú el id ni la fecha de un evento nuevo; pasa `{ eventId, occurredOn }` (o el JSON entero) solo al reconstruir uno que entregó un canal. `toJSON()` da la forma que viaja:
+
+```ts
+const [confirmed] = order.pullDomainEvents();
+confirmed.toJSON();
+// { eventName: 'OrderConfirmed', eventVersion: 1, eventId: '…', aggregateId: '9b2f6c1e-…',
+//   occurredOn: '2026-03-01T09:30:00.000Z', total: { amount: 7000, currency: 'EUR' } }
+```
+
+## Identidad del evento
+
+* Dentro del contexto rara vez hace falta comparar eventos; el tipo, las identidades implicadas y la fecha suelen bastar, como en un value object [IDDD cap. 8].
+* Fuera, con mensajería que puede reenviar, una identidad única permite deduplicar. Algunos buses la ponen en la cabecera; si no, la asigna el publicador [IDDD cap. 8]. Con el paquete es el `eventId` que pone `EventBase`: viaja en el JSON, `EventRegistry` lo conserva al reconstruir el evento (la fábrica pasa el JSON como metadatos) y el adaptador del broker lo usa como `messageId`.
+
+## Eventos con características de agregado
+
+A veces un evento no resulta de un comando sobre un agregado sino que un usuario lo origina directamente. Entonces puede modelarse como agregado inmutable en su propio repositorio, que no permite borrarlo, con identidad generada [IDDD cap. 8]. Ejemplo: una `IncidenciaDeEntregaReportada` por el transportista que se archiva y se consulta. Con el paquete sería un `AggregateRoot` cuyo repositorio implementa solo `AggregateFinder` y `AggregateSaver` (nunca `AggregateRemover`), con id `XId.generate()`.
+
+## Versionado
+
+* Los eventos publicados llevan versión. Diseñados con cuidado, muchos consumidores pueden leer cualquier versión como si fuera la 1 [IDDD cap. 13].
+* Cambios compatibles `[Fuera de los libros]`: añadir campos opcionales. Incompatibles: renombrar, quitar o cambiar el significado → nueva versión o nuevo evento, publicando ambas durante la transición.
+* Con el paquete, la versión de la forma interna es `static readonly eventVersion` (1 si no se declara; `toJSON()` la escribe). Los eventos guardados conservan la versión con la que se escribieron, así que la fábrica del `EventRegistry` lee las formas antiguas a partir de `json.eventVersion`:
+
+```ts
+import { EventBase } from '@archi-code/ddd/domain';
+import type { EventMetadata } from '@archi-code/ddd/domain';
+import { EventRegistry } from '@archi-code/ddd/infrastructure';
+
+export class OrderCancelled extends EventBase {
+  static readonly eventName = 'OrderCancelled';
+  static readonly eventVersion = 2;
+
+  constructor(
+    orderId: string,
+    readonly reason: string,
+    readonly refund: MoneyData,
+    metadata?: EventMetadata,
+  ) {
+    super(orderId, metadata);
+  }
+}
+
+export const cancellations = new EventRegistry<OrderCancelled>().register(
+  OrderCancelled,
+  (json) =>
+    json.eventVersion === 1
+      ? new OrderCancelled(
+          json.aggregateId,
+          json.reason as string,
+          { amount: json.refundCents as number, currency: 'EUR' },
+          json,
+        )
+      : new OrderCancelled(json.aggregateId, json.reason as string, json.refund as MoneyData, json),
+);
+```
+
+La versión del contrato publicado a otros contextos es otra cosa: la decide el adaptador del broker, que puede seguir emitiendo la v1 del contrato aunque el evento interno esté en la v2 (ver `ddd-skills/ddd-eventos-dominio/references/publicacion-ts.md`).