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

package/ddd-skills/archi-code-ddd/what-not-to-do.md

@@ -0,0 +1,189 @@
+# What not to do
+
+Part of the `archi-code-ddd` skill: read it only when that skill routes here.
+
+- Putting a class in the wrong layer: a repository implementation, a mapper or a driver in the
+  domain; a listener or an event bus implementation in the domain; a use case importing
+  `/infrastructure`; business rules in an adapter or a controller.
+- A use case that imports, extends or calls another use case, or a base use case with shared
+  helpers: move the rule to the aggregate or a domain service, or chain them with an event and a
+  listener.
+- Building value objects inside `handle` from raw input, or passing raw strings to aggregates
+  from a use case: build them in `toCommand`.
+- A listener without `@ListensTo`, decorated with two events, or one that holds business rules,
+  saves aggregates or calls several use cases.
+- A listener consumer name taken from the class (`ListensTo(X, { consumer: this.name })`), shared by
+  two listeners or renamed casually: it is the listener's identity in the channel (its queue in a
+  broker), so it must be a stable literal, unique per listener.
+- Subscribing listeners by a text name or calling them from a use case: the composition root
+  subscribes them with `bus.subscribe(listener)`, which reads their `@ListensTo`.
+- Declaring `eventName()` as a method in an event: declare `static readonly eventName`.
+- Importing the repository contracts from `@archi-code/ddd/application`: they live in `/domain`.
+- Do not invent API: there is no root `@archi-code/ddd` import, no `toPrimitives()` in the base
+  classes, no generic `ValueObject` (a value object of several fields is `Composite({...})`), no
+  `setNow()`, `addItem()`, `setItem()` or `removeItem()`. When in doubt, check the installed
+  README.
+- Writing the suite's base classes in the project (`domain/shared/AggregateRoot.ts`,
+  `DomainEvent.ts`, `ValueObject.ts`, an `EventPublisher` port): they come from the package.
+- A computed getter (`get total()`, `get isEditable()`) on an aggregate, a child entity or a
+  composite: `PrimitiveTypes` takes it for a field and `toPrimitives()` stops compiling; write a
+  method.
+- `ArrayType<OrderLine>` with a composite item: a list of composites is a `Composite` list field
+  (`Composite({ items: [OrderLine] })`) or a `OrderLine[]` field of the aggregate.
+- A domain service or a repository received by the constructor of an aggregate: pass the service
+  or the loaded data as a method argument.
+- Events named `OrderUpdated` carrying the whole state, named in present tense (`PlaceOrder` as an
+  event), carrying value objects, `toPrimitives()` or personal data that consumers do not need.
+- Creating an event inside an aggregate method without the clock it received
+  (`new OrderPlaced(id.value, customer.value)`): `occurredOn` becomes the system time and tests stop
+  being deterministic.
+- A registry factory that does not pass the JSON as metadata
+  (`(json) => new OrderShipped(json.aggregateId)`): the event gets a new `eventId`, a listener
+  cannot skip a redelivery, and `fromJSON` throws.
+- Subscribing a listener of an event the `EventRegistry` does not know: `bus.subscribe` refuses it
+  with `UnknownEventException`; register every event a listener receives.
+- Writing a second bus for a new technology (a `RabbitMqEventBus` with its own `publish` and
+  subscriptions): implement only `EventChannel` and keep `DomainEventBus`, so listeners and use
+  cases behave the same on every channel.
+- A use case run by a listener that throws `AggregateNotFoundException` or a business error: the
+  channel redelivers it forever; return, or record an event that compensates.
+- Retrying a `ConcurrencyException` with the same loaded aggregate, without a limit, or for a
+  command that is not safe to repeat: each attempt loads again and saves again, and only for
+  commands safe to repeat. A use case never calls itself nor another use case to retry, and one run
+  by a listener never retries: the channel's redelivery tries again.
+- A read query that loads aggregates through `AggregateFinder`, or a repository method that
+  returns DTOs: reads go straight to the database through an application interface.
+- Importing `@archi-code/ddd/infrastructure` from domain code, or `application` from the domain.
+- Importing an exception from `@archi-code/ddd/domain`: exceptions live in
+  `@archi-code/ddd/exceptions`.
+- Catching errors inside `handle` just to rethrow them as `ApplicationException`: let them
+  propagate; `execute` keeps package exceptions and wraps the rest.
+- Calling `bus.publish` before `repository.save`, or publishing without `pullDomainEvents()`.
+- Opening, joining or closing transactions in a use case, a listener or the domain, or passing a
+  transaction runner, unit of work, session or connection to them: the repository makes each
+  `save`/`remove` atomic and handles everything about persistence.
+- Saving two aggregates in one use case without one of the exceptions IDDD ch. 10 accepts,
+  written down as a decision: one use case saves one aggregate once.
+- Changing the use case so events are not lost between `save` and `publish`: the repository stores
+  them with the aggregate in the same atomic write (an outbox) and a relay delivers them.
+- A listener that breaks when a channel delivers the same event twice: delivery is at least once;
+  skip an `eventId` already processed.
+- Sending `event.toJSON()` of a domain event to another context: translate it to a published,
+  versioned contract.
+- Changing the data of a stored or published event without raising `eventVersion` (or the
+  contract version).
+- Repository methods with business names or rules (`pendingOlderThan`, `findOverdueInvoices`),
+  `nextId()` in a repository, or a use case returning the aggregate to the controller.
+- Throwing `AggregateNotFoundException` from the domain or a repository: the use case throws it when
+  `findById` returns `null`; it is an application exception (404).
+- Authorization checks in the aggregate, or business rules in a controller: authorization is the
+  use case's (`NotAllowedException`, 403); business rules are the aggregate's.
+- A controller, consumer or CLI importing a repository or an adapter: entry points only call use
+  cases; the composition root wires everything.
+- Folders named after patterns (`entities/`, `services/`, `valueobjects/`): name modules after the
+  business (`order/`, `invoicing/`).
+- A use case that does several things (`UpdateOrder` that ships, cancels or renames depending on
+  the input) or that saves more than one aggregate outside the IDDD ch. 10 exceptions written down
+  as an explicit decision: split it into one use case per business action.
+- Technical or CRUD names for use cases (`OrderService`, `UpdateUser`, `SaveOrder`,
+  `ProcessPayment` when the business says `CapturePayment`): name them after the business action.
+- Declaring an all-in-one `Repository` interface in the project, or a use case that receives the
+  three roles when it only reads or only saves: ask for exactly the roles it uses.
+- Looking for helpers such as `findOrFail` or `saveAndPublish` in `UseCase`: there are none; the
+  steps go in `handle`.
+- Using `new Date()` inside use cases or aggregates: inject a `Clock`.
+- An in-memory repository in `src/` or used in production: it lives in `test/support/`.
+- `vo.toString` without parentheses: it is a method; use `vo.toString()`, `` `${vo}` `` or
+  `vo.value`.
+- Mutating a VO or its value (`vo.value.setFullYear(...)`, pushing to `vo.value`): values are frozen
+  and date setters throw. Build a new VO; for arrays use `withItem`/`withoutItem` and keep the
+  returned instance (`this._tags = this._tags.withItem('x')`).
+- Ignoring what `withItem`/`withoutItem` return: the original does not change.
+- Comparing VOs or entities with `===`: use `equals()`.
+- Calling `assertValid()`: it does not exist; the constructor already throws `ValidationException`.
+- Building the value objects of an input one after another with `new` in `toCommand`: the first
+  invalid field hides the rest. Use `ValueObjects.build` so every field is reported.
+- Moving a value object's rule to the request schema or the controller (`isEmail` in a DTO
+  validator instead of the `Email` value object): the adapter may check format for the user
+  (empty, length) [IDDD ch. 4], but the value object owns the rule and always checks it.
+- Catching the `ValidationException` of a value object to keep an invalid value, or creating
+  `ValidationException` by hand from `validate()` results (a domain service that collects
+  `ValidationIssue`s of an existing object may throw `new ValidationException(issues)`).
+- Sending local date-times without a zone (`'2024-01-31T10:00:00'`) to `DateType`: they are rejected.
+- Passing unconverted values with their static type (`new NumberType('1.5')`): type error; conversion
+  is for `any`/`unknown` input.
+- Using `Required(StringType)` directly as a property type instead of a named subclass.
+- Declaring `private readonly _id` + `get id()` in an aggregate: the id goes to `super(id)`.
+- An optional value object (`class Code extends StringType {}`) as the id of an entity or
+  aggregate: an id is always required (`IdType` or `Required(...)`); an empty id throws
+  `RequiredValueException`.
+- Removing by id without loading the aggregate, or a `remove` with no version condition: `remove`
+  receives the loaded aggregate and refuses a stale one with `ConcurrencyException`.
+- Putting listeners or event ports under `application/ports/` or a separate listener folder of the
+  package API: the event contract (`EventListener`, `@ListensTo`, `EventBus`) is imported from
+  `@archi-code/ddd/application`.
+- Importing `DomainEventBus`, `EventRegistry`, `EventChannel`, `ChannelHandler`,
+  `ChannelSubscription` or `Subscription` from `@archi-code/ddd/application`, or using them in a use
+  case or a listener: they are infrastructure (`@archi-code/ddd/infrastructure`), used only by the
+  composition root and by channel implementations.
+- A child entity as a plain class, with setters, or called from outside its aggregate: it extends
+  `Entity<Id>`, holds value objects, and its business methods are called only by its root.
+- Modeling an amount with its currency, a date range or an address as loose fields of the
+  aggregate, as a `JsonType`, or as a child entity with an id nobody looks up: use `Composite`.
+- `Required(Composite(...))`, or `Composite({ amount: Required(NumberType) })` without a named
+  class: every field class is a named subclass, and every field instance must be given (an
+  optional value object holding `null` is fine; an optional composite is a `Money | null` field of
+  the aggregate).
+- Mutating a composite or adding state to it (instance fields, setters): it is frozen; return a new
+  instance from its methods.
+- Returning a composite from `toPrimitives()` instead of `composite.toPrimitives()`.
+- A specification that loads data through a repository, a generic one without a business name
+  (`FieldEquals`), or one used instead of the aggregate to protect an invariant.
+- Raw state in an aggregate (`private _shipped: boolean`, `private _at: Date`, a `string` field):
+  wrap it in a value object.
+- A private field without its public getter, or left out of `toPrimitives()`: it compiles and is
+  lost when saving (`PrimitiveTypes` does not see private fields, and nothing checks them at run
+  time); the round-trip test of each aggregate must cover every field.
+- `toPrimitives()` returning value objects instead of `vo.value`.
+- A repository that reads aggregate fields or builds rows by hand: call `order.toPrimitives()` and
+  `Order.fromPrimitives(row)`.
+- Importing a persistence concern (a repository, a driver, a mapper) into domain code: it belongs to
+  infrastructure.
+- A repository whose constructor receives an aggregate class, a mapper or
+  `{ toPrimitives, fromPrimitives }`: it receives only its technology (a collection, a pool) and
+  calls the aggregate's own methods.
+- A generic repository shared by several aggregates: write one per aggregate.
+- Converting an aggregate to or from primitives outside the aggregate (a domain service, a
+  hand-written mapper reading its fields): the aggregate owns `toPrimitives()` and
+  `static fromPrimitives()`.
+- Declaring a `version` field in an aggregate, or putting it in `toPrimitives()`: the base already
+  has it, and the repository stores it next to the primitives.
+- A repository (also the in-memory one of the tests) that saves with `upsert` and no version
+  condition, or "last save wins": a stale save must throw `ConcurrencyException`.
+- Forgetting `markPersisted()` after a successful write (the next save of the same object becomes a
+  false conflict), or `Order.fromPrimitives(row)` without `.restoreVersion(storedVersion)` (every load looks
+  new, and the first save conflicts).
+- Calling `restoreVersion()` or `markPersisted()` from domain or application code: they are for
+  repositories.
+- Creating events without the aggregate id (`super()`), or generating `eventId`/`occurredOn`
+  yourself for a new event: the base does it.
+- Wrapping or translating an error (`InternalErrorException`, `ConcurrencyException`,
+  `NotAllowedException`, `AggregateNotFoundException`) without `{ cause: error }`.
+- `JsonType` with `{}` or with an array: throws `TypePrimitiveException` (it must be a non-empty
+  object).
+- `IdType` with `00000000-0000-0000-0000-000000000000` or `ffffffff-ffff-ffff-ffff-ffffffffffff`:
+  throws `TypePrimitiveException`.
+- An id class without its brand (`class OrderId extends IdType {}`): it compiles, but a `CustomerId`
+  is then accepted where an `OrderId` is expected. Write `class OrderId extends IdType<'OrderId'> {}`.
+- Declaring an aggregate's VOs as `private` without getters and expecting `PrimitiveTypes` to see
+  them.
+- Calling `record()` from outside the aggregate (it is `protected`) or forgetting `super(...)` in the
+  constructor of an aggregate or event.
+- Importing `@Validations` from `@archi-code/ddd/domain`: it is imported from `@archi-code/validation`.
+- Logging from the domain, or importing a logging library (pino, winston, `console`) in a use case:
+  inject the `Logger` port and choose the provider in the composition root.
+- Logging an error and rethrowing it in every layer: the edge that handles it logs it once
+  (`HttpErrorMapper` and `DomainEventBus` with a logger already do).
+- Interpolating data into the message (`` `order ${id} failed` ``) or logging passwords, tokens or
+  personal data that the entry does not need: keep a stable message and put only what is needed in
+  the context.

