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

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

@@ -0,0 +1,121 @@
+# Repositorios y persistencia
+
+> 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.** Repositorios DDD y persistencia de agregados en TypeScript/Node. Cubre un repositorio por agregado, repositorios orientados a colección frente a orientados a persistencia (save), interfaz en el dominio e implementación en infraestructura, mappers entre filas o documentos y el modelo, concurrencia optimista, la transacción como responsabilidad del repositorio, consultas y "use case optimal queries", diferencias con un DAO, implementaciones en memoria y tests de contrato. Consúltala siempre que haya que guardar o cargar agregados, integrar Prisma, TypeORM, Drizzle, MikroORM, pg o MongoDB con un modelo de dominio, diseñar métodos find/save, gestionar transacciones, o cuando el ORM esté dictando la forma de las clases del dominio, aunque no se mencione "repository".
+
+## Con @archi-code/ddd
+
+[Fuera de los libros: convención de @archi-code/ddd]
+
+* 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.
+* `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.
+
+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].
+
+
+## Reglas
+
+1. **Un repositorio por agregado**, nunca por entidad interna ni por tabla [IDDD cap. 12].
+2. **La interfaz vive en el dominio** con lenguaje del dominio; la implementación, en infraestructura [IDDD cap. 4 y cap. 12; PHP: Repositories]. Con el paquete, los contratos ya están en `@archi-code/ddd/domain` y tu adaptador (`MongoOrderRepository`) vive en `infrastructure/persistence/`.
+3. **Devuelve agregados completos** (o value objects para consultas concretas), nunca filas, DTOs del ORM ni partes que la raíz no permita alcanzar [IDDD cap. 12].
+4. **No es un DAO.** Un DAO se expresa en términos de tablas y CRUD; un repositorio, en términos de colección de agregados. Operaciones CRUD de grano fino sobre partes del agregado rompen su encapsulación [IDDD cap. 12; PHP: Repositories].
+5. **El dominio no gestiona transacciones** [IDDD cap. 12; Destilado cap. 2]. Los libros las controlan desde la capa de aplicación; con el paquete las controla el repositorio, dentro de `save`/`remove`, y la aplicación tampoco las ve `[Fuera de los libros: convención de @archi-code/ddd]`.
+6. **Una escritura atómica, un agregado.** La "transacción por agregado" de los libros es aquí una escritura atómica por agregado, garantizada por el repositorio. Que funcione en tests no significa que funcione en producción con concurrencia [IDDD cap. 12].
+7. **Nada de lógica de negocio en procedimientos almacenados** salvo requisito no funcional que lo exija; saca la lógica del modelo y de su lenguaje [IDDD cap. 12].
+
+## Paso 1. Elegir el estilo
+
+| Estilo | Interfaz | Cuándo [IDDD cap. 12; PHP: Repositories] |
+|---|---|---|
+| Orientado a colección | `add`, `remove` y búsqueda por id; los cambios se detectan solos | El mecanismo tiene unidad de trabajo que rastrea cambios |
+| Orientado a persistencia | `save`, `remove` y búsqueda por id; hay que guardar explícitamente | Sin rastreo de cambios (almacenes clave-valor, documentos) o cuando es realista cambiar de mecanismo |
+
+**Con el paquete el estilo es orientado a persistencia** `[Fuera de los libros: convención de @archi-code/ddd]`: los roles son `findById`, `save` y `remove`, y cada cambio se guarda con un `save` explícito. Los clientes más usados (driver de MongoDB, pg, Prisma, Drizzle) no rastrean cambios de objetos de dominio, y un `save` explícito es más legible. Una unidad de trabajo de ORM (MikroORM) ataría el dominio al ORM.
+
+## Paso 2. Elegir los roles
+
+El proyecto no declara un `OrderRepository`: usa los contratos del paquete, que reciben el agregado como parámetro de tipo.
+
+| 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()` |
+| `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`):
+
+```ts
+import { UseCase } from '@archi-code/ddd/application';
+import type { Clock, EventBus } from '@archi-code/ddd/application';
+import type { AggregateFinder, AggregateSaver } from '@archi-code/ddd/domain';
+
+export class AddOrderLine extends UseCase<AddOrderLineInput, AddOrderLineCommand, void> {
+  constructor(
+    private readonly orders: AggregateFinder<Order> & AggregateSaver<Order>,
+    private readonly events: EventBus<OrderEvent>,
+    private readonly clock: Clock,
+  ) {
+    super();
+  }
+}
+```
+
+* El repositorio solo obtiene y persiste: sin lógica de negocio, sin consultas de negocio (`pendingOlderThan`) y sin generar identidades (`nextId()`) `[Fuera de los libros: convención de @archi-code/ddd]`. La identidad nueva la genera su value object (`OrderId.generate()`, ver `ddd-skills/ddd-value-objects-entidades/GUIA.md`); las selecciones son consultas de lectura (Paso 5).
+* Nada de `findAll()` ni `findBy(field, value)` genéricos.
+* Consultas para pantallas que cruzan agregados no van aquí: van a consultas de lectura (ver Paso 5).
+
+## Paso 3. Implementar
+
+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()`.
+* 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.
+
+## Paso 4. Transacciones
+
+La transacción es del repositorio, como todo lo demás de la persistencia `[Fuera de los libros: convención de @archi-code/ddd]`. La aplicación no abre, une ni cierra transacciones: el caso de uso carga, llama al método de negocio, `await this.orders.save(order)` y después `await this.events.publish(order.pullDomainEvents())`. El adaptador garantiza que cada `save`/`remove` es atómico (un documento en MongoDB; varias tablas SQL en una transacción que abre y confirma o revierte dentro del propio `save`, con su conexión), comprueba la versión (`ConcurrencyException`), gestiona la conexión, la sesión y el pool, y envuelve los errores del driver en `InternalErrorException` con `{ cause }`. Un conflicto se reintenta en `handle` volviendo a cargar y a guardar, con un límite y solo para comandos seguros de repetir. En tests basta el `InMemoryOrderRepository` que el proyecto escribe en `test/support/`. Patrón y ejemplos en `ddd-skills/ddd-repositorios-persistencia/references/transacciones-ts.md`.
+
+## Paso 5. Consultas
+
+* Para pantallas que cruzan varios agregados, IDDD admite consultas optimizadas por caso de uso que devuelven un value object a medida. Si necesitas muchas, sospecha: o los límites de agregado están mal ("el repositorio enmascara un mal diseño de agregados") o te conviene CQRS [IDDD cap. 12].
+* En la práctica, separa: los roles `AggregateFinder`/`AggregateSaver` para escribir y una consulta de lectura (`OrderSummaries`, `StaleOrders`) declarada como interfaz en la capa de aplicación e implementada en infraestructura directamente sobre la base de datos, con filtros de `@archi-code/criteria` `[Fuera de los libros]`. Nunca carga agregados con `AggregateFinder`. Ejemplo en `ddd-skills/ddd-repositorios-persistencia/references/implementacion-ts.md`.
+* *DDD in PHP* propone consultar el repositorio con especificaciones (`query(specification)`) [PHP: Repositories; PHP: Factories]. Aquí no: el repositorio no selecciona por criterios de negocio `[Fuera de los libros: convención de @archi-code/ddd]`. Una selección con nombre del negocio es una consulta de lectura que devuelve ids o DTOs; una `Specification` se aplica sobre datos ya cargados (`ddd-skills/ddd-value-objects-entidades/references/specification-y-diseno-flexible.md`).
+
+## Paso 6. Probar
+
+Dos tipos de prueba [IDDD cap. 12]:
+* **Del repositorio real**, contra la base de datos de verdad (por ejemplo con Testcontainers o `mongodb-memory-server`) `[herramienta fuera de los libros]`.
+* **Del código que usa repositorios**, con una implementación **en memoria** cuando la real es lenta o aún no existe [IDDD cap. 12; PHP: Repositories]. Con el paquete se escribe en `test/support/` del proyecto, una por agregado (`new InMemoryOrderRepository()`), como cualquier otra implementación `[Fuera de los libros: convención de @archi-code/ddd]`.
+
+Un mismo conjunto de tests de contrato, en `test/support/` del proyecto, se ejecuta contra ambas implementaciones para que la versión en memoria no mienta `[Fuera de los libros]`. Ver `ddd-skills/ddd-repositorios-persistencia/references/tests-repositorios.md`.
+
+## Señales de alarma
+
+* `UserRepository`, `OrderLineRepository`, `AddressRepository`: repositorios de partes internas.
+* Una interfaz `OrderRepository` todo en uno en el proyecto, o un caso de uso que recibe los tres roles cuando solo lee o solo guarda.
+* El repositorio devuelve tipos de Prisma, documentos de MongoDB o filas.
+* Decoradores `@Entity` del ORM en clases del dominio.
+* `updateStatus(id, status)` en el repositorio: CRUD de grano fino que salta al agregado.
+* El caso de uso recibe una dependencia `transactions`, `unitOfWork` o parecida, o abre `BEGIN`/`COMMIT` o `startTransaction()`: la transacción es del repositorio.
+* Un repositorio que reparte un agregado en varias tablas sin agrupar sus sentencias en una transacción dentro de `save`.
+* Docenas de métodos `findByXAndYOrderByZ` para pantallas.
+* 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.
+* 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
+
+* Casos de uso que usan los repositorios → `ddd-skills/ddd-servicios-capa-aplicacion/GUIA.md`.
+* Persistir como eventos en vez de estado → `ddd-skills/ddd-event-sourcing-cqrs/GUIA.md`.

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

@@ -0,0 +1,296 @@
+# Implementar repositorios en TypeScript
+
+Todos los ejemplos usan el agregado `Order` de `ddd-skills/ddd-agregados/references/implementacion-ts.md`, con sus value objects (`OrderId`, `CustomerId`, `OrderLines`, `OrderLine`, `Sku`, `Quantity`, `Money`, `ShippingAddress`, `OrderStatus`, `PaymentAuthorization`) y sus eventos: `Order.place(id, customerId, lines, address, clock)` lo crea pendiente con sus líneas, `addLine(line, clock)` añade una, y `toPrimitives()` y `static fromPrimitives()` son su conversión, la que llama el repositorio (ver `ddd-skills/ddd-agregados/GUIA.md`). El repositorio es código del proyecto en `infrastructure/persistence/` que implementa los roles del paquete.
+
+## Qué se guarda
+
+`[Fuera de los libros: esquema propio siguiendo IDDD cap. 6, valores embebidos en el registro del padre]`
+
+`PrimitiveTypes<Order>` es la forma persistida: cada value object se convierte en su valor, cada composite en sus primitivos, un enum en su opción y las fechas siguen siendo `Date`. Para `Order`:
+
+```ts
+import type { PrimitiveTypes } from '@archi-code/ddd/domain';
+import { Order, Status } from '../../domain/order/order';
+
+const primitives: PrimitiveTypes<Order> = {
+  id: '9b2f6c1e-4d3a-4f8b-a1c2-3e4d5f6a7b8c',
+  customerId: '3f1d2c4b-5a6e-4f70-8b9c-0d1e2f3a4b5c',
+  lines: { items: [{ sku: 'TORCH-01', quantity: 2, unitPrice: { amount: 4990, currency: 'EUR' } }] },
+  shippingAddress: { street: 'Calle Mayor 1', city: 'Huelva', country: 'ES' },
+  status: Status.Pending,
+  stockReservation: null,
+  paymentAuthorization: {
+    paymentId: '0b8e4f2a-6c1d-4e7f-9a3b-5d2c8e1f4a6b',
+    amount: { amount: 9980, currency: 'EUR' },
+    expiresAt: new Date('2026-03-08T09:30:00Z'),
+  },
+};
+```
+
+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]`.
+
+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.
+
+## 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.
+
+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>`.
+
+Cada repositorio es único para su agregado y su constructor recibe solo las dependencias de su tecnología (la `collection` de MongoDB, el `pool` de Postgres, el `PrismaClient`), nunca la clase del agregado ni un mapper: los agregados solo entran y salen por `save(order)`, `remove(order)` y `findById(id)` `[Fuera de los libros: convención de @archi-code/ddd]`. `toPrimitives()`/`fromPrimitives()` son la única puerta de infraestructura al estado interno `[Fuera de los libros: convención de @archi-code/ddd]`; el repositorio nunca lee getters del agregado ni construye filas a mano. Los constructores de los value objects validan al cargar: un dato corrupto falla en `fromPrimitives` y no dentro del modelo.
+
+## Repositorio con MongoDB
+
+Un documento por agregado es el encaje natural de un almacén orientado a agregados [IDDD cap. 12]. Cada `save` y cada `remove` es una sola operación sobre un documento, atómica por sí misma, así que no necesita sesión ni transacción: la transacción es del repositorio y aquí no hace falta abrir ninguna (`ddd-skills/ddd-repositorios-persistencia/references/transacciones-ts.md`) `[Fuera de los libros: convención de @archi-code/ddd]`. El repositorio implementa los tres roles y envuelve los errores de escritura del driver con su causa:
+
+```ts
+import { MongoServerError } from 'mongodb';
+import type { Collection } from 'mongodb';
+import type {
+  AggregateFinder,
+  AggregateRemover,
+  AggregateSaver,
+  PrimitiveTypes,
+} from '@archi-code/ddd/domain';
+import { ConcurrencyException, InternalErrorException } from '@archi-code/ddd/exceptions';
+import { Order, OrderId } from '../../domain/order/order';
+
+export type OrderDocument = PrimitiveTypes<Order> & { _id: string; version: number };
+
+const DUPLICATE_KEY = 11000;
+
+export class MongoOrderRepository
+  implements AggregateFinder<Order>, AggregateSaver<Order>, AggregateRemover<Order>
+{
+  constructor(private readonly collection: Collection<OrderDocument>) {}
+
+  async findById(id: OrderId): Promise<Order | null> {
+    const document = await this.collection.findOne({ _id: id.value });
+    if (document === null) {
+      return null;
+    }
+    const { _id, version, ...primitives } = document;
+    return Order.fromPrimitives(primitives).restoreVersion(version);
+  }
+
+  async save(order: Order): Promise<void> {
+    const document: OrderDocument = {
+      ...order.toPrimitives(),
+      _id: order.id.value,
+      version: order.version + 1,
+    };
+    const written = await this.write(order, async () => {
+      if (order.version === 0) {
+        await this.collection.insertOne(document);
+        return true;
+      }
+      const { matchedCount } = await this.collection.replaceOne(
+        { _id: document._id, version: order.version },
+        document,
+      );
+      return matchedCount === 1;
+    });
+    if (!written) {
+      throw new ConcurrencyException('Order', order.id.value, order.version);
+    }
+    order.markPersisted();
+  }
+
+  async remove(order: Order): Promise<void> {
+    const filter = { _id: order.id.value };
+    const removed = await this.write(order, async () => {
+      if (order.version === 0) {
+        return (await this.collection.countDocuments(filter, { limit: 1 })) === 0;
+      }
+      const { deletedCount } = await this.collection.deleteOne({ ...filter, version: order.version });
+      return deletedCount === 1;
+    });
+    if (!removed) {
+      throw new ConcurrencyException('Order', order.id.value, order.version);
+    }
+  }
+
+  private async write(order: Order, 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 InternalErrorException(`writing order ${order.id.value}`, { cause: error });
+    }
+  }
+}
+```
+
+* 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.
+* 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.
+
+## Con PostgreSQL
+
+`[Fuera de los libros: esquema propio siguiendo IDDD cap. 6]`
+
+```sql
+CREATE TABLE orders (
+  id           UUID        PRIMARY KEY,
+  version      INT         NOT NULL,
+  customer_id  UUID        NOT NULL,
+  status       TEXT        NOT NULL,
+  data         JSONB       NOT NULL
+);
+```
+
+`data` guarda `PrimitiveTypes<Order>` entero; las columnas sueltas (`customer_id`, `status`) se duplican solo para indexar las consultas de lectura. Todo el agregado cabe en una fila, así que cada `save` es una sola sentencia, atómica por sí misma, sobre el pool. `PgPool` (la interfaz estructural de los métodos de `pg` que usa) y la variante con las líneas en otra tabla, donde el repositorio abre y confirma una transacción dentro de `save`, están en `ddd-skills/ddd-repositorios-persistencia/references/transacciones-ts.md`. Este adaptador solo implementa los roles que soporta:
+
+```ts
+import type { AggregateFinder, AggregateSaver, PrimitiveTypes } from '@archi-code/ddd/domain';
+import { ConcurrencyException, InternalErrorException } from '@archi-code/ddd/exceptions';
+import { Order, OrderId } from '../../domain/order/order';
+import type { PgPool } from './pg-pool';
+
+interface OrderRow {
+  version: number;
+  data: PrimitiveTypes<Order>;
+}
+
+export class PostgresOrderRepository implements AggregateFinder<Order>, AggregateSaver<Order> {
+  constructor(private readonly pool: PgPool) {}
+
+  async findById(id: OrderId): Promise<Order | null> {
+    const { rows } = await this.pool.query<OrderRow>(
+      'SELECT version, data FROM orders WHERE id = $1',
+      [id.value],
+    );
+    return rows[0] ? Order.fromPrimitives(rows[0].data).restoreVersion(rows[0].version) : null;
+  }
+
+  async save(order: Order): Promise<void> {
+    const primitives = order.toPrimitives();
+    const write =
+      order.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],
+          );
+    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);
+    }
+    order.markPersisted();
+  }
+}
+```
+
+Al leer `data` de `jsonb`, `paymentAuthorization.expiresAt` llega como texto ISO con zona, que `ExpiresAt` (un `DateType`) convierte.
+
+## 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()`.
+* 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
+
+Las selecciones no pasan por el repositorio: son interfaces de la capa de aplicación que devuelven DTOs o ids, implementadas en infraestructura directamente sobre la base de datos [IDDD cap. 12, "use case optimal query"] `[Fuera de los libros: convención de @archi-code/ddd]`. Los filtros se escriben con `@archi-code/criteria` sobre la forma persistida (`PrimitiveTypes<Order>`) y `@archi-code/criteria-adapters/mongodb` los ejecuta:
+
+En `application/order-summaries/`:
+
+```ts
+import type { CustomerId } from '../../domain/order/order';
+
+export interface OrderSummary {
+  readonly id: string;
+  readonly status: string;
+  readonly lines: number;
+}
+
+export interface OrderSummaries {
+  ofCustomer(
+    customerId: CustomerId,
+    page: { limit: number; offset: number },
+  ): Promise<OrderSummary[]>;
+}
+
+export interface StaleOrders {
+  ids(expiredBefore: Date, limit: number): Promise<string[]>;
+}
+```
+
+En `infrastructure/persistence/`:
+
+```ts
+import { Criteria } from '@archi-code/criteria';
+import { searchMongo } from '@archi-code/criteria-adapters/mongodb';
+import type { Collection } from 'mongodb';
+import type { PrimitiveTypes } from '@archi-code/ddd/domain';
+import { Status } from '../../domain/order/order';
+import type { CustomerId, Order } from '../../domain/order/order';
+import type { OrderSummaries, OrderSummary, StaleOrders } from '../../application/order-summaries/order-summaries';
+import type { OrderDocument } from './mongo-order-repository';
+
+export class MongoOrderSummaries implements OrderSummaries {
+  constructor(private readonly collection: Collection<OrderDocument>) {}
+
+  async ofCustomer(
+    customerId: CustomerId,
+    page: { limit: number; offset: number },
+  ): Promise<OrderSummary[]> {
+    const { items } = await searchMongo<PrimitiveTypes<Order>, OrderDocument>(
+      this.collection,
+      Criteria.create<PrimitiveTypes<Order>>({
+        where: { customerId: customerId.value },
+        orderBy: { id: 'asc' },
+        limit: page.limit,
+        offset: page.offset,
+      }),
+    );
+    return items.map((order) => ({
+      id: order.id,
+      status: order.status,
+      lines: order.lines.items.length,
+    }));
+  }
+}
+
+export class MongoStaleOrders implements StaleOrders {
+  constructor(private readonly collection: Collection<OrderDocument>) {}
+
+  async ids(expiredBefore: Date, limit: number): Promise<string[]> {
+    const { items } = await searchMongo<PrimitiveTypes<Order>, OrderDocument>(
+      this.collection,
+      Criteria.create<PrimitiveTypes<Order>>({
+        where: {
+          status: Status.Pending,
+          'paymentAuthorization.expiresAt': { lt: expiredBefore },
+        },
+        orderBy: { 'paymentAuthorization.expiresAt': 'asc' },
+        limit,
+      }),
+    );
+    return items.map((order) => order.id);
+  }
+}
+```
+
+`T` es la forma persistida, no el agregado: la consulta nunca construye un `Order`. Un proceso por tiempo (pedidos pendientes cuya autorización de pago ha caducado) pide los ids a `StaleOrders` y ejecuta un caso de uso por agregado.
+
+## Jerarquías de tipos
+
+IDDD trata repositorios compartidos por subtipos y sus complicaciones [IDDD cap. 12]. Antes de diseñar una jerarquía de agregados, revisa si un tipo estándar (value object de estado o tipo, como `OrderStatus`) basta. Cada repositorio reconstruye una clase concreta con su `fromPrimitives`.

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

