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

package/SKILL.md

@@ -1,19 +1,21 @@
 ---
 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.
+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 ExceptionClassifier. 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
+layer, each with the exceptions of its layer: `@archi-code/ddd/domain` (value objects, `Composite`,
+`Specification`, `Entity`, `AggregateRoot`, `EventBase`, the repository contracts
+`AggregateFinder`, `AggregateSaver`, `AggregateRemover`, and `DomainException`,
+`ValidationException`…), `@archi-code/ddd/application` (`UseCase`, the event contract to listen,
+`EventListener` and `@ListensTo`, and to publish, `EventBus`, the ports `Clock`, `Logger`, and
+`AggregateNotFoundException`, `NotAllowedException`…) and `@archi-code/ddd/infrastructure` (the
 event wiring `DomainEventBus`, `EventRegistry` and the `EventChannel` port, in-memory event
-channel, HTTP error mapper, clocks, loggers).
+channel, clocks, loggers, `InternalErrorException`…). `@archi-code/ddd/infrastructure` also has
+`ExceptionClassifier`, which gives every entry point (HTTP, gRPC, queue, CLI) the `ExceptionKind`
+of an error.
 
 ## Full API
 

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

@@ -11,34 +11,24 @@ import {
   Composite,
   CreatedAt,
   DateType,
+  DomainException,
+  DomainExceptionCode,
   Entity,
   EnumType,
   EventBase,
   IdType,
+  InvalidEventDefinitionException,
   JsonType,
   NumberType,
   Required,
+  RequiredValueException,
   Specification,
   StringType,
+  TypePrimitiveException,
   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';
+} from '@archi-code/ddd/domain';
 import type {
   AggregateFinder,
   AggregateRemover,
@@ -49,8 +39,20 @@ import type {
   PrimitiveTypes,
   SatisfiedBy,
   SerializedEvent,
+  ValidationIssue,
 } from '@archi-code/ddd/domain';
-import { EventListener, ListensTo, UseCase } from '@archi-code/ddd/application';
+import {
+  AggregateNotFoundException,
+  ApplicationException,
+  ApplicationExceptionCode,
+  ConcurrencyException,
+  EventListener,
+  ListensTo,
+  NotAllowedException,
+  UnexpectedErrorException,
+  UseCase,
+  ValueObjectBuilder,
+} from '@archi-code/ddd/application';
 import type {
   Clock,
   EventBus,
@@ -63,12 +65,17 @@ import {
   ConsoleLogger,
   DomainEventBus,
   EventRegistry,
+  ExceptionClassifier,
+  ExceptionKind,
   FixedClock,
-  HttpErrorMapper,
+  InfrastructureException,
+  InfrastructureExceptionCode,
   InMemoryEventChannel,
   InMemoryLogger,
+  InternalErrorException,
   SilentLogger,
   SystemClock,
+  UnknownEventException,
 } from '@archi-code/ddd/infrastructure';
 import type {
   ChannelHandler,
@@ -79,6 +86,9 @@ import type {
 import { Validations } from '@archi-code/validation';
 ```
 
+Each layer exports its own exceptions and its own code enum; there is no `/exceptions` subpath
+and the common base class of the exceptions is internal.
+
 ```js
 const { Required, StringType } = require('@archi-code/ddd/domain');
 ```

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

@@ -6,8 +6,9 @@ Part of the `archi-code-ddd` skill: read it only when that skill routes here.
   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
+  required: the constructor demands `T` and, if it receives an empty value (`null` or `undefined`),
+  throws `RequiredValueException` with the class name. A blank text is a value: `StringType` keeps
+  it and the other types refuse it with `TypePrimitiveException`. `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
@@ -18,15 +19,18 @@ Part of the `archi-code-ddd` skill: read it only when that skill routes here.
   (`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
+- **Report every field, never only the first.** In `toCommand`, build the value objects of an
+  input with `ValueObjectBuilder.build({ field: () => new X(input.field), … })` from
+  `@archi-code/ddd/application` (the domain never uses it): 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
+  `ORD003`); `ValueObjectBuilder.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
+  `UnexpectedErrorException`), and an error that is not a `DomainException` is a bug that wins over the
   validation errors already collected.
+- An `ArrayType` receives items that are already valid: it does not collect item errors and lets
+  the error of the first invalid item through as the item throws it.
 - **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
@@ -39,9 +43,9 @@ Part of the `archi-code-ddd` skill: read it only when that skill routes here.
 - 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.
+- `toString()` is a method, `equals(other)` compares class and
+  value (dates by instant, arrays and objects by content). Template literals work on VOs;
+  `JSON.stringify` does not unwrap them: serialize `value` or the aggregate's `toPrimitives()`.
 - 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
@@ -107,56 +111,60 @@ Part of the `archi-code-ddd` skill: read it only when that skill routes here.
      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.
+  5. Repositories only call `order.toPrimitives()` and `Order.fromPrimitives(row)`; 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 })`.
+- Aggregates extend `AggregateRoot<Id, Event>` and call `super(id)`. The aggregate carries **no
+  version**: it never declares, stores nor maps one; optimistic concurrency is the repository's.
+- **Every repository checks the version** (contract): it remembers the version of each aggregate
+  object it loaded or saved in a private `WeakMap<Order, number>` (`versions`); load with
+  `Order.fromPrimitives(row)` and `versions.set(order, row.version)`; on save take
+  `versions.get(order) ?? 0`, save a new aggregate (`0`) as version 1 and treat an existing id as a
+  conflict; save an existing one only where the stored version still equals the remembered one,
+  storing one more next to (never inside) the primitives; when nothing was written throw
+  `ConcurrencyException('Order', id, version)` (`ExceptionKind.Conflict`); after a write
+  remember `version + 1`. 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`
+  where the stored version still equals the remembered one, 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.
+- `record(event)` is `protected` and keeps the event as it is (facts never change [IDDD ch. 8]: the
+  event declares its fields `readonly`); `pullDomainEvents()` returns the events (typed `Event[]`) in order
+  and empties the list. Pull them after persisting, to publish. `DomainEventBus.publish` only sends a
+  plain copy of each event (`{ ...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
+  call `super(metadata)`; the base copies the name into the event's `eventName` field. An event
+  is plain data with no methods. The id of the aggregate is a field the event declares like any
+  other (`readonly orderId: string`). Rule (not checked at run time): each event declares as
+  `readonly` constructor fields only the primitive data it needs (text, finite numbers, booleans,
+  `null`, lists and plain objects of them), taken from value objects (`id.value`,
+  `customer.value`, money as `{ amount, currency }`, dates as ISO text): never value objects,
+  `Date`s, `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
+  base sets `eventId` (UUID v4) and `occurredOn` (ISO text in UTC, 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).
+  `new OrderPlaced(id.value, customer.value, { clock })`. The event is its own JSON:
+  `{ ...event }` / `JSON.stringify(event)` give `eventName`, `eventId`, `occurredOn` and the
+  fields, in that order.
 - `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`).
+    code; `ValidationException` (thrown by value objects and `ValueObjectBuilder.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
@@ -165,13 +173,19 @@ Part of the `archi-code-ddd` skill: read it only when that skill routes here.
     `{ 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
+- The package speaks no protocol: each entry point (HTTP, gRPC, queue consumer, CLI) translates
+  errors itself from `ExceptionClassifier.classify(error)` (`/infrastructure`), which returns the
+  `ExceptionKind`: `Malformed` for a conversion or required error thrown alone (a value object
+  built with `new` outside `ValueObjectBuilder.build`; inside it they become a `ValidationException` with
+  `DOM003`/`DOM004` in `errors`), `NotAllowed` for `NotAllowedException`, `NotFound` for
+  `AggregateNotFoundException`, `Conflict` for `ConcurrencyException`, `Invalid` for
+  `ValidationException` and any other `DomainException` (a broken business rule), `Rejected` for
+  any other `ApplicationException`, `Internal` for `UnexpectedErrorException`,
+  `InvalidEventDefinitionException` and anything else. The entry point maps the kind to its
+  protocol (HTTP: 400, 403, 404, 409, 422, 400, 500), handles your own codes with `error.code`,
+  returns the `errors` of a `ValidationException`, never sends the message of an `Internal`
+  failure and logs it once; never classify exceptions with hand-written `instanceof` chains. For logs or messages use `error.code` and the code enum of each layer
+  (`DomainExceptionCode`, `ApplicationExceptionCode`, `InfrastructureExceptionCode`), 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
@@ -193,13 +207,13 @@ Part of the `archi-code-ddd` skill: read it only when that skill routes here.
   (`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
+  `ValueObjectBuilder.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`.
+  in `UnexpectedErrorException` 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
@@ -221,9 +235,9 @@ Part of the `archi-code-ddd` skill: read it only when that skill routes here.
   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.
+  (`Order.fromPrimitives(row)` on load, `order.toPrimitives()` on save, with the version it keeps
+  in its own `WeakMap`, `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
@@ -243,9 +257,10 @@ Part of the `archi-code-ddd` skill: read it only when that skill routes here.
   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`.
+- **Events carry no schema version.** Adding an optional field old readers can ignore is
+  compatible; a change they cannot follow is a new event with its own `eventName`
+  (`CustomerRenamedV2`), or the `EventRegistry` factory reads both shapes from the stored JSON
+  (`typeof json.name === 'string' ? … : …`).
 - **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
@@ -257,8 +272,8 @@ Part of the `archi-code-ddd` skill: read it only when that skill routes here.
   `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.
+  already processed. Listeners always receive the event rebuilt from its JSON (equal field
+  by field), 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
@@ -274,7 +289,7 @@ Part of the `archi-code-ddd` skill: read it only when that skill routes here.
   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`):
+  published) and to the entry points, which log an `Internal` failure as `error`:
   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
@@ -294,6 +309,6 @@ Part of the `archi-code-ddd` skill: read it only when that skill routes here.
   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`
+  (`register(OrderPlaced, (json) => new OrderPlaced(json.orderId as string, …, json))`); `fromJSON`
   throws `InternalErrorException` when the rebuilt event lost its `eventId` or `occurredOn`, which
   listeners need to skip a redelivery.

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

@@ -29,7 +29,7 @@ new Email('x');
 new PackSize(-3);
 // ValidationException: Validation failed, PackSize: Value does not satisfy isInt, PackSize: Must be even
 
-const command = ValueObjects.build({
+const command = ValueObjectBuilder.build({
   email: () => new Email(input.email),
   packSize: () => new PackSize(input.packSize),
 });
@@ -55,11 +55,11 @@ class OrderPlaced extends EventBase {
   static readonly eventName = 'OrderPlaced';
 
   constructor(
-    orderId: string,
+    readonly orderId: string,
     readonly customer: string,
     metadata?: EventMetadata,
   ) {
-    super(orderId, metadata);
+    super(metadata);
   }
 }
 
@@ -67,12 +67,12 @@ class OrderLineAdded extends EventBase {
   static readonly eventName = 'OrderLineAdded';
 
   constructor(
-    orderId: string,
+    readonly orderId: string,
     readonly sku: string,
     readonly quantity: number,
     metadata?: EventMetadata,
   ) {
-    super(orderId, metadata);
+    super(metadata);
   }
 }
 
@@ -180,7 +180,7 @@ class AddOrderLine extends UseCase<AddOrderLineInput, AddOrderLineCommand, void>
   }
 
   protected toCommand(input: AddOrderLineInput): AddOrderLineCommand {
-    return ValueObjects.build({
+    return ValueObjectBuilder.build({
       orderId: () => new OrderId(input.orderId),
       sku: () => new Sku(input.sku),
       quantity: () => new Quantity(input.quantity),
@@ -216,7 +216,7 @@ class PrepareShipment extends UseCase<
   }
 
   protected toCommand(input: { orderId: string; sku: string }): { orderId: OrderId; sku: Sku } {
-    return ValueObjects.build({
+    return ValueObjectBuilder.build({
       orderId: () => new OrderId(input.orderId),
       sku: () => new Sku(input.sku),
     });
@@ -234,7 +234,7 @@ class PrepareShipmentOnOrderLineAdded extends EventListener<OrderLineAdded> {
   }
 
   async handle(event: OrderLineAdded): Promise<void> {
-    await this.prepareShipment.execute({ orderId: event.aggregateId, sku: event.sku });
+    await this.prepareShipment.execute({ orderId: event.orderId, sku: event.sku });
   }
 }
 ```
@@ -246,6 +246,8 @@ which receives the loaded aggregate) and wraps driver errors with their cause:
 class MongoOrderRepository
   implements AggregateFinder<Order>, AggregateSaver<Order>, AggregateRemover<Order>
 {
+  private readonly versions = new WeakMap<Order, number>();
+
   constructor(private readonly collection: Collection<OrderDocument>) {}
 
   async findById(id: OrderId): Promise<Order | null> {
@@ -254,34 +256,34 @@ class MongoOrderRepository
       return null;
     }
     const { _id, version, ...primitives } = document;
-    return Order.fromPrimitives(primitives).restoreVersion(version);
+    const order = Order.fromPrimitives(primitives);
+    this.versions.set(order, version);
+    return order;
   }
 
   async save(order: Order): Promise<void> {
-    const data = { ...order.toPrimitives(), version: order.version + 1 };
+    const version = this.versions.get(order) ?? 0;
+    const data = { ...order.toPrimitives(), version: version + 1 };
     let written: boolean;
     try {
       written =
-        order.version === 0
+        version === 0
           ? await this.insertUnlessTaken(data)
-          : (await this.collection.replaceOne({ _id: data.id, version: order.version }, data))
-              .matchedCount === 1;
+          : (await this.collection.replaceOne({ _id: data.id, version }, data)).matchedCount === 1;
     } catch (error) {
       throw new InternalErrorException('saving order', { cause: error });
     }
     if (!written) {
-      throw new ConcurrencyException('Order', order.id.value, order.version);
+      throw new ConcurrencyException('Order', order.id.value, version);
     }
-    order.markPersisted();
+    this.versions.set(order, version + 1);
   }
 
   async remove(order: Order): Promise<void> {
-    const { deletedCount } = await this.collection.deleteOne({
-      _id: order.id.value,
-      version: order.version,
-    });
-    if (deletedCount === 0 && order.version > 0) {
-      throw new ConcurrencyException('Order', order.id.value, order.version);
+    const version = this.versions.get(order) ?? 0;
+    const { deletedCount } = await this.collection.deleteOne({ _id: order.id.value, version });
+    if (deletedCount === 0 && version > 0) {
+      throw new ConcurrencyException('Order', order.id.value, version);
     }
   }
 }
@@ -298,48 +300,54 @@ import type {
   AggregateSaver,
   PrimitiveTypes,
 } from '@archi-code/ddd/domain';
-import { ConcurrencyException } from '@archi-code/ddd/exceptions';
+import { ConcurrencyException } from '@archi-code/ddd/application';
 
 export class InMemoryOrderRepository
   implements AggregateFinder<Order>, AggregateSaver<Order>, AggregateRemover<Order>
 {
   private readonly rows = new Map<string, { version: number; primitives: PrimitiveTypes<Order> }>();
+  private readonly versions = new WeakMap<Order, number>();
 
   async findById(id: OrderId): Promise<Order | null> {
     const row = this.rows.get(id.value);
-    return row === undefined
-      ? null
-      : Order.fromPrimitives(structuredClone(row.primitives)).restoreVersion(row.version);
+    if (row === undefined) {
+      return null;
+    }
+    const order = Order.fromPrimitives(structuredClone(row.primitives));
+    this.versions.set(order, row.version);
+    return order;
   }
 
   async save(order: Order): Promise<void> {
-    const key = this.currentKey(order);
+    const version = this.checkedVersion(order);
     const primitives = structuredClone(order.toPrimitives());
-    this.rows.set(key, { version: order.version + 1, primitives });
-    order.markPersisted();
+    this.rows.set(order.id.value, { version: version + 1, primitives });
+    this.versions.set(order, version + 1);
   }
 
   async remove(order: Order): Promise<void> {
-    this.rows.delete(this.currentKey(order));
+    this.checkedVersion(order);
+    this.rows.delete(order.id.value);
   }
 
-  private currentKey(order: Order): string {
+  private checkedVersion(order: Order): number {
     const key = order.id.value;
-    if ((this.rows.get(key)?.version ?? 0) !== order.version) {
-      throw new ConcurrencyException('Order', key, order.version);
+    const version = this.versions.get(order) ?? 0;
+    if ((this.rows.get(key)?.version ?? 0) !== version) {
+      throw new ConcurrencyException('Order', key, version);
     }
-    return key;
+    return version;
   }
 }
 ```
 
-Wiring and tests with the in-memory adapters (repository, event channel) and the HTTP mapper:
+Wiring and tests with the in-memory adapters (repository, event channel), and the kind of an error:
 
 ```ts
 const orders = new InMemoryOrderRepository();
 const registry = new EventRegistry<OrderEvent>().register(
   OrderLineAdded,
-  (json) => new OrderLineAdded(json.aggregateId, json.sku as string, json.quantity as number, json),
+  (json) => new OrderLineAdded(json.orderId as string, json.sku as string, json.quantity as number, json),
 );
 const channel = new InMemoryEventChannel(); // swap for your RabbitMQ or database channel
 const bus = new DomainEventBus<OrderEvent>(channel, registry);
@@ -354,8 +362,7 @@ await new AddOrderLine(orders, bus, clock).execute({
 });
 channel.sent.map((event) => event.eventName); // ['OrderLineAdded']: PrepareShipment already ran
 
-const errors = new HttpErrorMapper({ statusByCode: { ORD001: 409 } }); // a domain rule defaults to 422
-const { status, body } = errors.map(caughtError);
+ExceptionClassifier.classify(new OrderShippedException(orderId)); // ExceptionKind.Invalid ('invalid')
 ```
 
 A test of the event flow asserts on what the listener caused and on what the channel carried,
@@ -385,7 +392,7 @@ describe('Adding a line to an order', () => {
 
     expect(prepared).toEqual([`${orderId}:TORCH-01`]);
     expect(channel.sent).toMatchObject([
-      { eventName: 'OrderLineAdded', aggregateId: orderId, sku: 'TORCH-01', quantity: 2 },
+      { eventName: 'OrderLineAdded', orderId, sku: 'TORCH-01', quantity: 2 },
     ]);
   });
 });
@@ -478,9 +485,9 @@ integration test waits for the effect (polling until `prepared` has the line) in
 right after `execute`.
 
 Tests with Vitest: describe real situations, use a plain fixture factory in the project's
-`test/support/` and the native matchers (there is no archi-code test package). Dates held by VOs and
-events are immutable `Date` subclasses: compare them with `toEqual` or `.toISOString()`, not
-`toStrictEqual` against a plain `Date`.
+`test/support/` and the native matchers (there is no archi-code test package). Dates held by VOs are
+immutable `Date` subclasses: compare them with `toEqual` or `.toISOString()`, not
+`toStrictEqual` against a plain `Date`; an event's `occurredOn` is already ISO text.
 
 ```ts
 import { describe, expect, it } from 'vitest';
@@ -496,8 +503,8 @@ describe('Order', () => {
       id: orderId,
       lines: [{ sku: 'TORCH-01', quantity: 2 }],
     });
-    expect(order.pullDomainEvents().map((event) => event.toJSON())).toMatchObject([
-      { eventName: 'OrderPlaced', aggregateId: orderId, customer: 'Ana' },
+    expect(order.pullDomainEvents().map((event) => ({ ...event }))).toMatchObject([
+      { eventName: 'OrderPlaced', orderId, customer: 'Ana' },
       { eventName: 'OrderLineAdded', sku: 'TORCH-01', quantity: 2 },
     ]);
   });