feat(jpa): implement the JPA relational persistence platform

Implements the Stable and Experimental JPA persistence platform designs
against real PostgreSQL, adapted to this repository's fail-closed 19-leaf
registry.

The design models the platform as 25 Gradle projects. `src/settings.gradle`
throws unless the registry holds exactly 19 leaves, so the plan's modules
become packages inside `:adapter:outbound:persistence-jpa` (starter in
`:app-bootstrap`, testkit in its own source set). The full mapping, the
renames this repository's naming gate required, and every deliberate
substitution are recorded in `docs/jpa/repository-adaptation.md`.

Seven Docker-backed lanes replace the plan's seven JVM test suites. Each
fails closed: a lane that discovers nothing, or a container that cannot
start, is an error rather than a skip.

Three defects the contracts found against a real server:

- `CommitFailureClassifier` treated only SQLSTATE 40003, class 08, and
  transport breaks as completion-unknown. A backend terminated mid-commit
  reports 57P01, and the commit record may already be in the WAL — so a
  possibly-committed transaction could be re-run. 57P01/57P02/57P03 now
  classify as completion-unknown.
- `SchemaTenantMigrationOrchestrator` recorded `MigrateResult`'s target
  version, which is empty for a tenant already current, reporting migrated
  tenants as unmigrated during a partial rollout. It now reads the applied
  version back from the tenant's schema history.
- `JpaStreamExecutor` checked only the declared return type for reactive
  publishers, and `RegisteredPostgreSqlCopyLoader` passed the COPY timeout
  to `SET`, which is parsed before parameter binding.

`JpaModuleBoundaryTest` enforces the plan's module map as package rules;
`verifyCleanArchitectureDependencies` governs edges between leaves and
cannot see these. Its first assertion is that the import is non-empty,
because every rule under it is a `noClasses()` rule and would pass
vacuously on an empty import.

Verified: 128 container tests across all seven lanes, 1183 unit tests,
`:adapter:outbound:persistence-jpa:check`, `:app-bootstrap:check`,
`verifyCleanArchitectureDependencies`, `verifyOneTypePerFile`.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

docs/adr/ADR-JPA-001-domain-owns-persistence-model.md

@@ -0,0 +1,35 @@
+# ADR-JPA-001 — The domain owns the persistence model
+
+- Status: Accepted
+- Date: 2026-08-11
+- Design: §10.1, §23.3
+
+## Context
+
+A persistence platform can either own the repository abstraction — a `GenericRepository<T, ID>`
+every aggregate inherits — or provide only the pieces domains assemble themselves.
+
+## Decision
+
+The domain owns entities, embeddables, repositories, queries, index requirements, and lock,
+soft-delete, and audit policy. The platform provides no generic CRUD repository and no base
+repository. `JpaRepositoryFragmentSupport` exists, has no `save`, `findById`, `findAll`, or
+`delete`, and is enforced not to acquire them.
+
+## Consequences
+
+A generic base repository has one property that looks like a benefit and is not: every aggregate
+gets the same operations. That means each aggregate is offered operations that may be wrong for it —
+a `delete` on an append-only ledger, a `findAll` on a table that will never be small — and, worse,
+one aggregate's later requirement changes the shared base and therefore changes behaviour for
+aggregates nobody reviewed.
+
+Spring Data already implements CRUD. Re-implementing it adds a layer whose only function is to be
+harder to opt out of.
+
+The cost is a small amount of repetition: each domain declares the repository interface it needs.
+That repetition is the thing that makes each aggregate's persistence surface reviewable.
+
+## Enforcement
+
+`JpaArchitectureRules.noGenericRepository()`; `JpaRepositoryFragmentSupportTest`.

docs/adr/ADR-JPA-002-full-transaction-retry.md

@@ -0,0 +1,37 @@
+# ADR-JPA-002 — Retry re-runs the whole use case
+
+- Status: Accepted
+- Date: 2026-08-11
+- Design: §19.2
+
+## Context
+
+Optimistic conflicts, deadlocks, and serialization failures are recoverable. The question is what
+unit gets retried: the failed statement, the transaction, or the use case.
+
+## Decision
+
+The whole use case, in a new transaction with a new Persistence Context.
+`FullTransactionRetryCoordinator` re-enters `JpaTransactionExecutor` for every attempt, and the
+retry advice is ordered outside Spring's transaction advice so each attempt begins a new
+transaction.
+
+## Consequences
+
+Statement-level retry is wrong for exactly the failures being retried. An optimistic conflict means
+the state the attempt computed against is no longer the committed state; re-issuing the same
+statement computes the same wrong answer against a version that has moved on. The domain rules have
+to run again over reloaded data, which means the whole use case.
+
+Reusing the Persistence Context would be equally wrong: the second attempt would read the first
+attempt's stale entities out of the first-level cache. And with the advice ordering inverted, the
+retry loop would run inside one transaction that has already been marked rollback-only, so the
+second attempt fails immediately without executing anything.
+
+The cost is that a retryable use case must be safe to run from scratch — no irreversible external
+effect before the commit. `IrreversibleSideEffectContext` lets a use case declare when that does not
+hold, and the policy then refuses to retry it whatever budget remains.
+
+## Enforcement
+
+`FullTransactionRetryCoordinatorTest`; `RetryableJpaTransactionInterceptor.DEFAULT_ORDER`.

