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

package/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: archi-code-ddd
+description: The single entry point for Domain-Driven Design with @archi-code/ddd. It routes every DDD question to the guide suite shipped in the package (integration between contexts, architecture, value objects and entities, aggregates, domain events, repositories, application services, event sourcing and CQRS, audits) and gives the rules, patterns and common mistakes for TypeScript code with @archi-code/ddd - where each class goes and what it may import, value objects, Composite, Specification, Entity, AggregateRoot, EventBase, repository roles, exceptions, UseCase, the event contract (EventListener, @ListensTo, DomainEventBus, event channels), ports, persistence owned by the repository and HttpErrorMapper. Use it whenever someone applies DDD, designs or reviews a domain model, integrates contexts, writes or changes value objects, aggregates, events, use cases, listeners, repositories or adapters, decides which layer a class belongs to, or whenever the code imports @archi-code/ddd.
+---
+
+# archi-code-ddd
+
+`@archi-code/ddd` is archi-code's Domain-Driven Design package for TypeScript, one entry point per
+layer: `@archi-code/ddd/exceptions` (the exceptions every layer throws), `@archi-code/ddd/domain`
+(value objects, `Composite`, `Immutable`, `Specification`, `Entity`, `AggregateRoot`, `EventBase`
+and the repository contracts `AggregateFinder`, `AggregateSaver`, `AggregateRemover`),
+`@archi-code/ddd/application` (`UseCase`, the event contract to listen, `EventListener` and
+`@ListensTo`, and to publish, `EventBus`, and the ports `Clock`, `Logger`) and
+`@archi-code/ddd/infrastructure` (aggregate mapper for your repositories, the
+event wiring `DomainEventBus`, `EventRegistry` and the `EventChannel` port, in-memory event
+channel, HTTP error mapper, clocks, loggers).
+
+## Full API
+
+Before using a class, function, option or type that does not appear in this skill, read
+`node_modules/@archi-code/ddd/README.md`: it matches the installed version. Do not assume
+signatures, options or exports. If the package is not installed: `npm install @archi-code/ddd`
+(and `npm install @archi-code/validation` if validations are declared with `@Validations`).
+
+If that path does not exist (monorepo with workspaces, pnpm…), locate the package with
+`node -p "require.resolve('@archi-code/ddd/package.json')"` and read the `README.md` in that
+folder.
+
+## The DDD guide suite
+
+This is the **only skill to load** for Domain-Driven Design with this package. It brings a suite
+of DDD guides (in Spanish, with the source of each rule: Vernon's _Implementing Domain-Driven
+Design_ and _Domain-Driven Design Distilled_, and _DDD in PHP_) inside the package, in
+`ddd-skills/`; never copy the suite into `.claude/skills/`: read it from the package when this
+skill says so. Locate it as the README: `node_modules/@archi-code/ddd/ddd-skills/`, or the
+`ddd-skills/` folder next to the `package.json` that
+`node -p "require.resolve('@archi-code/ddd/package.json')"` prints (in this monorepo,
+`packages/ddd/ddd-skills/`). Each guide is a folder with a `GUIA.md` (no skill frontmatter), its
+`references/` and, when it has them, `assets/` (tool configuration) and `scripts/`: they are never loaded
+on their own, only read when this skill routes to them. Paths inside the guides (`ddd-skills/ddd-agregados/GUIA.md`) are relative to the package
+folder.
+
+How to use it, for every design question or task:
+
+1. **Start at `ddd-skills/ddd-orquestador/GUIA.md`**: it says which guide covers each coding task
+   (integration between contexts, architecture, classes, aggregates, events, repositories, use
+   cases) and holds the conventions of the suite; read it for every task that is not a quick code
+   fix. Its `references/chuleta-reglas.md` has every essential rule with its source.
+2. **Read the `GUIA.md` of the matching guide** before answering, and the `references/` it points
+   to for the case at hand:
+
+   | Situation                                                              | Read `ddd-skills/…/GUIA.md`     |
+   | ---------------------------------------------------------------------- | ------------------------------- |
+   | Unclear request, "where do I start", the essential rules               | `ddd-orquestador`               |
+   | How contexts and external systems relate and integrate, ACL            | `ddd-context-mapping`           |
+   | Folder structure, layers, dependencies, modules, composition root      | `ddd-arquitectura`              |
+   | Value object or entity, ids, primitives, validation, Specification     | `ddd-value-objects-entidades`   |
+   | What goes together, invariants, transactions, concurrency, factories   | `ddd-agregados`                 |
+   | Events, messaging, outbox, idempotence, versions                       | `ddd-eventos-dominio`           |
+   | Loading and saving aggregates, mappers, transactions, repository tests | `ddd-repositorios-persistencia` |
+   | Domain services, use cases, where the logic goes, authorization        | `ddd-servicios-capa-aplicacion` |
+   | Full history, read models, CQRS, Event Sourcing                        | `ddd-event-sourcing-cqrs`       |
+   | Review or migrate existing code                                        | `ddd-auditoria-refactorizacion` |
+
+   A new project follows the orchestrator's sequence (architecture → aggregates and value objects →
+   events → repositories → use cases).
+
+3. **Design with the suite, write the code with this package.** The guides' examples are already
+   written with this package's API (the classes of its `src`): copy them as they are, never write
+   generic base classes (`ValueObject`, `Entity`, `AggregateRoot`, `DomainEvent`) of your own.
+   Every guide but the orchestrator opens with a "Con @archi-code/ddd" box that lists where it
+   diverges from the books, marked `[Fuera de los libros: convención de @archi-code/ddd]`. The
+   guides are the source of truth: the package departs from them only where that mark says so,
+   and then the package rule wins. Any other disagreement between a guide and this package
+   (`ddd-skills/archi-code-ddd/` or its code) is a defect of the package: follow the guide.
+4. **Audits of code built on this package** (`ddd-auditoria-refactorizacion`): apply its checklist
+   and also every item of `ddd-skills/archi-code-ddd/what-not-to-do.md`. Its scanner needs Python 3:
+   `python3 -I "$(dirname "$(node -p "require.resolve('@archi-code/ddd/package.json')")")/ddd-skills/ddd-auditoria-refactorizacion/scripts/scan_ddd_smells.py" <folder>`.
+   It flags a use case that saves two aggregates (`this.orders.save(…)` and `this.invoices.save(…)`
+   or `remove(…)`), transactions handled in the domain or the application (they belong to the
+   repository), domain code importing `@archi-code/ddd/application` or `/infrastructure`, and
+   `new Date()` in domain or application code; its findings are hints to confirm by reading the
+   code, and a use case that saves through a helper still needs a manual check. Without Python, apply the checklist by hand. For
+   the import direction, use `ddd-skills/ddd-arquitectura/assets/dependency-cruiser.cjs`.
+5. Keep the suite's conventions: say which rule comes from which book and mark what does not come
+   from them.
+
+If they are installed in the project, use them together with this one:
+
+- `archi-code-validation`: available validators, their options and `@Validations` rules.
+
+## Rules and patterns of this package
+
+The rules, patterns and common mistakes of `@archi-code/ddd` live next to the suite, in
+`ddd-skills/archi-code-ddd/` (located like the suite). They are part of this skill: read the file
+that matches the task before writing or reviewing code, and every file when unsure.
+
+| Read `ddd-skills/archi-code-ddd/…` | When                                                                                     |
+| ---------------------------------- | ---------------------------------------------------------------------------------------- |
+| `imports.md`                       | Which entry point exports each class, function and type                                  |
+| `where-each-class-goes.md`         | The layer of each class, what it may import, the folder layout and the names             |
+| `layers.md`                        | The rules of value objects, aggregates, events, use cases, listeners, ports and adapters |
+| `patterns.md`                      | Code to start from: value objects, aggregates, use cases, listeners, repositories, tests |
+| `what-not-to-do.md`                | The common mistakes; also the checklist of every audit of code built on this package     |