package/ddd-skills/archi-code-ddd/where-each-class-goes.md

@@ -0,0 +1,63 @@
+# Where each class goes
+
+Part of the `archi-code-ddd` skill: read it only when that skill routes here.
+
+| Class                                                        | Layer                                   | May depend on                                                                             | Never                                                                      |
+| ------------------------------------------------------------ | --------------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| Value object, composite                                      | domain                                  | other value objects, `@archi-code/validation`, exceptions                                 | mutate, know about storage or transport                                    |
+| Aggregate root (`extends AggregateRoot`)                     | domain                                  | value objects, child entities, events; a domain service or loaded data as method argument | read a repository, publish, `new Date()`, services received by constructor |
+| Child entity (`extends Entity`)                              | domain                                  | its local id, value objects, business methods the root calls                              | setters, being called from outside the root, loaded or saved on its own    |
+| Domain event (`OrderPlaced`)                                 | domain                                  | primitives taken from value objects                                                       | behavior, value objects or the whole state in its payload                  |
+| Repository contract (`AggregateFinder`…)                     | domain                                  | the aggregate                                                                             | business logic or queries, an all-in-one `Repository`                      |
+| Domain service                                               | domain                                  | aggregates, value objects, specifications, repository contracts (to read), domain ports   | I/O code, transactions, publishing                                         |
+| Domain port to another context or service (`ProductPricing`) | domain                                  | value objects                                                                             | remote DTOs, I/O code                                                      |
+| Use case (`PlaceOrder`)                                      | application                             | domain, ports, exceptions                                                                 | import another use case or a listener, return an aggregate                 |
+| Listener (`ReserveStockOnOrderPlaced`)                       | application                             | one use case (by constructor), the event                                                  | business rules, saving aggregates, calling several use cases               |
+| Port (`EventBus`, `Clock`, `Logger`, your own) | application                             | domain types                                                                              | code                                                                       |
+| Read query (`OrderSummaries`, `StaleOrders`)                 | application (interface), infrastructure | DTOs and ids, `@archi-code/criteria`                                                      | loading aggregates, repositories, business rules                           |
+| Adapter (repository, event channel, ACL translator, logger provider) | infrastructure                          | domain, application, exceptions, drivers                                                  | business rules                                                             |
+| Event wiring (`DomainEventBus`, `EventRegistry`, `EventChannel` port and its implementations) | infrastructure (composition root) | `@archi-code/ddd/infrastructure`, domain events, listeners                     | being seen by use cases (they only see `EventBus`) or listeners             |
+| Entry point (controller, consumer, scheduler, CLI)           | interfaces                              | application, exceptions, `HttpErrorMapper`; domain types only if unavoidable              | business rules, repositories or other adapters                             |
+| Composition root (`composition.ts`)                          | per context                             | everything                                                                                | being imported by any layer                                                |
+
+- Dependencies only point inwards: the domain imports only `@archi-code/ddd/domain`,
+  `@archi-code/ddd/exceptions` and `@archi-code/validation` (not "nothing external" as the suite
+  says: these are the package convention); the application adds `@archi-code/ddd/application`;
+  only infrastructure and the composition root import `@archi-code/ddd/infrastructure`, with one
+  exception: an entry point may import `HttpErrorMapper` (or receive it from the composition root).
+  Entry points (`interfaces/`: controllers, message consumers, schedulers, CLI) call use cases
+  only. The composition root of each context is the only place that builds and connects everything
+  (repositories, event channel, `DomainEventBus`, `EventRegistry`, listeners) and reads
+  `process.env`. `DomainEventBus`, `EventRegistry` and the `EventChannel` port come from
+  `@archi-code/ddd/infrastructure`; a use case sees only `EventBus` and a listener only
+  `EventListener` + `@ListensTo`, both from `@archi-code/ddd/application`.
+- Layout, with modules named after the ubiquitous language inside each zone, never after patterns
+  (`entities/`, `events/`, `valueobjects/`, `listeners/`); a listener lives next to the use case it
+  runs; a context never imports another one, only an explicit `shared-kernel/`:
+
+  ```
+  src/contexts/sales/
+  ├── domain/order/            Order, OrderId, OrderLine, OrderPlaced, ProductPricing (port)
+  ├── application/
+  │   ├── place-order/         PlaceOrder
+  │   ├── reserve-stock/       ReserveStock, ReserveStockOnOrderPlaced
+  │   └── order-summaries/     OrderSummaries (read query)
+  ├── infrastructure/
+  │   ├── persistence/         MongoOrderRepository, MongoOrderSummaries
+  │   ├── messaging/           RabbitMqEventChannel
+  │   └── catalog/             HttpProductPricing, CatalogTranslator (ACL)
+  ├── interfaces/http/         OrderController
+  └── composition.ts
+  ```
+
+- Check the direction with dependency-cruiser (`tsPreCompilationDeps: true`) and the suite's
+  `ddd-skills/ddd-arquitectura/assets/dependency-cruiser.cjs`, which already allows the `@archi-code/ddd`
+  layers above and forbids importing `composition.ts`.
+- Import from the layer, never from the package root (there is none): exceptions always come from
+  `@archi-code/ddd/exceptions` (never from `/domain`).
+- Logic two use cases share never goes in a use case: a business rule becomes a method of the
+  aggregate or a domain service; a technical step becomes a port. When an action must follow
+  another, the first records an event and a listener runs the second.
+- Names: use cases are business verbs (`PlaceOrder`), events are facts in the past
+  (`OrderPlaced`, never `OrderUpdated` nor present tense), listeners are `<Action>On<Event>`
+  (`ReserveStockOnOrderPlaced`, where `<Action>` is the use case it runs).

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