docs/adr/ADR-JPA-003-completion-unknown.md

@@ -0,0 +1,41 @@
+# ADR-JPA-003 — Completion unknown is never retried
+
+- Status: Accepted
+- Date: 2026-08-11
+- Design: §17
+
+## Context
+
+A connection can break while a commit is in flight. The server may have committed; the
+acknowledgement may simply have been lost. The driver cannot tell the two apart.
+
+## Decision
+
+`TransactionCompletionUnknownException` is never retried, automatically or otherwise. It is
+produced only by a failure observed while the transaction phase is `COMMITTING`, and only for
+SQLSTATE `40003`, a connection-class (`08*`) state, or a transport break. Recovery is
+domain-specific reconciliation through `TransactionCompletionResolver`.
+
+## Consequences
+
+Retrying a possibly-committed write is the most damaging thing this platform could do: a duplicate
+payment, a duplicate order, a double decrement. There is no budget or backoff that makes it safe,
+because the failure is epistemic rather than transient.
+
+The invariant is enforced at the type level rather than by policy alone. `JpaFailureContext` refuses
+to construct a retryable completion-unknown context, and the exception rebuilds its context through
+the safe factory whatever it is handed. A future policy bug therefore cannot produce an unsafe
+retry — the value it would need does not exist.
+
+The rule is deliberately narrow in the other direction too. Classifying every connection failure as
+completion-unknown would push ordinary pool exhaustion and server restarts into the reconciliation
+queue, which trains operators to clear that queue without reading it — and then the one entry that
+mattered gets cleared with the rest.
+
+The cost is that the domain must supply the resolver. The platform cannot: only the domain knows
+which idempotency record, business row, or outbox entry proves the write happened.
+
+## Enforcement
+
+`JpaFailureContextTest`; `DefaultJpaRetryPolicyTest`; `CommitFailureClassifierTest`; release gate
+`completion-unknown-no-retry`.

docs/adr/ADR-JPA-004-flyway-schema-source-of-truth.md

@@ -0,0 +1,37 @@
+# ADR-JPA-004 — Flyway is the schema source of truth
+
+- Status: Accepted
+- Date: 2026-08-11
+- Design: §31
+
+## Context
+
+Hibernate can create and alter schema from the entity mapping. Flyway can apply versioned scripts.
+Both cannot own the schema.
+
+## Decision
+
+Flyway owns every schema change. Hibernate validates and never mutates: `ddl-auto` is `validate` or
+`none`, enforced at startup. The runtime database credential holds no DDL privilege, so the rule is
+enforced by the server as well as by configuration.
+
+## Consequences
+
+`ddl-auto=update` fails in a specific and expensive way: it adds but never drops or narrows, so the
+result is a schema that is neither the previous one nor the one the mappings describe — produced
+silently, by whichever instance started first, with no record of what it did.
+
+Two credentials rather than one is what makes this more than a convention. A configuration rule can
+be overridden by a property; a role without `CREATE` cannot be overridden by anything the
+application does.
+
+Validation fails closed and never repairs. `repair` rewrites the schema history to match the scripts
+on disk, which resolves a checksum mismatch by deleting the evidence of which change is missing.
+
+The cost is that a schema change requires a migration script and a deployment step. That is the
+intended cost: it makes schema change reviewable and reversible.
+
+## Enforcement
+
+`JpaDangerousConfigurationGuard`; `FlywaySchemaPolicy`; `FlywayValidationGate`;
+`PostgreSqlRuntimeRoleVerifier`; release gates `flyway-validate` and `runtime-role-no-ddl`.

docs/adr/ADR-JPA-005-postgresql-real-contract.md

@@ -0,0 +1,38 @@
+# ADR-JPA-005 — Contracts run against real PostgreSQL
+
+- Status: Accepted
+- Date: 2026-08-11
+- Design: §40
+
+## Context
+
+An in-memory database makes tests fast and hermetic. A container makes them slow and requires
+Docker.
+
+## Decision
+
+Every persistence contract runs against real PostgreSQL 16, 17, and 18 in containers. H2 remains a
+local-development convenience and never satisfies a contract. The lanes fail closed when Docker is
+absent rather than skipping.
+
+## Consequences
+
+The behaviours these contracts verify either do not exist in H2 or differ there: SQLSTATE values for
+the same violation, `FOR UPDATE SKIP LOCKED` semantics, JSONB operators, range types, concurrent
+index builds, `search_path` privileges, and the generated SQL for a paged collection fetch. A green
+H2 run is evidence that the code compiles and runs — not that any of the above holds.
+
+Three versions rather than one because the platform claims three. A contract suite that ran only on
+16 would make "Stable on 17 and 18" an assumption.
+
+Skipping on missing Docker is the failure mode this decision most wants to avoid: a skipped contract
+reports success, and CI eventually inherits that silence. `PostgreSqlContainerFactory.assertDockerAvailable()`
+throws instead.
+
+The cost is that the contract lanes need Docker and take minutes. The unit lane stays hermetic and
+fast, and is where most tests live; the container lanes verify the things only a real server can
+answer.
+
+## Enforcement
+
+`PostgreSqlVersion.stable()`; `PostgreSqlContainerFactory`; release gate `postgresql-contract`.