Files
clean-architecture-backend-…/src/adapter/outbound/persistence-jpa/README.md
T
DongHyeonka 354b7fc959
pr / done (pull_request) Canceled after 0s
fix(observability)!: 지표·MDC·헤더 registry를 코드가 실제로 내는 것과 맞춘다
관측 registry가 코드와 양쪽으로 어긋난다. metrics.yaml에는 아무 코드도
등록하지 않는 행 열하나와 코드에 없는 tag 값이 있고, 코드가 등록하는
graphql·notification·http.client·fileserver·mongodb·jpa.query 지표 다수가
없다. mdc-keys.yaml은 18키 중 코드가 넣는 5키만 맞고 required_in이 틀렸다.
headers.yaml은 X-Request-Id·X-Correlation-Id를 ulid로 적고 아무도 쓰지
않는 Deprecation·Sunset·tracestate를 적는다. 전송마다 correlation 규칙이
다른데 registry는 하나로 적는다. 단일 인스턴스 in-process lock은
lock.acquisition을 세지 않아 그 지표가 0이다. 밑줄 든 meter 이름 둘이
이름 규칙을 어긴다.

- 행마다 등록하는 main 파일(source)·상수(constant)·등록 주체
  (registered_by)를 적고, MetricsRegistryCodeAlignmentTest가 행 → 코드(이름이
  상수면 그 상수를 쓰는 곳까지)와 코드(글자·상수 이름의 builder·registry·
  Metrics 호출) → 행 두 방향을 본다. 템플릿이 부르지 않는 공개 메서드로만
  생기는 job.* 행은 emitted_when을 적는다. 버린 안: 행만 지우기(새 지표가
  다시 빠진다).
- mdc-keys는 5키와 전송별 표, headers는 source가 든 33행(서비스 controller용
  상수는 service: 출처), StructuredLog·HeaderRegistry 시험이 코드 상수와
  집합을 대조한다. 두 registry 시험은 시험 도우미 MainSources를 같이 쓴다.
- slo_driven 행은 MetricsDistributionMeterFilter 대상과 같은 집합이다(두
  방향 시험). histogram을 켜지 않는 hikaricp timer 행은 평균으로 경보한다.
  graphql.datafetcher·dataloader 행에 Spring 기본 tag를 적는다.
- in-process lock을 MeteredDistributedLock으로 감싼다.
- http.client.ratelimit.rejected, fileserver.upload.offset.mismatch로
  이름을 바꾸고 http.client.circuit.state.rejected를 상수로 둔다.
- CardinalityBounds(status 40·outcome 6·uri), MetricNaming 단위 규칙,
  SLO filter 대상(http.server.requests·jvm.gc.pause)을 문서와 맞춘다.

위험: 지표 이름 둘이 바뀌고 단일 인스턴스 lock 지표가 생긴다. 그 이름으로
만든 대시보드·경보를 옮겨야 한다(docs/upgrade/2026-11-round9-observability.md
8~13행). ApachePoolMetricsBinder·MongoTransactionRetry 지연은 다른 묶음이
맡는다.

검증: 위와 같은 desktop 실행(묶음 셋을 합친 트리) rc=0.

Refs: RR9-02-05, RR9-02-07, RR9-02-08, RR9-02-27, RR9-03-05
BREAKING CHANGE: http.client.rate_limit.rejected → http.client.ratelimit.rejected,
  fileserver.upload.offset_mismatch → fileserver.upload.offset.mismatch,
  CardinalityBounds 상수. docs/upgrade/2026-11-round9-observability.md 8~13행.
2026-11-13 13:12:27 +09:00

76 KiB
Raw Blame History

adapter-persistence-rdbms — 설계 결정 참조

RDBMS/JPA 퍼시스턴스 베이스 모듈. 패키지 루트: dev.caskeleton.adapter.persistence.

허용/금지 의존과 테스트 명령은 AGENTS.md 가 정본이다. 계약 테이블(TransactionPort 모드표, SQLState → Error Code 매트릭스, auditing 계약, vendor·lane 표)은 이 문서 끝 「지역 규칙에서 옮긴 표와 계약」 절이 정본이다. 나머지는 코드 주석에서 덜어낸 설계 결정의 근거를 모아둔 참조용 기록이다 — 코드를 읽다 "왜 이렇게 했나"가 궁금할 때 본다.

capability 모듈로 쓰기 — 제공하는 것, 추가할 한 줄, 필요한 env

템플릿 기본 조립에는 이 모듈이 없다. 관계형 저장소가 필요한 서비스는 src/bootstrap/app/build.gradle에 한 줄을 넣는다.

runtimeOnly project(':adapter:outbound:persistence-jpa')

그 줄을 지우면 아래 전부가 함께 사라진다. 다른 파일은 고치지 않는다.

제공하는 것 (모듈이 있으면 켜진다. APP_PERSISTENCE_JPA_ENABLED=false면 완전히 꺼진다: 이 모듈의 bean과 함께 Boot의 JDBC·Hibernate·Spring Data JPA·Flyway 자동 설정도 spring.autoconfigure.exclude에 추가되므로 DataSource·풀·EntityManagerFactory·Flyway가 만들어지지 않고 DB 없이 기동한다. 그래서 DB가 필요한 다른 capability(notification·fileserver 저장소, messaging JDBC outbox/inbox 등)와 함께 끌 수는 없다)

  • 포트 구현: TransactionPort(SpringTransaction), DistributedLockPort(단일 인스턴스는 in-process, APP_MULTI_INSTANCE_ENABLED=true면 JDBC INT_LOCK = distributedLockProvider. 둘 다 MeteredDistributedLock 데코레이터 안에 있다), outbox store(OutboxStorePort, APP_OUTBOX_ENABLED=true), PostgreSQL 멱등성 store(APP_IDEMPOTENCY_PROVIDER=postgresql), audit·operation·live-event store.
  • 엔티티/리포지토리 스캔, vendor 조립(PostgreSQL 기본, H2는 개발용), Flyway 위치.
  • 기동 정책(startup 패키지, JpaStartupAutoConfiguration): Flyway 마이그레이션 전략 (migrationStartupRunner, 실패 시 exit 70), datasource env 확인(exit 78), 실제 DB 제품·버전 확인, OSIV·DDL·Hikari·TLS·H2 금지 가드(prod exit 71), /actuator/jpaplatform(actuator가 있을 때만).
  • 스위치의 환경 처리(JpaActivationEnvironmentPostProcessor, 모듈의 spring.factories): 켜져 있으면 readiness 그룹에 db 추가, 꺼져 있으면 Boot의 jdbc·hibernate·data.jpa·flyway 자동 설정 패키지를 spring.autoconfigure.exclude에 추가(기존 값은 유지).
  • 기본 설정 config/module-defaults/persistence-jpa.yml(spring.datasource/flyway/jpa, app.persistence*, app.lock.*, app.outbox.*, app.realtime.replay.*, app.runtime.migration-on-startup). support 모듈의 ModuleDefaultsEnvironmentPostProcessor가 가장 낮은 우선순위로 읽으므로 애플리케이션 설정과 환경변수가 언제나 이긴다.

outbox relay(스케줄러)는 이 모듈이 아니라 조립 모듈 :composition:outbox-relay의 OutboxRelayAutoConfiguration이 조립한다. use case를 만들고 구동하는 일은 driven adapter의 몫이 아니기 때문이다. 그 설정은 이 모듈이 주는 OutboxStorePort와 messaging이 주는 OutboxMessagePublishPort가 모두 있을 때만 켜진다.

durable operation HTTP 엔드포인트(POST /operations·GET·DELETE /operations/{id})도 같은 이유로 composition:durable-operation의 DurableOperationAutoConfiguration이 조립한다. 이 모듈이 주는 operation store와 outbox append 포트(APP_OUTBOX_ENABLED=true)가 모두 있을 때만 켜진다. submit·cancel에는 operation-submit 역할(operation:submit, operation:cancel)이 필요하다.

애플리케이션이 제공해야 하는 bean: Clock, DomainContextPropagator(app-bootstrap이 제공).

필요한 env 키 (.env.example, 레지스트리 docs/registries/env-keys.yaml)

용도 키
연결(필수) APP_DATASOURCE_URL, APP_DATASOURCE_USERNAME, APP_DATASOURCE_PASSWORD(prod 필수 secret), APP_DATASOURCE_DRIVER
스위치·vendor APP_PERSISTENCE_JPA_ENABLED(기본 true), APP_PERSISTENCE_VENDOR(postgresql|h2), APP_FLYWAY_ENABLED, APP_MIGRATION_ON_STARTUP
풀 APP_DATASOURCE_POOL_MAX_SIZE, APP_DATASOURCE_POOL_MIN_IDLE, APP_DATASOURCE_CONNECTION_TIMEOUT, APP_DATASOURCE_POOL_IDLE_TIMEOUT, APP_DATASOURCE_POOL_MAX_LIFETIME
JPA APP_DATASOURCE_DDL_AUTO, APP_DATASOURCE_SHOW_SQL, APP_DATASOURCE_FORMAT_SQL, APP_DATASOURCE_OPEN_IN_VIEW, APP_JPA_HIBERNATE_*
선택 기능 APP_OUTBOX_ENABLED, APP_OUTBOX_RELAY_ENABLED, APP_MULTI_INSTANCE_ENABLED(합성 루트 소유, 락 provider 선택), APP_IDEMPOTENCY_PROVIDER=postgresql, APP_REALTIME_REPLAY_ENABLED, APP_REALTIME_REPLAY_RETENTION

라이브러리 API — 서비스의 어댑터 leaf에서 implementation으로 받아 직접 호출

아래 타입은 어떤 설정도 bean으로 만들지 않는다. 쓰려면 서비스의 어댑터 leaf가 implementation project(':adapter:outbound:persistence-jpa')를 선언하고(registry allowed_dependencies에 그 edge가 있어야 한다) 자기 코드에서 생성·호출한다. runtimeOnly로는 컴파일되지 않는다(AGENTS.md capability 규칙의 라이브러리형 예외). Envers는 이 leaf에서 compileOnly이므로 쓰는 서비스가 org.hibernate.orm:hibernate-envers를 직접 추가한다. Querydsl은 querydsl-core의 Predicate만 쓴다(compileOnly, 버전은 Boot BOM). JPA 질의(JPAQuery)가 필요한 서비스는 querydsl-jpa를 직접 더한다. 단 com.querydsl:querydsl-jpa 5.1.0에는 CVE-2024-49203(orderBy를 통한 HQL injection)이 있고 고친 버전이 없다. 쓰려면 OpenFeign 포크(io.github.openfeign.querydsl)를 검토한다. "PG"는 postgresqlIntegrationTest(실제 PostgreSQL) 테스트다.

