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

package/ddd-skills/ddd-eventos-dominio/references/publicacion-ts.md

@@ -32,11 +32,9 @@ Qué pone `@archi-code/ddd` y qué escribe el proyecto:
 El caso de uso guarda y después publica lo que devuelve `pullDomainEvents()`: si `save` falla no se publica nada, y los eventos nunca salen dos veces. No hay puerto de transacciones: el caso de uso recibe solo los roles de repositorio que usa, el `EventBus` y el `Clock`, y el repositorio garantiza que `save` es una escritura atómica `[Fuera de los libros: convención de @archi-code/ddd]`.
 
 ```ts
-import { ValueObjects } from '@archi-code/ddd/domain';
 import type { AggregateFinder, AggregateSaver } from '@archi-code/ddd/domain';
-import { UseCase } from '@archi-code/ddd/application';
+import { AggregateNotFoundException, UseCase, ValueObjectBuilder } from '@archi-code/ddd/application';
 import type { Clock, EventBus } from '@archi-code/ddd/application';
-import { AggregateNotFoundException } from '@archi-code/ddd/exceptions';
 
 interface AddOrderLineInput {
   orderId: string;
@@ -60,7 +58,7 @@ export class AddOrderLine extends UseCase<AddOrderLineInput, AddOrderLineCommand
   }
 
   protected toCommand(input: AddOrderLineInput): AddOrderLineCommand {
-    return ValueObjects.build({
+    return ValueObjectBuilder.build({
       orderId: () => new OrderId(input.orderId),
       line: () =>
         OrderLine.fromPrimitives({
@@ -128,7 +126,7 @@ describe('Adding a line to an order', () => {
     expect(channel.sent).toMatchObject([
       {
         eventName: 'OrderLineAdded',
-        aggregateId: orderId,
+        orderId,
         sku: 'GLOVES-02',
         quantity: 2,
         unitPrice: { amount: 1250, currency: 'EUR' },
@@ -156,7 +154,6 @@ CREATE TABLE stored_events (
   event_id      UUID        NOT NULL UNIQUE,
   aggregate_id  TEXT        NOT NULL,
   event_name    TEXT        NOT NULL,
-  event_version INT         NOT NULL,
   occurred_on   TIMESTAMPTZ NOT NULL,
   body          JSONB       NOT NULL,
   published_at  TIMESTAMPTZ NULL
@@ -164,13 +161,14 @@ CREATE TABLE stored_events (
 CREATE INDEX stored_events_unpublished ON stored_events (sequence) WHERE published_at IS NULL;
 ```
 
-`sequence` conserva el orden causal dentro del contexto; `body` es el `SerializedEvent` que produjo `toJSON()`.
+`sequence` conserva el orden causal dentro del contexto; `body` es el `SerializedEvent`, la copia plana del evento (`{ ...event }`).
 
 ### El repositorio
 
 ```ts
 import type { AggregateFinder, AggregateSaver, PrimitiveTypes } from '@archi-code/ddd/domain';
-import { ConcurrencyException, InternalErrorException } from '@archi-code/ddd/exceptions';
+import { ConcurrencyException } from '@archi-code/ddd/application';
+import { InternalErrorException } from '@archi-code/ddd/infrastructure';
 
 interface QueryResult<Row> {
   rows: Row[];
@@ -195,6 +193,8 @@ interface OrderRow {
 }
 
 export class PostgresOrderRepository implements AggregateFinder<Order>, AggregateSaver<Order> {
+  private readonly versions = new WeakMap<Order, number>();
+
   constructor(private readonly pool: Pool) {}
 
   async findById(id: OrderId): Promise<Order | null> {
@@ -203,41 +203,46 @@ export class PostgresOrderRepository implements AggregateFinder<Order>, Aggregat
         'SELECT version, data FROM orders WHERE id = $1',
         [id.value],
       );
-      return rows[0] ? Order.fromPrimitives(rows[0].data).restoreVersion(rows[0].version) : null;
+      if (rows[0] === undefined) {
+        return null;
+      }
+      const order = Order.fromPrimitives(rows[0].data);
+      this.versions.set(order, rows[0].version);
+      return order;
     } catch (error) {
       throw new InternalErrorException('loading order', { cause: error });
     }
   }
 
   async save(order: Order): Promise<void> {
+    const version = this.versions.get(order) ?? 0;
     const primitives = order.toPrimitives();
-    const events = order.pullDomainEvents().map((event) => event.toJSON());
+    const events = order.pullDomainEvents().map((event) => ({ ...event }));
     const client = await this.pool.connect();
     try {
       await client.query('BEGIN');
       const { rowCount } =
-        order.version === 0
+        version === 0
           ? await client.query(
               'INSERT INTO orders (id, version, customer_id, status, data) VALUES ($1, 1, $2, $3, $4) ON CONFLICT (id) DO NOTHING',
               [primitives.id, primitives.customerId, primitives.status, primitives],
             )
           : await client.query(
               'UPDATE orders SET version = version + 1, status = $3, data = $4 WHERE id = $1 AND version = $2',
-              [primitives.id, order.version, primitives.status, primitives],
+              [primitives.id, version, primitives.status, primitives],
             );
       if (rowCount === 0) {
-        throw new ConcurrencyException('Order', order.id.value, order.version);
+        throw new ConcurrencyException('Order', order.id.value, version);
       }
       for (const event of events) {
         await client.query(
           `INSERT INTO stored_events
-             (event_id, aggregate_id, event_name, event_version, occurred_on, body)
-           VALUES ($1, $2, $3, $4, $5, $6)`,
+             (event_id, aggregate_id, event_name, occurred_on, body)
+           VALUES ($1, $2, $3, $4, $5)`,
           [
             event.eventId,
-            event.aggregateId,
+            primitives.id,
             event.eventName,
-            event.eventVersion,
             event.occurredOn,
             JSON.stringify(event),
           ],
