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

package/ddd-skills/ddd-arquitectura/GUIA.md

@@ -0,0 +1,80 @@
+# Arquitectura de un Bounded Context
+
+> 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.** Arquitectura interna de un Bounded Context con DDD en TypeScript/Node. Cubre capas e inversión de dependencias, arquitectura hexagonal (puertos y adaptadores), qué va en dominio, aplicación, infraestructura e interfaz, módulos con nombres del lenguaje ubicuo, estructura de carpetas, composition root e inyección de dependencias, reglas automáticas de dependencias, cómo exponer REST sin exponer el modelo y cuándo (y cuándo no) añadir CQRS, arquitectura dirigida por eventos o Event Sourcing. Consúltala siempre que haya que crear o reorganizar la estructura de un proyecto o servicio con DDD, decidir dónde va un fichero o una clase, separar dominio de framework u ORM, montar la inyección de dependencias, configurar límites entre módulos, o cuando el dominio importe Express, Prisma, TypeORM o similares, aunque no se diga "arquitectura hexagonal".
+
+## Con @archi-code/ddd
+
+[Fuera de los libros: convención de @archi-code/ddd]
+
+* El dominio importa `@archi-code/ddd/domain`, `@archi-code/ddd/exceptions` y `@archi-code/validation` (no "nada externo"); la aplicación añade `@archi-code/ddd/application`; solo infraestructura y el composition root importan `@archi-code/ddd/infrastructure`, salvo `HttpErrorMapper` en los puntos de entrada.
+* No se escriben clases base ni puertos genéricos en el proyecto: `AggregateRoot`, `Entity`, `EventBase`, los tipos de value object y `Composite` vienen de `@archi-code/ddd/domain`; los contratos de repositorio son los roles `AggregateFinder`, `AggregateSaver` y `AggregateRemover` de `@archi-code/ddd/domain` (no hay un `OrderRepository` propio); `EventBus` y `Clock` vienen de `@archi-code/ddd/application` y `EventChannel` de `@archi-code/ddd/infrastructure`. No hay puerto de transacciones: el repositorio es responsable de la transacción y de todo lo relacionado con la persistencia.
+* Un mecanismo de mensajería es solo un `EventChannel` en `infrastructure/messaging/`; el bus es siempre `DomainEventBus`, y cambiar de tecnología cambia una línea del composition root. `DomainEventBus`, `EventRegistry` y el puerto `EventChannel` (con `ChannelHandler` y `ChannelSubscription`) se importan de `@archi-code/ddd/infrastructure`: son cableado de infraestructura. La aplicación solo ve el contrato para publicar (`EventBus`) y para escuchar (`EventListener` + `@ListensTo`) de `@archi-code/ddd/application`.
+* El composition root de cada contexto es el único que construye y conecta todo (repositorios, canal, `DomainEventBus`, suscripción de listeners con `bus.subscribe`) y lee `process.env`; nadie lo importa. El `dependency-cruiser.cjs` de esta guía ya aplica estas reglas.
+* Capa, dependencias permitidas y nombres de cada clase: `ddd-skills/archi-code-ddd/where-each-class-goes.md`.
+
+La arquitectura existe para proteger el modelo de dominio. El modelo debe estar libre de tecnología; por eso, por ejemplo, las transacciones las gestionan los servicios de aplicación y no el dominio [Destilado cap. 2]. Con el paquete tampoco las gestiona la aplicación: cada `save` y `remove` del adaptador del repositorio es una escritura atómica `[Fuera de los libros: convención de @archi-code/ddd]`. Y ningún estilo arquitectónico es una colección de herramientas para usar en todas partes: se aplica donde mitiga un riesgo concreto [IDDD cap. 4].
+
+
+## La arquitectura por defecto: hexagonal
+
+Recomendación de estas fuentes para cualquier contexto con modelo de dominio: **puertos y adaptadores** con inversión de dependencias. Motivos:
+
+* Con capas tradicionales, la infraestructura queda debajo del dominio y implementar repositorios obliga a romper las reglas o a hacer apaños [IDDD cap. 4].
+* Con DIP, módulos de alto y bajo nivel dependen de abstracciones; la infraestructura implementa interfaces definidas por las capas interiores [IDDD cap. 4].
+* Hexagonal da simetría: cada cliente o mecanismo de salida tiene su adaptador, y todos llegan al interior por la misma API de aplicación [IDDD cap. 4].
+* *DDD in PHP* la adopta como arquitectura base de sus ejemplos [PHP: Modules; PHP: Appendix Hexagonal].
+
+### Las cuatro zonas y la regla de dependencia
+
+```
+interfaces (adaptadores de entrada) ─┐
+                                     ├──▶ application ──▶ domain
+infrastructure (adaptadores salida) ─┘                     ▲
+         └──────────── implementa interfaces de ───────────┘
+```
+
+| Zona | Contiene | Puede depender de | Nunca |
+|---|---|---|---|
+| `domain` | Agregados (`AggregateRoot`), entidades (`Entity`), value objects, eventos de dominio (`EventBase`), servicios de dominio, puertos hacia servicios externos (`ProductPricing`); los contratos de repositorio son los roles `AggregateFinder`/`AggregateSaver`/`AggregateRemover` del paquete | Nada externo salvo `@archi-code/ddd/domain`, `@archi-code/ddd/exceptions` y `@archi-code/validation` | Framework web, ORM, cliente HTTP, `process.env`, logger |
+| `application` | Casos de uso (`UseCase`), listeners (`EventListener` + `@ListensTo`), consultas de lectura con sus DTOs, puertos de salida no de dominio (`EventBus` y `Clock` del paquete; los tuyos, como `Warehouse`) | `domain`, `@archi-code/ddd/application` | Express/Fastify, SQL, detalles de mensajería |
+| `infrastructure` | Repositorios concretos (`MongoOrderRepository`), ACL, canales de eventos (`EventChannel`) y el cableado de eventos (`DomainEventBus`, `EventRegistry`, en el composition root), clientes HTTP; el repositorio se encarga de la atomicidad de cada escritura, la versión, la conexión y los errores del driver | `domain`, `application`, `@archi-code/ddd/infrastructure` | Lógica de negocio |
+| `interfaces` | Controladores REST, consumidores de mensajes, CLI, resolvers GraphQL | `application`, `HttpErrorMapper` (y tipos de `domain` solo si es imprescindible) | Lógica de negocio, acceso directo a repositorios |
+
+Responsabilidades de los servicios de aplicación según IDDD: sin lógica de dominio, controlan transacciones y seguridad (en el paquete, la seguridad con `NotAllowedException`; la transacción pasa al adaptador del repositorio, que hace atómico cada `save` y `remove` `[Fuera de los libros: convención de @archi-code/ddd]`), pueden enviar notificaciones; son clientes directos del modelo y deben ser **finos**. Si crecen, la lógica de dominio se está escapando y el modelo se vuelve anémico [IDDD cap. 4]. Detalle en `ddd-skills/ddd-servicios-capa-aplicacion/GUIA.md`.
+
+En la interfaz se valida formato (campo obligatorio, longitud), no conocimiento profundo del negocio, que se queda en el modelo [IDDD cap. 4].
+
+## Flujo de trabajo
+
+1. **Decide si el contexto merece modelo de dominio.** Si no tiene reglas de negocio, un CRUD sencillo y bien encapsulado es legítimo [IDDD cap. 1]. La estructura hexagonal sigue siendo útil, pero sin agregados artificiales.
+2. **Crea la estructura de carpetas** con `ddd-skills/ddd-arquitectura/references/estructura-hexagonal-ts.md`. Si el proyecto ya reserva `src/app/` para la lógica principal, usa la variante descrita allí.
+3. **Nombra los módulos** con el lenguaje ubicuo, nunca por tipo de patrón (`entities/`, `services/`, `valueobjects/`). Guía en `ddd-skills/ddd-arquitectura/references/modulos.md`.
+4. **Monta el composition root**: un único punto donde se instancian adaptadores, se construye el `DomainEventBus` sobre un `EventChannel`, se inyectan los puertos en los casos de uso y se suscriben los listeners con `bus.subscribe`. Sin contenedor mágico salvo necesidad.
+5. **Automatiza las reglas de dependencia** con `ddd-skills/ddd-arquitectura/assets/dependency-cruiser.cjs`. Una regla que no se comprueba en CI acaba violándose `[Fuera de los libros]`.
+6. **Decide los estilos adicionales** (CQRS, eventos, Event Sourcing) con `ddd-skills/ddd-arquitectura/references/estilos-adicionales.md`. Por defecto, ninguno.
+
+## REST sin exponer el modelo
+
+Exponer el modelo directamente por REST produce interfaces frágiles: cada cambio del modelo rompe a los clientes. IDDD prefiere separar el modelo de la interfaz: recursos diseñados por casos de uso, construidos a partir de uno o varios agregados [IDDD cap. 4]. En TypeScript: el controlador comprueba la forma de la petición, llama a `execute` del caso de uso con su input, responde con lo que este devuelve (un id, un DTO o nada; nunca el agregado) y traduce los errores con `HttpErrorMapper` de `@archi-code/ddd/infrastructure` (404, 403, 409, 422…). Ejemplo en `ddd-skills/ddd-arquitectura/references/estructura-hexagonal-ts.md`.
+
+## Señales de alarma
+
+* `import` de `express`, `@prisma/client`, `typeorm`, `axios`, `pg`, `kafkajs` o similares dentro de `domain/`.
+* Decoradores de ORM (`@Entity`, `@Column`) en clases de dominio. Mezclan el modelo con la persistencia.
+* Clases base propias (`domain/shared/AggregateRoot.ts`, `ValueObject.ts`, `DomainEvent.ts`), un `OrderRepository` que lo hace todo, un `OrderMapper` a mano o un `EventPublisher` propio: el paquete ya da `AggregateRoot`, los roles de repositorio y `EventBus`, y la conversión a primitivos es del propio agregado (`toPrimitives()` y `static fromPrimitives()`).
+* `@archi-code/ddd/infrastructure` importado desde `domain/` o `application/`.
+* Carpetas `domain/entities`, `domain/services`, `domain/valueobjects`: módulos por tipo de patrón [PHP: Modules].
+* Controladores que llaman a repositorios o contienen `if` de negocio.
+* Servicios de aplicación de cientos de líneas [IDDD cap. 4].
+* Un único `utils/` o `common/` compartido entre contextos con lógica de negocio.
+* CQRS o Event Sourcing "porque es la arquitectura moderna", sin un riesgo concreto que mitiguen [IDDD cap. 4].
+* Un contexto nuevo creado para separar algo que bastaba con un módulo [IDDD cap. 9].
+
+## Siguiente guía
+
+* Diseñar lo que va dentro de `domain/` → `ddd-skills/ddd-value-objects-entidades/GUIA.md` y `ddd-skills/ddd-agregados/GUIA.md`.
+* Implementar repositorios en `infrastructure/` → `ddd-skills/ddd-repositorios-persistencia/GUIA.md`.
+* Casos de uso en `application/` → `ddd-skills/ddd-servicios-capa-aplicacion/GUIA.md`.
+* CQRS y Event Sourcing en profundidad → `ddd-skills/ddd-event-sourcing-cqrs/GUIA.md`.