@@ -0,0 +1,114 @@
+# Agregados
+
+> 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.** Diseño e implementación de agregados DDD en TypeScript, la guía central del diseño táctico. Cubre las cuatro reglas (proteger invariantes reales dentro del límite, agregados pequeños, referencias por identidad, consistencia eventual fuera del límite), el procedimiento para dimensionar agregados según los plazos de consistencia, la heurística de "¿de quién es el trabajo?", cuándo está justificado romper las reglas, la raíz del agregado, partes como value objects, fábricas, concurrencia optimista, registro de eventos de dominio y tests. Consúltala siempre que haya que decidir qué objetos van juntos, qué se guarda en una transacción, por qué hay conflictos de concurrencia o bloqueos, si un objeto debe contener una colección de otro, cómo coordinar cambios en varias entidades, o cuando aparezca un objeto enorme que carga medio modelo, aunque no se diga "agregado".
+
+## Con @archi-code/ddd
+
+[Fuera de los libros: convención de @archi-code/ddd]
+
+* La raíz no se escribe: extiende `AggregateRoot<Id, Event>` y llama a `super(id)`; la `version` de la concurrencia optimista está en la base, fuera del estado del agregado, y solo la tocan los repositorios (`restoreVersion()` al cargar, `markPersisted()` tras escribir).
+* Todo el estado son value objects, composites o entidades hijas con getter público; constructor privado, una factoría de negocio y `fromPrimitives`, y `toPrimitives()` con datos planos (las seis reglas de `layers.md`).
+* Las identidades nuevas salen del value object (`OrderId.generate()`), no del repositorio.
+* Los métodos del dominio reciben `clock: { now(): Date }` y lo pasan a los eventos (`{ clock }`).
+* La variante funcional (estado inmutable + funciones que devuelven `[estado, eventos]`) no la da el paquete: necesita clases `AggregateRoot` y `PrimitiveTypes`.
+* El agregado registra sus eventos con `record()` y el caso de uso, tras `await this.orders.save(order)`, los publica con `events.publish(order.pullDomainEvents())`. La aplicación no abre transacciones: la transacción es del repositorio, que hace atómico cada `save`; si un evento no puede perderse, el repositorio lo guarda con el agregado en la misma escritura (outbox) y un proceso aparte lo entrega por un `EventChannel`.
+* Una política se parte en un listener `<Acción>On<Evento>` con `@ListensTo` y el caso de uso que ejecuta.
+
+Un agregado es un grupo de entidades y value objects con una entidad raíz que lo nombra y lo controla, y que forma un **límite de consistencia transaccional**: al confirmar la transacción, todo lo de dentro cumple las reglas del negocio [Destilado cap. 5]. No es un grafo de objetos cómodo de navegar; es una decisión sobre consistencia [IDDD cap. 10].
+
+
+## Las cuatro reglas
+
+[Destilado cap. 5; IDDD cap. 10]
+
+1. **Protege las invariantes reales dentro del límite.** Una invariante es una regla que debe cumplirse siempre, de forma inmediata y atómica. Es negocio quien decide qué tiene que ser consistente al confirmar.
+2. **Diseña agregados pequeños.** Raíz y los mínimos atributos y value objects necesarios: todos los que deben ser consistentes entre sí, ninguno más. Un caso real que cita IDDD: en torno al 70 % de los agregados de un proyecto tenían solo la raíz con value objects, y el resto dos o tres entidades.
+3. **Referencia a otros agregados solo por su identidad.** `productId: ProductId`, nunca `product: Product`.
+4. **Actualiza otros agregados con consistencia eventual.** Un agregado publica un evento de dominio; un suscriptor modifica el otro en **otra** transacción.
+
+Corolario operativo: **una transacción modifica una sola instancia de agregado** [Destilado cap. 5; IDDD cap. 10]. Eso implica que cada petición de usuario debería ejecutar un comando sobre un agregado [IDDD cap. 10]. Con el paquete, esa transacción es una escritura atómica por agregado que garantiza el repositorio en su `save`; el caso de uso carga un agregado y lo guarda una vez `[Fuera de los libros: convención de @archi-code/ddd]`.
+
+## Flujo de diseño
+
+### Paso 1. Partir de los candidatos
+
+Lista los agregados candidatos con sus comandos y eventos: sustantivos del negocio con ciclo de vida que reciben comandos.
+
+### Paso 2. Dimensionar con el procedimiento de Vernon
+
+[Destilado cap. 5]
+
+1. Empieza con **un agregado por entidad**, cada uno solo con su raíz. Ponle lo necesario para identificarlo, encontrarlo y dejarlo en un estado inicial válido.
+2. Para cada agregado A1, lista qué otros agregados deben actualizarse cuando A1 cambia.
+3. Para cada reacción, fija **cuánto puede tardar**: inmediatamente, o en N segundos, minutos, horas o días.
+4. Lo que debe ser **inmediato**: considera fusionar ambas entidades en un único agregado.
+5. Lo que admite **plazo**: consistencia eventual con eventos de dominio.
+
+Desconfía de "inmediato" para todo: con usuarios concurrentes, un agregado grande falla en las transacciones y consume mucha memoria [Destilado cap. 5].
+
+### Paso 3. Desempatar con "¿de quién es el trabajo?"
+
+Si no está claro si algo es transaccional o eventual: si es trabajo **del usuario que ejecuta el caso de uso** dejar los datos consistentes, intenta consistencia transaccional (respetando las demás reglas). Si es trabajo de otro usuario o del sistema, eventual [IDDD cap. 10, guía atribuida a Evans].
+
+### Paso 4. Desconfiar de los casos de uso que tocan varios agregados
+
+Un caso de uso que pide modificar varios agregados en una transacción puede indicar una invariante que falta (y un concepto nuevo), o simplemente que el caso de uso debe reescribirse con consistencia eventual y un retraso aceptable. Cuidado con fusionar agregados y acabar en uno gigante [IDDD cap. 10].
+
+### Paso 5. Elegir bien la abstracción
+
+Modela el lenguaje ubicuo explícitamente. Nada de `ScrumElement` con un `typeName` para cubrir "todos los casos futuros": el lenguaje no coincide con el del negocio, aparecen casos especiales, sobra código y nunca se acierta con el futuro [Destilado cap. 5].
+
+### Paso 6. Implementar
+
+Guía completa en `ddd-skills/ddd-agregados/references/implementacion-ts.md`. Lo esencial:
+
+* La raíz tiene identidad global; las entidades internas solo identidad local [IDDD cap. 10].
+* Partes internas como **value objects** siempre que se puedan reemplazar enteras [IDDD cap. 10].
+* Comportamiento con nombres del lenguaje; sin setters públicos. Ley de Demeter y "Tell, Don't Ask": los clientes piden a la raíz que haga algo, no navegan por dentro [IDDD cap. 10].
+* **No inyectes repositorios ni servicios en el agregado.** Busca antes lo que necesite (en el servicio de aplicación) y pásaselo al método [IDDD cap. 10].
+* **Concurrencia optimista** con versión en la raíz [IDDD cap. 10]: la `version` de `AggregateRoot`, que el repositorio comprueba al guardar (`ConcurrencyException`).
+* El agregado **registra** sus eventos (`record`); el caso de uso los publica tras guardar con `events.publish(order.pullDomainEvents())` (ver `ddd-skills/ddd-eventos-dominio/GUIA.md`).
+* **Distingue comandos de hechos.** Un comando de usuario puede rechazarse con un error de negocio. Un método que registra un hecho ya ocurrido en otro agregado o contexto es idempotente y no lanza: si el hecho no encaja, registra un evento de negocio para que otra política compense [Destilado cap. 6]. Una excepción en un consumidor de mensajes provoca reintentos sin fin.
+* Creación con **fábricas**: método en la raíz de otro agregado cuando el nuevo nace de él (`customer.placeOrder(...)`), o servicio cuando la creación necesita traducir de otro contexto [IDDD cap. 11; PHP: Factories]. Ver `ddd-skills/ddd-agregados/references/fabricas.md`.
+
+### Paso 7. Coordinar agregados
+
+Consistencia eventual dentro y fuera del contexto: suscriptores (`EventListener` + caso de uso), reintentos, compensaciones y procesos. `ddd-skills/ddd-agregados/references/consistencia-eventual.md`.
+
+## Cuándo romper las reglas
+
+Solo con un buen motivo. IDDD cita cuatro [IDDD cap. 10]:
+
+| Motivo | Condición para que sea aceptable |
+|---|---|
+| Comodidad de interfaz: crear varios agregados en lote | Crear en lote no cambia nada semánticamente frente a crearlos de uno en uno; cada uno protege sus invariantes |
+| Falta de mecanismos técnicos (sin mensajería, temporizadores ni procesos en segundo plano) | Afinidad usuario-agregado (un solo usuario trabaja sobre ese conjunto) y concurrencia optimista |
+| Transacciones globales impuestas (dos fases) | Aun así, intenta no modificar varios agregados del propio contexto |
+| Rendimiento de consultas | Referencia directa a otro agregado, valorando el coste |
+
+## Señales de alarma
+
+* Un agregado con colecciones que crecen sin límite (`Product.backlogItems` con miles de elementos) [Destilado cap. 5; IDDD cap. 10].
+* Fallos frecuentes por concurrencia en un agregado concreto.
+* Propiedades que son otro agregado completo (`order.customer.address.city`).
+* Servicios de aplicación que guardan dos o más agregados en el mismo caso de uso "porque sí", o que reciben una dependencia `transactions`/`unitOfWork` para agruparlos.
+* Un agregado que recibe un repositorio por constructor.
+* Setters públicos o un `update(dto)` genérico [Destilado cap. 5].
+* Lógica de negocio en servicios de aplicación o en clases `Helper`/`Utils` [Destilado cap. 5].
+* Relaciones bidireccionales mantenidas solo por comodidad o por la versión de concurrencia [IDDD cap. 10].
+
+## Programación funcional
+
+Con un estilo funcional, separar datos y comportamiento no es anemia: el agregado es un tipo inmutable y las funciones devuelven un estado nuevo o un evento. Parte de esta guía orientada a objetos no aplica tal cual [Destilado cap. 5]. `ddd-skills/ddd-agregados/references/implementacion-ts.md` incluye una variante funcional escrita con los value objects y eventos del paquete; el paquete no da su base ni su persistencia `[Fuera de los libros: convención de @archi-code/ddd]`.
+
+## Ejemplo completo
+
+`ddd-skills/ddd-agregados/references/ejemplo-ecommerce.md` aplica el procedimiento de dimensionado a Pedido, Pago y Reserva de stock, con la tabla de reacciones y plazos; el código del agregado `Order` está en `ddd-skills/ddd-agregados/references/implementacion-ts.md` y la política que registra la reserva, en `ddd-skills/ddd-agregados/references/consistencia-eventual.md`.
+
+## Siguiente guía
+
+* Diseño, publicación y consumo de eventos → `ddd-skills/ddd-eventos-dominio/GUIA.md`.
+* Repositorio del agregado → `ddd-skills/ddd-repositorios-persistencia/GUIA.md`.
+* Casos de uso que cargan, invocan y guardan agregados → `ddd-skills/ddd-servicios-capa-aplicacion/GUIA.md`.