패키지 진입점 동작을 증명하는 테스트
springdata JpaRepositoryFragmentSupport(커스텀 fragment 베이스) + RegisteredQuery JpaRepositoryFragmentSupportTest
springdata SafeSortRegistry·SafeSortMapper(클라이언트 정렬 → 등록 컬럼) SafeSortMapperTest, KeysetOrderingContractTest
springdata, api.query JpaKeysetQuerySupport·KeysetPredicateBuilder + KeysetPageRequest·KeysetSlice JpaKeysetQuerySupportTest, KeysetSliceAssemblerTest, KeysetOrderingContractTest
springdata FetchPlanApplier + EntityGraphCatalog FetchPlanApplierTest
springdata JpaStreamExecutor + ScrollPolicy JpaStreamExecutorTest, ScrollPolicyTest
api.query SignedJsonCursorCodec(서비스가 CursorPayloadCodec 구현), QueryName SignedJsonCursorCodecTest, QueryNameTest
hibernate.batch HibernateJpaBatchExecutor + JpaBatchProfile·HibernateStatisticsCollector·JdbcBatchCounter HibernateJpaBatchExecutorTest, HibernateBatchConfigurationGuardTest, HibernateStatisticsCollectorTest, PG HibernateJpaBatchExecutorIntegrationTest
hibernate.bulk HibernateBulkDmlExecutor PG HibernateBulkDmlExecutorIntegrationTest
hibernate.stateless HibernateStatelessSessionRunner PG HibernateStatelessSessionRunnerIntegrationTest
hibernate NamedStatementInspector(spring.jpa.properties.hibernate.session_factory.statement_inspector로 켬) NamedStatementInspectorTest
postgresql.error PostgreSqlExceptionTranslator.with(PostgreSqlConstraintCatalog) → api.error 예외 계층 PostgreSqlFailureClassifierTest, PostgreSqlConstraintCatalogTest, PG PostgreSqlSqlStateContractTest·ConstraintRaceContractTest
postgresql.lock PostgreSqlLockExceptionTranslator.standard(), PostgreSqlLockOptions PostgreSqlLockOptionsTest, PG PostgreSqlPessimisticLockContractTest
postgresql.json PostgreSqlJsonQuerySupport + JsonDocumentCodec·JsonDocument PG PostgreSqlJsonbContractTest
postgresql.array, .range PostgreSqlArraySupport, PgRange·PgRangeCodec PgRangeTest, PG PostgreSqlArrayRangeContractTest
postgresql.copy RegisteredPostgreSqlCopyLoader(admin DataSource + CopyAdminCapability) PG PostgreSqlCopyLoaderIntegrationTest
envers HibernateEnversHistoryReader, EnversConfigurationGuard PG EnversHistoryContractTest
querydsl PredicatePolicy, QueryPage(서비스가 만든 JPAQuery 앞에서 검사) PredicatePolicyTest
cache HibernateCacheGuard, HibernateCachePolicy, CacheRegionCatalog HibernateCacheGuardTest
observation MicrometerQueryObservation(위 executor에 QueryObservation으로 전달), SqlDiagnosticRedactor JpaObservabilityContractTest, JpaMetricTagsTest
experimental tenant·RLS·schema·database·replica 진입점 — 목록은 docs/jpa/experimental-support-matrix.md ExperimentalFailClosedTest, PG platform/experimental/*

metric은 기본으로 하나도 나오지 않는다. jpa.query.*는 서비스가 MicrometerQueryObservation을 넘길 때만 기록된다(docs/jpa/observability.md). 2026-09-25에 지운 항목(단일 구현 인터페이스, 아무도 읽지 않는 app.jpa-platform.addons-enabled·backend.jpa.experimental.*, main의 promotion gate, 생성하는 곳 없는 JpaTransactionObservation 등)은 docs/capability-status.md "제거된 코드"에 있다.

transaction — SpringTransaction

왜 모드별 템플릿을 미리 만들어 두나

TransactionTemplate 은 문서상 thread-safe 지만 mutable 하다. 매 호출마다 propagation / readOnly 를 바꿔 쓰면 같은 빈을 공유하는 동시 요청 사이에 race window 가 생긴다. 모드별로 (WRITE / READ_ONLY / REQUIRES_NEW) 템플릿을 생성 시점에 하나씩 만들어 두면 그 race 가 사라지고, 각 모드를 따로 감사(audit)할 수 있다. isolation 은 템플릿이 아니라 pool 에 READ_COMMITTED 로 고정한다(모드표와 이유는 아래 「TransactionPort 구현 계약」).

왜 inRootWrite가 별도 템플릿이나 NEVER propagation을 만들지 않나

inRootWrite의 실행 속성은 inWrite와 같은 WRITE + REQUIRED + READ_COMMITTED라 기존 write template을 재사용한다. 차이는 실행 전 precondition이다. TransactionSynchronizationManager.isActualTransactionActive()가 true이면 action과 PlatformTransactionManager를 호출하기 전에 NestedRootTransactionRejectedException으로 fail-fast한다. REQUIRES_NEW로 suspend해서 "root처럼 보이게" 하지 않으므로 호출자 transaction과 독립 commit되는 silent 의미 변경이 없다.

TransactionTemplate.execute는 commit까지 성공한 다음 값을 반환한다. 따라서 inRootWrite의 결과는 post-commit에만 호출자에게 보이고, commit 실패는 값 대신 원래 transaction 예외로 전파된다. 이 보장은 action이 외부 객체를 직접 변경하는 것을 되돌리는 보상이 아니라, 경계의 반환값을 성공으로 노출하지 않는 계약이다.

audit — AuditableEntity / AuditContextPort / DomainContextAuditContext

캡처 메커니즘 — Manual explicit-set (D1 현재 스켈레톤 기본값)

AuditableEntity 의 네 필드(created_at / updated_at / created_by / updated_by)는 평범한 @Column 이다 — Spring Data 의 @CreatedDate/@LastModifiedDate/@CreatedBy/@LastModifiedBy 도, @EntityListeners(AuditingEntityListener.class) 도 붙이지 않는다. 퍼시스턴스 어댑터가 initializeAudit(INSERT) 와 carryCreation + applyModification(UPDATE)로 명시적으로 값을 세팅한다. 공유 Clock 빈(D4)과 AuditContextPort actor(D5)를 재사용한다.

  • INSERT 는 created_* 와 updated_* 를 같은 now/actor 로 찍는다. NOT NULL 인 updated_* 를 신규 row 에서 채우기 위함이며, JPA-auditing 의 modifyOnCreate 기본동작에 의존하지 않는다.
  • UPDATE 는 두 단계다: carryCreation 으로 (Vernon Option A 재구성된) 엔티티가 잃어버린 created_* 를 다시 채워 넣고, applyModification 으로 updated_* 만 옮긴다.
  • created_* 는 updatable = false 라 INSERT 이후 모든 UPDATE 문에서 제외된다 — 생성 actor/시각이 덮어써질 수 없다.
  • version/optimistic-lock 은 여기 두지 않는다. 이 베이스는 audit 전용으로 남기고, 낙관적 잠금 정책은 개별 영속성 모델이 소유한다.

Growth path (D1, deferred — 구현 복제본 없음)

audited 애그리거트 수가 늘어 수동 세팅이 누락 위험을 키우면 Spring Data JPA Auditing 으로 이전할 수 있다. 다만 현재 leaf에는 두 번째 audit 모델을 미리 보관하지 않는다. 전환할 때 AuditableEntity의 같은 created_*/updated_* 스키마와 256자 actor 계약을 유지한 채 @EntityListeners(AuditingEntityListener.class)와 composition-owned AuditorAware / DateTimeProvider를 원자적으로 도입한다. bulk/native @Query UPDATE는 어느 방식에서도 listener를 우회하므로 audit column을 statement에서 명시적으로 갱신해야 한다.

actor seam 을 왜 별도 포트로 격리하나

AuditContextPort 는 퍼시스턴스가 "누가 행위하는가"에 대해 의존하는 단 하나의 seam 이다. actor 의 값 의미론(user id vs email vs subject claim)은 application/web 쪽의 사용자 모델 책임이고 여기서는 의도적으로 다루지 않는다. 그래서 타입을 String 으로 못박고, 이 포트가 보장하는 건 오직 "non-null actor"(프레임워크의 blank-on-absent 가 아니라) 하나 — principal 이 없으면 "system".

DomainContextAuditContext 는 actor id 를 runtime-context-propagation seam (DomainContextPropagator)에서 읽는다. 그 브랜치가 canonical actor key 를 소유하지만 API 가 확정되기 전까지 이 어댑터가 ACTOR_KEY 뒤로 격리해, 키가 바뀌어도 정확히 한 클래스만 손대게 한다(D5 Open Risk). 빈/blank context 값은 null/blank actor 가 아니라 "system" 으로 떨어뜨려 scheduler / Flyway / anonymous 경로에서도 NOT NULL created_by/updated_by 를 항상 만족시킨다.

config — PersistenceJpaConfig

왜 명시적 @EntityScan / @EnableJpaRepositories 가 필요한가

Spring Boot 메인 클래스는 dev.caskeleton.bootstrap 에 있어서, @AutoConfigurationPackage 가 앵커로 삼는 기본 엔티티/리포지토리 스캔이 dev.caskeleton.adapter.persistence.* 를 놓친다. @SpringBootApplication 의 scanBasePackages 는 컴포넌트 스캔만 넓힐 뿐 JPA 엔티티/리포지토리 스캔은 넓히지 않는다. 이 설정이 없으면 production 리포지토리(예: IdempotencyRecordJpaRepository) 가 생성되지 않아 소비자(예: IdempotencyReaper)가 부팅에서 와이어링 실패한다. 스캔을 엔티티를 소유한 모듈에 둬서 와이어링을 그 자리에 유지한다.

왜 이름이 JpaConfig 가 아닌가

서비스가 자기 설정 클래스에 JpaConfig 라는 이름을 쓰기 쉽다. 그러면 simple name JpaConfig 를 공유하는 두 @Configuration 이 기본 빈 이름 jpaConfig 에서 충돌한다 (ConflictingBeanDefinitionException). 다른 simple name 으로 이를 피한다. 처음 충돌한 곳은 지운 샘플 모듈의 JpaConfig 였다.

failure — 퍼시스턴스 실패 변환 SPI

매트릭스(SQLState → DB_* 코드, category, http, retryable)의 정본은 아래 「영속 실패 번역 계약 (feature-persistence-failure-baseline)」 절이다. 여기서는 SPI 구조와 fallback 근거만 적는다.

SPI-pluggable 설계 (vendor 추출)

