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

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.
+* `AggregateRoot` no lleva versión: la de concurrencia optimista de los repositorios de instantáneas la recuerda cada repositorio en un `WeakMap` y crece 1 por guardado, no por evento. Un agregado con Event Sourcing lleva su propia versión de stream (`streamVersion()`), se reconstruye con `fromHistory` a partir de los eventos que reconstruye `EventRegistry` y no usa `toPrimitives()`/`fromPrimitives()`.
+* El contrato del stream (`load`/`append`) lo declara el dominio y no es `AggregateFinder`/`AggregateSaver`; su adaptador es responsable de la persistencia: anexa los eventos de un `append` en una sola escritura atómica con la versión esperada y lanza `ConcurrencyException` si otro escribió antes. La aplicación no abre transacciones; el reintento ante `ConcurrencyException` va en el `handle` del caso de uso, cada intento vuelve a cargar y vuelve a anexar.
+* Una proyección es un `EventListener` con `@ListensTo(Event, { consumer })` que llama a un puerto de proyección (no a un caso de uso), idempotente por `eventId`; un `EventChannel` no guarda historial, así que reconstruirla exige un log de eventos propio (con Event Sourcing, el propio event store).
+* Una consulta de lectura es una interfaz en `application/` implementada en infraestructura directamente sobre la base de datos.
+
+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 versión de guardados de un repositorio de instantáneas como versión de stream o se guarda como instantánea con `toPrimitives()`.
+* Agregados que consultan read models para proteger invariantes (las invariantes viven en el agregado).
+* Datos personales en eventos sin estrategia de supresión.
+* CQRS con dos bases de datos para un CRUD de cinco pantallas.
+
+## Siguiente guía
+
+* Revisar un sistema existente → `ddd-skills/ddd-auditoria-refactorizacion/GUIA.md`.

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