@@ -0,0 +1,177 @@
+# Probar repositorios
+
+## Repositorio en memoria
+
+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.
+
+En `test/support/in-memory-order-repository.ts`:
+
+```ts
+import type {
+  AggregateFinder,
+  AggregateRemover,
+  AggregateSaver,
+  PrimitiveTypes,
+} from '@archi-code/ddd/domain';
+import { ConcurrencyException } from '@archi-code/ddd/exceptions';
+import { Order } from '../../src/contexts/sales/domain/order/order';
+import type { OrderId } from '../../src/contexts/sales/domain/order/order';
+
+export class InMemoryOrderRepository
+  implements AggregateFinder<Order>, AggregateSaver<Order>, AggregateRemover<Order>
+{
+  private readonly rows = new Map<string, { version: number; primitives: PrimitiveTypes<Order> }>();
+
+  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);
+  }
+
+  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();
+  }
+
+  async remove(order: Order): Promise<void> {
+    this.rows.delete(this.currentKey(order));
+  }
+
+  private currentKey(order: Order): string {
+    const key = order.id.value;
+    if ((this.rows.get(key)?.version ?? 0) !== order.version) {
+      throw new ConcurrencyException('Order', key, order.version);
+    }
+    return key;
+  }
+}
+```
+
+* 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()`.
+* 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.
+* Otro agregado tiene el suyo, escrito igual (`InMemoryProductRepository` con `Product.fromPrimitives` y `product.toPrimitives()`).
+
+El repositorio en memoria no comprueba que la conversión esté completa: que `fromPrimitives` deshaga `toPrimitives` sin perder ningún campo lo prueba el spec del agregado (`Order.fromPrimitives(order.toPrimitives()).toPrimitives()` igual a `order.toPrimitives()`) `[Fuera de los libros: convención de @archi-code/ddd]`. La suite de contrato de abajo se ejecuta contra este repositorio y contra el adaptador real, así que el doble no puede apartarse del contrato. El repositorio no guarda los eventos publicados: los publica el caso de uso, y los tests los leen de `channel.sent` del `InMemoryEventChannel` `[Fuera de los libros: convención de @archi-code/ddd]`.
+
+## Tests de contrato compartidos
+
+Un único conjunto de tests, en `test/support/order-repository-contract.ts` del proyecto, recibe una fábrica de repositorios y se ejecuta contra la referencia en memoria y contra el adaptador real `[Fuera de los libros]`:
+
+```ts
+import { expect, it } from 'vitest';
+import type { AggregateFinder, AggregateRemover, AggregateSaver } from '@archi-code/ddd/domain';
+import { ConcurrencyException } from '@archi-code/ddd/exceptions';
+import { FixedClock } from '@archi-code/ddd/infrastructure';
+import {
+  CustomerId,
+  Order,
+  OrderId,
+  OrderLine,
+  OrderLines,
+  ShippingAddress,
+} from '../../src/contexts/sales/domain/order/order';
+
+const orderId = '9b2f6c1e-4d3a-4f8b-a1c2-3e4d5f6a7b8c';
+const customerId = '3f1d2c4b-5a6e-4f70-8b9c-0d1e2f3a4b5c';
+
+export function orderRepositoryContract(
+  make: () => Promise<AggregateFinder<Order> & AggregateSaver<Order> & AggregateRemover<Order>>,
+): void {
+  const clock = new FixedClock('2026-03-01T09:30:00Z');
+  const line = (sku: string) =>
+    OrderLine.fromPrimitives({ sku, quantity: 1, unitPrice: { amount: 4990, currency: 'EUR' } });
+  const placeOrder = () =>
+    Order.place(
+      new OrderId(orderId),
+      new CustomerId(customerId),
+      new OrderLines({ items: [line('TORCH-01')] }),
+      ShippingAddress.fromPrimitives({ street: 'Calle Mayor 1', city: 'Huelva', country: 'ES' }),
+      clock,
+    );
+
+  it('loads what it saved', async () => {
+    const orders = await make();
+    const order = placeOrder();
+    order.addLine(line('HELMET-02'), clock);
+    await orders.save(order);
+    expect((await orders.findById(order.id))?.toPrimitives()).toEqual(order.toPrimitives());
+  });
+
+  it('saves the same object twice', async () => {
+    const orders = await make();
+    const order = placeOrder();
+    await orders.save(order);
+    order.addLine(line('HELMET-02'), clock);
+    await expect(orders.save(order)).resolves.toBeUndefined();
+  });
+
+  it('refuses a stale save and a new order with a taken id', async () => {
+    const orders = await make();
+    await orders.save(placeOrder());
+    const first = await orders.findById(new OrderId(orderId));
+    const second = await orders.findById(new OrderId(orderId));
+    first!.addLine(line('HELMET-02'), clock);
+    await orders.save(first!);
+    second!.addLine(line('GLOVES-03'), clock);
+    await expect(orders.save(second!)).rejects.toThrow(ConcurrencyException);
+    await expect(orders.save(placeOrder())).rejects.toThrow(ConcurrencyException);
+  });
+
+  it('refuses to remove an order someone changed after it was loaded', async () => {
+    const orders = await make();
+    await orders.save(placeOrder());
+    const first = await orders.findById(new OrderId(orderId));
+    const second = await orders.findById(new OrderId(orderId));
+    await orders.save(first!);
+    await expect(orders.remove(second!)).rejects.toThrow(ConcurrencyException);
+  });
+
+  it('forgets a removed order', async () => {
+    const orders = await make();
+    const order = placeOrder();
+    await orders.save(order);
+    await orders.remove(order);
+    expect(await orders.findById(order.id)).toBeNull();
+  });
+}
+```
+
+El spec del adaptador lo ejecuta contra las dos implementaciones. El de MongoDB necesita un servidor real (Testcontainers, `mongodb-memory-server` o el de CI) `[herramienta fuera de los libros]`; cada fábrica usa una colección nueva para que los tests no compartan datos. En `test/contexts/sales/infrastructure/persistence/mongo-order-repository.spec.ts`, espejo de `src/`:
+
+```ts
+import { randomUUID } from 'node:crypto';
+import { MongoClient } from 'mongodb';
+import { afterAll, beforeAll, describe } from 'vitest';
+import { MongoOrderRepository } from '../../../../../src/contexts/sales/infrastructure/persistence/mongo-order-repository';
+import type { OrderDocument } from '../../../../../src/contexts/sales/infrastructure/persistence/mongo-order-repository';
+import { InMemoryOrderRepository } from '../../../../support/in-memory-order-repository';
+import { orderRepositoryContract } from '../../../../support/order-repository-contract';
+
+let client: MongoClient;
+
+beforeAll(async () => {
+  client = await MongoClient.connect(process.env.MONGO_TEST_URL!);
+});
+
+afterAll(() => client.close());
+
+const mongoOrders = async () =>
+  new MongoOrderRepository(
+    client.db('sales-test').collection<OrderDocument>(`orders-${randomUUID()}`),
+  );
+
+describe('InMemoryOrderRepository', () =>
+  orderRepositoryContract(async () => new InMemoryOrderRepository()));
+describe('MongoOrderRepository', () => orderRepositoryContract(mongoOrders));
+```
+
+Los tests del repositorio real usan la implementación de producción; si no, no sabes si funciona [IDDD cap. 12].
+
+Cada agregado tiene además un test de ida y vuelta de sus primitivos (`Order.fromPrimitives(order.toPrimitives()).toPrimitives()` igual a `order.toPrimitives()`), que no necesita repositorio (ver `ddd-skills/ddd-agregados/GUIA.md`).