PersistenceExceptionTranslator 는 exact-state → code 맵을 등록된 모든 SqlStateErrorMapping 빈을 생성 시점에 merge 해서 만든다. core 모듈(StandardSqlStateErrorMapping)은 모든 RDBMS 가 공통으로 반환하는 portable/vendor-neutral 5개 row(40001, 23502, 23503, 23505, 23514)만 기여한다. vendor 별 row(40P01, 25P03, 57014 등 PostgreSQL)는 adapter-persistence-postgresql 가 추가 SqlStateErrorMapping 빈으로 기여한다.

  • 서로 다른 contributor가 같은 exact SQLState를 등록하면 code가 같더라도 startup construction을 실패시킨다. last-writer-wins merge는 mapping ownership drift를 숨기므로 허용하지 않는다.
  • 08* connection-class prefix → DB_UNAVAILABLE 규칙은 맵 엔트리가 아니라 translator 가 직접 처리한다. 따라서 core 매핑 맵에는 08* 가 없다.
  • 커밋 단계는 따로 분류한다(ADR-JPA-003). SpringTransaction 은 본문이 끝난 뒤 자기가 연 쓰기 트랜잭션을 커밋하다 난 실패를 translateCommitFailure 로 보낸다. 여기서 08*·40003·벤더 종료 상태(commitOutcomeUnknownStates(), PostgreSQL 은 57P01·57P02)·SQLState 없는 전송 단절은 DB_UNAVAILABLE(재시도 가능)이 아니라 DB_COMPLETION_UNKNOWN(재시도 불가)이 된다. 서버가 이미 커밋했을 수 있어 재시도가 쓰기를 중복시키기 때문이다.
    • 커밋 전(연결 획득, 본문 실행) 연결 실패는 그대로 DB_UNAVAILABLE 이다. 풀 고갈·재시작까지 결과 불명으로 몰면 운영자가 그 신호를 무시하게 된다(ADR 의 "좁게" 원칙).
    • 커밋 단계 안에서 Hibernate flush 실패와 COMMIT 자체 실패는 구분하지 않는다. flush 중 연결 단절은 실제로는 롤백이지만 결과 불명으로 보고된다 — 중복 쓰기보다 불필요한 조정(reconciliation)이 싸다.
    • 읽기 전용 트랜잭션과 바깥 트랜잭션에 참여한 호출은 커밋할 쓰기가 없으므로 이 분류를 타지 않는다.
  • Fallback: 기여된 어떤 row 에도 없는 SQLState — 또는 cause chain 에 SQLException 자체가 없는 경우 — 는 Optional.empty() 를 반환한다. 호출부는 원본 예외를 web catch-all 까지 전파시켜 detail 누설 없는 generic INTERNAL 엔벨로프로 답하게 한다. translator 는 unknown state 에 대해 DB_* 코드를 절대 지어내지 않는다.
  • 변환된 carrier 의 진단 메시지에 SQLState 를 넣는 건 server-log 전용이다(web 어댑터가 절대 surface 하지 않음) — triage 를 돕되 클라이언트로 새지 않는다.

idempotency — PostgreSQL provider

app.capabilities.idempotency.provider=postgresql 일 때만 켜진다 (autoconfigure/PostgreSqlIdempotencyStoreConfig). 이 leaf 는 IdempotencyStorePort 구현 (PostgreSqlIdempotencyStore) 하나만 내놓고, executor 는 app-bootstrap 조립 모듈 :composition:idempotency의 IdempotencyAutoConfiguration이 만든다. V1 JDBC store 와 jdbc provider 값은 없다.

  • 스키마: 기본 테이블은 primary Flyway(db/migration/postgresql/V1__idempotency_record.sql)가, owner-safe 컬럼은 db/migration/jpa/idempotency stream 이 소유한다. 기동 시 IdempotencySchemaStream 이 db/migration/jpa/core → db/migration/jpa/idempotency 순서로 적용하고 capability registry 행을 ACTIVE 로 올린다. 알림 capability 의 NotificationSchemaStream 과 같은 방식이다. app.runtime.migration-on-startup=false 면 건너뛰고, 운영자가 적용·활성화할 때까지 store 가 fail closed 한다.
  • PostgreSQL 전용: data source 가 PostgreSQL 이 아니면 기동을 거부한다. bootRunH2 는 provider 를 disabled 나 redis 로 둔다.
  • 응답 크기: 완료 응답은 8 KiB 이하만 행에 inline 저장하고, 넘으면 거부한다.
  • 만료: claim 은 expires_at 을 처리 lease 끝 + replay TTL 로 두고, renew 는 lease 를 늘린 만큼 expires_at 도 뒤로 민다. 완료·실패 때 다시 앞으로 옮긴다. IdempotencyReaper (IdempotencyRecordJpaRepository 사용, 기본 10분 간격 reaper-interval)가 상태와 상관없이 지난 행을 지운다. 그래서 expires_at 이 lease 보다 먼저 오면 실행 중인 행이 지워지고 다음 claim 이 같은 작업을 다시 돌린다(재리뷰 2026-11-04 RR-03-11). 공유 계약의 PostgreSQL lane 은 시간을 흘린 뒤 이 reaper 를 실제로 돌려 이 경우를 본다. reaper 는 provider 가 postgresql 일 때만 돈다.
  • lease 가 지난 실행: lease 가 지난 EXECUTING 행은 넘겨받지 않고 RecoveryRequired 로 답하며, 행은 바꾸지 않는다. 주인이 늦게 complete·markFailed 하면 그대로 기록되고, 다음 claim 은 그 결과를 재생하거나 재시도한다. renew 는 이미 끝난 lease 를 늘리지 않고, lease 가 지난 CLAIMED 는 주인도 시작할 수 없다 — 둘 다 LEASE_EXPIRED(전에는 NOT_OWNER, 재리뷰 RR5-01-02). inspect 는 남의 lease 지난 실행을 ABANDONED 로 보고한다. Redis store 도 같다(IdempotencyStoreContract, RR-01-11, 2026-11-04 소유자 결정 — 전에는 행을 ABANDONED·EXPIRED_EXECUTION 으로 바꿔 늦은 결과를 버렸다).
  • 한 트랜잭션 안의 모양: executor 를 유스케이스의 쓰기 트랜잭션 하나 안에서 부르면(템플릿의 모양) claim 행은 그 트랜잭션이 끝날 때까지 커밋되지 않는다. 그래서 위의 "lease 가 지난 실행"을 다른 요청이 보는 일이 없다: 같은 키 요청은 on conflict 에서 기다렸다가 커밋이면 재생, 롤백이면 새 실행을 받는다. 롤백(작업 예외, 쓰기 트랜잭션 제한 30s)은 executor 가 남긴 실패 기록도 지운다. 이 store 가 막는 중복은 같은 트랜잭션 안의 DB 효과이고, 트랜잭션 밖 효과는 다음 요청에서 다시 일어날 수 있다 (PostgreSqlIdempotencyIntegrationTest, 재리뷰 RR5-01-05, docs/web/http-contract.md §2).

outbox — JpaOutboxStore 외

스키마는 Flyway(V3__outbox_event.sql)가 소유하고, V13__outbox_canonical_transport_compatibility.sql이 canonical metadata와 exact BYTEA envelope_bytes를 더했다. append 모델은 canonical 하나다(2026-09-28, 소유자 결정 7): JpaOutboxStore가 OutboxAppendPort(ValidatedIntegrationEvent)와 OutboxStorePort를 함께 구현하고, app.outbox.enabled=true일 때만 존재한다. row는 validated event의 exact envelope bytes와 hash를 저장하고, claim은 그 bytes로 같은 event를 복원한다 (ClaimedOutboxEvent). event_type·aggregate_id·correlation_id는 claim gate와 metrics query를 위해 contract id·aggregate id·correlation id를 한 번 더 적는다.

V19__outbox_event_canonical_only.sql은 pre-canonical row가 더 없다는 것을 DB에 적는다: envelope 없는 미발행 row가 남아 있으면 migration이 실패하고(이전 릴리스로 relay를 비우거나 손으로 정리한 뒤 다시 적용한다), 이후로는 PUBLISHED가 아닌 row에 canonical metadata가 반드시 있다 (ck_outbox_event_canonical_unless_published). pre-canonical payload·idempotency_key 컬럼은 nullable로 남고 아무것도 쓰거나 읽지 않는다 — 이전 릴리스로 되돌릴 때를 위해 지우지 않았다.

트랜잭션 경계 계약

  • append: 호출자의 TransactionPort.inWrite() 경계 안에서 호출되어야 하며, 내부에서 새 트랜잭션을 열지 않는다. @Repository 가 빈만 등록하고 TX 는 use case 가 소유한다.
  • Application write 경계에는 adapter-local @Transactional을 추가하지 않는다: 여러 port를 하나의 원자 작업으로 묶는 경계는 use case의 TransactionPort가 소유한다. 예외는 adapter 자체가 하나의 저장소 프로토콜을 구현하는 내부 원자 단위다. 예를 들어 durable operation의 claim은 UPDATE ... RETURNING 후 같은 claim을 읽어야 하고, live-event append는 position allocator와 event insert가 함께 commit돼야 한다. 이런 메서드의 로컬 transaction은 application transaction을 대체하는 것이 아니라 port 자체의 atomic semantics다.

claim 계약 — vendor SPI (OutboxClaimRepository)

row claim 은 vendor 별 락 전략이 필요해 OutboxClaimRepository SPI 로 추출했다. canonical PostgreSQL 구현은 native query 의 FOR UPDATE SKIP LOCKED 를 쓰고, 다른 벤더는 등가물을 공급한다(예: SQL Server WITH (UPDLOCK, READPAST)). eligibility predicate(I3 — concurrent-relay 안전을 위한 SKIP LOCKED)와 per-aggregate FIFO gate(I4 — NOT EXISTS correlated subquery)를 전부 SQL 에서 강제한다. 한 배치에 aggregate 당 최대 한 row(head)만 나타난다. 어댑터는 추가 in-memory 필터링을 하지 않는다 — 리포지토리가 반환한 모든 row 를 IN_FLIGHT 로 전이시켜 호출자에 돌려준다. 전체 SQL gate 동작은 PG contract 테스트(Testcontainers)가 검증한다.

FIFO gate 의 "같은 aggregate"와 "앞선 row":

  • canonical row 끼리는 (tenant_scope, aggregate_type, aggregate_id) 가 같아야 같은 aggregate 이고, 순서는 (aggregate_sequence, event_index) 다. 그래서 occurred_at 이 같은 이벤트도 한 번에 하나씩 나가고, 다른 tenant·type 의 DEAD row 가 같은 aggregate_id 를 막지 않는다. 인덱스는 V18 의 ix_outbox_event_unpublished_aggregate_order.
  • gate 가 비교하는 row 는 전부 canonical 이다: V19 가 envelope 없는 미발행 row 를 거부한다.

읽을 수 없는 row(envelope 없음, 부분 metadata, 저장된 hash 와 bytes 불일치 등)는 claim 에서 DEAD 로 옮기고 배치에서 뺀다. 예전에는 예외로 claim transaction 전체가 롤백되고 다음 claim 이 같은 row 를 다시 먼저 골라 relay 가 영구히 멈췄다. 추측해서 발행하지 않으므로 fail-closed 는 유지된다.

eligible row(I3/I4/I6):

  • PENDING — next_attempt_at <= now(insert 시 즉시 eligible)
  • FAILED — next_attempt_at <= now(backoff 경과)
  • IN_FLIGHT — next_attempt_at <= now(orphaned row)

claim lease와 fencing token (V17)