package/ddd-skills/ddd-agregados/references/consistencia-eventual.md

@@ -0,0 +1,159 @@
+# Consistencia eventual entre agregados
+
+## Mecanismo básico
+
+Un método de comando del agregado publica (o registra) un evento de dominio. Uno o varios suscriptores asíncronos lo reciben; cada uno carga **otro** agregado y ejecuta su comportamiento en **su propia transacción** [IDDD cap. 10; Destilado cap. 5]. Con el paquete, esa transacción es el `save` atómico del repositorio de ese otro agregado `[Fuera de los libros: convención de @archi-code/ddd]`.
+
+El suscriptor puede estar en el mismo contexto (en el ejemplo del libro, `Sprint` reacciona a `BacklogItemCommitted` creando un `CommittedBacklogItem`) o en otro. Para el mismo contexto no hace falta un middleware de mensajería, aunque es fácil usarlo si ya existe [Destilado cap. 5].
+
+## Fallos y reintentos
+
+* Si el suscriptor falla por concurrencia, no confirma el mensaje; el mecanismo lo reenvía y se reintenta en una nueva transacción (con el paquete, el caso de uso vuelve a cargar y a guardar en la nueva entrega; no reintenta por su cuenta), hasta lograrlo o hasta un límite de reintentos [IDDD cap. 10].
+* Si falla del todo: compensar o, como mínimo, informar del fallo para intervención [IDDD cap. 10]. Con el paquete, los reintentos y el límite son del `EventChannel` que implementes (por ejemplo, una cola con reintentos y una dead-letter donde quedan los mensajes que agotan el límite); `InMemoryEventChannel` no reintenta: el error del listener llega a quien llamó a `publish` `[Fuera de los libros: convención de @archi-code/ddd]`.
+* El suscriptor debe ser idempotente: la mensajería entrega al menos una vez [Destilado cap. 4].
+
+## No crear asociaciones bidireccionales
+
+El evento no está para mantener un puntero inverso sin sentido. En IDDD, `BacklogItem` ya conoce su `SprintId`; el evento sirve para que `Sprint` registre el compromiso con su propio orden, que es un concepto suyo [IDDD cap. 10].
+
+## Políticas: el nombre del lenguaje para "cuando pase X, haz Y"
+
+`[Fuera de los libros como término]`
+
+Con el paquete, la política se parte en un listener `<Acción>On<Evento>` (con `@ListensTo`) que solo traduce el evento a la entrada de un caso de uso, y ese caso de uso carga, invoca y guarda `[Fuera de los libros: convención de @archi-code/ddd]`. Política de Ventas: cuando Almacén reserva stock, se registra en el pedido (`Order`, `OrderId`, `ReservationId` y `OrderEvent` son los de `references/implementacion-ts.md`).
+
+El hecho de Almacén llega por el canal con su contrato publicado; Ventas declara una clase `EventBase` con ese contrato para que `DomainEventBus` lo reconstruya y se lo entregue al listener `[Fuera de los libros: convención de @archi-code/ddd]`:
+
+```ts
+import { EventBase } from '@archi-code/ddd/domain';
+import type { EventMetadata } from '@archi-code/ddd/domain';
+
+export class StockReserved extends EventBase {
+  static readonly eventName = 'warehouse.stock.StockReserved';
+
+  constructor(
+    stockItemId: string,
+    readonly orderId: string,
+    readonly reservationId: string,
+    metadata?: EventMetadata,
+  ) {
+    super(stockItemId, metadata);
+  }
+}
+```
+
+El caso de uso registra el hecho: un agregado, un `save` atómico, y si el pedido no existe (es de otro canal) vuelve sin error:
+
+```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 type { Clock, EventBus } from '@archi-code/ddd/application';
+
+interface StockReservationInput {
+  orderId: string;
+  reservationId: string;
+}
+
+interface StockReservationCommand {
+  orderId: OrderId;
+  reservationId: ReservationId;
+}
+
+export class RegisterStockReservation extends UseCase<
+  StockReservationInput,
+  StockReservationCommand,
+  void
+> {
+  constructor(
+    private readonly orders: AggregateFinder<Order> & AggregateSaver<Order>,
+    private readonly events: EventBus<OrderEvent>,
+    private readonly clock: Clock,
+  ) {
+    super();
+  }
+
+  protected toCommand(input: StockReservationInput): StockReservationCommand {
+    return ValueObjects.build({
+      orderId: () => new OrderId(input.orderId),
+      reservationId: () => new ReservationId(input.reservationId),
+    });
+  }
+
+  protected async handle(command: StockReservationCommand): Promise<void> {
+    const order = await this.orders.findById(command.orderId);
+    if (order === null) {
+      return;
+    }
+    order.registerStockReservation(command.reservationId, this.clock);
+    await this.orders.save(order);
+    await this.events.publish(order.pullDomainEvents());
+  }
+}
+```
+
+El listener solo traduce el evento a la entrada del caso de uso:
+
+```ts
+import { EventListener, ListensTo } from '@archi-code/ddd/application';
+
+@ListensTo(StockReserved, { consumer: 'register-stock-reservation-on-stock-reserved' })
+export class RegisterStockReservationOnStockReserved extends EventListener<StockReserved> {
+  constructor(private readonly registerStockReservation: RegisterStockReservation) {
+    super();
+  }
+
+  async handle(event: StockReserved): Promise<void> {
+    await this.registerStockReservation.execute({
+      orderId: event.orderId,
+      reservationId: event.reservationId,
+    });
+  }
+}
+```
+
+La raíz de composición registra el evento y suscribe el listener; en los tests, con los adaptadores en memoria del paquete y el `InMemoryOrderRepository` que el proyecto escribe en `test/support/` (`ddd-skills/ddd-repositorios-persistencia/references/tests-repositorios.md`). En `test/contexts/sales/application/register-stock-reservation.spec.ts`:
+
+```ts
+import {
+  DomainEventBus,
+  EventRegistry,
+  FixedClock,
+  InMemoryEventChannel,
+} from '@archi-code/ddd/infrastructure';
+import { InMemoryOrderRepository } from '../../../support/in-memory-order-repository';
+
+const orders = new InMemoryOrderRepository();
+const registry = new EventRegistry<OrderEvent | StockReserved>().register(
+  StockReserved,
+  (json) =>
+    new StockReserved(json.aggregateId, json.orderId as string, json.reservationId as string, json),
+);
+const channel = new InMemoryEventChannel();
+const bus = new DomainEventBus<OrderEvent | StockReserved>(channel, registry);
+await bus.subscribe(
+  new RegisterStockReservationOnStockReserved(
+    new RegisterStockReservation(orders, bus, new FixedClock('2026-03-01T09:30:00Z')),
+  ),
+);
+```
+
+En producción se cambia solo el canal (`InMemoryEventChannel` por el de tu broker o tu outbox); los casos de uso y los listeners no cambian.
+
+Reglas para políticas:
+* Una política, un agregado modificado.
+* Nombre con el lenguaje del negocio, no `StockReservedHandler`. Con el paquete, el listener se llama `<Acción>On<Evento>`, donde `<Acción>` es el caso de uso que ejecuta (`RegisterStockReservationOnStockReserved`), y su `consumer` es un nombre estable y único, nunca el de la clase.
+* La regla de negocio está en el agregado; la política solo lo invoca.
+* El método invocado no lanza errores de negocio (ver "Comandos frente a hechos" en `references/implementacion-ts.md`). Los errores técnicos (base de datos caída, `ConcurrencyException`) sí se propagan para que la mensajería reintente.
+* El listener es idempotente: si el canal entrega dos veces el mismo `eventId`, el segundo no cambia nada (aquí lo garantiza el agregado, que ignora una reserva cuando ya no está pendiente).
+
+## Plazos y lo que ve el usuario
+
+Si el plazo aceptado es "en 30 segundos", el sistema debe comportarse bien durante esos 30 segundos:
+* Estados intermedios explícitos en el modelo (`Pending`) [IDDD cap. 3 trata la indisponibilidad como estado válido].
+* Mensajes al usuario que reflejen el estado ("Estamos confirmando tu pedido").
+* Un temporizador o rastreador de plazo para el caso en que no llegue nunca (ver procesos en `ddd-skills/ddd-context-mapping/GUIA.md`).
+
+## Procesos con varios pasos
+
+Cuando hay varios agregados y plazos, un objeto de proceso con su propio estado (confirmación del pedido: esperando reserva y pago, confirmado, fallido, caducado) coordina los pasos [IDDD cap. 13]. Ese objeto es en sí un agregado pequeño: se modifica solo, en su transacción, al recibir cada evento.

