# ADR001-WP2-006 – Rehydration of Aggregate Roots

**Status:** Draft

## 1. Context

With WP2-005 Reconcilix introduced relational repositories and specialized data mappers.
The next step is the reconstruction (rehydration) of complete aggregate roots from the
relational persistence layer.

Rehydration shall recreate valid domain objects while preserving aggregate boundaries and
domain invariants.

## 2. Decision

Reconcilix performs rehydration exclusively through aggregate repositories.

No generic hydrator or service locator is introduced.

Each repository coordinates the reconstruction of exactly one aggregate.

## 3. Aggregate Boundaries

### SourceValue Aggregate

```text
SourceValue
└── InterpretationGraph
    └── InterpretationNode
```

Coordinator:

`RelationalSourceValueRepository`

### ReconciliationResult Aggregate

```text
ReconciliationResult
├── CandidateItem
└── MatchDecision
```

Coordinator:

`RelationalReconciliationResultRepository`

## 4. Responsibilities

### Repository

Responsibilities:

- execute persistence queries
- coordinate reconstruction order
- assemble complete aggregate
- return only valid aggregate roots
- translate persistence failures into `PersistenceException`

Repositories do not contain SQL mapping logic.

### Data Mapper

Each mapper reconstructs only its own domain object.

Examples:

- SourceValueMapper
- InterpretationGraphMapper
- InterpretationNodeMapper
- ReconciliationResultMapper
- CandidateItemMapper
- MatchDecisionMapper

Mappers remain independent from other aggregates.

## 5. Rehydration Sequence

### SourceValue

```text
Application
      │
      ▼
RelationalSourceValueRepository
      │
      ├── SourceValueMapper
      ├── InterpretationGraphMapper
      └── InterpretationNodeMapper
      │
      ▼
Complete SourceValue Aggregate
```

### ReconciliationResult

```text
Application
      │
      ▼
RelationalReconciliationResultRepository
      │
      ├── ReconciliationResultMapper
      ├── CandidateItemMapper
      └── MatchDecisionMapper
      │
      ▼
Complete ReconciliationResult Aggregate
```

## 6. Domain Reconstruction

Domain objects are reconstructed through explicit domain-supported construction
(constructor or dedicated reconstitution methods).

Persistence is allowed to restore technical identifiers generated during persistence.

Domain invariants shall not be bypassed.

## 7. Error Handling

The repository throws `PersistenceException` if:

- aggregate root does not exist
- mandatory persistence records are missing
- foreign key references are inconsistent
- reconstructed aggregate would violate domain invariants

No partially reconstructed aggregate is returned.

## 8. Consequences

Advantages

- identical architecture for save and load
- clear aggregate boundaries
- repositories remain aggregate coordinators
- no additional infrastructure layer

Trade-offs

- repository coordinates multiple mapper calls
- mapper collaboration increases for larger aggregates

## 9. Out of Scope

WP2-006 explicitly excludes:

- transactions
- Unit of Work
- Identity Map
- Lazy Loading
- caching
- optimistic locking

These topics are addressed in later work packages.

## Revision History

| Revision | Description |
|-----------|-------------|
| Draft | Initial proposal for LA review |