in-flight timeout이 지나면 다른 relay가 IN_FLIGHT row를 다시 claim한다. 예전 완료 처리는 event_id만으로 row를 읽어 status를 덮어썼고 claim·publish·완료가 서로 다른 transaction이라, timeout을 넘겨 멈췄던 relay A가 relay B의 결과를 덮을 수 있었다 — B가 PUBLISHED로 만든 row를 A가 FAILED로 바꾸면 다시 발행되고(중복 전달), A의 늦은 PUBLISHED는 B의 실패를 가린다.

  • claim: claimBatch(owner, ...)가 row lock(FOR UPDATE SKIP LOCKED)을 쥔 상태에서 lease_owner = owner, lease_token = lease_token + 1을 기록하고 OutboxLease(event, owner, token)을 돌려준다. owner는 relay 인스턴스(PublishPendingOutboxEventsUseCase)마다 한 번 만든 UUID다.
  • 완료: markPublished/markFailed/markDead(lease)는 한 문장의 조건부 UPDATE다 — WHERE event_id = ? AND status = 'IN_FLIGHT' AND lease_owner = ? AND lease_token = ?. owner는 비우고 token은 그대로 둔다(token은 증가만 한다). 1 row면 APPLIED, 0 row면 STALE. findById + setter 경로와 @Version은 쓰지 않는다.
  • 실패 원인 코드(V22): markFailed·markDeferred·markDead는 같은 조건부 UPDATE에서 last_failure_code를 쓴다(publisher가 붙인 코드, 없으면 결과·예외 타입 이름). append INSERT는 이 열을 쓰지 않는다. claim이 행을 DEAD로 옮길 때(ATTEMPT_COUNTERS_INCONSISTENT, UNREADABLE_ROW)는 claim의 row lock 아래 entity flush로 그 이유를 쓴다 — 앞선 발행 실패의 코드가 남아 원인을 잘못 가리키지 않게(재리뷰 2차 RR-02-12). 이 DEAD는 relay 결과를 거치지 않아 outbox.publisher.published.total{outcome=DEAD}에 안 잡히므로 경보는 outbox.pending.size{status=DEAD}로도 건다. longRetries(n, now)는 미룬 claim이 n번 이상인 FAILED 행 수와 가장 오래된 행의 나이를 센다(outbox.retry.long.* 게이지). 상태 PARKED는 DDL이 없다 — claim이 PENDING·FAILED·IN_FLIGHT만 고르고, FIFO 게이트는 PUBLISHED 아닌 모든 행을 막는 앞 행으로 본다. claim이 시도 횟수가 어긋난 행(deferred_attempt_count > attempt_count)을 만나면 DEAD로 옮기고 WARN error.reason=ATTEMPT_COUNTERS_INCONSISTENT로 원인을 말한다(재리뷰 2026-11-03 RR-05-01·03).
  • 미룬 실패와 claim 해제(V20): markDeferred(lease, next)는 markFailed와 같은 전이에 deferred_attempt_count + 1을 더한다(일시적 실패는 시도 예산 밖). releaseLease(lease, at)는 손대지 않은 claim을 PENDING, next_attempt_at = at, attempt_count - 1로 되돌린다(종료 중인 relay가 쓴다). 둘 다 같은 lease 조건부 UPDATE다.
  • aggregate 순서 번호(V21): JpaOutboxStore는 OutboxAggregateSequencePort도 구현한다. outbox_aggregate_sequence counter를 UPDATE(row lock)로 올린다. 올린 값은 그 aggregate의 가장 큰 outbox 번호보다 작아지지 않는다(rolling 배포 중 옛 인스턴스가 쓴 벽시계 번호가 먼저 온다). counter가 없으면 INSERT ... ON CONFLICT DO NOTHING으로 만든다. 시작값은 남은 outbox 최대 번호와 V21이 기록한 floor(outbox_aggregate_sequence_floor, V21 적용 시각의 epoch 마이크로초) 중 큰 값 + 1이다. 첫 쓰기 두 개가 겹치면 두 번째는 첫 번째 커밋을 기다렸다가 아무것도 넣지 않고 증가만 한다(리뷰 RR-03-01). V21은 남은 row가 있는 aggregate의 counter를 그 최대 번호로 미리 만들고, outbox_event의 순서 키 유일 인덱스도 만든다 — 기존 중복 row가 있으면 migration이 실패하므로 먼저 정리해야 한다 (docs/runbooks/outbox-dead-letter.md §8).
  • STALE은 예외가 아니다: row의 결과는 지금 lease를 가진 relay가 쓴다. use case는 결과를 OutboxRelayResult.Outcome.STALE로 남기고 OutboxRelayFailureReportPort.reportStaleCompletion 으로 알린 뒤 다음 이벤트로 넘어간다. FAILED/DEAD report는 보내지 않는다(아무것도 저장되지 않았다). outbox.publisher.published.total{outcome=STALE}이 0보다 크면 in-flight timeout이 relay 정지 시간보다 짧다는 뜻이고, broker는 그 이벤트를 두 번 받았을 수 있다.
  • row가 없을 때도 0 row라 STALE이다. 예전처럼 throw하지 않는 이유: fencing 뒤에는 0 row가 "다른 relay가 가져감"이라는 정상 결과이고, 그 row는 가져간 relay가 끝내거나 timeout 뒤 다시 claim되므로 FIFO 큐가 막히지 않는다.

OutboxEventEntity 의 결정

  • AuditableEntity 미상속(D6 — infra 엔티티). IdempotencyRecordEntity 처럼 outbox row 는 도메인 애그리거트가 아니라 인프라 record 다. 자체 temporal 필드(occurred_at, next_attempt_at)가 도메인 의미를 갖고, generic created_at/updated_at audit 컬럼과 섞이면 안 된다.
  • mutating setter 노출은 의도. claim은 lock된 managed 엔티티 위에서 상태(status / attempt_count / next_attempt_at / lease)를 전이시킨다. 완료는 setter가 아니라 lease 조건부 bulk UPDATE다. outbox 어댑터만 이 필드를 건드리고, 모든 mutation 이 use case 소유 TransactionPort.inWrite() 경계 안에서 돌기에 안전하다.
  • next_attempt_at dual-purpose(I6 — 추가 컬럼 없음):
    • PENDING: insert 때 occurred_at 으로 세팅 → 최초 claim 체크(next_attempt_at <= now)가 즉시 만족.
    • IN_FLIGHT: claim_time + in_flight_timeout → orphaned row 가 visibility window 만료 후 재claim 가능.
    • FAILED: now + backoff → backoff window 경과 후에만 재시도.
  • status 는 PENDING | IN_FLIGHT | PUBLISHED | FAILED | DEAD 문자열이다.
  • Persistable<String>(새 엔티티는 isNew() == true). 식별자를 직접 넣고 @Version 이 없는 엔티티를 Spring Data 는 기존 row 로 보고 merge 한다. 그래서 같은 event_id 로 두 번 append 하면 이미 PUBLISHED 된 row 가 PENDING·attempt 0 으로 덮여 다시 발행됐다. 이제 append 는 항상 insert 이고, 중복은 primary key 위반(23505)으로 드러난다.

metric 쿼리 반환 형태

OutboxEventJpaRepository.countGroupedByStatus() 는 [status(String), count(Long)], findOldestUnpublishedOccurredAtByEventType() 는 [eventType(String), oldestOccurredAt(Instant)] 2-요소 배열 리스트를 돌려준다(각각 outbox.pending.size, outbox.publisher.lag gauge 용). 두 쿼리 모두 PUBLISHED row 는 세지 않는다 — retention 기간 동안 테이블 대부분이 PUBLISHED 라, 매 poll 마다 테이블 전체를 세게 된다. JpaOutboxStore.oldestUnpublishedAgeSecondsByEventType 가 HashMap 을 쓰는 건 키가 enum 이 아니라 String(event-type 이름)이기 때문이다 — countByStatus() 는 키가 OutboxEventStatus enum 이라 EnumMap 을 쓴다(두 반환 타입이 의도적으로 다름). status 에는 CHECK 가 없어 이 버전이 모르는 상태(뒤 버전이 쓴 상태, 손으로 친 값)가 있을 수 있다. countByStatus() 는 그 상태만 빼고 세고 처음 한 번 WARN 으로 이름과 행 수를 말한다. 예전에는 그 이름 하나로 집계 전체가 실패해 PENDING 게이지까지 꺼졌다(재리뷰 2차 RR-02-11).

OutboxReaper

PUBLISHED row 는 이미 전달된 terminal-success record 라 무한 보관할 필요가 없다. reaper 가 retention 보다 오래된 PUBLISHED row 를 주기적으로 비워 테이블 성장과 metric gauge 를 묶는다. 스케줄링은 컴포지션 루트의 @EnableScheduling 으로 켜진다. 삭제는 deletePublishedBatch 로 1,000 row 씩, 배치마다 별도 transaction 으로 돌리고 배치가 덜 차면 멈춘다 — relay 장애 뒤 쌓인 PUBLISHED backlog 를 한 transaction 으로 지우면 그 사이 모든 row lock 을 쥔 긴 transaction 이 된다. 고정 interval / clock-skew 미처리는 프로젝트 선택(부하 하 cadence 측정 필요). retention 한 값은 reaper-local 이라 @Value 로 받지만, canonical 6-property 문서는 app-bootstrap OutboxSettings / application.yml 에 있다.

JPA 운영 capability 후보

src/adapter/outbound/persistence-jpa/release/readiness-cards.yaml이 capability와 독립 schema stream의 machine-readable SSOT다(개수는 registry가 소유한다). selected base card와 implemented-candidate reliability card를 구분하며, 실제 PostgreSQL 테스트 통과만으로 immutable 운영 evidence가 필요한 R2를 주장하지 않는다.

이미 쓰이는 테이블을 잠그는 migration은 그 잠금 앞에 SET LOCAL lock_timeout = '5s';를 둔다. 상한이 없으면 그 테이블을 건드린 열린 트랜잭션 하나 뒤에서 끝없이 기다리고, 그동안 뒤에 온 읽기·쓰기가 모두 migration 뒤에 줄을 선다(V22, 재리뷰 2차 RR-02-09). MigrationLockWaitTest가 이 leaf DB에 도는 모든 tree를 검사하고, postgresqlMigrationLockWaitIntegrationTest lane이 실제 PostgreSQL에서 상한 안에 실패하는지 본다 (docs/jpa/migration-guide.md "Bound the lock wait").

Flyway의 PostgreSQL 마이그레이션 잠금은 트랜잭션이 아니라 세션에 둔다. Flyway 기본값은 실행 내내 트랜잭션을 열어 두고, CREATE INDEX CONCURRENTLY·REINDEX … CONCURRENTLY는 그 트랜잭션이 끝나기를 기다려 배포가 끝나지 않는다(재리뷰 round6 RR6-03-01). Spring Boot의 Flyway는 config/module-defaults/persistence-jpa.yml의 spring.flyway.postgresql.transactional-lock: false로, 템플릿이 직접 만드는 Flyway는 FlywaySchemaPolicy.configure()로 받는다. 운영 코드가 Flyway.configure()를 직접 부르거나 Flyway 설정 객체를 직접 만들면(new FluentConfiguration(), new ClassicConfiguration(), 그 하위 클래스) JpaProductionArchitectureTest가 거부한다. 배포 마이그레이션 도구에도 같은 값을 넣는다 (docs/jpa/migration-guide.md "Who may change the schema", lane postgresqlConcurrentIndexMigrationIntegrationTest).