package/ddd-skills/ddd-agregados/references/ejemplo-ecommerce.md

@@ -0,0 +1,52 @@
+# Ejemplo: dimensionar los agregados de la tienda online
+
+## Paso 1. Un agregado por entidad
+
+Candidatos: `Order` (Ventas), `Payment` (Pagos), `StockItem` con sus reservas (Almacén), `Shipment` (Almacén), `Customer` (Ventas).
+
+## Pasos 2 y 3. Reacciones y plazos
+
+| Cuando cambia | Debe reaccionar | Plazo aceptado |
+|---|---|---|
+| Order realizado | StockItem reserva | 1 minuto |
+| Order realizado | Payment autoriza | 1 minuto |
+| StockItem reservado + Payment autorizado | Order confirmado | 30 segundos |
+| Order cancelado | StockItem libera reserva | 10 minutos |
+| Shipment enviado | Payment captura | 1 día |
+| Order realizado | Customer: "último pedido" para marketing | 1 día |
+| Línea de pedido cambia | Total del pedido | **Inmediato** |
+
+## Pasos 4 y 5. Decisión
+
+* Líneas y total: inmediato → dentro de `Order` (como value objects).
+* Todo lo demás admite plazo → agregados separados y consistencia eventual.
+* "Último pedido" del cliente: no se toca `Customer` en la transacción del pedido; es una proyección para marketing.
+
+Prueba con "¿de quién es el trabajo?": confirmar el pedido no es trabajo del cliente que compra, sino del sistema cuando llegan reserva y pago → eventual. Por eso no hay un comando "confirmar" que alguien invoque (`order.confirm(authorization)`), sino un pedido que se confirma solo al registrar las dos condiciones.
+
+## Resultado
+
+```mermaid
+flowchart LR
+  subgraph Ventas
+    O["Order<br/>(raíz + OrderLines + ShippingAddress<br/>+ stockReservation + PaymentAuthorization)"]
+    C["Customer"]
+  end
+  subgraph Almacén
+    S["StockItem<br/>(raíz + reservas)"]
+    SH["Shipment"]
+  end
+  subgraph Pagos
+    P["Payment"]
+  end
+  O -- OrderPlaced --> S
+  O -- OrderPlaced --> P
+  S -- StockReserved --> O
+  P -- PaymentAuthorized --> O
+  O -- OrderCancelled --> S
+  SH -- ShipmentDispatched --> P
+```
+
+`StockItem` sí agrupa sus reservas: la invariante "no reservar más unidades de las disponibles" es inmediata y la protege él. Si un mismo `StockItem` sufre muchos conflictos de concurrencia en campañas, la alternativa es partir el stock por almacén o por lote, no meter pedidos dentro.
+
+El código de `Order` (sobre `AggregateRoot<OrderId, OrderEvent>`, con `OrderLines`, `ShippingAddress` y `PaymentAuthorization` como `Composite`) está en `ddd-skills/ddd-agregados/references/implementacion-ts.md`. Cada flecha que llega a `Order` es un listener `<Acción>On<Evento>` que ejecuta un caso de uso (`RegisterStockReservationOnStockReserved` → `RegisterStockReservation`, y lo mismo para `PaymentAuthorized` → `RegisterPaymentAuthorization`); el primero está escrito en `ddd-skills/ddd-agregados/references/consistencia-eventual.md`.