0015 · Repositories return one RepositoryError
Status: Accepted (2026-10-11).
Context
Section titled “Context”Every repository port returned its entity’s error (ProductError), and every Pg repository
re-implemented the driver mapping inline — 23505 → Duplicate, anything else →
RepositoryError — once per entity and once more in the IDE snippet. A row that no longer passed
the domain’s rules surfaced as whatever VO error TryFrom produced (product.invalid_name, a
422), blaming the caller for stored data. document-api splits it: one shared RepositoryError
that adapters map onto, and per-context errors with From<RepositoryError> (backlog T-28).
Decision
Section titled “Decision”business/src/domain/shared/repository_error.rsships in the template:RepositoryError { Duplicate, InvalidData, Unavailable }(repository.*codes,Copy,Eq). Three variants, not more: they are the three outcomes a use case reacts to differently. “Not found” is not one —find_by_idanswersOk(None)and the use case decides it is an error.- Every repository port and its mock return
Result<_, RepositoryError>. Each entity error hasimpl From<RepositoryError>:Duplicate → Duplicate,InvalidData | Unavailable → RepositoryError, one test per arm. Use cases keep?. - The entity’s error codes do not change. The API contract (ADR-0007) still answers
product.duplicate/product.repository_error;RepositoryError’s own codes only reach logs. - Pg repositories call
infrastructure::db::map_sqlx_error(&sqlx::Error)— the one place that knows Postgres codes — after logging with their own context. A row whoseTryFromfails is logged with the domain error and becomesInvalidData(500, not 422). - The module lives in
domain/shared/, next to shared value objects, now declared indomain/shared.rsinstead of a generatedshared/mod.rs(the module convention forbidsmod.rs).generate value-objectappends its two modules toshared.rs.
Consequences
Section titled “Consequences”- An adapter for another store (an HTTP API, Redis) maps onto the same three variants; the domain and application layers do not change.
RepositoryError::InvalidDatahides the underlying VO error from the caller; the log keeps it.- Use cases can no longer receive an entity-specific error from a repository. A repository that
needs a richer failure (an optimistic-lock conflict) adds a variant here, with its
Fromarm in every entity — the exhaustive match makes the compiler list them.