# Marketplace persistence

Marketplace owns the `pharos_marketplace` database and its restricted runtime role
of the same name. Administration applies the shared baseline and Beto's delivery
migrations before startup. The Order needs nothing beyond the shared aggregate,
receipt and outbox tables, so the context's migration manifest lists no migrations.

## Orders

`NewOrderTransaction` gives each command one Order through the shared
`AggregateTransaction`. The Order is a versioned snapshot in `pharos.aggregates`
with kind `order`. The Order, the command receipt, the recorded outcome and the
private `OrderPlaced` in the outbox commit together; a failure after the Order is
saved leaves none of them. A refusal records its outcome and no Order or event.

An exact retry returns the recorded outcome without running the handler. A
command ID reused with another input or actor is refused with
`idempotency_conflict`. An expected version that differs from the stored one is
refused with `version_conflict` before the handler runs, so `If-Match: 0` on an
existing Order and the losers of concurrent placements get it.

The snapshot codec refuses missing, duplicate, unknown and null fields and
unpaired UTF-16 escapes, then restores the Order through its own checks. A
corrupt stored Order fails the command and records nothing.

Beto's composition gives PlaceOrder this transaction. The `mock` stand-ins are
described in the [context README](../../README.md).

## Order reads

`OrderReads` serves ListProjectOrders from the stored Orders, not from a copy, so
a list shows each Order as it is now. It selects one Project's Orders by the
snapshot's `project_id`, ordered by Order ID, one page at a time. Each Order goes
through the same strict codec, and an Order whose row and snapshot disagree fails
the list. Nothing indexes the Project yet, so a list scans the context's Orders;
an index would be the context's first migration.

## Verification

`python3 scripts/beto_native_integration.py` creates the database with its
restricted role, applies the migrations twice and runs the integration tests
with race detection. They cover the atomic commit, replay, changed input or
actor, stale and concurrent expected versions, refusal and rollback, a corrupt
stored Order, and refused administration and cross-context access. The read tests
cover a Project's Orders without other Projects', paging and a corrupt Order.
`pnpm test:integration` runs the same tests against its Docker PostgreSQL. The
snapshot tests run with the ordinary Beto suite.