package/ddd-skills/archi-code-ddd/imports.md

@@ -0,0 +1,84 @@
+# Import
+
+Part of the `archi-code-ddd` skill: read it only when that skill routes here.
+
+```ts
+import {
+  AbstractType,
+  AggregateRoot,
+  ArrayType,
+  BooleanType,
+  Composite,
+  CreatedAt,
+  DateType,
+  Entity,
+  EnumType,
+  EventBase,
+  IdType,
+  JsonType,
+  NumberType,
+  Required,
+  Specification,
+  StringType,
+  UpdatedAt,
+  UuidType,
+  ValueObjects,
+} from '@archi-code/ddd/domain';
+import {
+  AggregateNotFoundException,
+  ApplicationException,
+  ConcurrencyException,
+  DomainException,
+  ExceptionCode,
+  InfrastructureException,
+  InternalErrorException,
+  NotAllowedException,
+  RequiredValueException,
+  TypePrimitiveException,
+  UnknownEventException,
+  ValidationException,
+} from '@archi-code/ddd/exceptions';
+import type { ValidationIssue } from '@archi-code/ddd/exceptions';
+import type {
+  AggregateFinder,
+  AggregateRemover,
+  AggregateSaver,
+  EntityId,
+  EventClass,
+  EventMetadata,
+  PrimitiveTypes,
+  SatisfiedBy,
+  SerializedEvent,
+} from '@archi-code/ddd/domain';
+import { EventListener, ListensTo, UseCase } from '@archi-code/ddd/application';
+import type {
+  Clock,
+  EventBus,
+  ListenerSubscription,
+  LogContext,
+  Logger,
+  LogLevel,
+} from '@archi-code/ddd/application';
+import {
+  ConsoleLogger,
+  DomainEventBus,
+  EventRegistry,
+  FixedClock,
+  HttpErrorMapper,
+  InMemoryEventChannel,
+  InMemoryLogger,
+  SilentLogger,
+  SystemClock,
+} from '@archi-code/ddd/infrastructure';
+import type {
+  ChannelHandler,
+  ChannelSubscription,
+  EventChannel,
+  Subscription,
+} from '@archi-code/ddd/infrastructure';
+import { Validations } from '@archi-code/validation';
+```
+
+```js
+const { Required, StringType } = require('@archi-code/ddd/domain');
+```