@@ -0,0 +1,476 @@
+# Event Sourcing en TypeScript
+
+`@archi-code/ddd` no trae event store, repositorios con Event Sourcing ni snapshots: todo lo de esta referencia es código del proyecto escrito sobre las clases del paquete (`AggregateRoot`, `EventBase`, `EventRegistry`, `UseCase`, `EventBus`, `ConcurrencyException`). Úsalo solo en los agregados que la tabla de decisión de `ddd-skills/ddd-event-sourcing-cqrs/GUIA.md` justifique.
+
+## Eventos del stream
+
+Cada evento es una subclase de `EventBase` con `static readonly eventName` y, como campos `readonly` del constructor, el id del agregado y los datos primitivos que necesita, tomados de los value objects (el dinero como `{ amount, currency }`), nunca value objects: el evento no tiene métodos y se serializa tal cual (`{ ...event }`) [IDDD cap. 8].
+
+```ts
+import { EventBase } from '@archi-code/ddd/domain';
+import type { EventMetadata } from '@archi-code/ddd/domain';
+
+export class PaymentRequested extends EventBase {
+  static readonly eventName = 'PaymentRequested';
+
+  constructor(
+    readonly paymentId: string,
+    readonly orderId: string,
+    readonly amount: { amount: number; currency: string },
+    metadata?: EventMetadata,
+  ) {
+    super(metadata);
+  }
+}
+
+export class PaymentAuthorized extends EventBase {
+  static readonly eventName = 'PaymentAuthorized';
+
+  constructor(
+    readonly paymentId: string,
+    readonly authorizationCode: string,
+    readonly expiresAt: string,
+    metadata?: EventMetadata,
+  ) {
+    super(metadata);
+  }
+}
+
+export class PaymentRejected extends EventBase {
+  static readonly eventName = 'PaymentRejected';
+
+  constructor(
+    readonly paymentId: string,
+    readonly reason: string,
+    metadata?: EventMetadata,
+  ) {
+    super(metadata);
+  }
+}
+
+export class PaymentCaptured extends EventBase {
+  static readonly eventName = 'PaymentCaptured';
+
+  constructor(
+    readonly paymentId: string,
+    metadata?: EventMetadata,
+  ) {
+    super(metadata);
+  }
+}
+
+export type PaymentEvent = PaymentRequested | PaymentAuthorized | PaymentRejected | PaymentCaptured;
+```
+
+`EventBase` pone `eventName`, `eventId` y `occurredOn` (texto ISO en UTC, del `clock` que recibe el método del agregado); la identidad del pago es un campo más del evento (`paymentId`), declarado por cada clase. `{ ...event }` da `eventName`, `eventId`, `occurredOn` y los campos, todos datos primitivos (regla del paquete, no comprobada en ejecución): esa es la fila del stream.
+
+## Agregado con decidir y aplicar
+
+`[Fuera de los libros como código; estructura basada en IDDD apéndice A]`
+
+```ts
+import {
+  AggregateRoot,
+  Composite,
+  DateType,
+  EnumType,
+  IdType,
+  NumberType,
+  Required,
+  StringType,
+} from '@archi-code/ddd/domain';
+import { DomainException } from '@archi-code/ddd/domain';
+import { Validations } from '@archi-code/validation';
+
+export class PaymentId extends IdType<'PaymentId'> {}
+export class OrderId extends IdType<'OrderId'> {}
+export class AuthorizationCode extends Required(StringType) {}
+export class RejectionReason extends Required(StringType) {}
+export class ExpiresAt extends Required(DateType) {}
+
+@Validations([{ validator: 'isInt' }])
+export class Cents extends Required(NumberType) {}
+@Validations([{ validator: 'isISO4217' }])
+export class Currency extends Required(StringType) {}
+export class Money extends Composite({ amount: Cents, currency: Currency }) {}
+
+export enum Status {
+  Requested = 'requested',
+  Authorized = 'authorized',
+  Rejected = 'rejected',
+  Captured = 'captured',
+}
+
+class StatusType extends EnumType<Status> {
+  protected getEnum(): typeof Status {
+    return Status;
+  }
+}
+
+export class PaymentStatus extends Required(StatusType) {
+  is(status: Status): boolean {
+    return this.value === status;
+  }
+}
+
+export class PaymentNotAuthorized extends DomainException {
+  constructor(paymentId: string) {
+    super(`Payment ${paymentId} is not authorized`, ['PAY002']);
+  }
+}
+
+export class AuthorizationExpired extends DomainException {
+  constructor(paymentId: string) {
+    super(`The authorization of payment ${paymentId} has expired`, ['PAY003']);
+  }
+}
+
+export class PaymentAlreadyDecided extends DomainException {
+  constructor(paymentId: string) {
+    super(`Payment ${paymentId} was already authorized or rejected`, ['PAY004']);
+  }
+}
+
+export class Payment extends AggregateRoot<PaymentId, PaymentEvent> {
+  private status = new PaymentStatus(Status.Requested);
+  private amount: Money | null = null;
+  private expiresAt: ExpiresAt | null = null;
+  private replayed = 0;
+
+  private constructor(id: PaymentId) {
+    super(id);
+  }
+
+  static request(id: PaymentId, orderId: OrderId, amount: Money, clock: { now(): Date }): Payment {
+    const payment = new Payment(id);
+    payment.emit(
+      new PaymentRequested(
+        id.value,
+        orderId.value,
+        { amount: amount.amount.value, currency: amount.currency.value },
+        { clock },
+      ),
+    );
+    return payment;
+  }
+
+  static fromHistory(id: PaymentId, history: readonly PaymentEvent[]): Payment {
+    const payment = new Payment(id);
+    history.forEach((event) => payment.apply(event));
+    payment.replayed = history.length;
+    return payment;
+  }
+
+  streamVersion(): number {
+    return this.replayed;
+  }
+
+  authorize(code: AuthorizationCode, expiresAt: ExpiresAt, clock: { now(): Date }): void {
+    if (!this.status.is(Status.Requested)) {
+      throw new PaymentAlreadyDecided(this.id.value);
+    }
+    this.emit(
+      new PaymentAuthorized(this.id.value, code.value, expiresAt.value.toISOString(), { clock }),
+    );
+  }
+
+  reject(reason: RejectionReason, clock: { now(): Date }): void {
+    if (!this.status.is(Status.Requested)) {
+      throw new PaymentAlreadyDecided(this.id.value);
+    }
+    this.emit(new PaymentRejected(this.id.value, reason.value, { clock }));
+  }
+
+  capture(clock: { now(): Date }): void {
+    if (!this.status.is(Status.Authorized) || this.expiresAt === null) {
+      throw new PaymentNotAuthorized(this.id.value);
+    }
+    if (this.expiresAt.value < clock.now()) {
+      throw new AuthorizationExpired(this.id.value);
+    }
+    this.emit(new PaymentCaptured(this.id.value, { clock }));
+  }
+
+  private emit(event: PaymentEvent): void {
+    this.apply(event);
+    this.record(event);
+  }
+
+  private apply(event: PaymentEvent): void {
+    if (event instanceof PaymentRequested) {
+      this.amount = Money.fromPrimitives(event.amount);
+    } else if (event instanceof PaymentAuthorized) {
+      this.status = new PaymentStatus(Status.Authorized);
+      this.expiresAt = new ExpiresAt(new Date(event.expiresAt));
+    } else if (event instanceof PaymentRejected) {
+      this.status = new PaymentStatus(Status.Rejected);
+    } else {
+      this.status = new PaymentStatus(Status.Captured);
+    }
+  }
+}
+```
+
+Reglas:
+* `apply` no valida ni lanza: los eventos son hechos ya ocurridos [Destilado cap. 6].
+* Las reglas viven en los métodos de comando (`authorize`, `capture`), antes de emitir, y lanzan subclases de `DomainException` con su código.
+* El estado solo cambia vía eventos: `emit` aplica y después llama a `record` (protegido en `AggregateRoot`, congela el evento), así que `pullDomainEvents()` devuelve exactamente los cambios pendientes, en orden.
+* `fromHistory` aplica sin `record`: reconstituir no genera eventos nuevos.
+* El reloj se recibe como `{ now(): Date }` y se pasa a cada evento (`{ clock }`), para que reconstruir no dependa de la hora actual; en pruebas, `FixedClock`.
+* IDDD propone separar estado y comportamiento en dos clases que solo colaboran a través de `apply` [IDDD apéndice A]; aquí el estado son campos privados de value objects que solo `apply` escribe. Si el agregado crece, extrae ese estado a una clase propia con su `apply`.
+* `[Fuera de los libros: convención de @archi-code/ddd]` `AggregateRoot` no tiene versión, y la que recuerda un repositorio de instantáneas en su `WeakMap` cuenta guardados, no eventos (crece 1 por `save`), así que este agregado lleva su propia versión de stream (`streamVersion()`, los eventos que se aplicaron al cargar) y no se guarda como instantánea: no necesita `toPrimitives()`/`fromPrimitives()` ni getters para sus campos, porque lo que se persiste son los eventos.
+
+## Event store
+
+Un stream por agregado, identificado por la identidad de la raíz; almacenamiento solo de anexión con cualquier tecnología que ofrezca consistencia fuerte [IDDD apéndice A; Destilado cap. 6].
+
+```sql
+CREATE TABLE event_streams (
+  stream_id    TEXT      NOT NULL,
+  version      INT       NOT NULL,
+  body         JSONB     NOT NULL,
+  global_seq   BIGSERIAL UNIQUE,
+  PRIMARY KEY (stream_id, version)
+);
+```
+
+La clave primaria `(stream_id, version)` impide dos escrituras con la misma versión; `global_seq` da el orden global que necesitan la publicación y la reconstrucción de proyecciones. `body` es la copia plana del evento (`{ ...event }`).
+
+El dominio declara el contrato del stream (solo tipos, como los contratos de repositorio del paquete) `[Fuera de los libros: convención de @archi-code/ddd]`: no es `AggregateFinder`/`AggregateSaver`, porque guardar necesita los cambios que el caso de uso ya sacó con `pullDomainEvents()` para publicarlos.
+
+```ts
+export interface PaymentStream {
+  load(id: PaymentId): Promise<Payment | null>;
+  append(payment: Payment, changes: readonly PaymentEvent[]): Promise<void>;
+}
+```
+
+La infraestructura lo implementa: reconstruye cada fila con `EventRegistry.fromJSON` (que conserva `eventId` y `occurredOn` y congela el evento), anexa todos los eventos de un `append` en una sola transacción que abre y cierra con su propia conexión, y traduce la violación de la clave primaria a `ConcurrencyException`. Como cualquier repositorio del paquete, el stream es responsable de todo lo de persistencia: la escritura atómica del stream con su versión esperada, la conexión y los errores del driver `[Fuera de los libros: convención de @archi-code/ddd]`.
+
+```ts
+import type { SerializedEvent } from '@archi-code/ddd/domain';
+import { EventRegistry, InternalErrorException } from '@archi-code/ddd/infrastructure';
+import { ConcurrencyException } from '@archi-code/ddd/application';
+
+export const paymentEvents = new EventRegistry<PaymentEvent>()
+  .register(
+    PaymentRequested,
+    (json) =>
+      new PaymentRequested(
+        json.paymentId as string,
+        json.orderId as string,
+        json.amount as { amount: number; currency: string },
+        json,
+      ),
+  )
+  .register(
+    PaymentAuthorized,
+    (json) =>
+      new PaymentAuthorized(
+        json.paymentId as string,
+        json.authorizationCode as string,
+        json.expiresAt as string,
+        json,
+      ),
+  )
+  .register(
+    PaymentRejected,
+    (json) => new PaymentRejected(json.paymentId as string, json.reason as string, json),
+  )
+  .register(PaymentCaptured, (json) => new PaymentCaptured(json.paymentId as string, json));
+
+interface SqlClient {
+  query<Row>(text: string, values: readonly unknown[]): Promise<{ rows: Row[] }>;
+}
+
+interface PoolClient extends SqlClient {
+  release(): void;
+}
+
+interface Pool extends SqlClient {
+  connect(): Promise<PoolClient>;
+}
+
+export class PgPaymentStream implements PaymentStream {
+  constructor(
+    private readonly pool: Pool,
+    private readonly registry: EventRegistry<PaymentEvent>,
+  ) {}
+
+  async load(id: PaymentId): Promise<Payment | null> {
+    const { rows } = await this.pool.query<{ body: SerializedEvent }>(
+      'SELECT body FROM event_streams WHERE stream_id = $1 ORDER BY version',
+      [id.value],
+    );
+    if (rows.length === 0) {
+      return null;
+    }
+    return Payment.fromHistory(
+      id,
+      rows.map((row) => this.registry.fromJSON(row.body)),
+    );
+  }
+
+  async append(payment: Payment, changes: readonly PaymentEvent[]): Promise<void> {
+    const expected = payment.streamVersion();
+    const client = await this.pool.connect();
+    try {
+      await client.query('BEGIN', []);
+      for (const [index, event] of changes.entries()) {
+        await client.query(
+          'INSERT INTO event_streams (stream_id, version, body) VALUES ($1, $2, $3)',
+          [payment.id.value, expected + index + 1, JSON.stringify(event)],
+        );
+      }
+      await client.query('COMMIT', []);
+    } catch (error) {
+      await client.query('ROLLBACK', []);
+      if ((error as { code?: string }).code === '23505') {
+        throw new ConcurrencyException('Payment', payment.id.value, expected, { cause: error });
+      }
+      throw new InternalErrorException('appending payment events', { cause: error });
+    } finally {
+      client.release();
+    }
+  }
+}
+```
+
+`Pool` y `SqlClient` son la parte de `pg` que usa el adaptador, declarada de forma estructural. La transacción empieza y termina dentro de `append`: o entran todos los eventos del cambio o ninguno, y la aplicación no ve ninguna transacción. `'23505'` es el código de violación de unicidad de PostgreSQL; con otro motor, comprueba el suyo.
+
+## Caso de uso y reintento
+
+El caso de uso carga, decide, anexa y publica; no abre transacciones ni recibe un puerto para ello. Ante un conflicto puede reintentar recargando y reejecutando el comando contra el estado nuevo, como propone IDDD [IDDD apéndice A]; si el comando ya no es válido, el error de negocio sale normalmente. `[Fuera de los libros: convención de @archi-code/ddd]` El stream solo carga y anexa; el bucle de reintento va en el `handle` del caso de uso, cada intento vuelve a cargar y vuelve a anexar, unos pocos intentos y después relanza la `ConcurrencyException` (`ExceptionKind.Conflict`, 409 en HTTP). Reintenta solo comandos seguros de repetir; un caso de uso que lanza un listener no lleva este bucle: el reintento lo hace la reentrega del canal.
+
+```ts
+import { AggregateNotFoundException, ConcurrencyException, UseCase } from '@archi-code/ddd/application';
+import type { Clock, EventBus } from '@archi-code/ddd/application';
+
+export class CapturePayment extends UseCase<{ paymentId: string }, PaymentId, void> {
+  constructor(
+    private readonly payments: PaymentStream,
+    private readonly events: EventBus<PaymentEvent>,
+    private readonly clock: Clock,
+  ) {
+    super();
+  }
+
+  protected toCommand(input: { paymentId: string }): PaymentId {
+    return new PaymentId(input.paymentId);
+  }
+
+  protected async handle(paymentId: PaymentId): Promise<void> {
+    for (let attempt = 1; ; attempt += 1) {
+      try {
+        const payment = await this.payments.load(paymentId);
+        if (payment === null) {
+          throw new AggregateNotFoundException('Payment', paymentId.value);
+        }
+        payment.capture(this.clock);
+        const changes = payment.pullDomainEvents();
+        await this.payments.append(payment, changes);
+        await this.events.publish(changes);
+        return;
+      } catch (error) {
+        if (!(error instanceof ConcurrencyException) || attempt === 3) {
+          throw error;
+        }
+      }
+    }
+  }
+}
+```
+
+Publicar: IDDD publica con un proceso en segundo plano que lee lo anexado [IDDD apéndice A]. Con el paquete, el caso de uso solo ve el puerto `EventBus`; el `DomainEventBus` de la composición envía a un `EventChannel`. Si `publish` falla después de `append`, los eventos ya están en el stream pero no se entregan. Para no perder ninguno, el propio `event_streams` hace de bandeja, porque `append` ya los guardó en su escritura atómica: un reenviador lee por `global_seq` y entrega los `SerializedEvent` a los manejadores que registró `receive`, y el canal que recibe el bus del caso de uso no escribe nada en su `send` (los eventos ya están guardados) y delega `receive` en el canal del reenviador. Es persistencia y entrega, así que vive en la infraestructura; los casos de uso no cambian `[Fuera de los libros: convención de @archi-code/ddd]`.
+
+## Pruebas en memoria
+
+Una implementación en memoria del stream sirve como doble de pruebas y como referencia del contrato; anexa todos los cambios de una vez o ninguno, como `PgPaymentStream`:
+
+```ts
+import { DomainEventBus, FixedClock, InMemoryEventChannel } from '@archi-code/ddd/infrastructure';
+
+export class InMemoryPaymentStream implements PaymentStream {
+  private readonly streams = new Map<string, readonly SerializedEvent[]>();
+
+  constructor(private readonly registry: EventRegistry<PaymentEvent>) {}
+
+  async load(id: PaymentId): Promise<Payment | null> {
+    const stream = this.streams.get(id.value);
+    if (stream === undefined) {
+      return null;
+    }
+    return Payment.fromHistory(
+      id,
+      stream.map((json) => this.registry.fromJSON(json)),
+    );
+  }
+
+  async append(payment: Payment, changes: readonly PaymentEvent[]): Promise<void> {
+    const stream = this.streams.get(payment.id.value) ?? [];
+    if (stream.length !== payment.streamVersion()) {
+      throw new ConcurrencyException('Payment', payment.id.value, payment.streamVersion());
+    }
+    this.streams.set(payment.id.value, [...stream, ...changes.map((event) => ({ ...event }))]);
+  }
+}
+
+const clock = new FixedClock('2026-10-19T09:30:00Z');
+const payments = new InMemoryPaymentStream(paymentEvents);
+const channel = new InMemoryEventChannel();
+const bus = new DomainEventBus<PaymentEvent>(channel, paymentEvents);
+
+const paymentId = PaymentId.generate();
+const payment = Payment.request(
+  paymentId,
+  OrderId.generate(),
+  Money.fromPrimitives({ amount: 4990, currency: 'EUR' }),
+  clock,
+);
+payment.authorize(
+  new AuthorizationCode('AUTH-7731'),
+  new ExpiresAt(new Date('2026-10-26T09:30:00Z')),
+  clock,
+);
+await payments.append(payment, payment.pullDomainEvents());
+
+await new CapturePayment(payments, bus, clock).execute({
+  paymentId: paymentId.value,
+});
+channel.sent.map((event) => event.eventName); // ['PaymentCaptured']
+(await payments.load(paymentId))?.streamVersion(); // 3
+```
+
+Ejecuta las mismas pruebas de contrato (carga lo anexado, rechaza una versión esperada antigua con `ConcurrencyException`) contra `InMemoryPaymentStream` y `PgPaymentStream`, como el contrato de repositorio de `ddd-skills/ddd-repositorios-persistencia/GUIA.md`.
+
+## Snapshots
+
+Para streams largos, guarda periódicamente el estado serializado con su versión y carga desde ahí más los eventos posteriores [IDDD apéndice A; Destilado cap. 6]. Los snapshots son una optimización desechable: si cambia la forma del estado, se borran y se regeneran. El paquete no los trae: son una tabla más de tu infraestructura (`stream_id`, `version`, `state`) y una fábrica del agregado que parte del estado y aplica solo los eventos con versión mayor, dejando `streamVersion()` en la versión del último evento aplicado.
+
+## Versionado de eventos
+
+`[Fuera de los libros]` Los eventos del stream no se reescriben. Para cambiar su forma, convierte las versiones antiguas al leer ("upcasting") en el deserializador, o añade un tipo de evento nuevo. El apéndice de IDDD trata los serializadores (por ejemplo Protocol Buffers) como apoyo para esta evolución [IDDD apéndice A].
+
+Con el paquete, los eventos no llevan número de versión: la fábrica del `EventRegistry` recibe cada fila tal como se guardó, así que el upcasting va ahí y reconoce la forma antigua por sus campos; un cambio que no se pueda leer así se publica como un evento nuevo con otro `eventName` (`PaymentRequestedV2`). Por ejemplo, si una primera forma de `PaymentRequested` guardaba `amountCents` en euros:
+
+```ts
+export class PaymentRequested extends EventBase {
+  static readonly eventName = 'PaymentRequested';
+  // constructor as above
+}
+
+new EventRegistry<PaymentEvent>().register(
+  PaymentRequested,
+  (json) =>
+    new PaymentRequested(
+      json.paymentId as string,
+      json.orderId as string,
+      typeof json.amountCents === 'number'
+        ? { amount: json.amountCents, currency: 'EUR' }
+        : (json.amount as { amount: number; currency: string }),
+      json,
+    ),
+);
+```
+
+Pasa siempre `json` como último argumento: el evento reconstruido conserva su `eventId` y su `occurredOn`, y `fromJSON` lanza `InternalErrorException` si la fábrica los pierde.