적용된 versioned migration은 수정하지 않는다. Flyway가 기동할 때마다 checksum을 검사하므로 바꾼 파일은 이미 그것을 적용한 모든 DB의 기동을 막는다. 변경은 새 버전으로 추가하고, src/test/resources/db/applied-migrations.sha256에 한 줄을 더한다 (AppliedMigrationImmutabilityTest가 검사). 2026-09-23~25 사이에 수정본 postgresql/V9·V13을 적용해 만든 개발 DB는 원복된 파일과 checksum이 다르므로 한 번 flyway repair가 필요하다. 그 사이 수정본이 바꾸려던 char(64)→varchar(64)는 V16이 한다.

독립 Flyway stream은 broad classpath:db/migration으로 함께 실행하지 않는다. 각 stream은 자기 location/history table을 사용하고 non-empty schema adoption 때 version 0 baseline을 명시한 뒤 V1부터 실행한다.

capability 위치 history 테이블 상태
core/adoption db/migration/jpa/core flyway_jpa_core_history selected candidate
idempotency db/migration/jpa/idempotency flyway_jpa_idempotency_history implemented-candidate

owner-safe idempotency

PostgreSqlIdempotencyStore는 row lock을 얻은 뒤 clock_timestamp()를 평가한다. claim takeover와 start/renew/complete/fail/release는 scope/state/owner/attempt/claim operation/ state revision을 SQL predicate로 다시 검증한다. expired CLAIMED(와 FAILED_RETRYABLE)만 takeover하며 expired EXECUTING은 행을 바꾸지 않고 reconciliation(RecoveryRequired)을 요구한다(2026-11-04 소유자 결정 — 이 문단은 그 전의 ABANDONED로 닫던 동작을 적고 있었다). takeover는 같은 attempt의 재생보다 먼저 본다. 시작을 거절당했거나 재시도 가능 실패로 끝난 attempt가 같은 attempt로 다시 claim해도 넘겨받는다(라운드6 RR6-02-01). raw client key는 저장하지 않고 versioned HMAC scope digest만 쓴다.

Redis store·in-memory fake와 같은 계약(IdempotencyStoreContract)을 실 PostgreSQL에서 통과한다 (PostgreSqlIdempotencyStoreContractTest, jpaPlatformContractTest). 그 계약에 맞춰 두 가지를 정했다(review 2026-11-01 01-05). 이전 revision의 핸들은 owner 튜플이 다르므로 NOT_OWNER다. OPERATION_CONFLICT는 둘이다. 하나는 owner token이 같은데 호출이 claim과 다른 operation id를 댄 경우로, 다섯 전이(start·renew·complete·fail·release) 모두 거절하고 행을 바꾸지 않는다. 같은 token·다른 operation의 inspect도 상태와 상관없이(완료된 행도) OPERATION_CONFLICT다(2026-11-06 소유자 결정 — 전에는 CAS가 핸들의 claim operation만 보고 호출의 id는 last_transition_operation_id에 적기만 해서 적용했다). 다른 하나는 같은 operation id가 다른 인자로 이미 적용된 경우다. 이미 기록된 전이는 그 전이를 적용한 핸들(owner identity가 같고 행보다 revision이 하나 낮은 핸들)에게만 재생으로 읽는다(2026-11-06 소유자 결정). 그 핸들이면 digest가 같을 때 "이미 처리됨", 다를 때 OPERATION_CONFLICT다. 다른 핸들은 재생이 아니라 owner 검사로 간다. 그래서 같은 operation id를 쓴 다른 attempt의 늦은 complete와, 같은 attempt가 넘겨받기 전 핸들로 다시 보낸 complete·markFailed·renew·release는 NOT_OWNER다(전에는 complete를 owner token만 보고 ALREADY_COMPLETED_SAME_RESULT로 확인했고, 나머지는 digest가 달라 OPERATION_CONFLICT였다). renew가 돌려준 핸들로 다시 renew하면 한 번 더 renew된다(전에는 앞 renew의 digest와 달라 OPERATION_CONFLICT였다). 시작은 핸들 말고 인자가 없어서, 넘겨받기 전 핸들은 NOT_OWNER, 재생받은 현재 핸들은 NOT_CLAIMED다(라운드6 RR6-02-01, 전에는 OPERATION_CONFLICT). release한 핸들로 시작하면 행이 남아 있어 NOT_OWNER다. 행을 지우는 Redis·fake는 ABSENT이고 계약은 둘 다 받는다. 실패는 disposition마다 전이 종류가 둘(FAIL_RETRYABLE·FAIL_ABANDONED)이라, 적용한 핸들이 다른 disposition으로 다시 보내면 종류가 달라 재생으로 읽히지 않고 NOT_OWNER였다. 두 종류를 모두 실패의 재생으로 읽어, 다른 disposition은 digest가 달라 OPERATION_CONFLICT다. fail digest에는 retention을 넣지 않는다 — complete의 replay TTL처럼 결과를 얼마나 보관하나일 뿐이라, retention만 다른 재전송은 "이미 처리됨"이고 처음 retention이 남는다(전에는 OPERATION_CONFLICT, 2026-11-07 소유자 결정). renew는 EXECUTING의 lease만 늘리고, 시작 전 CLAIMED는 NOT_IN_PROGRESS다.

outbox V2 (삭제됨)

immutable outbox storage·polling delivery V2(jpa/outbox-storage, jpa/outbox-polling stream과 그 adapter)는 어떤 composition도 location을 설정한 적 없는 미조립 세대라 2026-09-25에 삭제했다 (docs/capability-status.md "제거된 코드"). 실제로 도는 v1 outbox_event relay가 V2의 owner/token CAS를 이어받았다(위 "claim lease와 fencing token").

실제 PostgreSQL task

base task 외에 다음 candidate task가 Docker 부재 시 skip이 아니라 실패하도록 등록돼 있다.

postgresqlIdempotencyIntegrationTest

readiness card 검사 (evidence manifest 폐기)

readiness-cards.yaml의 evidence.scenarios와 evidence.task-claims가 required evidence를 실제 테스트와 task에 연결한다. build-tools의 JPA evidence manifest(ca.jpa-evidence, ca.jpa-qualification, verifyJpaCandidateEvidence, verifyJpaPrimaryFoundationEvidence, jpa-r2-evidence.yml)는 소유자 결정 4(2026-09-25)로 폐기했다. 그 manifest가 증명하던 사실은 이제 두 곳에서 확인한다.

  • JpaReadinessRegistryTest(이 leaf의 test): 카드 상태·선행 관계(순환 없음), 구현된 카드가 가리키는 이 leaf의 task가 build.gradle에 선언된 lane인지, 인용한 scenario 메서드가 src/postgresqlIntegrationTest에 있는지, required evidence가 모두 덮이는지, 소유 schema stream의 location·history table이 고유하고 존재하는지.
  • readiness lane 자체: 카드가 인용한 scenario마다 lane의 required test가 되고(requires), lane은 skip을 거절한다(rejectSkipped). 실제 PostgreSQL이 없으면 skip이 아니라 실패한다.
./gradlew :adapter:outbound:persistence-jpa:test --tests '*JpaReadinessRegistryTest' --console=plain
./gradlew :adapter:outbound:persistence-jpa:integrationTestLaneCheck --console=plain   # 모든 readiness·platform lane

R2(운영 evidence) 승격은 더 이상 build가 판정하지 않는다. clean revision에서 위 lane을 돌린 CI 결과(jpa-release job의 JUnit XML artifact)를 검토해 결정한다.

stream migration이 중단되면 history/registry/object 상태를 먼저 확인하고 기존 migration을 임의 수정하거나 history를 바로 repair하지 않는다. 장애를 수정한 forward migration으로 복구하는 운영 절차는 docs/runbooks/migration-failed.md를 따른다.

lock — 분산 락

provider 선택(flag → bean → registry)의 정본은 설정 코드 lock/DistributedLockPersistenceConfig(bean 이름 distributedLockProvider)다. 여기서는 어댑터/설정 결정 근거만 적는다.

LockRegistryDistributedLock 계약

  • D4 — transaction-commit ordering invariant. 이 어댑터는 트랜잭션 경계를 관리하지 않는다. 호출자는 보호된 트랜잭션이 커밋된 뒤에만 핸들(DistributedLock.close())을 release 해야 한다. 커밋 전(트랜잭션 안)에 release 하면 lost-update race 가 생긴다.
  • D5 — finite waitTime + lease TTL. tryAcquire 는 Spring Integration DistributedLock 이면 tryLock(waitTime, leaseTtl) 로, 일반 Lock 이면 Lock.tryLock(long, TimeUnit) 으로 최대 waitTime 만 블록하고, 잡으면 핸들을, 못 잡으면 LockAcquisitionTimeoutException 을 던진다. 무한 블로킹은 쓰지 않는다.
  • leaseTtl > configuredTtl 은 IllegalArgumentException 으로 거부한다. provider 기본 TTL 보다 긴 lease 를 약속하는 건 false contract 다. shipped 와이어링에선 leaseTtl == configuredTtl (둘 다 LockSettings.leaseTtl() 바인딩)이라 이 가드는 mis-wired 호출자/테스트에서만 fail-fast 로 발동한다.
  • 반환 핸들은 lock::unlock 람다(SAM 인터페이스 충족). InterruptedException 은 interrupt flag 를 복원하고 LockAcquisitionTimeoutException 으로 변환한다.

TTL 주의 (SI 7.0)

  • JdbcLockRegistry: 기본 TTL 은 JdbcLockRegistry(LockRepository, Duration) 생성자로 설정하고, acquisition 별 TTL 은 DistributedLock.tryLock(Duration waitTime, Duration ttl) 로 전달한다. 크래시한 JVM 의 row 는 lock TTL 만료 후 다음 acquire 시도에서 회수된다.
  • DefaultLockRegistry: TTL 은 advisory 이고 무의미하다 — JVM 크래시가 in-JVM 락을 프로세스와 함께 자동으로 떨군다.

SI-LOCK-C5 — lease 만료 후 release

반환 핸들은 lock::unlock 이다. lease TTL 이 close() 전에 만료된 JdbcLockRegistry 의 경우, 내부 JdbcLock.unlock() 이 ConcurrentModificationException 을 던진다(row 가 이미 회수됨). 이 어댑터는 여기서 일부러 잡지 않는다 — metered distributedLockProvider 데코레이터 (컴포지션 루트)가 SI-LOCK-C5 계약을 소유한다: 로그 + lock.lease.expired metric 후 close() 에서 정상 return 해, 만료가 호출자의 보호작업 예외를 가리지 않게 한다. in-process DefaultLockRegistry 경로는 만료가 없어 그 close() 가 이 예외를 던질 수 없다.