@@ -253,19 +258,19 @@ export class PostgresOrderRepository implements AggregateFinder<Order>, Aggregat
     } finally {
       client.release();
     }
-    order.markPersisted();
+    this.versions.set(order, version + 1);
   }
 }
 ```
 
-La transacción empieza y termina dentro de `save`: el pedido y sus eventos se confirman o se deshacen juntos, que es lo que pide "un agregado por transacción" [IDDD cap. 10]. `markPersisted()` se llama solo tras el `COMMIT`. Si la escritura falla, el caso de uso termina con el error y el agregado se descarta con sus eventos. El caso de uso no cambia: su `publish` recibe una lista vacía, porque los eventos de este pedido ya están en el outbox. El esquema de `orders` y el repositorio sin outbox están en `ddd-skills/ddd-repositorios-persistencia/references/implementacion-ts.md`.
+La transacción empieza y termina dentro de `save`: el pedido y sus eventos se confirman o se deshacen juntos, que es lo que pide "un agregado por transacción" [IDDD cap. 10]. El repositorio actualiza la versión que recuerda para el pedido (`this.versions.set(order, version + 1)`) solo tras el `COMMIT`. Si la escritura falla, el caso de uso termina con el error y el agregado se descarta con sus eventos. El caso de uso no cambia: su `publish` recibe una lista vacía, porque los eventos de este pedido ya están en el outbox. El esquema de `orders` y el repositorio sin outbox están en `ddd-skills/ddd-repositorios-persistencia/references/implementacion-ts.md`.
 
 ## Reenviador
 
 ```ts
 import type { EventChannel } from '@archi-code/ddd/infrastructure';
 import type { SerializedEvent } from '@archi-code/ddd/domain';
