Files
clean-architecture-backend-…/src/adapter/outbound/persistence-jpa
DongHyeonka 6ec0c4f7fa fix(migration): 실패한 동시 인덱스 마이그레이션 복구와 검사기 설명을 실제 동작에 맞춘다
문제 (재리뷰 round7 영속성 RR7-03-01~05)
- 실패한 동시 인덱스 마이그레이션의 복구를 가이드·검사기·학습 문서가
  "DROP INDEX 하나"로 안내한다. Flyway는 트랜잭션 밖에서 실패한 버전의
  이력 행(success = false)을 남기고, 다음 배포의 validate가 그 행 때문에
  다시 멈춘다. runbook에는 이 경우가 없고 이력 수정은 금지다.
  docs/jpa/runbooks.md "An invalid index exists"도 같은 이유로 재적용에서
  멈춘다.
- 검사기 Javadoc·학습 문서가 "섞인 파일은 부분 적용되지 않는다"고 쓴다.
  가이드가 요구하는 executeInTransaction=false를 붙이면 Flyway가 문장마다
  커밋해 앞 문장이 남는다.
- 가이드·검사기 Javadoc·실패 메시지·학습 문서가 "Flyway는 REINDEX …
  CONCURRENTLY를 트랜잭션 안에서 돌린다"고 쓴다. REINDEX SCHEMA|DATABASE
  CONCURRENTLY는 Flyway가 스스로 트랜잭션 밖에서 돌린다.
- LockWaitMigrationInspector는 .sql.conf가 executeInTransaction=true면
  SET LOCAL 뒤의 VACUUM FULL·REINDEX SCHEMA를 통과시킨다. Javadoc은
  "늘 거부"라고 쓴다.
- ledger 잠금 대기 IT가 동시 인덱스 파일을 "이 테스트에 예외로 적으라"고
  안내하지만 예외를 적을 곳이 없다. 같은 원인으로 ledger의 다른 IT 두 개
  (GrpcOperationLedgerPostgresIT, JpaGrpcOperationLedgerContractIT)도
  모든 파일을 한 문자열로 실행해, 동시 인덱스 파일이 생기면 "cannot be
  executed within a pipeline"으로 실패한다.

고른 방법
- 복구(RR7-03-03): 소유자 결정(2026-11-06)대로 migration-failed.md에
  "Recover a failed concurrent index migration" 절을 둔다. 진행 중 빌드
  확인 → 무효 인덱스 DROP INDEX CONCURRENTLY → 원인 정리 → 그 버전의
  실패 행만 DELETE → 재배포. "Do not"에 이 한 가지 예외를 적고
  flyway repair는 계속 금지한다. SQL 세 블록에 runbook-sql 표시를 달고
  postgresqlConcurrentIndexMigrationIntegrationTest가 runbook에서 읽어
  실 PostgreSQL에서 돌린다(outbox runbook과 같은 방식). 가이드·검사기
  Javadoc·메시지·학습 문서·jpa/runbooks.md는 그 절을 가리킨다.
- 섞인 파일(RR7-03-04)·REINDEX(RR7-03-02): 문장을 고치고, 같은 IT와
  잠금 대기 IT에 사실을 고정한다(섞인 파일 두 경우, REINDEX 다섯 형태).
- 검사기(RR7-03-05): 트랜잭션 안에서 돌 수 없는 잠금 문장은 .sql.conf와
  상관없이 거부한다(리뷰 권장안). 버린 안: Javadoc만 좁히기 — 그 파일은
  PostgreSQL이 배포 때 25001로 거부하므로 검사기가 먼저 알려 주는 쪽이
  맞다. 잠그지 않는 문장(plain VACUUM 등)은 이 검사기의 범위가 아니라
  그대로 둔다.
- ledger(RR7-03-01): IT에 RUN_OUTSIDE_A_TRANSACTION(파일 → 이유) 목록을
  두고 잠금 대기 케이스에서 뺀다. 목록의 파일은 같은 IT가 동시 인덱스
  문장 하나·executeInTransaction=false인지 ConcurrentIndexMigration
  Inspector로 본다. optional 빌드는 testkit에 의존할 수 없어
  sharedMigrationFileSources가 그 파일과 MigrationResource를 복사한다
  (VersionedMigrationFiles와 같은 방식). ledger IT 셋은 마이그레이션을
  파일마다 따로 실행한다(Flyway처럼). 버린 안: 안내만 "다룰 수 없다"로
  바꾸기 — 다음 동시 인덱스 파일이 생길 때 같은 질문이 다시 남는다.

위험·한계
- 검사기 변경으로 서비스의 자기 스트림 검사가 새로 실패할 수 있다.
  걸리는 파일은 PostgreSQL이 배포 때 거부하는 파일뿐이라 배포된 적이
  없다(업그레이드 안내 4.1에 적음).
- runbook의 DELETE는 운영자가 version을 옮겨 적는다. NOT success라
  성공한 행은 지우지 못하지만, 다른 버전의 실패 행을 잘못 적으면 그 행이
  지워진다. 한 행만 지워야 하고 0행이면 다시 분류하라고 적었다.
- ledger 복사 파일 두 개도 JDK만 써야 한다(각 Javadoc에 적음).
- Spotless 검사는 같은 worktree에서 spotlessApply가 변경 없이 끝난 직후라
  UP-TO-DATE로 처리됐다.

검증 (desktop, 공유 잠금, 로그 ~/r8-f3-logs/)
RED — 기준 73d39212 + 이 커밋의 테스트(+ 기준 문서 주장을 단언하는 임시
메서드, + 임시 ledger V004):
- persistence-jpa test --tests LockWaitMigrationInspectorTest: 80건 중
  2건 실패, 검사기가 빈 목록(통과)을 돌려줌 (red-unit.log)
