workflow 15개(+ composite action, jq 설치 스크립트)가 모듈 모양으로 나뉘어 있었고, 그것을 읽는 판독기(ShellScript·WorkflowGradleInvocations· TaskSelectors, 운영 3,283줄과 그 시험 1,814줄)가 리뷰 라운드마다 새 셸 모양으로 결함을 냈다. 그런데 Gitea에서는 Actions가 꺼져 있어 workflow는 한 번도 돌지 않았다(design-docs repo-structure/03-ci.md 2.1·3.4절). 소유자가 정한 B안(같은 문서 7절, 11절 ①~⑧)대로 바꾼다. - .gitea/workflows/pr.yml: `gradle` job이 `./gradlew :prCheck`와 `./gradlew :verifyStrictLaneStages --dry-run` 두 줄, `vulnerabilities` (trivy), 필수 검사 하나 `done`. - main.yml: push마다 mainCheck·integrationCheck·build-logic 시험· configuration cache·lychee·trivy·http3(권고). nightly·수동 실행에서 PostgreSQL major·HTTP transport·Redis topology 행렬, NFS, 알림 chaos, jpa-next, compose smoke, 마지막에 `needs`로 performanceCheck. - release.yml: releaseCheck와 기존 release lane, 이미지를 이 Gitea 레지스트리에 올리고 cosign 키 쌍으로 서명한다. 수동 실행은 push·서명 앞까지 돈다. upload/download-artifact를 쓰지 않는다. JPA 승격은 `needs: jpa-release-gate`가 대신한다. - 새 집계 `prCheck` = ci + verifyDependencyLocks + compose 렌더링 + 저장소 배치 + 문서 검사(Exec). workflow와 verify.sh가 같은 한 줄을 쓴다. - verifyStrictLaneStages: 그래프 검사(모든 strict lane이 선언한 단계의 계획에 있다)는 그대로 두고, workflow 쪽은 고정 문자열 형식 검사로 바꾼다. 단계마다 workflow·이벤트·필터·job·옵션·조건을 build.gradle에 선언하고, 그 job의 step이 `run: ./gradlew <단계> <옵션>`을 가지며 다른 run도 셸 문법 없는 ./gradlew 한 줄이고, 선언 밖의 if:, 조건 없는 needs:, continue-on-error·shell:·defaults:, 따옴표 키·flow 형식, 다른 working-directory, 선언 밖의 이벤트 필터가 없는지 본다. PR 단계 job 하나는 이 검사 자신을 돌려야 한다. 셸 해석 코드와 그 시험을 지운다 (build-logic 운영 코드 −3,167줄, 시험 −2,231줄). 우회 입력 21가지를 TestKit 시험으로 둔다. - scripts/verify.sh <단계>: 사람·세션의 진입점. 무거운 단계는 지금 작업 트리를 패치로 desktop에 보내 잠금 아래에서 돌린다(operate.md 4.1절의 손 절차). scripts/ci/는 workflow가 부르는 trivy·Redis topology·포트 포워더·configuration cache 스크립트다. - workflow를 읽는 시험(DeveloperExperienceContractTest, JpaRelease RenderingTest, FileserverDocumentationCoverageTest)과 입력 선언을 .gitea로 옮기고, keyless 서명 시험을 키 쌍 서명 시험으로 바꾼다. - 문서: gates.md·operate.md·docs/ci-cd·AGENTS.md(검증 절)·build-logic AGENTS.md(셸 규칙 문단을 세 줄로)·leaf 문서의 workflow 참조, docs/upgrade B-57~B-61. 버린 것: workflow 하나에 if:로 단계를 나누기(파일만 보고 단계를 알 수 없다), 레지스트리에서 생성(같은 정보의 셋째 사본), 바뀐 모듈만 돌리기 (결정 30과 충돌). 판독기를 남기고 고치기는 6라운드 13건이 반증했다. 위험: PR이 어댑터 컨테이너 lane과 Redis standalone lane을 더는 막지 않는다(main·nightly에서 빨갛게 된다. 소유자 결정 ②). main push는 ci를 다시 돌리지 않는다. 성능 lane은 매 push가 아니라 nightly에서만 돈다. `.github/workflows/messaging-certification.yml`은 메시징 분리 작업이 지우므로 남겼다(.gitea가 있으면 Gitea가 읽지 않는다). 서명·push는 secret이 없어 실제 태그로는 돌려 보지 않았다. BREAKING CHANGE: workflow 파일 위치와 이름, strictLaneStages 문법, 릴리스 레지스트리·서명 방식이 바뀌었다. docs/upgrade/2026-11-maturity- review.md B-57~B-61을 따른다.
9.1 KiB
JPA 영속성 플랫폼 — 지원 매트릭스
이 문서는 렌더링이다. 기계가 읽는 정본은
src/adapter/outbound/persistence-jpa/release/release-registry.json이다.
registry는 major마다 지원 수준을 칸으로 선언하고, gate마다 그 증거를 만드는 Gradle 태스크를 이름 댄다. 이 문서는 registry가 말하는 것을 설명한다. 표를 고치지 말고 registry를 고친다. 표가 따라오지 않으면 빌드가 실패한다.
JpaReleaseRenderingTest가 DB 표, gate 표,.gitea/workflows/release.yml의 JPA matrix를 registry와 비교한다. 릴리스 이미지 job은 그 matrix job 전부를needs로 기다린다. 그래서 같은 실행·같은 커밋에서 모든 Stable major가 통과해야 이미지가 나간다.jpaReleaseQualification집계 태스크는 막는 gate마다 그 태스크에 의존한다. 그래서 없는 태스크를 이름 댄 gate는 태스크 그래프를 만들 때 실패한다..gitea/workflows/main.yml의 nightlyjpa-postgresqlmatrix도 같은 비교를 받는다. Experimental major는.gitea/workflows의 어떤 lane이 그것을 대상으로 기록해야 하고(지금main.yml의jpa-nextjob), Stable lane은 그것을 돌리면 안 된다.
이력: 전에는
JpaReleaseManifest가 이 파일을 정규식으로 읽었다. 어느 표나 문장에서 나왔든PostgreSQL NN이 지원 버전이 됐다. Experimental major가 Stable 목록에 들어갔고, 본문에 한 번 나온 버전이 지원으로 셌고, 문자열이 문서 어딘가에 남아 있는 한 major를 내려도 아무것도 바뀌지 않았다. registry로 옮긴 뒤에도 한동안 아래 표는 손으로 썼다. 그래서 registry에서 내린 major가 여기서는 Stable로 남고 자기 전체 릴리스 job을 계속 가졌다. nightly workflow는 자기 matrix를 아무도 확인하지 않아서, 내리기가 릴리스 lane만 고치고 nightly lane은 그 major를 계속 인증했다. Experimental major의 「compatibility lane only」는 어떤 파일도 가리키지 않았다. lane은 있었지만 registry, 이 문서, 릴리스 workflow를 끝까지 읽어도 그것을 알 수 없어서, 찾던 사람은 없다고 결론 냈다.
데이터베이스
| Database | Support | Evidence |
|---|---|---|
| PostgreSQL 16 | Stable | 전체 계약 suite, 릴리스 lane(자기 matrix job) |
| PostgreSQL 17 | Stable | 전체 계약 suite, 릴리스 lane(자기 matrix job) |
| PostgreSQL 18 | Stable | 전체 계약 suite, 릴리스 lane(자기 matrix job) |
| PostgreSQL 19 | Experimental | main.yml의 jpa-next job — NOT_EXECUTABLE: postgres:19-alpine이 게시되지 않아 그 major의 컨테이너를 띄운 적이 없다. 승격에는 ADR이 필요하다 |
| H2 | Local convenience | PostgreSQL 동작의 증거가 절대 아니다 |
major마다 자기 릴리스 job이 있다. release.yml의 jpa-release-gate job이 major마다 job 하나로 펼치고, 승격 job은 세
major의 증거가 모두 같은 커밋 SHA를 지니기를 요구한다. 그래서 major 하나가 빠지면 그 증거가 아니라 릴리스가 빠진다.
JpaPlatformContractSupport.start()는 여러 버전 선택을 아예 거부한다.
이력: 한동안 그렇지 않았다. 릴리스 lane이
-Pjpa.matrix.versions=16,17,18을selectedVersions().get(0)을 쓰는JpaPlatformContractSupport.start()에 넘겼으므로, 통합 suite 전체가 PostgreSQL 16에만 돌았다. 이 표는 단언 셋짜리 smoke test를 근거로 17과 18을 전부 덮었다고 적었다.
provider 기준선. gate는 Spring Boot BOM이 푸는 Hibernate 버전 7.1.8.Final에서 돈다. registry는 그것을
stable-tested-baseline으로 기록한다. 7.4는 compatibility-target으로 기록하고, 전체 lane이 실제로 그 버전에서 돈 뒤에
기준선이 된다.
이력: 이 문서는 전에 7.4를 Stable 기준선이라 불렀고 페이지네이션 gate 이름도
hibernate-7.4-fetch-pagination이었다. 그래서 그 gate를 돌릴 때마다 한 번도 돌려 보지 않은 provider 이름이 붙은 증거가 나왔다.
H2는 두 번째 운영 대상이 아니다. 같은 위반에 다른 SQLSTATE를 보고하고, JSONB 연산자도, range 타입도, 동시 인덱스 빌드도 없다. H2에서 통과한 실행은 코드가 컴파일되고 돈다는 증거일 뿐이다.
SKIP LOCKED는 따로 한 문장이 필요하다. 두 문서가 다른 말을 했기 때문이다. 모듈의 AGENTS.md는 측정을 기록한다.
H2 2.4.240은 FOR UPDATE SKIP LOCKED를 받고 잠긴 행을 정말로 건너뛴다. 그래서 outbox claim SQL이 두 vendor에서 같다. 이
문서는 전에 H2에 그런 보장이 없다고 했다. 둘은 서로 다른 질문에 각각 맞았고, 그 구별이 요점이다. 측정한 버전에서 관찰한
동작은 운영 보장이 아니고, PostgreSQL 계약 증거는 더욱 아니다. 측정 덕분에 claim SQL에 vendor 분기가 필요 없고, 보장이
없으므로 모든 동시성 계약은 여전히 실제 PostgreSQL에서 돈다.
명세와 provider
| 구성 요소 | Stable | Experimental |
|---|---|---|
| Jakarta Persistence | 3.2 | 4.0 (lane) |
| Hibernate ORM | 7.4 선언 기준선 | 8 (lane) |
| Spring Boot | 저장소 BOM | — |
Hibernate 줄에는 설명이 필요하다. 설계서는 7.4를 Stable provider로 선언하고, 이 저장소의 Spring Boot BOM은 7.1.x를 푼다.
HibernateProviderPolicy가 둘을 다 가진다. 선언 기준선은 상수로, 풀린 버전은 Hibernate 자신에게서 읽는다.
driftsFromDeclaredBaseline()이 상수를 상수와 비교하는 대신 그 차이를 드러낸다.
repository-adaptation.md §4를 본다.
capability 지원 수준
수준은 jpaplatform actuator 엔드포인트가 JpaPlatformReport.platformCapabilities()로 보고하는 값이다. 마지막 세
줄(기술 감사, multi-tenancy, read replica)은 그 보고에 없고 이 문서가 정한다. Advanced와 Experimental 줄은 서비스가 직접
부르는 라이브러리 코드다(src/adapter/outbound/persistence-jpa/README.md 「라이브러리 API」).
| capability | 수준 |
|---|---|
| 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 |
Advanced (admin 자격 증명 필요) |
| Hibernate second-level cache | Advanced |
| Hibernate Envers | Advanced |
기술 감사 — audit/AuditableEntity |
Stable (canonical) |
| Multi-tenancy (column, RLS, schema, database) | Experimental |
| 일관성을 아는 read replica | Experimental |
릴리스 gate
줄마다, 플랫폼이 테스트를 통과하고도 운영에서 틀릴 수 있는 길 하나다.
| Gate | Kind | 막는 것 |
|---|---|---|
postgresql-contract |
gate | DB 증거가 H2에서만 나온 릴리스 |
completion-unknown-no-retry |
gate | 이미 커밋됐을 수 있는 쓰기를 자동으로 다시 돌림 |
osiv-disabled |
gate | view 계층에서의 lazy loading, 렌더링한 행마다 쿼리 하나 |
flyway-validate |
gate | Hibernate가 배포된 스키마를 바꾸거나, 맞지 않는 스키마에서 돎 |
runtime-role-no-ddl |
gate | 애플리케이션 자신의 자격 증명으로 스키마 객체를 바꾸거나 지울 수 있음 |
collection-fetch-pagination |
gate | 페이지 단위 collection fetch가 몰래 테이블 전체를 읽고 메모리에서 페이지를 나눔 |
감사 방식
감사 방식은 audit/AuditableEntity 하나다. created_*/updated_*, 256자 actor이고, repository 어댑터가 명시적으로
찍는다. 서비스의 엔티티는 이것을 상속하고, 마이그레이션도 이 열에 맞춰 썼다. 두 번째 방식인 Spring Data listener 기반
(auditing/AuditMetadata)은 한 번도 조립되지 않아서 지웠다. JpaAuditMechanismRule.entitiesUseExactlyOneAuditMechanism이
그것이 엔티티에 돌아오지 못하게 막는다.
이 방식은 bulk·native update에 닿지 않는다. 어댑터의 보통 save에서 찍으므로, DB로 바로 가는 문장은 감사 열을 앞 save의
값으로 남긴다. 그래서 감사 대상 엔티티의 bulk update는 문장 안에서 감사 열을 설정해야 하고,
JpaAuditMechanismRule.bulkUpdatesOfAuditedEntitiesStampAudit가 운영 그래프에서 그것을 확인한다.
지원하지 않는다고 밝힌 것
- Reactive JPA. JPA는 blocking 명세다. 그 위의 reactive facade는 blocking 호출을 없애는 게 아니라 event loop로 옮긴다.
- 운영 스키마를 쓰는 Hibernate.
ddl-auto는 배포된 스키마를 절대 바꾸지 않는다. - 플랫폼이 가진 generic CRUD repository. 도메인이 자기 repository를 가진다(설계서 §10.1).
- 완료를 모르는 트랜잭션의 자동 맞추기. 플랫폼은 기록하고, 도메인이 푼다.