DistributedLockPersistenceConfig 와이어링 결정

  • jdbcDistributedLock 빈은 일부러 @Primary 가 아니다. 같은 설정이 이를 metrics 데코레이터(MeteredDistributedLock, package-private)로 감싸 @Primary distributedLockProvider 빈으로 노출한다. 단일 인스턴스의 inProcessDistributedLock 도 같은 데코레이터 안에 있어 lock.acquisition 이 두 경로를 모두 센다. 예전에는 app-bootstrap의 DistributedLockConfig가 감쌌지만, JDBC 락이 있을 때만 의미가 있는 코드라 이 모듈로 옮겼다. SI 타입은 여전히 이 모듈 밖으로 보이지 않는다(SI 는 implementation 의존).
  • DefaultLockRepository 는 InitializingBean/SmartLifecycle 을 구현해 Spring 이 lifecycle 을 자동 관리하고, ApplicationContextAware 로 PlatformTransactionManager 를 auto-discover 한다. app-bootstrap Testcontainers 테스트가 와이어링 갭을 드러내면 부트스트랩이 setTransactionManager 로 명시 전달할 수 있다.
  • setCheckDatabaseOnStart(false): INT_LOCK 테이블은 첫 lock acquire 전에 Flyway V4/V5 가 provision 하므로 DDL 체크를 건너뛴다.
  • JdbcLockRegistry(lockRepository, settings.leaseTtl()): Spring Integration 7.0 이후 기본 TTL 은 repository setter 가 아니라 registry 생성자에서 설정한다. 어댑터는 호출별 leaseTtl 도 DistributedLock.tryLock(waitTime, leaseTtl) 로 전달한다.

LockSettings

app.lock.* 에서 바인딩되는 yaml-only 기본값이다(config/module-defaults/persistence-jpa.yml). 새 APP_* env 키가 아니므로 env-keys.yaml 엔트리가 필요 없다. DistributedLockPersistenceConfig의 @EnableConfigurationProperties가 바인딩한다. cross-field invariant: leaseTtl >= waitTime 이어야 한다 — TTL 이 waitTime 보다 먼저 만료되면 첫 holder 의 보호작업이 끝나기 전에 두 번째 holder 가 락을 잡을 수 있다.

MeteredDistributedLock (app-bootstrap에서 이동)

  • DistributedLockPort를 감싸는 얇은 Micrometer 데코레이터다. tryAcquire 호출마다 lock.acquisition 카운터를 outcome 태그와 함께 1 증가시킨다. 태그 값은 세 가지: acquired(락 획득 성공, 위임 핸들 반환), timeout(LockAcquisitionTimeoutException 발생), error(그 외 모든 RuntimeException 발생). 메트릭 이름과 태그 값은 docs/registries/metrics.yaml의 lock.acquisition 행과 일치해야 한다.
  • 리스 만료(lease-expiry) CME 흡수. 보유자가 close()를 호출하기 전에 리스(저장소 TTL)가 만료되면 그 락 행은 이미 다른 인스턴스가 회수해 갔을 수 있고, 그 시점에 내부 JdbcLock.unlock()은 ConcurrentModificationException(CME)을 던진다. 이 예외를 호출자의 finally { lock.close(); } 블록 밖으로 그대로 전파하면 보호 구간(critical section)에서 발생한 본래 예외를 가려버린다 (masking). 그래서 CME 만 잡아 WARN 로그를 남기고 태그 없는 lock.lease.expired 카운터를 1 증가시킨 뒤 close()는 정상 복귀시킨다. 이렇게 해야 신호(로그+메트릭)는 남기면서도 호출자의 정상 흐름과 예외 전파를 방해하지 않는다. 오직 ConcurrentModificationException만 흡수하며, DB 장애 같은 다른 예외(예: DataAccessResourceFailureException)는 리스 만료 신호가 아니므로 손대지 않고 그대로 전파한다.
  • MeterRegistry 부재 시 no-op. 레지스트리를 ObjectProvider.getIfAvailable()로 해석하므로 클래스패스에 MeterRegistry 빈이 없으면(Actuator 미탑재) 모든 메트릭 연산이 조용히 no-op 이 된다. BackgroundJobMetrics 선례와 동일한 패턴이다.
  • 메트릭 실패가 락 경로를 절대 깨뜨리지 않음. 카운터 등록·증가는 모두 try/catch 로 감싸 예외를 로깅 후 삼킨다(log-and-swallow). Micrometer 쪽 실패가 락 획득·보유·실패 보고를 막는 일은 없어야 하기 때문이다.

startup — 관계형 기동 정책 (app-bootstrap에서 이동)

JpaStartupAutoConfiguration(package-private, 모듈 스위치 app.persistence-jpa.enabled 아래)이 아래 가드를 등록한다. 전부 adapter:outbound:support의 StartupFailures로 실패하므로 exit 코드(78/70/71)와 구조화 로그 필드(startup.phase/error.code/error.category)는 옮기기 전과 같다. migrationStartupRunner는 @ConditionalOnMissingBean(FlywayMigrationStrategy)라, 자기 전략을 둔 애플리케이션(예: 두 번째 마이그레이션 스트림을 돌리는 서비스)에는 끼어들지 않는다.