package/ddd-skills/archi-code-ddd/layers.md

@@ -0,0 +1,299 @@
+# Domain, application and infrastructure
+
+Part of the `archi-code-ddd` skill: read it only when that skill routes here.
+
+- Value objects are **optional by default** (`value: T | null`) `[Fuera de los libros: convención
+  de @archi-code/ddd]`: the books build every value object with a value and model an optional one
+  as a field that may be `null` (`reservation: ReservationId | null`) [IDDD ch. 5 and 6]; both
+  forms work here. `Required(XType)` makes them
+  required: the constructor demands `T` and, if it receives an empty value (`null`, `undefined` or a
+  blank string), throws `RequiredValueException` with the class name. `Required(...)` also declares
+  the `isRequired` validation. An id is always required (see the aggregate root below).
+- A domain VO is always a named subclass (`class Email extends ...`): the name appears in the error
+  messages, and `equals` compares the class too (`BillingCountry('ES')` is not a
+  `ShippingCountry('ES')`).
+- **A value object that exists is valid.** The constructor converts (or throws
+  `TypePrimitiveException`), checks `Required` (or throws `RequiredValueException`) and runs every
+  `@Validations` rule, throwing one `ValidationException` with all the broken rules
+  (`errors: [{ field: null, code: 'isEmail', message: '<Class>: <message>' }]`; `code` is the
+  validator or custom rule name, or the code of the exception). There is no `assertValid()`;
+  `validate()` only re-runs the rules and is always ok on a built VO.
+- **Report every field, never only the first.** Build the value objects of an input with
+  `ValueObjects.build({ field: () => new X(input.field), … })`: it runs every factory and throws one
+  `ValidationException` whose `errors` carry the `field` and `code` of each problem (required
+  `DOM004`, conversion `DOM003`, a rule name, or the code of any `DomainException`, such as your
+  `ORD003`); `ValueObjects.buildList(list, (item) => …)` names list items by position
+  (`lines.1.quantity`). It returns the command typed field by field. Factories are synchronous (one
+  that returns a Promise does not compile and is refused at run time with
+  `InternalErrorException`), and an error that is not a `DomainException` is a bug that wins over the
+  validation errors already collected.
+- **Which layer validates what:** the input adapter checks the shape and format of the request (it
+  parses, a field is a string, an empty field or a length for a good user experience [IDDD ch. 4]),
+  never a business rule, and that never replaces the value object; value objects check each value (built in
+  `toCommand`); the aggregate checks invariants over several values; a domain service checks rules
+  over several aggregates; the use case checks authorization. The input of a use case arrives
+  unvalidated on purpose: every adapter goes through it.
+- `@Validations` is imported from `@archi-code/validation`; a validator's parameters go in a single
+  `properties` object. Subclasses inherit validations, and one with the same name replaces the
+  parent's.
+- Values are **immutable**: `_value` is `readonly`; to change a value, build a new VO.
+  `ArrayType.withItem/withoutItem` return a new instance; `UpdatedAt` is replaced with
+  `UpdatedAt.now()`.
+- `toString()` is a method, `toJSON()` returns the plain value, `equals(other)` compares class and
+  value (dates by instant, arrays and objects by content). Template literals and `JSON.stringify`
+  work on VOs.
+- Dates: `DateType` accepts `Date`, ISO dates (`'2024-01-31'`, UTC midnight) and ISO date-times
+  **with** a zone (`Z` or offset); a date-time without a zone throws `TypePrimitiveException`.
+  `UuidType`/`IdType` store lowercase. New ids: `OrderId.generate()` (an `OrderId`). Every id class
+  passes its own name as the brand (`class OrderId extends IdType<'OrderId'> {}`) so the compiler never
+  takes a `CustomerId` for an `OrderId`.
+- Time: pass a `Clock` to `CreatedAt.now(clock)` / `UpdatedAt.now(clock)` and to events
+  (`new OrderPlaced(id, …, { clock })`) from use cases; tests use `FixedClock`. Aggregate methods
+  type it as `clock: { now(): Date }`: the `Clock` port matches it, and the domain never imports
+  `/application`.
+- A custom type extends `AbstractType<T>` and implements only `protected filter(value: unknown): T`
+  (it receives input already known to be non-empty; it returns the value or throws
+  `TypePrimitiveException`). If restricting an existing type is enough, extend it and use
+  `@Validations`; to normalize the value (trim, lower case) override `filter` and call
+  `super.filter(value)` first: `IdType` does the same, and the rules run on the normalized value.
+- **Concepts of several attributes are composite value objects**, not entities nor loose fields:
+  `class Money extends Composite({ amount: Cents, currency: Currency }) {}`. The schema names each
+  field's class: a value object class, another composite, or a list `[OrderLine]`. Fields are
+  exposed read-only with their value object type; the instance is frozen; `equals` compares class
+  and every field; `toPrimitives()` gives plain data (dates stay `Date`); `JSON.stringify` writes
+  the values; `X.fromPrimitives(data)` rebuilds it reporting every invalid field with its path
+  (`lines.1.quantity`). Rules over several fields (end ≥ start, one currency) are `@Validations`
+  `custom` rules on the composite class: `fn` receives the built composite, after its fields are
+  valid. Behavior returns new instances (`add(other): Money`). Prefer a composite over a child
+  entity: an order line with no id anybody looks it up by is a value [IDDD ch. 6]. A collection
+  with rules of its own (`OrderLines`: not empty, unique SKU, `total()`) is a composite with a list
+  field (`Composite({ items: [OrderLine] })`); `ArrayType` holds only simple value objects. A field
+  of a composite may hold an optional value object whose value is `null` (`new Line2(null)`); only
+  a missing instance is refused.
+- The aggregate root passes the id to `super(id)`, exposed as `readonly id`; do not redeclare it
+  (no `_id` + getter). `equals` compares class and id only. The id is a required value object
+  (`EntityId`: `IdType` or a `Required(...)` type); an optional type does not compile as `Id`, and an
+  id that holds no value throws `RequiredValueException`, so two new entities are never equal by an
+  empty id [IDDD ch. 5]. A child entity (a part with an identity
+  of its own inside the aggregate) extends `Entity<Id>` (`super(id)`, `equals` by class and id)
+  and holds its id and value objects; it may have business methods named after the language
+  (`seat.relabel(label)`) with the rules of that part, never setters, and only its root calls them
+  (Tell, Don't Ask: `room.relabelSeat(id, label)` finds the seat and tells it) [IDDD ch. 5 and
+  10]; rules over several parts stay in the root. Its identity is local: unique only inside its
+  aggregate, never used from outside [IDDD ch. 10] (`class SeatNumber extends Required(NumberType)`). `AggregateRoot` extends `Entity` too.
+- **Derived values are methods, never getters** (`total()`, `isEditable()`), on aggregates, child
+  entities and composites: `PrimitiveTypes` sees every getter as a field, so a computed getter
+  breaks `toPrimitives()` at compile time.
+- **A named business rule that selects, validates or combines is a `Specification<T>`**:
+  `class EligibleForExpressShipping extends Specification<Order> { isSatisfiedBy(order) {…} }`,
+  combined with `and`, `or` and `not`; `and`/`or` accept any `SatisfiedBy<T>` (an object with
+  `isSatisfiedBy`), the books' `Specification` interface [IDDD ch. 5]. It receives data already loaded (never a repository) and is
+  never used to protect an invariant of an aggregate: invariants stay inside the aggregate.
+- **The domain knows nothing about persistence**: no mapper, repository nor storage concern in
+  domain code; a repository receives an aggregate and stores it, calling the aggregate's own
+  `toPrimitives()` / `fromPrimitives()`.
+- **Aggregates and their primitives** (every aggregate follows these six rules so infrastructure can
+  store it; rules 1, 2, 4 and 5, and the name `fromPrimitives` of rule 3, are package conventions, `[Fuera de los libros: convención de
+  @archi-code/ddd]`: the books allow a primitive without behavior [IDDD ch. 6], getters only where
+  needed [Destilado ch. 5] and a mapper in infrastructure [IDDD ch. 6]):
+  1. All its state is value objects: each persisted field is a value object, a composite, a list
+     of them or a child entity (`extends Entity<Id>`) whose fields are value objects. A flag is
+     `class Shipped extends Required(BooleanType) {}`, never `boolean`; a moment is `DateType` /
+     `CreatedAt`, never `Date`.
+  2. Private field + public getter with the same name without `_` (or a public `readonly`). No
+     private state without its getter: the primitives use those names.
+  3. Private constructor and two factories: a business one that validates and records events, and
+     `static fromPrimitives(primitives: PrimitiveTypes<Order>)` that rebuilds each value object
+     from its primitive and records nothing.
+  4. `toPrimitives(): PrimitiveTypes<Order>` returns only plain data (`vo.value`, child primitives),
+     never a value object.
+  5. Repositories only call `order.toPrimitives()` and `Order.fromPrimitives(row)` (plus
+     `.restoreVersion(version)`); they never read the aggregate's fields. There is no mapper.
+  6. One round-trip test per aggregate: `Order.fromPrimitives(order.toPrimitives()).toPrimitives()`
+     equals `order.toPrimitives()`.
+     The compiler rejects public raw state (`PrimitiveTypes` gives `never`); nothing checks private
+     state at run time: a private field left out of `toPrimitives()` compiles and is lost when
+     saving, so rule 2 and the round-trip test of rule 6 are the aggregate's responsibility. An enum value object stores its option (`PrimitiveType` is the enum type),
+     so `new OrderStatus(primitives.status)` needs no cast.
+- Aggregates extend `AggregateRoot<Id, Event>` and call `super(id)`. **Every aggregate has a
+  `version`** for optimistic concurrency: `0` when new, the stored one when loaded, `+1` after each
+  save. The aggregate never declares, stores nor maps it (it is not a field nor in
+  `PrimitiveTypes`); only repositories touch it.
+- **Every repository checks the version** (contract): load with
+  `Order.fromPrimitives(row).restoreVersion(storedVersion)`; save a new aggregate (`version === 0`) as version 1
+  and treat an existing id as a conflict; save an existing one only where the stored version still
+  equals `aggregate.version`, storing `aggregate.version + 1` next to (never inside) the
+  primitives; when nothing was written throw
+  `ConcurrencyException('Order', id, aggregate.version)` (HTTP 409); after a write
+  call `aggregate.markPersisted()`. Keep the driver error: `ConcurrencyException(…, { cause })`.
+  Removing is a change too: `remove(aggregate)` receives the loaded aggregate and deletes only
+  where the stored version still equals `aggregate.version`, or throws `ConcurrencyException`
+  (someone changed or removed it after it was loaded) [IDDD ch. 10].
+  After a conflict, the use case may repeat its own work when the command is safe against the new
+  state [IDDD ch. 10; IDDD appendix A]: a loop in `handle` where each attempt loads the aggregate
+  again and saves it again (a few attempts, then rethrow); otherwise the conflict reaches the user
+  (409). A use case run by a listener does not retry by itself: the channel's redelivery tries
+  again.
+- `record(event)` is `protected` and deep-freezes the event (facts never change [IDDD ch. 8]); `pullDomainEvents()` returns the events (typed `Event[]`) in order
+  and empties the list. Pull them after persisting, to publish. `DomainEventBus.publish` does not freeze
+  them again: it only sends the `toJSON()` of each event to the channel.
+- Events extend `EventBase`, declare `static readonly eventName` with their class name, a fact in
+  the past tense (`'OrderPlaced'`) [IDDD ch. 8] (a published contract is named
+  `<context>.<module>.<Event>`, `sales.order.OrderPlaced` [IDDD ch. 13]) and
+  call `super(aggregateId, metadata)`; `event.eventName()` returns it. The payload is primitives
+  taken from value objects (`customer.value`, money as `{ amount, currency }`), only what
+  consumers need: never value objects, `toPrimitives()` nor personal data nobody needs. Listeners and registries refer to
+  the event by its class (`@ListensTo(OrderPlaced, { consumer: 'reserve-stock-on-order-placed' })`, `register(OrderPlaced, …)`). The
+  base sets `eventId` (UUID v4) and `occurredOn` (immutable `Date`, from `metadata.clock` when
+  given, otherwise the system time); pass `{ eventId, occurredOn }` only when rebuilding an event
+  a channel delivered. Inside an aggregate method, always pass the clock it received:
+  `new OrderPlaced(id.value, customer.value, { clock })`. Serialize with `JSON.stringify` /
+  `toJSON()` (`eventName`, `eventVersion`, `eventId`, `aggregateId`, ISO `occurredOn` and the
+  payload).
+- `PrimitiveTypes<T>` only sees **public** non-method members (it strips the leading `_`): expose
+  VOs with public getters or public `readonly` properties. For an aggregate it includes `id`;
+  child entities become their primitives; raw `string`/`number`/`boolean`/`Date`
+  members become `never`.
+- Where to throw each exception:
+  - Domain (aggregates, VOs, business rules): `DomainException` or a custom subclass with its own
+    code; `ValidationException` (thrown by value objects and `ValueObjects.build`).
+  - Use cases: `AggregateNotFoundException` when a repository returns `null` (except a use case
+    run by a listener to register a fact: it returns, so the listener is not retried forever),
+    `NotAllowedException` when the requester may not run the action (authorization belongs to the
+    use case), `ApplicationException` for other application errors.
+  - Adapters (DB, network…): `InfrastructureException` / `InternalErrorException`, always with
+    `{ cause: error }` when wrapping another error.
+  - `TypePrimitiveException` and `RequiredValueException` are thrown by the VOs; throw them yourself
+    only inside the `filter` of a custom type.
+- Map errors to HTTP with `HttpErrorMapper` (overrides by code for your own codes): 400 for a
+  conversion or required error thrown alone (a value object built with `new` outside
+  `ValueObjects.build`; inside it they become a `ValidationException`, 422, with `DOM003`/`DOM004`
+  in `errors`), 403 `NotAllowedException`, 404 `AggregateNotFoundException`, 409
+  `ConcurrencyException`, 422 `ValidationException` and any other `DomainException` (a broken
+  business rule), 400 any other `ApplicationException`, 500 otherwise; never hand-write status tables that leak infrastructure
+  messages. For logs or messages use `error.code` and the exported `ExceptionCode` enum, or
+  `instanceof`: the built-in exceptions are recognized across the CJS and ESM builds.
+- A use case does **one thing**: one business action, one class, one `handle`. It changes one
+  aggregate and saves it once [Destilado ch. 5; IDDD ch. 10] (the exceptions IDDD ch. 10 accepts, such
+  as creating several aggregates in one batch that changes nothing semantically, are written down
+  as an explicit decision); a flow that needs several actions is several use cases (chained by
+  domain events or called one after another by whoever orchestrates them), never one use case with
+  flags or a `type` field in its input that switch between behaviors.
+- A use case is **named after the business action**, a verb and a noun from the ubiquitous language
+  that a domain expert would say: `PlaceOrder`, `ShipOrder`, `CancelSubscription`,
+  `RegisterUser`, `ApproveRefund`. Never technical or CRUD names (`CreateOrder` when the business
+  says "place", `UpdateOrder`, `SaveUser`, `OrderService`, `OrderManager`, `ProcessOrder`,
+  `HandleData`, `OrderUseCase`).
+- The repository contracts belong to the domain
+  (`import type { AggregateSaver } from '@archi-code/ddd/domain'`). Interface segregation: a use case depends only on the repository roles it uses —
+  `AggregateFinder<A>` (`findById`), `AggregateSaver<A>` (`save`), `AggregateRemover<A>`
+  (`remove`), combined with `&` when it needs several. There is no all-in-one `Repository` port:
+  an adapter implements each role it supports.
+- Use cases extend `UseCase<Input, Command, Output>`, receive ports by constructor
+  (`AggregateSaver<Order>`, `EventBus<OrderEvent>`, `Clock`) and are called
+  with `execute(input)`.
+  They implement two steps: `protected toCommand(input)` builds the value objects with
+  `ValueObjects.build` and returns the command (a small interface of value objects, or one value
+  object built with `new`); `protected handle(command)` works only with value objects. `UseCase` has no helpers:
+  write every step in `handle` (load with `findById` and throw `AggregateNotFoundException` when it
+  is `null` — or return, in a use case a listener runs —, change the aggregate, `save`, then
+  `publish(aggregate.pullDomainEvents())`); it never opens a transaction. Let errors
+  propagate: `execute` keeps package exceptions and wraps any other error (also from `toCommand`)
+  in `InternalErrorException` with `cause`.
+- A use case never imports nor calls another use case, and **returns an id, a DTO or nothing**,
+  never an aggregate. Screens that read several aggregates use read queries, not repositories.
+- **Authorization belongs to the use case**: the entry point takes the requester id from the token
+  and puts it in the input, `toCommand` builds it as a value object, and an application policy
+  (`SalesAccessPolicy`) throws `NotAllowedException`. A rule that is business (only the owner may
+  change the order) stays in the aggregate.
+- **Domain services** are plain classes in `domain/` (no base class) named after the business
+  operation; they receive aggregates and loaded data, and may read other aggregates through an
+  `AggregateFinder` to validate or calculate over several of them [IDDD ch. 5 and 7]; they never
+  save, open transactions nor publish. A
+  technical one (`ExchangeRates`) is an interface in `domain/` implemented in infrastructure.
+- **Repositories only get and persist** (`findById`, `save`, `remove`): no business logic, no
+  business queries (`pendingOlderThan`), no `nextId()`; new ids come from the value object
+  (`OrderId.generate()`). A `findAll()` exists only in the in-memory repository of the tests, if
+  they need it (`[Fuera de los libros: convención de @archi-code/ddd]`; a real repository has no
+  `findAll()`).
+- **One repository per aggregate and technology** (user rule): it implements the roles it supports,
+  knows the aggregate it rebuilds, and its constructor receives only its technology (a collection,
+  a pool), never an aggregate class nor a mapper; aggregates only go in and out through its
+  methods. The aggregate converts itself (`toPrimitives()` / `static fromPrimitives()`), never a
+  domain service nor a mapper; the repository calls those methods directly
+  (`Order.fromPrimitives(row).restoreVersion(row.version)` on load, `order.toPrimitives()` with
+  `order.version + 1` on save, `ConcurrencyException('Order', …)` on a conflict) and maps the
+  primitives to its storage.
+  The package ships no repository: the in-memory one is written in the project's `test/support/`.
+- **Another aggregate is referenced by its id** (`customerId: CustomerId`), never by the object.
+- **A command can be refused, a fact cannot**: a method that registers something that already
+  happened elsewhere (`registerStockReservation`, called by a listener) is idempotent and never
+  throws a business error; if the fact does not fit, it records an event so another listener
+  compensates.
+- **Money is a composite with whole minor units** (`Money({ amount: Cents, currency })`, `Cents` a
+  `Required(NumberType)` with `isInt`), never a decimal amount; it is exact up to
+  `Number.MAX_SAFE_INTEGER` cents (the books use `bigint`, `[Fuera de los libros: convención de
+  @archi-code/ddd]`); rounding is explicit.
+- **The repository owns the transaction and everything about persistence** (`[Fuera de los
+  libros: convención de @archi-code/ddd]`; IDDD ch. 14 gives it to the application service): there
+  is no transaction port, and neither the domain nor the application opens, joins or closes a
+  transaction. Each `save`/`remove` is atomic: one document per aggregate is one write; an
+  aggregate over several tables is written in a database transaction the repository opens and
+  commits inside `save`. The repository also checks the version, manages connections and sessions
+  and wraps driver errors. When events must not be lost between `save` and `publish` [Destilado
+  ch. 6; IDDD ch. 8], the repository stores them in the same atomic write (an outbox) and a relay
+  delivers them through an `EventChannel`: use cases do not change.
+- **Events have a schema version** (`static readonly eventVersion = 2` when their data changes
+  incompatibly; 1 by default, written in `toJSON()`); an `EventRegistry` factory reads older
+  stored versions from `json.eventVersion`.
+- **The application holds only the event contract, in `application/event`**: to publish, the
+  port `EventBus` (`publish`, the only thing use cases see); to listen, `EventListener` and
+  `@ListensTo` (`ListensTo.subscriptionOf(listener)` → `{ eventName, consumer }`). What moves the
+  events is infrastructure, used only by the wiring (composition root), and is imported from
+  `@archi-code/ddd/infrastructure`: `DomainEventBus(channel, registry)` (implements `EventBus`;
+  `subscribe(listener)` → `Subscription { unsubscribe() }`, both async), `EventRegistry` and the
+  port `EventChannel` (`send(serialized)`, `receive(eventName, consumer, handler)` →
+  `ChannelSubscription { close() }`, with `ChannelHandler`). A messaging technology implements only
+  `EventChannel` (`InMemoryEventChannel` in the package; RabbitMQ, a table or Kafka in your
+  infrastructure); swapping it changes one line of the wiring.
+- **Consumers are idempotent**: delivery is at least once, so a listener ignores an `eventId` it
+  already processed. Listeners always receive the event rebuilt from its JSON (frozen, equal by
+  `toJSON()`), also in memory, so nothing changes when the channel does.
+- **Other contexts never receive domain classes**: translate the serialized event to a published,
+  versioned contract (`sales.order.OrderPlaced`, only what consumers need, `messageId` = `eventId`)
+  in the adapter that talks to the broker [IDDD ch. 13]; expose a new contract version next to the
+  old one while consumers move.
+- Event Sourcing and CQRS are optional, only for a concrete need (full history, read models very
+  different from the model); read queries straight to the database come first. A projection is
+  an `EventListener` that writes a read table and skips an `eventId` it already applied; a read query is an application
+  interface implemented in infrastructure that returns DTOs or ids.
+- Logging goes through the `Logger` port of `/application` (`debug`, `info`, `warn`, `error`,
+  each `(message, context?)`): the message is a stable snake_case name (`order_shipped`) and the
+  data goes in the context. Use cases, listeners and adapters that need it receive it by
+  constructor; the domain never logs (it records events or throws). The composition root picks the
+  provider: `ConsoleLogger({ level })` (one JSON line per entry), an adapter over pino or winston,
+  `InMemoryLogger` in tests (`entries`), `SilentLogger` by default. Pass it to
+  `new DomainEventBus(channel, registry, logger)` (listener failures, subscriptions, what was
+  published) and `new HttpErrorMapper({ statusByCode, logger })` (5xx as `error`, 4xx at `debug`):
+  each error is logged once, where it is handled, never logged and rethrown in every layer.
+- Tests use the project's `InMemoryOrderRepository` (in `test/support/`) and
+  `new DomainEventBus(new InMemoryEventChannel(), registry)` (`channel.sent` lists
+  what was published; `{ delivery: 'parallel' }` runs the listeners of an event together).
+- Listeners extend `EventListener<Event>`, are decorated with `@ListensTo(EventClass, { consumer })`
+  (one event per listener, any number of listeners per event; `consumer` is a stable name, unique
+  per listener, that the channel uses as its identity, such as its queue; never derived from the
+  class name, which a minifier changes), receive the one use case they run by
+  constructor and their `handle(event)` only maps the event to that use case's input.
+- The bus is built and connected in the composition root:
+  `const bus = new DomainEventBus(channel, registry)`, then `await bus.subscribe(listener)` for
+  each listener; `subscribe` refuses a listener without `@ListensTo` and an event the registry
+  cannot rebuild. The use cases only receive `EventBus`.
+- A real repository implements the roles it supports (`AggregateFinder<A>`, `AggregateSaver<A>`,
+  `AggregateRemover<A>`) and wraps driver errors in `InternalErrorException` with `cause`.
+  The in-memory repository of the tests (`InMemoryOrderRepository`, see `patterns.md`) stores copies
+  of the primitives with their version and follows the same concurrency contract.
+- `DomainEventBus` rebuilds events with `EventRegistry`: register a factory per
+  event class that passes the JSON as metadata
+  (`register(OrderPlaced, (json) => new OrderPlaced(json.aggregateId, …, json))`); `fromJSON`
+  throws `InternalErrorException` when the rebuilt event lost its `eventId` or `occurredOn`, which
+  listeners need to skip a redelivery.