docs(review): 2차 재리뷰 결과와 파생 서비스 업그레이드 안내를 더한다

문제: 1차 재리뷰 수정(bbe944bd)도 앞 라운드처럼 새 결함을 만들었는지
아무도 다시 읽지 않았다. 이 브랜치는 파생 서비스가 깨지는 변경이
많은데 따라올 안내가 없었다.

방법: 수정 커밋만 대상으로 리뷰어 4명이 1차와 같은 템플릿·스킬 방식으로
봤다(round2/). Critical·회귀 0, Important 7(이번 라운드가 새로 만든 것
4), Minor 22. 3차 수정에 쓸 결정을 README 9.1절에 적었다. 파생 서비스용
docs/upgrade/2026-11-maturity-review.md에 깨지는 변경 38건, 마이그레이션
영향, 따라오는 순서를 diff 근거와 함께 정리했다.

위험·한계: 이 커밋은 기록만 담는다. Important 7건은 다음 수정에서
고친다. 업그레이드 안내는 tech-log-backend에 실제로 적용해 보지 않았다.

검증: 문서만. 리뷰어별 실행 명령은 각 문서 "범위" 절.

Refs: docs/reviews/2026-11-03-rereview/README.md 9절
This commit is contained in:
DongHyeonka
2026-11-04 00:21:51 +09:00
parent bbe944bd3c
commit ecc74b7df7
6 changed files with 1438 additions and 0 deletions
@@ -110,3 +110,36 @@ Minor 41건은 각 문서에 있다.
- **짝 프론트**: `IDEMPOTENCY_COMPLETION_UNKNOWN`(503, 결과 불명)을 인계 문서에 더했다.
- **이 환경에서 확인할 수 없는 것**: 실제 CI runner 실행.
## 9. 2차 재리뷰 (수정 커밋 `bbe944bd`만, 2026-11-04)
1차 재리뷰 수정(`bbe944bd`, 406파일)을 리뷰어 4명이 같은 템플릿·스킬 방식으로 다시 봤다(`round2/01~04-*.md`). 저장소 전체가 아니라 이 커밋만 본 이유: 원래 리뷰와 1차 재리뷰가 전 영역을 이미 봤고, 위험은 "수정이 새 결함을 만든다"는 반복 패턴이다.
| 문서 | Important | Minor | 이번 라운드가 새로 만든 Important | 회귀 |
|---|---|---|---|---|
| [round2/01 core·inbound](round2/01-core-app-inbound.md) | 2 | 5 | RR-01-12 | 0 |
| [round2/02 persistence·messaging](round2/02-persistence-messaging.md) | 1 | 7 | RR-02-09 | 0 |
| [round2/03 outbound](round2/03-outbound.md) | 1 | 7 | 없음 | 0 |
| [round2/04 bootstrap·build·sample](round2/04-bootstrap-build-sample.md) | 3 | 3 | RR2-04-01, RR2-04-02 | 0 |
Important 7건:
- RR-01-11 — `http-contract.md`는 결과 불명 503 뒤 같은 키 재전송이 lease 뒤 500으로 막힌다고 적었지만, Redis store는 lease가 지난 EXECUTING을 넘겨받아 작업을 다시 실행한다(실 Redis 확인). RR-02-03 부분.
- RR-01-12 — 새 `@SystemInvoked` 규칙 두 개가 매뉴얼 09장의 이벤트 소비 handler → 쓰기 use case 경로를 막는다.
- RR-03-11 — Redis claim이 key TTL을 replay TTL로 둬서, replay TTL < processing lease인 배포에서 lease 도중 key가 사라져 같은 키가 두 번 실행된다(실 Redis Lua 확인). RR-04-08 부분.
- RR-02-09 — V22가 `outbox_event`에 가장 강한 잠금을 걸면서 `lock_timeout`이 없다(실 PG16: 19초 대기, 그동안 읽기·쓰기 막힘).
- RR2-04-01 — prod `fixture-` 거부가 비밀이 아닌 값(`HOSTNAME` 등)까지 막는다.
- RR2-04-02 — 데모 허용 목록의 `test`·`demo` 프로필로 sample이 뜨지 않는다(이미지 실행 문서대로 하면 기동 거부).
- RR2-04-03 — 기동 rule runner에 검사 없는 면제 경로가 남아 `@Value` 필드·JavaBean 설정이 조용히 null(RR-06-01 부분).
### 9.1 결정 (3차 수정용, 2026-11-04)
| 항목 | 결정 | 이유 |
|---|---|---|
| RR-01-11 결과 불명 뒤 재전송 | 두 멱등성 store(PostgreSQL·Redis)가 같은 공유 계약을 따른다: lease가 지난 실행 중 기록은 작업을 다시 돌리지 않고 "회복 필요"로 답한다. 계약 문서와 코드를 맞춘다 | 결과 불명인 작업을 서버가 몰래 다시 실행하면 이번 계약의 목적(중복 효과 방지)이 무너진다 |
| RR-03-11 Redis key TTL | claim·renew 모두 key TTL ≥ max(replay TTL, processing lease). 설정 검사도 둔다 | lease가 남아 있는 동안 key가 사라지면 안 된다 |
| RR-01-12 소비 경로 | 사용자가 닿는 전송(web·GraphQL·gRPC·WebSocket)만 `@SystemInvoked` use case에 닿지 못한다. 시스템이 부르는 inbound(메시지 소비자·스케줄러)는 명시적 표시로 허용하고, 매뉴얼 09장 경로를 실제 테스트로 고정한다 | 규칙의 목적은 "사용자 요청이 권한 검사 없이 쓰기에 닿지 않게"다. 시스템 경로까지 막으면 매뉴얼이 거짓이 된다 |
| RR2-04-01 fixture 값 거부 범위 | 비밀로 분류된 키(`docs/registries/secrets-classification.yaml`)만 검사한다 | 운영 hostname·이름은 비밀이 아니다 |
| RR2-04-02 데모 프로필 | 허용 목록의 각 프로필은 sample이 실제로 뜨는 프로필이어야 한다. 뜨게 고치거나, 독립 실행용이 아니면 목록에서 뺀다. 문서·Dockerfile과 맞춘다 | 허용한 프로필로 뜨지 않으면 허용 목록이 거짓이다 |
| RR-02-09 V22 잠금 | V21과 같은 `SET LOCAL lock_timeout`과 같은 모양의 lane 테스트 | 같은 커밋 안의 두 마이그레이션이 다른 규칙을 따르면 안 된다 |
멈추는 기준: 3차 수정 뒤 그 diff만 보는 확인 리뷰에서 새 Important가 0이면 멈춘다.
@@ -0,0 +1,314 @@
# 01 core·application·inbound 재리뷰 (2026-11-03, 2차)
경로는 저장소 루트 기준이다. 코드 경로는 `src/`가 앞에 붙는다.
## 범위 — 본 pathspec, 불러온 스킬과 적용한 기준, 실행한 명령과 결과, 못 본 것
### 본 pathspec
- 리뷰 범위: Base `7ef8d0b4` → Head `bbe944bd`(커밋 1개) 중 아래 pathspec. 152파일, +5,757 −692.
```text
src/domain-core src/shared-contract src/application-core src/application-fileserver
src/application-objectstorage src/composition src/adapter/inbound src/grpc src/grpc-advanced
scripts docs/manual docs/web
```
- 맡은 1차 재리뷰 발견: RR-01-01~10, RR-02-01~08, RR-07-01, RR-07-06, RR-04-04(=RR-01-05).
- 이 문서의 새 발견 ID는 `RR-01-11`부터다. 1차의 `RR-01-01~10`과 겹치지 않게 이어 붙였다.
- 읽은 방식: diff가 커서 여러 번에 나눠 직접 읽었다(하위 에이전트 없음).
1. application-core main diff 전부(멱등성 executor·예외, `IntegrationEventDraft`·`IntegrationIdentity`,
`SubmitDurableOperationUseCase`, outbox 포트·relay·`OutboxPublishAttempt`, `SystemInvoked`).
2. application-core testFixtures 중 멱등성 저장소 계약, outbox 순서 계약·fake, `OverlappingWrites`,
`DirectTransactionPort`, 캐시 계약 추가분.
3. composition: service-runtime(`PermissionEnforcementGuard`), outbox-relay(조립·지표·설정),
idempotency(`IdempotencySettings`), fileserver-platform(move 조립).
4. web main diff 전부(`EnvelopeErrorController`, `HttpStatusErrorCodes`, `EnvelopeBodyAdvice`,
`SecurityConfig`, `WebMvcPlatformAutoConfiguration`, `RetryAfterAdvisor`)와 새 시스템 테스트·testkit.
5. GraphQL scorer diff와 새 union·interface 테스트. 같은 leaf의 page 크기 계산 복사본을 grep으로 전수 확인.
6. gRPC: `GrpcClaimToken`, 포트, JPA adapter·repository·entity·V003, in-memory fake, 공유 계약 diff,
interceptor·decision, 기동 검증기.
7. application-fileserver: move use case, `FileAccessSubject.owns`, 새 계약 6개의 케이스 목록과 상속 관계,
쿼터 fake.
8. 생성 명령 템플릿·탐침·`verify-feature-scaffold.sh` diff, 매뉴얼 04·05·06·07·09 diff, `docs/web/http-contract.md` diff.
- 범위 밖에서 확인용으로 읽은 것: `ApplicationBoundaryArchitectureTest`(D4·새 ArchUnit 2개),
`RequiresPermissionAuthorizationManager`, `adapter/inbound/messaging/README.md`·통합 테스트의 handler 모양,
Redis 멱등성 Lua(`IdempotencyScripts.java`)와 adapter, `PostgreSqlIdempotencyStore`와 그 PG 테스트,
`JpaFileQuota`·`JpaQuotaReclaim`(호출자 트랜잭션 요구 여부), `docs/registries/error-codes.yaml` diff,
ADR-GRPC-004 diff.
### 불러온 스킬과 적용한 기준
| 스킬 | 적용한 기준 | 무엇을 봤나 |
| --- | --- | --- |
| `superpowers:requesting-code-review` | 리뷰어 템플릿(Strengths → Critical/Important/Minor → Declined → Assessment), 실제 심각도로 분류, 읽지 않은 코드에 판정 금지 | 문서 양식 전체. 발견마다 "고치는 법"과 4절 결정을 코드로 대조 |
| `clean-architecture` | 의존은 안쪽으로, 포트는 안쪽이 소유, composition root(Main)가 조립, 경계에서 framework 격리 | `@SystemInvoked` 조립 규칙이 시스템 호출자(relay·이벤트 소비자)를 composition에서 조립할 수 있게 두는지, web leaf가 application-core 상수를 읽는 방향, 계약 키트 위치 |
| `api-and-interface-design` | 일관된 오류 의미, Hyrum's Law(관찰되는 동작이 계약), 멱등 키의 세 결과(성공·실패·불명)와 in-flight 중복 처리, 계약과 구현의 일치 | `IDEMPOTENCY_COMPLETION_UNKNOWN`이 약속한 재전송 판정을 저장소 구현이 지키는지, `/error` 응답 status·모양, gRPC·GraphQL wire 변경 표시 |
| `security-and-hardening` | 인가는 모든 요청에서, 오류 본문에 내부 정보 금지, 자원 상한(DoS), 숨은 우회 경로 | ERROR 디스패치 허용이 새 노출을 만드는지, `@SystemInvoked` 우회 경로, GraphQL union 아래 page 상한, 파일 move 쿼터 우회 |
### 실행한 명령과 결과
| 명령 | 결과 |
| --- | --- |
| `git diff --stat / --shortstat 7ef8d0b4..bbe944bd -- <pathspec>` | 152파일 +5,757 −692 |
| `git grep`으로 `@SystemInvoked` 사용처, `new PublishPendingOutboxEventsUseCase`, `effectivePageSize`, `sendError(`, `SecurityFilterChain`, `extends <각 fileserver 계약>` 전수 확인 | 아래 표·발견의 근거 |
| `git worktree add --detach <scratchpad>/rr2-01 bbe944bd` 후 `IdempotencyStoreContract`에 탐침 메서드 1개 추가, `flock … ./gradlew :adapter:outbound:cache-redis:redisContainerContractTest --console=plain -i` | 첫 실행은 탐침의 Error Prone `ReturnValueIgnored`로 컴파일 실패(탐침 코드 문제). 고친 뒤 `BUILD SUCCESSFUL in 44s`, 출력 `RR2-PROBE … duringLease=InProgress afterLease=TakenOverClaimed`(RR-01-11) |
| `git worktree remove --force <scratchpad>/rr2-01` | 탐침과 함께 삭제 |
### 못 본 것
- 전체 게이트는 다시 돌리지 않았다. 재리뷰 README 7절 결과를 읽기만 했다.
- gRPC ledger의 PG lane(`JpaGrpcOperationLedgerContractIT`)은 다시 돌리지 않았다. 동시 commit 경쟁은 그 lane이
7절 게이트(`-p optional-platforms … integrationCheck`)에서 통과했다는 기록과 SQL을 읽은 것에 기댄다.
- Jetty의 오류 디스패치, 관리 포트를 따로 둔 배포의 오류 처리는 보지 않았다.
- application-core의 outbox·messaging 변경(RR-05-xx, 06-10~14)은 diff를 읽었지만 판정은 05 영역 리뷰어 몫으로 두었다
(「Declined to judge」).
- sample-portfolio(데모 체인의 ERROR 디스패치 허용, `WorkLogReservedPayload`)는 pathspec 밖이라 grep으로 수정 여부만 봤다.
## Strengths
- `@SystemInvoked` 빈은 advisor가 있어도 기동을 멈춘다. 검사가 advisor 검사보다 먼저다
(`src/composition/service-runtime/.../authorization/PermissionEnforcementGuard.java:57-70`). 테스트가 "advisor가 있어도
실패"를 고정한다(`PermissionEnforcementGuardTest.aSystemInvokedUseCaseRegisteredAsABeanFailsStartupEvenWithAnAdvisor`).
- relay는 여전히 `new`로 조립돼 scheduler에만 들어간다(`src/composition/outbox-relay/.../OutboxRelayAutoConfiguration.java:80`).
새 기동 차단이 relay를 막지 않는다.
- gRPC ledger의 모든 전이가 `claim_attempt`를 조건에 넣은 UPDATE 한 문장이다
(`GrpcOperationLedgerRepository.java` `tryReclaimFailed`·`tryReclaimStale`·`tryMarkCommitted`·`tryMarkFailed`).
load-check-save가 사라졌다. 공유 계약에 "옛 owner의 실패 무시"(`GrpcOperationLedgerContract.java:439`)와
"동시 commit은 하나만"(`:515`)이 들어가 fake와 PG adapter가 같이 받는다.
- claim이 "충돌인데 행이 없음"을 보면 insert를 한 번 더 한다(`JpaGrpcOperationLedger.java:49-62`). 1차의 purge 경쟁이 닫혔다.
- GraphQL scorer가 `GraphQLCompositeType`으로 내려간다(`GraphQlDocumentComplexityScorer.java:154,232,265`). union과
interface 각각 "중첩 list 곱셈"과 "page 상한 거부"를 테스트한다(`GraphQlDocumentComplexityScorerTest.java:299` 등).
- `/error` 응답이 요청에서 아무것도 싣지 않는다(`EnvelopeErrorController.java:60-71`). 실제 Tomcat에서 방화벽 거부
경로를 단언하고, 기본 JWT 체인에서 "오류 디스패치는 원래 400, `/error` 직접 호출은 401"을 둘 다 확인한다
(`JwtChainErrorDispatchIT`).
- status → code 표가 한 곳이다(`HttpStatusErrorCodes.java:18`). 예외 처리기와 오류 컨트롤러가 같은 표를 쓴다.
- move의 쿼터 이동이 relocate와 같은 트랜잭션이다(`MoveFileApplicationUseCase.java:92-109`). JPA 쪽 세 포트가 모두
호출자 트랜잭션을 요구하므로(`JpaFileQuota.java:39,58,71`, `JpaQuotaReclaim.java:42`) 버전 충돌이면 쿼터도 롤백된다.
- 생성 계약에 `inTransaction` hook이 생겼고(`__Feature__RepositoryContract.java.tmpl:41`), 왕복 검사가 "호출자
트랜잭션 밖이면 거부하는 저장소"로 계약을 한 번 더 돌린다(`scripts/verify-feature-scaffold.sh:140-161`). 확인할
결과 XML 목록도 템플릿에서 만든다(`:102`).
- Retry-After 2초가 상수 하나이고(`IdempotencyExecutor.IN_FLIGHT_RETRY_AFTER`), lease가 그 이하면 기동이 실패한다
(`IdempotencySettings.java:57`).
- 파일 소유자 규칙이 `FileAccessSubject.owns` 하나다(`FileAccessSubject.java:63`). fake와 `RoleBasedFileAccessPolicy`가
둘 다 부르고, `FileAccessPolicyPortContract`를 둘 다 상속한다.
## 발견 재확인 표
| ID | 상태 | 근거 |
| --- | --- | --- |
| RR-01-01 | 닫힘 | 템플릿 계약의 모든 호출이 `inTransaction`을 거친다(`__Feature__RepositoryContract.java.tmpl:41` 이하). 탐침 `CallerTransaction__Feature__RepositoryContractTest.java.tmpl`이 트랜잭션 요구 저장소로 계약을 통과시키고, `verify-feature-scaffold.sh:140-161`이 그 결과 XML을 확인한다. 매뉴얼 04장 4단계에 hook 사용을 적었다 |
| RR-01-02 = RR-07-01 | 닫힘(결정대로) | 4절 결정 두 가지가 다 들어갔다: 빈이면 기동 실패(`PermissionEnforcementGuard.java:57-70`), inbound adapter 의존 금지 ArchUnit(`ApplicationBoundaryArchitectureTest.java:455-467`). 결정이 만든 새 위험 → RR-01-12 |
| RR-01-03 | 닫힘 | 07장(`docs/manual/07-authorization.md:65-89`), 09장(`docs/manual/09-outbox-events.md:56-87`), 06장(`:44-46`) 문장이 코드와 맞다. `INTEGRATION_EVENT_DRAFTS_ARE_BUILT_BY_THE_SHARED_HELPER`(`ApplicationBoundaryArchitectureTest.java:475`), `application-core/CLAUDE.md` 표에 두 타입 |
| RR-01-04 (+RR-07-06) | 닫힘 | 저장 포트 9개 모두 계약이 있고 fake와 PG 테스트가 각각 상속한다(`extends` grep: ContentReferenceLedger·FileQuotaLedger·RecoveryQueue·StagingUploadLocator·UploadSession·FileMetadata·CleanupQueue). `FileQuotaLedgerContract`가 만료·해제 뒤 확정·연장 거부를 같은 표로 본다. build.gradle 주석도 사실대로 고쳤다 |
| RR-01-05 = RR-04-04 | 닫힘 | `MoveFileApplicationUseCase.java:100-109`가 대상 `requireRoom` → 예약·확정 → 출발 회수를 relocate와 한 트랜잭션에서 한다. 테스트 두 개(`FileLifecycleUseCasesTest.java:467,485`). 남은 작은 틈 → RR-01-17 |
| RR-01-06 | 닫힘 | 2^53 경우(`CacheRegionContract`), 트랜잭션 밖 거부·롤백 번호 재사용(`OutboxAggregateSequenceContract`), 시간 경우는 시계 없으면 abort(`IdempotencyStoreContract.java:94`). 새로 넣은 겹침 경우의 fake 실행 방식 → RR-01-16 |
| RR-01-07 | 닫힘 | `__Feature__Config.java.tmpl:36` `afterName = PersistenceJpaAutoConfiguration` |
| RR-01-08 | 닫힘(범위 밖 grep) | `sample-portfolio/.../WorkLogReservedPayload.java:15`가 `IntegrationIdentity.isCanonical`을 부른다 |
| RR-01-09 | 닫힘 | `shared-contract/README.md:369-370`, `RuntimeEnvironment.java:32-33`, application-core README 알림 절 정리 |
| RR-01-10 | 닫힘 | `verify-feature-scaffold.sh:102-127`이 템플릿의 `*Test.java.tmpl` 전부에서 결과 XML 경로를 만들고 `tests="0"`도 거부한다 |
| RR-02-01 | 닫힘 | 위 Strengths. union·interface 아래 곱셈·page 상한 테스트 4개 |
| RR-02-02 | 닫힘 | `EnvelopeErrorController` + `SecurityConfig.java:91` ERROR 디스패치만 허용 + `EnvelopeBodyAdvice`가 4xx·5xx를 감싸지 않음. 실 Tomcat·JWT 체인 테스트. 문서와 다른 작은 점 → RR-01-13 |
| RR-02-03 | 부분 | 코드 분기(`IdempotencyExecutor.java:251,286`)와 테스트는 들어갔다. 그러나 이 코드를 실제로 내는 저장소는 Redis뿐이고, Redis는 lease가 지난 EXECUTING 기록을 넘겨받아 작업을 다시 돌린다. 계약 문서가 약속한 "lease 뒤 500 RECOVERY_REQUIRED"가 지켜지지 않는다 → RR-01-11 |
| RR-02-04 | 닫힘 | 토큰·V003·조건부 UPDATE·계약 케이스(Strengths). `release`만 토큰 밖에 남았다 → RR-01-15 |
| RR-02-05 | 닫힘 | `IdempotencySettings.java:57`, `RetryAfterAdvisor`가 같은 상수를 읽는다 |
| RR-02-06 | 닫힘 | `GrpcStatusMapperTest`·`GraphQlWireErrorMapperTest` 케이스, 두 README, registry `compatibility_impact: behavior-change` |
| RR-02-07 | 닫힘 | 검증기 문구(`GrpcPlatformStartupValidator.java` keyed-method 메시지), ADR-GRPC-004 "(b)" 기록, `src/grpc/CLAUDE.md:168` |
| RR-02-08 | 부분 | ② Javadoc은 고쳤다(`GraphQlDeadline.java:17-19`). ① calculator의 복사본은 지웠지만 같은 규칙의 세 번째 복사본이 `GraphQlClientPolicy.java:101`에 남았다 → RR-01-14 |
| RR-07-01 | 닫힘(결정대로) | = RR-01-02 |
| RR-07-06 | 닫힘 | `FileAccessSubject.owns` 한 곳, `FileAccessPolicyPortContract`를 `FakeFileAccessPolicyContractTest`와 `RoleBasedFileAccessPolicyContractTest`가 상속 |
| RR-04-04 | 닫힘 | = RR-01-05 |
회귀로 판정한 발견은 없다.
## Issues
### Critical (Must Fix)
없음.
### Important (Should Fix)
#### RR-01-11 · `IDEMPOTENCY_COMPLETION_UNKNOWN` 뒤 "같은 키 재전송은 안전" 약속을 Redis 저장소가 지키지 않는다 — lease가 지나면 작업을 다시 돌린다
- **위치**: `docs/web/http-contract.md:108-114`, `src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyCompletionUnknownException.java:16-17`,
`src/shared-contract/src/main/java/dev/caskeleton/shared/error/OperationalError.java:50`(주석), `docs/registries/error-codes.yaml:448-450`(주석),
`src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/idempotency/IdempotencyScripts.java:71-79`,
`src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyExecutor.java:136-137`
- **무엇이 틀렸나**:
- 새 계약은 "결과 불명 503을 받으면 같은 키로 다시 보내라. 서버가 판정한다 — 기록됐으면 재생, lease 안이면 409,
lease가 지났으면 500 `IDEMPOTENCY_RECOVERY_REQUIRED`"라고 적는다(`http-contract.md:111-113`, 예외 Javadoc `:16-17`).
- 이 예외는 `complete`가 `UNAVAILABLE`을 돌려줄 때만 난다. `UNAVAILABLE`을 돌려주는 저장소는 Redis뿐이다
(`RedisIdempotencyStoreAdapter.java:248,251` — lane이 보내기 전에 거절). PostgreSQL 저장소에는 `UNAVAILABLE` 결과가
아예 없다(`PostgreSqlIdempotencyStore`에서 grep 0건). 즉 결과 불명은 실제로 Redis 배포에서만 생긴다.
- 그때 Redis 기록은 `EXECUTING`으로 남는다(complete가 보내지지 않았다). 그런데 Redis CLAIM 스크립트는 상태를 가리지
않고 lease가 끝난 기록을 넘겨준다: `if state == 'FAILED_RETRYABLE' or (leaseUntil ~= nil and leaseUntil <= nowMillis)`
→ `TAKEN_OVER`(`IdempotencyScripts.java:71-79`). executor는 `TakenOverClaimed`를 받으면 `startAndRun`으로 작업을 다시
돌린다(`IdempotencyExecutor.java:136-137`).
- PostgreSQL은 반대다. lease가 지난 `EXECUTING`은 `ABANDONED`로 바꾸고 `RecoveryRequired`를 준다
(`PostgreSqlIdempotencyStore.java:153-155`, 테스트 이름 `expiredExecutingRecordRequiresReconciliationAndIsNeverBlindlyTakenOver`).
공유 `IdempotencyStoreContract`는 이 경우를 묶지 않는다("expiry and take-over … stay with each store's own tests", `:34-35`).
그래서 두 저장소가 갈라진 채 게이트를 통과한다.
- **왜 중요한가**:
- 4절 결정이 막으려던 것은 "결과 불명을 '안 됨'으로 믿고 다시 실행"이다. 새 코드는 클라이언트에게 "같은 키면 안전"이라고
말하는데, 이 코드가 나는 유일한 저장소에서 같은 키 재전송이 lease(기본 30초) 뒤 작업을 다시 실행한다.
- 발생 조건: `provider=redis` + complete 단계에서 lane이 포화·종료 중 + action이 트랜잭션 밖 효과(외부 호출·메일)를 가짐 +
클라이언트가 계약대로 30초 넘게 재시도. 결과: 외부 효과가 두 번 일어난다. 클라이언트는 "같은 키라 안전"이라고 믿었으므로
이상을 알아챌 근거가 없다.
- DB만 쓰는 action이고 `execute`가 `tx.inWrite` 안이면(sample `PublishPosterImageUseCase.java:109-118`) DB 효과는 롤백되므로
다시 돌리는 것이 오히려 맞다. 하지만 그것도 계약 문장("500 RECOVERY_REQUIRED")과 다르다. 어느 쪽이든 문서가 틀렸다.
- 사용자 원칙: 위험이 코드에 드러나야 한다. 지금은 두 저장소의 차이가 각자의 테스트에만 있고, 계약 문서는 PG 쪽만 말한다.
- **고치는 법**: 4절 결정 문장("lease 뒤 회복 필요")을 기준으로 맞춘다.
1. Redis CLAIM 스크립트: `state == 'EXECUTING'`이고 lease가 끝났으면 `ABANDONED`로 바꾸고 `RECOVERY_REQUIRED`를 돌려준다.
lease 만료 넘겨받기는 `CLAIMED`(실행 전)와 `FAILED_RETRYABLE`만 한다. PG와 같은 규칙이다.
2. `IdempotencyStoreContract`에 시간 경우 하나: "실행 시작 뒤 lease가 지나면 다른 claim은 `RecoveryRequired`".
in-memory는 abort되고 Live Redis·PG lane이 실제로 돈다(아래 탐침이 그 모양이다).
3. 예외 Javadoc의 "Effects inside the action's own transaction roll back"을 "`execute`를 쓰기 트랜잭션 안에서 부른 경우"로
좁힌다. action이 자기 트랜잭션을 따로 커밋하면 DB 효과도 남는다.
- Redis 스크립트 변경은 04 영역 파일이다. 계약 문서·계약 테스트·Javadoc은 이 영역이다.
- **가이드 심각도·우선순위**: Medium · P2 (Redis 배포·complete 단계 lane 거절·외부 효과가 겹칠 때만. 기본 조립은 멱등성 비활성)
- **증거**: E3 — 아래 탐침. 코드 경로는 E1.
- 탐침: worktree에서 `IdempotencyStoreContract`에 메서드 하나를 넣었다. claim(lease 1s) → `markExecutionStarted` →
다른 attempt로 claim(lease 안) → `elapse(2s)` → 다른 attempt로 claim. `LiveRedisIdempotencyStoreContractTest`(Testcontainers
Redis, 실제 서버 시계)로 `redisContainerContractTest` lane을 돌렸다.
- 출력: `RR2-PROBE LiveRedisIdempotencyStoreContractTest duringLease=InProgress afterLease=TakenOverClaimed`,
`BUILD SUCCESSFUL in 44s`. lease 안에서는 409가 되고, lease 뒤에는 계약이 말한 `RecoveryRequired`가 아니라
`TakenOverClaimed`다 — executor는 이것을 받으면 작업을 다시 돌린다.
- PG 쪽 반대 동작은 기존 테스트 `PostgreSqlIdempotencyIntegrationTest.java:164`가 고정한다(E2, 다시 돌리지 않음).
#### RR-01-12 · 새 `@SystemInvoked` 규칙 둘이 매뉴얼 09장의 이벤트 소비 경로(쓰기 use case 호출)를 막는다 — 규칙을 지키는 방법이 문서에 없다
- **위치**: `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ApplicationBoundaryArchitectureTest.java:455-467`,
`src/composition/service-runtime/src/main/java/dev/caskeleton/composition/runtime/authorization/PermissionEnforcementGuard.java:57-70`,
`docs/manual/09-outbox-events.md:115-117`, `docs/manual/07-authorization.md:65-89`, `src/adapter/inbound/messaging/README.md:32,95`
- **무엇이 틀렸나**:
- 매뉴얼 09장 4단계는 소비 handler(`MessageHandler<T>`)를 `adapter:inbound:messaging`에 두고 "delivery 하나를 use case 호출
하나로 바꾸라, use case는 평소처럼 `tx.inWrite`로 쓴다"고 가르친다. 소유자 결정 10(Kafka 소비)의 정식 경로다.
- 그 use case는 쓰기다(`WRITE_REPOSITORY`). 지금 쓰기 use case가 고를 수 있는 길은 셋인데, 소비 handler에서는 셋 다 막힌다.
1. `@RequiresPermission` + bean: 소비 스레드에는 `Authentication`이 없다. `RequiresPermissionAuthorizationManager.java:56`이
`auth == null`이면 거부한다. 메시지는 재시도 후 DLQ로 간다.
2. `@SystemInvoked`(07장이 말하는 "시스템이 부르는 쓰기"): bean이면 이번 라운드의 가드가 기동을 막는다. handler가 그
클래스에 의존하면 이번 라운드의 ArchUnit이 막는다 — 규칙이 `..adapter.inbound..` 전체를 대상으로 하므로
`dev.caskeleton.adapter.inbound.messaging`도 들어간다(`:458`).
3. 표시 없음: D4(`MUTATING_USE_CASES_DECLARE_REQUIRED_PERMISSION`)가 빌드를 막는다.
- 남는 길은 "handler가 구체 클래스 대신 `CommandUseCase<C,R>` 같은 인터페이스에 의존하고, composition이 `new`로 만든
`@SystemInvoked` use case를 handler bean에 넣는다"뿐이다. 이 방법은 07장·09장·messaging README·ArchUnit 메시지 어디에도
없다. ArchUnit 메시지는 "scheduler에 넘긴다"고만 한다. 게다가 messaging README는 handler를 app-bootstrap에서 등록하는
안을 버렸다(`:95`).
- 이번 라운드 전에는 `@SystemInvoked` use case를 bean으로 만들어 handler에 넣는 길이 있었다(그래서 RR-01-02가 위험했다).
그 문을 닫으면서 정당한 시스템 호출자 하나(소비자)의 길을 문서 없이 함께 닫았다.
- **왜 중요한가**:
- 첫 소비자를 붙이는 파생 서비스는 매뉴얼대로 하면 기동·빌드·런타임 중 하나에서 반드시 실패한다.
- 실패를 끄는 가장 쉬운 우회가 위험하다. `repositoryAccess`를 낮춰 D4를 피하면 권한 표시 없는 쓰기 use case가 bean으로
생기고, 컨트롤러도 그것을 주입받을 수 있다. RR-01-02가 막으려던 "검사 없는 쓰기"가 다른 문으로 돌아온다.
- 사용자 원칙: 선택지가 여럿이면 고른 방법·버린 대안·이유가 남아야 하고, 개발자가 따로 기억해야 하는 규칙은 결함이다.
- **고치는 법**: 둘 중 하나를 고르고 기록한다.
- (a) 경로를 문서로 고정: 09장 4단계와 07장 「시스템이 부르는 쓰기」에 "소비 handler는 use case를 인터페이스(또는
application-core가 소유한 함수형 포트)로 받고, `@SystemInvoked` use case는 소비 조립(composition)이 `new`로 만들어
handler bean에 넣는다"를 적는다. 예시 조립 하나(`InboxRedeliveryIntegrationTest`의 handler 모양을 그 방식으로)와
ArchUnit 메시지에 "scheduler 또는 소비 handler"를 넣는다.
- (b) 규칙을 좁힘: ArchUnit 대상에서 `..adapter.inbound.messaging..`을 빼고, 대신 "messaging inbound는 HTTP·gRPC·GraphQL·
WebSocket 패키지에 의존하지 않는다"로 노출 경로를 막는다. 가드는 그대로 둔다(소비 handler가 use case를 `new`로 만들면 bean이
아니다).
- 어느 쪽이든 07장 "지금 이해하면 되는 것"의 "시스템만 부르는 쓰기" 줄에 소비자를 넣는다.
- **가이드 심각도·우선순위**: Medium · P2 (런타임 결함이 아니라 매뉴얼이 가르치는 경로와 새 규칙의 충돌. 템플릿에 소비자는 아직 없다)
- **증거**: E1 — 규칙 대상 패키지(`:458`), 가드 조건(`:57`), 인가 관리자의 무인증 거부(`:56`), 매뉴얼 4단계(`:115-117`)를 대조했다.
ArchUnit을 fixture로 돌려 보지는 않았다.
### Minor (Nice to Have)
#### RR-01-13 · `/error` 응답이 표에 없는 status를 400·500으로 바꾸는데, 정본은 "원래 status가 그대로 나간다"고 적는다
- **위치**: `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/error/EnvelopeErrorController.java:65-70`,
`HttpStatusErrorCodes.java:32-35`, `EnvelopeResponseWriter.java:37`, `docs/web/http-contract.md:59`
- **무엇이 틀렸나**: 오류 컨트롤러는 디스패치 status를 `HttpStatusErrorCodes`로 코드에 바꾼 뒤 그 코드의 status를 다시 쓴다.
표에 없는 4xx(408·409·410·422 등)는 `BAD_PARAMETER` 400, 표에 없는 5xx(501·502·504)는 `INTERNAL_ERROR` 500이 된다.
Boot 기본 컨트롤러는 원래 status를 그대로 냈다. 지금 main 코드에 `sendError`는 없어서(grep 0건) 나오는 경우는 컨테이너·
라이브러리가 낸 오류뿐이다.
- **왜 중요한가**: 정본 1절의 "원래 status가 그대로"는 표에 있는 status에서만 참이다. 필터를 더하는 서비스가 `sendError(409)`를
쓰면 400으로 바뀌어 클라이언트 분기가 틀어진다.
- **고치는 법**: 문장을 "표에 있는 status는 그대로, 그 밖은 400·500으로 접힌다"로 고치거나, 오류 컨트롤러가 status는 원래 값을
두고 code만 표로 고르게 한다(`EnvelopeResponseWriter`에 status를 따로 받는 overload).
- **가이드 심각도·우선순위**: Low · P3 · **증거**: E1
#### RR-01-14 · page 크기 규칙의 세 번째 복사본이 남았다(RR-02-08 ① 부분)
- **위치**: `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/policy/GraphQlClientPolicy.java:101-107`
- **무엇이 틀렸나**: 지운 `GraphQlComplexityCalculator.effectivePageSize`와 같은 "둘 다 있으면 `first`" 규칙이 public 메서드로
`GraphQlClientPolicy`에 있다. 상한 검사도 없다. main 호출자는 없고 테스트(`GraphQlClientPolicyTest.java:45-47`)만 부른다.
실제 점수는 `connectionCost`(큰 쪽), 실제 resolver 쪽은 `GraphQlConnectionPolicy.effectivePageSize`(방향 섞임 거부)다.
- **왜 중요한가**: 갈라진 복사본이다. adopter가 이름만 보고 이것을 resolver에서 부르면 상한 없는 page를 받는다.
- **고치는 법**: 지우고 테스트를 `GraphQlConnectionPolicy` 쪽으로 옮긴다.
- **가이드 심각도·우선순위**: Low · P3 · **증거**: E1(grep)
#### RR-01-15 · gRPC ledger `release`는 토큰 밖에 있고, 행이 지워지면 시도 번호가 1로 돌아간다
- **위치**: `src/grpc/grpc-core-api/src/main/java/dev/caskeleton/grpc/api/ledger/GrpcOperationLedger.java:143`,
`src/grpc/grpc-operation-ledger-jpa/src/main/java/dev/caskeleton/grpc/ledger/JpaGrpcOperationLedger.java:204-207`,
`GrpcOperationLedgerRepository.java:48`, `GrpcClaimToken.java:14-15`
- **무엇이 틀렸나**: 다른 전이는 모두 토큰을 받는데 `release(identity)`는 토큰 없이 `deleteById`한다. 지운 뒤 새 claim은
`claim_attempt = 1`로 시작한다. 그래서 `GrpcClaimToken` Javadoc의 "두 시도는 같은 값을 나눠 갖지 않는다"는 release·purge 뒤에는
거짓이다. 옛 attempt 1 owner가 그때 살아 있으면 새 attempt 1의 claim에 commit·실패를 기록할 수 있다(ABA).
- **왜 중요한가**: 지금 main에 `release` 호출자는 없고, purge는 24h 지난 완료 행만 지우므로 실제 창은 아주 좁다. 다만 포트에
"토큰 없는 파괴 연산"이 남아 있고 Javadoc이 반대로 말한다.
- **고치는 법**: `release(identity, claimToken)`으로 바꿔 `DELETE … WHERE claim_attempt = :token AND state = 'IN_PROGRESS'`로 하거나,
포트에서 지운다. Javadoc 문장을 "같은 행이 살아 있는 동안"으로 좁힌다.
- **가이드 심각도·우선순위**: Low · P3 · **증거**: E1
#### RR-01-16 · 새 "첫 쓰기 두 개가 겹침" 계약 케이스가 fake에서는 겹치지 않는다
- **위치**: `src/application-core/src/testFixtures/java/dev/caskeleton/application/outbox/testkit/OutboxAggregateSequenceContract.java:71-83`,
`src/application-core/src/testFixtures/java/dev/caskeleton/application/transaction/testkit/DirectTransactionPort.java:47,115-118`
- **무엇이 틀렸나**: `OverlappingWrites`는 두 스레드에서 트랜잭션을 연다. in-memory 계약 테스트의 `DirectTransactionPort`는
스레드를 구분하지 않는 필드 하나(`current`)로 "열린 트랜잭션"을 기억한다. 둘째 스레드는 첫 스레드의 트랜잭션이 열려 있는 것을
보고 거기에 join한다(`:117`). fake에서는 "겹친 두 트랜잭션"이 아니라 "한 트랜잭션 안의 두 호출"을 검사한다. `ArrayList`도
두 스레드가 같이 고친다.
- **왜 중요한가**: 실제 대상인 PG에서는 의미대로 돈다. fake에서는 녹색이 아무것도 말하지 않고, 경쟁 상태가 있는 테스트 코드라
드물게 흔들릴 수 있다.
- **고치는 법**: `DirectTransactionPort`의 `current`를 `ThreadLocal`로 바꾸거나, fake 계약 테스트에서 이 케이스를 순차 실행으로
바꾸고 그렇게 적는다.
- **가이드 심각도·우선순위**: Low · P3 · **증거**: E1
#### RR-01-17 · move의 "거절되면 아무것도 바뀌지 않는다"는 쓰기 전 거절에서만 테스트된다
- **위치**: `src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/lifecycle/MoveFileApplicationUseCase.java:38-40,92-109`,
`FileLifecycleUseCasesTest.java:485`
- **무엇이 틀렸나**: 테스트는 `requireRoom`에서 거절되는 경우(아직 아무것도 안 씀)만 본다. 쿼터를 옮긴 뒤 `relocate`가 버전 충돌로
실패하는 경우의 롤백은 JPA 포트들이 호출자 트랜잭션에 합류한다는 사실에만 기댄다. 쿼터 fake는 롤백을 모르므로 use case 테스트로는
볼 수 없고, PG lane에도 move 케이스가 없다. 또 이번 수정 전에 move된 파일은 여전히 출발 namespace에 잡혀 있고, 그 파일을 지우면
지금 namespace에서 회수한다. 이 과거 데이터의 처리 방법이 어디에도 없다.
- **왜 중요한가**: 지금 코드는 맞다(E1). 나중에 누가 quota 포트 하나를 `inNew`로 바꾸면 잡을 테스트가 없다.
- **고치는 법**: persistence-fileserver PG lane에 "move 중 버전 충돌 → 양쪽 사용량 그대로" 하나. `NamespaceQuota` 또는 fileserver
runbook에 "수정 전 move된 파일은 장부가 틀릴 수 있다, 재계산 SQL"을 한 줄.
- **가이드 심각도·우선순위**: Low · P3 · **증거**: E1
## Declined to judge
- application-core outbox 변경(`OutboxPublishAttempt`, `last_failure_code`, `PARKED`, `longRetries`, 포트 시그니처 변경): diff는 읽었고
눈에 띄는 결함은 없었다. RR-05-xx·06-10~14의 닫힘 판정은 05 영역 리뷰어 몫이다.
- `SubmitDurableOperationUseCase`의 파생 UUIDv7 event id: 클라이언트가 고른 operation id가 남의 파생 id와 같으면 inbox가 두 이벤트를
같은 것으로 본다. 옛 `operation-<sha256>` 방식에도 같은 성질이 있었고 남의 operation id를 알아야 하므로 이번 라운드 결함으로 보지 않았다.
- `PermissionEnforcementGuard`가 못 보는 경우(lazy·prototype bean의 선언 타입이 인터페이스, `registerSingleton`, 람다 wrapper):
일부러 우회해야 생기는 경우라 판정하지 않았다.
- ERROR 디스패치 허용의 새 노출: 컨테이너 오류 페이지가 `/error` 하나이고 컨트롤러가 요청 값을 쓰지 않으며, 다른 체인
(actuator·알림 콜백)은 `/error`와 맞지 않는다. 새 노출은 찾지 못했다. Jetty와 관리 포트 분리 배포는 보지 않았다.
- V003의 `CHECK` 제약은 `NOT VALID` 없이 붙어 테이블 전체를 검사한다. 마이그레이션 주석대로 플랫폼이 아직 어디에도 채택되지 않아
판정하지 않았다.
- 필터가 던진 예외의 오류 디스패치가 span 오류 기록을 남기지 않는 것(예외 처리기는 남긴다): 1차 이전부터 같았다.
## 수렴 판단
**이 라운드가 만든 새 Important가 있다: 2건.**
- RR-01-11: 이번 라운드가 새로 쓴 계약 문장(같은 키 재전송 판정)이 그 코드를 실제로 내는 유일한 저장소(Redis)와 반대다. 원인인
Redis 동작은 이전부터 있었지만, 그 위에 "안전"이라는 약속을 이번에 얹었다.
- RR-01-12: 이번 라운드의 `@SystemInvoked` 규칙 둘이 매뉴얼의 이벤트 소비 경로를 문서 없이 막는다.
둘 다 기본 조립(멱등성 비활성, 소비자 없음)에서는 동작하지 않는 경로라 Critical·High는 아니다. 고치는 범위도 작다(Redis 스크립트 한
분기 + 계약 케이스 하나 + 문서, 그리고 매뉴얼 두 장과 ArchUnit 메시지). 그래도 둘 다 "계약·매뉴얼대로 한 사람이 틀린 결과를 받는다"는
종류라 다음 수정 라운드가 필요하다. Minor 5건은 같은 라운드에 묶을 수 있다.
## Assessment
**Ready to merge? With fixes**
맡은 1차 발견은 중복(RR-07-01=RR-01-02, RR-04-04=RR-01-05)을 빼면 19건이다. 17건이 닫혔고 2건이 부분이며 회귀는 없다. RR-02-03은 결과 불명 계약이 Redis 저장소와 맞지 않아 부분이고(RR-01-11),
`@SystemInvoked` 규칙은 결정대로 들어갔지만 소비자 경로를 막는 새 Important를 만들었다(RR-01-12).
@@ -0,0 +1,246 @@
# 02 persistence·messaging 재리뷰 (2026-11-03, 2차)
경로는 저장소 루트 기준이다. 코드 경로는 `src/`가 앞에 붙는다.
## 범위 — 본 pathspec, 불러온 스킬과 적용한 기준, 실행한 명령과 결과, 못 본 것
### 본 pathspec
- 리뷰 범위: Base `7ef8d0b4` → Head `bbe944bd`(커밋 1개) 중 아래 pathspec. 90파일, +2,924 −454.
```text
src/adapter/outbound/persistence-jpa src/adapter/outbound/persistence-mongo
src/adapter/outbound/persistence-fileserver src/adapter/outbound/persistence-notification
src/messaging src/adapter/outbound/messaging src/adapter/outbound/messaging-kafka
src/adapter/inbound/messaging src/application-notification docs/runbooks docs/messaging docs/jpa
docs/reviews/2026-11-01-maturity-review/06-messaging.md
```
`persistence-mongo`와 `adapter/inbound/messaging`은 이 커밋에 바뀐 파일이 없다.
- 맡은 1차 재리뷰 발견: RR-03-01~10, RR-05-01~10, 06-10~06-14.
- 새 발견 ID는 `RR-02-09`부터다. 1차의 `RR-02-01~08`은 inbound 영역의 발견이라 겹치지 않게 이어 붙였다.
- 읽은 방식: 하위 에이전트 없이 여러 번에 나눠 직접 읽었다.
1. persistence-jpa main 전부(`JpaOutboxStore`, `OutboxEventJpaRepository`, floor entity, `OutboxEventEntity`,
`SpringTransaction`, `PersistenceExceptionTranslator`, V21·V22)와 build.gradle.
2. persistence-jpa 테스트: `PostgreSqlOutboxOrderKeyRunbookIntegrationTest`, `PostgreSqlOutboxDispositionRunbookIntegrationTest`,
`OutboxRunbookSql`, `PostgreSqlOutboxAggregateSequenceIntegrationTest`, `SpringTransactionDeadlineTest`,
`PostgreSqlTransactionIntegrationTest` 추가분, `JpaOutboxStoreTest`, 아키텍처 규칙·fixture.
3. runbook 두 개(`outbox-dead-letter.md`, `outbox-publish-failed.md`) 전문과 나머지 runbook diff.
4. messaging bridge·relay 포트 diff, vendored messaging diff 전부(`KafkaConsumerRegistrar`,
`KafkaQuarantinePublisher`, `KafkaDeadLetterQuarantine`, `FailureDescriptor`, `MessagingShutdownLifecycle`),
`KafkaConsumerRegistrarTest` 추가분.
5. notification·fileserver persistence diff, `ReconciliationJobWorker`(시도 한도가 실제로 걸리는지).
- 판단에 필요해서 pathspec 밖에서 읽은 것(전체 diff 리뷰는 아님): application-core의 `OutboxPublishAttempt`,
`PublishPendingOutboxEventsUseCase`, `OutboxEventStatus`, `OutboxAggregateSequencePort`, `IntegrationEventDraft`,
`IntegrationIdentity`, `SubmitDurableOperationUseCase`, `ReleasedPayloadSchemaContract`, `OutboxAggregateSequenceContract`,
`OverlappingWrites`; composition의 `OutboxSettings`, `OutboxRelayAutoConfiguration`, `OutboxMetrics`;
`DefaultMessagePublisher`의 기한 처리, `KafkaMessagingAutoConfiguration`의 producer 설정, `docs/registries/metrics.yaml`
outbox 항목, `docs/manual/09-outbox-events.md`.
### 불러온 스킬과 적용한 기준
| 스킬 | 적용한 기준 | 무엇을 봤나 |
|---|---|---|
| `superpowers:requesting-code-review` | 리뷰어 템플릿: 요구사항 정합, mock이 아닌 실제 동작 테스트, 마이그레이션 전략·하위 호환, Declined to judge, 심각도 보정, 읽지 않은 코드를 칭찬하지 않기 | 발견마다 "고치는 법"·4절 결정 대조, 테스트가 실제 DB·실제 문서를 쓰는지, V21·V22의 배포 경로 |
| `jpa-patterns` | Flyway 마이그레이션은 additive·재실행 가능, Hibernate는 validate만, 짧은 트랜잭션, 연관관계 규칙(사용자 원칙 "양방향 금지"를 스킬의 `mappedBy` 예시보다 우선) | V21·V22, `insertable/updatable=false` 필드의 실제 SELECT 동작(RR-02-13), `SingleSidedAssociationCondition`의 그래프 판정(RR-02-15), 트랜잭션 마감 분류 |
| `supabase-postgres-best-practices` | `lock-short-transactions`(DDL은 `lock_timeout`으로 잠금 대기를 묶는다), `data-upsert`(`ON CONFLICT`로 경쟁을 DB가 판정), `lock-skip-locked`, `schema-constraints`(제약·상태 값의 재실행 안전성) | V21 `lock_timeout`·무효 인덱스 거부·floor, V22의 잠금 대기(RR-02-09, 실 PG), counter `ON CONFLICT DO NOTHING` 경쟁, PARKED를 DDL 없이 둔 결정의 영향(RR-02-11) |
| `doubt-driven-development` | 주장(CLAIM)을 적고 반증을 시도한다 | 아래 7개 주장. 브리프가 하위 에이전트를 금지해 새 맥락 리뷰어 대신 자기 반증(축소 적용)으로 했다. 비대화 실행이라 교차 모델 검토는 건너뛰었다 |
반증을 시도한 주장과 결과:
1. "V21은 실패해도 다시 돌리면 된다" → 반증 못 함. 한 트랜잭션이라 lock_timeout·중복·무효 인덱스 실패 모두 V20에 남고, floor는 다시 돌 때의 시각으로 다시 기록된다. 해당 lane 테스트 3개가 확인한다.
2. "rolling 배포 중 옛 인스턴스의 벽시계 번호 뒤에 새 번호가 온다" → **일부 반증**. 같은 identity면 맞다. tenant scope가 바뀌는 배포에서는 옛 scope 행을 보지 못해 새 번호가 더 작다(RR-02-10, 실 PG).
3. "counter 첫 생성 경쟁에서 두 쓰기 모두 성공한다" → 반증 못 함. PG(공용 계약의 겹침 테스트)와 H2 PostgreSQL 모드(직접 실험) 둘 다 맞다.
4. "이번 라운드의 마이그레이션은 잠금 대기가 묶여 있다" → **반증**. V21은 5초로 묶었지만 같은 커밋의 V22는 ACCESS EXCLUSIVE를 상한 없이 기다리고, 그동안 outbox 읽기·쓰기가 모두 멈춘다(RR-02-09, 실 PG).
5. "runbook SQL은 lane이 문서에서 읽어 실 PG로 돌린다" → 반증 못 함. 두 lane이 system property로 문서 경로를 받고 문서를 Gradle 입력으로 선언한다. 표지 없는 SQL은 돌지 않는다(Declined 참고).
6. "draft의 UUIDv7 거부는 기존 데이터·재시도를 막지 않는다" → 반증 못 함. draft는 새 이벤트에만 쓰이고, 저장된 행 복원은 draft를 거치지 않는다. durable operation 재시도는 같은 UUIDv7을 다시 만든다.
7. "PARKED는 DDL 없이 안전하다" → **일부 반증**. 새 버전에서는 맞다. 옛 버전(배포 중·롤백 후)은 상태 이름을 몰라 `outbox.pending.size` 게이지 전체가 꺼진다(RR-02-11, 코드).
### 실행한 명령과 결과
메인 작업 트리·index·HEAD는 바꾸지 않았다. Gradle은 돌리지 않았다. 실험은 scratchpad에 마이그레이션 파일을 복사해서 했다.
| 명령 | 실행 직전 부하 | 결과 |
|---|---|---|
| `git diff --stat 7ef8d0b4..bbe944bd -- <pathspec>`, `git diff ...` | — | 90파일. 나눠서 전부 읽었다 |
| `java -cp h2-2.4.240.jar H2Check.java` (scratchpad, `nextSequence`의 세 문장을 그대로 H2 `MODE=PostgreSQL`에서 실행) | — | `first=1 second=2 third=3`, 이미 있는 counter에 생성 문장 → `0`. 두 연결 겹침: 첫째가 생성 후 커밋 보류, 둘째 `next=2`, 최종 `2`. 커밋에 적힌 "H2가 `ON CONFLICT DO NOTHING`을 받는다"를 확인 |
| `flock heavy.lock scratchpad/rr2-02/exp.sh` (postgres:16-alpine, 컨테이너 안 psql로 HEAD의 V1~V21 적용 후 실험) | load 16.65 | rc=0. 첫 시도는 다른 작업이 잠금을 잡고 있어 대기 중 시간 초과(rc=124)였고 재실행했다 |
| └ EXP1: 세션 A가 `outbox_event`를 읽은 트랜잭션을 20초 열어 둠 → 세션 B가 V22 실행 → 세션 C·D가 3초 제한으로 읽기·쓰기 | | `pg_locks`: A `AccessShareLock` granted, V22 `AccessExclusiveLock` 대기. C 읽기 `canceling statement due to statement timeout`(3.09초), D 쓰기 같은 오류(3.20초). **V22는 19.1초 기다린 뒤 rc=0** |
| └ EXP2: floor 뒤 30초에 옛 버전이 `portfolio` scope로 쓴 행(번호 floor+30,000,000) → 새 버전이 같은 aggregate를 `global` scope로 `nextSequence` 문장 실행 | | floor=1793718324464623, 옛 행=1793718354464623, **새 번호=1793718324464624(옛 행보다 작음)** |
### 못 본 것
- Gradle lane을 직접 돌리지 않았다. `postgresqlOutboxDispositionRunbookIntegrationTest`·`postgresqlOutboxOrderKeyRunbookIntegrationTest`·
`postgresqlOutboxAggregateSequenceIntegrationTest`·Kafka relay lane·`KafkaConsumerRegistrarTest`의 통과는 재리뷰 README 7절 게이트 기록을 따랐다.
- persistence-jpa에 새로 들어온 fileserver PG 계약 테스트(`FileserverPostgreSqlStack`, `PostgreSqlFileQuotaLedgerContractTest` 등)는
RR-01-04 몫이라 stack만 읽었다. 계약 케이스 목록은 01 영역 리뷰가 본다.
- 실제 Kafka·SIGTERM·다중 인스턴스 동시 기동은 실행하지 않았다.
- idempotency·redis·grpc·job-timeout runbook diff는 다른 영역 발견의 문서라 이 영역 코드와 모순이 없는지만 봤다.
## Strengths
- **counter 첫 생성 경쟁을 DB가 판정한다.** `JpaOutboxStore.java:125-139`는 `UPDATE` → `INSERT … ON CONFLICT DO NOTHING` → 다시 `UPDATE`다. 두 번째 쓰기는 첫째의 커밋을 기다렸다가 증가만 한다. 공용 계약 `OutboxAggregateSequenceContract.java:71`이 `OverlappingWrites`로 겹침을 운에 맡기지 않고 만들고, PG 테스트가 상속한다. H2 개발 경로도 직접 실험으로 같은 결과였다.
- **번호가 뒤로 가지 않게 두 겹으로 막았다.** 새 counter는 floor와 남은 행 최대값 중 큰 값 다음에서 시작한다(`OutboxEventJpaRepository.java:164`). 기존 counter의 증가도 그 aggregate의 가장 큰 행 아래로 내려가지 않는다(`:140`). 롤백 후 재배포처럼 옛 번호가 다시 섞여도 다음 번호가 그 뒤에 온다.
- **V21의 실패 경로를 실 PG로 고정했다.** 잠금 대기 초과(`PostgreSqlOutboxOrderKeyRunbookIntegrationTest.java:227`), 실패한 CONCURRENTLY가 남긴 무효 인덱스 거부(`:263`), runbook대로 미리 만든 인덱스 재사용(`:298`), counter 선생성(`:185`)이 있다. 각 테스트가 "DB가 V20에 남는다"를 함께 단언한다.
- **runbook SQL이 문서 그대로 실행된다.** `OutboxRunbookSql`이 `<!-- runbook-sql: id -->` 블록을 문서에서 읽고, 두 lane이 문서를 Gradle 입력으로 선언한다(`persistence-jpa/build.gradle:252-260`). 재발행 테스트(`PostgreSqlOutboxDispositionRunbookIntegrationTest.java:63`)는 옛 SQL이면 실패하는 RED가 성립한다. "다음 claim이 그 행을 가져가는가"로 결과를 본다.
- **PARKED가 순서를 지키는지 실제로 본다.** 보류 행 뒤의 행이 claim되지 않음을 단언한다(`PostgreSqlOutboxDispositionRunbookIntegrationTest.java:149`).
- **마감 초과 분류를 자기가 연 트랜잭션으로 좁혔다.** `SpringTransaction.java:201-232`는 이 호출이 시작한 트랜잭션이고 마감이 지났고 다른 분류가 없을 때만 `translateAfterDeadline`을 부른다. 운영 조합(`JpaTransactionManager`)의 실 PG 테스트(`PostgreSqlTransactionIntegrationTest.java:305`)와 "업무 예외는 그대로" 테스트(`SpringTransactionDeadlineTest.java:113`)가 있다.
- **ACL이 원인 코드를 잃지 않는다.** bridge가 platform 코드를 그대로 옮기고, 문법 밖이면 platform의 category 이름으로 바꾼다(`PlatformIntegrationEventPublishAdapter.java:205-233`). 메시지가 아니라 이름만 옮긴다.
- **06-12 검사가 값이 만나는 곳에 있다.** 발행 포트만 아는 최악 시간과 설정이 relay 조립에서 만난다(`OutboxRelayAutoConfiguration.java:76`, `OutboxSettings.java:80`). Kafka `max.block.ms`를 같은 기본 기한으로 묶은 설정과 계산이 맞다.
- **정산 job의 버려진 claim이 시도로 셈된다.** `JdbcReconciliationJobStore.java:74`, 그리고 worker가 provider를 부르기 전에 한도를 본다(`ReconciliationJobWorker.java:111`). 매번 죽는 job도 끝난다.
- **격리 분류가 재시도 경로에서도 유지된다.** 읽을 수 없는 레코드는 첫 격리 쓰기가 실패해도 DESERIALIZATION으로 남는다(`KafkaConsumerRegistrar.java:351,357`, 테스트 `anUndecodableRecordStaysDeserializationWhenItsQuarantineIsRetried`).
## 발견 재확인 표
| ID | 상태 | 근거 |
|---|---|---|
| RR-03-01 | 닫힘 | `JpaOutboxStore.java:132-137`, `OutboxEventJpaRepository.java:169`. PG 겹침 계약 `OutboxAggregateSequenceContract.java:71`. H2 경로는 이 리뷰의 직접 실험으로 확인(E3) |
| RR-03-02 = RR-05-02 | 결정으로 닫힘(잔여 RR-02-10) | V21 floor(`V21:54-56`)·counter 선생성(`:58-65`), 생성 `GREATEST(MAX, floor)`, 증가 `GREATEST(last, MAX)`. PG 테스트 reaper·scope 변경·rolling(`PostgreSqlOutboxAggregateSequenceIntegrationTest.java:108,126`). manual 09에 첫 번호 안내. scope가 바뀌는 배포의 rolling 구간은 막지 못한다(RR-02-10, E3) |
| RR-03-03 | 닫힘 | `SpringTransaction.java:209,220`, `PersistenceExceptionTranslator.java:159-179`. H2 본문 flush·커밋 flush, 실 PG `JpaTransactionManager` 테스트 |
| RR-03-04 | 닫힘(잔여 RR-02-15) | `SingleSidedAssociationCondition.java:84-117` 그래프 판정, fixture `JoinColumnParentEntity`·`JoinColumnChildEntity`, 가이드 `entity-mapping-guide.md:75-91`. 서로 다른 두 FK를 양방향으로 오판한다(Minor) |
| RR-03-05 | 닫힘 | `V21:28-34` `lock_timeout 5s`, `:73-93` 고른 이유·무효 인덱스 거부, runbook §8 Step 0, lane 테스트 3개. 같은 커밋의 V22가 같은 종류의 빈틈을 새로 만들었다(RR-02-09) |
| RR-03-06 | 닫힘 | 두 `positional` helper와 그 테스트 삭제, Javadoc 정정(`CleanupClaimSql.java:17-19`) |
| RR-03-07 | 닫힘 | `WorkerCrashRecoveryContractTest` 이름·`as()`를 단언 범위로 줄이고 한국어 DisplayName, `CleanupClaimSqlTest` 이름을 "문장 텍스트"로 |
| RR-03-08 | 닫힘 | `JdbcReconciliationJobStore.java:74`, 한도 판정 `ReconciliationJobWorker.java:111`, 계약 `ReconciliationJobStoreContract` 추가분 |
| RR-03-09 | 닫힘 | `JpaArchitectureRules.entitiesAreUsedOnlyInsideTheirLeaf`, `JpaProductionArchitectureTest`가 notification·fileserver에 적용, red/green fixture(`OrderEntityReader`) |
| RR-03-10 | 결정으로 닫힘 | `FailureCategory.java` Javadoc 첫 문장 "Not a transaction timeout", 이름 변경은 다음 호환성 깨짐 때로 기록 |
| RR-05-01 | 닫힘 | runbook §4 두 SQL에 `deferred_attempt_count = 0`, `runbook-sql` 표지와 실 PG lane, claim의 WARN이 `ATTEMPT_COUNTERS_INCONSISTENT`로 원인을 말함(`JpaOutboxStore.java:166-177`). CHECK 제약은 결정으로 넣지 않음 |
| RR-05-03 | 결정으로 닫힘(잔여 RR-02-11·12·14) | `OutboxPublishAttempt`, V22 `last_failure_code`, 실패 로그 `error.reason`, `outbox.retry.long.size/age` 게이지·registry·경보, PARKED와 runbook §4.1 SQL 4개(실 PG lane) |
| RR-05-04 | 닫힘 | `IntegrationEventDraft`가 비UUIDv7 event id·causation id 거부, durable operation은 결정적 UUIDv7 파생(`SubmitDurableOperationUseCase.java:177-193`), bridge 주석·README의 "until it does" 제거 |
| RR-05-05 | 닫힘 | 게이지가 자기 스레드(`OutboxMetrics` SmartLifecycle, `outbox-gauges`)에서 poll 주기로 갱신 |
| RR-05-06 | 닫힘 | registry `outcome` 허용 값에 RELEASED, IN_FLIGHT 제거, `OutboxStatusRegistryContractTest`가 outcome label도 비교 |
| RR-05-07 | 닫힘 | `FailureDescriptor` Javadoc, vendored 주석에서 소비자 이름 제거, `src/messaging/CLAUDE.md`에 수정 목록과 버린 대안 |
| RR-05-08 | 닫힘 | `MessagingShutdownLifecycle.java` POLL Javadoc 위치 복구. 같은 모양의 떨어진 Javadoc이 `OutboxEventEntity`에 새로 생겼다(RR-02-13) |
| RR-05-09 | 닫힘 | V21 주석의 클래스명, manual 09 문단, leader election 토큰 삭제, runbook `last_updated` |
| RR-05-10 | 닫힘 | 2026-11-01 README 12절 색인에 06-10~06-14와 정정 문단 |
| 06-10 | 닫힘(다른 방법, 이유 기록) | 출시한 schema 버전 해시 고정(`ReleasedPayloadSchemaContract`, application-core·sample 적용), manual 09 6단계. 버전 간 diff를 하지 않는 이유를 Javadoc에 적었다 |
| 06-11 | 닫힘 | `outbox-inbox.md` 머리말과 두 모델 상태 대응표, `configuration-reference.md` 문장 정정 |
| 06-12 | 닫힘 | `batch-size × longestAttempt ≥ in-flight-timeout`이면 기동 실패. 최악 시간 = 기본 기한 5초 × 2(Kafka `max.block.ms`) |
| 06-13 | 닫힘 | 낡은 문장 정정, `OutboxLeaderElectionToken` 삭제, `composition:outbox-relay`·`messaging-kafka` CLAUDE.md 신설 |
| 06-14 | 닫힘(잔여 RR-02-16) | 읽을 수 없는 레코드 DESERIALIZATION, 예산 소진은 실패의 category 또는 POISON_MESSAGE. 테스트는 SPI 인자를 단언하고 header 쓰기는 테스트가 없다 |
회귀로 판정한 발견은 없다.
## Issues
### Critical (Must Fix)
없음.
### Important (Should Fix)
#### RR-02-09 — V22가 `outbox_event`의 ACCESS EXCLUSIVE 잠금을 상한 없이 기다려, 그동안 outbox 읽기·쓰기가 모두 멈춘다
- **위치**: `src/adapter/outbound/persistence-jpa/src/main/resources/db/migration/postgresql/V22__outbox_event_last_failure_code.sql:20-21`. 비교: 같은 커밋의 `V21__outbox_aggregate_sequence.sql:28-34`, `docs/runbooks/outbox-dead-letter.md:119-122`.
- **무엇이 틀렸나**:
- V22는 `ALTER TABLE outbox_event ADD COLUMN`이다. 이 문장은 ACCESS EXCLUSIVE 잠금을 잡는다.
- 열려 있는 트랜잭션 하나가 `outbox_event`를 읽기만 했어도 V22는 그 트랜잭션이 끝날 때까지 기다린다.
- 기다리는 동안 뒤에 오는 모든 읽기·쓰기가 V22 뒤에 줄을 선다. ACCESS EXCLUSIVE는 읽기와도 충돌한다.
- V22에는 `lock_timeout`이 없다. 같은 커밋이 RR-03-05를 고치며 V21에 "Without a bound, the migration queues behind any open outbox write and every outbox write after it queues behind the migration"이라고 적고 5초 상한을 넣었다. 그 규칙이 바로 다음 마이그레이션에 빠졌다.
- **증거(E3, 실 PG 16)**: 세션 A가 `outbox_event`를 읽은 트랜잭션을 20초 열어 두었다. V22는 19.1초 기다린 뒤 적용됐다. 그동안 `pg_locks`에 V22의 `AccessExclusiveLock`이 granted=false로 있었다. 3초 제한을 건 일반 읽기(`SELECT count(*)`)와 일반 쓰기(`UPDATE`)가 둘 다 `canceling statement due to statement timeout`으로 끝났다.
- **왜 중요한가**:
- 발생 조건: V21 이하 DB를 올리는 첫 배포. Flyway는 기본으로 기동 때 돈다(`persistence-jpa.yml` `flyway.enabled: ${APP_FLYWAY_ENABLED:true}`). 옛 버전이 트래픽을 받는 rolling 배포 중이다.
- 영향: 기다리는 시간만큼 outbox를 쓰는 모든 업무 쓰기, relay claim, 모든 인스턴스의 게이지 갱신이 멈춘다. 멈춘 요청은 Hikari 연결을 쥔 채 기다리므로 outbox와 무관한 요청도 연결을 못 받을 수 있다.
- 기다리는 시간은 그 순간 가장 오래 열린, `outbox_event`를 건드린 트랜잭션의 남은 시간이다. 앱 트랜잭션은 30초 마감이 있다. 운영자가 runbook 조회를 `BEGIN` 안에서 하고 둔 psql 세션, 백업·분석 질의처럼 앱 밖의 세션에는 상한이 없다.
- 1차의 RR-03-05(같은 종류, V21)는 Low였다. 이것을 Medium으로 올린 이유: (1) ACCESS EXCLUSIVE는 SHARE와 달리 읽기까지 막아 relay와 게이지도 선다. (2) 이 라운드가 규칙과 이유를 V21·runbook에 적고 바로 옆 파일에서 어겼다 — 사용자 원칙 "위험은 코드에 드러나야 한다"에 걸리고, 같은 정책의 갈라진 복사본이다.
- **고치는 법**:
1. V22 맨 앞에 `SET LOCAL lock_timeout = '5s';`와 이유 한 줄을 둔다. V22도 아직 어디에도 적용되지 않았으니 V21처럼 직접 고치고 `applied-migrations.sha256`을 갱신한다.
2. `PostgreSqlOutboxOrderKeyRunbookIntegrationTest.v21GivesUpOnALock…`와 같은 테스트를 V22에 둔다. "읽기 트랜잭션이 잡고 있으면 V22는 실패하고 DB는 V21에 남는다".
3. 다음 마이그레이션이 같은 빈틈을 다시 만들지 않게 `docs/jpa/migration-guide.md`에 "운영 중인 테이블에 잠금을 거는 DDL은 `SET LOCAL lock_timeout`을 둔다"를 적는다. 가능하면 마이그레이션 테스트가 `ALTER TABLE`/`CREATE INDEX`(비동시)가 있는 파일에 `lock_timeout`이 있는지 검사한다.
4. runbook §8에 V22 실패 시 동작(롤백, V21에 남음, 새 버전 기동 실패)을 한 줄 더한다.
- **가이드 심각도·우선순위**: Medium · P2. **증거**: E3. **통제**: V22에 대해 M0(V21은 M3).
### Minor (Nice to Have)
#### RR-02-10 — tenant scope가 바뀌는 배포의 rolling 구간에서는 새 번호가 옛 버전이 막 쓴 번호보다 작다
- **위치**: `docs/runbooks/outbox-dead-letter.md:124-131`, `src/application-core/src/main/java/dev/caskeleton/application/outbox/OutboxAggregateSequencePort.java:29-31`, `OutboxEventJpaRepository.java:140-169`.
- **무엇이 틀렸나**:
- floor는 V21이 돈 순간의 값이다. rolling 중 옛 버전은 그 뒤에도 벽시계 번호(초당 10⁶씩 커짐)를 쓴다.
- 새 버전의 `GREATEST(…, MAX(행))`는 같은 identity의 행만 본다.
- 샘플처럼 scope를 바꾸면 옛 버전은 `portfolio`로, 새 버전은 `global`로 쓴다. 새 번호는 floor+1부터라 옛 버전이 방금 쓴 번호보다 작다.
- runbook 124행은 rolling 중 새 번호가 "그 행 뒤에" 온다고 말한다. 포트 계약은 "written under an identity that has since changed" 행보다도 크다고 약속한다. 두 문장이 이 경우에 틀린다.
- runbook 128행의 대응은 "배포 전에 옛 scope 미발행 행 확인"뿐이다. 배포 중에 옛 버전이 새로 쓰는 행은 다루지 않는다.
- **증거(E3)**: 실 PG에서 floor+30초 번호의 `portfolio` 행 뒤에 `global` scope로 `nextSequence` 문장을 돌리자 floor+1이 나왔다.
- **왜 중요한가**: scope를 무시하고 aggregate id로 "마지막 번호보다 작으면 버린다"를 구현한 소비자는 rolling 구간의 새 이벤트를 버린다. 발생은 scope를 바꾸는 배포(현재는 샘플)에 한정된다.
- **고치는 법**: runbook §8에 "scope를 바꾸는 배포는 옛 writer를 모두 멈춘 뒤(혼합 버전 금지) 한다"를 적는다. 포트 Javadoc의 그 구절을 "배포 전에 쓰인 행"으로 좁힌다. 또는 샘플만 옛 scope를 유지한다.
- Low · P3 · E3.
#### RR-02-11 — PARKED 행이 하나라도 있으면 옛 버전 인스턴스의 `outbox.pending.size` 게이지가 통째로 꺼진다
- **위치**: `JpaOutboxStore.java:264`(`OutboxEventStatus.valueOf`), 옛 버전 같은 줄(`7ef8d0b4`·`origin/main`의 `countByStatus`), `V22__outbox_event_last_failure_code.sql:16-19`(PARKED는 DDL 없음).
- **무엇이 틀렸나**: `countByStatus`는 DB의 상태 문자열을 enum `valueOf`로 바꾼다. PARKED를 모르는 옛 버전은 `IllegalArgumentException`을 던지고, 게이지 갱신은 그 상태 하나가 아니라 전체가 실패한다(WARN). rolling 배포 중의 옛 인스턴스와, 운영자가 행을 보류한 뒤 롤백한 버전이 해당한다. DB CHECK가 없으니(결정) 수동 SQL 오타 상태값도 같은 일을 일으킨다.
- **왜 중요한가**: 보류는 장애 중에 하는 일이고, 장애 중 롤백은 흔하다. 그때 `PENDING size growing` 경보의 입력이 사라진다. 결정(DDL 없음·CHECK 없음)을 뒤집자는 것이 아니라 그 결정이 만든 호환성 위험이다.
- **고치는 법**: `countByStatus`가 모르는 상태를 건너뛰거나 `UNKNOWN`으로 모아 세게 한다(새 버전부터라도 이후 상태 추가에 대비). runbook §4.1 Step 2에 "롤백한 버전은 PARKED를 모른다 — 게이지가 꺼지므로 롤백 전에 resume 또는 skip"을 적는다.
- Low · P3 · E1.
#### RR-02-12 — claim이 DEAD로 옮긴 행은 `last_failure_code`가 낡은 값으로 남고 DEAD 경보도 울리지 않는다
- **위치**: `JpaOutboxStore.java:166-189`, `OutboxEventEntity.java:70`(`updatable = false`), `docs/runbooks/outbox-dead-letter.md` §1·§2 Step 1.
- **무엇이 틀렸나**:
- claim 때의 DEAD 전이(`ATTEMPT_COUNTERS_INCONSISTENT`, `UNREADABLE_ROW`)는 entity flush로 쓴다. `lastFailureCode`는 읽기 전용이라 이 경로는 원인 코드를 행에 쓰지 못한다. 행에는 이전 재시도의 코드(예: `KAFKA_AUTHENTICATIONEXCEPTION`)가 그대로 남는다.
- 이 경로는 relay 결과를 거치지 않아 `outbox.publisher.published.total{outcome=DEAD}`가 오르지 않는다. runbook §1의 경보 조건이 이 카운터다. `outbox.pending.size{status=DEAD}`에는 경보가 없다.
- **왜 중요한가**: 운영자가 `SELECT … WHERE status='DEAD'`로 보면 원인을 잘못 읽는다. 경보도 없어 WARN 로그를 찾지 않으면 모른다. 카운터 공백은 1차 RR-05-01이 적은 기존 문제이고, 낡은 원인 코드는 V22가 새로 만든 부분이다.
- **고치는 법**: claim의 DEAD 전이를 조건부 UPDATE로 바꿔 `last_failure_code`에 `error.reason`과 같은 값을 쓴다. `outbox.pending.size{status=DEAD} > 0`을 경보 조건에 더하거나 claim DEAD도 카운터에 센다.
- Low · P3 · E1.
#### RR-02-13 — `OutboxEventEntity`에 주인 없는 Javadoc이 생겼고, 새 필드 주석이 사실과 다르다
- **위치**: `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/outbox/jpa/entity/OutboxEventEntity.java:60-74`.
- **무엇이 틀렸나**:
- `nextAttemptAt`의 Javadoc("Dual-purpose per status …", 60행)이 새 필드의 Javadoc 바로 위로 떨어졌다. `nextAttemptAt`(74행)에는 설명이 없어졌다. 이 커밋이 RR-05-08로 고친 것과 같은 모양이다.
- 새 필드 주석은 append·claim이 "need the column on a database that has not run V22 yet"가 아니라고 말한다. `insertable/updatable = false`는 INSERT·UPDATE에서만 빠진다. Hibernate는 SELECT에 이 열을 넣으므로 claim은 V22 없는 DB에서 실패한다.
- **고치는 법**: 60행 주석을 `nextAttemptAt` 위로 옮긴다. 새 필드 주석의 V22 문장을 "INSERT와 flush는 이 열을 쓰지 않는다"로 줄인다.
- Low · P3 · E1.
#### RR-02-14 — "오래 재시도" 기준 10이 세 곳에 따로 적혀 있고 서로 묶여 있지 않다
- **위치**: `src/composition/outbox-relay/src/main/java/dev/caskeleton/composition/outbox/OutboxMetrics.java:52`, `docs/runbooks/outbox-publish-failed.md:97`, `src/composition/outbox-relay/README.md:118`.
- **무엇이 틀렸나**: 게이지는 상수를, runbook SQL은 리터럴 `10`을 쓴다. runbook은 "같은 기준(`OutboxMetrics.LONG_RETRY_DEFERRED_CLAIMS`)으로 센다"고 말하지만 이를 확인하는 테스트가 없다. runbook lane의 테스트 데이터(12와 1)는 상수가 2~12 사이로 바뀌어도 통과한다.
- **왜 중요한가**: 상수만 바꾸면 경보가 센 행과 runbook 조회가 보여 주는 행이 달라진다. 사용자 원칙의 "갈라진 복사본"이다.
- **고치는 법**: 문서 계약 테스트(`document-contract`)가 runbook 블록의 숫자와 상수를 비교한다. 또는 disposition lane이 경계값(기준-1, 기준)으로 runbook 조회와 `longRetries`를 같이 단언한다.
- Low · P3 · E1.
#### RR-02-15 — 서로 다른 두 FK로 서로를 가리키는 두 엔티티를 양방향 쌍으로 오판한다
- **위치**: `src/adapter/outbound/persistence-jpa/src/testFixtures/java/dev/caskeleton/adapter/outbound/persistence/testkit/arch/SingleSidedAssociationCondition.java:84-117`, `docs/jpa/entity-mapping-guide.md:84-91`.
- **무엇이 틀렸나**: 규칙은 A의 연관이 B를, B의 연관이 A를 가리키면 위반으로 본다. `Order.@OneToOne latestInvoice`와 `Invoice.@ManyToOne order`처럼 FK가 둘인 두 단방향 링크도 걸린다. 메시지는 "two fields map one link"라고 하지만 링크가 둘이다. 같은 클래스 안의 두 링크(manager·mentor)는 예외로 두면서 두 클래스 사이의 같은 모양은 예외가 없다.
- **왜 중요한가**: 금지 쪽으로 틀린 것이라 데이터 위험은 없다. 개발자가 정당한 모델을 바꾸거나 규칙을 끄는 쪽으로 밀린다. 이유를 말하는 메시지가 틀리면 규칙을 믿지 않게 된다.
- **고치는 법**: 같은 join column을 두 쪽이 매핑하는지(`@JoinColumn` 이름 비교, 또는 `@OneToMany`↔`@ManyToOne`·`@ManyToMany`↔`@ManyToMany` 짝)로 좁힌다. 아니면 가이드와 메시지를 "서로 가리키는 연관은 FK가 달라도 금지"로 고쳐 의도를 적는다. 어느 쪽이든 그 모양의 fixture를 둔다.
- Low · P3 · E1.
#### RR-02-16 — 06-14의 header 쓰기는 테스트가 없고, 공개 SPI 시그니처 변경이 깨지는 변경 목록에 없다
- **위치**: `src/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaDeadLetterQuarantine.java:42-52`, `src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaQuarantinePublisher.java:36`, 재리뷰 README 8절.
- **무엇이 틀렸나**:
- 06-14 완료 기준은 "두 경로가 다른 header 값을 남긴다"다. 새 테스트는 registrar가 SPI에 넘기는 category만 본다. category를 `msg.failure-category` header로 쓰는 `KafkaDeadLetterQuarantine`에는 테스트가 없다.
- `KafkaQuarantinePublisher.quarantine`에 인자가 하나 늘었다. 파생 서비스가 이 public SPI를 구현했다면 컴파일이 깨진다. README 8절의 "소유자 확인이 필요한 결정"은 발행·저장소 포트 변경만 적는다.
- **고치는 법**: `KafkaDeadLetterQuarantine` 단위 테스트에서 두 category의 header 바이트를 단언한다. 깨지는 변경 목록에 SPI 변경을 더한다.
- Low · P3 · E1.
## Declined to judge
- `ValidatedIntegrationEvent`는 public record라 draft를 거치지 않고 만들면 UUIDv7 검사를 건너뛴다 — 운영 코드의 생성처는 encoder와 저장 행 복원 둘뿐이고, 테스트의 v4 id는 의도된 것이다.
- 06-12의 최악 시간에 platform admission 대기(최대 남은 기한)가 들어 있지 않다 — relay는 한 번에 하나씩 보내고, 템플릿에는 같은 destination에 직접 발행하는 다른 publisher가 없다.
- 06-12 검사는 `<`라 행마다의 DB 쓰기 시간을 위한 여유가 없다 — 기본값(200초 대 300초)에서는 여유가 크다.
- `translateAfterDeadline`은 원인 사슬 전체를 본다. 마감이 지난 뒤 `DataAccessException`을 cause로 감싼 업무 예외는 `DB_QUERY_CANCELED`로 바뀐다 — 그렇게 감싸는 코드를 찾지 못했다(`PosterRepositoryAdapter`는 cause를 넘기지 않는다).
- 두 aggregate를 서로 다른 순서로 쓰는 두 트랜잭션의 counter 행 교착 — 1400dc15부터 있던 성질이고 이번 수정이 바꾸지 않았다.
- REPEATABLE READ에서 `ON CONFLICT DO NOTHING`은 직렬화 실패를 낸다 — 템플릿은 풀에서 READ COMMITTED를 강제하고 기동 검사가 있다(09-05).
- 옛 인스턴스의 시계가 DB보다 느려 floor 아래 번호를 쓰는 경우 — 옛 벽시계 방식이 보장하지 않던 것이고 runbook이 그렇게 적는다.
- V21의 `IF NOT EXISTS`는 같은 이름의 "다른 열" 유효 유일 인덱스를 받아들인다 — runbook 문장을 그대로 쓰면 생기지 않는다.
- runbook의 표지 없는 SQL(§2 차단 범위 조회, §8 scope 확인, `DROP INDEX CONCURRENTLY`)은 lane이 돌리지 않는다 — runbook 문장이 시험되는 범위를 정확히 적는다. 모든 `runbook-sql` 표지가 어느 테스트에서 쓰이는지 검사하는 장치는 없다.
- runbook lane이 문서 절대 경로를 `systemProperty`로 받아 build cache가 다른 경로에서 재사용되지 않는다 — 기존 lane과 같은 방식이고 정확성 문제는 아니다.
- idempotency runbook의 "action 자신의 트랜잭션 안 효과는 롤백된다" — 호출자가 executor를 트랜잭션으로 감쌀 때 참이다(샘플은 감싼다). inbound 영역 몫이다.
- 06-10이 버전 간 schema diff 대신 출시 버전 불변을 고른 것 — 이유가 Javadoc에 있고, 새 버전은 소비자가 먼저 읽는 절차(application-core README)를 따른다.
## 수렴 판단 — 이 라운드가 만든 새 Important 이상이 있는가
**있다. 1건(RR-02-09).** 이 라운드에서 새로 들어온 V22가 V21에 넣은 잠금 대기 상한을 빠뜨렸다. 실 PG에서 읽기·쓰기가 모두 막히는 것을 확인했다.
고치는 범위는 좁다. V22 한 줄, 같은 모양의 lane 테스트 하나, migration-guide 규칙 한 줄이다. 맡은 1차 발견 25건(RR-03 10건, RR-05 10건, 06-10~14)은 모두 닫혔거나 결정으로 닫혔고 회귀는 없다. 새 Minor 7건 중 6건은 이번 수정이 만든 잔여·문서 불일치이고, 데이터 손상으로 이어지는 것은 없다.
그래서 이 영역은 전체 재리뷰 라운드가 아니라 RR-02-09만 고치고 그 lane을 돌리는 좁은 수정으로 수렴할 수 있다고 본다.
## Assessment
**Ready to merge? With fixes.**
순서 번호·runbook SQL·원인 코드·PARKED·마감 분류는 결정대로 구현됐고 실제 PG·문서 원문으로 검증된다. 다만 같은 커밋의 V22가 outbox 테이블 잠금을 상한 없이 기다려 배포 중 outbox 읽기·쓰기를 멈출 수 있으므로(RR-02-09, E3), V22에 `lock_timeout`과 그 테스트를 넣은 뒤 병합한다.
@@ -0,0 +1,268 @@
# 03 outbound 재리뷰 (2026-11-03)
> 2차 재리뷰. 대상은 재리뷰 수정 커밋 `bbe944bd`(Base `7ef8d0b4`)의 outbound capability 영역이다.
> 경로는 따로 적지 않으면 `src/adapter/outbound/`를 생략한다.
## 범위 — 본 pathspec, 불러온 스킬과 적용한 기준, 실행한 명령과 결과, 못 본 것
### 본 pathspec
- `src/adapter/outbound/{support, identifier, redis-runtime, redis-sdk, cache-redis, httpclient, objectstorage, notification, fileserver}`,
`docs/httpclient`, `docs/notification`, `docs/registries/metrics.yaml`, `infra/redis-sdk`.
`git diff --stat 7ef8d0b4..bbe944bd -- <pathspec>` 기준 78파일, +2,750 −364. diff 전체를 읽었다.
- 재확인한 1차 발견: RR-04-01·02·03·05~11(RR-04-04 제외), RR-07-03, RR-07-04, RR-07-07.
- pathspec 밖 파일은 판정에 필요한 줄만 읽었다: `application-core` `IdempotencyExecutor`·`IdempotencyClaimRequest`,
`composition/idempotency` `IdempotencySettings`·`idempotency.yml`, `persistence-notification` `JpaProviderEventLedger`,
`persistence-jpa` 멱등성 claim SQL·reaper, `app-bootstrap` `SecretSourceValidator`, `docs/runbooks/redis-capability-incident.md`,
`docker-compose.infra.yml`, `.github/workflows/object-storage-qualification.yml`.
- 이 문서의 새 발견 ID는 `RR-03-11`부터다. 1차의 `RR-03-01~10`(그때 03 영역은 persistence)과 겹치지 않게 이어서 매겼다.
01 영역 2차 리뷰어(`RR-01-11~`)와 같은 방식이다.
### 불러온 스킬과 적용한 기준
| 스킬 | 적용한 기준 | 무엇을 봤나 |
| --- | --- | --- |
| `superpowers:requesting-code-review` | 리뷰어 템플릿: 요구사항(1차 "고치는 법"·4절 결정) 대비 정렬, Critical/Important/Minor, 읽은 코드에만 판정 | 출력 양식 전체, 발견 재확인 표 |
| `performance-optimization` | "추정 말고 잰다", 바꾼 뒤 다시 잰다, 측정이 잡음 안이면 문제로 올리지 않는다 | JDK read-idle 타이머의 read당 비용과 JVM 전체 상한(측정해 Minor로), lane 대기 Timer의 borrow당 등록 비용(측정 결과 무시할 수준이라 기각), 캐시 전용 lane의 연결 예산 |
| `observability-and-instrumentation` | 태그는 닫힌 작은 집합, 지표가 on-call 질문에 답하는가, 계측 실패가 결과를 바꾸지 않되 보이는가, runbook이 실제 신호를 가리키는가 | `redis.lane.*` 태그·histogram 버킷, listener 실패 격리·로그 수준, opened 지표의 뜻, 레지스트리·runbook과 코드의 일치 |
| `security-and-hardening` | trust boundary마다 "누가 이 값을 썼나", STRIDE의 R(감사)·D(자원), 공개 비밀값, 서명 범위 | SNS 인증서 4xx를 위조로 보는 근거, `MessageId`가 서명 문자열 안인지, `fixture-` 비밀 거부, ACL fixture 표기 |
### 실행한 명령과 결과
checkout은 바꾸지 않았다. Gradle과 worktree는 쓰지 않았다. 탐침은 `git show bbe944bd:<path>`로 꺼낸 사본을 scratchpad에서
컴파일했고, Redis는 버리는 컨테이너 하나로 돌렸다.
| 명령 | 결과 |
| --- | --- |
| `git diff --stat` / `git diff 7ef8d0b4..bbe944bd -- <pathspec>` | 78파일 |
| `javap java.io.FilterInputStream`, `javap java.io.InputStream`, `javap --module java.net.http 'jdk.internal.net.http.ResponseSubscribers$HttpResponseInputStream'` | `FilterInputStream`은 `transferTo`·`readAllBytes`를 재정의하지 않는다 → 감시되는 `read(byte[],int,int)`를 지난다. JDK 응답 stream은 `skip`을 재정의하지 않는다 → `InputStream.skip`이 `read`를 여러 번 부른다 |
| `javap -c` Spring 7.0.9 `JdkClientHttpRequest`(Gradle cache) | `disallowedHeaders()`가 `jdk.httpclient.allowRestrictedHeaders`를 읽는다 |
| `SkipProbe` — `bbe944bd`의 `ReadIdleInputStream`, 100ms마다 1바이트 주는 stream 30바이트, read-idle 1s | `readAllBytes`: 30바이트 3,018ms 성공. **`skip(30)`: 1,001ms에 `SocketTimeoutException`**(공백은 모두 100ms) |
| `Bench` — `guarded()`와 같은 `completeOnTimeout` 걸기 + `cancel` 반복 | 1스레드 3.9~4.6µs/회. 8·32스레드에서 JVM 전체 0.35~0.51M회/초에서 멈춘다. 측정 당시 load average 14~22(22코어) |
| `TimerBench` — Micrometer 1.16.7 `SimpleMeterRegistry` | borrow마다 `Timer.builder(..).register(..).record(..)` 152~241ns, 미리 만든 Timer `record` 64ns. Redis 왕복(100µs 이상)에 비해 무시할 수준 → 발견으로 올리지 않음 |
| `docker run redis:7.4`(로컬 이미지 `b6b6e3dc0c09`, 고정 digest와 같은 id) + `bbe944bd`의 CLAIM Lua를 `redis-cli EVAL` | owner A claim(lease 3000ms, replay TTL 1000ms) → `ACQUIRED`, `PTTL 996`. 1.3s 뒤 `EXISTS 0`. owner B claim → **`ACQUIRED`**. A의 lease는 1.7s 남아 있었다 |
### 못 본 것
- Gradle 테스트와 게이트는 다시 돌리지 않았다(재리뷰 README 7절을 읽기만 했다).
- Redis 컨테이너 lane·topology lane, MinIO·Toxiproxy lane은 돌리지 않았다. 캐시 전용 배포의 ACL probe가 실제 Redis의
거절 메시지(`NOPERM …`)를 맞게 분류하는지는 합성 메시지 테스트로만 확인됐다.
- 실제 AWS SNS 인증서 호스트가 없는 인증서에 주는 status, VPC endpoint 경유 동작은 확인하지 못했다.
- JDK HTTP/2 스트리밍, TLS 소켓을 JVM 공용 delay 스레드에서 닫을 때의 지연은 보지 않았다.
- PostgreSQL 멱등성 저장소(claim SQL, reaper)는 RR-03-11의 범위를 가늠하려고 읽기만 했다.
- `app-bootstrap` `SecretSourceValidator`는 RR-07-04 판정에 필요한 diff만 읽었다.
## Strengths
- breaker가 deadline 출처를 구분한다. `Deadline.Source`(`httpclient/.../resilience/Deadline.java:28`)를 계산기가 정하고, 같으면
profile 쪽으로 기운다(`DeadlineCalculator.java:24-26`). 호출자 deadline으로 끝난 시도는 `releasePermission()`으로 permit만
돌려준다(`AttemptResiliencePipeline.java:136-137`). 회귀 테스트가 두 transport × 두 출처를 실제 서버로 본다
(`CircuitBreakerStatusAccountingTest.java:178,221`).
- JDK 스트리밍이 setup 전용 scope를 따로 연다(`AttemptDeadline.openStreamSetup`, `BlockingStreamingGateway.java:86`). 그래서
setup 상한과 본문 gap 상한이 섞이지 않는다. 테스트는 헤더 timeout·전체 예산보다 긴 본문과 read-idle보다 긴 공백을 두
transport에서 모두 본다(`StreamingBodyLifetimeTest`).
- 캐시 전용 lane의 결정이 코드에 남아 있다. 버린 대안 둘과 이유가 `CacheScriptLane.java:20-24`와 README
「Why the cache has its own script lane」(`cache-redis/README.md:192`)에 있다. lane 분리를 SCRIPT 1개를 잡은 상태로
증명하는 테스트가 있다(`RedisCacheRegionAdapterTest.java:442`).
- lane 지표가 닫힌 이름만 태그로 쓴다. 거절·폐기 counter는 기동 때 0으로 미리 만든다(`RedisLaneMetrics.java:89-108`).
listener는 lock 밖에서 부르고, 실패해도 borrow를 깨지 않는다(`RedisRuntimeOwner.java:350-356`, 테스트
`RedisLaneMetricsTest.java:277`).
- renew의 TTL 연장이 같은 Lua 안에 있어 원자적이다(`IdempotencyScripts.java:186-189`). 공유 계약에 실제 시간이 흐르는 경우가
생겼고(`IdempotencyStoreContract.java:373`), 시계를 못 움직이는 저장소는 통과 대신 abort로 보고된다.
- ACL probe가 "거절"을 허용 목록으로 판정한다(`RedisSemanticScriptAclProbe.java:124-145`). 끊김·`LOADING`·`BUSY`는 기동을
막지 않고, 읽은 값이 틀린 경우는 막는다. 둘 다 테스트가 있다.
- `MessageId`는 서명 검증을 통과한 envelope에서만 읽는다(`SesCallbackAdapter.java:126-129`). ledger가 두 유일 인덱스를 모두
먼저 조회하고 `ON CONFLICT DO NOTHING`을 대상 없이 쓴다(`JpaProviderEventLedger.java:237`). 그래서 event id가 새로 생겨도
제약 위반 예외가 아니라 중복으로 답한다.
- SNS 인증서 4xx 중 408·429를 장애 쪽에 남겼다(`NotificationCallbackProviderConfig.java:93`). 검증기는
`IllegalArgumentException`을 서명 실패로 바꾼다(`SnsSignatureVerifier.java:89`).
- 기동 rule이 앞당긴 bean을 이름으로 보고한다(`StartupRuleRunner.java:66-81`). 정적·무인자 `RequiredProductionSecrets`만
예외로 두고, 그 이유가 Javadoc에 있다.
- 파일 소유자 규칙이 한 벌이 됐다(`RoleBasedFileAccessPolicy.java:78`의 `subject.owns`). 운영 policy가 fake와 같은 계약을
상속한다(`RoleBasedFileAccessPolicyContractTest`).
## 발견 재확인 표
| ID | 상태 | 근거 |
| --- | --- | --- |
| RR-04-01 | 닫힘 | `BlockingAttemptExecutor.java:156` `deadline.setByCaller() && scope.expired()` → `AttemptResiliencePipeline.java:136-137` `releasePermission()`. total-call로 끊긴 시도는 계속 센다(결정). 두 transport 회귀 테스트. 남은 문서 공백은 RR-03-16 |
| RR-04-02 | 닫힘(4절 결정대로) | 캐시 조건부 쓰기가 `CacheScriptLane.CACHE_SCRIPT`(기본 4)로(`RedisCacheRegionAdapter.java:138`, `RedisCacheConfig.java:74-79`). 기여 조건이 캐시 region bean과 같다(`:37`, `:74`). lane별 대기·거절·재연결 지표(`RedisLaneMetrics`). 문서 표류는 RR-03-17 |
| RR-04-03 | 닫힘 | `DeadlineAwareJdkRequestFactory.java:49` → `JdkStreamingClientHttpRequest`, 본문은 `ReadIdleInputStream`, 실패는 `ClassifiedBodyInputStream`. 두 transport 테스트. 새 Minor 넷: RR-03-12(skip), RR-03-13(read당 타이머 비용), RR-03-14(unchecked 예외), RR-03-15(헤더 목록 사본) |
| RR-04-05 | 닫힘 | `cache-redis/build.gradle:89` `requires`에 `LiveRedisIdempotencyStoreContractTest`. CLAUDE.md 목록도 맞췄다. 결과적으로 lane은 `integrationCheck`에서만 돈다(mainCheck 중복 제거). README 목록 누락은 RR-03-18 |
| RR-04-06 | 닫힘 | `package-info.java`, `identifier/CLAUDE.md` Allowed 4개, README가 `build.gradle`과 `modules.json`(`domain-core, application-core, shared-contract`)에 맞는다 |
| RR-04-07 | 닫힘 | `RedisSemanticScriptAclProbe.java:124-145` 허용 목록 판정, `LOADING`·끊김·`BUSY` 테스트. 실제 서버 메시지로는 미확인(못 본 것) |
| RR-04-08 | **부분** | renew는 고쳤다(`IdempotencyScripts.java:186-189`, 계약 `:373`). claim·takeover는 여전히 key TTL을 replay TTL로 둔다(`:44,77`). replay TTL < processing lease면 lease 중에 key가 사라진다 → RR-03-11(E3) |
| RR-04-09 | 닫힘 | `StartupRuleRunner.java:66-81,103-131`(RR-06-01과 같은 수정), 테스트 3건(non-static 규칙, 비정적 secrets, 정적 secrets 허용) |
| RR-04-10 | 닫힘 | 순서 키가 `redis-runtime/.../module-defaults/redis-runtime.yml`로 옮겨졌고 cache-redis에서는 빠졌다(중복 키면 기동 실패라 한 곳뿐). `RedisRuntimeHealthStatusOrderTest` |
| RR-04-11 | 닫힘 | `JavaMailSenderSmtpDispatch.java:120` `400 <= code < 600`, 테스트 |
| RR-07-03 | 닫힘 | 4xx(408·429 제외) → `IllegalArgumentException` → 서명 실패 → 거절·감사. 5xx·408·429·IO → 503. `SnsCertificateFetchTest`. 4xx가 SNS 자신의 답이라는 가정은 Declined to judge |
| RR-07-04 | 닫힘 | 파일 이름 `lane-fixture-accounts.acl`, `acl/README.md`가 "배포 파일 아님"과 계정 구성을 실제대로 적는다, compose 4개·`docker-compose.infra.yml` 주석, `SecretSourceValidator`가 prod에서 `fixture-` 값 거부. 프로필 범위는 Declined to judge |
| RR-07-07 | 닫힘 | SES 이벤트의 `provider_event_id` = SNS `MessageId`(`SesEventNormalizer.normalize(payload, id)`), Javadoc이 실제 인덱스를 적는다. fingerprint는 event id를 입력으로 쓰지 않아 배포 경계의 재전송도 중복으로 잡힌다(`AesGcmCallbackPayloadProtection.java:112-124`) |
회귀로 판정한 발견은 없다.
## Issues
### Critical (Must Fix)
없음.
### Important (Should Fix)
#### RR-03-11 · replay TTL이 processing lease보다 짧으면 Redis 멱등성 key가 lease 도중 사라져, 같은 키의 두 번째 요청이 작업을 다시 돌린다 (RR-04-08 부분)
- **위치**: `cache-redis/.../idempotency/IdempotencyScripts.java:44`(claim `PEXPIRE ARGV[7]` = replay TTL), `:77`(takeover도 같음),
`:186-189`(renew만 늘림). 설정: `src/composition/idempotency/.../IdempotencySettings.java:57,65`(lease와 replay TTL을 따로만 검사),
`src/application-core/.../IdempotencyClaimRequest.java:23-24`(관계 검사 없음), `idempotency.yml`의 `replay-ttl: ${APP_IDEMPOTENCY_TTL:24h}`.
- **무엇이 틀렸나**:
- 이번 수정은 "key TTL이 lease보다 먼저 끝나면 실행 중에 key가 사라져 같은 부작용이 다시 돈다"를 renew 경로에서만 막았다.
수정 Javadoc 자신이 원인을 "Claim sets it to the replay TTL, which may be shorter than a lease"라고 적는다.
- claim은 여전히 key TTL을 replay TTL로 둔다. replay TTL이 processing lease보다 짧은 설정은 거부되지 않는다.
`processing-lease`는 `IN_FLIGHT_RETRY_AFTER`보다 길어야 한다는 검사만 있고, `replay-ttl`은 72h 상한만 있다.
- 그 설정에서 action이 replay TTL보다 오래 걸리면 key가 lease 도중 사라진다. 다음 claim은 `ACQUIRED`를 받고 executor는
작업을 처음부터 돌린다(`IdempotencyExecutor.java:132-133`). 첫 실행은 아직 진행 중이다.
- **왜 중요한가**:
- 멱등성이 막으려는 바로 그 피해다. 외부 호출·메일 같은 트랜잭션 밖 효과가 두 번 일어난다. 두 실행이 동시에 돈다.
- 발생 조건: `provider=redis` + `APP_IDEMPOTENCY_TTL` < `APP_IDEMPOTENCY_PROCESSING_LEASE`(기본 30s) + action이 replay TTL보다
오래 걸림 + 그동안 같은 키 재전송. 변수 이름이 `..._TTL`이고 env 레지스트리 설명도 "완료 응답을 재생하는 시간"뿐이라,
"짧은 재생 창"을 원해 10s를 넣는 설정은 그럴듯하다. 두 값의 관계는 어디에도 적혀 있지 않다. 사용자 원칙의 "숨은 위험"이다.
- 탐지가 어렵다. 두 번째 요청은 정상 `ACQUIRED` 경로라 로그·지표에 이상이 없다.
- RR-01-11(만료된 `EXECUTING`을 `RECOVERY_REQUIRED`로)을 고쳐도 이 경로는 남는다. 기록이 lease가 끝나기 전에, 또는 renew 뒤
lease와 같은 순간에 사라지므로 "만료된 EXECUTING"을 볼 기록이 없다. renew가 TTL을 lease와 정확히 같게 두기 때문이다(`:187-188`).
- PostgreSQL 저장소도 claim에서 `expires_at = now + replay TTL`을 쓰고 reaper가 상태와 lease를 보지 않고 지운다
(`IdempotencyClaimGateway.java:44`, `IdempotencyRecordJpaRepository.java:22-24`, E1). reaper 주기만큼 늦을 뿐 같은 원인으로 보인다.
- **고치는 법**:
1. 설정에서 막는다(두 저장소를 한 번에): `IdempotencySettings`가 `replay-ttl < processing-lease`이면 기동 실패. env 레지스트리와
`idempotency.yml` 주석에 관계를 적는다. 고른 방법·버린 대안을 Javadoc에 남긴다.
2. 저장소도 스스로 지킨다: Redis claim·takeover·renew가 key TTL을 `max(replay TTL, lease + 여유)`로 둔다. 여유는 RR-01-11의
만료 처리가 기록을 볼 수 있을 만큼(예: replay TTL)이다. "lease와 정확히 같은 TTL"은 피한다.
3. 계약에 시간 경우 하나: "replay TTL보다 긴 lease로 claim하면 lease 안의 다른 claim은 `InProgress`". Live Redis·PG lane이 실제로 돈다.
- **가이드 심각도·우선순위**: Medium · P2. 피해는 High급(업무 중복 실행)이지만 비기본 설정에서만 도달한다. 기본 조립은 멱등성 비활성.
- **증거**: E3 — `redis:7.4` 컨테이너에서 `bbe944bd`의 CLAIM Lua를 직접 실행. lease 3000ms·replay TTL 1000ms claim → 1.3s 뒤
key 없음 → 다른 owner claim `ACQUIRED`(A의 lease 1.7s 남음). 설정 경로(`IdempotencySettings`→executor→claim)는 E1.
이번 라운드가 만든 결함은 아니다. 1차 RR-04-08이 renew만 짚었고, 같은 원인의 claim 경로가 남았다.
### Minor (Nice to Have)
#### RR-03-12 · JDK `ReadIdleInputStream.skip`이 gap이 아니라 skip 전체 시간을 read-idle로 묶는다
- **위치**: `httpclient/.../jdk/ReadIdleInputStream.java:49-51`(`skip`을 `guarded` 한 번으로), `:53-57`.
- **무엇**: JDK 응답 stream은 `skip`을 재정의하지 않는다. 그래서 `InputStream.skip`이 안에서 `read`를 여러 번 부른다. 타이머는
그 묶음 전체에 한 번 걸린다. 데이터가 꾸준히 와도 큰 `skip`이 read-idle보다 오래 걸리면 거짓 `SocketTimeoutException`이 나고
stream이 닫힌다. 문서는 "본문은 gap마다 read-idle로만 묶인다"고 적는다. `skipNBytes`도 `skip`을 쓴다.
- **고치는 법**: `skip`을 직접 구현한다. 작은 버퍼로 `read`를 반복하고, 각 `read`만 `guarded`로 감싼다. 위 탐침을 단위 테스트로 둔다.
- **심각도·우선순위**: Low · P3(JDK transport + 스트리밍 + skip 사용에서만). **증거**: E3 — `SkipProbe`: 공백 100ms, read-idle 1s에서
`readAllBytes`는 30바이트 성공, `skip(30)`은 1,001ms에 `SocketTimeoutException`.
#### RR-03-13 · JDK 스트리밍의 read마다 JVM 공용 delay 스케줄러에 타이머를 걸고 지운다
- **위치**: `httpclient/.../jdk/ReadIdleInputStream.java:53-69`.
- **무엇**: `read` 한 번마다 `CompletableFuture.completeOnTimeout`으로 JVM에 하나뿐인 delay 스케줄러 큐에 작업을 넣고 지운다.
지울 때 큐의 맨 앞이 바뀌면 그 스레드를 깨운다. 측정: 1스레드 read당 3.9~4.6µs, 여러 스레드에서는 JVM 전체 약 0.5M회/초에서
멈춘다. 같은 큐를 `AttemptDeadline`과 Spring JDK 요청 timeout도 쓴다. 16KB read라면 영향이 작다(1GB에 약 0.2초 CPU). 1바이트씩
읽는 소비자(`DataInputStream` 등)는 JVM 전체 약 0.5MB/초가 상한이 된다. Apache는 소켓 timeout이라 이 비용이 없다.
- **고치는 법**: stream마다 "마지막 진행 시각"(volatile `nanoTime`)만 read에서 갱신한다. 타이머는 read-idle 주기로 한 번 걸고,
깨어났을 때 진행이 없으면 닫고 있으면 다시 건다. 전용 `ScheduledExecutorService`를 transport가 하나 갖는 방법도 있다. 고른 방법을
주석에 남기고, 위 측정을 전후로 다시 잰다.
- **심각도·우선순위**: Low · P3(기본 transport는 Apache). **증거**: E3 — `Bench`(load average 14~22에서 측정, 수치는 크기 정도로만 읽는다).
#### RR-03-14 · 스트리밍 본문 `InputStream.read`가 이제 unchecked `HttpClientException`을 던지는데, 공개 타입에 적혀 있지 않다
- **위치**: `httpclient/.../restclient/ClassifiedBodyInputStream.java:34,43,52,61`, `api/result/BlockingStreamingResponse.java`(`body()` Javadoc),
`api/error/HttpClientException.java:12`(`extends RuntimeException`).
- **무엇**: 이전에는 본문 실패가 `IOException`이었다. 이제는 `HttpResponseTimeoutException`·`HttpResponseTruncatedException`
(RuntimeException)이다. 두 transport 모두다(Apache도 바뀌었다). `catch (IOException)`으로 부분 파일을 지우거나 재시도하는 소비자
코드는 이 예외를 놓친다. `InputStream` 계약상 `read`가 던지는 것은 `IOException`이다. README와 configuration-reference에는
적혔지만 소비자가 보는 `BlockingStreamingResponse.body()`에는 없다.
- **고치는 법**: (a) `IOException`을 상속한 본문 예외(예: `HttpBodyReadException`)를 두고 분류된 `HttpClientException`을 cause·accessor로
싣는다. 또는 (b) 지금 방식을 유지하되 `body()` Javadoc과 README에 "read는 unchecked `HttpClientException`을 던진다,
`IOException` catch로는 잡히지 않는다"를 적는다. 고른 쪽과 이유를 남긴다.
- **심각도·우선순위**: Low · P3(템플릿 안 운영 소비자 없음, 파생 서비스의 기존 catch가 영향). **증거**: E1.
#### RR-03-15 · JDK 스트리밍 요청이 Spring의 금지 헤더 목록을 사본으로 갖고, 원본과 갈라졌다
- **위치**: `httpclient/.../jdk/JdkStreamingClientHttpRequest.java:44,89,123-127`.
- **무엇**: 사본은 다섯 이름을 고정으로 둔다. Spring 7.0.9 `JdkClientHttpRequest.disallowedHeaders()`는
`jdk.httpclient.allowRestrictedHeaders` 시스템 속성을 읽어 허용된 이름을 뺀다. 그 속성을 켠 배포에서 같은 profile의 일반 호출은
`Host` 등을 보내고 스트리밍 호출은 조용히 버린다. 사용자 원칙의 "갈라진 중복 복사본"이다.
- **고치는 법**: 같은 시스템 속성을 읽는다. 또는 사본을 둔 이유와 원본 위치를 주석에 적고, 두 목록이 같은지 보는 테스트를 둔다.
- **심각도·우선순위**: Low · P3. **증거**: E1(`javap -c`로 Spring 쪽 확인).
#### RR-03-16 · 호출자 예산이 stage timeout보다 짧은 profile에서는 죽은 상대를 breaker가 보지 못한다 — 문서에 없다
- **위치**: `httpclient/.../restclient/BlockingAttemptExecutor.java:156`, `resilience/AttemptResiliencePipeline.java:26-29`(Javadoc),
`docs/httpclient/configuration-reference.md` "Two deadlines" 표.
- **무엇**:
- 코드는 "호출자 deadline이 profile보다 이르고, 실패 시점에 scope가 만료됐으면" 기록하지 않는다.
- Javadoc은 "상대가 profile 한도 안에서 답하던 중"인 시도라고 적는다. 코드는 그 조건을 보지 않는다.
- 결과: 모든 호출자가 connect·response-header timeout(기본 2s)보다 짧은 예산을 넘기면, 블랙홀이 된 상대(패킷 버림)의 시도는 하나도
breaker에 기록되지 않는다. circuit이 열리지 않아 모든 호출이 자기 예산을 끝까지 기다린다.
- connect 거절 같은 즉시 실패는 계속 센다.
- **고치는 법**: 이 맹점을 configuration-reference 표와 Javadoc에 적는다("호출자 예산이 stage timeout보다 짧으면 hang하는 상대는
breaker가 못 본다. 그런 profile은 stage timeout을 호출자 예산보다 짧게 둔다"). Javadoc의 조건 문장을 코드에 맞춘다.
- **심각도·우선순위**: Low · P3(결정의 부작용 기록). **증거**: E1.
#### RR-03-17 · Redis 관측 문서가 지금 나오는 신호와 어긋난다
- **위치**: `docs/runbooks/redis-capability-incident.md:50,60-63,64-67,74`, `cache-redis/README.md:218`,
`docs/registries/metrics.yaml`의 `redis.lane.acquire.wait.seconds` 행, `redis-runtime/.../RedisRuntimeOwner.java:354`.
- **무엇**:
- runbook의 Detection 절은 "`redis.capability.*`는 내보내지 않는다"로 고쳤다. 그런데 같은 문서의 다른 줄은 그 지표가 있는 것처럼
남았다. "semantic operation 계측은 … 결과를 기록한다", "앞선 success 표본과 이 실패를 두 operation으로 합산하지 않는다",
"이 meter와 단일-process lifecycle test는…", "reconnect, cache source-load, session repository error 지표의 변화를 함께 본다"
(cache source-load·session 지표를 내는 코드가 없다). 레지스트리에서 뺀 `redis.capability.*`의 이름을 직접 부르는 곳은 없다
(`git grep` 결과 README 「아직 내보내지 않는 지표」와 runbook 해명 줄뿐).
- README는 `opened`를 "warm-up 뒤에는 모두 재연결"이라고 적는다. routed lease(Cluster `TRANSACTION`)는 borrow마다 새로 열고
pool에 돌려주지 않으며 `discarded`로도 세지 않는다(`RedisRuntimeOwner.java:265-267`, 반환 시 `discarded == null`). 그 lane에서는
정상 동작이 재연결 급증처럼 보인다.
- 레지스트리는 대기 timer를 `percentiles: [0.5,0.9,0.95,0.99]`, `histogram_buckets: slo_driven`으로 적는다. 코드는 SLO 경계 없이
`publishPercentileHistogram()`만 쓴다(`RedisLaneMetrics.java:117`). p99 경보는 histogram으로 계산되니 동작은 맞고, 표기만 다르다.
- listener 실패는 DEBUG로만 남는다(`RedisRuntimeOwner.java:354`). 결과를 바꾸지 않는 것은 맞다. 다만 registry 충돌 등으로
지표가 통째로 사라져도 운영 로그에는 흔적이 없다.
- **고치는 법**: runbook의 남은 줄을 "설계(미구현)"로 옮기거나 지운다. README에 "routed lease는 매번 연다"를 적거나 routed 열기를
다른 reason으로 센다. 레지스트리 행을 코드에 맞춘다. listener 실패는 처음 한 번 WARN으로 남긴다.
- **심각도·우선순위**: Low · P3. **증거**: E1.
#### RR-03-18 · lane의 자리·구성을 바꾼 뒤 옛 문장이 남은 문서
- **위치**: `objectstorage/README.md:108`("(in `mainCheck`)"), `.github/workflows/object-storage-qualification.yml:4`
("they run in its `mainCheck` on main and here"), `cache-redis/README.md:337-338`. 원인 변경: `objectstorage/build.gradle:158-162`
(mainCheck 의존 삭제), `cache-redis/build.gradle:89`(멱등성 계약 추가).
- **무엇**:
- build는 MinIO lane을 `integrationCheck`에만 둔다. 두 문서는 leaf `mainCheck`가 돌린다고 적는다. cache-redis의 같은 변경은
README·CLAUDE.md를 함께 고쳤다(`cache-redis/README.md:339-340`).
- cache-redis README는 컨테이너 lane이 "cache-region and lease port contracts"를 돈다고 적는다. RR-04-05로 멱등성 계약이
더해졌는데 README에는 없다. CLAUDE.md(`:131-139`)는 맞다.
- 같은 종류의 사소한 것: `SesEventNormalizer.java:58-59` 주석이 "is keyed / by / the active"로 잘못 줄바꿈됐다.
- **고치는 법**: MinIO 두 문장을 "`integrationCheck`(main push·nightly)와 이 workflow"로 고친다. cache-redis README의 계약 목록에
멱등성 계약을 넣는다.
- **심각도·우선순위**: Low · P3. **증거**: E1.
## Declined to judge
- SNS 인증서 URL의 4xx를 "SNS가 없다고 답했다 = 위조"로 보는 가정. 호스트 검사를 통과해도 TLS를 가로채는 egress 장비나
private DNS를 켠 SNS VPC endpoint가 답할 수 있다. 그 경로에서 정상 콜백이 400으로 영구 거절되고(SNS는 4xx에 재전송을 멈춘다)
감사 로그가 위조로 찬다. 명시 proxy의 CONNECT 실패는 JDK가 `IOException`으로 주므로 503 쪽이다. AWS가 없는 인증서·VPC endpoint
경유에 어떤 status를 주는지 확인하지 못해 판단을 미룬다. 확인할 것: 운영과 같은 네트워크에서 존재하지 않는 `.pem`을 받아 보기.
- `SecretSourceValidator`의 `fixture-` 거부가 `isProduction()`(prod 프로필)에서만 돈다. 프로필 없음·`staging`은 그대로 기동한다.
기존 sentinel 검사와 같은 범위이고, RR-07-02가 문제 삼은 "거부 목록이 prod 하나" 구조와 닮았다. pathspec 밖(app-bootstrap)이라 07 영역에 넘긴다.
- PostgreSQL 멱등성 reaper가 `expires_at`만 보고 진행 중 기록도 지우는 것(RR-03-11 근거로 읽음). persistence 영역의 판단이 필요하다.
- 캐시 전용 배포에서 advanced 계정 비밀번호가 틀리면(`WRONGPASS`) 연결 단계 실패라 "장애"로 WARN 후 기동한다. 이번 diff 전부터의
동작이다. 설정 오류로 볼지는 판단하지 않았다.
- `CACHE_SCRIPT`가 pod당 advanced 계정 연결을 최대 4개 늘린다(SCRIPT 8 + 4). Redis `maxclients`와 ACL 계정별 연결 예산에 주는 영향은 판단하지 않았다.
- read-idle 타이머가 만료되면 JDK 공용 delay 스레드에서 `in.close()`를 부른다. JDK 응답 stream의 close는 구독 취소라 막히지 않는다고
보지만, HTTP/2·TLS에서 재 보지 않았다(1차 Declined와 같은 질문).
- lane 대기 Timer를 borrow마다 builder로 등록하는 비용. 측정 결과 152~241ns로 Redis 왕복 대비 무시할 수준이라 발견으로 올리지 않았다.
## 수렴 판단
- **이 라운드가 만든 새 Important 이상: 없음.** 수정 diff가 새로 만든 결함은 모두 Minor다(RR-03-12~18). 그중 실행으로 확인한 것은
RR-03-12(E3)와 RR-03-13(E3)이고, 둘 다 기본이 아닌 JDK transport의 스트리밍에만 닿는다.
- **남은 Important 1건은 덜 닫힌 1차 발견이다.** RR-03-11은 RR-04-08과 같은 원인의 claim 경로다. 이번 라운드가 만든 것이 아니라
1차가 renew만 짚어 남은 것이다. 고치는 비용은 설정 검사 몇 줄이다. RR-01-11의 수정과 TTL 규칙을 함께 정해야 한다.
- 따라서 이 영역만 보면 수정 라운드는 수렴했다. 다음 라운드가 필요하다면 RR-03-11(및 RR-01-11과의 묶음) 때문이다.
## Assessment
**Ready to merge: With fixes.** 1차 발견 13건 중 12건이 코드와 실제 서버 테스트로 닫혔고, 회귀와 이 라운드가 만든 새 Important는 없다.
다만 RR-04-08의 claim 경로가 남아 있어(RR-03-11, E3) replay TTL을 processing lease보다 짧게 둔 Redis 배포에서 멱등 작업이 두 번 돈다.
@@ -0,0 +1,306 @@
# 04 bootstrap·build·sample 재리뷰 (2026-11-03)
리뷰 대상: Base `7ef8d0b4` → Head `bbe944bd`(재리뷰 수정 커밋), 영역 번호 04(slug `bootstrap-build-sample`).
1차 재리뷰 발견 중 이 영역이 맡은 것: RR-06-01~12, RR-07-02, RR-07-05, RR-04-09. 경로는 저장소 루트 기준이다.
## 범위 — 본 pathspec, 불러온 스킬과 적용한 기준, 실행한 명령과 결과, 못 본 것
### 본 pathspec
```text
src/app-bootstrap src/sample-portfolio src/build-logic src/build.gradle src/settings.gradle src/gradle
src/gradle.properties src/optional-platforms src/config src/.env.example .github docker-compose*.yml
infra/postgres infra/fileserver AGENTS.md CLAUDE.md docs/registries docs/capability-status.md docs/testing
```
`git diff --stat` 기준 83파일 +2,159 −413. 하위 에이전트 없이 여러 번에 나눠 직접 읽었다.
- 전부 읽은 것: build-logic main diff 전체(`StrictLaneStagesPlugin`, `WorkflowGradleInvocations`,
`StrictTestLanePlugin`, `ConfigContractPlugin`, `ConfigurationMetadataClasspath`, `EnvContractVerifier`,
`VerifyEnvKeysTask`)와 그 테스트 diff, workflow diff 3개, `src/optional-platforms/build.gradle`,
`src/config/spotbugs/exclude.xml` diff, app-bootstrap main·test·architectureTest diff, sample main diff 전체와
`application.yml` 전문, sample 보안 테스트 diff, AGENTS.md·CLAUDE.md·`docs/capability-status.md`·
`src/build-logic/README.md`·`src/app-bootstrap/README.md`·`CLAUDE.md` diff, `.env.example` diff.
- 표본으로 읽은 것: `docs/registries/env-keys.yaml`·`error-codes.yaml`·`secrets-classification.yaml` diff,
`metrics.yaml` diff(키 이름만), `docs/testing/TESTING_STRATEGY.md` diff, `OutboxStatusRegistryContractTest` diff.
- pathspec 밖에서 확인용으로 읽은 것: `src/adapter/outbound/support/.../startup/StartupRuleRunner.java`·
`StartupRule.java`·`RequiredProductionSecrets.java`와 그 테스트 diff(RR-06-01 수정 본체),
`src/Dockerfile.sample`, `src/adapter/inbound/web/.../error/EnvelopeErrorController.java`,
`src/adapter/outbound/objectstorage/build.gradle`·`ObjectStorageAutoConfiguration.java`,
`src/grpc/grpc-testkit/build.gradle`·`GrpcPerformanceLaneTest.java`, `docs/runbooks/job-timeout.md` diff,
`scripts/run-compose-runtime-smoke.sh`, `infra/redis-sdk/acl/*.acl`.
### 불러온 스킬과 적용한 기준
| 스킬 | 적용한 기준 | 무엇을 봤나 |
| --- | --- | --- |
| `superpowers:requesting-code-review` | 리뷰어 템플릿(Strengths → severity별 Issues → Declined → Assessment), "spec이 말하지 않은 동작은 합리적인 사용자의 기대로 판단", 읽기 전용, 의심 결함은 별도 worktree에서 확인 | 수정이 1차 발견의 "고치는 법"을 채웠는지, 수정이 만든 새 결함. 의심 5건을 worktree 실험으로 확인 |
| `ci-cd-and-automation` | "No gate can be skipped", Red flag "CI failures ignored or silenced", 캐시 최적화가 결과를 바꾸면 안 된다 | `verifyStrictLaneStages`의 workflow 해석(`-x`·`continue-on-error`·`if:`·`-p`)이 실제 Gradle 계획과 같은지, lane 정책 입력이 캐시 재사용을 불필요하게 깨는지, optional 빌드 단계 연결 |
| `security-and-hardening` | 비밀값은 환경에서, 기본값은 닫힘, 오류 메시지는 내부를 드러내지 않음, CSRF는 ambient 자격이 있을 때 의미가 있다 | 데모 계정 허용 목록·기본 프로필 제거, prod `fixture-` 거부 범위, SpotBugs CSRF 제외 축소와 `EnvelopeErrorController` 제외의 근거 |
### 실행한 명령과 결과
worktree `scratchpad/rr2-04`(HEAD `bbe944bd`)에서 Gradle을 `flock heavy.lock`으로 감싸 실행했다. 시작 부하 6~40.
probe 파일은 worktree에만 만들었고, 끝난 뒤 `git worktree remove --force`로 지웠다. 메인 체크아웃은 건드리지 않았다.
| # | 명령 | 결과 |
| --- | --- | --- |
| 1 | build-logic에 reader probe 추가 → `./gradlew -p build-logic test --tests '*RR2WorkflowProbeTest*' --tests '*StrictLaneStagesFunctionalTest.rr2*'` | rc=0. `on: workflow_dispatch`만 있는 workflow의 `:integrationCheck`는 실행으로 셈(`reason=null`). `working-directory: src/optional-platforms` + `../gradlew ci`는 main 빌드 `ci` 실행으로 셈. job `if: ${{ !cancelled() && !failure() }}`는 안 셈. `with: run:`(action 입력)은 실행으로 셈. TestKit: `:integrationCheck -x databaseL --dry-run` 계획에서 Gradle은 `:leaf:databaseLane`을 뺐는데, 같은 줄을 가진 workflow로 `verifyStrictLaneStages`는 **"every strict lane is in an executed stage"로 통과** |
| 2 | support·app-bootstrap·sample에 probe 추가 → `./gradlew :adapter:outbound:support:test --tests '*RR2ProbeTest*' :app-bootstrap:test --tests '*RR2FixturePrefixProbeTest*' :sample-portfolio:test --tests '*RR2DemoProfile*' --continue` | rc=1(의도한 실패 14건). 아래 2-a~2-e |
| 2-a | support: JavaBean `@ConfigurationProperties("probe2")`가 `RequiredProductionSecrets`를 구현, static 규칙이 `ObjectProvider<RequiredProductionSecrets>.orderedStream()`으로 읽음, `probe2.name=bound` | runner 없음: `name=bound`. runner 있음: **기동 성공, `name=null`**, 경고 없음 |
| 2-b | support: `@Import`한 `StartupRule` 클래스에 `@Value("${probe3.mode}")` 필드, `probe3.mode=strict` | **기동 성공, 규칙이 본 값 `null`, 기동 뒤 bean 필드도 `null`** |
| 2-c | support: raw `FactoryBean` 컴포넌트(생성자 의존 1개) + 같은 static 규칙 | 기동 성공(오탐 없음). 규칙 없는 대조군도 성공 |
| 2-d | app-bootstrap: prod 프로필, `HOSTNAME=fixture-api-6d5f7c9b8-x2k4q`(시스템 환경 소스), `spring.application.name=fixture-service`, `app.messaging.topic=fixture-updates` | 세 이름 모두 위반: `'fixture-' repository fixture password (public, infra/redis-sdk/acl) is configured for HOSTNAME` 등 |
| 2-e | sample: `SampleDemoSecurityConfigTest`를 복사해 `app.object-storage.enabled=false`만 빼고 프로필을 `demo`·`test`·`local`로 | `local` 7건 통과. `demo`·`test` 각 7건 **전부 실패**: `Error creating bean with name 'objectStorageCapability' ... object-storage binding is incomplete or invalid` |
| 3 | `./gradlew :sample-portfolio:qualityCheck` | rc=0 (PR sample job이 새로 부르는 태스크) |
| 4 | `./gradlew -p optional-platforms :verifyStrictLaneStages --dry-run`, `./gradlew :verifyStrictLaneStages --dry-run` | 둘 다 rc=0 |
| 4-b | worktree의 `integration-main.yml` optional performance 줄에 `-x grpcPerformanceT` 추가 → 같은 optional 검사, 그리고 `./gradlew -p optional-platforms performanceCheck -x grpcPerformanceT --dry-run` | 검사는 **통과**. 실제 계획에는 `:grpc:grpc-testkit:grpcPerformanceTest`가 없고 `performanceTestLaneCheck`만 있다 — RR-06-03이 닫은 lane이 다시 어디서도 돌지 않는데 검사가 모른다 |
돌리지 않은 것: `ci`·`mainCheck`·`integrationCheck` 전체(README 7절 오케스트레이터 실행을 근거로 삼았다), `docker build`·
`docker run`(Dockerfile.sample은 정적 확인), compose 실제 기동, GitHub Actions 실행.
### 못 본 것
- 실제 CI runner에서의 workflow 실행, `gradle/actions/setup-gradle`의 캐시 복원 범위.
- `docs/registries/metrics.yaml`의 새 `redis.lane.*` 행과 코드가 내보내는 이름의 대조(03·04 outbound 영역 소관).
- `env-keys.yaml`에 새로 넣은 행 중 `APP_CACHE_REDIS_MAXIMUM_SCRIPT_CONNECTIONS` 외 다른 영역 행의 의미.
- architectureTest의 새 ArchUnit 규칙 2개의 적용 범위(01 core 영역 소관). 실패 fixture가 있다는 것까지만 봤다.
## Strengths
- **기동 규칙이 앞당긴 bean을 이제 실제로 잡는다.** `src/adapter/outbound/support/src/main/java/dev/caskeleton/adapter/outbound/support/startup/StartupRuleRunner.java:64-83,100-131`.
1차 probe와 같은 모양(설정 bean을 받는 non-static `@Bean` 규칙)이 `probeRule`·`probe-dev.caskeleton`을 대며 기동 실패한다
(`StartupRuleRunnerTest.java` 새 테스트 3건). 같은 수정 때문에 기존 테스트 설정 2곳이 static으로 바뀌었다
(`ErrorDetailExposureSafetyValidatorTest.java:71`, `RuntimeNumericBoundsValidatorTest.java:81`). 검사가 장식이 아니라는 증거다.
- **정상 구성에서 오탐하지 않는다.** 실험 2-c에서 생성자 의존이 있는 raw `FactoryBean`이 있어도 규칙이 `RequiredProductionSecrets`를
읽는 동안 다른 singleton이 생기지 않았다. 템플릿의 모든 조립(app-bootstrap·sample·qualification)은 README 7절 게이트에서 기동했다.
- **lane 정책이 캐시 입력이 됐고, 바뀌지 않은 lane의 캐시는 그대로 쓴다.** `StrictTestLanePlugin.java:227-240`.
정책만 바꾼 두 번째 실행이 "forbids skipped tests"로 실패하는 TestKit(`StrictTestLaneConventionTest.java:549-583`)과,
정책을 그대로 둔 hermetic lane이 여전히 `FROM_CACHE`인 기존 TestKit(`:505-547`)이 둘 다 HEAD에서 통과한다. 입력은 모두
상수 값(Boolean·String·List)이라 머신 간 캐시 키가 갈라지지 않는다.
- **optional 빌드가 자기 lane 도달성을 스스로 검사한다.** `src/optional-platforms/build.gradle:1-7,55-83`,
`StrictLaneStagesExtension.java:19-25`. 실험 4에서 `grpcPerformanceTest`가 `-p optional-platforms performanceCheck`로 덮인다.
`performanceCheck`·`releaseCheck` 집계로 바뀌어 lane을 더해도 workflow를 고칠 필요가 없다(`release.yml:135`).
- **`-x` 경로 지정·`continue-on-error`·비상태 `if:`를 Gradle 계획 위에서 판정한다.** `StrictLaneStagesPlugin.java:120-183`.
전체 경로 `-x`는 lane과 그 아래 의존을 계획에서 잘라 낸다. TestKit 4건(`StrictLaneStagesFunctionalTest.java:189-316`).
- **env 계약이 leaf 이름을 모른다.** `ConfigContractPlugin.java:21-66`, `VerifyEnvKeysTask.java:50-118`,
`src/app-bootstrap/build.gradle:483-488`. metadata classpath가 비면 실패한다(`VerifyEnvKeysTask.java:67-71`).
- **CSRF 제외가 클래스 이름으로 좁혀졌고 sample이 처음으로 분석된다.** `src/config/spotbugs/exclude.xml:19-50`,
`.github/workflows/ci-quality-gates.yml:73`. 실험 3에서 `:sample-portfolio:qualityCheck`가 통과한다.
- **데모 계정 허용 목록이 섞인 프로필도 거부한다.** `SampleDemoAccountsProductionGuard.java:51-65`.
`local,prod`·`test,staging`·프로필 없음이 거부되는 테스트가 있다(`SampleDemoAccountsProductionGuardTest.java:70-94`).
- **Poster 포트의 충돌 규칙이 코드로 묶였다.** domain 예외(`domain/poster/PosterTitleAlreadyExistsException.java`)와
`PosterRepositoryContract`를 in-memory fake와 실 PostgreSQL adapter(`integrationTest` source set)가 함께 상속한다.
- **종료 예산의 web drain을 compose가 실제로 주는 값에서 읽는다.** `DeveloperExperienceContractTest.java:412-418,632-639`.
runbook도 49초 기준으로 고쳤다(`docs/runbooks/job-timeout.md:51-54`).
## 발견 재확인 표
상태: 닫힘 / 부분 / 회귀 / 결정으로 닫힘. `>`는 다른 영역 소관.
| ID | 상태 | 근거 |
| --- | --- | --- |
| RR-06-01 | 부분 | 1차 probe 모양(non-static `@Bean` 규칙이 설정 bean을 받음)은 기동 실패로 잡힌다(`StartupRuleRunner.java:100-131`). 그러나 새로 생긴 singleton이 `StartupRule`·`RequiredProductionSecrets` 타입이면 묻지 않고 허용한다(`:108-109`). 그 bean 자신이 BPP 없이 만들어지는 경우 — 필드 주입 컴포넌트 규칙, JavaBean 설정 클래스가 비밀 목록을 겸함 — 는 여전히 조용히 바인딩되지 않는다(실험 2-a·2-b) → RR2-04-03 |
| RR-06-02 | 닫힘 | `StrictTestLanePlugin.java:227-240` 정책 5개를 입력으로. TestKit `:549-583`. release job `--rerun-tasks`는 결정으로 넣지 않음(README 6절 r4-f) |
| RR-06-03 | 닫힘(잔여 RR2-04-04) | `src/optional-platforms/build.gradle:1-7,55-83`, `ci-quality-gates.yml:83-87`, `integration-main.yml:206-211`. 실험 4 통과. 다만 축약 `-x`로 같은 lane을 빼도 검사는 모른다(실험 4-b) |
| RR-06-04 | 부분 → RR2-04-04 | 지목한 세 가지(`-x` 전체 경로, `continue-on-error`, 비상태 `if:`)는 닫힘(`WorkflowGradleInvocations.java:236-307`). 축약 `-x`, `on:` 트리거, `working-directory`는 여전히 안 본다(실험 1·4-b) |
| RR-06-05 | 닫힘 | sample PR job에 `:sample-portfolio:qualityCheck`(`ci-quality-gates.yml:73`), CSRF Match FQCN화(`exclude.xml:19-50`). 실험 3 통과 |
| RR-06-06 | 닫힘 | 죽은 블록 3개 삭제(`sample application.yml`), `SampleRuntimeDefaultsContractTest.java:83-176`이 `app.*` 최상위 묶음마다 sample classpath의 읽는 코드를 요구. 하위 키까지는 보지 않는다(고치는 법이 요구한 수준) |
| RR-06-07 | 부분 → RR2-04-05 | lane json·smoke 래퍼의 `APP_*` 키는 이제 등록·읽힘 검사 대상(`ConfigContractPlugin.java:45-62`, `EnvContractVerifier.java:44,216-224`). 1차 발견을 낳은 `CASKELETON_GRPC_ENABLED` 같은 비-`APP_` 키는 여전히 아무 검사도 받지 않는다 |
| RR-06-08 | 닫힘 | `DeveloperExperienceContractTest.java:412-418`, `docs/runbooks/job-timeout.md:51-54` |
| RR-06-09 | 닫힘 | `src/adapter/outbound/objectstorage/build.gradle:158-162` mainCheck 의존 삭제 |
| RR-06-10 | 닫힘 | `ConfigContractPlugin.java`에서 redis-runtime 경로·`dependsOn` 삭제, `ConfigurationMetadataClasspath`, `app-bootstrap/build.gradle:483-488` |
| RR-06-11 | 닫힘(새 drift RR2-04-06) | 지목한 7곳 모두 고침(build-logic README:64, grpc-testkit 주석, CLAUDE.md·AGENTS.md mainCheck, runtime.yml·observability.yml, SampleManagementSecurityConfig:24-29, capability-status idempotency 행, sample build.gradle). 이번 수정이 같은 종류의 새 drift를 만들었다 |
| RR-06-12 | 닫힘 | domain 예외 + `PosterRepositoryContract`(fake·PG adapter 상속), `PosterRepository.java:12-23`, `WorkLogRepository.java:11-17`이 두 갈래의 이유를 적음 |
| RR-07-02 | 결정으로 닫힘(새 결함 RR2-04-02) | 허용 목록 `local`·`test`·`demo`(`SampleDemoAccountsProductionGuard.java:30,51-65`), yml 기본 프로필 삭제(`application.yml:29-32`), bootRun만 `local`을 넘김(`sample-portfolio/build.gradle:248-254`). 결정대로 구현됐다. 그런데 허용한 `test`·`demo`로는 sample이 기동하지 않고, 이미지 실행 문서가 깨졌다 |
| RR-07-05 | 닫힘 | `exclude.xml:19-50`. sample 데모 체인은 별도 Match와 이유 |
| RR-04-09 | 닫힘 | non-static `@Bean` 규칙은 그 설정 클래스를 만들므로 이름을 대며 실패한다(`StartupRuleRunnerTest` 새 테스트 1·2). 남은 경로는 RR2-04-03 |
회귀로 판정한 발견은 없다.
## Issues
### Critical (Must Fix)
없음.
### Important (Should Fix)
#### RR2-04-01 · prod의 `fixture-` 거부가 모든 설정값을 보아서, 비밀이 아닌 정당한 값으로 운영 기동이 막힌다 (이번 라운드가 만든 결함)
- **위치**: `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/runtime/SecretSourceValidator.java:48,51-54,113-140`.
문서: `src/app-bootstrap/README.md:132-136`, `docs/registries/secrets-classification.yaml:13-15`.
- **무엇이 틀렸나**: prod 프로필이면 모든 property source의 모든 값을 훑어 `fixture-`로 시작하면 기동을 거부한다.
OS 환경 변수도 포함한다. `fixture-`는 이 저장소의 lane 비밀번호 접두사이기 전에 평범한 영어 단어다.
거부 대상은 비밀번호가 아니라 "그 접두사로 시작하는 모든 문자열"이다.
- **증거 (E3)**: 실험 2-d. prod에서 `HOSTNAME=fixture-api-6d5f7c9b8-x2k4q`, `spring.application.name=fixture-service`,
`app.messaging.topic=fixture-updates`가 모두 위반이 됐다. 메시지는 셋 다 "repository fixture password (public,
infra/redis-sdk/acl)"라고 말한다.
- **왜 중요한가**:
- 발생 조건: Kubernetes는 pod 이름을 `HOSTNAME`으로 넣는다. Deployment 이름이 `fixture-`로 시작하면(경기 일정
"fixture" 도메인, 테스트 데이터 서비스 등) 모든 pod가 이 값을 가진다. 앱 이름·topic·bucket·key prefix도 같다.
- 발견 시점: 검사는 prod 프로필에서만 돈다. dev·staging은 통과하고 첫 운영 배포가 crash loop가 된다.
- 우회 수단: 없다. 이름을 바꾸거나 이 클래스를 고쳐야 한다. README는 "설정값이면 이름을 바꾼다"고 적지만,
운영자가 `HOSTNAME`을 설정값으로 떠올릴 이유가 없다.
- 막으려던 것은 공개된 lane 비밀번호 7개다(`infra/redis-sdk/acl/lane-fixture-accounts.acl`의 `fixture-admin`·
`fixture-advanced`·`fixture-application`·`fixture-bootstrap`·`fixture-raw`·`fixture-replication`·`fixture-sentinel`).
정확한 값 목록으로도 같은 사고를 막을 수 있어서, 넓은 접두사 일치가 얻는 것은 없다.
- **고치는 법**: 결정(prod에서 lane fixture 비밀번호 거부)은 그대로 두고 범위만 좁힌다.
1. 접두사가 아니라 저장소가 공개한 값 집합과 정확히 같을 때만 거부한다. 값 목록은 ACL fixture 파일에서 한 번만
정의하고, 그 파일과 목록이 같은지 테스트로 묶는다.
2. 또는 검사 대상을 비밀값으로 좁힌다: 레지스트리에서 `secret`으로 분류된 키와, `secret://…@environment/<VAR>`
참조가 가리키는 변수.
3. 메시지는 "lane fixture 비밀번호와 같은 값"이라고 말하고, `HOSTNAME`·`spring.application.name` 같은 값이 통과하는
테스트를 둔다.
- **가이드 심각도·우선순위**: Medium · P2. 운영에서만 드러나는 기동 실패이고, 원인이 된 값이 정당하다.
- **증거 등급**: E3(실험 2-d), prod 전용 경로는 E1(`SecretSourceValidator.java:98`).
#### RR2-04-02 · 허용 목록의 `test`·`demo`로는 sample이 기동하지 않고, sample 이미지의 실행 문서가 깨졌다 (이번 라운드가 만든 결함)
- **위치**: `src/sample-portfolio/src/main/resources/application.yml:215-227`(object storage를 끄는 것은 `local` 문서뿐),
`SampleDemoAccountsProductionGuard.java:30,44`(remedy가 "local (or test or demo)"를 권함),
`src/sample-portfolio/README.md:54-57`(jar·이미지는 "`local`(또는 `test`·`demo`)"), `src/Dockerfile.sample:7-9,14-17`
(pathspec 밖), `src/sample-portfolio/src/systemTest/resources/application-test.yml:176-177`(테스트만 object storage를 끔).
- **무엇이 틀렸나**:
1. object storage 모듈은 classpath에 있으면 켜진다. sample main 설정은 `local` 프로필에서만 끈다.
`test`·`demo`로 jar나 이미지를 띄우면 목적지 없는 object storage가 기동을 막는다. `demo` 프로필 문서는 아예 없다.
2. `Dockerfile.sample`의 실행 예시는 프로필을 주지 않는다. 이제 그 명령은 종료 코드 71로 끝난다. 머리말의
"필요한 외부 의존은 PostgreSQL 하나"도 틀렸다.
3. 게이트가 이를 못 본 이유: sample의 모든 Spring 테스트는 `local`이거나, `test` 프로필에 테스트 리소스
`application-test.yml`이 object storage를 끈다. 실제 jar의 `test`·`demo`를 띄우는 테스트는 없다.
- **증거 (E3)**: 실험 2-e. 같은 slice를 `demo`·`test`로 띄우면 14건 모두 `objectStorageCapability ... object-storage binding
is incomplete or invalid`로 실패했고, `local`은 7건 통과했다. 이번 diff의 `SampleDemoSecurityConfigTest.java:57-59`도
같은 이유로 `app.object-storage.enabled=false`를 손으로 더했다(주석이 그렇게 말한다).
- **왜 중요한가**: sample은 도입자가 가장 먼저 띄우고 복제하는 실행 경로다(가이드 35.3: 템플릿에서는 개발자 경험의
실행 경로가 도입 차단 항목이 될 수 있다). 결정이 `demo` 프로필을 새로 허용했지만 그 프로필로는 아무것도 뜨지
않는다. 이미지 사용자는 문서대로 하면 거부되고, 거부 메시지가 권하는 두 번째·세 번째 선택지에서 다시
프로필과 무관해 보이는 object storage 오류를 만난다. 보안 결함은 아니다(실패는 닫힌 쪽이다).
- **고치는 법**:
1. sample의 lean demo 기본값(object storage off 등)을 `local` 문서가 아니라 기본 문서에 두거나, 세 데모 프로필
모두에 같은 문서를 둔다(`on-profile: local | test | demo`).
2. `Dockerfile.sample` 실행 예시에 `-e SPRING_PROFILES_ACTIVE=demo`(또는 `local`)를 넣고, 머리말을 고친다.
이미지에 기본 프로필을 굽지 않는 것은 결정대로 둔다.
3. 회귀 방지: 허용 목록의 각 프로필로 `SamplePortfolioApplication`을 테스트 리소스 없이 띄우는 테스트 하나
(`DEMO_PROFILES`를 파라미터로).
- **가이드 심각도·우선순위**: Medium · P2.
- **증거 등급**: E3(실험 2-e), Dockerfile 부분은 E1.
#### RR2-04-03 · 기동 규칙 검사가 `StartupRule`·`RequiredProductionSecrets` 타입이면 묻지 않고 통과시켜, RR-06-01과 같은 "조용히 바인딩 안 됨"이 남는다 (RR-06-01 부분)
- **위치**: `src/adapter/outbound/support/src/main/java/dev/caskeleton/adapter/outbound/support/startup/StartupRuleRunner.java:104-110`
(타입 면제), `:44-49`(Javadoc "the two kinds that are declared static and argument-free"), `src/app-bootstrap/CLAUDE.md:88-92`,
prod 전용 경로 `SecretSourceValidator.java:98,142-147`·`SecretSourceConfig.java:31-35`.
- **무엇이 틀렸나**: 검사는 "규칙을 만들거나 돌리는 동안 새로 생긴 singleton"을 본다. 그 singleton이 규칙이나 비밀 목록
자신이면 무조건 허용한다. Javadoc은 이 두 종류가 static·인자 없음으로 선언된다고 말하지만, 그 사실은 검사하지 않는다.
그래서 bean 자신이 BPP 없이 만들어지는 모양은 빠져나간다.
- JavaBean `@ConfigurationProperties` 클래스가 `RequiredProductionSecrets`를 겸하면 바인딩되지 않는다.
- `@Component` 규칙의 `@Value` 필드·`@Autowired` 필드는 주입되지 않는다(생성자 `@Value`는 된다).
둘 다 다른 singleton을 만들지 않으므로 검사가 볼 것이 없다.
- **증거 (E3)**: 실험 2-a. runner가 없으면 `name=bound`, runner가 있으면 기동 성공·`name=null`·경고 없음.
실험 2-b. 규칙이 본 값과 기동 뒤 bean의 필드가 모두 `null`, 기동 성공.
- **왜 중요한가**:
- `RequiredProductionSecrets`는 `SecretSourceValidator`가 prod에서만 꺼낸다(`SecretSourceValidator.java:98`). 그래서 2-a
모양은 dev·test·staging에서는 정상 바인딩되고 prod에서만 기본값으로 돈다. 그 설정 bean을 쓰는 런타임 코드도
prod에서만 기본값을 본다.
- 2-b 모양은 Spring에서 가장 흔한 컴포넌트 작성법이다. 규칙이 항상 `null`을 보면 그 안전 검사가 조용히 꺼진다.
- 1차 발견의 핵심은 "개발자가 기억해야 하는 숨은 제약"이었다. 수정 뒤 문서(`StartupRuleRunner` Javadoc, app-bootstrap
CLAUDE.md)는 "runner가 막아 준다"고 읽히지만, 이 두 모양은 막지 못한다. 지금 템플릿의 규칙·비밀 목록 선언은
모두 static `@Bean`이라 터지는 곳은 없다.
- **고치는 법**: 1차 리뷰의 첫째 안을 면제 대상에만 적용한다. 새로 생긴 singleton이 규칙·비밀 목록 타입이면
`beanFactory.getBeanDefinition(name)`이 `AnnotatedBeanDefinition`이고 `getFactoryMethodMetadata()`가 static이며 매개변수가
`Environment`·`ListableBeanFactory`·`ObjectProvider`뿐일 때만 허용한다. 그 밖(컴포넌트 스캔·`@Import`·
`@EnableConfigurationProperties`로 등록된 클래스)은 이름을 대며 실패시킨다. 실험 2-a·2-b를 RED 테스트로 쓴다.
- **가이드 심각도·우선순위**: Medium · P2(1차 RR-06-01과 같은 근거·같은 등급).
- **증거 등급**: E3(실험 2-a·2-b), prod 전용 경로는 E1.
### Minor (Nice to Have)
#### RR2-04-04 · `verifyStrictLaneStages`의 workflow 해석에 남은 틈 — 축약 `-x`, `on:` 트리거, `working-directory`
- **위치**: `src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocations.java:102-110`
(`excludes`: 전체 이름만 비교), `:197-230`(트리거·`working-directory`를 읽지 않음), `:236-278`.
- **무엇이 틀렸나**:
1. Gradle은 `-x`에 축약 이름(camel-case)을 받는다. reader는 이름이 정확히 같을 때만 제외로 본다.
2. `if: github.event_name == 'workflow_dispatch'`는 "실행 아님"으로 거부하면서, 같은 뜻의 `on: workflow_dispatch`만 있는
workflow는 실행으로 센다.
3. `working-directory: src/optional-platforms` + `../gradlew ci`를 main 빌드의 `ci` 실행으로 센다. optional 빌드에는 안 센다.
4. `uses:` 단계의 `with: run:` 입력을 실행으로 센다(이전부터).
- **증거 (E3)**: 실험 1과 4-b. 실제 `integration-main.yml`에 `-x grpcPerformanceT`를 넣으면 Gradle 계획에서
`grpcPerformanceTest`가 빠지는데 optional 검사는 통과한다. 지금 workflow에는 이런 줄이 없다.
- **왜 중요한가**: 검사는 "lane이 실제로 돈다"를 증명한다고 문서(AGENTS.md:79-86, CLAUDE.md:40-44)에 적혀 있다.
축약 `-x`는 사람이 터미널에서 흔히 쓰는 형태라 workflow로 그대로 옮겨질 수 있다. 그러면 RR-06-03이 막은 상태가
조용히 돌아온다.
- **고치는 법**: `-x` 판정을 문자열 비교가 아니라 Gradle에 맡긴다. 각 실행 명령의 `-x` 값을 `--dry-run` 계획을
다시 만들 때 `StartParameter.excludedTaskNames`로 넘기거나, 계획의 태스크 이름에 Gradle과 같은 camel-case 일치를
적용한다. 트리거가 `workflow_dispatch`뿐인 workflow는 `if:`와 같은 이유로 세지 않는다. `working-directory`가
있으면 그 경로를 `-p`처럼 읽는다. 각각 reader 단위 테스트 1건.
- **심각도·우선순위·증거**: Low · P3 · E3.
#### RR2-04-05 · lane 활성화 키 검사가 `APP_` 키만 봐서, RR-06-07을 낳은 비-`APP_` 키는 여전히 아무도 안 본다 (RR-06-07 부분)
- **위치**: `src/build-logic/src/main/java/dev/caskeleton/buildlogic/config/EnvContractVerifier.java:44`(`JSON_KEY`는
`"APP_…"`만), `:225-233`(레지스트리 행에 `property:`가 있으면 "읽힘"), `ConfigContractPlugin.java:45-49`(주석),
`EnvContractVerifierTest.java:236-253`.
- **무엇이 틀렸나**: 1차 발견의 실제 사례는 `CASKELETON_GRPC_ENABLED`, 즉 `APP_`가 아닌 아무도 읽지 않는 키였다.
새 검사는 그 키를 패턴에서부터 건너뛴다. 새 테스트 fixture에 이 키가 들어 있지만 단언하지 않는다. plugin 주석은
"이 태스크가 아니라 손으로 찾았다"를 들어 이제는 잡힌다고 읽힌다. 또 레지스트리 행에 `property:`만 있으면 그 property가
실제로 있는지(`app.redis.` 밖) 보지 않고 "읽힘"으로 친다.
- **왜 중요한가**: compose lane에 오타 난 비-`APP_` 스위치를 넣어도 lane은 다른 이유로 녹색일 수 있다. 1차 결함과 같은 모양이다.
- **고치는 법**: lane json의 `activationEnv` 키 중 `APP_`·`SPRING_`·`MANAGEMENT_`·`SERVER_`·`REDIS_LANE_`(문서화된 비밀번호
변수) 같은 허용 접두사 밖의 키를 거부한다. fixture의 `CASKELETON_GRPC_ENABLED`를 실패로 단언한다. `property:` 행은
qualification classpath metadata에서 그 이름을 찾는다.
- **심각도·우선순위·증거**: Low · P3 · E1(테스트 본문으로 확인).
#### RR2-04-06 · 이번 수정이 새로 만든 문서·주석 불일치
- **무엇이 틀렸나** (모두 E1):
- `docs/capability-status.md:42` gRPC transport 행: "`ca-skeleton.grpc.server.enabled` (no `APP_*` row)". 이번 diff가
`APP_GRPC_SERVER_ENABLED`(property `app.grpc.server.enabled`, `GrpcServerSettings.java:27`)를 등록했다. object storage 행만 고쳤다.
- `src/.env.example:297-299`: "Explicit offs for two more capabilities"라고 쓰고 값은 `true`다.
- `src/config/spotbugs/exclude.xml:474-478`: "Only DispatcherType.ERROR reaches it ... meets the normal chain (and its CSRF
rules)". 인증된 직접 요청도 이 메서드에 닿고(`EnvelopeErrorController.java:35-37`가 그렇게 말한다), JWT 체인은 CSRF를 끈다.
제외가 성립하는 진짜 이유는 "상태를 바꾸지 않고 고정된 실패 envelope만 쓴다"이다. 결론은 맞고 근거 문장이 틀렸다.
- `src/Dockerfile.sample:7-9,14-17`: RR2-04-02 참조.
- `StartupRuleRunner.java:44-49`, `src/app-bootstrap/CLAUDE.md:88-92`: RR2-04-03 참조.
- **고치는 법**: 위 줄을 코드에 맞춘다. exclude 이유는 "부작용 없음, 직접 요청은 인증 체인을 거친다"로 바꾼다.
- **심각도·우선순위·증거**: Low · P3 · E1.
## Declined to judge
- 데모 허용 목록에 `test`가 있는 것 — 회사마다 외부에 열린 공유 "test" 환경이 있을 수 있다. 4절 결정이라 뒤집지 않는다.
- release job이 `--rerun-tasks` 없이 캐시 결과를 증거로 올리는 것 — README 6절 r4-f 결정. 이유는 문서에 없지만, tag 필터가
task 입력이라 "tag가 무언가를 고른다"는 증거 의미는 캐시로도 유지된다.
- job·단계의 비상태 `if:`(`github.event_name == 'push'`, `!cancelled() && !failure()`)를 실행으로 세지 않는 것 — 정상
workflow를 거부할 수 있지만 닫힌 쪽 실패이고 메시지가 이유를 말한다. 결함으로 세지 않았다.
- `verifyEnvKeys`가 이제 모든 capability jar를 만든다(qualification classpath) — mainCheck 비용 증가를 측정하지 않았다.
- lane 입력 중 `tag`·`mainStage`는 판정에 쓰이지 않거나 이미 다른 입력에 들어 있다 — 캐시를 불필요하게 깨는 경우는
그 값을 바꿀 때뿐이라 해가 없다.
- IDE에서 `SamplePortfolioApplication`을 프로필 없이 바로 실행하면 거부된다 — 결정의 직접 결과이고 메시지가 해결책을 말한다.
- sample 관리 포트에서 데모 체인이 모든 GET을 허용 — 이전부터의 상태(1차 06 Declined).
- 새 ArchUnit 규칙 2개(`INBOUND_ADAPTERS_DO_NOT_REACH_SYSTEM_INVOKED_USE_CASES`, `INTEGRATION_EVENT_DRAFTS_ARE_BUILT_BY_THE_SHARED_HELPER`)의
범위 — 01 영역 소관.
- `metrics.yaml`의 `redis.lane.*`·`outbox.retry.long.*` 행과 코드의 일치 — 03·04·05 영역 소관.
- `SampleRuntimeDefaultsContractTest`가 `app.*` 최상위 묶음만 보는 것 — RR-06-06 고치는 법이 요구한 수준이다.
## 수렴 판단 — 이 라운드가 만든 새 Important 이상이 있는가
**있다. 2건이다.**
- RR2-04-01: RR-07-04 수정(prod `fixture-` 거부)이 모든 설정값을 보아서, 정당한 값(예: Kubernetes pod 이름 `HOSTNAME`)으로
운영 기동만 막힌다.
- RR2-04-02: RR-07-02 결정 구현(허용 목록·기본 프로필 삭제)이 허용한 `test`·`demo`로는 sample이 뜨지 않고, sample 이미지
실행 문서가 깨졌다.
그 밖에 1차 Important 하나가 덜 닫혔다. RR-06-01(RR2-04-03)은 1차 probe 모양은 막았지만, 규칙·비밀 목록 bean 자신이
바인딩되지 않는 모양은 여전히 조용하다.
세 건 모두 고치는 범위가 작다. 정확한 값 목록 하나, yml 문서 하나와 Dockerfile 주석, runner의 면제 조건 하나다.
다음 수정 라운드는 필요하다. 다만 이 영역에서 구조를 다시 바꿀 일은 아니다.
## Assessment
**Ready to merge? With fixes.**
RR-06-02·03·05~12, RR-07-05, RR-04-09는 코드와 실행으로 닫혔고 회귀는 없다. 다만 이번 라운드의 보안·데모 수정이 새
Medium 2건(운영에서만 터지는 `fixture-` 오거부, 허용한 데모 프로필로 sample이 뜨지 않음)을 만들었다. RR-06-01도 면제
경로가 남았다. 셋 다 merge 전에 고치는 것이 맞다.
+271
View File
@@ -0,0 +1,271 @@
# 업그레이드 안내 — 2026-11 성숙도 리뷰 수정
- 범위: `01a8a2a70..bbe944bd` (main → `refactor/maturity-review-2026-11`, 커밋 5개)
- 커밋: `34565130` High·P1 19건 · `1400dc15` 남은 발견·매뉴얼·생성 명령 · `5786126c` 남은 항목과 합친 뒤 결함 ·
`7ef8d0b4` 재리뷰 기록(문서만) · `bbe944bd` 재리뷰 결함
- 근거 문서: `docs/reviews/2026-11-01-maturity-review/README.md` 13~16절, `docs/reviews/2026-11-03-rereview/README.md`
4·6·8절, 각 커밋의 `BREAKING CHANGE:` 꼬리말
- 아래 표의 각 줄은 위 범위의 diff와 코드로 확인했다. 확인하지 못한 것은 그 자리에 "확인 못 함"으로 적었고 9절에
모았다.
## 1. 누가 읽나
이 템플릿을 `upstream` remote로 두고 변경을 merge해 받는 파생 서비스(예: `tech-log-backend` — `origin`=서비스,
`upstream`=이 템플릿)의 개발자가 읽는다. 이 브랜치가 main에 합쳐진 뒤 `git merge upstream/main`을 하기 전에 본다.
## 2. 한눈에
### 반드시 할 일
| # | 할 일 | 안 하면 | 해당 서비스 |
|---|---|---|---|
| 1 | JWT 모드면 `APP_SECURITY_JWT_AUDIENCE`에 이 서비스의 client id를 쉼표로 넣는다 | 기동 실패 `APP_SECURITY_JWT_AUDIENCE (app.security.audience) is required` | JWT 모드(기본값) 전부 |
| 2 | dev·prod 환경 변수의 `APP_FLYWAY_ENABLED` 값을 확인한다 | `false`가 남아 있으면 이제 정말로 마이그레이션이 안 돈다 | persistence-jpa 선택 |
| 3 | prod 설정 어디에도 `fixture-`로 시작하는 값이 없게 한다 | prod 기동 실패(exit 78) | prod 배포 전부 |
| 4 | 직접 만든 `StartupRule`·`RequiredProductionSecrets` bean을 `static @Bean`, 의존성 없이 바꾼다 | 기동 실패 `startup rule '<이름>' created [...]`(exit 78) | 자기 rule이 있는 서비스 |
| 5 | 직접 구현한 outbox·발행·알림·파일 서버 포트를 새 시그니처로 고친다(3.1절) | 컴파일 오류 | 해당 포트를 구현·호출하는 서비스 |
| 6 | `dev.caskeleton.application.outbound.*` import를 `application.secret.*`·`application.objectstorage.content.CallBudget`으로 바꾼다 | 컴파일 오류 | 해당 타입을 쓰는 서비스 |
| 7 | 이벤트 id를 소문자 UUIDv7로 만들고 `IntegrationEventDraft`는 `IntegrationEventDrafts.draft(...)`로만 만든다 | 쓰기 요청이 `IllegalArgumentException`으로 실패, architectureTest 실패 | 통합 이벤트를 내는 서비스 |
| 8 | V21 배포 전에 `docs/runbooks/outbox-dead-letter.md` §8 Step 1 쿼리를 운영 DB에 돌린다 | 중복 순서 키가 있으면 기동 실패(exit 70, V20에 남음) | persistence-jpa + outbox |
| 9 | 이 브랜치의 이전 V21을 적용한 개발 DB를 다시 만든다(4.2절) | Flyway checksum 불일치로 기동 실패(exit 70) | 이 브랜치를 미리 받아 돌린 개발 DB |
| 10 | 자기 SecurityFilterChain이 있으면 `DispatcherType.ERROR`를 허용한다 | 핸들러 밖 오류가 401로 바뀌어 나간다 | 자기 보안 체인을 둔 서비스 |
| 11 | 짝 프론트(또는 다른 클라이언트)에 7절 계약을 맞추게 한다 | 409를 재시도 불가로 읽거나, `null` 키를 기대하다 깨진다 | HTTP 클라이언트가 있는 서비스 |
| 12 | 자기 Flyway 마이그레이션 번호가 템플릿의 새 번호와 겹치지 않는지 본다(4절) | 같은 버전 두 개로 Flyway 실패 | 같은 stream에 자기 마이그레이션을 둔 서비스 |
| 13 | `.env`에 옛 `.env.example` 값을 복사해 두었다면 5.6절 키를 다시 맞춘다 | 새 기본값이 안 먹거나(JDBC batch), 기동 실패(알림 콜백 상한) | `.env`를 복사해 쓰는 서비스 |
### 되돌릴 수 없는 것
- 이 repo에는 down 마이그레이션이 없다(`U*__*.sql` 파일 0개). 되돌리려면 배포 전 백업을 복원한다(4.4절).
- notification V12는 중복 수신 거부(suppression) 행을 **지운다**. 알림을 쓰는 서비스는 배포 전 백업이 필수다.
## 3. 호환성을 깨는 변경
증상 칸의 exit 코드는 `StartupErrorCode`(`src/adapter/outbound/support/.../startup/StartupErrorCode.java`)를 따른다:
70 `MIGRATION_FAILED`, 71 `PROFILE_MISMATCH`, 72 `REQUIRED_ADAPTER_DISABLED`, 78 `STARTUP_VALIDATION_FAILED`.
### 3.1 Java API — 컴파일이 깨진다
| # | 무엇이 바뀌었나 | 파생 서비스 증상 | 할 일 | 근거 |
|---|---|---|---|---|
| B-01 | `OutboxStorePort`: `markFailed(OutboxLease, Instant)` → `markFailed(OutboxLease, Instant, String failureCode)`, `markDead(OutboxLease)` → `markDead(OutboxLease, String failureCode)`. 추상 메서드 추가: `markDeferred(OutboxLease, Instant, String)`, `releaseLease(OutboxLease, Instant)`, `longRetries(int, Instant)`(반환 `OutboxLongRetries`) | 직접 만든 store·fake가 `does not override abstract method` 컴파일 오류, 호출부 인자 수 오류 | 템플릿 `JpaOutboxStore`만 쓰면 할 일 없음. 직접 구현했다면 다섯 메서드를 구현한다. `failureCode`는 메시지가 아닌 코드다(`OutboxPublishAttempt.isFailureCode`) | `1400dc15`(markDeferred·releaseLease), `bbe944bd`(failureCode·longRetries) · `src/application-core/src/main/java/dev/caskeleton/application/outbox/OutboxStorePort.java` |
| B-02 | 발행 포트 반환형: `IntegrationEventPublishPort.publish(ValidatedIntegrationEvent)`가 `CompletionStage<OutboxPublishOutcome>` → `CompletionStage<OutboxPublishAttempt>`. `OutboxMessagePublishPort.publishForOutcome(ClaimedOutboxEvent)`가 `OutboxPublishOutcome` → `OutboxPublishAttempt`. 둘 다 default `longestAttempt()` 추가 | 구현체 반환형 불일치 컴파일 오류 | 결과를 `OutboxPublishAttempt.confirmed()`, `OutboxPublishAttempt.of(outcome)`, `OutboxPublishAttempt.failed(outcome, code)`로 감싼다 | `bbe944bd` · `.../messaging/event/IntegrationEventPublishPort.java`, `.../outbox/OutboxMessagePublishPort.java` |
| B-03 | enum 값 추가: `OutboxPublishOutcome.REJECTED_RETRYABLE`(`retryable()`=true), `OutboxRelayResult.Outcome.RELEASED`, `OutboxEventStatus.PARKED` | `default` 없는 switch 식이 "does not cover all possible input values" 컴파일 오류 | 새 값 분기를 더한다 | `34565130`(REJECTED_RETRYABLE), `1400dc15`(RELEASED), `bbe944bd`(PARKED) |
| B-04 | `OutboxRelayFailureReport`에 `failureCode` 필드 추가, `retryableFailure(...)`·`deadLetter(...)`에 `String failureCode` 인자 추가. `PublishPendingOutboxEventsCommand()` → `PublishPendingOutboxEventsCommand(BooleanSupplier stopRequested)` | 직접 생성하는 코드 컴파일 오류 | 보고서는 code를 넘긴다. command는 `PublishPendingOutboxEventsCommand.INSTANCE`를 쓰거나 supplier를 넘긴다 | `bbe944bd`(report), `1400dc15`(command) |
| B-05 | 알림: `ReconciliationJobStorePort.claimDue(int, Instant)` → `claimDue(int limit, Instant now, Duration lease)`. `ReconciliationJob`에 `long claimFence` 필드 추가. `reschedule`·`complete`는 fence가 다르면 아무것도 안 바꾼다 | 직접 구현한 store·job 생성 코드 컴파일 오류 | lease 인자를 받고, claim마다 fence를 올리고, 쓰기에 fence 조건을 건다. 계약은 `application-notification` testFixtures의 공유 계약 테스트로 확인 | `34565130`, `bbe944bd` · `src/application-notification/.../dispatch/ReconciliationJobStorePort.java` |
| B-06 | 파일 서버: `CleanupQueuePort.claimDue(Instant, int)` → `claimDue(Instant, int, Duration lease)`, `markAbandoned(CleanupItem, String reasonCode)` 추가. `CleanupItem`에 `UUID claimToken` 필드 추가. `FileQuotaPort.usedBytes(QuotaScope)` 추가. `UploadContentPort.releaseLease(UploadSession, RequestContext)` 삭제 | 직접 구현한 포트·`CleanupItem` 생성 코드 컴파일 오류 | 새 메서드 구현, `releaseLease` 호출 제거 | `1400dc15`(cleanup), `5786126c`(quota·upload) · `src/application-fileserver/.../cleanup/CleanupQueuePort.java`, `.../api/metadata/FileQuotaPort.java`, `.../upload/UploadContentPort.java` |
| B-07 | 패키지 이동: `dev.caskeleton.application.outbound.SecretSourcePort`·`SecretReference` → `dev.caskeleton.application.secret.*`. `dev.caskeleton.application.outbound.CallBudget` → `dev.caskeleton.application.objectstorage.content.CallBudget`(leaf `application-objectstorage`). `application.outbound` 패키지 삭제 | `package dev.caskeleton.application.outbound does not exist` | import를 바꾼다. `CallBudget`을 쓰는 leaf가 `application-objectstorage`에 의존해도 되는지 `modules.json` 간선을 확인 | `5786126c` · `src/application-core/.../secret/`, `src/application-objectstorage/.../content/CallBudget.java` |
| B-08 | `shared-contract`에서 `dev.caskeleton.shared.operation.Operation`·`OperationStatus` 삭제. sample-portfolio(`...sample.portfolio.adapter.inbound.web.operation`)로 옮겨졌다 | import 실패 | 쓰고 있었다면 자기 inbound adapter로 복사한다 | `1400dc15` · `src/shared-contract/src/main/java/dev/caskeleton/shared/operation/`(삭제) |
| B-09 | `SecuritySettings`(adapter:inbound:web): `audience`가 `String` → `List<String>`. `@ConfigurationProperties` 제거, `SecuritySettings.bind(Environment)`로 strict 바인딩. 생성자 `(String, String, List)` → `(String, List<String>, List<String>)`. `bootstrap.security.AuthenticationModeSettings` 삭제 | `audience()`를 문자열로 쓰는 코드, 직접 생성하는 테스트 컴파일 오류 | `List<String>`으로 바꾼다. 인증 모드는 `SecuritySettings.authMode()`에서 읽는다 | `34565130`(List), `5786126c`(strict·삭제) · `src/adapter/inbound/web/.../settings/SecuritySettings.java` |
| B-10 | adapter 공개 타입 삭제·이동: graphql `execution.GraphQlTimeoutPolicy`·`dataloader.GraphQlDataLoaderRequestRegistry` 삭제(`runtime.GraphQlDeadlineInstrumentation`·`GraphQlPerParentFetchInstrumentation` 추가). jpa `experimental.tenant.TenantId` 삭제 → `dev.caskeleton.application.tenant.TenantId`. persistence-notification의 엔티티는 `...platform.entity`, 저장소는 `...platform.repository`로 이동, `inbox` 하위 클래스는 `platform`으로 올라옴, `PreferenceJpaRepository`·`SuppressionJpaRepository` 삭제, `JpaNotificationSideEffect` → application-notification `dispatch.SuppressionSideEffect` | import 실패. leaf `check`의 API surface 비교가 스냅샷과 달라 실패(자기 공개 타입을 더했다면 merge 충돌) | import를 바꾼다. 스냅샷 파일은 upstream 것을 받고 자기 추가분을 다시 승인한다 | `1400dc15`·`5786126c` · `docs/architecture/graphql-api-surface.txt`, `docs/architecture/jpa-api-surface.txt`(166→165), `docs/notification/api-surface-snapshot.txt`(362→364) |
| B-11 | 조립·지원 타입: `bootstrap.autoconfigure.operation.DurableOperationConfig` → `composition:durable-operation`의 `composition.operation.DurableOperationAutoConfiguration`. `bootstrap.settings.LoggingSettings` 삭제. `composition.outbox.OutboxLeaderElectionToken` 삭제. `TracingSamplingEnvironmentPostProcessor` → `TracingEnvironmentPostProcessor`, `StartupOrder.TRACING_SAMPLING` → `TRACING_PROPERTIES`. `StartupRuleRunner(Environment, List<StartupRule>)` → `StartupRuleRunner(Environment)`. `SecretSourceValidator(ConfigurableEnvironment, SecretSourcePort, List)` → `SecretSourceValidator(Supplier<List<RequiredProductionSecrets>>)` | 이 타입을 참조하는 코드·테스트 컴파일 오류 | 새 이름으로 바꾼다 | `1400dc15`, `34565130`, `bbe944bd` · `src/composition/durable-operation/`, `src/adapter/outbound/support/.../startup/` |
### 3.2 설정·기동 — 기동이 실패하거나 런타임 예외가 난다
| # | 무엇이 바뀌었나 | 파생 서비스 증상 | 할 일 | 근거 |
|---|---|---|---|---|
| B-12 | JWT 모드에서 `APP_SECURITY_JWT_AUDIENCE` 필수(빈 값 거부, `${...}`가 안 풀린 값도 없는 값으로 봄). 토큰 `aud`가 목록 중 하나를 담아야 통과. `resource_access` role은 audience에 적은 client 것만 읽는다(realm role은 그대로) | 기동 실패 `APP_SECURITY_JWT_AUDIENCE (app.security.audience) is required`(exit 코드 확인 못 함). `.env.example`이 `APP_SECURITY_JWT_AUDIENCE=`(빈 값)를 싣고 있다. 다른 client의 role에 기대던 권한이 사라짐 | client id를 쉼표로 넣는다. 다른 client role로 권한을 받던 사용자가 있는지 IdP에서 확인 | `34565130`(필수·role), `1400dc15`(안 풀린 `${...}`) · `src/adapter/inbound/web/.../auth/JwtDecoderConfig.java`, `.../JwtToAuthenticatedPrincipalConverter.java`, `.../settings/SecuritySettings.java` |
| B-13 | `app.security.*` strict 바인딩: 접두어 아래 오타 키, 또는 설정·placeholder 어디에도 쓰이지 않는 `APP_SECURITY_*` 환경 변수가 기동을 막는다 | 기동 실패(메시지는 `StrictSettingsBinder`가 키 이름을 담아 냄, 정확한 문구 확인 못 함) | 쓰지 않는 `APP_SECURITY_*` 변수를 지운다 | `5786126c` · `SecuritySettings.bind`, `src/adapter/outbound/support/.../StrictSettingsBinder.java` |
| B-14 | prod 프로필에서 `fixture-`로 시작하는 설정 값(변수 이름 무관)을 거부. Redis ACL fixture 파일 이름 변경: `infra/redis-sdk/acl/all-accounts.acl` → `lane-fixture-accounts.acl` | prod 기동 실패, 요약 `prod secret/config-source contract is invalid`(exit 78). 옛 ACL 경로를 mount하던 compose는 파일 없음 | prod 값을 진짜 비밀로 바꾼다. compose의 ACL 경로를 새 이름으로 | `bbe944bd` · `src/app-bootstrap/.../runtime/SecretSourceValidator.java`, `docs/registries/secrets-classification.yaml` |
| B-15 | 기동 rule이 모든 singleton보다 먼저 돈다(`StartupRuleRunner`가 `BeanFactoryPostProcessor`). `StartupRule`과 `RequiredProductionSecrets` bean은 `static @Bean`이고 `Environment`, bean factory, static 무인자 `RequiredProductionSecrets`의 `ObjectProvider`만 받아야 한다 | non-static `@Bean`이거나 다른 bean을 받으면 기동 실패 `startup rule '<이름>' created [<bean>] while creating it ... Declare the rule with a static @Bean method ...`(exit 78) | rule 선언을 `static`으로, 인자를 위 셋으로 줄인다. 다른 bean이 필요한 검사는 rule이 아니라 일반 bean으로 둔다 | `34565130`, `bbe944bd` · `src/adapter/outbound/support/.../startup/StartupRule.java`, `StartupRuleRunner.java` |
| B-16 | 권한 가드(새 `PermissionEnforcementGuard`): `@SystemInvoked` 유스케이스가 bean이면 기동 실패. `@RequiresPermission`을 단 bean에 적용되는 advisor가 없어도 기동 실패. ArchUnit `SYSTEM_INVOKED_USE_CASES_DECLARE_NO_PERMISSION`, `INBOUND_ADAPTERS_DO_NOT_REACH_SYSTEM_INVOKED_USE_CASES` 추가 | 기동 실패 `@SystemInvoked use cases are registered as beans ...` 또는 `beans declare @RequiresPermission but no advisor enforces it ...`(exit 72). inbound adapter가 그 유스케이스를 부르면 architectureTest 실패 | 시스템만 부르는 쓰기 유스케이스는 composition에서 `new`로 만들어 호출자(scheduler 등)에 넘긴다. `@RequiresPermission`을 쓰면 web adapter(`MethodSecurityConfig`)가 조립돼 있어야 한다 | `1400dc15`, `bbe944bd` · `src/composition/service-runtime/.../authorization/PermissionEnforcementGuard.java`, `src/application-core/.../security/SystemInvoked.java` |
| B-17 | `IntegrationEventDraft`: `eventId`·`causationId`는 소문자 UUIDv7만. ArchUnit `INTEGRATION_EVENT_DRAFTS_ARE_BUILT_BY_THE_SHARED_HELPER`: `new IntegrationEventDraft<>(...)` 금지, `IntegrationEventDrafts.draft(...)`만 | 이벤트를 만드는 쓰기 요청이 `IllegalArgumentException: eventId must be a canonical lower-case UUIDv7...`로 실패. architectureTest 실패 | event id를 UUIDv7로 만든다(예: sample `UuidOutboxEventIdFactory`가 `UuidCreator.getTimeOrderedEpochPlus1()`). draft는 헬퍼로 만든다. tenant가 없는 이벤트는 `IntegrationEventDrafts.SINGLE_TENANT_SCOPE`(`global`) | `1400dc15`, `bbe944bd` · `src/application-core/.../messaging/event/IntegrationEventDraft.java`, `IntegrationEventDrafts.java` |
| B-18 | `MessageHandler.schemaVersions()`(vendored `messaging-core-api`, default `{v1}`): 소비자 decode 목록을 handler 선언으로 만든다. 같은 (메시지 타입, 버전)에 다른 payload class를 선언하면 실패 | 컴파일은 된다. v1이 아닌 메시지는 `SCHEMA_VERSION_NOT_REGISTERED`로 거부. 발행 등록(`MessageContracts`)과 class가 다르면 기동 실패 `MESSAGING_CONTRACT_CONFLICT` | v2 이상을 읽는 handler는 `schemaVersions()`를 override한다. 소비 타입을 `MessageContracts`에 따로 등록하던 코드는 지운다 | `5786126c` · `src/messaging/messaging-core-api/.../delivery/MessageHandler.java`, `messaging-spring-boot-starter/.../MessageContracts.java` |
| B-19 | `APP_FLYWAY_ENABLED`가 모든 프로필에서 읽힌다. dev·prod 프로필 파일의 `spring.flyway.enabled: true`·`app.persistence.vendor` 고정값을 지우고 persistence-jpa `config/module-defaults`가 `${APP_FLYWAY_ENABLED:true}`를 싣는다 | dev·prod 환경에 `APP_FLYWAY_ENABLED=false`가 있으면 전에는 무시됐지만 이제 기동 때 마이그레이션이 안 돈다 | dev·prod 환경 값을 확인한다. 자기 `application-dev.yml`·`application-prod.yml`에 같은 고정값을 다시 넣지 않는다 | `5786126c` · `src/app-bootstrap/src/main/resources/application-{dev,prod}.yml`, `src/adapter/outbound/persistence-jpa/.../module-defaults/persistence-jpa.yml` |
| B-20 | JDBC batch 기본 켜짐: `APP_JPA_HIBERNATE_BATCH_SIZE` 0→50, `APP_JPA_HIBERNATE_ORDER_INSERTS`·`ORDER_UPDATES` false→true(registry `compatibility_impact: behavior-change`) | 컴파일·기동은 그대로. SQL이 묶여 나가고 insert·update 순서가 바뀐다. IDENTITY 키 엔티티는 batch가 조용히 꺼진다. `.env`에 옛 값(0·false)이 있으면 새 기본값이 안 먹는다 | 문장 순서에 기대는 코드가 있는지 본다. 끄려면 0·false를 명시 | `1400dc15` · `persistence-jpa.yml`, `docs/registries/env-keys.yaml` |
| B-21 | 트랜잭션 제한: `TransactionPort` 쓰기·읽기 트랜잭션 30초(`app.persistence-jpa.transaction.write-timeout`·`read-timeout`, env 키 아님) | 30초를 넘는 트랜잭션은 문장이 취소되고 `DB_QUERY_CANCELED`로 실패 | 긴 일괄 작업은 쪼갠다. 꼭 필요하면 프로필 yml에서 값을 올린다 | `1400dc15` · `persistence-jpa.yml` |
| B-22 | 격리 수준을 Hikari에서 고정: `spring.datasource.hikari.transaction-isolation: TRANSACTION_READ_COMMITTED`. 다른 값이면 거부. `TransactionPort`는 트랜잭션마다 격리 수준을 정하지 않는다 | 다른 격리 수준을 설정했다면 기동 실패(`HikariPoolConstraintValidator`) | 값을 지운다. 더 높은 격리가 필요한 곳은 따로 설계한다 | `1400dc15` · `src/adapter/outbound/persistence-jpa/.../startup/HikariPoolConstraintValidator.java` |
| B-23 | H2 드라이버가 운영 jar에서 빠짐(persistence-jpa `runtimeOnly` → `testRuntimeOnly`). `bootRunH2` 작업만 따로 넣는다 | `APP_PERSISTENCE_VENDOR=h2`로 `bootRunH2` 밖에서 띄우면 드라이버가 없다(정확한 오류 확인 못 함) | 로컬은 Compose PostgreSQL 또는 `bootRunH2`를 쓴다 | `1400dc15` · `src/adapter/outbound/persistence-jpa/build.gradle` |
| B-24 | `APP_IDEMPOTENCY_PROCESSING_LEASE`는 2초(`IdempotencyExecutor.IN_FLIGHT_RETRY_AFTER`)보다 길어야 한다 | 2초 이하면 기동 실패 | 값을 2초보다 길게(기본 30s) | `5786126c`, `bbe944bd` · `src/composition/idempotency/.../IdempotencySettings.java` |
| B-25 | 알림 콜백 본문 상한 65508 → 65251(바인딩에서 상한 검사) | `.env`에 옛 예제 값 `APP_NOTIFICATION_PLATFORM_CALLBACK_MAX_BODY_BYTES=65508`이 있으면 기동 실패 `max-body-bytes must be 1..65251` | 값을 지우거나 65251 이하로 | `5786126c` · `src/adapter/outbound/notification/.../autoconfigure/NotificationPlatformSettings.java` |
| B-26 | `config/module-defaults/`에 같은 이름 파일이 둘이거나, 두 파일이 같은 키를 실으면 기동 실패 | 기동 실패 `two capability modules ship config/module-defaults/<file>` 또는 `... both ship <key>`(exit 78) | 자기 leaf의 module-defaults 파일 이름·키가 템플릿 모듈과 겹치지 않게 한다 | `1400dc15` · `src/adapter/outbound/support/.../startup/ModuleDefaultsEnvironmentPostProcessor.java` |
| B-27 | (sample-portfolio를 남겨 둔 경우) 데모 계정은 활성 프로필이 모두 `local`·`test`·`demo` 중 하나일 때만. 프로필이 없어도 거부 | 기동 실패 `the sample's demo accounts authenticate only under the local, test or demo profile` | `SPRING_PROFILES_ACTIVE=local` 등으로 띄우거나 sample 보안 설정을 지운다 | `5786126c`, `bbe944bd` · `src/sample-portfolio/.../security/SampleDemoAccountsProductionGuard.java` |
### 3.3 HTTP wire — 응답이 달라진다
정본은 `docs/web/http-contract.md`다. 클라이언트는 `success`와 `error.code`로 가른다.
| # | 무엇이 바뀌었나 | 파생 서비스 증상 | 할 일 | 근거 |
|---|---|---|---|---|
| B-28 | 처리 중 409 `IDEMPOTENT_IN_FLIGHT`: `retryable` false→true, `Retry-After: 2` 추가. gRPC trailer `error-retryable`과 GraphQL extension `retryable`도 true | 409를 "재시도 금지"로 처리하던 클라이언트가 틀린다 | **같은 `Idempotency-Key`로** `Retry-After` 뒤 재전송하게 한다. 새 키 금지 | `34565130` · `src/shared-contract/.../error/OperationalError.java`, `docs/registries/error-codes.yaml` |
| B-29 | Envelope의 `null` 필드를 키째 생략: 성공은 `error` 키 없음, 실패는 `data` 키 없음, `meta.page`·`meta.correlationId`·`error.details`도 값이 없으면 키 없음. 빈 목록은 그대로 | `"error": null`·`"data": null`을 기대하던 클라이언트·계약 테스트가 깨진다 | `success`로 가르고 키 존재로 판단하지 않는다 | `34565130` · `src/adapter/inbound/web/.../envelope/EnvelopeWireFormatConfig.java` |
| B-30 | 새 코드 `IDEMPOTENCY_COMPLETION_UNKNOWN`(503, `TRANSIENT_DEPENDENCY`, retryable=true): 작업 실행 **뒤** complete 단계에서 멱등성 저장소가 응답하지 않음. 전에는 `IDEMPOTENCY_UNAVAILABLE` | 503을 "적용 안 됨"으로 읽던 클라이언트가 새 키로 다시 보내 중복이 생길 수 있다 | `error.code`로 가른다. 결과 불명이므로 같은 키로만 재전송 | `bbe944bd` · `src/application-core/.../idempotency/IdempotencyCompletionUnknownException.java`, `IdempotencyExecutor.java` |
| B-31 | 핸들러 밖 오류(`/error` 디스패치)를 `EnvelopeErrorController`가 실패 Envelope로 답한다. 전에는 Boot `/error` 맵이 `success:true`로 감싸져 요청 경로까지 실려 나갔다. 기본 JWT 체인에서 익명 400이 401로 바뀌지 않는다. 4xx·5xx 본문은 `success:true`로 감싸지 않는다. 보안 체인이 `DispatcherType.ERROR`를 허용한다 | 오류 본문 모양이 바뀐다. 자기 SecurityFilterChain이 ERROR 디스패치를 막으면 400이 401로 나간다 | 자기 체인에 `auth.dispatcherTypeMatchers(DispatcherType.ERROR).permitAll()`을 넣는다(템플릿 `SecurityConfig`와 같게) | `bbe944bd` · `src/adapter/inbound/web/.../error/EnvelopeErrorController.java`, `.../auth/SecurityConfig.java` |
| B-32 | 새·바뀐 오류 코드: 비동기 요청 timeout 500 `INTERNAL_ERROR` → 503 `REQUEST_TIMEOUT`(retryable). `IDEMPOTENCY_KEY_INVALID` 400(`details.reason`=`MISSING`·`MALFORMED`, `IdempotencyKeyHeader.parse`를 쓰는 엔드포인트, sample은 `BAD_PARAMETER`에서 바뀜). web-advanced 예외 10종이 모두 500 `INTERNAL_ERROR`였다가 각자 코드(`ADMISSION_REFUSED` 503 등) | 코드로 분기하던 클라이언트가 새 코드를 모른다 | 클라이언트 분기표에 더한다. web-advanced 표는 `src/adapter/inbound/web-advanced/README.md` 「오류 응답」 | `1400dc15` · `src/adapter/inbound/web/.../error/WebTransportError.java`, `HttpStatusErrorCodes.java`, `src/adapter/inbound/web-advanced/.../error/WebAdvancedError.java` |
| B-33 | DB 실패 분류: 낙관적 잠금 충돌 500 → 409 `DB_OPTIMISTIC_CONFLICT`. 커밋 단계 연결 끊김(08xxx, 40003 등)을 재시도 가능으로 답하던 것 → 500 `DB_COMPLETION_UNKNOWN`(retryable=false) | 응답 status·code가 바뀐다 | 409는 다시 읽고 재시도, `DB_COMPLETION_UNKNOWN`은 업무 데이터로 결과를 확인 | `34565130`, `1400dc15` · `src/adapter/outbound/persistence-jpa/.../failure/PersistenceExceptionTranslator.java` |
### 3.4 빌드 게이트·아키텍처 규칙 — `ci`가 빨개진다
| # | 무엇이 바뀌었나 | 파생 서비스 증상 | 할 일 | 근거 |
|---|---|---|---|---|
| B-34 | 템플릿 패키지 규칙(ArchUnit): `FEATURE_PACKAGES_DO_NOT_REUSE_TEMPLATE_PACKAGE_NAMES`, `TEMPLATE_PACKAGES_DO_NOT_DEPEND_ON_FEATURE_PACKAGES`. 템플릿 이름: application `usecase command query capability transaction security tenant observability secret messaging outbox idempotency operation lease lock cache realtime notification fileserver objectstorage`, domain `identifier stereotype` | 기능 패키지 이름이 이 목록과 겹치거나(예: `domain.lock`), 업무 코드를 템플릿 패키지(예: `application.usecase.*`)에 두고 기능 패키지를 import하면 `:app-bootstrap:architectureTest` 실패 | 기능 패키지 이름을 바꾸고, 업무 코드를 `dev.caskeleton.application.<feature>`로 옮긴다. 규칙 정본은 `src/application-core/CLAUDE.md` "Package ownership" | `5786126c` · `src/app-bootstrap/src/architectureTest/.../TemplatePackageOwnership.java` |
| B-35 | JPA 규칙: 양방향 연관은 한쪽에서만 매핑(`mappedBy`), notification·fileserver 저장소 엔티티는 그 leaf 안에서만, `@Version` 엔티티의 bulk update는 version을 올려야 함 | 위반 엔티티·쿼리가 있으면 architectureTest 실패 | 매핑·쿼리를 고친다 | `34565130`, `1400dc15`, `bbe944bd` · `src/app-bootstrap/src/architectureTest/.../JpaProductionArchitectureTest.java` |
| B-36 | 빌드 검사 강화: `modules.json`에 없는 `build.gradle`이 있으면 `verifyCleanArchitectureDependencies` 실패. `verifyStrictLaneStages --dry-run`은 모든 strict lane이 workflow가 실행하는 단계(`:ci` `:sample-portfolio:check` `:mainCheck` `:integrationCheck` `:performanceCheck` `:releaseCheck`)에 속해야 하고 `.github/workflows`를 읽는다. SpotBugs 신뢰도 HIGH → MEDIUM | 등록 안 한 leaf, 단계에 안 걸린 자기 lane, 자기 코드의 MEDIUM 발견이 `ci`·`qualityCheck`를 막는다 | leaf를 등록하거나 지운다. 자기 lane은 단계에 건다. SpotBugs 발견은 고치거나 이유를 단 제외로 | `1400dc15`, `34565130`, `bbe944bd`, `5786126c` · `src/build-logic/.../ModuleRegistry.java`, `.../strictlane/StrictLaneStagesPlugin.java`, `.../quality/QualityConventionsPlugin.java`, `src/build.gradle` |
| B-37 | app-bootstrap 테스트 lane 분리: 저장소 파일을 읽는 테스트는 태그 `document-contract`(main 단계) 또는 `repository-contract`(`check`)여야 하고, 일반 `test` lane에는 `ca.repository.root`가 없다 | app-bootstrap에 둔 자기 테스트가 저장소 파일을 읽으면 `test`에서 실패 | 태그를 단다 | `1400dc15` · `src/app-bootstrap/build.gradle` |
### 3.5 모듈 registry·새 leaf
| # | 무엇이 바뀌었나 | 파생 서비스 증상 | 할 일 | 근거 |
|---|---|---|---|---|
| B-38 | 새 leaf: `adapter-inbound-messaging`(`:adapter:inbound:messaging`, 이벤트 소비+inbox, 기본 조립에 없음), `composition-durable-operation`(`:composition:durable-operation`, `/operations`). 새 간선: `application-objectstorage`·`adapter-outbound-persistence-mongo`·`adapter-outbound-identifier`·`adapter-outbound-redis-sdk` → `shared-contract`, `adapter-inbound-web` → `adapter-outbound-support`, `sample-portfolio` → `adapter-outbound-support`, `app-bootstrap` → 두 새 leaf. 지운 간선: `composition-fileserver-platform` → `adapter-outbound-identifier`. `app-bootstrap/build.gradle`에 `runtimeOnly project(':composition:durable-operation')` 추가 | 자기 leaf를 더한 서비스는 `modules.json`·`app-bootstrap/build.gradle`에서 merge 충돌. 충돌을 풀다 durable-operation 줄을 빠뜨리면 `/operations` 조립이 없다(`DurableOperationConfig`가 app-bootstrap에서 빠졌기 때문) | 두 파일을 손으로 합친다. 합친 뒤 `architectureCheck`로 간선을 확인 | `1400dc15`, `5786126c` · `src/config/architecture/modules.json`, `src/app-bootstrap/build.gradle` |
## 4. DB 마이그레이션
### 4.1 새 버전과 영향
| stream (history 표) | 버전 | 하는 일 | 기존 데이터 영향 | 실패 조건 | 근거 |
|---|---|---|---|---|---|
| postgresql (`flyway_schema_history`, persistence-jpa 선택 시) | V20 | `outbox_event.deferred_attempt_count INTEGER NOT NULL DEFAULT 0` + CHECK ≥ 0 | 기존 행 0. 지난 claim은 전부 시도 예산에 센다 | 확인된 것 없음 | `1400dc15` |
| 〃 | V21 | `outbox_aggregate_sequence`(aggregate별 counter), `outbox_aggregate_sequence_floor`(V21 적용 시각 마이크로초 한 행), 남은 행 최대 번호로 counter 미리 생성, 유일 인덱스 `ux_outbox_event_aggregate_order (tenant_scope, aggregate_type, aggregate_id, aggregate_sequence, event_index)` | 새로 생기는 aggregate의 첫 번호가 floor+1(약 1.7×10¹⁵)부터. 순서 열이 NULL인 옛 행은 비교 안 함 | ① 같은 순서 키 행이 이미 둘 이상 → 실패, V21 전체 롤백, V20에 남음(exit 70). ② `SET LOCAL lock_timeout = '5s'` 안에 `outbox_event` 잠금을 못 잡으면 실패·롤백. ③ 같은 이름 인덱스가 유효한 유일 인덱스가 아니면(실패한 CONCURRENTLY) `RAISE EXCEPTION` | `1400dc15`, `bbe944bd` · `docs/runbooks/outbox-dead-letter.md` §8 |
| 〃 | V22 | `outbox_event.last_failure_code VARCHAR(120)` NULL, 기본값 없음. 새 상태 `PARKED`는 DDL 없음 | 행 재작성 없음. 기존 행은 다음 실패 때까지 NULL | 확인된 것 없음 | `bbe944bd` |
| notification (`flyway_jpa_notification_history`, notification-platform 선택 시) | V11 | `notification_reconciliation_job.claimed_until timestamptz`, `claim_fence bigint NOT NULL DEFAULT 0` + CHECK | 기존 job은 fence 0, lease 없음 | 확인된 것 없음 | `34565130` |
| 〃 | V12 | `notification_suppression`의 `(tenant_id, normalized_target_hmac, reason)` 중복 행을 **삭제**(만료 없는 것 > 늦은 만료 > 이른 `effective_at` > 이른 `created_at` > 작은 id 순으로 하나 남김) 후 UNIQUE `uk_notification_suppression_target` | 지운 행의 `SuppressionId`는 더 이상 조회되지 않는다. 되돌리려면 백업 필요 | 확인된 것 없음(잠금 대기 제한 없음) | `1400dc15` |
| 〃 | V13 | `notification_request.acceptance varchar(40) NOT NULL DEFAULT 'ACCEPTED'` + CHECK(`ACCEPTED`, `DROPPED_AS_DUPLICATE`) | 기존 요청은 모두 `ACCEPTED` | 확인된 것 없음 | `5786126c` |
| sample (`flyway_sample_schema_history`, sample-portfolio를 남긴 경우) | V8_1 | 유일 인덱스 `uq_poster_title_ci ON poster (upper(title))` | 없음 | 대소문자만 다른 제목이 있으면 `poster has titles that differ only by case or repeat: ...`로 실패 | `34565130` |
| grpc-ledger (optional-platforms, history 표 확인 못 함) | V002 | 부분 인덱스 `ix_grpc_operation_ledger_finished_completed_at` (일반 `CREATE INDEX`) | 없음 | 큰 ledger면 만드는 동안 쓰기가 멈춘다. 파일 주석은 손으로 `CONCURRENTLY`를 먼저 돌리라고 한다 | `1400dc15` |
| 〃 | V003 | `grpc_operation_ledger.claim_attempt BIGINT NOT NULL DEFAULT 1` + CHECK > 0 | 기존 행은 첫 시도(1) | 확인된 것 없음 | `bbe944bd` |
- **새로 연결된 stream**: `adapter:inbound:messaging`을 `runtimeOnly`로 넣으면 platform의 `V1101__messaging_inbox.sql`을
`MessagingInboxSchemaStream`이 `flyway_messaging_inbox_history`에 적용한다(baseline 1100). 넣지 않으면 영향 없음
(`src/adapter/inbound/messaging/README.md`).
- **번호 충돌**: 템플릿이 이제 postgresql V20~V22, notification V11~V13, sample V8_1, grpc V002·V003을 쓴다. 파생 서비스가 같은
위치에 같은 번호를 두었다면 Flyway가 같은 버전 두 개로 실패한다. 자기 마이그레이션은 템플릿과 떨어진 번호대로 옮긴다
(이미 적용된 파일 이름을 바꾸면 checksum·history가 어긋나므로 운영 DB에 적용된 것이면 DB 담당과 정한다).
- **migration-on-startup=false로 운영하는 서비스**: `infra/postgres/apply-capability-streams.sh`가 바뀌었다(stream을
`/flyway/streams/<name>`에서 먼저 찾음). 운영자가 직접 적용한다.
### 4.2 이 브랜치의 이전 V21을 적용한 DB
V21은 `bbe944bd`에서 V22를 따로 두지 않고 직접 고쳤다(floor 표와 counter 미리 만들기를 넣음). `1400dc15`·`5786126c` 시점의
V21(sha256 `f830cda5…`)을 적용한 DB는 새 V21(sha256 `21744ea1…`, `src/adapter/outbound/persistence-jpa/src/test/resources/db/applied-migrations.sha256`)과
checksum이 달라 Flyway 검증에서 기동이 실패한다(exit 70 `MIGRATION_FAILED`).
- 해당 여부 확인: V21이 history에 있는데 floor 표가 없으면 이전 V21이다.
```sql
SELECT version, success FROM flyway_schema_history WHERE version = '21';
SELECT to_regclass('outbox_aggregate_sequence_floor'); -- NULL이면 이전 V21
```
- 할 일: 그 개발 DB를 다시 만든다(예: Compose PostgreSQL 볼륨 삭제 후 재기동). `flyway repair`로 checksum만 맞추지 않는다.
이전 V21에는 floor 표와 counter 미리 만들기가 없어서 스키마가 새 코드와 맞지 않는다.
- 운영 DB: 이 브랜치는 main에 합쳐지기 전이라 어느 배포에도 V21이 없다는 것이 커밋 메시지의 전제다(`bbe944bd`). 파생 서비스가
이 브랜치를 운영에 미리 배포했다면 이 전제가 깨진다. 그 경우는 DB 담당과 정한다.
### 4.3 V21 배포 전 절차
`docs/runbooks/outbox-dead-letter.md` §8을 따른다. 요약:
1. **Step 1 — 중복 확인(읽기 전용)**: §8의 `v21-duplicate-order-keys` 쿼리. 0행이면 배포한다.
2. **Step 2**: 미발행 행이 있는 키는 relay가 비울 때까지 기다린다. `DEAD` 행은 §4 처분을 먼저 한다.
3. **Step 3**: 모두 `PUBLISHED`인 키의 중복을 `outbox_event_v21_duplicates`로 복사한 뒤 지운다(`v21-remove-published-duplicates`).
4. **Step 0 — outbox가 커서 V21이 거는 SHARE 잠금을 견딜 수 없으면**: 중복을 없앤 뒤 같은 이름 인덱스를 transaction 밖에서
`CREATE UNIQUE INDEX CONCURRENTLY IF NOT EXISTS ux_outbox_event_aggregate_order ...`로 먼저 만든다. V21의 `IF NOT EXISTS`가 그것을 쓴다.
CONCURRENTLY가 실패해 INVALID 인덱스가 남으면 `DROP INDEX CONCURRENTLY` 후 Step 1부터.
5. tenant scope를 바꾼 서비스는 옛 scope의 미발행 행이 없는지 §8의 `GROUP BY tenant_scope` 쿼리로 본다.
이 절의 SQL 블록은 `:adapter:outbound:persistence-jpa:postgresqlOutboxOrderKeyRunbookIntegrationTest` lane이 실제 PostgreSQL에서 돌린다.
V21 실패의 분류는 `docs/runbooks/migration-failed.md` "Classify the failure"에 추가됐다.
### 4.4 되돌리기
- **down 마이그레이션 없음.** 이 repo에 `U*__*.sql`(Flyway undo) 파일이 없다. `migration-failed.md`는 앞으로 고치는 마이그레이션을
먼저 쓰고, 적용된 파일 수정·history 고쳐 쓰기·`clean`을 금지한다.
- **배포 전 백업**: 마이그레이션을 돌리기 전에 DB 백업(또는 PITR 지점)을 남긴다. 특히 notification V12는 행을 지운다.
스키마를 되돌려야 하면 백업 복원이 유일한 길이고, `migration-failed.md` Escalation에 따라 DB 담당이 결정한다.
- **V21 실패 시**: V21은 transaction 하나라 실패하면 V20에 그대로 남는다. 원인(중복·잠금)을 없애고 다시 배포한다.
- **앱만 옛 버전으로 되돌릴 때**: 이번 범위의 마이그레이션은 열·표·인덱스·제약을 더하기만 하고(V12의 중복 행 삭제 제외) 열을 지우거나
이름을 바꾸지 않는다. 새 열은 기본값이 있거나 NULL을 허용해서 옛 코드의 insert가 막히지 않는다. 다만 V21 유일 인덱스와 V12·V8_1
유일 제약은 옛 코드가 같은 키를 두 번 쓰면 이제 DB가 거부한다. 옛 앱의 Flyway가 자기가 모르는 최신 버전(V20~V22 등)이 적용된
DB에서 기동하는지는 **확인 못 함**(이 repo는 해당 Flyway 옵션을 설정하지 않음). 스테이징에서 먼저 확인한다.
## 5. 동작 변경 — 코드는 안 깨지지만 결과가 달라진다
| 영역 | 바뀐 것 | 영향 | 근거 |
|---|---|---|---|
| outbox relay | 일시 거부(`REJECTED_RETRYABLE`)·무응답(`AMBIGUOUS`)은 시도 예산을 쓰지 않고 최대 5분 간격(`OutboxBackoffPolicy.MAX_DELAY`)으로 끝없이 재시도. 실패 원인 코드를 `last_failure_code`에 남김. 수동 보류 상태 `PARKED`. 지표 `outbox.retry.long.size`·`outbox.retry.long.age` | 진짜 인증 오류도 DEAD가 아니라 계속 재시도한다. 경보는 새 지표로 잡는다. 처분 SQL은 `docs/runbooks/outbox-dead-letter.md`·`outbox-publish-failed.md` | `34565130`, `1400dc15`, `bbe944bd` |
| outbox append | 읽기 전용 트랜잭션 안의 `append`도 거부(`CallerTransaction.requireReadWrite`). 전에는 트랜잭션 밖만 거부했고 읽기 전용에서는 이벤트가 조용히 사라졌다 | `inRead` 안에서 이벤트를 쓰던 코드가 이제 예외로 드러난다 | `5786126c` · `JpaOutboxStore.java` |
| 순서 번호 | aggregate 순서 번호를 DB counter가 매긴다(`OutboxAggregateSequencePort.nextSequence`). 한 aggregate에 이벤트가 하나면 `AggregateOrder.first()`. 같은 순서 키 두 번째 append는 유일 인덱스가 거부(정확한 오류 코드 확인 못 함) | 소비자가 보는 번호가 새 aggregate에서 floor+1부터 시작해 크게 뛴다. 벽시계로 번호를 만들던 코드는 바꾼다 | `1400dc15`, `bbe944bd` |
| durable operation | operation id가 UUIDv7(`UuidV7DurableOperationIdFactory`). 제출 이벤트의 event id·aggregate id가 UUIDv7이고 tenant scope는 `global` | 전에는 이 이벤트가 messaging bridge에서 전부 DEAD가 됐다(커밋 `1400dc15` 본문). 소비자가 보는 id 모양이 바뀐다 | `1400dc15`, `bbe944bd` · `SubmitDurableOperationUseCase.java` |
| tracing | 자체 tracer를 지우고 Boot tracing·OTLP로. `OTEL_EXPORTER_OTLP_ENDPOINT`는 base 주소로 보고 `<값>/v1/traces`(OTLP/HTTP)로 보낸다. 빈 값이면 exporter 없음. `meta.traceId`가 tracer의 trace id와 같다 | span이 실제로 나가기 시작한다. gRPC 포트(4317)를 넣었다면 HTTP 수신 주소로 바꾼다 | `34565130`, `1400dc15` · `docs/registries/env-keys.yaml` |
| correlation id | `X-Correlation-Id`가 `[A-Za-z0-9._-]{1,128}`(앞뒤 공백 제거 후) 밖이면 서버가 새 값으로 바꾼다 | 규칙 밖 값을 쓰던 호출자는 로그에서 자기 값을 못 찾는다 | `1400dc15` · `docs/web/http-contract.md` §3 |
| String 응답 | `String`을 반환하는 컨트롤러에 JSON을 요청하면 Envelope(`"data": "<문자열>"`)로 나간다. 전에는 500이었다. `byte[]`는 감싸지 않는다(`/v3/api-docs`) | JSON 클라이언트가 이제 200을 받는다 | `1400dc15` · `EnvelopeBodyAdvice.java` |
| GraphQL | 크기를 선언하지 않은 list를 원소 20개로 계산, `first`·`last` 둘 다면 큰 쪽. per-parent 경고 임계 10(`APP_GRAPHQL_PER_PARENT_FETCH_WARNING_THRESHOLD`). deadline instrumentation이 `REQUEST_TIMEOUT` | 전에 통과하던 깊은 목록 쿼리가 복잡도로 거부될 수 있다. 필요한 필드에 `estimatedListSize`를 선언 | `34565130`, `1400dc15`, `bbe944bd` |
| WebSocket | 노드당 STOMP 세션 1000개(`APP_WEBSOCKET_MAX_CONNECTIONS`), 초과 시 연결 후 1013으로 닫음. 메시지 64KB, 송신 버퍼 512KB, 송신 시간 10s, 첫 메시지 60s를 명시 | 동시 연결이 많은 서비스는 상한을 올린다 | `1400dc15` · `env-keys.yaml` |
| gRPC 서버(inbound adapter) | 수신 메시지 1 MiB(io.grpc 기본 4 MiB에서 줄어듦), 메타데이터 8 KiB, 연결당 동시 호출 100, 실행 스레드 32·대기열 256, 기본 deadline 10s, keepalive 30s/10s, 최대 연결 수명 30분, drain 2s | 1 MiB를 넘는 메시지는 거부된다 | `1400dc15` · `src/adapter/inbound/grpc/.../GrpcServerSettings.java` |
| 파일 서버 | 정리 worker 기본 켜짐(`APP_FILESERVER_PLATFORM_CLEANUP_ENABLED` false→true, 끄면 기동 경고). copy·move 대상은 기본 namespace만(`APP_FILESERVER_PLATFORM_TARGET_NAMESPACES`, 그 밖은 `ACCESS_DENIED`). namespace 쿼터 상한(`APP_FILESERVER_PLATFORM_QUOTA_NAMESPACE_LIMIT`, 비우면 무제한, 넘으면 413 `QUOTA_EXCEEDED`). move가 쿼터를 옮긴다 | 다른 namespace로 copy·move하던 서비스는 허용 목록을 설정해야 한다. 정리 worker가 물리 객체를 지운다 | `5786126c`, `bbe944bd` · `CopyFileApplicationUseCase.java`, `env-keys.yaml` |
| 알림 | SES 콜백 replay 허용 차이 5m→1h. 중복 제거 창에서 버린 제출을 `CANCELED`·`DROPPED_AS_DUPLICATE`로 저장해 같은 멱등성 키에 같은 영수증. reconciliation job은 DB lease로 소유. INGEST_ONLY도 accept 때 route 이름 기록 | 콜백·영수증 결과가 바뀐다 | `34565130`, `5786126c` |
| Redis | 캐시 조건부 쓰기가 자기 SCRIPT lane(`APP_CACHE_REDIS_MAXIMUM_SCRIPT_CONNECTIONS`, 기본 4)을 쓴다. registry에서 `redis.capability.*` 지표 6개를 빼고 `redis.lane.*` 6개를 더했다 | Redis 연결이 캐시 lane만큼 늘어난다. 옛 지표 이름으로 만든 대시보드·경보는 바꾼다 | `bbe944bd` · `docs/registries/metrics.yaml` |
| 설정 바인딩 | strict 설정에서 선택 숫자·크기·기간 키의 빈 값은 "미설정". 목록 원소 아래 오타 키도 거부(`StrictSettingsBinder`) | `.env.example`의 빈 값으로 기동 가능. 목록 원소 아래 오타는 이제 기동 실패 | `5786126c` · `StrictSettingsBinder.java` |
| 권한 매핑 | `app.authz.role-permissions` 기본 항목이 app-bootstrap `config/security.yml`에서 각 capability의 module-defaults(notification·fileserver·durable-operation)로 옮겨짐. 여러 출처의 항목이 합쳐진다 | 모듈을 빼면 그 권한 매핑도 빠진다 | `1400dc15` · `src/app-bootstrap/src/main/resources/config/security.yml` |
| 로그 설정 | logback이 `APP_LOG_*` 대신 `app.logging.*`을 읽는다(환경 변수 이름은 그대로 매핑) | 프로필 yml의 `app.logging.*`이 이제 먹힌다 | `1400dc15` · `logback-spring.xml` |
| local 프로필 | `server.port`가 `${APP_SERVER_PORT:8080}`을 읽는다. Flyway·`ddl-auto validate`·PostgreSQL vendor를 module-defaults에서 받는다 | local에서 `APP_SERVER_PORT`가 다른 값이면 포트가 바뀐다 | `1400dc15`, `5786126c` · `application-local.yml` |
| deprecated | `APP_CACHE_REDIS_TTL_JITTER`는 아무것도 바인딩하지 않음(`removal_deadline: 2027-02-28`) | 값이 아무 효과 없다 | `1400dc15` · `env-keys.yaml` |
| sample-portfolio | 익명 쓰기 401, 포스터 제목 대소문자 무시 유일(409 `POSTER_ALREADY_EXISTS`), 관리자도 남의 work log 수정 불가, 샘플 이벤트 tenant `global` | sample을 남긴 서비스만 | `34565130`, `1400dc15` |
## 6. 따라오는 순서
모든 명령은 `src/`에서 `--console=plain`으로 돌린다. 한 단계가 빨개지면 다음으로 가지 않는다.
| 단계 | 할 일 | 게이트 |
|---|---|---|
| 0. 준비 | 운영·스테이징 DB 백업. 작업 브랜치를 따로 만든다. 자기 마이그레이션 번호가 4.1절 번호와 겹치는지 본다. 운영 DB 사본에 4.3절 Step 1 쿼리(필요하면 V8_1 중복 제목 확인)를 돌려 둔다 | — |
| 1. merge·의존성 | `git fetch upstream` 후 merge. 충돌 예상 파일: `config/architecture/modules.json`, `app-bootstrap/build.gradle`, `docs/registries/env-keys.yaml`, `.env.example`, `application*.yml`, API surface 스냅샷, `gradle.lockfile`. 자기 의존성을 바꿨으면 `./gradlew :<leaf>:resolveAndLockAll --write-locks` | `./gradlew verifyDependencyLocks` |
| 2. 컴파일·아키텍처 | 3.1절(B-01~B-11) 고치기. 3.4절 규칙 위반 고치기 | `./gradlew architectureCheck`, `./gradlew :app-bootstrap:architectureTest`, 고친 leaf마다 `./gradlew <gradle-path>:check` |
| 3. PR 게이트 전체 | 자기 strict lane을 단계에 건다. SpotBugs MEDIUM 발견 처리 | `./gradlew ci`, `./gradlew verifyStrictLaneStages --dry-run` |
| 4. 설정 | 2절 체크리스트 1~4·10·13. 3.2절(B-12~B-27) 확인 | `./gradlew :app-bootstrap:verifyEnvKeys`, `./gradlew configContractCheck` |
| 5. DB | 이전 V21을 적용한 개발 DB 재생성(4.2절). 스테이징에 4.3절 절차 후 마이그레이션 | `./gradlew :adapter:outbound:persistence-jpa:integrationTestLaneCheck`(Docker 필요), 알림을 쓰면 `./gradlew integrationCheck` |
| 6. 기동 | prod와 같은 프로필·환경으로 스테이징 기동. exit 코드 70·71·72·78이면 3.2절·4절 해당 줄로 | `./gradlew :app-bootstrap:systemTest`, `./gradlew mainCheck` |
| 7. 계약 | HTTP 응답 모양·코드(3.3절)를 클라이언트와 맞춘다. 공개 경로가 바뀌었는지 확인 | `./gradlew verifyPublicPathSnapshot`, `./gradlew mainCheck`(문서 계약 lane 포함), 짝 프론트 계약 테스트 |
## 7. 짝 프론트
프론트가 맞출 계약의 정본은 `docs/web/http-contract.md`다. 요약:
**Envelope**
| 응답 | 있는 키 | 없는 키 |
|---|---|---|
| 성공 | `success`(true), `data`, `meta` | `error` |
| 실패 | `success`(false), `error`, `meta` | `data` |
| bulk 전체 성공 | `success`(true), `results`, `meta` | `error` |
| bulk 부분 실패 | `success`(false), `error`(`BATCH_PARTIAL_FAILURE`, `details`), `meta` | `results` |
- `success`로 가른다. 키 존재로 판단하지 않는다. `null`이면 키가 없고, 빈 목록은 `[]`로 온다.
- `error`는 `code`·`category`·`message`·`retryable`이 항상 있고 `details`는 있을 때만.
- `meta`의 모르는 키는 무시한다. 요청 id 필터 전에 끊긴 응답은 id 키가 빠질 수 있다.
**멱등성** (같은 `Idempotency-Key` 재전송에 대한 서버 판정)
| 경우 | status | `error.code` | `retryable` | `Retry-After` | 클라이언트 행동 |
|---|---|---|---|---|---|
| 재생 | 첫 요청의 성공 status | — | — | — | 첫 결과로 받는다 |
| 처리 중 | 409 | `IDEMPOTENT_IN_FLIGHT` | true | 2 | 같은 키로 `Retry-After` 뒤 재전송. 새 키 금지 |
| 본문 불일치 | 422 | `IDEMPOTENT_REQUEST_MISMATCH` | false | — | 다시 보내지 않는다 |
| 키 누락·형식 오류 | 400 | `IDEMPOTENCY_KEY_INVALID`(`details.reason`) | false | — | 보이는 ASCII 1~256자 키로 다시 |
| 실행 전 저장소 응답 없음 | 503 | `IDEMPOTENCY_UNAVAILABLE` | true | — | 실행 안 됨. 같은 키로 나중에 |
| 실행 뒤 기록 실패(결과 불명) | 503 | `IDEMPOTENCY_COMPLETION_UNKNOWN` | true | — | 같은 키로 나중에. 새 키 금지 |
| 이전 효과 증명 불가 | 500 | `IDEMPOTENCY_RECOVERY_REQUIRED` | false | — | 업무 데이터로 확인 |
- CORS가 켜져 있으면 `Retry-After`·`X-Request-Id`·`X-Correlation-Id`·`traceparent` 등이 `Access-Control-Expose-Headers`에 있다(§3).
- 새 코드: `REQUEST_TIMEOUT`(503, retryable), web-advanced를 쓰는 서비스는 10종(3.3절 B-32).
- 프론트 계약 문서(`clean-architecture-frontend-template` `docs/architecture/backend-api-and-server-state-contract.md` §4.1·§6)는
`docs/web/http-contract.md`를 가리켜야 한다.
- 프론트 세션에 넘긴 인계 문서(세션 scratchpad라 지워질 수 있음):
`/tmp/claude-1000/-home-donghyeon-workspace-desktop-server-git-clean-architecture-frontend-template/4cfb2000-88f4-4501-87c2-64e07e1575a5/scratchpad/backend-contract-handoff.md`
## 8. 소유자 확인이 남은 결정
재리뷰 README 8절은 아래를 "소유자 확인이 필요한 결정"으로 남겼다. main에 합쳐지기 전에 바뀔 수 있다.
- 서블릿 오류 디스패치 허용(B-31), 데모 계정 허용 목록(B-27), V21을 V22 없이 직접 수정(4.2절), 발행·저장소 포트 시그니처 변경
(B-01·B-02), `IDEMPOTENCY_COMPLETION_UNKNOWN` 신설(B-30), prod `fixture-` 값 거부(B-14).
## 9. 확인 못 한 것
- 실제 파생 서비스(예: `tech-log-backend`) 코드에 이 안내를 적용해 보지 않았다. 각 줄이 그 서비스에 해당하는지는 서비스 쪽에서 확인한다.
- `APP_SECURITY_JWT_AUDIENCE` 누락·`app.security` 오타의 정확한 exit 코드와 메시지 전문(바인딩 예외로 감싸지는 경로).
- H2를 `bootRunH2` 밖에서 쓸 때의 정확한 오류(B-23).
- 같은 순서 키를 두 번 append할 때 나가는 오류 코드(5절 "순서 번호").
- 옛 버전 앱이 V20~V22가 적용된 DB에서 기동하는지(4.4절).
- gRPC ledger stream의 history 표 이름과 누가 적용하는지.
- 실제 CI runner에서의 workflow 실행(재리뷰 README 8절과 같음).