문제: src/ 최상위에 계층 폴더와 들여온 제품 폴더(messaging, grpc,
grpc-advanced)와 optional 빌드 폴더(optional-platforms)가 같은 높이로
놓여, 무엇이 이 애플리케이션의 계층인지 폴더만으로 안 보인다.
src/config/에는 빌드 전체 설정과 기능 하나가 주인인 데이터(jpa,
messaging, mongodb)가 섞여 있다.
고른 방법(소유자 결정 2026-11-07, 설계 가-1):
- git mv로 src/platforms/{messaging,grpc,grpc-advanced,optional-build}.
registry source_path 28행만 바꾸고 Gradle 경로(:messaging:*, :grpc:*)는
그대로다. optional 빌드의 이름(optional-platforms)도 그대로다.
- optional 빌드가 한 단계 깊어져, build-logic이 "optional 빌드의 부모 =
주 빌드"로 가정한 네 곳(registry settings, ArchitecturePlugin, 테스트
이미지 catalog, checkstyle·spotbugs 설정)을 MainBuild(위로 올라가며
registry·설정 파일을 찾음)로 바꾼다.
- settings.gradle·build.gradle의 상대 경로, workflow의 -p 값과 경로,
buf 작업 폴더를 고친다. buf breaking은 이동 전 baseline에서도 옛
경로로 비교해 이동 PR에서 건너뛰지 않는다.
- config/jpa, config/messaging, config/mongodb의 데이터를 주인 leaf의
release/로 옮기고 읽는 빌드 줄·테스트·스크립트·문서를 고친다.
- 루트 CLAUDE.md 5절에 최상위 폴더 지도를 한 줄로 적는다.
버린 대안: Gradle 루트를 저장소 루트로(가-3, CI 재편 때 다시 봄),
application-* 묶기(가-2, 파생 서비스 충돌이 큼).
위험·한계: Gradle 문서의 "이름 = 위치" 권고와 한 단계 어긋난다
(:messaging:x가 platforms/messaging/x). 옮긴 폴더를 고쳐 쓰던 파생
서비스는 이름 바뀜 충돌이 날 수 있다(B-52). docs/capability-status.md
「제거된 코드」 표와 docs/work/evidence.md의 옛 경로는 이력이라 두었다.
검증(desktop, 트리 2b3354a4, ~/t1-layout-logs/):
- ./gradlew :ci :verifyDependencyLocks --warning-mode=fail --continue
첫 실행 rc=1: MessagingAuthorityContractTest가 src/messaging을 찾아 실패
→ 경로를 고침. 두 번째 rc=1: messaging-policy
MessagingAdmissionControllerTest.aWaitingCallerIsAdmittedOnceAPermitIsReturned
(2초 대기 경쟁, 부하 7.3에서 한 번 실패, 코드 변경 없는 leaf) → --rerun
3회 모두 통과. 세 번째 rc=0
- -p platforms/optional-build ci rc=0, 두 빌드의 verifyStrictLaneStages
--dry-run rc=0, -p build-logic check rc=0
- :app-bootstrap:documentContractTest
:adapter:outbound:persistence-mongo:mongoDocumentContractTest rc=0
- ./gradlew projects(주 빌드)와 optional 빌드 projects의 프로젝트 목록이
이동 전 트리와 같다(Gradle 경로 불변)
- check-work-docs.py, 상대 링크 검사 rc=0
Refs: design-docs repo-structure/README.md 3.1, repo-structure/01-backend-layout.md 6.1
BREAKING CHANGE: src/messaging·src/grpc·src/grpc-advanced·src/optional-platforms가 src/platforms/ 아래로, src/config/{jpa,messaging,mongodb}가 주인 leaf의 release/로 옮겨졌다. optional 빌드는 -p platforms/optional-build로 부른다. docs/upgrade/2026-11-maturity-review.md B-52.
8.3 KiB
JPA Persistence Platform — Support Matrix
This document is a rendering. The machine-readable source is
src/adapter/outbound/persistence-jpa/release/release-registry.json.
JpaReleaseManifest used to parse this file with regular expressions: every PostgreSQL NN it
mentioned became a supported version, whatever table or sentence produced the match. An Experimental
major joined the Stable list, a version named once in prose counted as supported, and demoting a
major changed nothing so long as the string survived somewhere in the document. Now the registry
declares a support level per major as a field, each gate names the Gradle task that produces its
evidence, and this document describes what the registry says.
Being a rendering used to be a claim rather than a mechanism: the tables below were still typed by
hand, so a major demoted in the registry stayed Stable here and kept its full release job.
JpaReleaseRenderingTest now compares the database table, the gate table and release.yml's JPA
matrix and promotion lists to the registry, and the jpaReleaseQualification aggregate depends on
every blocking gate's task, so a gate naming a task that does not exist fails when the task graph is
built. Edit the registry; these tables follow, or the build fails.
Two renderings stayed outside that comparison until they were added to it. jpa-nightly.yml runs
its own matrix and nothing checked it, so a demotion corrected the release lane and left the nightly
lane certifying the major. And an Experimental major's "compatibility lane only" named no file: the
lane existed, but the registry, this document and the release workflow could each be read end to end
without establishing that, so a reader looking for it concluded there was none. An Experimental major
now has to be recorded as the target of a lane in .github/workflows, and a Stable lane may not run
it.
Database
| Database | Support | Evidence |
|---|---|---|
| PostgreSQL 16 | Stable | full contract suite, release lane (own matrix job) |
| PostgreSQL 17 | Stable | full contract suite, release lane (own matrix job) |
| PostgreSQL 18 | Stable | full contract suite, release lane (own matrix job) |
| PostgreSQL 19 | Experimental | jpa-next.yml — NOT_EXECUTABLE: no postgres:19-alpine is published, so no container of that major has been started; promotion requires an ADR |
| H2 | Local convenience | never evidence of PostgreSQL behaviour |
Each major gets its own release job, because for a while it did not. The release lane passed
-Pjpa.matrix.versions=16,17,18 to a JpaPlatformContractSupport.start() that used
selectedVersions().get(0), so the whole integration suite ran against PostgreSQL 16 and this table
recorded 17 and 18 as fully covered on the strength of a three-assertion smoke test. start() now
refuses a multi-version selection outright, the jpa-release-gate job in release.yml fans out to one job per major, and a
promotion job requires all three majors' evidence to carry the same commit SHA — so a removed major
removes the release, not the evidence for it.
Provider baseline. The gates run against the Hibernate version the Spring Boot BOM resolves —
7.1.8.Final — which the registry records as stable-tested-baseline. This document previously
called 7.4 the Stable baseline and the pagination gate was named hibernate-7.4-fetch-pagination,
so every run of that gate produced evidence labelled with a provider it had never executed against.
7.4 is recorded as compatibility-target; it becomes the baseline when a full lane has actually run
on it.
H2 is not a second production target. It reports different SQLSTATEs for the same violation, no JSONB operators, no range types, and no concurrent index builds. A green H2 run is evidence that the code compiles and runs, and nothing more.
SKIP LOCKED needs its own sentence, because two documents said different things about it. The
module's CLAUDE.md records a measurement: H2 2.4.240 accepts FOR UPDATE SKIP LOCKED and does
genuinely skip locked rows, which is why the outbox claim SQL is identical on both vendors. This
document previously said H2 has no such guarantee. Both are right about different questions, and
the distinction is the point: observed behaviour in the version we measured is not a production
guarantee, and it is never PostgreSQL contract evidence. The measurement is why the claim SQL
needs no vendor branch; the absence of a guarantee is why every concurrency contract still runs
against a real PostgreSQL.
Specification and provider
| Component | Stable | Experimental |
|---|---|---|
| Jakarta Persistence | 3.2 | 4.0 (lane) |
| Hibernate ORM | 7.4 declared baseline | 8 (lane) |
| Spring Boot | repository BOM | — |
The Hibernate row needs a note. The design declares 7.4 as the Stable provider; this repository's
Spring Boot BOM resolves 7.1.x. HibernateProviderPolicy holds both — the declared baseline as a
constant, the resolved version read from Hibernate itself — and driftsFromDeclaredBaseline() makes
the difference visible instead of asserting a constant against itself. See
repository-adaptation.md §4.
Capability support levels
The levels are the ones JpaPlatformAutoConfiguration.capabilities() reports through the
jpaplatform actuator endpoint. Advanced and Experimental rows are library code a service calls
itself (src/adapter/outbound/persistence-jpa/README.md "라이브러리 API").
| Capability | Level |
|---|---|
| Keyset pagination | Stable |
| Flyway schema gate | Stable |
| Runtime role verification | Stable |
| Commit completion evidence | Advanced |
| JDBC batch | Advanced |
| Observability (query metrics, redaction) | Advanced |
| PostgreSQL JSONB | Advanced |
| PostgreSQL array and range | Advanced |
| Bulk DML | Advanced |
Hibernate StatelessSession |
Advanced |
PostgreSQL COPY |
Admin (J4) |
| Hibernate second-level cache | Advanced |
| Hibernate Envers | Advanced |
Technical auditing — audit/AuditableEntity |
Stable (canonical) |
| Multi-tenancy (column, RLS, schema, database) | Experimental |
| Consistency-aware read replica | Experimental |
Release gates
Each row is a way the platform could pass its tests and still be wrong in production.
| Gate | Kind | What it prevents |
|---|---|---|
postgresql-contract |
gate | a release whose only database evidence came from H2 |
completion-unknown-no-retry |
gate | automatically re-running a write that may already have committed |
osiv-disabled |
gate | lazy loading from the view layer, one query per rendered row |
flyway-validate |
gate | Hibernate mutating a deployed schema, or running against one it was not built for |
runtime-role-no-ddl |
gate | the application's own credential being able to alter or drop schema objects |
collection-fetch-pagination |
gate | a paged collection fetch silently reading the whole table and paginating in memory |
The audit mechanism
audit/AuditableEntity is the only one: created_*/updated_*, a 256-character actor, stamped
explicitly by the repository adapter. 서비스의 엔티티는 이것을 상속하고, 마이그레이션도 이 열에
맞춰 썼다. A second, Spring Data listener-based mechanism (auditing/AuditMetadata) was never
composed and has been removed; JpaAuditMechanismRule.entitiesUseExactlyOneAuditMechanism keeps it
from coming back on an entity.
The mechanism does not reach a bulk or native update. It stamps on an ordinary save in the adapter,
so a statement that goes straight to the database leaves the audit columns showing the previous save.
A bulk update of an audited entity must therefore set the audit column in the statement, which
JpaAuditMechanismRule.bulkUpdatesOfAuditedEntitiesStampAudit checks over the production graph.
Explicitly unsupported
- Reactive JPA. JPA is a blocking specification; a reactive facade over it moves the blocking call onto an event loop rather than removing it.
- Hibernate as the production schema writer.
ddl-autonever mutates a deployed schema. - A platform-owned generic CRUD repository. Domains own their repositories (design §10.1).
- Automatic reconciliation of a completion-unknown transaction. The platform records; the domain resolves.