package/ddd-skills/ddd-arquitectura/assets/dependency-cruiser.cjs

@@ -0,0 +1,92 @@
+/**
+ * Reglas de dependencia DDD para dependency-cruiser, adaptadas a @archi-code/ddd.
+ * Uso: npx depcruise src --config .dependency-cruiser.cjs
+ * Funciona con src/contexts/<contexto>/ y con src/app/contexts/<contexto>/ (proyectos con la lógica en src/app/).
+ * Probado con dependency-cruiser 16.10.0 y TypeScript 5.6, con un paquete simulado que expone
+ * @archi-code/ddd/{domain,application,infrastructure,exceptions}. Si la estructura publicada del
+ * paquete difiere, ajusta ARCHI_LAYER.
+ */
+// Grupo no capturante para app/: así $1 en las reglas es siempre el nombre del contexto.
+const CTX = '^src/(?:app/)?contexts/([^/]+)/';
+// Ruta resuelta de un punto de entrada del paquete: node_modules/@archi-code/ddd/<...>/<capa>/...
+const ARCHI_LAYER = (layers) => `node_modules/@archi-code/ddd/.*(?:${layers})[/.]`;
+
+module.exports = {
+  forbidden: [
+    {
+      name: 'domain-solo-paquetes-permitidos',
+      comment:
+        'El dominio solo usa @archi-code/ddd (domain y exceptions) y @archi-code/validation; nada más de npm.',
+      severity: 'error',
+      from: { path: CTX + 'domain/' },
+      to: {
+        dependencyTypes: ['npm', 'npm-dev', 'npm-optional', 'npm-peer'],
+        pathNot: ['node_modules/@archi-code/(?:ddd|validation)/'],
+      },
+    },
+    {
+      name: 'domain-sin-capas-exteriores-del-paquete',
+      comment: 'El dominio nunca importa @archi-code/ddd/application ni @archi-code/ddd/infrastructure.',
+      severity: 'error',
+      from: { path: CTX + 'domain/' },
+      to: { path: ARCHI_LAYER('application|infrastructure') },
+    },
+    {
+      name: 'domain-no-mira-afuera',
+      severity: 'error',
+      from: { path: CTX + 'domain/' },
+      to: { path: CTX + '(?:application|infrastructure|interfaces)/' },
+    },
+    {
+      name: 'application-sin-infraestructura',
+      comment: 'La aplicación no conoce adaptadores propios ni @archi-code/ddd/infrastructure.',
+      severity: 'error',
+      from: { path: CTX + 'application/' },
+      to: { path: [CTX + '(?:infrastructure|interfaces)/', ARCHI_LAYER('infrastructure')] },
+    },
+    {
+      name: 'interfaces-no-saltan-a-infraestructura',
+      comment:
+        'Los puntos de entrada llaman a casos de uso; no importan repositorios ni adaptadores. ' +
+        'Pueden importar HttpErrorMapper de @archi-code/ddd/infrastructure.',
+      severity: 'error',
+      from: { path: CTX + 'interfaces/' },
+      to: { path: CTX + 'infrastructure/' },
+    },
+    {
+      name: 'nadie-importa-composition',
+      comment: 'El composition root construye y conecta todo; ninguna capa lo importa.',
+      severity: 'error',
+      from: { path: CTX },
+      to: { path: CTX + 'composition\\.ts$' },
+    },
+    {
+      name: 'contextos-aislados',
+      comment: 'Un contexto no importa código de otro. Se integra por API, mensajes o shared-kernel acordado.',
+      severity: 'error',
+      from: { path: '^src/(?:app/)?contexts/([^/]+)/' },
+      to: {
+        path: '^src/(?:app/)?contexts/',
+        pathNot: '^src/(?:app/)?contexts/$1/', // $1 = contexto del fichero de origen
+      },
+    },
+    {
+      name: 'sin-ciclos',
+      severity: 'error',
+      from: {},
+      to: { circular: true },
+    },
+  ],
+  options: {
+    tsConfig: { fileName: 'tsconfig.json' },
+    // Imprescindible en TypeScript: sin esto se ignoran los imports usados solo como tipos
+    // (import type { AggregateSaver } ...), y un dominio que importa un tipo prohibido pasaría.
+    tsPreCompilationDeps: true,
+    doNotFollow: { path: 'node_modules' },
+    // Resolver los subpaths del campo "exports" del paquete (@archi-code/ddd/domain, etc.).
+    enhancedResolveOptions: {
+      exportsFields: ['exports'],
+      conditionNames: ['import', 'require', 'node', 'default', 'types'],
+    },
+  },
+};