-import { InternalErrorException } from '@archi-code/ddd/exceptions';
+import { InternalErrorException } from '@archi-code/ddd/infrastructure';
 
 export class OutboxForwarder {
   private static readonly lockKey = 8_201_001;
@@ -338,7 +343,7 @@ Un lote que falla se queda en el outbox y lo reintenta la pasada siguiente; el `
 
 ## Lenguaje publicado en el adaptador del broker
 
-Los otros contextos no reciben las clases ni el `toJSON()` del dominio: reciben un contrato versionado [IDDD cap. 13]. El paquete no trae esa traducción; se hace en el adaptador que habla con el broker, a partir del `SerializedEvent`, con `messageId` = `eventId`. Un evento interno no produce ningún mensaje, y durante una transición un evento puede producir un mensaje por versión del contrato:
+Los otros contextos no reciben los eventos del dominio tal cual: reciben un contrato versionado [IDDD cap. 13]. El paquete no trae esa traducción; se hace en el adaptador que habla con el broker, a partir del `SerializedEvent`, con `messageId` = `eventId`. Un evento interno no produce ningún mensaje, y durante una transición un evento puede producir un mensaje por versión del contrato. El `SerializedEvent` no lleva campo de versión: cada versión incompatible del contrato se publica con su propio `eventName` (`sales.order.OrderPlacedV2`) `[Fuera de los libros: convención de @archi-code/ddd]`:
 
 ```ts
 import type {
@@ -355,9 +360,7 @@ interface Broker {
 export class SalesContracts {
   static toPublished(event: SerializedEvent): SerializedEvent[] {
     const envelope = {
-      eventVersion: 1,
       eventId: event.eventId,
-      aggregateId: event.aggregateId,
       occurredOn: event.occurredOn,
     };
     switch (event.eventName) {
@@ -366,7 +369,7 @@ export class SalesContracts {
           {
             ...envelope,
             eventName: 'sales.order.OrderPlaced',
-            orderId: event.aggregateId,
+            orderId: event.orderId,
             customerId: event.customerId,
             lines: (event.lines as OrderLineData[]).map((line) => ({
               sku: line.sku,
@@ -381,7 +384,7 @@ export class SalesContracts {
           {
             ...envelope,
             eventName: 'sales.order.OrderConfirmed',
-            orderId: event.aggregateId,
+            orderId: event.orderId,
             total: SalesContracts.money(event.total as MoneyData),
           },
         ];
@@ -418,15 +421,15 @@ export class ContractPublishingChannel implements EventChannel {
 }
 ```
 
-`SalesContracts` decide qué eventos salen del contexto y con qué forma, campo a campo (`MoneyData` y `OrderLineData` son los de `ddd-skills/ddd-eventos-dominio/references/ejemplo-ecommerce.md`), para que un campo nuevo del evento interno no se filtre al contrato (ver "Eventos internos y eventos publicados" en `ddd-skills/ddd-eventos-dominio/GUIA.md`); el contrato no cambia cuando cambia el evento interno, solo cuando se publica una versión nueva. El mensaje es un `SerializedEvent` plano con el nombre y la versión del contrato (`sales.order.OrderPlaced`, v1), que el consumidor lee con su propia clase `EventBase` (`ddd-skills/ddd-context-mapping/references/anticorrupcion-ts.md`). `Broker` es la parte del driver que el adaptador usa, declarada de forma estructural.
+`SalesContracts` decide qué eventos salen del contexto y con qué forma, campo a campo (`MoneyData` y `OrderLineData` son los de `ddd-skills/ddd-eventos-dominio/references/ejemplo-ecommerce.md`), para que un campo nuevo del evento interno no se filtre al contrato (ver "Eventos internos y eventos publicados" en `ddd-skills/ddd-eventos-dominio/GUIA.md`); el contrato no cambia cuando cambia el evento interno, solo cuando se publica una versión nueva. El mensaje es un `SerializedEvent` plano con el nombre del contrato (`sales.order.OrderPlaced`, la v1; una v2 incompatible llevaría otro nombre), que el consumidor lee con su propia clase `EventBase` (`ddd-skills/ddd-context-mapping/references/anticorrupcion-ts.md`). `Broker` es la parte del driver que el adaptador usa, declarada de forma estructural.
 
 ## Consumidor idempotente
 
 La entrega es al menos una vez, así que el consumidor se salta un `eventId` que ya procesó, y lo anota **en la misma transacción** que su cambio [IDDD cap. 8]. El paquete no trae inbox. `[Fuera de los libros: convención de @archi-code/ddd]` Anotar el `eventId` y escribir el efecto es persistencia, así que lo hace el adaptador del puerto que escribe, en una sola escritura atómica; el listener solo pasa el `eventId` al caso de uso (como en `ddd-skills/ddd-eventos-dominio/GUIA.md`, paso 3), y el caso de uso se lo pasa al puerto:
 
 ```ts
-import { IdType, ValueObjects } from '@archi-code/ddd/domain';
-import { UseCase } from '@archi-code/ddd/application';
+import { IdType } from '@archi-code/ddd/domain';
+import { UseCase, ValueObjectBuilder } from '@archi-code/ddd/application';
 
 export class EventId extends IdType<'EventId'> {}
 
@@ -454,7 +457,7 @@ export class PrepareShipment extends UseCase<PrepareShipmentInput, PrepareShipme
   }
 
   protected toCommand(input: PrepareShipmentInput): PrepareShipmentCommand {
-    return ValueObjects.build({
+    return ValueObjectBuilder.build({
       eventId: () => new EventId(input.eventId),
       orderId: () => new OrderId(input.orderId),
       sku: () => new Sku(input.sku),
@@ -469,7 +472,7 @@ export class PrepareShipment extends UseCase<PrepareShipmentInput, PrepareShipme
 ```
 
 ```ts
-import { InternalErrorException } from '@archi-code/ddd/exceptions';
+import { InternalErrorException } from '@archi-code/ddd/infrastructure';
 
 export class PostgresWarehouse implements Warehouse {
   private static readonly consumer = 'prepare-shipment';
@@ -514,7 +517,7 @@ La anotación y el efecto van en la misma transacción, abierta y cerrada dentro
 ## Orden y causalidad
 
 * El `sequence` de la tabla conserva el orden causal dentro del contexto [Destilado cap. 6], y el reenviador entrega en ese orden. Un mismo consumidor recibe los eventos de un `send` en su orden.
-* El bus puede desordenar. Opciones `[Fuera de los libros]`: particionar por `aggregateId` (Kafka, sesiones de Service Bus, un consumidor activo por cola en RabbitMQ) para mantener el orden por agregado; o que el consumidor compare `occurredOn` o una versión y aparque los eventos que llegan antes que su causa [Destilado cap. 6 describe la responsabilidad del consumidor].
+* El bus puede desordenar. Opciones `[Fuera de los libros]`: particionar por la identidad del agregado (`orderId`; Kafka, sesiones de Service Bus, un consumidor activo por cola en RabbitMQ) para mantener el orden por agregado; o que el consumidor compare `occurredOn` o una versión y aparque los eventos que llegan antes que su causa [Destilado cap. 6 describe la responsabilidad del consumidor].
 * Si un evento posterior hace irrelevante uno anterior, el consumidor puede ignorar el anterior [Destilado cap. 6].
 
 ## Despacho interno

package/ddd-skills/ddd-repositorios-persistencia/GUIA.md

@@ -11,12 +11,12 @@
 * No hay un `Repository` completo: los contratos son tres roles en `@archi-code/ddd/domain` (`AggregateFinder.findById`, `AggregateSaver.save`, `AggregateRemover.remove`) y un caso de uso pide solo los que usa, combinados con `&`.
 * Los repositorios solo obtienen y persisten: sin `nextId()` ni consultas de negocio como `pendingOlderThan`, que pasan a ser consultas de lectura en `application/`.
 * Cada repositorio es único para su agregado (`MongoOrderRepository implements AggregateFinder<Order>, AggregateSaver<Order>, AggregateRemover<Order>`) y sabe qué agregado reconstruye. Su constructor recibe solo las dependencias de su tecnología (una `collection` de MongoDB, un `pool` de Postgres), nunca la clase del agregado ni un mapper; los agregados solo entran y salen por sus métodos (`save(order)`, `remove(order)`, `findById(id)` → `Order | null`).
-* La conversión es del agregado, su único dueño: `toPrimitives()` y `static fromPrimitives()` (instantánea o Memento), sin un mapper, un servicio de dominio ni una comprobación de forma en medio. El repositorio no lee campos del agregado: guarda `order.toPrimitives()` con `order.version + 1` al lado y carga con `Order.fromPrimitives(row).restoreVersion(row.version)`. Nada comprueba en ejecución que la conversión esté completa: lo garantiza el test del agregado con el viaje de ida y vuelta (`Order.fromPrimitives(order.toPrimitives()).toPrimitives()` igual a `order.toPrimitives()`), y quien añade un campo lo añade a los dos métodos.
-* La versión de concurrencia optimista vive en la base `AggregateRoot` (`version`, `restoreVersion()`, `markPersisted()`): el agregado no la declara ni la mapea, y solo los repositorios la tocan. Un conflicto es `ConcurrencyException('Order', id, version, { cause })` (HTTP 409), con el nombre del agregado como texto literal y no como nombre de clase, que los minificadores cambian.
+* La conversión es del agregado, su único dueño: `toPrimitives()` y `static fromPrimitives()` (instantánea o Memento), sin un mapper, un servicio de dominio ni una comprobación de forma en medio. El repositorio no lee campos del agregado: guarda `order.toPrimitives()` con la versión siguiente al lado y carga con `Order.fromPrimitives(row.primitives)`. Nada comprueba en ejecución que la conversión esté completa: lo garantiza el test del agregado con el viaje de ida y vuelta (`Order.fromPrimitives(order.toPrimitives()).toPrimitives()` igual a `order.toPrimitives()`), y quien añade un campo lo añade a los dos métodos.
+* La versión de concurrencia optimista es solo del repositorio: el agregado no la declara ni la mapea y el caso de uso nunca la ve. El repositorio recuerda la versión de cada agregado que cargó o guardó en un `WeakMap<Order, number>` privado (`versions`): al cargar `this.versions.set(order, row.version)`; al guardar `const version = this.versions.get(order) ?? 0` (`0` = nuevo), escribe solo donde la versión guardada es `version` (nuevo: inserta, y un id ya existente es conflicto), guarda `version + 1` junto a los primitivos y hace `this.versions.set(order, version + 1)` solo tras escribir con éxito (en SQL, tras el `COMMIT`) `[Fuera de los libros: convención de @archi-code/ddd]`. Un conflicto es `ConcurrencyException('Order', id, version, { cause })` (HTTP 409), con el nombre del agregado como texto literal y no como nombre de clase, que los minificadores cambian.
 * `remove(aggregate)` recibe el agregado cargado y comprueba su versión como `save`: borrar un agregado que otro cambió después de cargarlo es `ConcurrencyException`.
 * El repositorio no publica eventos: lo hace el caso de uso con `events.publish(order.pullDomainEvents())` después de `save`.
 * La transacción es del repositorio: no hay puerto de transacciones en `@archi-code/ddd/application` y la aplicación nunca abre, une ni cierra una. Cada `save`/`remove` es una escritura atómica, y si el agregado ocupa varias tablas el repositorio abre y confirma la transacción de la base de datos dentro de ese método, con su propia conexión o sesión.
-* El paquete no da un repositorio en memoria: cada proyecto escribe el suyo en `test/support/`, uno por agregado (`InMemoryOrderRepository`), con el mismo contrato que el real (copias guardadas, comprobación de versión, `markPersisted()`), y lo usa en los tests con un `DomainEventBus` sobre `InMemoryEventChannel`. Solo tiene `findAll()` si los tests del proyecto lo necesitan; un repositorio real no lo tiene.
+* El paquete no da un repositorio en memoria: cada proyecto escribe el suyo en `test/support/`, uno por agregado (`InMemoryOrderRepository`), con el mismo contrato que el real (copias guardadas, versiones en un `WeakMap` y su comprobación), y lo usa en los tests con un `DomainEventBus` sobre `InMemoryEventChannel`. Solo tiene `findAll()` si los tests del proyecto lo necesitan; un repositorio real no lo tiene.
 
 Un repositorio da la ilusión de una colección en memoria con todos los agregados de un tipo, con una interfaz conocida para añadir, quitar y seleccionar. **Solo los agregados tienen repositorio**, normalmente uno por tipo de agregado [IDDD cap. 12, citando a Evans].
 
@@ -47,7 +47,7 @@ El proyecto no declara un `OrderRepository`: usa los contratos del paquete, que
 | Rol (`@archi-code/ddd/domain`) | Método | Contrato |
 |---|---|---|
 | `AggregateFinder<Order>` | `findById(id: OrderId): Promise<Order \| null>` | Devuelve el agregado completo con su versión almacenada, o `null` |
-| `AggregateSaver<Order>` | `save(order: Order): Promise<void>` | Alta (versión 0) y cambios; comprueba la versión y llama a `markPersisted()` |
+| `AggregateSaver<Order>` | `save(order: Order): Promise<void>` | Alta (versión 0) y cambios; comprueba la versión que recuerda su `WeakMap` y la actualiza tras escribir |
 | `AggregateRemover<Order>` | `remove(order: Order): Promise<void>` | Borra el agregado cargado solo si nadie lo cambió después |
 
 Un caso de uso pide exactamente los roles que usa. Constructor de `AddOrderLine` (la clase completa, con `toCommand` y `handle`, está en `ddd-skills/ddd-repositorios-persistencia/references/transacciones-ts.md`):
@@ -76,8 +76,8 @@ export class AddOrderLine extends UseCase<AddOrderLineInput, AddOrderLineCommand
 
 Guía completa con MongoDB, PostgreSQL y Prisma en `ddd-skills/ddd-repositorios-persistencia/references/implementacion-ts.md`. Puntos clave:
 
-* El agregado se convierte en datos planos y vuelve a construirse con sus value objects [IDDD cap. 6]: la conversión es del propio agregado y el repositorio llama a `order.toPrimitives()` y a `Order.fromPrimitives(row).restoreVersion(version)` `[Fuera de los libros: convención de @archi-code/ddd]`. Que no falte ningún campo lo prueba el test de ida y vuelta del agregado, no una comprobación en ejecución.
-* La **versión** se comprueba al guardar y al borrar (concurrencia optimista) [IDDD cap. 10]: se guarda junto a los primitivos, nunca dentro, y tras escribir el repositorio llama a `order.markPersisted()`.
+* El agregado se convierte en datos planos y vuelve a construirse con sus value objects [IDDD cap. 6]: la conversión es del propio agregado y el repositorio llama a `order.toPrimitives()` y a `Order.fromPrimitives(row.primitives)` `[Fuera de los libros: convención de @archi-code/ddd]`. Que no falte ningún campo lo prueba el test de ida y vuelta del agregado, no una comprobación en ejecución.
+* La **versión** se comprueba al guardar y al borrar (concurrencia optimista) [IDDD cap. 10]: se guarda junto a los primitivos, nunca dentro; el repositorio la recuerda por agregado en su `WeakMap` y la actualiza solo tras escribir con éxito `[Fuera de los libros: convención de @archi-code/ddd]`.
 * Los **eventos** los publica el caso de uso con `EventBus.publish` después de `save`. Si un evento no puede perderse, el repositorio escribe el agregado y sus eventos pendientes en la misma escritura atómica (outbox) y un proceso aparte los entrega después por un `EventChannel` (`ddd-skills/ddd-repositorios-persistencia/references/transacciones-ts.md`, `ddd-skills/ddd-eventos-dominio/GUIA.md`).
 * El **esquema** sirve al modelo, no al revés [IDDD cap. 6]. Un agregado pequeño encaja a menudo en un documento, o en una fila con una columna `jsonb` para sus value objects.
 
@@ -112,7 +112,7 @@ Un mismo conjunto de tests de contrato, en `test/support/` del proyecto, se ejec
 * El repositorio lee campos del agregado o construye filas a mano en vez de llamar a `order.toPrimitives()` y `Order.fromPrimitives(row)`.
 * El constructor del repositorio recibe la clase del agregado o un mapper: recibe solo las dependencias de su tecnología.
 * Un campo nuevo del agregado que no está en `toPrimitives()`/`fromPrimitives()`, sobre todo uno privado que `PrimitiveTypes<Order>` no ve, sin un test de ida y vuelta que lo detecte.
-* `save` con `upsert` sin condición de versión, `fromPrimitives(row)` sin la versión almacenada o `markPersisted()` olvidado tras escribir.
+* `save` con `upsert` sin condición de versión, cargar sin recordar la versión almacenada en el `WeakMap`, olvidar actualizarla tras escribir (el segundo `save` del mismo objeto da un falso conflicto) o actualizarla antes de que la escritura termine. También la versión dentro de `toPrimitives()` o como campo del agregado.
 * Un repositorio en memoria que no comprueba versiones ni copia objetos (los tests pasan, producción falla): escríbelo como `InMemoryOrderRepository` y ejecuta contra él la suite de contrato.
 
 ## Siguiente guía

package/ddd-skills/ddd-repositorios-persistencia/references/implementacion-ts.md

@@ -27,17 +27,17 @@ const primitives: PrimitiveTypes<Order> = {
 };
 ```
 
-Un documento (o una fila) por agregado: lectura rápida, sin joins, y la versión protege todo el agregado [IDDD cap. 10]. La versión se guarda **junto a** los primitivos, nunca dentro: el agregado no la declara y `PrimitiveTypes` la deja fuera `[Fuera de los libros: convención de @archi-code/ddd]`.
+Un documento (o una fila) por agregado: lectura rápida, sin joins, y la versión protege todo el agregado [IDDD cap. 10]. La versión se guarda **junto a** los primitivos, nunca dentro: el agregado no la declara ni la mapea, y el caso de uso nunca la ve `[Fuera de los libros: convención de @archi-code/ddd]`.
 
-Convención de versiones del paquete: un agregado nuevo tiene `version` 0; al insertarlo se guarda con 1 y `markPersisted()` lo lleva a 1. Cada actualización exige que la versión almacenada coincida con `order.version`, guarda `order.version + 1` y llama a `markPersisted()`. Al cargar, el repositorio llama a `Order.fromPrimitives(primitives).restoreVersion(storedVersion)`. El repositorio llama a `markPersisted()` solo cuando la escritura se completó (en SQL, tras el `COMMIT`); si `save` lanza, el objeto conserva su versión y el caso de uso lo descarta y vuelve a cargarlo.
+Convención de versiones del paquete: la versión es solo del repositorio. Cada repositorio recuerda la versión de cada agregado que cargó o guardó en un campo privado `versions = new WeakMap<Order, number>()`. Al cargar, `this.versions.set(order, row.version)`. Al guardar, `const version = this.versions.get(order) ?? 0` (`0` es un agregado nuevo): escribe solo donde la versión almacenada es `version` (un agregado nuevo se inserta y un id ya ocupado es un conflicto), guarda `version + 1` junto a los primitivos y, solo cuando la escritura se completó (en SQL, tras el `COMMIT`), hace `this.versions.set(order, version + 1)`. Si `save` lanza, el repositorio sigue recordando la versión anterior y el caso de uso descarta el objeto y vuelve a cargarlo. `remove` comprueba la versión igual. Al ser un `WeakMap`, un agregado que nadie usa ya no retiene memoria `[Fuera de los libros: convención de @archi-code/ddd]`.
 
 ## Conversión
 
 No se escribe un mapper: la conversión es del agregado, su único dueño (`toPrimitives()` y `static fromPrimitives()`, su instantánea o Memento), no de un servicio de dominio ni de un mapper hecho a mano, y no hay comprobación de forma en medio `[Fuera de los libros: convención de @archi-code/ddd]`. El repositorio llama al agregado directamente:
 
-* Al escribir: guarda `order.toPrimitives()` con `order.version + 1` al lado y, tras escribir, llama a `order.markPersisted()`.
-* Al leer: `Order.fromPrimitives(row).restoreVersion(row.version)`.
-* En un conflicto: `throw new ConcurrencyException('Order', key, order.version)`, con el nombre del agregado como texto literal, no como nombre de clase: los minificadores cambian los nombres de las clases.
+* Al escribir: guarda `order.toPrimitives()` con `version + 1` al lado (`version` es la que recuerda su `WeakMap`, `0` si es nuevo) y, tras escribir, `this.versions.set(order, version + 1)`.
+* Al leer: `const order = Order.fromPrimitives(row.primitives)` y `this.versions.set(order, row.version)`.
+* En un conflicto: `throw new ConcurrencyException('Order', key, version)`, con el nombre del agregado como texto literal, no como nombre de clase: los minificadores cambian los nombres de las clases.
 
 Nada comprueba en ejecución que la conversión esté completa. Lo garantizan el agregado y sus tests: el spec de cada agregado prueba el viaje de ida y vuelta (`Order.fromPrimitives(order.toPrimitives()).toPrimitives()` igual a `order.toPrimitives()`), y quien añade un campo lo añade a `toPrimitives()` y a `fromPrimitives()`, también un campo privado que TypeScript no ve en `PrimitiveTypes<Order>`.
 
@@ -56,7 +56,8 @@ import type {
   AggregateSaver,
   PrimitiveTypes,
 } from '@archi-code/ddd/domain';
-import { ConcurrencyException, InternalErrorException } from '@archi-code/ddd/exceptions';
+import { ConcurrencyException } from '@archi-code/ddd/application';
+import { InternalErrorException } from '@archi-code/ddd/infrastructure';
 import { Order, OrderId } from '../../domain/order/order';
 
 export type OrderDocument = PrimitiveTypes<Order> & { _id: string; version: number };
@@ -66,6 +67,8 @@ const DUPLICATE_KEY = 11000;
 export class MongoOrderRepository
   implements AggregateFinder<Order>, AggregateSaver<Order>, AggregateRemover<Order>
 {
+  private readonly versions = new WeakMap<Order, number>();
+
   constructor(private readonly collection: Collection<OrderDocument>) {}
 
   async findById(id: OrderId): Promise<Order | null> {
@@ -74,54 +77,60 @@ export class MongoOrderRepository
       return null;
     }
     const { _id, version, ...primitives } = document;
-    return Order.fromPrimitives(primitives).restoreVersion(version);
+    const order = Order.fromPrimitives(primitives);
+    this.versions.set(order, version);
+    return order;
   }
 
   async save(order: Order): Promise<void> {
+    const version = this.versions.get(order) ?? 0;
     const document: OrderDocument = {
       ...order.toPrimitives(),
       _id: order.id.value,
-      version: order.version + 1,
+      version: version + 1,
     };
-    const written = await this.write(order, async () => {
-      if (order.version === 0) {
+    const written = await this.write(order, version, async () => {
+      if (version === 0) {
         await this.collection.insertOne(document);
         return true;
       }
       const { matchedCount } = await this.collection.replaceOne(
-        { _id: document._id, version: order.version },
+        { _id: document._id, version },
         document,
       );
       return matchedCount === 1;
     });
     if (!written) {
-      throw new ConcurrencyException('Order', order.id.value, order.version);
+      throw new ConcurrencyException('Order', order.id.value, version);
     }
-    order.markPersisted();
+    this.versions.set(order, version + 1);
   }
 
   async remove(order: Order): Promise<void> {
+    const version = this.versions.get(order) ?? 0;
     const filter = { _id: order.id.value };
-    const removed = await this.write(order, async () => {
-      if (order.version === 0) {
+    const removed = await this.write(order, version, async () => {
+      if (version === 0) {
         return (await this.collection.countDocuments(filter, { limit: 1 })) === 0;
       }
-      const { deletedCount } = await this.collection.deleteOne({ ...filter, version: order.version });
+      const { deletedCount } = await this.collection.deleteOne({ ...filter, version });
       return deletedCount === 1;
     });
     if (!removed) {
-      throw new ConcurrencyException('Order', order.id.value, order.version);
+      throw new ConcurrencyException('Order', order.id.value, version);
     }
   }
 
-  private async write(order: Order, operation: () => Promise<boolean>): Promise<boolean> {
+  private async write(
+    order: Order,
+    version: number,
+    operation: () => Promise<boolean>,
+  ): Promise<boolean> {
     try {
       return await operation();
     } catch (error) {
       if (error instanceof MongoServerError && error.code === DUPLICATE_KEY) {
-        throw new ConcurrencyException('Order', order.id.value, order.version, {
-          cause: error,
-        });
+        throw new ConcurrencyException('Order', order.id.value, version, { cause: error });
       }
       throw new InternalErrorException(`writing order ${order.id.value}`, { cause: error });
     }
@@ -129,9 +138,9 @@ export class MongoOrderRepository
 }
 ```
 
-* Alta (`version === 0`): `insertOne`; un `_id` ya ocupado (error 11000) es `ConcurrencyException` con el error del driver como `cause`.
-* Cambio: `replaceOne` con la condición `{ _id, version: order.version }`; si no casa ningún documento, otro guardó antes.
-* Un conflicto es `ConcurrencyException`: el caso de uso puede reintentar volviendo a cargar y a guardar, y `HttpErrorMapper` responde 409, no 500.
+* Alta (el `WeakMap` no conoce el agregado, `version === 0`): `insertOne`; un `_id` ya ocupado (error 11000) es `ConcurrencyException` con el error del driver como `cause`.
+* Cambio: `replaceOne` con la condición `{ _id, version }`, la versión que el repositorio recordaba; si no casa ningún documento, otro guardó antes.
+* Un conflicto es `ConcurrencyException`: el caso de uso puede reintentar volviendo a cargar y a guardar, y `ExceptionClassifier` lo clasifica como `ExceptionKind.Conflict` (409 en HTTP), no como error interno.
 * Borrado: `deleteOne` con la misma condición. Un agregado que nunca se guardó (versión 0) no tiene nada que borrar, salvo que su id ya esté ocupado: entonces es un conflicto, igual que en el `InMemoryOrderRepository` de los tests (`ddd-skills/ddd-repositorios-persistencia/references/tests-repositorios.md`).
 * Cualquier otro error del driver al escribir es `InternalErrorException` con el error como `cause`.
 * Cuidado con la serialización: IDDD advierte de que en estos almacenes hay que cuidar el formato serializado, que no es gratis [IDDD cap. 12]. Los primitivos son datos planos y `Date`, que el driver guarda tal cual.
@@ -154,7 +163,8 @@ CREATE TABLE orders (
 
 ```ts
 import type { AggregateFinder, AggregateSaver, PrimitiveTypes } from '@archi-code/ddd/domain';
-import { ConcurrencyException, InternalErrorException } from '@archi-code/ddd/exceptions';
+import { ConcurrencyException } from '@archi-code/ddd/application';
+import { InternalErrorException } from '@archi-code/ddd/infrastructure';
 import { Order, OrderId } from '../../domain/order/order';
 import type { PgPool } from './pg-pool';
 
@@ -164,6 +174,8 @@ interface OrderRow {
 }
 
 export class PostgresOrderRepository implements AggregateFinder<Order>, AggregateSaver<Order> {
+  private readonly versions = new WeakMap<Order, number>();
+
   constructor(private readonly pool: PgPool) {}
 
   async findById(id: OrderId): Promise<Order | null> {
@@ -171,28 +183,34 @@ export class PostgresOrderRepository implements AggregateFinder<Order>, Aggregat
       'SELECT version, data FROM orders WHERE id = $1',
       [id.value],
     );
-    return rows[0] ? Order.fromPrimitives(rows[0].data).restoreVersion(rows[0].version) : null;
+    if (rows[0] === undefined) {
+      return null;
+    }
+    const order = Order.fromPrimitives(rows[0].data);
+    this.versions.set(order, rows[0].version);
+    return order;
   }
 
   async save(order: Order): Promise<void> {
+    const version = this.versions.get(order) ?? 0;
     const primitives = order.toPrimitives();
     const write =
-      order.version === 0
+      version === 0
         ? this.pool.query(
             'INSERT INTO orders (id, version, customer_id, status, data) VALUES ($1, 1, $2, $3, $4) ON CONFLICT (id) DO NOTHING',
             [primitives.id, primitives.customerId, primitives.status, primitives],
           )
         : this.pool.query(
             'UPDATE orders SET version = version + 1, status = $3, data = $4 WHERE id = $1 AND version = $2',
-            [primitives.id, order.version, primitives.status, primitives],
+            [primitives.id, version, primitives.status, primitives],
           );
     const { rowCount } = await write.catch((error: unknown) => {
       throw new InternalErrorException(`writing order ${order.id.value}`, { cause: error });
     });
     if (rowCount === 0) {
-      throw new ConcurrencyException('Order', order.id.value, order.version);
+      throw new ConcurrencyException('Order', order.id.value, version);
     }
-    order.markPersisted();
+    this.versions.set(order, version + 1);
   }
 }
 ```
@@ -202,8 +220,8 @@ Al leer `data` de `jsonb`, `paymentAuthorization.expiresAt` llega como texto ISO
 ## Con Prisma
 
 `[Fuera de los libros]`
-* El esquema de Prisma y su cliente viven en infraestructura. El repositorio implementa `AggregateFinder<Order>` y `AggregateSaver<Order>`, recibe el `PrismaClient` y devuelve agregados con `Order.fromPrimitives(row.data).restoreVersion(row.version)`, nunca modelos de Prisma.
-* La concurrencia optimista con Prisma: `updateMany({ where: { id, version: order.version }, data: { ..., version: { increment: 1 } } })`; si `count === 0`, `ConcurrencyException('Order', order.id.value, order.version)`; si no, `order.markPersisted()`.
+* El esquema de Prisma y su cliente viven en infraestructura. El repositorio implementa `AggregateFinder<Order>` y `AggregateSaver<Order>`, recibe el `PrismaClient` y devuelve agregados con `Order.fromPrimitives(row.data)` (y `this.versions.set(order, row.version)` en su `WeakMap`), nunca modelos de Prisma.
+* La concurrencia optimista con Prisma: con `const version = this.versions.get(order) ?? 0`, `updateMany({ where: { id, version }, data: { ..., version: { increment: 1 } } })`; si `count === 0`, `ConcurrencyException('Order', order.id.value, version)`; si no, `this.versions.set(order, version + 1)`.
 * Si el agregado ocupa varios modelos de Prisma, el repositorio agrupa sus escrituras con `prisma.$transaction(async (tx) => ...)` dentro de su propio `save`; la aplicación nunca la abre `[Fuera de los libros: convención de @archi-code/ddd]`.
 
 ## Consultas de lectura

package/ddd-skills/ddd-repositorios-persistencia/references/tests-repositorios.md

@@ -4,7 +4,7 @@
 
 Un mapa con la identidad como clave y el agregado como valor [IDDD cap. 12]. Dos detalles para que no mienta `[Fuera de los libros]`: guardar copias (para que modificar un objeto sin `save` no "persista") y comprobar versiones.
 
-El paquete no lo da: cada proyecto escribe el suyo en `test/support/`, uno por agregado, como cualquier otra implementación de una tecnología `[Fuera de los libros: convención de @archi-code/ddd]`. Implementa los roles de `@archi-code/ddd/domain` para su agregado (`AggregateFinder<Order>`, `AggregateSaver<Order>`, `AggregateRemover<Order>`), su constructor no recibe nada (no hay tecnología de la que depender) y llama a `order.toPrimitives()` y `Order.fromPrimitives(row).restoreVersion(version)`, igual que un adaptador real.
+El paquete no lo da: cada proyecto escribe el suyo en `test/support/`, uno por agregado, como cualquier otra implementación de una tecnología `[Fuera de los libros: convención de @archi-code/ddd]`. Implementa los roles de `@archi-code/ddd/domain` para su agregado (`AggregateFinder<Order>`, `AggregateSaver<Order>`, `AggregateRemover<Order>`), su constructor no recibe nada (no hay tecnología de la que depender) llama a `order.toPrimitives()` y `Order.fromPrimitives(row.primitives)` y recuerda la versión de cada agregado en un `WeakMap`, igual que un adaptador real.
 
 En `test/support/in-memory-order-repository.ts`:
 
@@ -15,44 +15,58 @@ import type {
   AggregateSaver,
   PrimitiveTypes,
 } from '@archi-code/ddd/domain';
-import { ConcurrencyException } from '@archi-code/ddd/exceptions';
+import { ConcurrencyException } from '@archi-code/ddd/application';
 import { Order } from '../../src/contexts/sales/domain/order/order';
 import type { OrderId } from '../../src/contexts/sales/domain/order/order';
 
+interface StoredOrder {
+  version: number;
+  primitives: PrimitiveTypes<Order>;
+}
+
 export class InMemoryOrderRepository
   implements AggregateFinder<Order>, AggregateSaver<Order>, AggregateRemover<Order>
 {
-  private readonly rows = new Map<string, { version: number; primitives: PrimitiveTypes<Order> }>();
+  private readonly rows = new Map<string, StoredOrder>();
+  private readonly versions = new WeakMap<Order, number>();
 
   async findById(id: OrderId): Promise<Order | null> {
     const row = this.rows.get(id.value);
-    return row === undefined
-      ? null
-      : Order.fromPrimitives(structuredClone(row.primitives)).restoreVersion(row.version);
+    return row === undefined ? null : this.load(row);
   }
 
   async save(order: Order): Promise<void> {
-    const key = this.currentKey(order);
-    this.rows.set(key, { version: order.version + 1, primitives: structuredClone(order.toPrimitives()) });
-    order.markPersisted();
+    const key = order.id.value;
+    const version = this.checkedVersion(order);
+    const primitives = structuredClone(order.toPrimitives());
+    this.rows.set(key, { version: version + 1, primitives });
+    this.versions.set(order, version + 1);
   }
 
   async remove(order: Order): Promise<void> {
-    this.rows.delete(this.currentKey(order));
+    this.checkedVersion(order);
+    this.rows.delete(order.id.value);
   }
 
-  private currentKey(order: Order): string {
+  private checkedVersion(order: Order): number {
     const key = order.id.value;
-    if ((this.rows.get(key)?.version ?? 0) !== order.version) {
-      throw new ConcurrencyException('Order', key, order.version);
+    const version = this.versions.get(order) ?? 0;
+    if ((this.rows.get(key)?.version ?? 0) !== version) {
+      throw new ConcurrencyException('Order', key, version);
     }
-    return key;
+    return version;
+  }
+
+  private load(row: StoredOrder): Order {
+    const order = Order.fromPrimitives(structuredClone(row.primitives));
+    this.versions.set(order, row.version);
+    return order;
   }
 }
 ```
 
-* Guarda `structuredClone` de `order.toPrimitives()` con su versión al lado, y cada `findById` reconstruye un objeto nuevo con `Order.fromPrimitives(copy).restoreVersion(version)`: cambiar un agregado sin `save` no persiste nada.
-* Sigue el mismo contrato de concurrencia que un repositorio real: `save` y `remove` lanzan `ConcurrencyException` si la versión almacenada no coincide con `order.version` (también al dar de alta un id ocupado), y tras guardar llama a `markPersisted()`.
+* Guarda `structuredClone` de `order.toPrimitives()` con su versión al lado (nunca dentro), y cada `findById` reconstruye un objeto nuevo con `Order.fromPrimitives(copy)` y anota en `versions` la versión de la fila: cambiar un agregado sin `save` no persiste nada.
+* Sigue el mismo contrato de concurrencia que un repositorio real: la versión es solo del repositorio, que recuerda la de cada agregado que cargó o guardó en un `WeakMap<Order, number>` (`0` si no lo conoce: es nuevo). `save` y `remove` lanzan `ConcurrencyException` si la versión almacenada no coincide con la recordada (también al dar de alta un id ocupado), y `save` actualiza el `WeakMap` solo después de escribir. El agregado no declara ni mapea ninguna versión `[Fuera de los libros: convención de @archi-code/ddd]`.
 * Las claves son `id.value`; `IdType` y `UuidType` guardan el valor en minúsculas, así que la búsqueda no distingue mayúsculas.
 * Cada `save` y cada `remove` es atómico, como el de un repositorio real: no hay transacción que abrir ni estado que restaurar en los tests (la transacción es del repositorio, `ddd-skills/ddd-repositorios-persistencia/references/transacciones-ts.md`).
 * No tiene `findAll()` salvo que los tests del proyecto lo necesiten; si se añade, es solo comodidad de los tests y un repositorio real no lo tiene `[Fuera de los libros: convención de @archi-code/ddd]`. Nunca se usa en producción.
@@ -67,7 +81,7 @@ Un único conjunto de tests, en `test/support/order-repository-contract.ts` del
 ```ts
 import { expect, it } from 'vitest';
 import type { AggregateFinder, AggregateRemover, AggregateSaver } from '@archi-code/ddd/domain';
-import { ConcurrencyException } from '@archi-code/ddd/exceptions';
+import { ConcurrencyException } from '@archi-code/ddd/application';
 import { FixedClock } from '@archi-code/ddd/infrastructure';
 import {
   CustomerId,