FlywayProdSafetyValidator

  • prod 프로파일에서 Flyway 안전장치가 꺼지지 못하도록 런타임에서 강제한다. Flyway 옵션은 application.yml에 안전값으로 고정돼 있지만(baseline-on-migrate=false, out-of-order=false, clean-disabled=true), 환경별 override 가 프로덕션에서 이 값을 조용히 되돌릴 수 있다. 이 검증기는 그런 override 를 시작 시점에 잡아 PROFILE_MISMATCH(exit 71)로 부팅을 막는다.
  • 금지하는 옵션은 각각 "복구 불가능한 위험" 때문이다. baseline-on-migrate=true는 누락된 마이그레이션을 감지하는 안전망을 없애고, out-of-order=true는 개발자 간 마이그레이션 적용 순서 일관성을 깨며, clean-disabled=false는 스키마 전체를 드롭하는 파괴적 clean 명령을 다시 활성화한다.
  • 프로파일 비교는 대소문자를 무시한다. SPRING_PROFILES_ACTIVE=PROD처럼 대문자 오타가 나도 가드가 우회되지 않게 하기 위함이다.
  • Flyway repair 는 가드 대상이 아니다. repair 는 property 가 아니라 Flyway 명령이고 스켈레톤은 repair 호출 경로 자체를 배선하지 않으므로, "prod 에서 repair 금지"는 런타임 트리거가 없는 문서화된 정책으로 남는다. 부분 스키마 복구는 in-prod Flyway repair 가 아니라 runbook(runbook://migration/manual-recovery)을 통한 수동 복구로 가도록 실패 메시지에 명시한다. (프로젝트가 repair 경로를 추가한다면 동일하게 prod 게이트 + non-prod 감사 로그를 걸어야 한다.)

RequiredEnvironmentValidator

  • datasource 연결 환경변수를 마이그레이션 실행 전에 검증해 부팅을 빨리 실패시킨다. Flyway forward-only 마이그레이션은 context refresh 동안 애플리케이션 datasource 에 대해 실행된다. 연결 환경변수가 빠져 있으면 마이그레이션은 시작 단계 구분자 없이 불투명한 driver/connection 에러로 한참 뒤에야 실패한다. 이 검증기는 그것을 명시적인 env 검증 실패(STARTUP_VALIDATION_FAILED, exit 78)로 바꿔, 누락된 운영자용 env 키를 전부 이름으로 짚어준다.
  • 검증 범위를 datasource 3종(url/username/driver)으로 의도적으로 좁혔다. 이것들이 이 브랜치가 소유하는 마이그레이션 전제조건이기 때문이다. app-name(BootstrapSettings), issuer-uri(security settings) 등 다른 필수값은 각 모듈의 가드가 책임지므로 여기서 중복 검증하지 않는다.
  • 값이 없거나(blank) 공백이면 모두 "누락"으로 본다. spring-dotenv 에서 미설정 placeholder ${...}가 빈 문자열로 해석되기 때문에, null 뿐 아니라 blank 도 누락으로 처리해야 빈틈이 없다.
  • 메시지는 env 키 이름순으로 정렬해 출력한다. Map 순회 순서와 무관하게 결정적이고 안정적인 실패 메시지를 보장하기 위함이다.

JpaStartupAutoConfiguration (옛 MigrationStartupConfig·PersistenceJpaRootAutoConfiguration·JpaPlatformRuntimeAutoConfiguration)

  • 마이그레이션 전략과 관계형 기동 가드를 한곳에 모은다. app-bootstrap에서는 네 개 설정 클래스와 RuntimeSafetyConfig의 validator 목록에 흩어져 있었고, JPA 스위치를 합성 루트가 알아야 했다. JpaPlatformAutoConfiguration(플랫폼 조립 factory)은 지웠고, 보고서 조립은 JpaPlatformReport로 옮겼다.
  • migrationStartupRunner 빈 이름은 유지한다. Spring Boot Flyway 오토컨피규레이션이 migrate()를 위임하는 FlywayMigrationStrategy다.

MigrationStartupRunner

  • FlywayMigrationStrategy로 등록해 context refresh 중에 마이그레이션을 직접 실행한다(오토컨피그 기본값을 그대로 두지 않는다). refresh 안에서 실행한다는 것은 마이그레이션이 완료되거나 부팅을 실패시키는 일이 애플리케이션이 readiness 를 보고하기 전에 일어난다는 뜻이다. 따라서 절반만 마이그레이션된 스키마가 트래픽을 받는 일이 구조적으로 없다(actuator readiness probe 의 형태 자체는 health-lifecycle 브랜치가 소유하고, 여기서는 "마이그레이션 → ready" 순서만 책임진다).
  • FlywayException을 StartupFailures.migrationFailed(MIGRATION_FAILED, exit 70)로 번역한다. 일반적이고 구분 안 되는 스택트레이스 대신 구조화된 MIGRATION_FAILED 로그와 표준 exit 코드를 남기기 위함이다.
  • 멀티 인스턴스에서는 in-app 마이그레이션 + Flyway 자체 schema-history 락에 의존하는 것이 기본 전략이다. 여러 레플리카의 동시 migrate()를 Flyway 의 락이 직렬화한다. 대안인 "in-app 마이그레이션을 끄고 플랫폼 one-shot Job 으로 돌리기"는 "migration=Job"을 강제하는 공개 표준이 없는 배포 선택이라 스켈레톤 기본값이 아니다. Job 으로 돌리는 프로젝트는 이 빈의 migrate()를 no-op 으로 만들면 된다.

HikariPoolConstraintValidator

  • HikariCP 노브 사이의 상호 제약을 부팅 실패로 바꾼다. Hikari/Tomcat 은 잘못된 값을 결국 거부하지만 pool/connector 초기화 시점에 난해한 메시지로만 거부한다. 이 검증기는 계약을 일찍·명확 하게 만든다: resolved Spring property 를 읽고, 위반을 모두 모아 운영자가 실제로 설정한 APP_* 환경 키를 메시지에 담아 IllegalStateException을 던진다. 속성이 없으면 건너뛰고(placeholder/ 프레임워크 기본값이 소유), 있을 때만 검사한다.
  • 강제하는 제약과 그 숫자의 근거. connection-timeout >= 250ms(너무 짧으면 정상 연결도 타임 아웃). validation-timeout < connection-timeout(둘 다 있을 때; validation-timeout 기본 5000ms 가 흔한 connection-timeout 5s/5000ms 와 같아지는 충돌을 해소). keepalive-time < max-lifetime(둘 다 있을 때; keepalive 가 lifetime 보다 길면 의미 없음). leak-detection-threshold는 0(비활성)이 아니라면 >= 2000ms(너무 작으면 정상 사용을 누수로 오탐).
  • Spring Boot와 같은 Duration 문법을 검증한다. env-keys.yaml의 connection-timeout 기본값은 5s인데 .env는 30000(ms)을 준다. resolved 값을 String으로 읽은 뒤 DurationStyle로 plain milliseconds, simple duration(5s)과 ISO-8601(PT5S)을 같은 milliseconds 계약으로 변환한다. present-but-invalid 값은 부재로 조용히 취급하지 않고 property 이름을 포함한 startup validation failure로 거절한다.
  • env 키가 아직 없는 노브는 "env key pending" 문구를 쓴다. connection-timeout / max-lifetime만 env-keys.yaml에 등록돼 있고, greenfield 노브(validation-timeout, keepalive-time, leak-detection-threshold)는 env 키가 없다. 없는 키 이름을 지어내는 대신 pending 문구를 메시지에 넣는다.

OpenInViewSafetyValidator

  • OSIV(Open Session In View) OFF 를 hard stop 으로 강제한다. OSIV 가 켜져 있으면 Hibernate 세션이 view 렌더링까지 열려 있어, presentation 레이어에서 lazy 연관을 건드리면 거기서 조용히 DB 쿼리가 나간다 — 이것이 정확히 금지된 레이어 경계 위반이다. Spring Boot 는 spring.jpa.open-in-view가 암묵 기본값일 때 WARN 만 찍을 뿐 명시적으로 true로 설정한 배포는 막지 못한다. WARN 은 놓치기 쉬우므로, resolved 값이 true면 운영자가 실제 설정한 APP_DATASOURCE_OPEN_IN_VIEW 키를 메시지에 담아 부팅을 실패시킨다.
  • 읽기만 하고 re-bind 하지 않으며, 부재 값은 Spring 기본에 맡긴다. StartupRule로 위반만 돌려주고 support의 StartupRuleRunner가 다른 싱글톤(DataSource·Flyway)을 만들기 전에 한 번 실행하며, 값이 없으면 Spring Boot 기본(이 스켈레톤은 application.yml에서 OSIV off 가 기본)에 맡기며 *있는 true*만 거부한다.

JpaDangerousConfigurationGuard (ddl-auto)

  • Flyway를 physical schema의 유일한 writer로 유지한다. local convenience profile만으로 이뤄진 profile 집합이 아니면(prod, staging, profile 없음, local+prod 혼합 모두) spring.jpa.hibernate.ddl-auto가 none 또는 validate일 때만 허용한다. update, create, create-drop, 빈 값, 그 밖의 값이면 APP_DATASOURCE_DDL_AUTO를 이름으로 포함한 PROFILE_MISMATCH로 부팅을 중단한다. mode 비교는 대소문자를 무시한다.
  • 검사는 이 guard 하나다. prod만 보던 JpaSchemaSafetyValidator는 이 guard보다 늦게 돌아 한 번도 발동하지 않았고, 실제 prod 거부는 PROFILE_MISMATCH가 아닌 IllegalStateException이었다. 두 검사를 합치면서 guard가 PROFILE_MISMATCH를 던진다.

지역 규칙에서 옮긴 표와 계약

이 절의 표와 계약은 지역 규칙 AGENTS.md에 있던 것을 2026-11-07에 옮겼다(지역 규칙은 200줄 이하). 규칙이 바뀌면 이 절과 AGENTS.md를 같은 변경에서 고친다.

Spring 조립 소유

META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports는 package-private 항목 둘을 내놓는다: PersistenceJpaAutoConfiguration과 PersistenceJpaRuntimeConfig. Boot가 그 후보를 따로따로 읽으므로 둘 다 app.persistence-jpa.enabled=true를 요구한다. 첫째는 vendor·entity·repository와 capability 저장소 import를 가진다. 둘째는 provider runtime bean(HibernateProviderPolicy, PostgreSqlRuntimeRoleVerifier)만 기여한다. 트랜잭션 엔진은 SpringTransaction 하나뿐이다. 두 번째 엔진(SpringJpaTransactionExecutor/FullTransactionRetryCoordinator)은 2026-09-25에 지웠다 — docs/capability-status.md를 본다. 첫째 후보의 조건이 이웃 import 후보를 막아 준다고 기대지 않는다.

enabled=false는 bean만이 아니라 완전히 끄기다: JpaActivationEnvironmentPostProcessor(이 leaf의 spring.factories)가 Boot의 jdbc/hibernate/data.jpa/flyway 자동 구성을 spring.autoconfigure.exclude에 붙인다. 그래서 DataSource, pool, EntityManagerFactory, Flyway가 하나도 없다.

소유자를 안전하게 지키는 PostgreSQL 멱등성도 같은 분할을 쓴다: 이 leaf는 IdempotencyStorePort 뒤의 실제 PostgreSQL store를 만들고(PostgreSqlIdempotencyStoreConfig, app.capabilities.idempotency.provider=postgresql일 때만 켜진다), composition:idempotency가 provider 고르기, TTL·lease·codec 정책, executor 만들기, 배타성 검증을 가진다. 그 provider를 고르면 leaf는 db/migration/jpa/core + db/migration/jpa/idempotency Flyway stream도 적용하고 기동 때 capability registry 행을 켜며(IdempotencySchemaStream, app.runtime.migration-on-startup=false이면 건너뛴다), PostgreSQL이 아닌 data source를 거절하고, IdempotencyReaper를 돌린다. V1·JDBC 멱등성 store도 jdbc provider 값도 없다.

이 모듈은 빌드 한 줄(runtimeOnly project(':adapter:outbound:persistence-jpa'))로 고르는 capability다. 템플릿의 기본 조립은 이것을 싣지 않는다. 그래서 관계형 저장소가 있을 때만 뜻이 있는 것은 모두 여기 있고 모듈과 함께 켜진다: migration 기동 순서, 해석된 datasource·버전 검증, OSIV·DDL·pool·TLS·vendor 안전, 걸러 낸 관리 endpoint·보고 (startup), metric을 단 다중 인스턴스 lock(lock), readiness db 기여, 출하하는 설정 (config/module-defaults/persistence-jpa.yml). 유스케이스 조립은 아니다: driven 어댑터가 유스케이스를 만들거나 부르면 안 되므로 outbox relay는 composition:outbox-relay다. leaf에는 dev.caskeleton.bootstrap import가 하나도 없어야 한다. 기동 실패는 adapter:outbound:support(support.startup)를 거치고, 새 조립 도우미는 package-private로 둬서 배선 실수로 verifyJpaApiSurface가 늘지 않게 한다.

플랫폼 lane

./gradlew :adapter:outbound:persistence-jpa:test                       # hermetic unit lane
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformContractTest     # real PostgreSQL
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformMigrationTest    # Flyway upgrade scenarios
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformFailureTest      # deadlock
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformQueryPlanTest    # EXPLAIN structure
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformSecurityTest     # runtime role privileges
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformPoolContractTest   # pool behaviour
# Release blocking composition is CI-owned; locally run the exact database qualification set:
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformContractTest \
  :adapter:outbound:persistence-jpa:jpaPlatformMigrationTest \
  :adapter:outbound:persistence-jpa:jpaPlatformFailureTest \
  :adapter:outbound:persistence-jpa:jpaPlatformQueryPlanTest \
  :adapter:outbound:persistence-jpa:jpaPlatformSecurityTest \
  :adapter:outbound:persistence-jpa:jpaPlatformPoolContractTest

Docker를 쓰는 모든 lane은 실패하면 닫힌다. 고른 lane이 아무것도 찾지 못하거나 container가 시작하지 못하면 건너뛰기가 아니라 오류다 — 건너뛴 계약은 아무도 시험하지 않은 데이터베이스에 대해 성공을 알린다.

vendor 고르기

vendor 조립 둘이 이 모듈에 있고, 각각 자기 하위 패키지에 있으며, 각각 같은 SPI bean 둘(outbox claim, SQLState 대응)을 등록한다:

vendor 패키지 고르는 것 schema 소유
PostgreSQL .postgresql app.persistence.vendor=postgresql(기본값이기도 하다) Flyway, db/migration/postgresql
H2 .h2 app.persistence.vendor=h2 Hibernate ddl-auto, 엔티티만

outbox와 멱등성 기능은 기능별, 그다음 vendor별로 조각을 모아 둔다: outbox/{jpa,postgresql,h2}와 idempotency/{jpa,postgresql}. 어떤 claim repository를 등록할지는 여전히 위 vendor 설정이 정한다. 그 기능 클래스 중 driver 타입을 import하는 것이 없으므로, 그것들이 .postgresql 밖에 있어도 PERSISTENCE_RDBMS_STAYS_VENDOR_NEUTRAL이 계속 지켜진다.

config/PersistenceVendorSettings가 선택자를 enum으로 바인딩한다. 그래서 모르는 값은 두 조립 중 어느 것도 읽지 않고 OutboxClaimRepository가 없다는 오류로 나타나는 대신 기동 때 실패한다. 선택은 모듈이 정한다: 그 config/module-defaults/persistence-jpa.yml이 모든 profile에서 vendor를 PostgreSQL로, spring.flyway.enabled를 APP_FLYWAY_ENABLED(true)로 기본 설정한다. 조립 루트의 profile 파일은 더는 그것을 다시 적지 않는다(2026-11-01 성숙도 리뷰 뒤로. 기본 조립 루트가 고르지 않은 capability의 설정을 알면 안 된다). H2는 bootRunH2 태스크가 고르는, 개발자가 명시해서 빠지는 길이다. PersistenceVendorProdSafetyValidator(startup)는 어떤 속성 출처가 주든 prod에서 H2를 거절한다. bootRunH2에서는 멱등성 provider가 disabled나 redis여야 한다: postgresql provider는 기동 때 H2 data source를 거절한다.

H2는 로컬 개발 저장소이지 두 번째 운영 대상이 아니다. migration 트리가 없으므로, migration에만 있는 테이블 — capability schema registry, Spring Integration lock 테이블 — 은 H2에 없다. vendor 동시성과 migration 충실도는 postgresqlIntegrationTest에 남는다.

outbox claim은 H2가 돌리는 유일한 vendor 문장이고 내용이 같다 — H2 2.4.240은 FOR UPDATE SKIP LOCKED를 받고 잠긴 행을 정말 건너뛰므로 claim이 뜻을 지킨다. H2ClaimSqlTest가 그것을 실제 H2에 대고 실행한다. H2에는 멱등성 store가 없다.

capability로 막은 store

선택 capability 하나를 위한 어댑터는 이 모듈의 나머지와 달리 그 capability의 스위치를 단다. 지금은 fileserver 패키지가 그 경우다: 거기 있는 모든 Jpa* 어댑터는 @ConditionalOnProperty(prefix = "app.fileserver-platform", name = "enabled", havingValue = "true")를 단다.

그 막음이 없으면 이 모듈을 넣기만 한 조립 루트도 그 bean을 만들고, 각 bean에는 파일 서버 설정만 주는 협력 객체가 필요하다. 지운 샘플 모듈이 쓰지도 않는 Fileserver 협력 객체 때문에 기동에 실패한 일이 그 예다. 아무도 켜지 않은 capability의 store는 있으면 안 된다.

TransactionPort 구현 계약

SpringTransaction은 모드마다 TransactionTemplate을 하나씩 미리 만든다:

모드 전파 격리 읽기 전용 timeout
inWrite REQUIRED READ_COMMITTED(pool) false app.persistence-jpa.transaction.write-timeout(30 s)
inRootWrite REQUIRED READ_COMMITTED(pool) false inWrite와 같음
inRead REQUIRED READ_COMMITTED(pool) true app.persistence-jpa.transaction.read-timeout(30 s)
inNew REQUIRES_NEW READ_COMMITTED(pool) false 30 s, 고정

격리 수준은 template이 아니라 pool에 고정한다: template은 ISOLATION_DEFAULT를 쓰고, 모듈 기본값이 spring.datasource.hikari.transaction-isolation: TRANSACTION_READ_COMMITTED를 정하며(물리 연결마다 한 번 적용), HikariPoolConstraintValidator가 다른 수준이면 기동을 거절한다. template마다 수준을 대면 Spring이 begin마다 getTransactionIsolation()을 부르고, pgjdbc는 그것에 SHOW TRANSACTION ISOLATION LEVEL 왕복으로 답했다.

모든 모드에는 시간 한계가 있다(2026-11-01부터). Spring이 남은 시간을 문장마다 넘기므로 느린 query나 lock 대기는 서버가 취소하고(57014 → DB_QUERY_CANCELED), 다음 문장 전에 기한이 지난 경우도 같은 코드를 받는다: JDBC 경로에서는 Spring의 TransactionTimedOutException, JPA 경로(JpaTransactionManager, 운영)에서는 Hibernate 자신의 TransactionException이다. 후자는 SQLState가 없고, SpringTransaction이 기한이 지났음을 알기 때문에 분류된다(translateAfterDeadline). 기한 뒤에 던진 업무 예외는 바꾸지 않고 넘긴다.

미리 만든 template은 만든 뒤 바뀌지 않아서, 동시 호출자가 서로의 재설정을 볼 수 없다. inRootWrite는 미리 만든 쓰기 template을 다시 쓰지만, 먼저 TransactionSynchronizationManager.isActualTransactionActive()를 검사한다. 실제 바깥 트랜잭션이 있으면 action이나 PlatformTransactionManager를 부르기 전에 반드시 NestedRootTransactionRejectedException을 던진다. NEVER나 REQUIRES_NEW를 쓰면 안 된다.

inRootWrite는 TransactionTemplate.execute가 커밋한 뒤에만 action 값을 돌려준다. 커밋이 실패하면 트랜잭션 예외를 올리고 호출자에게 성공 값을 돌려주지 않는다.

inNew 풀 크기 제약 (feature-application-port-usecase-contract)

REQUIRES_NEW는 바깥 트랜잭션의 연결을 쥔 채 새 물리 JDBC 연결을 얻는다. pool은 다음을 만족하게 잡는다:

hikari.maximumPoolSize >= (concurrent_threads × (1 + max_inNew_depth)) + 1

레코드마다 inNew를 부르는 반복문은 금지다(pool 고갈 + 교착 위험). 레코드를 inNew 하나 안에서 묶어 처리하거나, 반복문을 트랜잭션 밖으로 뺀다.

영속 실패 번역 계약 (feature-persistence-failure-baseline)

날것의 Spring DataAccessException(과 그 안의 JPA 예외·SQLState·제약 이름)은 절대 표현 계층에 닿으면 안 된다. failure/PersistenceExceptionTranslator가 DataAccessException을 SQLState로 아래 §SQLState → 오류 코드 표와 대조해 분류하고, DB_* OperationalError 코드 하나를 실은 프레임워크 중립 shared.error.PersistenceFailureException을 돌려준다.

표준 행(core):

SQLState code category http retryable
08* DB_UNAVAILABLE TRANSIENT_DEPENDENCY 503 true
40001 DB_SERIALIZATION_FAILURE CONFLICT 409 true
23502 DB_NULL_VIOLATION DATA_INTEGRITY 409 false
23503 DB_FK_VIOLATION DATA_INTEGRITY 409 false
23505 DB_UNIQUE_VIOLATION CONFLICT 409 false
23514 DB_CHECK_VIOLATION DATA_INTEGRITY 409 false

vendor 전용 행(vendor 모듈이 SqlStateErrorMapping SPI로 기여):

SQLState code vendor
40P01 DB_DEADLOCK PostgreSQL(.postgresql 패키지)
55P03 DB_LOCK_TIMEOUT PostgreSQL
25P03 DB_IDLE_IN_TX_TIMEOUT PostgreSQL
57014 DB_QUERY_CANCELED PostgreSQL
57P01, 57P02 DB_UNAVAILABLE(커밋 전. 커밋 중이면 completion-unknown) PostgreSQL
23513 DB_CHECK_VIOLATION H2(.h2 패키지) — H2는 CHECK를 core 표가 대응시키는 표준 23514가 아니라 23513으로 알린다
HYT00 DB_QUERY_CANCELED H2 — H2는 문장 timeout과 lock timeout을 상태 하나로 합친다

PostgreSQL 행은 두 번째 표가 아니다: 2026-11-01 전에는 손으로 관리하던 두 번째 표가 이미 어긋나 있었다. PostgreSqlSqlStateErrorMapping이 그 행을 PostgreSqlFailureClassifier(SQLState → FailureCategory)와 FailureCategory.operationalError()(category → 코드)에서 끌어낸다 — 라이브러리 PostgreSqlExceptionTranslator가 쓰는 것과 같은 분류다 — 그리고 위 표준 행, 전용 코드가 없는 category(INTERNAL_ERROR), COMPLETION_UNKNOWN(단계에 따라 다르다)을 뺀다. PostgreSQL 상태를 더하려면 PostgreSqlState와 classifier에 더한다. 두 경로가 어떤 상태에서든 다르면 SqlStateClassificationParityTest가 실패한다.

SQLState가 없고 타입으로 분류: 진 @Version 경쟁(OptimisticLockingFailureException, JPA OptimisticLockException) → DB_OPTIMISTIC_CONFLICT(409). 만료된 Spring 트랜잭션 기한(TransactionTimedOutException) → DB_QUERY_CANCELED. SpringTransaction이 시작한 트랜잭션의 기한이 지난 뒤의 다른 영속 실패(JPA, Spring data-access, Spring transaction 예외) → DB_QUERY_CANCELED.

커밋 단계(translateCommitFailure, ADR-JPA-003): action이 돌아왔고 SpringTransaction이 자기가 시작한 쓰기 트랜잭션을 커밋하는 중이면, 08*, 40003, vendor가 기여한 종료 상태(SqlStateErrorMapping.commitOutcomeUnknownStates(): PostgreSQL 57P01, 57P02), SQLState 없는 전송 끊김을 가진 실패는 DB_UNAVAILABLE이 아니라 TransactionCompletionUnknownException → DB_COMPLETION_UNKNOWN(500, 절대 재시도하지 않음)이 된다: 서버가 이미 커밋했을 수 있다. 서버가 분명히 거절한 커밋(예: 미뤄진 23505)은 위 자기 행을 지킨다. 읽기 전용 커밋은 DB_UNAVAILABLE을 지킨다.

  • DataAccessException을 잡는 repository 어댑터는 translator.translate(ex)를 부르고 carrier를 다시 던진다 (ifPresent(e -> { throw e; })). 빈 결과는 모르는 SQLState라는 뜻이다 — 원래 예외를 다시 던져 web catch-all이 일반 INTERNAL envelope으로 답하게 한다(새는 것 없음).
  • category 정본은 값 10개의 Category enum이다 — PERSISTENCE category는 없다(설계 기록 §Audit CATEGORY_DRIFT).

영속 감사 계약 (feature-persistence-auditing-contract)

감사 metadata(created_at / updated_at / created_by / updated_by)는 기반 관심사이고 domain-core에 닿으면 안 된다. audit/AuditableEntity @MappedSuperclass에만 있다. 도메인 aggregate의 영속 엔티티가 그것을 상속해서 고른다(생성 명령이 만드는 서비스 persistence leaf의 엔티티가 그렇게 한다). 도메인 aggregate 자체는 감사 필드를 하나도 갖지 않는다. ArchUnit DOMAIN_IS_PURE(jakarta.persistence.. 없음)와 DOMAIN_ENTITIES_DO_NOT_CARRY_AUDIT_FIELDS(..domain.. 아래에 createdAt/updatedAt/createdBy/updatedBy 필드 없음)가 강제한다.

  • 잡기 = 손으로 명시해 넣기(지금 기본). repository 어댑터가 생성자로 Clock과 AuditContextPort를 받고 save에서 감사 값을 넣는다: INSERT(version null) → initializeAudit(now, actor). UPDATE(version 있음) → 저장된 created_*를 그대로 넘기고 + applyModification(now, actor). created_*는 updatable = false다.
  • actor 이음매. AuditContextPort.currentActor()는 runtime-context 전파 이음매를 읽고, principal이 묶여 있지 않으면 (scheduler / Flyway / 익명) "system"으로 물러선다. actor 값의 뜻은 feature-authentication-authorization-contract가 가진다(여기서는 UNSUPPORTED). 타입은 String으로 고정한다.
  • 빠지는 것. IdempotencyRecordEntity(자기 created_at, updated_at 없음) 같은 기반·불변 엔티티는 AuditableEntity를 상속하지 않는다. version·낙관적 lock은 이 감사 기반이 아니라 feature-persistence-failure-baseline / feature-transaction-concurrency-contract가 가진다.
  • 자랄 길(미룸). 트리에 두 번째 감사 구현은 없다. 손으로 넣는 것이 실수가 너무 잦아지면, 정해진 AuditableEntity 계약을 created_*/updated_* schema, actor 한계, Clock, AuditContextPort 뜻을 지키면서 한 번에 Spring Data listener로 옮긴다. bulk·native @Query UPDATE도 listener를 지나지 않으므로 계속 감사 열을 명시해 넣어야 한다.