# REF-TASK-016 — Decide safe decomposition of order persistence

**Status:** Implemented  
**Kind:** Decision / architectural refactor  
**Depends on:** REF-TASK-013, REF-TASK-015

## Problem and evidence

`PostgresOrderRepository` is about 592 lines and implements checkout claims, pricing, atomic order
creation, active queue and sales reads, histories, metadata changes, and fulfillment transitions.
Its integration test is about 1,587 lines, with separate history/restart suites nearby. The class is
large, but many operations intentionally share one order aggregate and transaction semantics; a
naive repository-per-table split would weaken cohesion and complicate atomic finalization.

## Required decision and proposed direction

Map methods by transaction boundary and use case. Consider extracting private query/mapping modules
or read-model repositories for independently read sales/active-queue projections while retaining one
transactional writer for finalization, checkout claims, transitions, and histories that must commit
together. Compare this with retaining one class but splitting internal SQL/mappers. Ask the user to
approve any change to repository interfaces or application dependency topology before implementing.

## Constraints and sequence

First document transaction/invariant ownership and characterize it with existing real-PostgreSQL
tests. Perform any approved move mechanically without SQL changes; validate. Only then simplify
queries/mappers. Preserve locks, database timestamps, append-only history, selection ordering,
checkout idempotency, snapshot immutability, sales semantics, and connection lifecycle. Do not add a
generic base repository or one repository per table.

## Validation

Run affected repository tests after each move, all real-PostgreSQL order/history/restart integration
tests, service/API tests, migration checks, backend build/coverage, relevant E2E journeys, Docker
validation if database composition changes, and `pnpm quality`.

## Guidance / ADR

An ADR is required if repository boundaries or dependency topology change. A private file split with
the same interface needs only architecture/development-guide updates.

## Open question for the user

Approve a read/write capability split only after the invariant map shows that it reduces coupling
without fragmenting atomic order operations; otherwise prefer internal module extraction.