package/ddd-skills/ddd-arquitectura/references/estilos-adicionales.md

@@ -0,0 +1,51 @@
+# Estilos adicionales: cuándo sí y cuándo no
+
+Ninguno es obligatorio. Úsalos cuando mitiguen un riesgo con alta probabilidad de causar fallo si se ignora [IDDD cap. 4]. Destilado los presenta como combinables con puertos y adaptadores según las necesidades [Destilado cap. 2].
+
+## CQRS
+
+**Problema que resuelve:** las pantallas cruzan muchos agregados y consultarlas desde repositorios obliga a juntar varios agregados en DTOs, a crear buscadores especiales o a empobrecer la interfaz para que siga los límites de los agregados [IDDD cap. 4].
+
+**Cómo es:** un modelo de comandos (los agregados, que ejecutan comportamiento) y un modelo de consultas (vistas desnormalizadas) actualizado por suscriptores a eventos [IDDD cap. 4]. Con el paquete, cada suscriptor es un `EventListener` con `@ListensTo(OrderPlaced, { consumer: '...' })` suscrito al `DomainEventBus`, que escribe la tabla de lectura y salta un `eventId` que ya aplicó (la entrega es al menos una vez). Reconstruir una vista desde el principio necesita un registro de eventos propio: un `EventChannel` no guarda historial legible. `[Fuera de los libros: convención de @archi-code/ddd]`
+
+**Cuándo no:** si la interfaz no es compleja ni cruza a menudo varios agregados en una vista, CQRS añade complejidad accidental [IDDD cap. 4].
+
+**Paso intermedio** `[Fuera de los libros]`: consultas de lectura que van directas a la base de datos con SQL o vistas, sin pasar por repositorios ni agregados, en la misma base. Ya separa lectura y escritura sin eventos ni consistencia eventual. Suele bastar. La consulta es una interfaz de `application/` que devuelve DTOs, implementada en `infrastructure/` sobre la base (`MongoOrderSummaries`), nunca con `AggregateFinder`:
+
+```ts
+export interface OrderSummary {
+  readonly id: string;
+  readonly customerId: string;
+  readonly lines: number;
+}
+
+export interface OrderSummaries {
+  ofCustomer(customerId: CustomerId, page: { limit: number; offset: number }): Promise<OrderSummary[]>;
+}
+```
+
+**Si el modelo de consultas es eventualmente consistente**, la interfaz debe asumir lo peor. Opciones de IDDD: mostrar temporalmente los datos enviados en el comando; mostrar la fecha y hora de los datos para que el usuario sepa su antigüedad; notificaciones push; o simplemente avisar de que la petición se procesará [IDDD cap. 4].
+
+Más detalle en `ddd-skills/ddd-event-sourcing-cqrs/GUIA.md`.
+
+## Arquitectura dirigida por eventos
+
+Contextos que se comunican publicando y consumiendo eventos de dominio. Es la base de la integración robusta descrita en `ddd-skills/ddd-context-mapping/GUIA.md` y del diseño de `ddd-skills/ddd-eventos-dominio/GUIA.md`. Dentro de un contexto, los eventos también desacoplan efectos secundarios del caso de uso: el caso de uso llama a `events.publish(order.pullDomainEvents())` después de `await this.orders.save(order)` y un listener (`PrepareShipmentOnOrderLineAdded`) ejecuta la acción siguiente.
+
+Con el paquete, la tecnología es un `EventChannel` del proyecto (`RabbitMqEventChannel`, un relay que entrega el outbox que el repositorio escribió junto al agregado…) bajo el mismo `DomainEventBus`; en tests, `InMemoryEventChannel`. Hacia otros contextos no viaja `event.toJSON()` de la clase de dominio: el adaptador que habla con el broker lo traduce a un contrato publicado y versionado (`sales.order.OrderPlaced`) [IDDD cap. 13], algo que el paquete no da y escribe el proyecto. `[Fuera de los libros: convención de @archi-code/ddd]`
+
+## Event Sourcing
+
+El estado de un agregado se guarda como la secuencia de sus eventos y se reconstruye aplicándolos [Destilado cap. 6; IDDD cap. 4]. Aporta historial completo y auditoría, pero cambia por completo la persistencia y las consultas. Ver `ddd-skills/ddd-event-sourcing-cqrs/GUIA.md` antes de decidir.
+
+El paquete no trae event store: cada repositorio guarda el `toPrimitives()` del agregado junto a su `version`, que crece 1 por cada `save`, no por evento. Un agregado con Event Sourcing sigue extendiendo `AggregateRoot` y registrando con `record()`, pero su repositorio (en `infrastructure/`, implementando `AggregateFinder`/`AggregateSaver`) lleva la versión del flujo él mismo y reconstruye el agregado aplicando sus eventos, no con `toPrimitives()`/`fromPrimitives()`. `[Fuera de los libros: convención de @archi-code/ddd]`
+
+## Tabla de decisión
+
+| Situación | Recomendación |
+|---|---|
+| Pantallas simples que siguen a un agregado | Solo hexagonal |
+| Listados y búsquedas que cruzan agregados | Consultas SQL directas de solo lectura |
+| Vistas muy distintas del modelo, alto volumen de lectura, otra base para leer | CQRS con read models por eventos |
+| Requisito legal o de negocio de historial completo de cambios del agregado | Valorar Event Sourcing en ese agregado |
+| Integración entre contextos | Eventos de dominio por un `EventChannel` de mensajería, traducidos a un contrato publicado |