- postgresqlMigrationLockWaitIntegrationTest: 47건 중 4건 실패 — 옛 주장
  대로면 거부여야 할 REINDEX SCHEMA|DATABASE CONCURRENTLY가 applied,
  conf=true VACUUM FULL·REINDEX SCHEMA를 PostgreSQL은 25001로 거부하는데
  검사기는 통과 (red2-lockwait.log)
- postgresqlConcurrentIndexMigrationIntegrationTest: 9건 중 3건 실패 —
  옛 절차(DROP INDEX) 뒤 재배포가 "Detected failed migration to version
  2", conf를 붙인 섞인 파일이 행 3001·무효 인덱스·실패 이력을 남김,
  runbook 블록이 없어 복구 테스트 준비 실패(RED로 세지 않음)
  (red2-concurrent.log)
- ledger integrationTest(V004 동시 인덱스): 6건 중 4건 실패 — 잠금 대기
  IT "name it as an exception here", 다른 IT 둘 "cannot be executed within
  a pipeline" (red-ledger.log)
GREEN — 이 커밋의 트리 b49369e7:
- :adapter:outbound:persistence-jpa:check rc=0 (test 666건 실패 0),
  :testQualityCheck rc=0
- postgresqlMigrationLockWaitIntegrationTest rc=0 (42건 실패 0)
- postgresqlConcurrentIndexMigrationIntegrationTest rc=0 (7건 실패 0)
- -p optional-platforms :grpc:grpc-operation-ledger-jpa:check
  integrationTest testQualityCheck rc=0 (IT 3+2+42건 실패 0)
- :app-bootstrap:documentContractTest rc=0 (66건 실패 0)
- 두 빌드의 verifyStrictLaneStages --dry-run rc=0
- ledger 탐침(임시 V004): 목록에 없으면 잠금 대기 케이스만 실패하고
  메시지가 RUN_OUTSIDE_A_TRANSACTION을 가리킴(48건 중 1건), 목록에 넣으면
  rc=0, 목록에 넣고 SET LOCAL을 섞으면 목록 검사가 "mixes a concurrent
  index statement"로 거부
- python3 scripts/check-work-docs.py --links docs: 깨진 링크 0

Refs: docs/reviews/2026-11-03-rereview/round7/03-persistence.md
2026-11-07 01:14:09 +09:00
..

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

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

허용/금지 의존, 테스트 명령, 그리고 계약 테이블(TransactionPort 모드표, SQLState → Error Code 매트릭스, auditing 계약, 분산 락 provider 선택표)의 SSOT 는 CLAUDE.md 다. 이 문서는 코드 주석에서 덜어낸 설계 결정의 근거를 모아둔 참조용 기록이다 — 코드를 읽다 "왜 이렇게 했나"가 궁금할 때 본다. 표가 CLAUDE.md 에 있으면 여기서는 중복하지 않고 그 근거만 적는다.

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

템플릿 기본 조립에는 이 모듈이 없다. 관계형 저장소가 필요한 서비스는 app-bootstrap/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 + MeteredDistributedLock 데코레이터 = distributedLockProvider), 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(스케줄러)는 이 모듈이 아니라 합성 루트의 OutboxConfig가 조립한다. 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과 sample-portfolio가 제공).

필요한 env 키 (src/.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 규칙의 라이브러리형 예외). Querydsl·Envers는 이 leaf에서 compileOnly이므로 쓰는 서비스가 com.querydsl:querydsl-jpa:5.1.0:jakarta·org.hibernate.orm:hibernate-envers를 직접 추가한다. "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 을 READ_COMMITTED 로 고정한다(모드표는 CLAUDE.md §TransactionPort implementation contract).

왜 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 가 아닌가

sample 모듈에 이미 ...sample.portfolio.adapter.persistence.config.JpaConfig 가 있다. IDE 의 "Run main class" 가 테스트 스코프 sample 모듈을 클래스패스에 올리면, simple name JpaConfig 를 공유하는 두 @Configuration 이 기본 빈 이름 jpaConfig 에서 충돌한다 (ConflictingBeanDefinitionException). 다른 simple name 으로 이를 피한다.

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

매트릭스(SQLState → DB_* 코드, category, http, retryable)의 SSOT 는 CLAUDE.md §Persistence failure translation contract 다. 여기서는 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 IdempotencyProviderSelectionConfig 가 만든다. 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 production capability candidate

src/config/jpa/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()를 직접 부르면 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 Location History table 상태
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가 다른 인자로 이미 적용된 경우다. complete 재생은 같은 owner token에만 확인한다 — 같은 operation id를 쓴 다른 attempt의 늦은 complete는 NOT_OWNER다(전에는 operation id만 보고 ALREADY_COMPLETED_SAME_RESULT). 시작은 핸들 말고 인자가 없어서, 이미 기록된 시작과 digest가 다르면 다른 핸들이다 — 넘겨받기 전 핸들은 NOT_OWNER, 재생받은 현재 핸들은 NOT_CLAIMED(라운드6 RR6-02-01, 전에는 OPERATION_CONFLICT). 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)의 SSOT 는 CLAUDE.md(또는 app-bootstrap 와이어링)다. 여기서는 어댑터/설정 결정 근거만 적는다.

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 빈으로 노출한다. 예전에는 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)라, 자기 전략을 둔 애플리케이션(sample-portfolio의 두 번째 마이그레이션 스트림)에는 끼어들지 않는다.

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인데 src/.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를 던진다.