package/ddd-skills/ddd-arquitectura/references/estructura-hexagonal-ts.md

@@ -0,0 +1,352 @@
+# Estructura hexagonal en TypeScript
+
+## Estructura base (un contexto por carpeta)
+
+`[Fuera de los libros: traslado a TypeScript de las estructuras de IDDD cap. 9 y PHP: Modules]`
+
+```
+src/
+  contexts/
+    sales/                         ← Bounded Context (nombre del modelo, no del producto comercial)
+      domain/
+        order/                     ← módulo del lenguaje ubicuo
+          Order.ts                 (agregado raíz: extends AggregateRoot<OrderId, OrderEvent>)
+          OrderId.ts               (extends IdType<'OrderId'>)
+          OrderLine.ts             (Composite({ sku: Sku, quantity: Quantity, unitPrice: Money }))
+          OrderLines.ts            (Composite({ items: [OrderLine] }) con sus reglas)
+          OrderStatus.ts           (Required(StatusType), StatusType extends EnumType<Status>)
+          Sku.ts, Quantity.ts      (Required(StringType) / Required(NumberType) + @Validations)
+          ShippingAddress.ts       (Composite({ street: Street, city: City, country: Country }))
+          events.ts                (OrderPlaced, OrderLineAdded, OrderConfirmed…: extends EventBase)
+          errors.ts                (OrderNoLongerEditable extends DomainException, código ORD001)
+        customer/
+          CustomerId.ts
+        pricing/
+          ProductPricing.ts        (puerto hacia Catálogo, ver ddd-skills/ddd-context-mapping/GUIA.md)
+        shared/                    ← solo para este contexto
+          Money.ts                 (Composite({ amount: Cents, currency: Currency }))
+      application/
+        place-order/
+          PlaceOrder.ts            (extends UseCase)
+        add-order-line/
+          AddOrderLine.ts
+        prepare-shipment/
+          PrepareShipment.ts
+          PrepareShipmentOnOrderLineAdded.ts   (listener junto al caso de uso que ejecuta)
+          Warehouse.ts             (puerto de salida de aplicación)
+        order-summaries/
+          OrderSummaries.ts        (consulta de lectura: interfaz + DTOs)
+      infrastructure/
+        persistence/
+          MongoOrderRepository.ts  (AggregateFinder/AggregateSaver/AggregateRemover<Order>; constructor solo con la collection; guarda order.toPrimitives() con su version y carga con Order.fromPrimitives(row); cada save/remove es atómico)
+          MongoOrderSummaries.ts
+        catalog/                   (ACL hacia Catálogo: CatalogHttpProductPricing, CatalogTranslator)
+        warehouse/
+          HttpWarehouse.ts
+        messaging/
+          RabbitMqEventChannel.ts  (implements EventChannel)
+      interfaces/
+        http/
+          ordersRouter.ts
+        messaging/
+          StockReservedConsumer.ts (traduce el contrato publicado por Almacén al input de un caso de uso)
+      composition.ts               ← composition root del contexto
+    warehouse/
+      ...
+  shared-kernel/                   ← solo si hay un Shared Kernel acordado (ver ddd-skills/ddd-context-mapping/GUIA.md)
+  main.ts                          ← arranque del proceso
+test/
+  support/
+    in-memory-order-repository.ts     (doble de test: AggregateFinder/AggregateSaver/AggregateRemover<Order>, constructor vacío)
+  contexts/sales/
+    domain/                        (tests unitarios y de aceptación del modelo)
+    application/                   (casos de uso con InMemoryOrderRepository, InMemoryEventChannel)
+    infrastructure/                (integración con BD real o contenedor)
+```
+
+Lo que no aparece porque lo da `@archi-code/ddd`: clases base (`AggregateRoot`, `Entity`, `EventBase`, los tipos de value object, `Composite`), una interfaz `OrderRepository` (los roles `AggregateFinder`, `AggregateSaver` y `AggregateRemover` vienen de `@archi-code/ddd/domain`), un `OrderMapper` (la conversión es del agregado, `toPrimitives()` y `static fromPrimitives()`, y cada repositorio los llama directamente: guarda `order.toPrimitives()` con `order.version + 1` y carga con `Order.fromPrimitives(row).restoreVersion(row.version)`), un publicador de eventos (`DomainEventBus` implementa `EventBus`) y el puerto `Clock`. Tampoco hay un runner de transacciones ni una unidad de trabajo: la transacción es del repositorio `[Fuera de los libros: convención de @archi-code/ddd]`.
+
+Lo que el paquete no da y escribe el proyecto: cada repositorio, uno por agregado. Su constructor recibe solo las dependencias de su tecnología (la `collection` de Mongo, el `pool` de Postgres), nunca la clase del agregado ni un mapper; el agregado solo entra y sale por sus métodos. Nada comprueba en ejecución la forma del agregado: que su estado sean value objects expuestos por getters y que `toPrimitives()`/`fromPrimitives()` no pierdan campos lo garantizan el agregado y su test de ida y vuelta. El repositorio en memoria también es del proyecto y es un doble de test: vive en `test/support/`, nunca en `src/` (ver `InMemoryOrderRepository` en `ddd-skills/ddd-repositorios-persistencia/references/tests-repositorios.md`) `[Fuera de los libros: convención de @archi-code/ddd]`.
+
+Decisiones:
+* Los tests de aceptación del modelo están junto al contexto, aunque en carpeta `test/` espejo [Destilado cap. 2 pide tenerlos con el código del contexto; la carpeta espejo mantiene esa correspondencia].
+* `domain/shared/` es compartido **dentro** del contexto y solo guarda conceptos del modelo (`Money`). Nada de un `shared/` global con modelos de varios contextos.
+* Un listener vive en el módulo del caso de uso que ejecuta, no en una carpeta `listeners/`.
+* El composition root vive por contexto para que cada contexto se pueda desplegar por separado si un día hace falta.
+
+## Variante para proyectos con la lógica en `src/app/`
+
+Algunos proyectos fijan `src/app/` para la lógica principal, `tests/` en raíz y `docs/` para las decisiones, y piden no crear carpetas raíz nuevas sin justificación `[Fuera de los libros]`. La estructura DDD encaja así:
+
+```
+src/
+  app/
+    contexts/
+      sales/ (domain, application, infrastructure, interfaces, composition.ts)
+      warehouse/
+    main.ts
+  prompts/      (si el proyecto usa IA; nunca dentro del dominio)
+config/
+tests/
+  contexts/sales/...
+```
+
+Reglas de encaje:
+* El logger es el puerto `Logger` de `@archi-code/ddd/application` (`debug`, `info`, `warn`, `error`, cada uno con un mensaje estable y un contexto). Lo reciben por constructor `application`, `infrastructure` e `interfaces`; el proveedor (`ConsoleLogger` del paquete, o un adaptador sobre pino, winston…) se elige en el composition root. El dominio no registra logs: registra eventos (`record`) o lanza una `DomainException` con nombre y código. `[Fuera de los libros: convención de @archi-code/ddd]`
+* Las variables de entorno se leen en el composition root y llegan a los adaptadores como configuración tipada. Nunca `process.env` fuera de ahí.
+* Los prompts de IA (si los hay) son infraestructura o aplicación; un modelo de lenguaje es un adaptador detrás de un puerto con nombre de negocio.
+
+## Puertos y adaptadores
+
+| Tipo | Ejemplo en el contexto de Ventas | Dónde se define la interfaz | Dónde se implementa |
+|---|---|---|---|
+| Entrada (driving) | HTTP `POST /orders`, consumidor de `StockReserved` | El caso de uso es la API de entrada (`execute(input)`) | `interfaces/` |
+| Salida de dominio | `AggregateFinder<Order>`, `AggregateSaver<Order>` (del paquete); `ProductPricing` (tuyo) | `@archi-code/ddd/domain`; `domain/` | `infrastructure/` (`MongoOrderRepository`, `CatalogHttpProductPricing`) |
+| Salida de aplicación | `EventBus`, `Clock`, `Logger` (del paquete); `Warehouse` (tuyo) | `@archi-code/ddd/application`; `application/` | `DomainEventBus` sobre tu `EventChannel`, `SystemClock`, `ConsoleLogger` o tu adaptador; `HttpWarehouse` |
+
+En IDDD los puertos no se implementan "a mano": el puerto es HTTP o el bus de mensajes, y el adaptador es el controlador o el listener que traduce a la API de aplicación [IDDD cap. 4]. El interior se diseña por casos de uso, no por número de clientes [IDDD cap. 4].
+
+Con el paquete, una tecnología de mensajería solo implementa `EventChannel` (`send` y `receive`); `DomainEventBus`, los casos de uso y los listeners no cambian. `[Fuera de los libros: convención de @archi-code/ddd]`
+
+## Composition root sin contenedor
+
+```ts
+// src/contexts/sales/composition.ts
+import { MongoClient } from 'mongodb';
+import {
+  DomainEventBus,
+  EventRegistry,
+  HttpErrorMapper,
+  SystemClock,
+} from '@archi-code/ddd/infrastructure';
+import { OrderLineAdded, OrderPlaced } from './domain/order/events';
+import type { MoneyData, OrderEvent, OrderLineData } from './domain/order/events';
+import { PlaceOrder } from './application/place-order/PlaceOrder';
+import { AddOrderLine } from './application/add-order-line/AddOrderLine';
+import { PrepareShipment } from './application/prepare-shipment/PrepareShipment';
+import { PrepareShipmentOnOrderLineAdded } from './application/prepare-shipment/PrepareShipmentOnOrderLineAdded';
+import { MongoOrderRepository } from './infrastructure/persistence/MongoOrderRepository';
+import type { OrderDocument } from './infrastructure/persistence/MongoOrderRepository';
+import { HttpWarehouse } from './infrastructure/warehouse/HttpWarehouse';
+import type { HttpClient } from './infrastructure/warehouse/HttpWarehouse';
+import { RabbitMqEventChannel } from './infrastructure/messaging/RabbitMqEventChannel';
+import type { AmqpChannel } from './infrastructure/messaging/RabbitMqEventChannel';
+import { ordersRouter } from './interfaces/http/ordersRouter';
+import type { Logger } from '@archi-code/ddd/application';
+
+export interface SalesConfig {
+  mongoUrl: string;
+  warehouseBaseUrl: string;
+}
+
+export async function composeSales(
+  config: SalesConfig,
+  deps: { amqp: AmqpChannel; http: HttpClient; logger: Logger },
+) {
+  const mongo = await new MongoClient(config.mongoUrl).connect();
+  const orders = new MongoOrderRepository(mongo.db().collection<OrderDocument>('orders'));
+  const clock = new SystemClock();
+
+  const registry = new EventRegistry<OrderEvent>()
+    .register(
+      OrderPlaced,
+      (json) =>
+        new OrderPlaced(
+          json.aggregateId,
+          json.customerId as string,
+          json.lines as OrderLineData[],
+          json.total as MoneyData,
+          json,
+        ),
+    )
+    .register(
+      OrderLineAdded,
+      (json) =>
+        new OrderLineAdded(
+          json.aggregateId,
+          json.sku as string,
+          json.quantity as number,
+          json.unitPrice as MoneyData,
+          json.total as MoneyData,
+          json,
+        ),
+    );
+  const bus = new DomainEventBus<OrderEvent>(
+    new RabbitMqEventChannel(deps.amqp),
+    registry,
+    deps.logger,
+  );
+
+  const placeOrder = new PlaceOrder(orders, bus, clock);
+  const addOrderLine = new AddOrderLine(orders, bus, clock);
+  const prepareShipment = new PrepareShipment(
+    new HttpWarehouse(deps.http, config.warehouseBaseUrl),
+  );
+
+  const subscriptions = [
+    await bus.subscribe(new PrepareShipmentOnOrderLineAdded(prepareShipment)),
+  ];
+
+  return {
+    httpRouter: ordersRouter(
+      { placeOrder, addOrderLine },
+      new HttpErrorMapper({ statusByCode: { ORD001: 409 }, logger: deps.logger }),
+    ),
+    close: async () => {
+      await Promise.all(subscriptions.map((subscription) => subscription.unsubscribe()));
+      await mongo.close();
+    },
+  };
+}
+```
+
+Qué hace cada pieza:
+* Del paquete, en `@archi-code/ddd/infrastructure`: `EventRegistry` (reconstruye cada evento desde su JSON; la factoría pasa el JSON como metadata para conservar `eventId` y `occurredOn`), `DomainEventBus` (implementa `EventBus`, lo único que reciben los casos de uso; su `subscribe(listener)` solo lo llama el composition root), `SystemClock` (implementa `Clock`) y `HttpErrorMapper` (códigos propios como `ORD001` se sobrescriben por código).
+* Código del proyecto sobre los puertos del paquete `[Fuera de los libros: convención de @archi-code/ddd]`: `MongoOrderRepository` (roles de repositorio de `Order`; su constructor recibe solo la `collection`; llama a `order.toPrimitives()` y a `Order.fromPrimitives(row).restoreVersion(row.version)` y controla la `version`; responsable de toda la persistencia: cada `save`/`remove` es una escritura atómica de un documento, y si un agregado ocupara varias tablas SQL abriría y cerraría la transacción de la base de datos dentro de `save`/`remove`; ver `ddd-skills/ddd-repositorios-persistencia/GUIA.md`), `RabbitMqEventChannel` (implementa `EventChannel`, ver `ddd-skills/ddd-eventos-dominio/GUIA.md`) y `HttpWarehouse` (implementa el puerto `Warehouse`).
+* Cada listener se suscribe con `bus.subscribe(listener)`, que lee su `@ListensTo(OrderLineAdded, { consumer: 'prepare-shipment-on-order-line-added' })` y rechaza un evento que el registro no sabe reconstruir.
+* Cambiar RabbitMQ por un outbox o por memoria cambia solo la línea del canal.
+* Ni los casos de uso ni los repositorios reciben un runner de transacciones: el composition root no construye ninguno.
+
+Por qué sin contenedor: en TypeScript las interfaces desaparecen en tiempo de ejecución y los contenedores necesitan tokens o decoradores. Para la mayoría de contextos, construir el grafo a mano es más legible y no mete decoradores de inyección en el dominio `[Fuera de los libros]`. Si usas NestJS, sus módulos y proveedores van en `interfaces/` e `infrastructure/`; el dominio sigue sin decoradores salvo `@Validations` de `@archi-code/validation` en los value objects.
+
+## El mismo grafo en los tests de aplicación
+
+Los tests de `application/` montan el contexto con el repositorio en memoria del proyecto (`test/support/in-memory-order-repository.ts`) y los adaptadores en memoria del paquete; los casos de uso y los listeners son los mismos (`test/contexts/sales/application/salesForTests.ts`):
+
+```ts
+import {
+  DomainEventBus,
+  EventRegistry,
+  FixedClock,
+  InMemoryEventChannel,
+} from '@archi-code/ddd/infrastructure';
+import { InMemoryOrderRepository } from '../../../support/in-memory-order-repository';
+import { OrderLineAdded } from '@sales/domain/order/events';
+import type { MoneyData, OrderEvent } from '@sales/domain/order/events';
+import { AddOrderLine } from '@sales/application/add-order-line/AddOrderLine';
+import { PlaceOrder } from '@sales/application/place-order/PlaceOrder';
+import { PrepareShipment } from '@sales/application/prepare-shipment/PrepareShipment';
+import { PrepareShipmentOnOrderLineAdded } from '@sales/application/prepare-shipment/PrepareShipmentOnOrderLineAdded';
+import type { Warehouse } from '@sales/application/prepare-shipment/Warehouse';
+
+export async function salesForTests(warehouse: Warehouse) {
+  const orders = new InMemoryOrderRepository();
+  const channel = new InMemoryEventChannel();
+  const registry = new EventRegistry<OrderEvent>().register(
+    OrderLineAdded,
+    (json) =>
+      new OrderLineAdded(
+        json.aggregateId,
+        json.sku as string,
+        json.quantity as number,
+        json.unitPrice as MoneyData,
+        json.total as MoneyData,
+        json,
+      ),
+  );
+  const bus = new DomainEventBus<OrderEvent>(channel, registry);
+  await bus.subscribe(new PrepareShipmentOnOrderLineAdded(new PrepareShipment(warehouse)));
+  const clock = new FixedClock('2026-03-01T09:30:00Z');
+  return {
+    orders,
+    channel,
+    placeOrder: new PlaceOrder(orders, bus, clock),
+    addOrderLine: new AddOrderLine(orders, bus, clock),
+  };
+}
+```
+
+El test comprueba lo que causó el listener (el `Warehouse` de prueba) y lo que llevó el canal (`channel.sent`), nunca que el listener fue llamado. `InMemoryOrderRepository` (cada `save` y `remove` atómico, con comprobación de versión) es un doble de test del proyecto: vive en `test/support/` y nunca se usa en producción `[Fuera de los libros: convención de @archi-code/ddd]`.
+
+## Controlador como adaptador de entrada
+
+```ts
+// src/contexts/sales/interfaces/http/ordersRouter.ts
+import { Router } from 'express';
+import type { Response } from 'express';
+import type { HttpErrorMapper } from '@archi-code/ddd/infrastructure';
+import type { AddOrderLine } from '../../application/add-order-line/AddOrderLine';
+import type { PlaceOrder } from '../../application/place-order/PlaceOrder';
+
+export function ordersRouter(
+  useCases: { placeOrder: PlaceOrder; addOrderLine: AddOrderLine },
+  errors: HttpErrorMapper,
+): Router {
+  const router = Router();
+
+  const fail = (res: Response, error: unknown) => {
+    const { status, body } = errors.map(error);
+    return res.status(status).json(body);
+  };
+
+  router.post('/orders', async (req, res) => {
+    const body = req.body as {
+      lines?: unknown;
+      shippingAddress?: { street?: unknown; city?: unknown; country?: unknown };
+    } | null;
+    const address = body?.shippingAddress;
+    if (
+      !Array.isArray(body?.lines) ||
+      typeof address?.street !== 'string' ||
+      typeof address.city !== 'string' ||
+      typeof address.country !== 'string'
+    ) {
+      return res
+        .status(400)
+        .json({ code: 'BAD_REQUEST', message: 'lines and shippingAddress are required' });
+    }
+    try {
+      const orderId = await useCases.placeOrder.execute({
+        customerId: req.auth.customerId,
+        lines: body.lines,
+        shippingAddress: { street: address.street, city: address.city, country: address.country },
+      });
+      return res.status(201).location(`/orders/${orderId}`).json({ orderId });
+    } catch (error) {
+      return fail(res, error);
+    }
+  });
+
+  router.post('/orders/:orderId/lines', async (req, res) => {
+    const body = req.body as {
+      sku?: unknown;
+      quantity?: unknown;
+      unitPrice?: { amount?: unknown; currency?: unknown };
+    } | null;
+    if (
+      typeof body?.sku !== 'string' ||
+      typeof body.quantity !== 'number' ||
+      typeof body.unitPrice?.amount !== 'number' ||
+      typeof body.unitPrice.currency !== 'string'
+    ) {
+      return res
+        .status(400)
+        .json({ code: 'BAD_REQUEST', message: 'sku, quantity and unitPrice are required' });
+    }
+    try {
+      await useCases.addOrderLine.execute({
+        orderId: req.params.orderId,
+        sku: body.sku,
+        quantity: body.quantity,
+        unitPrice: { amount: body.unitPrice.amount, currency: body.unitPrice.currency },
+      });
+      return res.status(204).json(null);
+    } catch (error) {
+      return fail(res, error);
+    }
+  });
+
+  return router;
+}
+```
+
+El controlador no sabe qué es un `Order`. Comprueba solo la forma de la petición (un campo es texto o número) [IDDD cap. 4]; las reglas de cada valor son de los value objects que `toCommand` construye con `ValueObjects.build`, y llegan como una `ValidationException` con todos los campos (422). La identidad del cliente sale del token, no del body. `HttpErrorMapper` traduce los errores: 404 `AggregateNotFoundException`, 403 `NotAllowedException`, 409 `ConcurrencyException`, 422 `ValidationException` y cualquier otra `DomainException`, 500 con un mensaje genérico para lo demás. Con `logger`, el mapper registra cada 5xx una vez como `error` (con su causa) y los 4xx solo en `debug`; el controlador no vuelve a registrarlos.
+
+## Configuración de TypeScript
+
+`[Fuera de los libros]`
+* `strict: true`. El dominio se apoya en el tipado para expresar invariantes.
+* `experimentalDecorators: true`: `@Validations` (value objects) y `@ListensTo` (listeners) son decoradores de clase.
+* `moduleResolution` `node16`, `nodenext` o `bundler` para resolver los subpaths `@archi-code/ddd/domain`, `/application`, `/infrastructure` y `/exceptions`; con `node` los resuelve el `typesVersions` del paquete.
+* Alias por contexto (`"@sales/*": ["src/contexts/sales/*"]`, usado como `@sales/domain/order/Order`) para que los imports revelen la zona.
+* `exactOptionalPropertyTypes` y `noUncheckedIndexedAccess` ayudan a que los value objects no acepten estados a medias.

package/ddd-skills/ddd-arquitectura/references/modulos.md

@@ -0,0 +1,48 @@
+# Módulos
+
+## Qué son
+
+En DDD, un módulo es un contenedor con nombre para clases del dominio muy cohesionadas entre sí, buscando bajo acoplamiento con las de otros módulos. No es un cajón genérico: su nombre forma parte del lenguaje ubicuo [IDDD cap. 9]. Deben contar la historia del sistema y reflejar conocimiento del dominio [IDDD cap. 9, citando a Evans].
+
+## Reglas
+
+* Nombres del lenguaje ubicuo [IDDD cap. 9; PHP: Modules].
+* Nunca nombres de patrones o piezas (`valueobjects`, `services`, `entities`) [PHP: Modules].
+* Lo de dentro, lo menos acoplado posible con otros módulos [PHP: Modules].
+* Refactoriza módulos como el código: muévelos, renómbralos, agrúpalos [IDDD cap. 9; PHP: Modules].
+* Nada de nombres comerciales de producto: cambian. Usa el nombre del contexto [IDDD cap. 9; PHP: Modules].
+* El segundo nivel identifica el Bounded Context, luego la zona (`domain`, `application`...), luego los módulos del modelo [IDDD cap. 9].
+* En aplicación e interfaz, submódulos solo si hay suficientes servicios o recursos para que ayude (IDDD sugiere pensarlo a partir de media docena) [IDDD cap. 9].
+
+## Módulo antes que Bounded Context
+
+Si la terminología es difusa y no está claro que haga falta una frontera de contexto, mantén los conceptos juntos y sepáralos con un módulo, que es una frontera más fina. Los contextos no sustituyen a los módulos; los módulos separan lo poco cohesionado dentro de un mismo lenguaje [IDDD cap. 9].
+
+Y en sentido contrario: un módulo no arregla un lenguaje mezclado. Si un término significa dos cosas, hace falta otro contexto [IDDD cap. 2].
+
+## En TypeScript
+
+`[Fuera de los libros]`
+* Un módulo es una carpeta con un `index.ts` que exporta solo su API pública. Lo demás no se importa desde fuera del módulo.
+* Un agregado y todo lo que solo él usa viven en el mismo módulo: `Order`, `OrderId`, `OrderLine` (un `Composite`), `OrderStatus`, sus eventos (`OrderPlaced`, `OrderLineAdded`) y sus excepciones de negocio (`OrderNoLongerEditable extends DomainException`).
+* Las clases base (`AggregateRoot`, `EventBase`, `Composite`, los tipos de value object) y los roles de repositorio (`AggregateFinder`, `AggregateSaver`, `AggregateRemover`) no forman un módulo del proyecto: se importan de `@archi-code/ddd/domain` donde se usan. `[Fuera de los libros: convención de @archi-code/ddd]`
+* En `application/`, un módulo por acción de negocio (`place-order/`, `add-order-line/`); el listener vive en el módulo del caso de uso que ejecuta (`prepare-shipment/PrepareShipmentOnOrderLineAdded.ts`), nunca en una carpeta `listeners/`.
+* Si dos módulos se importan mutuamente, el modelo está enredado: revisa los conceptos antes de mover ficheros.
+
+Ejemplo bueno y malo:
+
+```
+domain/                      domain/
+  order/                       entities/
+    Order.ts                     Order.ts
+    OrderLine.ts                 Invoice.ts
+    events.ts                  valueobjects/
+  invoicing/                     Money.ts
+    Invoice.ts                   OrderLine.ts
+  shared/                      events/
+    Money.ts                     OrderPlaced.ts
+                               shared/
+                                 AggregateRoot.ts
+(cuenta la historia)         (cuenta los patrones usados y
+                              reescribe lo que da el paquete)
+```