From 7ef8d0b4cbb2d5e4babf8b5679832d219f18806a Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Tue, 3 Nov 2026 20:30:39 +0900 Subject: [PATCH] =?UTF-8?q?docs(review):=20=EC=84=B1=EC=88=99=EB=8F=84=20?= =?UTF-8?q?=EB=A6=AC=EB=B7=B0=20=EC=88=98=EC=A0=95=EC=9D=98=20=EC=9E=AC?= =?UTF-8?q?=EB=A6=AC=EB=B7=B0=20=EA=B2=B0=EA=B3=BC=EB=A5=BC=20=EA=B8=B0?= =?UTF-8?q?=EB=A1=9D=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 2026-11-01 성숙도 리뷰 수정(커밋 3개)은 게이트를 통과했지만, 고친 코드 자체를 독립된 리뷰어가 다시 읽은 적이 없었다. 방법: requesting-code-review 템플릿으로 영역 리뷰어 6명과 보안 리뷰어 1명을 두고, 영역마다 스킬(clean-architecture, jpa-patterns, security-and-hardening 등)을 불러 그 기준으로 봤다. 의심 결함은 별도 worktree의 임시 테스트로 확인했다. README에 결과 종합과 수정에 필요한 결정을 적었다. 위험·한계: Critical 0, 회귀 0, 모든 영역 With fixes(Important 27건, 중복 제외 22건, Minor 41건). 원래 리뷰 색인이 06 영역 발견 5건 (NN-10~14)을 빠뜨려 "모든 발견 처리"가 틀렸음을 정정했다. 이 커밋은 기록만 담고, 수정은 다음 커밋들에서 한다. 검증: 문서만. 리뷰어별 실행 명령은 각 문서 "범위" 절. Refs: docs/reviews/2026-11-03-rereview/README.md --- .../01-core-application.md | 234 ++++++++++++++ .../02-inbound-transports.md | 298 ++++++++++++++++++ .../2026-11-03-rereview/03-persistence.md | 232 ++++++++++++++ .../04-outbound-capabilities.md | 210 ++++++++++++ .../2026-11-03-rereview/05-messaging.md | 252 +++++++++++++++ .../06-bootstrap-build-ci.md | 283 +++++++++++++++++ .../2026-11-03-rereview/07-security.md | 214 +++++++++++++ docs/reviews/2026-11-03-rereview/README.md | 69 ++++ 8 files changed, 1792 insertions(+) create mode 100644 docs/reviews/2026-11-03-rereview/01-core-application.md create mode 100644 docs/reviews/2026-11-03-rereview/02-inbound-transports.md create mode 100644 docs/reviews/2026-11-03-rereview/03-persistence.md create mode 100644 docs/reviews/2026-11-03-rereview/04-outbound-capabilities.md create mode 100644 docs/reviews/2026-11-03-rereview/05-messaging.md create mode 100644 docs/reviews/2026-11-03-rereview/06-bootstrap-build-ci.md create mode 100644 docs/reviews/2026-11-03-rereview/07-security.md create mode 100644 docs/reviews/2026-11-03-rereview/README.md diff --git a/docs/reviews/2026-11-03-rereview/01-core-application.md b/docs/reviews/2026-11-03-rereview/01-core-application.md new file mode 100644 index 00000000..8992e56d --- /dev/null +++ b/docs/reviews/2026-11-03-rereview/01-core-application.md @@ -0,0 +1,234 @@ +# 01 core·application·composition·매뉴얼 재리뷰 (2026-11-03) + +경로는 저장소 루트 기준이다. `src/`가 앞에 붙는다. + +## 범위 + +### 본 것 + +- 범위: `01a8a2a70..5786126c`(커밋 3개) 중 아래 pathspec. 365파일, +19,733 −3,474. + ```text + src/domain-core src/shared-contract src/application-core src/application-notification + src/application-fileserver src/application-objectstorage src/composition + scripts/new-feature.sh scripts/verify-feature-scaffold.sh scripts/feature-scaffold docs/manual + ``` +- 요구사항: `docs/reviews/2026-11-01-maturity-review/README.md` 2·12·13·14·15·16절과 + `01-core-and-feature-pattern.md`(완료 기준). +- 읽은 방식: diff가 커서 여러 번에 나눠 직접 읽었다. + 1. application-core main 전부(outbox·messaging.event·cache·operation·tenant·security·secret)와 testFixtures 계약 키트 전부. + 2. shared-contract main diff 전부와 README·CLAUDE.md 변경. + 3. 생성 명령(`new-feature.sh`, `verify-feature-scaffold.sh`)과 템플릿 29개 전부. + 4. 매뉴얼 13개 전부. 매뉴얼이 인용한 경로·클래스·규칙 이름이 실제로 있는지 스크립트로 전수 확인했다. + 5. application-notification main diff 전부. testFixtures는 계약 목록과 상속 관계 위주로 봤다. + 6. application-fileserver main diff 전부와 quota·move·cleanup 경로. 대응하는 persistence-fileserver 구현(`JpaFileQuota`, `JpaQuotaReclaim`)은 비교하려고 범위 밖에서 읽었다. + 7. composition: service-runtime(authorization·tracing), outbox-relay, durable-operation, fileserver-platform의 변경. +- 범위 밖에서 확인용으로 읽은 것: `ApplicationBoundaryArchitectureTest`(D4·`@SystemInvoked`), + `NamingConventionTest`·`TemplatePackageOwnership`, `DomainFeatureOnboardingContractTest`, `JpaOutboxStore.nextSequence`, + `JsonIntegrationEventEncoder`, `GlobalExceptionHandler`, sample `WorkLogRepositoryContract`·`WorkLogReservedPayload`, `docs/testing/TESTING_STRATEGY.md` 9절. + +### 불러온 스킬과 적용한 기준 + +| 스킬 | 적용한 기준 | 무엇을 봤나 | +| --- | --- | --- | +| `superpowers:requesting-code-review` | 리뷰어 템플릿(Strengths → Critical/Important/Minor → Declined → Assessment), 읽지 않은 코드에 판정 금지, 실제 심각도로 분류 | 문서 양식 전체 | +| `clean-architecture` | 의존 방향(안쪽만), 포트는 안쪽이 소유, 프레임워크는 바깥, composition root가 조립 | 생성 명령 출력의 계층별 의존, `@SystemInvoked`·권한 검사 위치, 계약 키트가 포트 소유 leaf에 있는지 | +| `domain-driven-design` | 불변식은 aggregate 안, 저장소 인터페이스는 domain, 유비쿼터스 언어 | 생성 aggregate·`*Repository`·오류 코드 위치, 이벤트 tenant 범위 규칙 | +| `codebase-design` | seam·adapter 용어, "어댑터 둘이면 진짜 seam", 인터페이스 = 호출자가 알아야 할 모든 것 | 포트 Javadoc이 약속한 것과 계약 키트가 실제로 검사하는 것의 차이, fake가 실제 adapter와 같은 interface를 지키는지 | + +### 실행한 명령과 결과 + +| 명령 | 결과 | +| --- | --- | +| `git diff --stat / --name-status 01a8a2a70..5786126c -- ` | 365파일. A 180, M 148, D 12, R 25 | +| `git worktree add /rr-01 5786126c` | 실험용. 끝나고 `git worktree remove --force`로 지웠다 | +| 변이 3개 적용 뒤 `flock … ./gradlew :application-core:test --tests TenantIdTest --tests IntegrationIdentityTest --tests InMemoryCacheRegionContractTest --continue` (load 17.4) | rc=1, 48건 중 2건 실패. M2(`TenantId` 문법에 `/` 허용) → `TenantIdTest [8] "acme/eu"` 실패(잡힘). M5(correlation 상한 128→200) → `IntegrationIdentityTest` 129자 거부 실패(잡힘). **M6(fake 캐시가 revision을 double로 비교) → 통과(살아남음)** | +| 워크트리에서 `scripts/new-feature.sh Invoice --no-format` 후, 호출자 트랜잭션을 요구하는 저장소로 생성 계약을 상속하는 실험 테스트 1개 추가, `flock … ./gradlew :domain-core:test --tests 'dev.caskeleton.domain.invoice.*'` (load 13.4) | rc=1, 18건 중 2건 실패: 실험 테스트의 `aSavedInvoiceIsFoundByItsId`, `savingTheSameIdAgainReplacesTheStoredState`. 생성된 테스트는 전부 통과 | +| 매뉴얼의 `` `src/…` `` `` `docs/…` `` 경로 존재 확인, 백틱 안 Java 식별자 109개 `git grep -w` | 없는 경로 0(glob 2개 제외), 없는 식별자 0(`V8_1` 파일명 접두어 제외) | + +### 못 본 것 + +- `:app-bootstrap:architectureTest`, 실 PostgreSQL·Redis lane은 돌리지 않았다. 게이트 결과(README 16.2)를 믿었다. +- application-notification test 디렉터리 약 60개 파일은 줄 단위로 다 읽지 않았다. 계약 상속 관계와 이름만 전수 확인했다. +- composition:notification-platform, service-runtime tracing(07-01)은 diff를 훑기만 했다. 07 영역 판단에 맡긴다. +- sample-portfolio는 범위 밖이다. 01-07·01-13·01-14 완료 기준에 필요한 줄만 읽었다. + +## Strengths + +- **트랜잭션 fake가 실제와 같은 규칙을 지킨다.** `DirectTransactionPort`가 롤백(`onRollback`), 참여 경계 실패 시 바깥 커밋 실패(doomed), 읽기 전용 표시를 갖는다(`application-core/src/testFixtures/java/dev/caskeleton/application/transaction/testkit/DirectTransactionPort.java:112-155`). 같은 `TransactionPortContract` 13건을 실 PostgreSQL의 `SpringTransactionContractTest`가 상속한다. 01-05의 핵심이 닫혔다. +- **encoder fake가 서버 조립 오류를 실제와 같은 예외로 거부한다.** `FakeIntegrationEventEncoder.java:55-73`이 미등록 계약·목적지·payload 타입을 `IllegalStateException`으로 거부하고, `IntegrationEventEncoderContract`를 `JsonIntegrationEventEncoder`와 함께 상속한다. 01-04 결함이 단위 테스트에서 보이게 됐다. +- **식별자 문법이 한 곳으로 모였다.** `IntegrationIdentity.java:17-31`이 문법과 상한 3개를 갖고 `EventId`·`IntegrationEventDraft`·`ValidatedIntegrationEvent`·`AggregateIdentity`가 쓴다. draft와 저장 이벤트의 correlation 상한이 128로 같아졌다. 변이 M5를 테스트가 잡는다(위 실행). +- **relay 정지가 claim을 돌려준다.** `PublishPendingOutboxEventsUseCase.java:124-128,143-155`의 `release`와 `OutboxStorePort.releaseLease`·`markDeferred`가 생겼고, `OutboxLeaseFencingContract.java:161-213`이 in-memory와 PostgreSQL 둘 다에 같은 경우를 건다. +- **05-01 수정이 정확하다.** 호출 전 행을 `undetermined()`로 쓴다(`application-notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/DeliveryAttemptFactory.java:55-60`). collapse 불가 검사도 attempt 행을 만들기 전으로 옮겼다(`NotificationDispatchService.java:186-194`). +- **권한 장치 부재를 기동에서 막는다.** `composition/service-runtime/.../authorization/PermissionEnforcementGuard.java:42-61`. 실제 web advisor의 pointcut이 class·method union이라(`MethodSecurityConfig.java:55-57`) `AopUtils.canApply` 판정과 맞는다. sample이 service-runtime과 web을 함께 띄워 실제 조합에서도 통과한다. +- **생성 명령이 이름 목록 대신 실제 패키지 존재로 거절한다.** `scripts/new-feature.sh:89-105`. 목록이 갈라질 여지를 없앴다. 왕복 검사가 실제 Gradle 게이트를 돌리고 결과 XML까지 본다(`scripts/verify-feature-scaffold.sh:86-108`). +- **패키지 소유 규칙이 양방향으로 검사된다.** `TemplatePackageOwnership` + 규칙 2개 + fixture 증명 테스트(`TemplatePackageOwnershipRuleTest`). 정본 표는 `application-core/CLAUDE.md:108-167` 한 곳이다. +- **LRO 계약이 하나가 됐다.** shared-contract `operation` 패키지를 지우고 이유를 README에 남겼다(`shared-contract/README.md:298-304`). +- **캐시 revision 순서가 포트 규칙이 됐다.** `CacheSourceRevisionOrder.java`가 길이→자리 비교로 2^53 이상도 맞게 비교하고, `CacheRecordMetadata`가 모든 provider에 같은 거부를 건다. + +## 발견 재확인 표 + +| ID | 상태 | 근거 | +| --- | --- | --- | +| 01-01 | 닫힘 | 배치 기준표 `docs/manual/03-placement.md:21-50`, 생성 명령, `verifyFeatureScaffold`(mainCheck). 생성 결과의 계약 설계 결함은 RR-01-01 | +| 01-02 | 닫힘 | fixture `CreateFeatureAggregateUseCase` non-final(`app-bootstrap/src/test/java/dev/caskeleton/onboarding/application/usecase/CreateFeatureAggregateUseCase.java:20`), `FeatureAggregateIdFactory extends IdFactory`. `DomainFeatureOnboardingContractTest.java:142-170`이 production ArchRule 전부(`RequiresPermissionProxyabilityTest` 포함)를 fixture에 적용. 변이는 직접 돌리지 않았다(E1) | +| 01-03 | 결정으로 닫힘 | experimental `TenantId` 삭제, `git ls-files '*/main/*TenantId.java'` = 정본 + notification 1개. notification 쪽은 결정 15절과 Javadoc(`application-notification/.../api/TenantId.java:4-15`), 쓰기는 `WritableTenant`가 정본 문법 강제. 변이 M2 이제 잡힘(E2) | +| 01-04 | 닫힘 | encoder의 미등록·목적지·타입 오류 → `IllegalStateException`(`adapter/outbound/support/.../JsonIntegrationEventEncoder.java:112-130`), web 400에 WARN 한 줄(`GlobalExceptionHandler.java:92-99`). 값 객체는 아직 IAE지만 WARN으로 흔적이 남는다. 매뉴얼 06장은 옛 동작을 적는다(RR-01-03) | +| 01-05 | 닫힘(application-core) | `TESTING_STRATEGY.md` 9.1 표의 포트 전부가 계약 키트와 fake·실제 상속을 가진다(직접 grep 확인). `implements TransactionPort`는 main 1 + testFixtures 2(`DirectTransactions`는 위임 래퍼). 남은 빈틈: RR-01-04(fileserver), RR-01-06(키트가 포트 약속을 다 안 봄) | +| 01-06 | 닫힘, 새 위험 있음 | 가드(`PermissionEnforcementGuard`) + relay `@SystemInvoked`. `@SystemInvoked`가 D4의 검사 없는 탈출구가 됐다(RR-01-02). 매뉴얼 07장이 "장치 없음"이라 적는다(RR-01-03) | +| 01-07 | 부분 | 문법 상수 하나 + M5 잡힘. 그러나 `sample-portfolio/.../application/worklog/WorkLogReservedPayload.java:8-9`에 같은 문법·160 상한 복사본이 남아 완료 기준("main에 한 번만")을 못 채운다(RR-01-08) | +| 01-08 | 닫힘 | `git grep shared.operation` 0건, README 기록 | +| 01-09 | 닫힘(코드), 재발 방지 없음 | `new IntegrationEventDraft<>(`가 main에서 `IntegrationEventDrafts.java:59` 한 곳. 하지만 그것을 지키는 규칙이 없고 매뉴얼은 "헬퍼 아직 없음, 기능마다 다시 쓴다"고 가르친다(RR-01-03) | +| 01-10 | 닫힘 | `outbound` 패키지 해체(`secret`, objectstorage `content.CallBudget`), 소유 표 + ArchUnit 2개 + 생성 명령 거절 | +| 01-11 | 결정으로 닫힘 | 템플릿 leaf 4곳 정본 사용, 출력 고정 테스트(`SafeFileFingerprintTest`, `ObjectIdentityDigestOutputTest`). 남은 직접 구현은 vendored `messaging:*`·`grpc*`뿐(grep) | +| 01-12 | 닫힘 | 이름 표 `application-core/CLAUDE.md:84-106`, `NamingConventionTest`가 그곳을 가리킴 | +| 01-13 | 닫힘(범위 밖 확인) | sample `UpdateWorkLogUseCase`에 소유자 검사(r2-09) | +| 01-14 | 닫힘 | README relay 설명 수정, 빈 패키지 3개 삭제, `*ValueTypesTest` 개명, `OutboxEventIdFactory`가 sample `application.event`로 이동, `TITLE_BLANK`→`WORKLOG_INVALID`(400) | +| 05-01 | 닫힘 | 위 Strengths | +| 05-07 (application 쪽) | 닫힘, 새 위험 있음 | copy가 admission·namespace 상한·예약을 거친다(`CopyFileApplicationUseCase.java:107-148`). move는 쿼터를 옮기지 않아 상한이 켜진 뒤 회계가 틀어진다(RR-01-05) | +| 04-02 (application 쪽) | 닫힘 | `ReconciliationJobStorePort.claimDue(limit, now, lease)`, `ReconciliationJob.claimFence`. fake·PG가 `ReconciliationJobStoreContract` 공유 | +| 06-01·06-03 (application 쪽) | 결정으로 닫힘 | `REJECTED_RETRYABLE`·`AMBIGUOUS`는 예산을 쓰지 않고 5분 상한 재시도(`PublishPendingOutboxEventsUseCase.java:181-193,236-260`, `OutboxBackoffPolicy.MAX_DELAY`). 결정 15절 | +| 06-02 | 닫힘 | `OutboxRelayScheduler`가 `SmartLifecycle`(phase MAX), 정지 요청 → 진행 중 발행 마무리 → 나머지 release(`OutboxRelayScheduler.java:72-170`). 경쟁 조건을 읽어 봤고 문제를 찾지 못했다 | +| 06-07 (application 쪽) | 닫힘 | `OutboxAggregateSequencePort` + `AggregateOrder.first()`, `ofOccurrence` 삭제. 계약 빈틈은 RR-01-06 | +| 02-01 (application 쪽) | 닫힘 | `OperationalError.IDEMPOTENT_IN_FLIGHT` retryable=true, 예외 Javadoc 갱신 | +| 05-02·05-03 (application 쪽) | 닫힘 | `CacheSourceRevisionOrder`, `CacheRecordMetadata` 검증. 계약에 2^53 이상 경우 없음(RR-01-06) | +| TEST-F-1 (application-core) | 닫힘 | 9.1 표 + 9.2 의도 표 | + +## Issues + +### Critical (Must Fix) + +없음. + +### Important (Should Fix) + +#### RR-01-01 생성 명령이 만든 저장소 계약은 매뉴얼대로 만든 실제 adapter가 상속할 수 없다 + +- **위치**: `scripts/feature-scaffold/templates/src/domain-core/src/testFixtures/java/dev/caskeleton/domain/__feature__/testkit/__Feature__RepositoryContract.java.tmpl:26,31,48,51` +- **무엇이 틀렸나**: 생성 계약은 `repository().save(...)`를 트랜잭션 없이 바로 부른다. 계약에 트랜잭션을 여는 자리(hook)가 없다. 그런데 매뉴얼 04장은 저장 adapter가 `CallerTransaction.require`로 호출자 트랜잭션을 요구하라고 가르친다(`docs/manual/04-persistence.md:15,66-72`). 그리고 그 adapter가 같은 계약을 상속하라고 한다(`04-persistence.md:30`, `08-testing.md:14`). 둘을 같이 지키면 계약 테스트가 실패한다. 생성 fake(`InMemory__Feature__Repository.java.tmpl:19`)도 트랜잭션을 보지 않아, 유스케이스가 `tx.inWrite` 밖에서 저장해도 fake 위 테스트는 통과한다. +- **왜 중요한가**: 이 매뉴얼은 "새 기능의 예시는 생성 명령 출력 하나"라고 정했다(`docs/manual/README.md:53-63`). 생성물이 "fake와 실제가 같은 계약을 통과한다"는 규칙의 견본인데, 실제 adapter를 붙이는 첫 순간 그 규칙을 지킬 수 없다. 개발자는 계약을 고치거나(정답), adapter에서 `require`를 빼거나(트랜잭션 밖 저장이 조용히 커밋되는 원래 결함), 계약 상속을 포기한다. 같은 저장소의 다른 키트는 이미 hook을 가진다: sample `WorkLogRepositoryContract.java:50` `inTransaction(Supplier)`, `IdempotencyStoreContract.java:70`. +- **발생 조건**: 생성된 기능에 매뉴얼 04장대로 JPA adapter를 붙이고 계약을 상속한다. 모든 파생 기능이 지나는 경로다. +- **고치는 법**: 템플릿 계약에 `protected T inTransaction(Supplier work) { return work.get(); }`를 두고 모든 호출을 거치게 한다. domain-core는 `TransactionPort`를 볼 수 없으니 sample처럼 `Supplier` hook이면 된다. fake 쪽은 "트랜잭션 밖 save 거부"를 계약 경우로 넣을지 정한다(넣으려면 fake가 트랜잭션 표시를 받아야 한다). +- **심각도·우선순위**: Medium / P2. 런타임 결함은 아니다. 템플릿이 복제시키는 테스트 설계 결함이다. +- **증거**: E2. 워크트리에서 `Invoice`를 생성하고 호출자 트랜잭션을 요구하는 저장소로 생성 계약을 상속했다. `:domain-core:test` 18건 중 그 2건이 "requires an active caller transaction"으로 실패했다(트랜잭션 없이도 되는 `findById` 경우만 통과). + +#### RR-01-02 `@SystemInvoked`가 D4 권한 규칙의 검사 없는 탈출구다 + +- **위치**: `app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ApplicationBoundaryArchitectureTest.java:558-560`, `application-core/src/main/java/dev/caskeleton/application/security/SystemInvoked.java:19-20`, `composition/service-runtime/.../authorization/PermissionEnforcementGuard.java:50` +- **무엇이 틀렸나**: D4는 쓰기 유스케이스에 `@RequiresPermission`을 강제한다. `@SystemInvoked`가 붙으면 바로 `return`해 면제한다. 면제의 전제는 "bean이 아니고 전송에서 닿지 않는다"인데 이것은 Javadoc 문장뿐이다. ArchUnit에 "inbound adapter는 `@SystemInvoked` 클래스에 의존하지 않는다" 규칙이 없다. 기동 가드는 `@RequiresPermission`만 보므로 `@SystemInvoked` bean을 그냥 지나간다. AGENTS.md와 매뉴얼 07장은 이 표시를 언급하지 않는다. +- **왜 중요한가**: 쓰기 유스케이스에 `@SystemInvoked(reason = "…")` 한 줄을 붙이고 `@Bean`으로 등록해 컨트롤러가 부르면, 권한 검사 없이 실행된다. 빌드·기동·테스트 어디서도 실패하지 않는다. 01-06이 막으려던 "조용한 인가 우회"를 다른 문으로 다시 연다. 사용자 원칙 "위험은 코드에 드러나야 한다"에 걸린다. +- **발생 조건**: 개발자가 D4 실패를 끄려고 이 표시를 쓴다. 이름이 시스템 호출용으로 보여 막을 단서가 리뷰뿐이다. +- **고치는 법**: (a) ArchUnit: `..adapter.inbound..`·`..bootstrap..`의 어떤 클래스도 `@SystemInvoked` 클래스에 의존하지 않는다(composition만 허용). (b) `PermissionEnforcementGuard`에 "`@SystemInvoked` 타입의 bean이 있으면 기동 실패"를 더한다. 둘 다 작다. (b)는 relay가 bean이 아닌 현재 구조와 맞는다. +- **심각도·우선순위**: Medium / P2. 기본 조립에는 해당 bean이 없다. 생기면 권한 우회다. +- **증거**: E1. 규칙 조건 코드와 가드 조건을 읽었다. 우회 조립을 띄워 보지는 않았다. + +#### RR-01-03 매뉴얼이 이번 수정 뒤의 코드와 반대로 말하는 곳이 세 군데 있고, 01-09의 헬퍼를 지키는 장치가 없다 + +- **위치와 내용**: + - `docs/manual/07-authorization.md:65-68` "web이 빠진 조립에서는 … 기동을 막는 장치는 아직 없다(리뷰 01-06)". 실제로는 `PermissionEnforcementGuard`가 있다. 같은 커밋 `1400dc15`에서 서로 다른 묶음이 만들었다. + - `docs/manual/09-outbox-events.md:59-60` "이 규칙은 아직 기능마다 다시 쓴다 … application-core 헬퍼로 올리는 일은 리뷰 01-09 후속이다". 실제로는 `IntegrationEventDrafts`가 있고 sample과 durable operation이 쓴다. 매뉴얼은 그 이름을 한 번도 쓰지 않는다. `application-core/CLAUDE.md` 이벤트 타입 표(:72-74)와 README에도 없다. + - `docs/manual/09-outbox-events.md:63-65` relay를 bean으로 만들지 않는 이유를 "권한 프록시가 매번 거부한다"로 적는다. 지금 relay는 `@SystemInvoked`라 권한 선언이 없다. bean이 되면 거부가 아니라 **검사 없이** 열린다(RR-01-02). 이유가 바뀌었다. + - `docs/manual/06-errors.md:44-45` "web은 그것을 로그 없이 400으로 바꿔서". 지금은 WARN 한 줄을 남긴다(`GlobalExceptionHandler.java:97`). +- **왜 중요한가**: 매뉴얼은 새 기능 작성자가 처음 읽는 문서이고 "매뉴얼과 정본이 다르면 정본이 맞다"는 규칙만으로는 독자가 차이를 알 수 없다. 특히 09장대로 하면 다음 기능이 `new IntegrationEventDraft<>(…)`를 직접 조립한다. 그것을 막는 규칙이 없으니 01-09가 고친 "기능마다 tenant·순서·correlation 규칙 재정의"가 그대로 돌아온다. 경로·식별자 전수 검사는 통과하므로(위 실행) 이 종류의 drift는 기계 검사로 안 잡힌다. +- **고치는 법**: 네 문장을 고친다. 09장 "event id·correlation·순서" 절을 `IntegrationEventDrafts.draft(…)` 사용으로 바꾸고 `SINGLE_TENANT_SCOPE`·`IntegrationIdentity`를 소개한다. `application-core/CLAUDE.md` 표에 두 타입을 넣는다. ArchUnit 한 줄: `IntegrationEventDraft` 생성자 호출은 `IntegrationEventDrafts`(와 테스트)에서만. +- **심각도·우선순위**: Medium / P2. 문서 불일치가 반복 결함(01-09)을 되살리는 경로라 Low보다 높게 본다. +- **증거**: E1. 해당 줄과 코드를 대조했다. `git grep -l IntegrationEventDrafts -- src docs` = main 2·sample 1·test 1, docs 0. + +#### RR-01-04 application-fileserver: 저장 포트 9개 중 7개는 공유 계약이 없고, 쿼터 fake는 실제와 다르게 답한다 + +- **위치**: `application-fileserver/build.gradle:12-17`, `application-fileserver/src/testFixtures/java/dev/caskeleton/application/fileserver/testkit/FakeFileQuotaService.java:17-20,43,57,63`, `adapter/outbound/persistence-fileserver/.../JpaFileQuota.java:62,74,91`, `docs/testing/TESTING_STRATEGY.md:192-193` +- **무엇이 틀렸나**: persistence-fileserver가 구현하는 포트는 9개다(`CleanupQueuePort`, `ContentReferenceLedgerPort`, `FileMetadataPort`, `FileQuotaPort`, `QuotaCommitPort`, `QuotaReclaimPort`, `RecoveryQueuePort`, `StagingUploadLocatorPort`, `UploadSessionPort`). 계약 키트는 `FileMetadataPortContract`, `CleanupQueuePortContract` 둘뿐이다. 나머지는 fake가 testFixtures로 옮겨졌을 뿐 계약이 없다. 그런데 build.gradle 주석은 "fake 위에서 통과한 유스케이스 테스트는 persistence-fileserver JPA adapter가 지키는 동작에 대해 통과한 것"이라 적고, TESTING_STRATEGY 9절은 fileserver 포트를 `*PortContract`가 "맡는다"고 적는다. 실제로 갈라진 예: `FakeFileQuotaService`는 Javadoc에 "durable adapter와 같은 장부"라 쓰지만 (1) 시계가 없어 만료된 예약도 `usedBytes`에 센다(실제는 `sumReservedBytes(…, now)`로 뺀다), (2) 해제된 예약의 `commit`·`extend`를 조용히 받는다(실제는 `QUOTA_EXCEEDED`로 거부). +- **왜 중요한가**: 05-07 수정으로 namespace 상한이 `usedBytes` 비교로 실제 거부를 하게 됐다. 그 판정에 쓰는 포트가 fake와 실제 사이에 묶여 있지 않다. 유스케이스 테스트가 녹색이어도 실제 상한 동작을 말해 주지 않는다. AGENTS.md 테스트 규칙 6과 capability 기준 5가 정확히 이것을 막으려는 규칙이다. +- **발생 조건**: fileserver 유스케이스를 고치거나 쿼터 규칙을 바꾸고 fake 위 테스트로 검증한다. +- **고치는 법**: 최소 `FileQuotaPortContract`(예약·연장·확정·해제·만료·`usedBytes`)를 만들어 fake와 `PostgreSqlFileserver…IntegrationTest`가 상속한다. fake에 `Clock`을 준다. 나머지 6개는 9.2처럼 "계약 없음, 이유" 표를 두거나 계약을 만든다. build.gradle 주석과 9절 문장을 사실대로 고친다. +- **심각도·우선순위**: Medium / P2. +- **증거**: E1. 두 구현을 나란히 읽었다. fake를 실 PG 테스트에 걸어 보지는 않았다. + +#### RR-01-05 파일 이동이 쿼터를 옮기지 않아, 상한을 켠 배포에서 namespace 사용량이 양쪽으로 틀어진다 + +- **위치**: `application-fileserver/src/main/java/dev/caskeleton/application/fileserver/lifecycle/MoveFileApplicationUseCase.java:53-60`, `cleanup/DefaultCleanupService.java:311`, `adapter/outbound/persistence-fileserver/.../JpaQuotaReclaim.java:41-58`, `application-fileserver/.../quota/NamespaceQuota.java:19-25` +- **무엇이 틀렸나**: copy는 대상 namespace에 예약·확정한다. move는 `metadataStore.relocate`만 하고 쿼터를 건드리지 않는다. 확정 사용량은 namespace별 예약 행의 합이라(`JpaFileQuota.committedBytes`) 파일이 B로 가도 사용량은 A에 남는다. 나중에 그 파일을 지우면 정리 서비스가 **현재** namespace B에서 회수한다. `JpaQuotaReclaim`은 B의 행에서 빼다가 모자라면 나머지를 버린다(바닥 0). +- **왜 중요한가**: 결과는 세 가지다. B는 move로 상한을 검사 없이 넘는다. A는 없는 파일의 사용량을 영원히 들고 있어 언젠가 정상 업로드가 `QUOTA_EXCEEDED`가 된다. B의 장부는 다른 파일의 확정분까지 깎여 과소 집계된다. 05-07 이전에는 쿼터가 "기록만" 해서 틀려도 피해가 없었다. 결정 15절이 상한을 실제로 강제하게 만들면서 이 차이에 이빨이 생겼다. `NamespaceQuota`의 "Known limit"은 동시 예약 초과만 적고 move는 적지 않았다. +- **발생 조건**: `APP_FILESERVER_PLATFORM_TARGET_NAMESPACES`로 namespace를 둘 이상 열고 `APP_FILESERVER_PLATFORM_QUOTA_NAMESPACE_LIMIT`을 설정한 배포에서 move를 쓴다. 기본값(대상 = 기본 namespace 하나, 상한 없음)에서는 생기지 않는다. +- **고치는 법**: move를 한 트랜잭션 안에서 "B에 `requireRoom` + 예약·확정, A에서 같은 바이트 회수"로 바꾼다. 또는 상한이 설정된 동안 namespace를 바꾸는 move를 거부하고 그 사실을 `NamespaceQuota` Javadoc과 `fileserver.yml` 주석에 적는다. 어느 쪽이든 "move 뒤 A·B `usedBytes`" 단언을 계약 테스트에 넣는다(RR-01-04와 함께). +- **심각도·우선순위**: Medium / P2. 데이터(쿼터 장부)가 조용히 틀어지지만 설정 두 개를 켠 배포에서만 생긴다. +- **증거**: E1. 코드 경로를 읽었다. 실행 재현은 하지 않았다. + +### Minor (Nice to Have) + +#### RR-01-06 계약 키트가 포트 Javadoc의 약속을 다 검사하지 않는다 + +- **위치·내용**: + - `application-core/src/main/java/dev/caskeleton/application/cache/CacheSourceRevisionOrder.java:13-18`은 "float 파싱은 2^53 위를 구분 못 한다"며 공유 `CacheRegionContract`가 Redis Lua 복사본을 맞춰 준다고 적는다. 계약의 숫자 순서 경우는 `9` 대 `10`뿐이다(`CacheRegionContract.java:168-180`). **변이 M6(fake가 revision을 `Double.parseDouble`로 비교)이 `InMemoryCacheRegionContractTest`를 통과했다(E2).** Lua가 `tonumber`로 바뀌어도 계약은 못 잡는다(현재 Lua는 문자열 비교로 맞다). + - `OutboxAggregateSequencePort.java:17-28`은 "계약이 모든 구현을 세 항목에 묶는다"고 적는다. 계약(`OutboxAggregateSequenceContract`)은 증가·독립 두 경우만 본다. "호출자 쓰기 트랜잭션 안에서만"과 "롤백된 번호는 다시 준다"는 없다. fake(`InMemoryOutboxAggregateSequences.java:14-16`)는 트랜잭션 밖 호출을 받고 롤백된 번호를 건너뛴다. JPA는 트랜잭션 밖을 거부한다(`JpaOutboxStore.java:116`). + - `IdempotencyStoreContract.java:89,340-357`의 시간 경우는 fake에서 `elapse`가 no-op이라 공짜로 통과한다. 문서에 적혀 있지만, fake 위 유스케이스 테스트는 lease 만료·넘겨받기를 영영 볼 수 없다. +- **고치는 법**: 계약에 `"9007199254740993"` 대 `"9007199254740992"` 경우, 트랜잭션 밖 `nextSequence` 거부 경우를 넣는다. 시간 경우는 fake에 시계를 주거나 `assumeTrue(hasClock())`로 건너뜀을 드러낸다. 포트 Javadoc의 "계약이 묶는다" 문장을 계약 범위에 맞춘다. +- **심각도·우선순위**: Low / P3. **증거**: E2(M6), 나머지 E1. + +#### RR-01-07 생성된 `Config`가 `TransactionPort` 공급 자동 설정 순서를 적지 않는다 + +- **위치**: `scripts/feature-scaffold/templates/src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/__feature__/__Feature__Config.java.tmpl:30-32` +- **내용**: `@ConditionalOnBean({Repository, TransactionPort})`인데 `afterName`이 없다. `TransactionPort`는 `PersistenceJpaAutoConfiguration`이 만든다. 지금은 클래스 이름 알파벳 순서(`dev.caskeleton.adapter…` < `dev.caskeleton.bootstrap…`)로 우연히 먼저 처리된다. 같은 모양의 `DurableOperationAutoConfiguration.java:42-44`는 이름을 적었고, 매뉴얼 02장(:124)도 "안 적으면 조건이 그 bean을 못 본다"고 한다. 기능이 조용히 없어지는 실패라 찾기 어렵다. +- **고치는 법**: 템플릿에 `@AutoConfiguration(afterName = "dev.caskeleton.adapter.outbound.persistence.autoconfigure.PersistenceJpaAutoConfiguration")`. 저장 adapter의 자동 설정 이름은 주석 안내대로 사람이 더한다. +- **심각도·우선순위**: Low / P3. **증거**: E1. + +#### RR-01-08 01-07 잔여 복사본 + +- **위치**: `sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/application/worklog/WorkLogReservedPayload.java:8-9` +- **내용**: `[A-Za-z0-9][A-Za-z0-9._:-]*`와 160 상한을 직접 갖는다. 같은 값이 `IntegrationIdentity.GRAMMAR`·`AGGREGATE_ID_MAX_LENGTH`다. 원래 리뷰의 다섯 곳 목록에 없던 여섯 번째 복사본이다. +- **고치는 법**: `IntegrationIdentity.isCanonical(workLogId, AGGREGATE_ID_MAX_LENGTH)`. +- **심각도·우선순위**: Low / P3. **증거**: E1(grep). + +#### RR-01-09 이번에 고친 문서 옆에 남은 옛 서술 + +- **내용**: 같은 파일을 이번 범위에서 고치면서 01 영역 문서 2절의 "남음" 항목을 그대로 두었다. + - `shared-contract/README.md:369` "1001번째 tenant부터 bucket folding이 자동 적용된다" — 구현 없음(A-5a). + - `shared-contract/src/main/java/dev/caskeleton/shared/runtime/RuntimeEnvironment.java:33` "app-bootstrap's RuntimeProfileSnapshot" — 실제는 support leaf(A-2d). + - `application-core/README.md:531-560` "알림 포트" 절이 application-notification의 `NotificationPort`를 설명하고, 그 아래 "Notification (값 객체)" 절 본문은 가명화 포트 설명이 섞여 있다(A-6a). +- **심각도·우선순위**: Low / P3. **증거**: E1. + +#### RR-01-10 왕복 검사가 생성 테스트 8개 중 4개만 "실행됨"을 확인한다 + +- **위치**: `scripts/verify-feature-scaffold.sh:96-101` +- **내용**: `Test`, `CreateUseCaseTest`, `ControllerTest`, `ConfigTest`의 결과 XML만 확인한다. `IdTest`, `InMemoryRepositoryContractTest`, `GetUseCaseTest`, `UuidIdFactoryTest`는 필터·태그 변경으로 실행되지 않아도 녹색이다. 스크립트 머리말이 막겠다고 한 "빈 녹색"이 절반 남는다. +- **고치는 법**: 템플릿의 `src/test/**/*Test.java.tmpl` 목록에서 기대 XML을 만들어 전부 확인한다. +- **심각도·우선순위**: Low / P3. **증거**: E1. + +## Declined to judge + +- SMTP provider adapter가 `ProviderAdapterContract`("every stable provider adapter")를 상속하지 않는 것 — 계약이 HTTP 모양이고 05 영역 판단이다. 파일 이동만 이번 범위다. +- `JpaOutboxStore`의 첫 counter 생성 경쟁(두 생성자가 PK 충돌) — persistence-jpa, 04·06 영역. +- `TracingSwitchImportFilter`가 Boot 4의 모든 tracing 자동 설정을 패키지 접두어로 덮는지 — 07 영역. +- `TemplatePackageOwnershipRuleTest`가 "목록 ⊆ 실제"만 보고 반대 방향은 안 보는 것 — 새 템플릿 패키지를 목록에 안 넣으면 기능으로 분류되지만, 다른 템플릿 패키지가 import하면 규칙 2가 잡고 생성 명령은 디스크로 거절한다. 피해가 작아 제외. +- durable operation 이벤트가 tenant가 있어도 `global` 범위로 나가는 것 — 코드 주석에 이유와 결정이 있다(`SubmitDurableOperationUseCase.java:145-147`). +- namespace 상한의 동시 예약 초과 — 결정 15절, `NamespaceQuota` Javadoc에 명시. +- relay가 진짜 인증 오류도 5분 간격으로 무한 재시도 — 결정 15절. +- 서버가 만드는 값 객체(`ValidatedIntegrationEvent` 등)가 아직 IAE를 던지는 것 — WARN 로그로 흔적이 남아 01-04 목적은 달성. 따로 올리지 않는다. +- `OutboxMetrics.refreshGauges`가 relay tick(최대 50 cycle)과 같은 스케줄러 스레드를 나눠 gauge 갱신이 늦을 수 있는 것 — 측정하지 않았다. +- sample `POSTER_INVALID_STATE`가 상태 전이 위반을 400으로 내는 것 — sample, 범위 밖. + +## 28개 관점 — 바뀐 관점만 + +01 영역 문서 8절 판정표 대비. 기호: O 충족, P 부분, X 미충족. + +| # | 관점 | 이전 | 지금 | 한 줄 이유 | +| --- | --- | --- | --- | --- | +| 2 | 구조적 성숙도 | P | O | 배치 기준표와 패키지 소유 규칙이 생기고 ArchUnit·생성 명령이 강제한다 | +| 3 | 변경 용이성 | P | O | 식별자 문법·draft 규칙이 한 곳. 남은 sample 복사본 1곳(RR-01-08)은 Low | +| 6 | 실패 성숙도 | P | O | 서버 조립 오류가 500+로그, relay 일시 거부가 DEAD 대신 재시도 | +| 8 | 디버깅 가능성 | P | O | IAE 400에도 WARN 한 줄 | +| 11 | 데이터 성숙도 | P | P | 이유가 바뀜: 이벤트 tenant 규칙은 하나가 됐고, 새로 move 쿼터 장부 drift(RR-01-05) | +| 17 | API·계약 성숙도 | P | O | LRO 계약 한 벌, Envelope null 생략 | +| 20 | 개발자 경험 | X | P | 매뉴얼·생성 명령·왕복 검사가 생겼다. 생성 계약이 실제 adapter를 못 받고(RR-01-01) 매뉴얼 일부가 코드와 반대(RR-01-03) | +| 22 | 추상화 성숙도 | P | O | `IntegrationEventDrafts`로 10필드 생성자를 직접 다루지 않는다 | +| 23 | 일관성 | X | P | TenantId·LRO·문법·이름 규칙이 정리됐다. 매뉴얼과 코드 불일치, sample 복사본이 남았다 | +| 24 | 네이밍·의미 | P | O | 이름 규칙 정본 표, `*ValueTypesTest` 개명, 예외는 "따라 하지 말 것"으로 명시 | +| 25 | 조직 확장성 | P | O | 기능 패키지가 템플릿 패키지와 섞이지 않게 생성 명령과 ArchUnit이 막는다 | +| 27 | 삭제 가능성 | P | O | sample 전용 LRO 타입이 sample로 내려갔다 | + +10 테스트·15 보안·21 Guardrail은 기호가 그대로 P다. 키트가 크게 늘었지만 RR-01-01·02·04·06이 남는다. + +## Assessment + +**Ready to merge?** With fixes + +**Reasoning:** 01 영역 발견 14건 중 12건이 닫히거나 결정으로 닫혔고, Critical·회귀는 없다. 다만 이번 수정이 새로 만든 탈출구(`@SystemInvoked`, RR-01-02)와, 따라 할 예시인 생성 계약이 실제 adapter를 못 받는 문제(RR-01-01), 매뉴얼이 고친 코드와 반대로 말하는 곳(RR-01-03)은 파생 서비스로 그대로 복제되므로 병합 전에 고치는 편이 싸다. diff --git a/docs/reviews/2026-11-03-rereview/02-inbound-transports.md b/docs/reviews/2026-11-03-rereview/02-inbound-transports.md new file mode 100644 index 00000000..89b92c7e --- /dev/null +++ b/docs/reviews/2026-11-03-rereview/02-inbound-transports.md @@ -0,0 +1,298 @@ +# 02 inbound 전송(HTTP·GraphQL·WebSocket·gRPC) 재리뷰 (2026-11-03) + +리뷰 대상: Base `01a8a2a70` → Head `5786126c`, 영역 번호 02(slug `inbound-transports`). 원래 영역 문서는 +`docs/reviews/2026-11-01-maturity-review/02-inbound-web.md`, `03-inbound-realtime-graphql-grpc.md`다. + +## 범위 — 본 pathspec, 불러온 스킬과 적용한 기준, 실행한 명령과 결과, 못 본 것 + +### 본 pathspec + +```text +src/adapter/inbound src/grpc src/grpc-advanced docs/web +docs/architecture/graphql-api-surface.txt docs/runbooks/grpc-platform-operations.md +docs/adr/ADR-GRPC-004-retry-ownership-and-durable-idempotency.md +``` + +`git diff --stat` 기준 188파일 +9,378 −614. 여러 번에 나눠 직접 읽었다(하위 에이전트 없음). + +- 꼼꼼히 읽은 것: web main 전체 diff(인증·CORS·Envelope·오류 핸들러·멱등 키·rate limit·설정), + `docs/web/http-contract.md` 전문, web README·runbook diff, web-advanced 오류 enum, web-fileserver CORS 기여, + GraphQL 복잡도 scorer·calculator·deadline·per-parent instrumentation·interceptor 전문, WebSocket writer·handler· + STOMP 연결 상한·구독 상한 전문, gRPC 어댑터 admission·deadline interceptor·runner·settings 전문, gRPC ledger + port·JPA adapter·repository·entity·V002·interceptor·retention·starter 전문, ADR-GRPC-004·runbook diff. +- 경로만 따라간 것: pathspec 밖이지만 판단에 필요한 `IdempotencyExecutor`(application-core), + `OperationalError`·`Envelope` 계열(shared-contract), `docs/registries/error-codes.yaml`, `security.yml`, + `IdempotencySettings`(composition:idempotency), spring-graphql 2.0.5 jar의 `BlockingHandlerMethodPredicate`(javap). +- 훑기만 한 것: `src/adapter/inbound/messaging`(새 leaf, 06 영역 소관), web-notification 콜백 503(05-20), + web-fileserver tus PATCH(05-12). 이 셋은 「Declined to judge」에 적었다. + +### 불러온 스킬과 적용한 기준 + +| 스킬 | 적용한 기준 | 무엇을 봤나 | +| --- | --- | --- | +| `superpowers:requesting-code-review` | 리뷰어 템플릿 — 계획 정렬(README 12~16절·영역 문서 완료 기준), 코드 품질, 아키텍처, 「Declined to judge」, 읽기 전용, 하위 에이전트 금지 | 발견마다 완료 기준을 코드로 대조, 수정 diff 자체의 결함 탐색 | +| `api-and-interface-design` | 한 가지 오류 모양(Consistent Error Semantics), Hyrum's Law(관찰되는 wire 변화는 계약), Idempotency-Key 절(원자적 claim, 처리 중 중복에 대한 의도된 응답 409, 다른 본문 422, 결과 불명 3분류, 보존 기간 ≥ 재시도 경로) | `http-contract.md`와 실제 응답 대조(Tomcat 실행), 409/422/Retry-After, gRPC ledger claim·takeover·commit·purge 경쟁 | +| `security-and-hardening` | STRIDE의 DoS(입력 크기·복잡도·연결 수 상한, timeout), CORS는 명시 목록, 인증/인가(JWT aud·role 범위), 오류 본문이 입력을 되돌려 쓰지 않음 | GraphQL 복잡도 우회, WebSocket·gRPC 한도와 종료, CORS 노출 헤더, JWT audience 필수·client role 범위, `/error` 본문의 path echo | + +### 실행한 명령과 결과 + +모두 `git worktree add /rr-02 5786126c`로 만든 worktree에서 `flock heavy.lock`으로 감싸 돌렸다. +끝난 뒤 `git worktree remove --force`로 지웠다. 임시 테스트 원본은 scratchpad `rr-02-notes/probes/`에 남겼다. +메인 체크아웃에는 이 문서 말고 바꾼 파일이 없다. + +| 명령 | 실행 직전 load | 결과 | +| --- | --- | --- | +| `git diff --stat / git diff 01a8a2a70..5786126c -- ` | — | 188파일 | +| `./gradlew :adapter:inbound:graphql:test --tests '*Rr02UnionProbeTest'` (임시 테스트) | 6.14 | rc=0. `plainNested score=3368410`, `unionNested score=20`, `unionSingleNested score=20`, `unionPageOverMax score=20`(거부 안 됨), `unionFragmentSpread score=20`, `plainPageOverMax rejected=page size exceeds maximum` → RR-02-01 | +| `./gradlew :adapter:inbound:web:test --tests '*Rr02ErrorDispatchProbeTest'` (임시 테스트, 실제 Tomcat) | 17.95 | rc=0. `GET /probe/item;x=1` → `400 {"success":true,"data":{"timestamp":…,"status":400,"error":"Bad Request","path":"/probe/item;x=1"},"meta":{…}}` → RR-02-02. 대조군 `/probe/item` 200 정상 Envelope, `/probe/missing` 404 `ROUTE_NOT_FOUND` 실패 Envelope | +| `./gradlew -p optional-platforms :grpc:grpc-core-api:test --tests '*Rr02StaleOwnerProbeTest'` (임시 테스트, 공유 계약 fake) | 22.27 | rc=0. `bTookOver=true staleOwnerMarkFailed=accepted state=FAILED_TERMINAL cReclaimed=true` → RR-02-04 | +| `javap` spring-graphql 2.0.5 `AnnotatedControllerDetectionSupport$BlockingHandlerMethodPredicate` | — | `CompletableFuture`를 돌려주는 resolver는 blocking으로 보지 않아 호출 스레드에서 돈다. per-parent instrumentation이 README 예시를 N+1로 오인하지 않는다(문제 없음 확인) | + +게이트(ci·mainCheck·integrationCheck·optional·performanceCheck·releaseCheck)는 README 16.2대로 이미 통과했고 +다시 돌리지 않았다. + +### 못 본 것 + +- 짝 프론트를 실제로 붙여 실행하지 않았다(프론트 분류기·strict 스키마의 반응은 판단하지 않음). +- 기본 JWT 체인에서 `/error` 디스패치가 401로 바뀌는지는 코드로 추론만 했다(실행은 permit-all 체인으로 함). +- gRPC ledger의 동시 commit 경쟁은 실 PostgreSQL로 재현하지 않았다(순차 경로만 fake로 실행). +- Jetty·nginx WebSocket lane, gRPC Netty·fault lane, GraphQL systemTest는 다시 돌리지 않았다. + +## Strengths + +- **wire 모양을 원문 키로 단언한다.** `EnvelopeWireShapeTest.java:36-41,186-189`가 `doesNotExist`(null도 통과) 대신 + 응답 원문의 키 집합을 비교한다. 02-02가 숨어 있던 바로 그 맹점을 막는다. Boot `JsonMapper`를 쓰는 + `@WebMvcTest`라 mix-in 등록 경로까지 함께 검증한다. +- **JWT audience가 두 겹으로 닫혀 있다.** `SecuritySettings.java:62`(기동 거부), `JwtDecoderConfig.java:78`(검증기 + 조립 거부), 미해결 `${…}` 자리표시자를 값으로 쓰지 않는 `SecuritySettings.java:87`. role은 audience client만 + 읽는다(`JwtToAuthenticatedPrincipalConverter.java:94`). 다른 client role 무시 테스트가 있다. +- **컨버터 밖 거부 응답의 writer가 하나다.** `EnvelopeResponseWriter.java:34-41`. Tomcat 기본 문자셋을 흉내 낸 + `RateLimitInterceptorTest`의 `ContainerDefaultCharsetResponse`가 02-04를 실제로 다시 잡는다(mock의 관대함에 기대지 않음). +- **gRPC 과부하 거부가 "정상 close"다.** `GrpcCallAdmission.java:65-118`이 executor 선택 단계에서 permit을 정하고, + 거부된 호출은 handler 없이 `RESOURCE_EXHAUSTED`로 닫으며, permit은 `onComplete`/`onCancel`에서 한 번만 돌려준다. + bounded pool reject가 스트림을 매달아 두는 io.grpc 동작을 정확히 피했다. 서버 deadline close도 + `GrpcServerDeadlineInterceptor.java:94-144`에서 직렬화했다. +- **WebSocket 경쟁 두 건을 같은 lock 아래 재확인으로 닫았다.** `SerializedOutboundWriter.java:107`(close 뒤 offer + 예약 금지), `PlatformWebSocketHandler.java:93-124`(stop 전후 연결 1001), 큐 거부 시 구독 슬롯 반환 + `WebSocketInboundAuthorizationInterceptor.java:78`. +- **ledger 회수·정리가 SQL 한 문장씩이다.** `GrpcOperationLedgerRepository.java:106-156` — takeover는 조건부 UPDATE, + purge는 `FOR UPDATE SKIP LOCKED` 부분 질의 + 바깥 `state <> 'IN_PROGRESS'` 이중 조건, V002 부분 인덱스. +- **GraphQL deadline이 값 하나다.** `GraphQlPlatformWebInterceptor.java:132-138`이 요청 context의 deadline으로 + timer를 걸고, 실행 스레드 모델별 한계를 테스트 두 개로 고정했다(README 「요청 deadline」). +- **복잡도 scorer가 변수 기본값·포화 산술을 다룬다.** `GraphQlDocumentComplexityScorer.java:385-405`, + `GraphQlComplexityCalculator.java:148`. 03-01 완료 기준의 네 쿼리는 모두 고쳐졌다. + +## 발견 재확인 표 + +| ID | 상태 | 근거 | +| --- | --- | --- | +| 02-01 | 닫힘(백엔드) | `OperationalError.java:47` retryable=true, `RetryAfterAdvisor.java:19` 2초, `http-contract.md:73`, `runbook.md:41-44`, `error-codes.yaml:402-408`이 같은 문장. 짝 프론트 §6 반영은 15절 결정대로 프론트 세션 인계. 단 같은 표의 503 행이 거짓 → RR-02-03 | +| 02-02 | 닫힘(MVC 경로) | `EnvelopeWireFormatConfig.java:33-38` mix-in, `EnvelopeWireShapeTest`. MVC 밖 `/error` 디스패치는 여전히 `success:true`+`data` → RR-02-02로 따로 | +| 02-03 | 닫힘 | 위 Strengths 두 번째 항목. `.env.example:97` 빈 값은 기동 실패(15절 결정대로) | +| 02-04 | 닫힘 | `EnvelopeResponseWriter.java:34-41`, `RateLimitInterceptor` reject가 이를 씀 | +| 02-05 | 닫힘 | `CorsExposedHeaders.PLATFORM`, `SecurityConfig` 합집합, `FileserverHttpSurfaceConfiguration` 기여 bean, `CorsSecurityFilterIntegrationTest` 2건 | +| 02-06 | 닫힘 | `EnvelopeBodyAdvice.java:77-80`(String 컨버터면 같은 mapper로 직렬화), `EnvelopeBodyAdviceTest` 3건 | +| 02-07 | 닫힘 | `WebAdvancedError` enum + 10종 carrier, `WebAdvancedErrorMappingTest`, `RetryAfterHint` | +| 02-08 | 닫힘 | `GlobalExceptionHandler.handleHandlerMethodValidationException`, 503→`REQUEST_TIMEOUT`, `TransportErrorHandlingTest` 2건 | +| 02-09 | 결정으로 닫힘 | 15절(JSON 아닌 본문은 엔드포인트가 직접). 변이 ①② 대응 테스트 `JsonBodyLimitFilterTest` 2건 추가 | +| 02-10 | 닫힘 | `WebAdapterAutoConfiguration` import 목록에서 제거, `WebMvcPlatformAutoConfigurationTest` 3건 | +| 02-11 | 닫힘 | `WebMvcRequestIdFilter.resolveCorrelationId`가 요청 id 규칙으로 교체, 테스트 3건 | +| 02-12 | 닫힘 | `IdempotencyKeyHeader`, sample `PosterImagePublicationController.java:64`, `FaultFixtureController.java:58` | +| 03-01 | **부분** | 완료 기준 네 쿼리는 통과. 그러나 union 타입 필드 아래는 점수 0·page 상한 미검사(실행 확인) → RR-02-01 | +| 03-02 | 닫힘(한계 문서화) | interceptor timer + `GraphQlDeadlineInstrumentation`, 두 실행 모델 테스트. 실행 중 resolver는 끊지 않음을 README가 명시 | +| 03-03 | 닫힘 | README 절 + 컴파일되는 예시 `OrderCustomerBatchLoading`, `GraphQlPerParentFetchInstrumentation`, `GraphQlPerParentFetchTest` | +| 03-04 | 닫힘 | registry 삭제, `graphql-api-surface.txt` 갱신 | +| 03-05 | 닫힘 | `GraphQlPlatformContextMissingException`(INTERNAL + `PLATFORM_CONTEXT`) + WARN | +| 03-06 | 닫힘 | STOMP 전송 한도 4개 키, `StompConnectionLimit`(1013), 세션당 구독 1, library handler `maxConnections` 필수. principal별 상한·토큰 재검증 없음은 README 한계로 명시 | +| 03-07 | 닫힘 | `SerializedOutboundWriter.java:107` 재확인 + 결정적 경합 테스트 | +| 03-08 | 닫힘 | `accepting` 플래그와 등록 뒤 재확인, `TomcatWebSocketShutdownIT` 재접속 케이스 | +| 03-09 | 닫힘 | `GrpcServerSettings` 상한, fixed pool + admission, 서버 deadline, drain. `GrpcP1BoundaryWireTest` 1 MiB·deadline·과부하 케이스 | +| 03-10 | 닫힘(완료 기준) | `reclaimStale`·purge·V002, 계약 테스트 fake·PG. 다만 takeover가 새 위험을 만들었다 → RR-02-04 | +| 03-11 | **부분** | 옵션 (b)로 interceptor·retention을 조립하고 ledger bean이 없으면 기동 거부. 그래도 플래그만 켜면 검증기는 통과하고 key를 실제로 처리하는 호출자는 여전히 없다. 「소유자가 (b)를 골랐다」는 기록이 15절에 없다 → RR-02-07 | +| 03-12 | > 08 영역 | `release.yml`은 이 pathspec 밖. README 13절 08-01+08-04+03-12 충족 | + +회귀로 판정한 발견은 없다. + +## Issues + +### Critical (Must Fix) + +없음. + +### Important (Should Fix) + +#### RR-02-01 · union 타입 필드 아래는 복잡도 점수 0이고 page 상한 검사도 건너뛴다 + +- **위치**: `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/cost/GraphQlDocumentComplexityScorer.java:154-156`, + `:250-260`, `:361-364` +- **무엇이 틀렸나**: `fieldCost`는 자식 비용을 `fieldsContainer(definition.getType())`로 구한다. 필드 타입이 + union이면 `GraphQLUnionType`은 `GraphQLFieldsContainer`가 아니라 `null`이 된다. 그러면 + `selectionSetCost(… parent=null …)`가 첫 줄에서 0을 돌려준다. union 아래의 inline fragment·fragment spread는 + 한 번도 방문되지 않는다. 그 안의 목록 곱셈도, `first`/`last` 상한 검사도 일어나지 않는다. 이 동작은 수정 전에도 + 있었고, 03-01 수정이 건드리지 않았다. 스코어러 단위 테스트에도 union 케이스가 없다. +- **왜 중요한가**: 검색 결과·피드처럼 union을 돌려주는 필드는 흔하다. 그런 필드가 하나라도 있으면 + `search { ... on Post { comments(first: 100000) { … } } }`가 점수 20으로 통과한다. 예산(기본 10,000)과 page 상한 + (기본 100)이 그 아래에서 꺼진다. resolver가 `GraphQlConnectionPolicy`를 직접 부르지 않으면 `first: 100000`이 + 그대로 DB까지 간다. 03-01과 같은 결함 종류이고, README 1절의 "GraphQL 공개 — 사용 보류" 판단을 그대로 남긴다. +- **고치는 법**: 부모가 union이어도 선택 집합은 내려간다. 직접 필드(union에는 `__typename`만 허용)만 건너뛰고, + type condition이 있는 inline fragment·fragment spread는 그 타입으로 계속 점수를 매긴다. union 목록 필드 자체는 + 지금처럼 `listCost`로 곱한다. scorer 테스트에 union·interface 각각 "중첩 목록 곱셈", "page 상한 초과 거부" 케이스를 넣는다. +- **심각도·우선순위**: High · P1 +- **증거**: E2 — 임시 테스트(스키마 `search: [SearchResult!]!`, `union SearchResult = Item`). + 같은 4단 중첩이 일반 목록이면 3,368,410점, union 아래면 20점. union 아래 `paged(first: 100000)`은 20점으로 통과, + 같은 값을 일반 목록에 쓰면 `page size exceeds maximum`으로 거부. + +#### RR-02-02 · 서블릿 오류 디스패치(`/error`) 응답이 `success:true` Envelope로 나간다 + +- **위치**: `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/envelope/EnvelopeBodyAdvice.java:68-81`, + `docs/web/http-contract.md:18-26,54-55`, `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/auth/SecurityConfig.java:87-94` +- **무엇이 틀렸나**: 컨트롤러 밖에서 생긴 오류(Spring Security firewall의 `RequestRejectedException`, 컨테이너 + `sendError`)는 서블릿 오류 디스패치로 Boot의 `BasicErrorController`에 간다. 그 컨트롤러가 돌려주는 `Map`을 + `EnvelopeBodyAdvice`가 그대로 `Envelope.ok(...)`로 감싼다. 결과는 HTTP 400인데 본문은 + `{"success":true,"data":{"timestamp":…,"status":400,"error":"Bad Request","path":"/probe/item;x=1"},"meta":{…}}`다. + 새 정본 `http-contract.md` 1절은 "실패 응답은 `success=false`, `error`, `meta`이고 `data` 키가 없다"고 약속하고, + 필터 체인 밖 오류는 "id 키가 빠질 수 있다"고만 적는다. `EnvelopeWireShapeTest`는 MockMvc라 오류 디스패치를 타지 + 않아 이 경로를 못 본다. 기본 JWT 체인은 `/error`를 공개 경로에 두지 않으므로, 익명 오류 디스패치가 인증에 걸려 + 원래 400 대신 401이 나갈 것으로 보인다(추론, 미실행). 샘플 체인은 GET을 모두 허용하므로 실행 결과와 같은 + `success:true` 모양이 나갈 것으로 보인다(추론). +- **왜 중요한가**: `success`를 판별자로 쓰라는 계약을 클라이언트가 그대로 따르면 4xx를 성공으로 읽는다. 짝 프론트의 + strict 스키마는 상태 코드와 모양이 어긋난 응답을 계약 위반으로 처리한다. 본문의 `path`는 요청 경로 원문을 + 되돌려 쓴다(02 영역 4.3이 404에서 막았다고 적은 것과 같은 종류). 기본 체인에서는 400이 401로 바뀌어 원인이 + 인증 문제로 오진된다. +- **고치는 법**: web leaf에 `ErrorController`(또는 `/error` 처리)를 두어 상태 코드를 `errorCodeFor`와 같은 표로 + 코드에 매핑하고 `ErrorResponseFactory`로 실패 Envelope를 쓴다. `EnvelopeBodyAdvice`는 응답 status가 4xx·5xx면 + 감싸지 않는다. 보안 체인에 `dispatcherTypeMatchers(DispatcherType.ERROR).permitAll()`을 더해 원래 status가 나가게 + 한다. 실제 서버 테스트(오류 디스패치는 MockMvc로 재현되지 않는다)에 `;` 경로 케이스를 넣고 원문 키를 단언한다. +- **심각도·우선순위**: Medium · P2 (동작은 수정 전부터 있었다. 새 정본 계약이 반대로 약속한다) +- **증거**: E3 — 실제 Tomcat 임시 테스트(permit-all 체인 + `EnvelopeBodyAdvice` + `EnvelopeWireFormatConfig` + + `WebMvcPlatformAutoConfiguration`). 기본 JWT 체인의 401 전환은 E1(코드 읽기). + +#### RR-02-03 · 정본 계약이 `IDEMPOTENCY_UNAVAILABLE`을 "작업 실행 전에 거부"라고 적지만, complete 단계에서는 작업이 이미 돌았다 + +- **위치**: `docs/web/http-contract.md:94`, `src/adapter/inbound/web/README.md:243`, + `src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyUnavailableException.java:7`, + `src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyExecutor.java:193,203,233` +- **무엇이 틀렸나**: `runStarted`는 `action.run()`(193행)이 성공한 뒤 `complete`(203행)를 부른다. 저장소가 + `UNAVAILABLE`을 돌려주면 233행이 같은 `IdempotencyUnavailableException`을 던진다. 그런데 새 정본 표는 이 코드를 + "작업 실행 전에 거부됐다. 같은 키로 나중에 다시 보낸다"로만 적는다. 02 영역 문서 2절이 P6-new-2로 이미 지적했고 + 결정 24는 "현재 동작 유지 + 문서화"였다. 이번에 만든 정본 문서가 그 거짓 문장을 다시 실었다. +- **왜 중요한가**: 클라이언트는 이 문장을 보고 사용자에게 "적용되지 않았다"고 알린다. `inWrite` 안의 DB 효과는 + 예외로 롤백되지만, action 안의 비트랜잭션 효과(외부 호출 등)는 이미 일어났다. 같은 키 재전송은 Redis 저장소에서 + claim이 `EXECUTING`으로 남아 있으면 409를 반복하다 lease 뒤 다른 판정을 받는다. "결과 불명"을 "확실히 안 함"으로 + 기록하는 것은 README 4절의 반복 원인 1번과 같은 모양이다. +- **고치는 법**: 최소한 정본 표·README 표·예외 Javadoc을 "claim 단계면 실행 전, complete 단계면 실행했을 수 있음 + (같은 트랜잭션의 DB 효과는 롤백)"으로 나눠 적는다. 더 낫게는 complete 단계에 별도 코드(예: + `IDEMPOTENCY_COMPLETION_UNKNOWN`)를 주고 클라이언트 행동을 따로 정한다. `IdempotencyExecutorTest`에 "action 뒤 + complete UNAVAILABLE" 케이스를 넣어 어느 예외·코드가 나가는지 고정한다. +- **심각도·우선순위**: Medium · P2 +- **증거**: E1 — 코드 경로(193→203→233)와 문서 대조 + +#### RR-02-04 · ledger에 시도(owner) 구분이 없어, takeover 뒤 옛 owner의 실패·완료 기록이 새 시도를 덮는다 + +- **위치**: `src/grpc/grpc-operation-ledger-jpa/src/main/java/dev/caskeleton/grpc/ledger/JpaGrpcOperationLedger.java:75-101`, + `GrpcOperationLedgerEntity.java:123-139`, `GrpcOperationLedgerRepository.java:106-123`, + `src/grpc/grpc-runtime/src/main/java/dev/caskeleton/grpc/idempotency/GrpcIdempotencyInterceptor.java:182-202`, + `docs/adr/ADR-GRPC-004-retry-ownership-and-durable-idempotency.md:61-69` +- **무엇이 틀렸나**: takeover(`tryReclaimStale`)는 `claimed_at`만 바꾼다. `markCommitted`·`markFailed`는 identity만 + 받고 "어느 시도의 기록인지"를 받지 않는다. 엔티티 검사는 `state == IN_PROGRESS` 하나다. 그래서 TTL(5분)을 넘긴 + 옛 owner A가 나중에 `markFailed`를 부르면, B가 넘겨받아 실행 중인 claim이 `FAILED_TERMINAL`이 된다. 그다음 재시도 + C가 `reclaimFailed`로 다시 claim하면 B와 C가 동시에 실행된다. 또 JPA `markCommitted`는 `findById` → 상태 확인 → + `save`라 행 잠금·`@Version`이 없다. 두 시도가 같은 순간 commit하면 둘 다 IN_PROGRESS를 읽고 둘 다 커밋한다. + ADR은 "느린 owner의 commit"만 위험으로 적고, 옛 owner의 `markFailed` 덮어쓰기는 적지 않는다. 버린 대안 목록에도 + heartbeat 없는 fence(commit 시 claim 시각 비교)가 없다. 공유 계약 테스트에 "takeover 뒤 옛 owner의 기록" 케이스가 없다. + - 같은 묶음의 작은 경쟁: purge가 지운 직후 같은 key의 claim은 `INSERT … ON CONFLICT`가 0을 받고 `findById`가 비어 + `IllegalStateException("… Retry the claim.")`을 던진다(`JpaGrpcOperationLedger.java:53-65`). `decide()`는 다시 + 시도하지 않아 호출자는 내부 오류를 받는다. 보존 기간(24h)보다 오래된 key에서만 열리는 좁은 창이다. +- **왜 중요한가**: 03-10 수정은 "key가 영구히 막힘"을 "TTL 뒤 넘겨받음"으로 바꿨다. 넘겨받는 순간이 바로 하류가 + 멈춘 때라 옛 owner가 늦게 깨어나 기록하는 경우가 생긴다. 그때 기록이 새 시도를 덮어 같은 operation이 두 번 + 돌 수 있다. 멱등성 ledger가 막으려던 결과다. 플랫폼이 아직 어디에도 채택되지 않아 지금 노출은 없다(채택 전 차단 항목). +- **고치는 법**: claim·reclaimFailed·reclaimStale이 claim 토큰(그 시도의 `claimed_at`이나 attempt id)을 돌려주게 + 한다. `markCommitted`·`markFailed`는 `UPDATE … WHERE state='IN_PROGRESS' AND claimed_at=:token`으로 바꿔 0행이면 + 호출자가 롤백한다. 계약 테스트에 "takeover 뒤 옛 owner의 commit·fail은 거부", PG lane에 "동시 commit은 하나만"을 + 더한다. ADR 버린 대안에 fence 안을 적거나 고른다. purge 경쟁은 claim이 행 소실을 보면 insert를 한 번 더 시도하게 한다. +- **심각도·우선순위**: Medium · P2 (채택 전에 고친다) +- **증거**: E2 — 공유 계약 fake로 순차 경로 실행: `bTookOver=true staleOwnerMarkFailed=accepted state=FAILED_TERMINAL cReclaimed=true`. + JPA 동시 commit 경쟁은 E1(코드 읽기, 실 PG 미실행). + +### Minor (Nice to Have) + +#### RR-02-05 · `Retry-After: 2`를 "lease에 맞춰 다시 정하라"고 하지만 고칠 손잡이가 없다 + +- **위치**: `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/observability/RetryAfterAdvisor.java:14-19`, + `docs/web/http-contract.md:80-83`, `src/composition/idempotency/src/main/java/dev/caskeleton/composition/idempotency/IdempotencySettings.java:47-50` +- **무엇이 틀렸나**: 정본은 "lease를 2초보다 짧게 설정한 서비스는 값을 다시 정한다"고 적는다. 그런데 2초는 web leaf의 + 정적 표에 박혀 있고 설정 키가 없다. `IdempotencySettings`도 lease 하한을 2초 위로 막지 않는다. +- **왜 중요한가**: 개발자가 따로 기억해야 하는 숨은 규칙이다. lease를 1초로 둔 서비스는 클라이언트를 lease 뒤에 + 다시 오게 만든다. +- **고치는 법**: `IdempotencySettings`에서 lease가 `IDEMPOTENT_IN_FLIGHT`의 Retry-After보다 길어야 기동하게 하거나, + 문장을 "lease를 2초 이하로 두지 않는다"로 바꾼다. +- **심각도·우선순위**: Low · P3 · **증거**: E1 + +#### RR-02-06 · in-flight `retryable` 변경이 gRPC·GraphQL wire에도 나가는데 문서·테스트·호환성 표시가 없다 + +- **위치**: `src/adapter/inbound/grpc/src/main/java/dev/caskeleton/adapter/inbound/grpc/GrpcStatusMapper.java:59-64`, + `docs/registries/error-codes.yaml:404-414` +- **무엇이 틀렸나**: `IDEMPOTENT_IN_FLIGHT`가 retryable=true가 되면서 gRPC trailer `error-retryable`(status ABORTED)와 + GraphQL extension `retryable`도 true로 바뀌었다. README 13절이 "테스트 없음"으로 남긴 상태 그대로다. registry는 + `compatibility_impact: none`이다. 같은 코드 이름 `REQUEST_TIMEOUT`이 web에서는 503·`TRANSIENT_DEPENDENCY`(이번에 + 새로 만듦), GraphQL에서는 category `TIMEOUT`이다. +- **왜 중요한가**: 관찰되는 wire 값이 바뀌면 소비자가 의존한다(Hyrum's Law). 클라이언트가 전송마다 다른 뜻을 배운다. +- **고치는 법**: gRPC·GraphQL 매핑 테스트에 in-flight 케이스를 넣고 각 README에 한 줄 적는다. registry의 + `compatibility_impact`를 `behavior-change`로 고친다. web 쪽 timeout 코드 이름과 category를 GraphQL과 맞추거나 차이를 적는다. +- **심각도·우선순위**: Low · P3 · **증거**: E1 + +#### RR-02-07 · 03-11: 플래그만 켜면 검증기는 통과하고, key를 처리하는 호출자는 여전히 adopter 몫이다 + +- **위치**: `src/grpc/grpc-spring-boot-starter/src/main/java/dev/caskeleton/grpc/boot/GrpcPlatformStartupValidator.java:149-155`, + `GrpcPlatformAutoConfiguration.java`(interceptor bean Javadoc "nothing calls this yet"), `src/grpc/CLAUDE.md:168` +- **무엇이 틀렸나**: 검증기 문구는 "플래그가 false면 key가 받아들여지고 처리되지 않는다"고 한다. 플래그를 true로 + 두면 결정 함수 bean은 생기지만 그것을 부르는 서버 단계가 없어도 기동한다. 원래 지적("운영자가 멱등 처리가 켜졌다고 + 믿는다")이 좁아졌을 뿐 남는다. 또 `src/grpc/CLAUDE.md:168`의 "The owner chose (b)"는 리뷰 README 15절 결정 기록에 없다. +- **고치는 법**: 15절(또는 ADR)에 (b) 결정과 이유를 기록한다. 검증기가 `IDEMPOTENCY` 단계 interceptor가 조립됐는지까지 + 보거나, 문구를 "플래그는 결정 함수만 조립한다. 서버 단계 연결은 별도"로 고친다. +- **심각도·우선순위**: Low · P3 · **증거**: E1 + +#### RR-02-08 · GraphQL 작은 불일치 두 건 + +- **위치**: `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/cost/GraphQlComplexityCalculator.java:124-127` + 대 `:56-60`, `context/GraphQlDeadline.java:11-22` 대 `README.md:298` +- **무엇이 틀렸나**: ① `effectivePageSize(first, last)`는 둘 다 있으면 `first`를 고른다. 같은 클래스의 + `connectionCost`는 이번 수정으로 큰 쪽을 고른다. main 호출자는 없다. 갈라진 복사본이다. ② `GraphQlDeadline` Javadoc은 + "지금 읽는 곳은 이것뿐"이라며 셋을 나열하지만 이번에 추가한 `GraphQlDeadlineInstrumentation`이 빠졌다. README는 넷이다. +- **고치는 법**: `effectivePageSize`를 지우거나 `connectionCost`와 같은 규칙으로 맞춘다. Javadoc 목록에 instrumentation을 넣는다. +- **심각도·우선순위**: Low · P3 · **증거**: E1 + +## Declined to judge + +- 짝 프론트의 분류기·strict 스키마가 `retryable=true` 409와 `meta.page.sort: null`을 어떻게 받는지 — 다른 repo이고 + 15절에서 프론트 세션에 인계했다. +- `src/adapter/inbound/messaging`(inbox 자동 설정·마이그레이션 스트림) — 06 영역 발견(06-08)의 수정이다. + `TransactionTemplate`에 timeout이 없다는 점만 눈에 띄었다. +- web-notification 콜백 503+`Retry-After`(05-20)와 본문 상한 계산, web-fileserver tus PATCH(05-12) — 05 영역 소관. +- Keycloak 기본 토큰의 `aud=account`를 audience로 넣는 운영 실수 — 코드는 설정한 값을 정확히 검사한다. 운영 문서 문제로 보고 판단하지 않았다. +- `GlobalExceptionHandler`가 503 상태 전체를 `REQUEST_TIMEOUT`으로 읽는 것 — 지금 Spring MVC에서 503을 내는 예외가 async timeout 하나라 문제는 없다. 미래 Spring 변경 위험은 추측이라 올리지 않았다. +- `PlatformWebSocketHandler`가 `final`이 되고 생성자 인자가 늘어난 API 변경 — 라이브러리 소비자가 템플릿 안에 없고 README가 새 시그니처를 적는다. +- WebSocket 연결 상한 기본 1000 × send buffer 512 KiB = 최악 512 MiB — README가 노드 heap에 맞추라고 적었다. 실측하지 않았다. +- GraphQL over WebSocket 구독에 interceptor timeout이 어떻게 걸리는지 — 이 템플릿에서 구독을 켜는 경로를 확인하지 못했다. +- `DurableOperationController`의 id factory 교체 — 01·07 영역 결정(UUIDv7)의 일부다. + +## 28개 관점 — 바뀐 관점만 + +| # | 관점 | 영역 | 이전 → 지금 | 이유 | +| --- | --- | --- | --- | --- | +| 5 | 위험 가시성 | 02 | X → P | audience 필수·String·null 생략이 코드에 드러남. `/error` 모양(RR-02-02)과 503 문장(RR-02-03)이 남음 | +| 5 | 위험 가시성 | 03 | X → P | deadline·STOMP 한도·ledger 플래그가 코드와 문서에 맞음. union 점수 구멍(RR-02-01)이 드러나지 않음 | +| 7 | 운영 성숙도 | 03 | P → O | gRPC drain, WebSocket stop 뒤 1001, ledger 증가 runbook | +| 8 | 디버깅 가능성 | 03 | P → O | batch context 누락이 `PLATFORM_CONTEXT`+WARN, per-parent N+1이 WARN+metric | +| 13 | 확장성 | 03 | X → P | WebSocket 노드 연결·구독 상한, gRPC bounded pool+admission. principal별 상한은 없음(문서화) | +| 15 | 보안 성숙도 | 02 | X → P | JWT audience 필수·client role 범위. `/error` 본문의 path echo와 상태 왜곡(RR-02-02) | +| 17 | API·계약 | 02 | X → P | 정본 `http-contract.md`와 원문 키 테스트. `/error`·503 행이 계약과 어긋남(RR-02-02·03) | +| 19 | 설정 성숙도 | 03 | P → O | STOMP·gRPC 한도가 검증되는 명시 키, ledger TTL·보존 키 | +| 25 | 조직 확장성 | 02 | P → O | KEYED 헤더 추출이 `IdempotencyKeyHeader` 하나(02-12) | +| 28 | 회복 가능성 | 03 | X → P | stale claim 회수·writer 예산 누수 해소. takeover 뒤 옛 owner 기록 fence 없음(RR-02-04) | + +## Assessment + +**Ready to merge? With fixes.** Critical은 없다. 02·03 발견 24건 중 21건이 닫혔고(결정으로 닫힘 1건 포함), 2건(03-01·03-11)은 부분, 1건(03-12)은 08 영역이다. RR-02-01(union 아래 복잡도 우회, +High)이 GraphQL 공개 보류를 그대로 남기므로 GraphQL을 켜기 전에, RR-02-04는 gRPC ledger 채택 전에, RR-02-02·03은 +짝 프론트가 정본 계약을 따르기 전에 고쳐야 한다. diff --git a/docs/reviews/2026-11-03-rereview/03-persistence.md b/docs/reviews/2026-11-03-rereview/03-persistence.md new file mode 100644 index 00000000..04f2581a --- /dev/null +++ b/docs/reviews/2026-11-03-rereview/03-persistence.md @@ -0,0 +1,232 @@ +# 03 persistence 재리뷰 (2026-11-03) + +## 범위 + +- 리뷰 범위: Base `01a8a2a70` → Head `5786126c`. +- 본 pathspec: `src/adapter/outbound/persistence-jpa`, `persistence-mongo`, `persistence-fileserver`, + `persistence-notification`, `docs/jpa`, `docs/mongodb`, `docs/architecture/jpa-api-surface.txt`, + `docs/adr/ADR-JPA-003-completion-unknown.md`. 224파일, +8,176 −2,138. +- 판단에 필요해서 pathspec 밖에서 읽은 것: + - `application-core`: `AggregateOrder`, `OutboxAggregateSequenceContract`, `SubmitDurableOperationUseCase`, `PublishPendingOutboxEventsUseCase`의 트랜잭션 경계. + - `adapter/outbound/messaging`: `PlatformIntegrationEventPublishAdapter`(순서 번호가 소비자에게 나가는 곳). + - `application-notification` testFixtures: `OverlappingWrites`, `SuppressionStoreContract`, `ReconciliationJobStoreContract`. + - `app-bootstrap`: `JpaProductionArchitectureTest`, `build.gradle`(ArchUnit 규칙이 보는 leaf 범위). + - `docs/runbooks/outbox-dead-letter.md` §8, `docs/jpa/migration-guide.md`, `src/config/architecture/modules.json`. + - 15절이 이 영역에 묶은 마이그레이션: grpc-ledger `V002`와 그 삭제 쿼리, sample `V8_1`과 `PosterRepositoryAdapter`. + +### 불러온 스킬과 적용한 기준 + +| 스킬 | 적용한 기준 | 무엇을 봤나 | +|---|---|---| +| `superpowers:requesting-code-review` | 리뷰어 템플릿: 요구사항 정합, mock이 아닌 실제 동작 테스트, 마이그레이션 전략·하위 호환, Declined to judge, 심각도 보정 | 발견별 완료 기준 대조, 테스트가 단언하는 범위, 마이그레이션의 기존 데이터 영향 | +| `jpa-patterns` | assigned id와 `Persistable`, 짧은 트랜잭션·readOnly, bulk UPDATE와 `@Version`, JDBC batch(`batch_size`, `order_inserts`), Flyway additive 마이그레이션 | 04-05·04-07·04-10·04-17·09-07. 연관관계는 **사용자 원칙(양방향 금지)을 스킬의 `mappedBy` 예시보다 우선**해서 규칙의 빈틈을 찾았다(RR-03-04) | +| `supabase-postgres-best-practices` | `lock-skip-locked`(claim은 CTE + `FOR UPDATE SKIP LOCKED` + `UPDATE … RETURNING` 한 문장), `data-upsert`(check-then-insert 금지, `ON CONFLICT`), `schema-constraints`(제약 추가의 재실행 안전성), `lock-short-transactions`(트랜잭션 시간 제한), `query-partial-indexes`·인덱스 | 04-02·04-08·04-13의 claim·upsert, 새 counter(RR-03-01), V20·V21·V11~V13·V002의 잠금·재실행·기존 데이터 영향(RR-03-02·05) | + +### 실행한 명령 + +모두 별도 worktree `scratchpad/rr-03`(@`5786126c`)에서 `flock heavy.lock`으로 감싸 실행했다. 끝난 뒤 `git worktree remove --force`로 지웠다. 메인 작업 트리는 바꾸지 않았다. + +| 명령 | 실행 직전 부하 | 결과 | +|---|---|---| +| `./gradlew :adapter:outbound:persistence-jpa:test --tests '*RrScratchTest*'` (임시 테스트 1클래스·엔티티 3개 추가) | load 23.79 | rc=0, 3개 실행. 관찰은 RR-03-03·RR-03-04 | +| `./gradlew :adapter:outbound:persistence-jpa:postgresqlOutboxAggregateSequenceIntegrationTest` (기존 클래스에 임시 메서드 2개 추가) | load 17.43 | rc=0, 6개 실행·skip 0. 관찰은 RR-03-01·RR-03-02 | + +임시 테스트는 결과를 출력만 하고 실패시키지 않게 썼다. rc=0은 "결함 없음"이 아니다. 관찰값은 각 발견의 증거 칸에 적었다. + +### 못 본 것 + +- Mongo 컨테이너 lane(`MongoTransactionWriteConflictLaneTest`)은 직접 돌리지 않았다. 04-11은 코드로만 봤다. +- 알림 정산 claim을 실제 2개 인스턴스로 돌리지 않았다. 공용 계약(`ReconciliationJobStoreContract`)을 읽었다. +- V20의 CHECK 추가가 테이블을 한 번 읽는지 실측하지 않았다. +- optional-platforms build(grpc-ledger)는 실행하지 않았다. +- 전체 게이트는 README 16.2 결과를 그대로 썼다. + +## Strengths + +- **커밋 단계를 따로 분류한다.** `SpringTransaction.java:195-215`는 본문이 끝난 뒤 자기가 연 쓰기 트랜잭션을 커밋하는 동안 난 실패만 `translateCommitFailure`로 보낸다. 실 PostgreSQL 테스트가 `pg_terminate_backend`로 커밋 중 연결을 끊고 `DB_COMPLETION_UNKNOWN`·`retryable=false`를 단언한다(`PostgreSqlTransactionIntegrationTest.java:211-214`). +- **SQLState 표가 한 벌이 됐다.** `PostgreSqlSqlStateErrorMapping.java:60-90`은 행을 직접 쓰지 않고 `PostgreSqlFailureClassifier` → `FailureCategory.operationalError()`에서 만든다. `SqlStateClassificationParityTest`가 두 경로의 결과를 모든 상태에 대해 비교한다. +- **정산 job claim이 한 문장이다.** `JdbcReconciliationJobStore.java:56-72`는 CTE + `SKIP LOCKED` + `UPDATE … RETURNING`으로 lease와 fence를 같은 문장에서 쓴다. 이후 쓰기는 fence 조건이다. 같은 계약을 fake와 실 PG가 상속한다(`ReconciliationJobStoreContract.java:54,70`). +- **upsert를 DB가 판정한다.** `JpaSuppressionStore.java:59-100`은 `ON CONFLICT DO NOTHING` 뒤 managed entity로 갱신한다. `OverlappingWrites.java:42`는 첫 트랜잭션을 열어 둔 채 두 번째를 시작해 경쟁을 운에 맡기지 않는다. +- **계약 테스트가 실제 결함을 찾았다.** 선호 설정이 `jsonb` 열에 쉼표 문자열을 넣어 실 PG에서 항상 실패하던 것을 PG 계약 테스트가 드러냈고 고쳤다(`JpaPolicyStores.java:104`). +- **bulk UPDATE 규칙이 운영 그래프에 걸린다.** `JpaVersionedBulkUpdateRule.java:51,78`은 `@Version` 엔티티 이름을 검사 대상 그래프에서 계산한다. `JpaProductionArchitectureTest.java:135`가 notification·fileserver를 포함한 운영 클래스에 적용한다. +- **격리 수준 왕복 제거를 실측으로 고정했다.** 서버 기본값을 `repeatable read`로 둔 풀에서 `getTransactionIsolation()` 호출 0회와 `read committed` 실행을 함께 단언한다(`PostgreSqlTransactionIntegrationTest.java:322`). +- **V21 runbook SQL을 실 PG에서 실행한다.** `PostgreSqlOutboxOrderKeyRunbookIntegrationTest`가 runbook 문서에서 SQL 블록을 읽어 돌린다. 문서가 lane의 입력으로 선언돼 있다(`persistence-jpa/build.gradle`). +- **Mongo URI 경로 기본값의 순서가 맞다.** `MongoProfileClientSettingsAutoConfiguration.java:99`는 기본값을 가장 먼저 적용해 URI 값이 이긴다. 테스트가 Boot 표준 connection-string customizer와 함께 순서를 확인한다. +- **V12가 남길 행의 규칙을 SQL 주석에 적었다.** 삭제 마이그레이션에 생존 규칙 4단계와 이유가 있다. 같은 규칙이 leaf `CLAUDE.md`에 적혀 있다. + +## 발견 재확인 표 + +| ID | 상태 | 근거 | +|---|---|---| +| 04-01 | 닫힘 | `SpringTransaction.java:195-215`, `PersistenceExceptionTranslator.java:157-182`, PG IT `:211-214`. 한계: IT는 `DataSourceTransactionManager`로 돈다. 운영은 `JpaTransactionManager`다. cause chain을 걷는 구현이라 같은 결과로 보지만 실행 확인은 안 했다 | +| 04-02 | 닫힘 | `JdbcReconciliationJobStore.java:56-90`, 계약 `ReconciliationJobStoreContract.java:54,70`. 남은 것: RR-03-08 | +| 04-03 | 부분 | 규칙(`SingleSidedAssociationCondition`), 가이드(`entity-mapping-guide.md:52-95`), 단방향 fixture는 들어왔다. `mappedBy` 없는 양방향이 규칙을 통과한다(RR-03-04, E3) | +| 04-04 | 닫힘(이 영역 몫) | persistence-fileserver 테스트 4클래스(activation, caller transaction, `AssignedIdEntity`, claim SQL). 새 lane 2개가 `readinessLanes`에 등록됐다. workflow 실행은 08 영역 | +| 04-05 | 닫힘 | `PersistenceExceptionTranslator.java:128-141`. PG IT `aVersionRaceLostAtCommitIsAnOptimisticConflict`가 `JpaTransactionManager`로 409 코드를 단언한다 | +| 04-06 | 닫힘 | `PostgreSqlSqlStateErrorMapping.java:60-90`, `SqlStateClassificationParityTest`. 남은 이름 문제: RR-03-10 | +| 04-07 | 닫힘 | `InboxItemJpaRepository`·`RecipientClaimSql.EXPIRE_OVERDUE`에 `version + 1`과 `clearAutomatically`. PG `InboxBulkReadVersionContractTest`·`RecipientExpiryVersionContractTest`. 한계: 규칙은 `@Modifying @Query`만 본다(Declined 참고) | +| 04-08 | 닫힘 | `JpaSuppressionStore.java:59-100`, `JpaPolicyStores.Preferences.save`, V12, `SuppressionStoreContract.java:150`(실 PG 겹침) | +| 04-09 | > | sample 영역. 이 리뷰에서 확인하지 않았다 | +| 04-10 | 부분 | 쓰기·읽기 30초. JDBC 경로는 PG IT로 확인됐다. Hibernate 문장 직전 마감 초과는 분류되지 않는다(RR-03-03, E3) | +| 04-11 | 닫힘(E1) | `SpringMongoTransactionSessionFactory.java:141-151`. 소항목(commit 재시도 대기 중 인터럽트)은 `MongoTransactionRetryCoordinator.java:150-156`. lane은 직접 돌리지 않았다 | +| 04-12 | 닫힘 | `MongoUriOnlyClientDefaults`, customizer 순서(`:99`), `MongoUriOnlyClientDefaultsTest`, `mongo.yml` 주석 정정 | +| 04-13 | 닫힘 | `JpaCleanupQueue`에 정책 상수·`heldClaims` 없음. lease는 인자, 토큰은 `CleanupItem`. claim 한 문장(`CleanupClaimSql`). PG `PostgreSqlFileserverReclamationIntegrationTest.java:174` | +| 04-14 | 부분 + 결정으로 닫힘 | notification 포트 계약 대부분을 PG가 상속한다. `ConsentStorePort`·`NotificationInbox`는 15절 결정으로 닫았다. fileserver `*PortContract` 상속 | +| 04-15 | 닫힘 | 테스트 소스 예시(`mongo/example`), `docs/mongodb/consumer-leaf-guide.md`. 가이드의 레지스트리 주장(app-bootstrap에 mongo edge가 이미 있음 등)을 `modules.json`과 대조해 맞음을 확인했다 | +| 04-16 | 닫힘 | 두 leaf `CLAUDE.md`, notification `entity`·`repository` 분할. 부작용: RR-03-09 | +| 04-17 | 닫힘 | `AssignedIdEntity`(`Persistable`), `AssignedIdEntityTest` | +| 09-02 | 닫힘(E1, 일부만 봄) | `V8_1`이 중복 사전 검사 뒤 `uq_poster_title_ci` 생성. adapter가 `saveAndFlush` 뒤 제약 이름으로 변환한다. 동시성 실측은 README 13절 기록 | +| 09-05 | 닫힘 | 템플릿 `ISOLATION_DEFAULT` + Hikari `transaction-isolation` + 기동 검사. PG IT `:322` | +| 09-07 | 닫힘 | `persistence-jpa.yml` batch 50·`order_inserts/updates` true, `ModuleDefaultJdbcBatchingTest` | +| 09-09 | 닫힘 | `build.gradle`이 H2를 `testRuntimeOnly`로. lockfile의 `runtimeClasspath`에서 H2가 빠졌다 | +| 05-01 | 닫힘(persistence 쪽) | `PostgreSqlNotificationBackgroundPassIntegrationTest`가 `DeliveryAttemptFactory`로 만든 행을 `LeaseRecoveryService`에 넣는다. 개명한 `WorkerCrashRecoveryContractTest` 테스트는 동어반복이다(RR-03-07) | +| 06-07 | 부분 | 순서 번호를 DB counter로 바꿨다(`JpaOutboxStore.nextSequence`). 순서 키 유일 인덱스(V21)가 들어왔다. counter가 새 결함 두 개를 만들었다(RR-03-01, RR-03-02) | + +회귀로 판정한 발견은 없다. + +## Issues + +### Critical (Must Fix) + +없음. + +### Important (Should Fix) + +#### RR-03-01 첫 counter 생성이 겹치면 정상 쓰기가 409로 거절된다 + +- **위치**: `persistence-jpa/.../outbox/jpa/JpaOutboxStore.java:114-124`, `OutboxEventJpaRepository.java:122-145`, Javadoc `JpaOutboxStore.java:108-112`. +- **무엇이 틀렸나**: counter가 없으면 `UPDATE`가 0행을 돌려주고 `INSERT … SELECT`로 만든다. 두 트랜잭션이 같은 aggregate에서 동시에 0행을 보면 둘 다 INSERT한다. 두 번째는 첫 번째의 커밋을 기다린 뒤 PK 위반(23505)으로 실패한다. Javadoc은 "a rollback the caller retries"라고 쓰지만 재시도하는 호출자는 없다. +- **증거**: 첫 트랜잭션이 `nextSequence` 뒤 커밋을 미루고, 두 번째가 같은 새 aggregate로 `nextSequence`를 불렀다. 첫째는 `1`. 둘째는 `PersistenceFailureException DB_UNIQUE_VIOLATION retryable=false`. +- **왜 중요한가**: + - 발생 조건: counter가 없는 aggregate에 쓰기 두 개가 겹칠 때. V21 배포 직후에는 기존 aggregate 전부가 counter가 없다. + - 영향: 정상 요청이 재시도 불가 409로 거절되고 그 업무 쓰기 전체가 롤백된다. + - 같은 leaf에 맞는 모양이 이미 있다: `JpaLiveEventReplay.java:41-48`의 `INSERT … ON CONFLICT (stream_id) DO UPDATE SET last_position = last_position + 1 RETURNING`. notification `CLAUDE.md`의 "Insert-or-update is decided by the database" 규칙과도 다르다. 같은 일을 하는 두 갈래 구현이다. +- **고치는 법**: 한 문장으로 바꾼다. + ```sql + INSERT INTO outbox_aggregate_sequence (tenant_scope, aggregate_type, aggregate_id, last_sequence) + SELECT :t, :a, :i, COALESCE(MAX(e.aggregate_sequence), 0) + 1 + FROM outbox_event e WHERE e.tenant_scope = :t AND e.aggregate_type = :a AND e.aggregate_id = :i + ON CONFLICT (tenant_scope, aggregate_type, aggregate_id) + DO UPDATE SET last_sequence = outbox_aggregate_sequence.last_sequence + 1 + RETURNING last_sequence; + ``` + 두 번째 쓰기는 첫째 커밋을 기다린 뒤 `DO UPDATE`로 2를 받는다. 행 잠금이라 커밋 순서도 그대로다. `OutboxAggregateSequenceContract`에 `OverlappingWrites` 같은 겹침 테스트를 더한다. +- **가이드 심각도·우선순위**: Medium · P2. **증거**: E3. + +#### RR-03-02 V21 이행 뒤 aggregate 순서 번호가 이미 내보낸 번호보다 작아진다 + +- **위치**: seed `OutboxEventJpaRepository.java:130-145`(`COALESCE(MAX(e.aggregate_sequence), 0) + 1 FROM outbox_event`), V21 주석 `V21__outbox_aggregate_sequence.sql:8-11`, 소비자로 나가는 곳 `PlatformIntegrationEventPublishAdapter.java:102,124`, 계약 `AggregateOrder` Javadoc("consumers read it as 'which change came last'"). +- **무엇이 틀렸나**: + - seed는 outbox에 남은 행만 본다. + - `OutboxReaper`는 retention이 지난 PUBLISHED 행을 지운다. + - 그래서 옛 벽시계 방식(epoch 마이크로초, 약 1.7×10¹⁵)으로 이미 발행한 aggregate도 counter가 1부터 시작한다. + - rolling 배포 중 옛 인스턴스가 벽시계 번호를 계속 쓰면, 새 인스턴스의 counter(옛 최대+1부터)는 나중 커밋에 더 작은 번호를 준다. + - V21 주석이 가리키는 `JpaOutboxAggregateSequences` 클래스는 없다(실제는 `JpaOutboxStore.nextSequence`). +- **증거**: 번호 1,761,955,200,000,000인 행을 append하고 지운 뒤(reaper 흉내) `nextSequence` → `1`(E3). 소비자 영향은 추론이다. 템플릿 안에는 번호를 비교하는 소비자가 없다(E1). +- **왜 중요한가**: + - `AggregateOrder.ofOccurrence`는 삭제된 공개 API다. 쓰던 파생 서비스는 업데이트하면서 `nextSequence`로 옮겨야 한다. + - 그 서비스의 소비자가 "마지막 번호보다 작으면 버린다"로 구현했다면 V21 이후 해당 aggregate의 이벤트를 모두 버린다. + - runbook §8은 중복 키만 다루고 이 단절은 말하지 않는다. + - V21 주석의 "rows numbered by the old clock scheme still come first"는 outbox 안에서만 참이다. +- **고치는 법(대안)**: + - (a) seed에 하한을 둔다. 다음 마이그레이션이 이행 시점 하한을 한 행 테이블에 기록하고, 새 counter는 `GREATEST(MAX, 하한) + 1`에서 시작한다. 벽시계를 쓴 적 없는 서비스는 하한 0. 코드로 막으므로 권한다. + - (b) runbook에 "V21 전 모든 옛 writer 종료(mixed version 금지)"와 "소비자의 마지막 번호 초기화" 절차를 적는다. + - (c) 계약 문서에 번호 단절을 명시하고 현상 유지. + - V21 파일은 해시가 고정돼 주석을 고칠 수 없다. 정정은 다음 마이그레이션 주석이나 runbook에 둔다. +- **가이드 심각도·우선순위**: Medium · P2. **증거**: E3(seed 동작), E1(소비자 영향). + +#### RR-03-03 JPA 경로에서 트랜잭션 마감 초과가 분류되지 않고 500이 된다 + +- **위치**: `PersistenceExceptionTranslator.java:128-141`(Spring `TransactionTimedOutException`만 본다), `SpringTransaction.java:121-126` Javadoc, `persistence-jpa/CLAUDE.md:237-238,305`, 테스트 `PostgreSqlTransactionIntegrationTest.java:273-290`(`DataSourceTransactionManager` + `JdbcTemplate`만). +- **무엇이 틀렸나**: 마감이 지난 뒤 Hibernate가 다음 문장을 준비하면 Hibernate가 직접 `org.hibernate.TransactionException("Transaction timeout expired")`를 던진다. SQLState도 없고 Spring 타입도 아니다. 번역기는 비운다. web catch-all이 500 `INTERNAL_ERROR`로 답한다. +- **증거**: H2 + `JpaTransactionManager` + `Timeouts(1s, 1s)`, 본문에서 1.3초 기다린 뒤 `persist`. + - 본문 안 `flush` → `org.hibernate.TransactionException`, 번역 안 됨. + - 커밋 시 flush → `JpaSystemException`(cause `TransactionException`), 번역 안 됨. + - 이 예외는 JDBC 호출 전에 Hibernate가 만든다. 벤더와 무관하다. +- **왜 중요한가**: 운영 조합은 `JpaTransactionManager`다. 문서와 Javadoc은 "마감이 지나면 `DB_QUERY_CANCELED`"를 약속하지만 주 경로에서는 500과 error 로그가 나간다. 테스트는 옆 경로(JDBC)만 본다. 롤백은 되므로 데이터 손상은 없다. +- **고치는 법**: `SpringTransaction`이 시작 시각과 마감을 안다. 실패가 분류되지 않았고 실패 시점이 마감을 넘었으면 `DB_QUERY_CANCELED`로 분류한다. 예외 메시지를 읽지 않아도 된다. `JpaTransactionManager`로 같은 시나리오를 도는 PG 테스트를 하나 더한다. +- **가이드 심각도·우선순위**: Medium · P2. **증거**: E3. + +#### RR-03-04 `mappedBy` 없는 양방향 연관관계가 금지 규칙을 통과한다 + +- **위치**: `testFixtures/.../arch/SingleSidedAssociationCondition.java:30,50`(`mappedBy` 속성만 본다), `docs/jpa/entity-mapping-guide.md:52,72,81`. +- **무엇이 틀렸나**: 부모 `@OneToMany @JoinColumn(name = "parent_id")`와 자식 `@ManyToOne @JoinColumn(name = "parent_id", insertable = false, updatable = false)`는 한 FK를 두 필드가 가진 양방향이다. Hibernate 문서에 있는 `@JoinColumn` 양방향 모양이다. `mappedBy`가 없어 규칙은 위반 0을 낸다. +- **증거**: 두 엔티티를 `ClassFileImporter`로 넣고 `associationsAreMappedFromOneSideOnly().check(...)` → 통과. +- **왜 중요한가**: 사용자 원칙은 "양방향 금지"다. 가이드도 "one side only"라고 말한다. 가이드가 허용한 예외(단방향 `@OneToMany @JoinColumn`)에 자식 쪽 `@ManyToOne` 하나만 더하면 금지된 모양이 빌드를 통과한다. 읽기 전용 쪽은 같은 영속성 컨텍스트에서 바뀌지 않는다. 규칙 Javadoc이 막겠다는 "메모리와 DB 불일치"가 그대로 생긴다. +- **고치는 법**: 규칙을 클래스 하나가 아니라 그래프로 본다. A의 연관이 B를 가리키고 B의 연관이 A를 가리키면 위반이다(같은 join column이든 `mappedBy`든). 최소한 `@ManyToOne`·`@OneToOne`에 `insertable = false, updatable = false`인 `@JoinColumn`이 있으면 위반으로 본다. 가이드 81행 문장을 실제 범위에 맞춘다. 위반 fixture로 red/green 테스트를 둔다. +- **가이드 심각도·우선순위**: Medium · P2. **증거**: E3. + +### Minor (Nice to Have) + +#### RR-03-05 V21 유일 인덱스를 잠금 아래 만들고, 고른 이유가 없다 + +- **위치**: `V21__outbox_aggregate_sequence.sql:26`, `docs/jpa/migration-guide.md:35-46`, 비교 대상 grpc-ledger `V002`. +- **무엇**: 비동시 `CREATE UNIQUE INDEX`는 빌드 동안 `outbox_event`에 SHARE 잠금을 건다. 그동안 모든 append, 즉 outbox를 쓰는 업무 쓰기가 멈춘다. `lock_timeout`이 없어 잠금을 기다리는 동안 뒤 요청이 줄을 선다. migration-guide는 `CONCURRENTLY` + `executeInTransaction=false`를 정형으로 둔다. grpc `V002`는 비동시를 고른 이유를 적었다. V21에는 고른 방법·버린 대안이 없다. "중복이면 롤백"을 위해 트랜잭션 안을 골랐을 수 있지만 기록이 없다. +- **고치는 법**: runbook §8에 한 줄을 더한다. "outbox가 크면 같은 정의를 `CREATE UNIQUE INDEX CONCURRENTLY`로 먼저 만든다. V21의 `IF NOT EXISTS`가 그것을 건너뛴다." 이유도 같이 적는다. +- Low · P3 · E1. + +#### RR-03-06 쓰는 곳 없는 `positional` helper가 두 벌이다 + +- **위치**: `persistence-fileserver/.../repository/CleanupClaimSql.java:53`(새로 복사), `persistence-notification/.../repository/RecipientClaimSql.java:80`. +- **무엇**: 같은 정규식 helper다. 두 벌 모두 자기 단위 테스트 말고 호출자가 없다. 04-14로 bare `Connection` 테스트가 없어졌기 때문이다. `CleanupClaimSql.java:17-19` Javadoc은 "a test in this package that runs the identical text on a bare Connection"이라는 없는 소비자를 말한다. +- **고치는 법**: 둘 다 지운다. 필요하면 persistence-jpa testFixtures 한 곳에 둔다. +- Low · P3 · E1. + +#### RR-03-07 테스트 이름이 단언보다 크다 + +- **위치**: `WorkerCrashRecoveryContractTest.java:94-112`, `CleanupClaimSqlTest.java:18,28`. +- **무엇**: + - `WorkerCrashRecoveryContractTest`의 개명 테스트는 "reconcile 대상이 된다"고 말한다. 실제로는 recovery를 돌리지 않는다. 방금 직접 insert한 evidence 값을 다시 읽어 같은지 본다. factory도 거치지 않는다. + - 같은 클래스의 나머지 `@DisplayName` 5개는 영어다(소유자 결정 5는 한국어). + - `CleanupClaimSqlTest`는 "잠그고 건너뛴다"를 문자열 `contains`로 단언한다. + - 실제 동작은 `PostgreSqlNotificationBackgroundPassIntegrationTest`와 `PostgreSqlFileserverReclamationIntegrationTest.java:174`가 본다. +- **고치는 법**: 이름을 단언 범위로 줄이거나, 동어반복 테스트를 지운다. +- Low · P3 · E1. + +#### RR-03-08 정산 job을 다시 claim해도 시도 횟수가 오르지 않는다 + +- **위치**: `JdbcReconciliationJobStore.java:56-72`(claim은 fence만 올린다), `:77`(`attempts`는 reschedule에서만 오른다). +- **무엇**: 워커가 같은 job에서 매번 죽으면 lease(2분)마다 다시 claim된다. 시도 한도에 닿지 않는다. 같은 라운드의 fileserver reclaim은 시도 횟수를 올린다(`FileserverCleanupRepository.java:101`, "bounded by the same retry budget"). +- **고치는 법**: 만료된 lease를 다시 잡을 때 `attempts + 1`, 또는 `claim_fence`와 `attempts`의 차로 한도를 판단한다. +- Low · P3 · E1. + +#### RR-03-09 notification 엔티티의 변경 메서드가 public이 됐다 + +- **위치**: `persistence-notification/.../entity/DeliveryAttemptEntity.java:133,199,288`, `persistence-notification/CLAUDE.md:16`, 비교 `persistence-fileserver/.../entity/AssignedIdEntity.java:23`. +- **무엇**: 04-16 패키지 분할로 생성자·`completeWith`·`claimSuppressionSideEffect` 등이 public이 됐다. "entity never leaves the leaf"는 글로만 있다. 같은 라운드의 fileserver는 "leaf's public surface is a ceiling"으로 반대로 했다. 두 leaf가 "같은 규칙"이라 했지만 공개 범위 규칙은 다르다. +- **고치는 법**: `..notification.platform.entity..`를 leaf 밖에서 쓰지 못하게 ArchUnit 규칙을 둔다. +- Low · P3 · E1. + +#### RR-03-10 `FailureCategory.TRANSACTION_TIMEOUT`의 이름과 뜻이 다르다 + +- **위치**: `persistence-jpa/.../api/error/FailureCategory.java:46-52`. +- **무엇**: 이 범주는 이제 25P03(idle 세션 종료)만 뜻하고 재시도 가능 코드로 간다. 실제 트랜잭션 시간 초과(Spring 마감)는 `QUERY_TIMEOUT`/`DB_QUERY_CANCELED`다. 이름만 보면 "트랜잭션 timeout은 재시도 가능"으로 읽힌다. 라이브러리 예외 `TransactionTimeoutException`도 같은 뜻이다. +- **고치는 법**: 공개 API(`jpa-api-surface.txt`)라 이름 변경은 호환성 비용이 있다. 지금은 Javadoc 첫 문장에 "Spring 트랜잭션 timeout이 아니다"를 적고, 다음 호환성 깨짐 때 `IDLE_IN_TRANSACTION_TIMEOUT`으로 바꾼다. +- Low · P3 · E1. + +## Declined to judge + +- V20의 `ADD COLUMN … CHECK`가 기존 행 검사를 위해 테이블을 한 번 읽는지 — 실측하지 않았다. outbox는 reaper로 크기가 묶여 있어 영향이 작을 것으로 본다. +- V12 생존 규칙이 `scope`·`notification_category`를 보지 않는 것 — 중복은 같은 webhook 경쟁에서 생겨 두 행의 scope가 같을 것으로 보지만 실제 데이터로 확인하지 않았다. 키는 수정 전 finder와 같은 `(tenant, target, reason)`이다. +- V11 배포 중 옛 인스턴스의 autocommit claim이 잠시 남는 것 — 배포 절차 문제이고 모든 인스턴스가 바뀌면 사라진다. +- `JpaTransactionManager`에서 커밋 중 연결 단절 — cause chain을 걷는 구현이라 같은 결과로 보지만 실행하지 않았다(04-01 한계로 적음). +- `afterCommit` 콜백 실패가 커밋 단계로 분류돼 "결과 불명"이 되는 경우 — 실제로는 커밋된 뒤라 안전한 쪽이다. +- `JpaVersionedBulkUpdateRule`이 `JdbcTemplate` 문자열 SQL을 보지 않는 것 — 지금 `JdbcTemplate` UPDATE 대상(정산 job 등)에는 `@Version` 엔티티가 없어 위반이 없다. +- 30초 기본 제한이 긴 작업을 끊는지 — outbox relay는 publish를 트랜잭션 밖에서 한다(`PublishPendingOutboxEventsUseCase.java:109,148,202,241,264`). 나머지 `inWrite` 호출처 약 50곳은 전수 확인하지 않았다. +- `HikariPoolConstraintValidator`가 `"2"` 같은 숫자 표기를 거부하는 것 — 엄격한 쪽이라 결함으로 보지 않는다. +- grpc-ledger `V002` — 읽기만 했다. 빈 테이블 전제와 `CONCURRENTLY` 수동 절차가 주석에 있고 삭제 쿼리 조건과 부분 인덱스 조건이 맞다. +- 04-09·09-02의 sample 코드 — sample 영역이라 마이그레이션과 예외 변환만 봤다. + +## 28개 관점 — 바뀐 관점만 + +| 관점 | 원래 | 지금 | 이유 | +|---|---|---|---| +| 5 위험 가시성 | X | P | claim 잠금·bulk version·`mappedBy` 양방향이 코드와 규칙으로 드러났다. 남음: 두-owner 양방향 통과(RR-03-04), 없는 재시도를 약속하는 Javadoc(RR-03-01) | +| 6 실패 성숙도 | X | P | 커밋 결과 불명·버전 충돌·시간 제한이 처리됐다. 남음: Hibernate 마감 초과 500(RR-03-03), counter 경쟁 409(RR-03-01) | +| 26 Ownership | P | O | 분리 leaf 두 곳에 가까운 `CLAUDE.md`가 생겼다. PG 테스트가 persistence-jpa에 남은 이유와 위치가 문서에 있다 | + +## Assessment + +**Ready to merge? With fixes.** + +원래 High(04-01·04-02)와 P1(04-03·04-04)은 코드와 실 DB 테스트로 닫혔다(04-03은 빈틈 하나). 다만 06-07 수정으로 들어온 순서 번호 counter가 첫 생성 경쟁에서 정상 쓰기를 409로 거절하고(RR-03-01, E3) 이행 때 번호를 되돌리므로(RR-03-02, E3), 벽시계 번호를 쓰던 서비스에 배포하기 전에 두 건을 고친다. RR-03-03·04는 같은 묶음에서 고치는 것이 싸다. diff --git a/docs/reviews/2026-11-03-rereview/04-outbound-capabilities.md b/docs/reviews/2026-11-03-rereview/04-outbound-capabilities.md new file mode 100644 index 00000000..4237c994 --- /dev/null +++ b/docs/reviews/2026-11-03-rereview/04-outbound-capabilities.md @@ -0,0 +1,210 @@ +# 04 outbound capability 재리뷰 (2026-11-03) + +## 범위 + +- 리뷰 범위: Base `01a8a2a70` → Head `5786126c`. 경로는 `src/`를 생략한다. +- 본 pathspec: `adapter/outbound/{support, identifier, redis-runtime, redis-sdk, cache-redis, httpclient, objectstorage, notification, fileserver}`, `docs/{httpclient, notification, fileserver}`, `infra/redis-sdk`, `infra/minio`. 238파일, +8,942 −1,682. +- 발견 ID: 원 리뷰 `05-outbound-capabilities.md`의 05-01~05-23. 고친 코드가 pathspec 밖(`application-notification`, `application-fileserver`, `web-fileserver`, `persistence-fileserver`)에 있는 발견은 그 줄을 읽어 상태만 판정했다. 그 파일의 diff 전체는 다른 영역 몫이다. + +### 불러온 스킬과 적용한 기준 + +| 스킬 | 적용한 기준 | 본 것 | +|---|---|---| +| `superpowers:requesting-code-review` | 리뷰어 템플릿(계획 정렬, 새 결함, Declined to judge, 읽기 전용, 하위 에이전트 금지) | 출력 양식 전체 | +| `performance-optimization` | 연결 pool 고갈 신호, "pool을 키우기 전에 누가 연결을 잡는지 찾는다", timeout이 대기열을 숨기는지 | Redis SCRIPT lane 공유(RR-04-02), 실패 뒤 연결 폐기로 생기는 재연결, rate-limit 대기 상한 | +| `observability-and-instrumentation` | 실패 원인이 신호에 맞게 남는지, health 상태 순서, 원인이 다른 실패를 같은 신호로 세지 않는지 | breaker가 호출자 deadline 중단을 상대 장애로 셈(RR-04-01), `DEGRADED` 순서, MinIO 공급 실패 메시지, JDK 스트림의 미분류 `IOException`(RR-04-03) | +| `security-and-hardening` | 자원 남용 상한(DoS), 인가 회귀 방지, 비밀값, replay 창, 공급망 | 파일 서버 쿼터·소유자 검사(RR-04-04), SNS replay 창 1h, MinIO 커뮤니티 fork digest·mirror override, ACL probe | + +### 실행한 명령 + +| 명령 | 결과 | +|---|---| +| `git diff --stat/--numstat 01a8a2a70..5786126c -- ` | 238파일. leaf별 변경 규모 확인 | +| `git worktree add /rr-04 5786126c` 후 임시 테스트 3개를 넣고 `flock … ./gradlew :adapter:outbound:httpclient:test --tests '…Rr*ProbeTest' --console=plain -i` | 아래 세 줄. 모두 BUILD SUCCESSFUL | +| `RrStreamingBodyProbeTest`: 헤더 즉시, 본문 30바이트를 100ms마다 1바이트(약 3초), 기본 timeout(response-header 2s, read-idle 3s, total 4s) | APACHE `bytesRead=30 elapsedMs=2994 COMPLETED`. **JDK `bytesRead=20 elapsedMs=2010 FAILED IOException: closed`** | +| `RrDeadlineBreakerProbeTest`: 600ms 뒤 200을 주는 건강한 서버, breaker 창 5, 호출자 deadline 200ms로 5회 → 예산 넉넉한 호출 1회 | APACHE·JDK 모두 5회 `HttpDeadlineExceededException` 뒤 **`HttpCircuitOpenException`**, 서버 요청 수 5 | +| `RrDeadlinePostProbeTest`: 비멱등 POST, 서버 800ms 지연, 호출자 deadline 300ms | APACHE·JDK 모두 `HttpAmbiguousExecutionException`, evidence `SENT_NO_RESPONSE` (기대대로) | +| `javap -c` Spring 7.0.9 `JdkClientHttpRequest$TimeoutHandler`(Gradle cache jar) | timeout이 끝나면 응답 future를 취소하고 본문 stream을 닫는다. timer는 stream `close()`에서만 취소된다 | +| `git worktree remove --force /rr-04` | 임시 테스트와 함께 삭제 | + +### 못 본 것 + +- 전체 게이트는 다시 돌리지 않았다(README 16.2 결과를 읽기만 했다). +- Redis 컨테이너 lane, Redis topology lane, MinIO 계약·fault lane, Toxiproxy lane, PostgreSQL lane은 실행하지 않았다. +- SCRIPT lane 경합(RR-04-02)과 move 쿼터 우회(RR-04-04)는 코드와 설정 숫자로만 판정했다(E1). +- 다중 인스턴스 경쟁, 실제 SES/SMTP 발송, TLS 소켓을 공용 타이머 스레드에서 닫을 때의 지연은 보지 않았다. +- `application-*`, `web-fileserver`, `persistence-fileserver`의 diff 전체는 읽지 않았다. 발견 판정에 필요한 줄만 읽었다. + +## Strengths + +- Redis 연결 실패가 "보내지 않음"으로 분류된다. 연결을 여는 단계의 실패를 `RedisLaneUnavailableException`으로 감싼다(`redis-runtime/.../RedisRuntimeOwner.java:245`). 대기가 끝난 lease는 pool에 돌려주지 않고 버린다(`cache-redis/.../SemanticRedisCall.java:146-155`). +- renew가 자기 Lua 프로그램을 갖는다(`IdempotencyScripts.java:145-181`). 잃어버린 응답의 재시도는 "시작 revision + 요청 lease"가 같을 때만 `ALREADY`다. lease가 다르면 `OPERATION_CONFLICT`라 호출자가 갖지 않은 lease를 가졌다고 믿지 않는다. +- revision 순서가 포트(`CacheRecordMetadata`)에서 정해지고, Lua 사본(`CacheScripts.java:56`)과 fake 사본을 `CacheRegionContract`가 fake와 실 Redis 양쪽에서 같은 표로 묶는다. +- HTTP 결과 불명 판정이 재시도 규칙보다 먼저다(`DefaultRetryEligibilityEngine.java:32`). 비멱등 POST가 호출자 deadline으로 잘려도 `HttpAmbiguousExecutionException`이 난다(위 probe, E3). +- Apache가 쓰기 시작 시점을 알린다(`SignallingRequestExecutor`). TLS·connect 실패가 더는 "보냈을 수 있음"이 되지 않는다. 401 토큰 갱신은 재시도가 허락될 때만 한다(`DefaultGenericHttpGateway.java:258`). +- 설정 실수를 기동에서 막는다. 0 timeout(`ClientProfileValidator.java:138`), `max-attempts` 상한 5(`:265`), breaker 범위 검사, 동작 없던 키 6개 삭제, 이름 없는 예산도 profile 단위로 제한(`RestClientRuntimeFactory`). +- MinIO 이미지 참조가 evidence 파일 한 곳이다. mirror override는 같은 digest만 받는다(`MinioQualificationImage.java`). compose 기본값을 테스트가 대조한다(`ComposeMinioImageMatchesEvidenceTest`). evidence의 측정 4줄을 lane이 매번 단언한다(`MinioManagedObjectContractTest.java:125,212`). +- S3 mutation의 5xx를 `INDETERMINATE`로 바꿨다(`S3ProviderErrorMapper.java:69`). 쓰기 뒤 5xx를 "반영 안 됨 확정"으로 읽지 않는다. +- SMTP 실패가 reply code·연결 거절·인증 실패로 나뉜다(`JavaMailSenderSmtpDispatch.java:68-104`). 근거가 없으면 보수적으로 "commit됨"을 유지한다. +- module-defaults 파일명·키 중복이 기동을 멈춘다(`ModuleDefaultsEnvironmentPostProcessor.java:65,84`). strict binder가 list 원소 둘째 단계 이하 오타도 거부한다(`StrictSettingsBinder.java:281-389`). 낮은 우선순위 출처의 list 원소는 예전처럼 봐준다. +- 파일 copy가 업로드와 같은 admission·쿼터 예약·대상 namespace 허용 목록을 거친다(`CopyFileApplicationUseCase.java:91-136`). + +## 발견 재확인 표 + +| ID | 상태 | 근거 | +|---|---|---| +| 05-01 | 닫힘 | factory가 `ProviderExecutionEvidence.undetermined()`로 행을 만든다(`DeliveryAttemptFactory.java:60`). requeue는 PROVEN+false만(`LeaseRecoveryService.java:101-144`) | +| 05-02 | 닫힘 | 전용 `RENEW` Lua(`IdempotencyScripts.java:145-181`), `RedisIdempotencyStoreAdapter.java:185-210`. 실 Redis renew는 `LiveRedisSemanticPortsTest.java:452`가 mainCheck lane에서 본다. 계약 클래스 전체는 게이트 밖(RR-04-05) | +| 05-03 | 닫힘 | `REPLACE_IF_REVISION_NEWER`(`CacheScripts.java:56`), 의도별 분기(`RedisCacheRegionAdapter.java:268-338`), `CacheRegionContract.java:151-195` | +| 05-04 | 닫힘 | 무효화 marker(`RedisCacheRegionAdapter.java:356,409-425`), miss도 condition 반환, stampede 보호 없음 문서화, CLAUDE.md jitter 문장 삭제. 새 부작용은 RR-04-02 | +| 05-05 | 닫힘 | `CircuitBreakerStatusPolicy`(5xx·408·429만), RETURN_RESULT 5xx 집계, profile별 breaker 키. 새 결함 RR-04-01 | +| 05-06 | 닫힘 | `AttemptDeadline` scope, Apache cancel(`DeadlineAwareApacheRequestFactory.java:30`), JDK·Jetty 상한, Toxiproxy lane을 mainCheck에(`httpclient/build.gradle` mainCheck). JDK 스트리밍 본문 문제는 RR-04-03 | +| 05-07 | 닫힘 | copy에 admission·쿼터·허용 목록(`CopyFileApplicationUseCase.java:91-136`), `namespace-limit` 신설. move 경로 우회는 RR-04-04 | +| 05-08 | 닫힘 | `FakeFileAccessPolicy`가 descriptor 소유자를 검사(`FakeFileAccessPolicy.java:38-46`), copy·move 소유자 거부 테스트(`FileLifecycleUseCasesTest.java:321,434`) | +| 05-09 | 결정으로 닫힘 | 15절 결정(`pgsty/minio` digest). 참조 한 곳, digest 고정 mirror override, `PinnedImageUnavailableException`, compose 대조 테스트 | +| 05-10 | 닫힘 | collapse 검사가 attempt 전 `failBeforeAttempt` 경로(`NotificationDispatchService.java:186-191`) | +| 05-11 | 닫힘 | SMTP 분류(`JavaMailSenderSmtpDispatch.java:76-104`), SES 사전 오류를 `ProviderCallNotStartedException`으로(`SesNotificationProviderAdapter.java:147-155`, `SesRequestMapper.java:93`). 작은 결함 RR-04-11 | +| 05-12 | 닫힘 | PATCH가 append 결과로 응답, status 재조회 삭제(`TusController.java:183-198`) | +| 05-13 | 닫힘 | cleanup 기본 on(`FileserverPlatformSettings.java` Cleanup, `fileserver.yml:101`), 끄면 WARN(`FileserverCleanupDisabledConfiguration.java:36`) | +| 05-14 | 닫힘 | 결과 불명 우선(`DefaultRetryEligibilityEngine.java:32`), `RequestWriteSignal`, 더 구체적 evidence 유지(`BlockingAttemptExecutor` `withMoreSpecificEvidence`). probe로 POST deadline 중단도 확인(E3) | +| 05-15 | 닫힘 | 키 6개 삭제, 0 timeout 거부, `max-attempts` 상한, 이름 없는 예산 제한, binder list 원소 검사 | +| 05-16 | 부분 | 계약이 포트 소유 testFixtures로 이동(notification·fileserver·objectstorage·cache·idempotency), Redis 컨테이너 lane·Toxiproxy lane이 mainCheck에. 남음: `LiveRedisIdempotencyStoreContractTest`가 어느 게이트 lane에도 없음(RR-04-05), SES/SMTP 실제 벤더 테스트 없음(GreenMail 등 0건) | +| 05-17 | 부분 | 연결 실패 → notSent, 실패 lease 폐기, rate-limit 대기 상한. 남음: 새 연결 열기는 caller deadline이 아니라 connect timeout 2s로 묶임(코드 주석에 명시, `RedisEdgeRateLimitAdapter.java:123-127`). 폐기가 SCRIPT lane 재연결을 늘린다(RR-04-02) | +| 05-18 | 부분 | Redis prefix 예외는 결정으로 닫힘(`cache-redis/CLAUDE.md` 예외 절). notification `@Value` 기본값 중복은 남음: `NotificationCallbackMvcController.java:59`(`65251`), `NotificationSubmissionConfiguration.java:91`(`ko-KR`). 같은 값이 settings·yml에도 있다(세 벌) | +| 05-19 | 닫힘 | 권한 매핑이 각 module-defaults로(`notification.yml:29-33`, `fileserver.yml:24-27`), `security.yml:32`에는 설명만 | +| 05-20 | 닫힘 | replay 창 기본 1h(`SesCallbackAdapter.SNS_HTTP_RETRY_HORIZON`), 인증서 실패는 `CallbackVerificationUnavailableException` | +| 05-21 | 부분 | README·CLAUDE.md 갱신, RFC 4231 벡터 테스트, 안 쓰는 edge 삭제. 합친 뒤 `package-info.java`가 다시 내용과 어긋남(RR-04-06) | +| 05-22 | 닫힘 | finalize가 writer lease를 잡고 token으로 해제(`FinalizeUploadApplicationUseCase.java:56-62`) | +| 05-23a | 닫힘 | 선언 길이 0이면 첫 바이트 거절(`LocalBlockingContentStore.java:146-147`) | +| 05-23b | 닫힘 | mutation 5xx → `INDETERMINATE`, PUT 재시도 불가 이유 주석(`S3AsyncClientFactory.java:38-42`) | +| 05-23c | 닫힘 | DROP 결과 저장(`NotificationSubmissionService.java:208,231`) | +| 05-23d | 닫힘 | 파일명·키 중복 기동 실패(`ModuleDefaultsEnvironmentPostProcessor.java:60-93`) | +| 05-23e | 닫힘(조건부) | `management.endpoint.health.status.order`(`cache-redis.yml:86`). 순서는 cache-redis가 싣고 상태는 redis-runtime이 낸다(RR-04-10) | +| 05-23f | 닫힘 | dedup 기본 off, 켜면 조립 거부(`RateLimitPolicy.java:36-38`, `RedisEdgeRateLimitAdapter.java:76-89`) | +| 05-23g | 닫힘 | 재시도 허락 뒤에만 토큰 갱신(`DefaultGenericHttpGateway.java:258-262`) | + +회귀로 판정한 발견은 없다. 다만 수정이 새 결함을 만든 발견이 넷이다(05-04·05-17 → RR-04-02, 05-05+05-06 → RR-04-01, 05-06 → RR-04-03, 05-07 → RR-04-04). + +## Issues + +### Critical (Must Fix) + +없음. + +### Important (Should Fix) + +#### RR-04-01 호출자 deadline으로 끊은 시도를 breaker가 상대 장애로 센다 + +- 위치: `httpclient/.../resilience/AttemptResiliencePipeline.java:111-113`, `restclient/BlockingAttemptExecutor.java:114`(pipeline 호출), `:218-235`(`finish`), `apache/DeadlineAwareApacheRequestFactory.java:30`. +- 무엇이 틀렸나: 05-06 수정으로 진행 중 시도가 deadline에서 취소된다. 취소된 시도는 엔진 예외로 pipeline을 빠져나간다. pipeline은 모든 예외를 `circuitBreaker.onError`로 기록한다. `finish()`가 결과를 `DEADLINE_EXCEEDED`로 바꾸는 것은 그 뒤다. 그래서 breaker는 "상대 장애"로 이미 셌다. `finish()` 주석 자신이 "deadline 중단을 transport 장애로 보고하면 건강한 상대를 오판한다"고 적는데, breaker에는 그 구분이 없다. +- 왜 중요한가: `HttpOperation.deadline()`으로 남은 요청 시간을 넘기는 호출자가 있으면, 정상 응답 시간보다 예산이 짧은 호출이 쌓여 circuit이 열린다. 열리면 그 profile의 모든 호출이 기본 60초 동안 거절된다. 05-05와 같은 피해(상대는 정상인데 기능 전체가 멈춤)다. 05-06 전에는 응답이 늦게라도 도착해 성공으로 기록됐다. 이 수정이 만든 동작이다. +- 증거: E3. `RrDeadlineBreakerProbeTest` — 600ms에 답하는 서버, 창 5, deadline 200ms 호출 5회 뒤 예산 넉넉한 호출이 Apache·JDK 모두 `HttpCircuitOpenException`. 서버는 요청 5개만 받았다. +- 고치는 법: 시도 scope가 만료돼 끝난 실패는 breaker에 기록하지 않는다(Resilience4j `releasePermission()` 또는 ignore). 판정은 `AttemptDeadline.Scope.expired()`로 pipeline 안에서 한다. profile `total-call`로만 끝난 경우를 계속 실패로 셀지는 따로 정해 주석에 남긴다. 위 probe를 회귀 테스트로 둔다. +- 가이드 심각도·우선순위: Medium / P1 (호출자가 deadline을 넘길 때만 도달, 도달하면 High와 같은 피해). + +#### RR-04-02 캐시 조건부 쓰기가 멱등성·rate-limit·lease와 8개짜리 SCRIPT lane을 나눠 쓴다 + +- 위치: `cache-redis/.../cache/RedisCacheRegionAdapter.java:135-136,262-268`, `README.md:183-187`. lane 공유: `RedisIdempotencyStoreAdapter.java:88`, `RedisEdgeRateLimitAdapter.java:71`, `RedisDistributedLeaseAdapter.java:85`. 크기: `redis-runtime/.../RedisRuntimeSettings.java:458`(`maximum-script-connections` 8). 실패 lease 폐기: `SemanticRedisCall.java:146-155`. +- 무엇이 틀렸나: 05-03·05-04 수정 뒤 write condition이 있는 기록은 모두 SCRIPT lane으로 간다. README가 권하는 정상 사용(조회가 준 condition으로 기록)이 곧 모든 캐시 채우기다. 그 lane은 pod당 연결 8개이고, 같은 lane에서 멱등성 claim과 요청 경로의 rate-limit이 돈다. lease는 호출마다 연결 하나를 독점한다. 또 05-17 수정으로 시간 초과(캐시 200ms)된 lease는 버려진다. 다음 호출은 새 연결을 연다. 새 연결은 caller deadline이 아니라 connect timeout 2s로 묶인다. +- 왜 중요한가: Redis가 느려지거나 region 무효화로 미스가 몰리면 캐시 채우기가 8개 연결을 차지한다. 그동안 멱등성 claim은 최대 2s 기다리다 `UNAVAILABLE`로, rate-limit은 deadline까지 기다리다 실패 정책으로 간다. 시간 초과마다 연결을 닫고 다시 열어 느린 Redis에 재연결 부하가 더해진다. 캐시는 "끊겨도 되는" 기능인데 정확성 기능을 굶긴다. README·CLAUDE.md 어디에도 이 공유가 적혀 있지 않다. 개발자가 따로 기억해야 하는 숨은 위험이다. +- 증거: E1(코드와 기본값). 실측하지 않았다. +- 고치는 법: 셋 중 하나를 고르고 버린 대안을 README에 남긴다. (a) 캐시 전용 script lane(별도 permit), (b) 캐시 조건부 쓰기에 SCRIPT lane permit 상한을 따로 둔다(예: 8 중 2), (c) 캐시 계정에 해당 script 권한만 주고 REGULAR lane에서 돈다. 어느 쪽이든 lane 대기·거절 수를 lane별 metric으로 낸다. 시간 초과 lease 폐기는 유지하되 재연결 횟수를 metric으로 본다. +- 가이드 심각도·우선순위: Medium / P2. + +#### RR-04-03 JDK transport 스트리밍 본문이 response-header timeout(2s)에서 잘린다 — 문서와 반대 + +- 위치: `httpclient/.../jdk/DeadlineAwareJdkRequestFactory.java:41`, `restclient/BlockingStreamingGateway.java:76-82`, `README.md:42-44`, `docs/httpclient/configuration-reference.md:103-105`. +- 무엇이 틀렸나: JDK factory는 Spring `JdkClientHttpRequest`의 read timeout을 `min(response-header, 남은 deadline)`으로 둔다. Spring 7.0.9의 이 timeout은 교환 전체에 걸린다. 끝나면 응답 future를 취소하고 본문 stream을 닫는다. timer는 stream을 닫을 때만 멈춘다. 그래서 스트리밍 다운로드는 헤더를 받은 뒤에도 2s(또는 남은 예산)에 끊긴다. 이번 diff가 추가한 문서는 "넘겨받은 뒤 본문은 gap마다 read-idle로만 묶인다, 긴 다운로드를 임의의 총 시간에서 자르지 않는다"고 적는다. Apache에서만 참이다. 끊길 때 호출자는 분류되지 않은 `IOException: closed`를 받는다. +- 왜 중요한가: JDK profile로 2초 넘는 다운로드는 항상 실패한다. 오류도 `HttpClientException` 계층이 아니라 원인 분류·로그 필드가 없다. 길이가 2초 근처인 다운로드는 간헐적으로 실패해 원인을 찾기 어렵다. +- 증거: E3. `RrStreamingBodyProbeTest` — Apache 30/30바이트 2,994ms 완료, JDK 20/30바이트 2,010ms `IOException: closed`. `javap`로 Spring `TimeoutHandler` 동작 확인. 기존 `StreamingSetupDeadlineTest`는 setup만 보고 본문 길이는 보지 않는다. +- 고치는 법: (a) JDK 스트리밍 요청은 read timeout을 걸지 않고 setup은 `AttemptDeadline` abort(응답 future 취소)로 묶는다. 본문 gap은 JDK가 못 재므로 "JDK 스트리밍은 gap 상한 없음"을 문서에 적는다. (b) JDK profile의 스트리밍을 기동에서 거부한다. 어느 쪽이든 README·configuration-reference의 문장을 transport별로 고치고, 위 probe를 transport별 계약 테스트로 둔다. 본문 stream 실패는 stable 예외로 감싼다. +- 가이드 심각도·우선순위: Medium / P2. + +#### RR-04-04 파일 move가 namespace 쿼터 상한을 우회하고, 쿼터 장부를 어긋나게 한다 + +- 위치: `application-fileserver/.../lifecycle/MoveFileApplicationUseCase.java:36-60`(쿼터 의존 없음, `relocate`만), `cleanup/DefaultCleanupService.java:311`(삭제 때 현재 namespace에서 회수), `persistence-fileserver/.../JpaFileQuota.java:85-96`(사용량 = 예약 장부 합), `docs/fileserver/configuration.md:131-136`. +- 무엇이 틀렸나: 쿼터 사용량은 namespace별 예약 장부의 합이다. move는 레코드의 namespace만 바꾸고 장부는 옮기지 않는다. 그래서 (1) 목적지 B는 옮겨 온 바이트를 세지 않는다. 상한 B를 꽉 채운 뒤에도 기본 namespace에 올리고 B로 옮기면 B가 상한을 넘는다. (2) 출발지 A는 떠난 파일을 계속 센다. (3) 옮긴 파일을 지우면 cleanup이 B 장부에서 회수한다. B의 다른 행이 깎이고(바닥 0), A는 영영 줄지 않는다. +- 왜 중요한가: 이번 diff가 `namespace-limit`을 "한 namespace가 가질 수 있는 최대 바이트"로 문서화했다. `target-namespaces`와 `namespace-limit`을 함께 켜는 배포에서 그 약속이 깨진다. 시간이 지나면 A는 실제로 비었는데 `QUOTA_EXCEEDED`로 업로드를 거절하고, B는 상한을 넘는다. 05-07의 목적(쓰기 자원 남용 상한)이 move로 빠져나간다. +- 증거: E1. `MoveFileApplicationUseCase` 생성자에 `FileQuotaPort`가 없다. 실행 재현은 하지 않았다. +- 고치는 법: move를 한 트랜잭션에서 "B에 `requireRoom` + 예약·commit, A에서 같은 바이트 reclaim"으로 바꾼다. 또는 move를 같은 namespace 안의 이름 변경으로 좁히고 namespace 간 이동은 copy+delete로 하게 한다. 고른 쪽을 문서에 적고, "B 상한을 move로 넘을 수 없다"와 "옮긴 뒤 A 사용량이 준다" 테스트를 둔다. +- 가이드 심각도·우선순위: Medium / P2 (두 설정을 함께 켤 때만 도달). + +#### RR-04-05 Redis 멱등성 계약의 실서버 실행이 어느 게이트에도 없다 + +- 위치: `cache-redis/build.gradle:57-64`(topology lane에만), `:76-86`(`redisContainerContractTest`의 `requires`에 없음), `cache-redis/CLAUDE.md:131-137`. +- 무엇이 틀렸나: `requires`는 lane이 돌릴 클래스를 거르는 필터다(`StrictTestLanePlugin.java:216-219`). 컨테이너 lane은 캐시·lease 계약, `LiveRedisSemanticPortsTest`, ACL probe만 돈다. `LiveRedisIdempotencyStoreContractTest`는 explicit-only topology lane에만 있다. r3-B(계약 추가)와 r3-C(컨테이너 lane 추가)가 따로 작업하고 합쳐진 틈으로 보인다. +- 왜 중요한가: 05-02의 원인은 "fake가 Lua의 버그를 따라 함"이었다. fake에는 Lua 상태 기계의 Java 사본이 있다(`InMemorySemanticRedisCommands.java:284-322`). 지금 실서버로 게이트에서 확인되는 멱등성 경로는 claim 경합·서버 시간·renew 정상 경로 세 개뿐이다. stale handle의 `NOT_OWNER`, `CLAIMED` 상태 renew 거부, complete·markFailed·release 재시도 같은 계약 케이스는 fake 사본에서만 돈다. 두 사본이 갈라져도 ci·mainCheck·integrationCheck가 초록이다. +- 증거: E1(빌드 파일과 lane 필터). +- 고치는 법: `redisContainerContractTest`의 `requires`에 `LiveRedisIdempotencyStoreContractTest`를 넣고 CLAUDE.md 목록을 맞춘다. 계약이 실서버에서 1초 lease를 기다리므로 lane 시간이 늘어나는지 한 번 잰다. +- 가이드 심각도·우선순위: Medium / P2. + +### Minor (Nice to Have) + +#### RR-04-06 identifier leaf 문서가 합친 뒤 다시 내용과 어긋난다 + +- 위치: `identifier/src/main/java/.../package-info.java:2`, `identifier/CLAUDE.md:27-33`, `README.md` HmacUserPrincipalPseudonymizer 절. +- 무엇: package-info는 "식별자 생성은 여기 없다"고 하는데 `UuidV7DurableOperationIdFactory`가 있다. CLAUDE.md Allowed에 `:domain-core`와 `uuid-creator`가 없다. README의 "checked exception을 `IllegalStateException`으로 감싼다"는 `HmacSha256` 위임 뒤 이 클래스 이야기가 아니다. 05-21 문서 수정(r2-05b)과 UUIDv7 추가(r2-06)가 따로 합쳐졌다. +- 고치는 법: 세 문서를 지금 두 클래스·세 의존에 맞춘다. +- 심각도·우선순위: Low / P3. 증거 E1. + +#### RR-04-07 캐시 전용 ACL probe가 연결 중 끊김을 "권한 설정 오류"로 보고 기동을 멈춘다 + +- 위치: `cache-redis/.../capability/RedisSemanticScriptAclProbe.java:92-109,137`. +- 무엇: "닿지 못함" 판정이 `RedisLaneUnavailableException`·`TimeoutException`뿐이다. 연결은 열렸지만 probe 중 끊김, Redis 재시작 중 `LOADING` 응답, Lettuce 재연결 중 거절은 `ExecutionException`이라 설정 오류로 간다. README는 "캐시 장애는 pod 기동을 멈추지 않는다"고 적는다. +- 고치는 법: `NOPERM`·`NOSCRIPT` 같은 권한 응답만 치명으로 보고 나머지 실패는 경고로 낮춘다. 테스트로 `LOADING` 응답 케이스를 둔다. +- 심각도·우선순위: Low / P3. 증거 E1. + +#### RR-04-08 Redis renew가 lease만 늘리고 key TTL은 늘리지 않는다 + +- 위치: `IdempotencyScripts.java:177-180`(RENEW에 `PEXPIRE` 없음), claim의 `PEXPIRE ARGV[7]`(`:44,77`, replay TTL). +- 무엇: renew로 lease를 replay TTL(`APP_IDEMPOTENCY_TTL`, 기본 24h, 짧게 둘 수 있음) 너머까지 늘리면 실행 중 key가 사라진다. 다음 요청은 새 claim(`ACQUIRED`)을 받아 같은 부작용을 다시 실행한다. PostgreSQL store에는 이 제약이 없어 두 구현의 계약이 다르다. 지금 템플릿 안 호출자는 없다. +- 고치는 법: RENEW에서 `PTTL < 새 leaseUntil - now`이면 `PEXPIRE`를 늘리거나, renew 요청을 거부한다. 계약에 "renew한 lease는 replay TTL보다 오래 살 수 있다" 케이스를 둔다. +- 심각도·우선순위: Low / P3. 증거 E1. + +#### RR-04-09 startup rule을 일찍 만드는 전제("static, 의존 없음")를 막는 장치가 없다 + +- 위치: `support/.../startup/StartupRuleRunner.java:65-66`, `StartupRule.java` Javadoc. +- 무엇: runner는 bean factory post-processor 단계에서 모든 rule bean을 `getBean`한다. 지금 rule은 모두 `static @Bean`이다. 파생 서비스가 non-static `@Bean` rule을 쓰면 그 설정 클래스와 생성자 의존(datasource 등)이 그 시점에 만들어진다. 07-02가 막은 "검사 전에 DB 연결"이 조용히 되살아난다. 규칙은 Javadoc에만 있다. +- 고치는 법: runner가 rule의 bean definition에 `getFactoryBeanName() != null`(non-static factory method)이면 기동을 실패시킨다. 테스트 1건. +- 심각도·우선순위: Low / P3. 증거 E1. + +#### RR-04-10 `DEGRADED` 정렬 순서를 상태를 내지 않는 leaf가 싣는다 + +- 위치: `cache-redis/src/main/resources/config/module-defaults/cache-redis.yml:78-87`, `redis-runtime/.../RedisRuntimeAutoConfiguration.java:71-72,276-286`. +- 무엇: `redisOptional`(`DEGRADED`)은 `app.redis.enabled=true`면 redis-runtime이 만든다. 순서 설정은 cache-redis에만 있다. redis-runtime을 `api`로 끌어오는 redis-sdk만 쓰는 조립에서는 05-23e가 그대로다. +- 고치는 법: 순서 키를 redis-runtime 쪽 기본값으로 옮긴다. redis-runtime에는 module-defaults가 없으니 `EnvironmentPostProcessor` 또는 문서화된 예외로 둔다. +- 심각도·우선순위: Low / P3. 증거 E1. + +#### RR-04-11 SMTP reply code 범위가 2xx·3xx까지 "거절"로 받는다 + +- 위치: `notification/.../smtp/JavaMailSenderSmtpDispatch.java:115`. +- 무엇: `200 <= code < 600`을 받는다. Angus `sendpartial` 경로의 `SMTPSendFailedException`은 마지막 성공 코드(250)를 싣는다. 이 값이 `SmtpFailureClassifier`에서 영구 거절로 기록된다. 지금은 수신자 1명이라 도달하기 어렵다(`SmtpMimeMessageFactory.java:69`). +- 고치는 법: `400 <= code < 600`만 reply code로 쓴다. 그 밖은 보수적 경로로 보낸다. +- 심각도·우선순위: Low / P3. 증거 E1. + +## Declined to judge + +- `AttemptDeadline`의 abort가 JVM 공용 `CompletableFuture` delay 스레드에서 Apache `cancel()`(소켓 닫기)을 돈다. TLS 소켓 닫기가 막히면 JVM 안 다른 timeout이 늦어질 수 있다. JDK·Apache 구현 확인과 실측이 필요해 판단하지 않았다. +- `pgsty/minio`(커뮤니티 fork)를 qualification 기준으로 삼는 공급망 위험. 15절 소유자 결정이고, digest 고정과 같은 digest mirror override로 완화돼 있다. +- SES replay 창 1h. 15절 결정이고 ledger 유일 제약이 중복을 막는다. 재전송 공격 면이 넓어진 정도는 판단하지 않았다. +- `namespace-limit`의 동시 예약 초과 허용. 15절 결정이며 문서에 적혀 있다. +- 시스템 env가 list 원소 하나를 덮으면 yml에 있던 같은 원소의 다른 필드가 조용히 사라지는 Spring의 list 통째 교체. 이번 diff 전부터 있던 동작이라 범위 밖으로 뒀다. +- 캐시 `invalidate`의 GET→SET 비원자성. 코드 주석에 고른 이유(덮어써도 무효화 의미가 같음, REGULAR lane 권한)가 있다. +- notification evidence verifier가 상위 계약 클래스를 따라가 테스트를 찾게 바뀐 것. 지정 root 밖은 따라가지 않아 fail-closed다. 문제 없다고 봤다. +- `application-*`·`web-fileserver`·`persistence-fileserver` diff 중 발견 판정에 쓰지 않은 부분. + +## 28개 관점 — 바뀐 관점만 + +| # | 관점 | 전 → 후 | 한 줄 이유 | +|---|---|---|---| +| 8 | 디버깅 가능성 | P → O | MinIO 공급 실패가 `PinnedImageUnavailableException`으로 구분되고, deadline 중단·evidence가 구체적으로 남는다. 예외: JDK 스트림의 미분류 `IOException`(RR-04-03) | +| 12 | 동시성 성숙도 | P → O | 발송 중 crash 재발송(05-01), renew(05-02), finalize lease(05-22)가 닫혔다. 쿼터 동시 초과는 결정으로 문서화 | +| 16 | 의존성 성숙도 | P → O | MinIO 공급원이 digest 고정 + mirror override로 복구됐고, Jackson 2는 결정으로 닫혔다 | +| 27 | 삭제 가능성 | P → O | 권한 매핑이 각 모듈 기본값으로 옮겨져 모듈 한 줄을 지우면 함께 사라진다(05-19) | +| 28 | 회복 가능성 | P → O | 증거 오기로 인한 재발송이 닫히고 정리 worker가 기본 on이다 | + +1·6·11·14·15·17·21번은 기호는 P 그대로이고 이유가 바뀌었다. 원래 이유는 대부분 닫혔고, 새 이유는 각각 RR-04-03(17), RR-04-01(6), RR-04-04(11·15), RR-04-02(14), RR-04-05(21)다. + +## Assessment + +**Ready to merge: With fixes.** 원 리뷰의 High·P1(05-01~05-09)은 모두 코드와 테스트로 닫혔고 회귀는 없다. 다만 05-06 수정이 breaker를 호출자 deadline으로 열게 만들었고(RR-04-01, E3), JDK 스트리밍이 문서와 반대로 잘린다(RR-04-03, E3). 이 둘과 RR-04-02·04·05는 파생 서비스가 HTTP client·Redis·파일 쿼터를 켜기 전에 고쳐야 한다. diff --git a/docs/reviews/2026-11-03-rereview/05-messaging.md b/docs/reviews/2026-11-03-rereview/05-messaging.md new file mode 100644 index 00000000..a2e1982b --- /dev/null +++ b/docs/reviews/2026-11-03-rereview/05-messaging.md @@ -0,0 +1,252 @@ +# 05 messaging 재리뷰 (2026-11-03) + +- 리뷰 범위: Base `01a8a2a70` → Head `5786126c`, 이 영역 pathspec 62파일(+3,798 −274). +- 원래 발견: `docs/reviews/2026-11-01-maturity-review/06-messaging.md`(06-01~06-09, NN-10~NN-14). +- 판정 기준: 리뷰 가이드 35절(심각도·우선순위·통제·증거), 36.3 양식, `AGENTS.md`·`CLAUDE.md`, `src/messaging/CLAUDE.md`, `src/adapter/inbound/messaging/CLAUDE.md`. + +## 범위 + +### 본 pathspec + +`src/messaging`, `src/adapter/outbound/messaging`, `src/adapter/outbound/messaging-kafka`, +`src/adapter/inbound/messaging`, `src/composition/outbox-relay`, `docs/messaging`, +`docs/runbooks/outbox-dead-letter.md`, `docs/runbooks/outbox-publish-failed.md`, +`docs/runbooks/migration-failed.md`, `docs/manual/09-outbox-events.md`. + +발견을 확인하려고 pathspec 밖의 다음 코드도 읽었다. 이 파일들의 diff 전체를 리뷰한 것은 아니다. + +- application-core: `application/outbox/**`(relay use case, outcome, backoff, `ClaimedOutboxEvent`, `OutboxStorePort`, `OutboxAggregateSequencePort`), `application/messaging/event/**`(`EventId`, `IntegrationIdentity`, `IntegrationEventDrafts`, `AggregateOrder`), `SubmitDurableOperationUseCase`. +- persistence-jpa: `JpaOutboxStore`, `OutboxEventJpaRepository`, `V20`, `V21`. +- support: `JsonIntegrationEventEncoder`(봉투·partition key). +- sample: `PortfolioEventOutbox`, `OutboxEventIdFactory`. +- `docs/registries/metrics.yaml` outbox 항목. + +### 불러온 스킬과 적용한 기준 + +| 스킬 | 적용한 기준 | 본 것 | +| --- | --- | --- | +| `superpowers:requesting-code-review` | 리뷰어 템플릿: Strengths → Issues(심각도별) → Assessment, Declined to judge, 읽기 전용, 하위 에이전트 금지 | 문서 구조 전체 | +| `domain-driven-design` | Anti-Corruption Layer는 바깥 모델의 의미를 안쪽 어휘로 번역한다. 통합 이벤트의 식별자·순서는 소비자 계약이다. 경계 맥락은 서로의 모델을 알지 않는다 | bridge의 `retryable` 번역(06-01), event id ↔ `MessageId`(06-06), aggregate 순서 번호가 소비자에게 보이는 계약인지(06-07), vendored 제품이 앱을 아는지(MSG-023) | +| `observability-and-instrumentation` | on-call 질문부터 정한다("이 행은 왜 계속 재시도하나", "인증 오류인가 종료 중 거부인가", "적체가 느는가"). 지표 label 집합은 고정한다. runbook의 첫 확인 절차가 실제로 동작해야 한다 | relay 실패 보고의 원인 정보, 게이지 갱신 경로, `outcome` label 값, DEAD runbook SQL | +| `doubt-driven-development` | 결과 불명 판단을 주장(CLAIM)으로 적고 반증을 시도한다 | 아래 다섯 주장. 하위 에이전트 금지(브리프)라 새 맥락 리뷰어 대신 자기 반증으로 했다(축소 적용). 비대화 실행이라 교차 모델 검토는 건너뛰었다 | + +반증을 시도한 주장과 결과: + +1. "retryable 거부·결과 불명은 DEAD가 되지 않으니 안전하다" → 일부 반증. 끝나지 않는 행을 구분·처분할 수단이 없다(RR-05-03). +2. "종료 중 claim된 행은 PUBLISHED 또는 lease 해제 상태로 남는다" → 반증 못 함. Spring 7.0.9 종료 순서와 맞는다(닫힘). +3. "V21 카운터는 옛 벽시계 번호 뒤에서 시작한다" → 반증. 옛 행이 지워졌거나 identity가 바뀌면 1부터 다시 시작한다(RR-05-02, 실 PG 재현). +4. "DEAD runbook 재발행 SQL로 행이 다시 발행된다" → 반증. `deferred_attempt_count`가 2 이상이면 행이 DEAD로 되돌아간다(RR-05-01, 실 PG 재현). +5. "게이지가 relay와 무관한 자기 주기로 갱신된다" → 일부 반증. relay와 같은 단일 스레드에서 줄을 선다(RR-05-05). + +### 실행한 명령과 결과 + +| 명령 | 결과 | +| --- | --- | +| `git diff --stat 01a8a2a70..5786126c -- `, `git diff ...` | 62파일. 나눠서 전부 읽었다 | +| `git worktree add /rr-05 5786126c` 후 worktree에서만 `PostgreSqlOutboxClaimAndMaintenanceIntegrationTest`에 실험 메서드 2개 추가 | 메인 작업 트리는 건드리지 않았다. 끝나고 `git worktree remove --force` | +| `flock ./gradlew :adapter:outbound:persistence-jpa:jpaPlatformContractTest --tests '*PostgreSqlOutboxClaimAndMaintenanceIntegrationTest.rr05RunbookRedrive*'` | 실 PostgreSQL. 예상대로 실패. `claimed=[] status=DEAD counts={attempt_count=1, deferred_attempt_count=2}`, WARN `outbox claim moved a row it cannot read to DEAD`, 원인 `deferredAttemptCount must be between 0 and attemptCount (1), was 2` (29초) | +| 같은 lane, `--tests '*rr05CounterSeed*'` | 통과(17초). `a(옛 행 남음)=1788000000000001`, `b(tenant scope 바뀜)=1`, `c(옛 행 지워짐)=1`, 옛 번호 `1788000000000000` | +| `javap -c -p` spring-context 7.0.9 `SimpleAsyncTaskScheduler`, spring-boot-autoconfigure 4.0.8 `TaskSchedulingConfigurations$TaskSchedulerConfiguration` | virtual thread가 켜지면(템플릿 기본 `true`, `app-bootstrap/.../application.yml:58`) Boot가 `SimpleAsyncTaskScheduler`를 만든다. fixed-delay 작업은 `fixedDelayExecutor`(core pool 1)에서 돈다. `ContextClosedEvent`에서는 `shutdown()`(실행 중 작업은 계속)이다 | + +게이트(`ci`·`mainCheck`·`integrationCheck` 등)는 README 16.2 기록을 따랐고 다시 돌리지 않았다. + +### 못 본 것 + +- Kafka lane(`messagingKafkaRelayIntegrationTest`, `messagingInboxRedeliveryIntegrationTest`)을 직접 실행하지 않았다. 코드와 README 16절 기록만 봤다. +- 실제 SIGTERM 종료 순서, 다중 인스턴스 동시 기동, 처리량을 측정하지 않았다. +- vendored admin·claim-check·schema·observability 내부, starter-kafka `KafkaConsumerRegistrar`는 이번 diff에 없어 보지 않았다. + +## Strengths + +- **종료 순서를 relay가 직접 소유한다.** `OutboxRelayScheduler`가 SmartLifecycle(phase `Integer.MAX_VALUE`)이 되어 platform admission(`MessagingShutdownLifecycle.PHASE`)보다 먼저 멈춘다(`composition/outbox-relay/.../OutboxRelayScheduler.java:40,150`). 진행 중 발행 하나만 끝내고 남은 claim은 `releaseLease`로 시도 횟수 없이 돌려준다(`application-core/.../PublishPendingOutboxEventsUseCase.java:123-127,143-155`). Spring 7.0.9의 `ContextClosedEvent → shutdown()` → lifecycle stop 순서와 맞는다. +- **순서 테스트가 platform 상수를 직접 쓴다.** `OutboxRelayShutdownOrderTest`가 MAX-1024를 복사하지 않고 `MessagingShutdownLifecycle.PHASE`를 compile-only로 참조한다(`composition/outbox-relay/build.gradle:32-39`). platform phase가 바뀌면 테스트가 깨진다. +- **ACL 번역이 정확해졌다.** bridge가 platform `retryable`을 `REJECTED_RETRYABLE`로 옮긴다(`PlatformIntegrationEventPublishAdapter.java:189`). AMBIGUOUS로 뭉개지 않은 이유(중복 경고 오염)가 README에 남아 있다. +- **재전송 id가 바뀌지 않는다.** bridge가 대문자·축약 표기 UUID를 다른 id로 바꿔 보내지 않고 거부한다(`PlatformIntegrationEventPublishAdapter.java:154-163`). 소비자 중복 제거 키가 깨지는 경로를 막았다. +- **시도 예산을 일시 실패와 분리했다.** `deferred_attempt_count`(V20)와 `budgetedAttemptCount()`(`ClaimedOutboxEvent.java:55`)로 예산은 분류되지 않은 예외에만 쓴다. 재시도 시각은 실패 시점 기준이다(`PublishPendingOutboxEventsUseCase.java:179,187,193`). V20은 기본값으로 기존 행을 다시 쓰지 않는다. +- **소비 경로를 실제 의존성으로 검증한다.** `InboxRedeliveryIntegrationTest`는 앱 relay → Kafka → platform consumer → inbox+JPA 한 트랜잭션을 실 Kafka·PostgreSQL로 돌린다. offset 되감기와 실패 재처리 둘 다 본다. inbox 중복 검사를 지우는 변이를 잡았다는 기록도 있다. +- **이 lane이 실제 결함을 찾았다.** inbound/outbound messaging leaf가 같은 Gradle 좌표라 bridge가 빠지던 문제를 group·jar 이름으로 고쳤다(`adapter/inbound/messaging/build.gradle:19-28`). +- **decode 등록을 코드가 막는다.** handler 선언으로 decode 목록을 만들고, 같은 계약에 다른 class를 선언하면 기동을 막는다(`MessageContracts.java:61-85`). 서비스가 등록을 잊어 메시지가 조용히 DLQ로 가는 숨은 위험이 사라졌다. +- **inbox 마이그레이션 위치를 고른 이유가 남아 있다.** primary location에 넣으면 V22가 out-of-order로 거부되는 이유와 explicit baseline을 쓴 이유가 코드 주석에 있다(`MessagingInboxSchemaStream.java:20-31`). + +## 발견 재확인 표 + +| ID | 상태 | 근거 | +| --- | --- | --- | +| 06-01 | 닫힘 | retryable REJECTED → `REJECTED_RETRYABLE`(`PlatformIntegrationEventPublishAdapter.java:188-190`). relay는 `markDeferred`로 예산 없이 재시도(`PublishPendingOutboxEventsUseCase.java:189-194`). Kafka 인증·인가는 retryable(`KafkaPublishFailureClassifier.java:43,75-76`). `PUBLISH_RUNTIME_UNAVAILABLE`·`KAFKA_TRANSPORT_CLOSED`도 retryable(`DefaultMessagePublisher.java:266-276`, `KafkaMessagingTransport.java:121-131`). 남은 위험은 RR-05-03 | +| 06-02 | 닫힘 | SmartLifecycle phase `MAX_VALUE`, `stop(Runnable)`이 진행 중 회차를 기다림(`OutboxRelayScheduler.java:150-162`). 남은 claim 해제(`OutboxStorePort.releaseLease`, `OutboxEventJpaRepository` `releaseLease`). 13절의 "lease 해제 없음"·"phase 하드코딩"도 해결 | +| 06-03 | 닫힘 | AMBIGUOUS·retryable 거부는 예산을 쓰지 않음. 지연 상한 5분(`OutboxBackoffPolicy.MAX_DELAY`). runbook 차단 범위 조회가 현재 FIFO 키(`outbox-dead-letter.md:27`). 단 같은 runbook의 재발행 SQL이 V20과 어긋난다(RR-05-01) | +| 06-04 | 닫힘 | 발행이 있으면 한 tick 안에서 다시 claim, 상한 50회차(`OutboxRelayScheduler.java:47,102-112`). README에 처리량 상한 숫자(`composition/outbox-relay/README.md` "한 tick이 claim 한 번이 아니다"). PG 카운트 테스트 대신 fake store 테스트(`OutboxRelaySchedulerDrainTest`) | +| 06-05 | 닫힘 | 게이지 갱신을 `@Scheduled refreshGauges`로 분리(`OutboxMetrics.java:91-94`). relay 꺼짐 WARN(`OutboxRelayOffWarning`). 실제 스케줄러로 relay-off 게이지 값을 단언(`OutboxMetricsTest.java:40-66`). 단 relay와 같은 스레드를 쓴다(RR-05-05) | +| 06-06 | 부분 | bridge는 정규 소문자 UUIDv7만 받게 엄격해졌다. 완료 기준인 "append(draft·encode) 시점 거부"는 없다. `EventId`는 여전히 `[A-Za-z0-9][A-Za-z0-9._:-]*`(`EventId.java:9`), durable operation digest 경로는 UUID가 아닌 id를 만든다(`SubmitDurableOperationUseCase.java:168-173`). bridge 주석·README도 "until it does"라고 미완을 인정한다(RR-05-04) | +| 06-07 | 닫힘 | sample이 `OutboxAggregateSequencePort`로 번호를 받는다(`PortfolioEventOutbox.java` append). V21 유일 인덱스로 같은 번호 두 번 append를 거부. 업그레이드 연속성은 RR-05-02 | +| 06-08 | 닫힘 | 새 leaf `adapter:inbound:messaging`(registry 등록), inbox 부품 조립, decode 목록 자동, V1101 별도 stream, 실 Kafka+PG 중복 전달 lane. application 소비 포트는 버린 대안으로 이유와 함께 기록(`adapter/inbound/messaging/README.md` "고른 방법과 버린 대안"). 예시 handler는 sample이 아니라 테스트에 있다 | +| 06-09 | 닫힘 | `messagingKafkaRelayIntegrationTest`(strict lane, `integration()`, skip 거부)가 relay → bridge → 실 Kafka 레코드 바이트를 비교. `:integrationCheck`는 `.github/workflows/integration-main.yml`에서 main push·nightly로 돈다 | +| NN-10~NN-14 | 미조치(색인 누락) | README 12절 색인에 06-01~06-09만 있다. NN-13은 부분(스케줄러·use case Javadoc은 고침, `OutboxLeaderElectionToken` 설명과 `CLAUDE.md` 부재는 남음). NN-10·11·12·14는 diff에 조치가 없다(RR-05-10) | + +회귀로 판정한 발견: 없음. RR-05-01은 06-03 자체의 회귀가 아니라 V20이 같은 변경 안에서 runbook SQL을 낡게 만든 새 결함이다. + +## Issues + +### Critical (Must Fix) + +없음. + +### Important (Should Fix) + +#### RR-05-01 — DEAD runbook의 재발행 SQL이 `deferred_attempt_count`를 되돌리지 않아 행이 다시 DEAD가 된다 + +- 위치: `docs/runbooks/outbox-dead-letter.md:46,48`. 관련 코드는 `application-core/.../ClaimedOutboxEvent.java:35-41`, `persistence-jpa/.../JpaOutboxStore.java:150-155`. +- 무엇이 틀렸나: + - runbook SQL은 `attempt_count = 0`만 쓴다. + - V20이 더한 `deferred_attempt_count`는 그대로 남는다. + - 다음 claim에서 `attempt_count`는 1이 된다. + - `ClaimedOutboxEvent`는 `deferredAttemptCount > attemptCount`이면 생성을 거부한다. + - claim은 그 예외를 "읽을 수 없는 행"으로 보고 행을 다시 DEAD로 옮긴다. +- 왜 중요한가: + - 발생 조건: DEAD 행의 `deferred_attempt_count`가 2 이상이다. 장애 중 두 번 이상 미뤄진 뒤 확정 거부나 예산 소진으로 DEAD가 된 행이 해당한다. 운영자가 장애 뒤 일괄 재구동할 행이 바로 이런 행이다. + - 영향: P1 incident의 유일한 복구 절차가 실패한다. aggregate는 계속 막힌다. + - 탐지가 어렵다. 로그는 `outbox claim moved a row it cannot read to DEAD`라고 말해 원인을 행 손상으로 오해하게 한다. 이 경로는 failure reporter를 거치지 않아 `OUTBOX_DEAD_LETTER` 보고와 `outcome=DEAD` 카운터도 다시 나오지 않는다. + - 증거: 실 PostgreSQL에서 runbook SQL을 그대로 실행해 재현했다. 결과는 `claimed=[]`, `status=DEAD`, `attempt_count=1`, `deferred_attempt_count=2`다. +- 고치는 법: + 1. runbook §4 두 SQL에 `deferred_attempt_count = 0`을 넣는다. + 2. V21 확인 쿼리처럼 §4 SQL에 `runbook-sql` 표지를 달고, PG lane(`PostgreSqlOutboxOrderKeyRunbookIntegrationTest`와 같은 방식)이 runbook에서 읽어 실행하게 한다. "재발행한 행이 claim된다"를 단언한다. + 3. 선택: DB에 `CHECK (deferred_attempt_count <= attempt_count)`를 둔다. 잘못된 수동 SQL이 claim 때 조용히 DEAD가 되는 대신 UPDATE 시점에 바로 실패한다. +- 가이드 심각도: Medium · 우선순위 P1 · 증거 E3(실 PG 재현) · 통제 M0(runbook SQL을 검사하는 장치 없음). + +#### RR-05-02 — 새 aggregate 카운터가 1부터 시작해 소비자가 보는 순서 번호가 업그레이드 때 뒤로 간다 + +- 위치: `persistence-jpa/.../OutboxEventJpaRepository.java:137`(`COALESCE(MAX(e.aggregate_sequence), 0) + 1`), `JpaOutboxStore.java:114-124`, `V21__outbox_aggregate_sequence.sql:9-11`, `sample-portfolio/.../PortfolioEventOutbox.java:38`(scope가 `portfolio` → `global`). +- 무엇이 틀렸나: + - 카운터가 없는 aggregate의 첫 번호는 "지금 outbox에 남은 행"의 최댓값 + 1이다. + - 옛 sample은 번호로 epoch 마이크로초(약 1.7×10^15)를 썼다. + - reaper가 PUBLISHED 행을 7일 뒤 지운다. 7일 넘게 조용했던 aggregate는 남은 행이 없다. 그래서 다음 번호가 1이다. + - sample은 같은 diff에서 tenant scope를 `portfolio`에서 `global`로 바꿨다. 옛 행은 다른 identity라 최댓값 계산에 들어가지 않는다. 모든 sample aggregate가 1부터 다시 시작한다. + - scope는 Kafka partition key 해시에도 들어간다(`JsonIntegrationEventEncoder.java:258-264`). 배포 전에 남은 `portfolio` 미발행 행과 배포 뒤 `global` 행은 서로 막지 않고 다른 partition으로 간다. +- 왜 중요한가: + - `AggregateOrder` 문서는 소비자가 이 번호를 "어느 변경이 마지막인가"로 읽는다고 적는다(`AggregateOrder.java:7`). 봉투에도 `aggregate.sequence`로 실린다. + - "마지막으로 본 번호보다 작으면 버린다"로 구현한 소비자는 업그레이드 뒤 그 aggregate의 이벤트를 모두 버린다. 템플릿이 권한 패턴이다. + - V21 주석의 의도("rows numbered by the old clock scheme still come first")가 옛 행이 남아 있을 때만 성립한다. 포트 계약(`OutboxAggregateSequencePort` Javadoc "greater than any number an earlier outbox row carries")도 지워진 행은 다루지 않는다. + - 증거: 실 PostgreSQL에서 `nextSequence`를 불렀다. 옛 행이 남은 경우 1788000000000001, scope가 바뀐 경우 1, 옛 행이 지워진 경우 1이다. + - scope를 `global`로 바꾼 것은 15절 결정(r2-01)이다. 결정을 뒤집자는 것이 아니라, 그 결정과 V21이 합쳐져 생긴 업그레이드 위험이다. +- 고치는 법: + - 새 카운터의 시작값을 `GREATEST(COALESCE(MAX(e.aggregate_sequence), 0), <현재 epoch 마이크로초>) + 1`로 둔다. 번호는 양수이고 커지기만 하면 되므로 비용이 없다. 옛 벽시계 번호는 그 시각 이전 값이라 새 번호가 항상 뒤에 온다. + - sample scope 변경은 "배포 전 `portfolio` 미발행 행을 비운다"는 절차를 sample README나 manual 09에 적는다. 또는 sample만 `portfolio`를 유지한다. + - 파생 서비스가 벽시계 번호에서 포트로 옮길 때의 주의를 manual 09 "event id·correlation·순서" 절에 한 줄 적는다. +- 가이드 심각도: Medium · 우선순위 P2 · 증거 E3(실 PG에서 번호 확인) · 소비자 쪽 피해는 E1(소비자 구현에 달림). + +#### RR-05-03 — 끝나지 않는 재시도 행을 운영자가 구분하거나 처분할 수단이 없다 + +- 위치: `PlatformIntegrationEventPublishAdapter.java:188-190`, `application-core/.../OutboxPublishRefusedException.java:39-41`, `PublishPendingOutboxEventsUseCase.java:181-194`, `messaging-kafka/.../KafkaPublishFailureClassifier.java:55-63`, `docs/runbooks/outbox-publish-failed.md:43-45,60`. +- 무엇이 틀렸나: + - AMBIGUOUS와 `REJECTED_RETRYABLE`은 이제 예산을 쓰지 않는다. 그래서 끝 상태가 없다. 이것은 15절 결정이다. + - 결정 기록과 runbook이 다루는 남은 위험은 "진짜 인증 오류" 하나다. + - 실제로 영원히 재시도하는 행은 하나 더 있다. Kafka classifier가 이름을 모르는 브로커 거부는 기본값으로 AMBIGUOUS다. 예: topic의 timestamp 정책에 걸린 `InvalidTimestampException`, 없는 topic의 metadata 대기 시간 초과. 예전에는 3회 뒤 DEAD와 P1 경보로 끝났다. 지금은 5분 간격으로 끝없이 FAILED가 되고 그 aggregate를 막는다. + - runbook은 원인을 "인증/인가면"으로 가르라고 한다. 그런데 bridge가 platform의 실패 code·category를 버리고 `REJECTED_RETRYABLE`만 넘긴다. relay 보고의 원인 문장은 "shutting down, saturated, transport closed or credentials refused" 넷을 한 문장에 묶는다. platform 발행 지표 label도 completion뿐이다(`DefaultMessagePublisher.java` `observe`). 그래서 앱 로그와 지표로는 원인을 가를 수 없다. + - FAILED 행을 건너뛰는 절차가 없다. skip SQL은 `status = 'DEAD'`만 대상으로 한다(`outbox-dead-letter.md:51`). publish-failed runbook은 "즉시 수동 개입 불필요"라고 한다. + - 영원히 재시도하는 행을 찾는 쿼리·지표가 없다. `deferred_attempt_count`가 있는데도 runbook이 쓰지 않는다. +- 왜 중요한가: + - 발생 조건: 레코드 하나에만 해당하는 영구 거부를 classifier가 모르는 경우, 또는 인증·ACL이 실제로 틀린 경우. + - 영향: 그 aggregate의 뒤 이벤트가 무기한 멈춘다. `outbox.publisher.lag` 경보는 울린다. 하지만 운영자는 원인을 알 수 없고 처분 절차도 없다. + - 사용자 판단 원칙 "위험은 코드에 드러나야 한다"에 걸린다. AMBIGUOUS 분기 주석(`PublishPendingOutboxEventsUseCase.java:182-186`)은 broker 정지만 말하고 이 경우를 말하지 않는다. +- 고치는 법: + 1. bridge가 platform `FailureDescriptor.code()`를 잃지 않게 한다. 예: `OutboxPublishOutcome`은 그대로 두고 `publishForOutcome` 결과에 sanitized code를 함께 실어 relay 보고 필드(`error.reason` 등)로 남긴다. 번역 경계(ACL) 안에서 끝나는 변경이다. + 2. runbook에 "끝나지 않는 재시도" 절을 둔다. 확인 쿼리는 `status='FAILED' AND deferred_attempt_count >= N`이다. 처분은 원인 해소 또는 FAILED 행 skip(DEAD skip과 같은 승인 조건)이다. + 3. 선택: 결정을 유지하면서 상한을 하나 둔다. 예: `deferred_attempt_count`가 아주 크거나 행 나이가 기준을 넘으면 별도 경보를 낸다. 예산 키를 만들지 않는다는 결정과 충돌하지 않는다. + 4. 15절 결정 기록의 "남은 위험" 칸에 classifier 미분류 영구 거부를 더한다. +- 가이드 심각도: Medium · 우선순위 P2 · 증거 E1 · 통제 M1(runbook이 인증 오류만 기술). + +#### RR-05-04 — 06-06이 "완료"로 기록됐지만 완료 기준(append 시점 거부)이 채워지지 않았다 + +- 위치: `application-core/.../EventId.java:9`, `IntegrationIdentity.java:18`, `SubmitDurableOperationUseCase.java:168-173`, `PlatformIntegrationEventPublishAdapter.java:133-151`, `adapter/outbound/messaging/README.md:45-51`. README 14절 r2-06 행("06-04~06-07 ... 완료"). +- 무엇이 틀렸나: + - application `EventId` 문법은 그대로 넓다. + - bridge만 정규 소문자 UUIDv7로 더 좁아졌다. 두 계약의 차이는 오히려 커졌다. + - `canonicalIdentity`는 문법 밖 operation id를 `operation-`로 바꾼다. 이 id는 append를 통과하고 relay에서 DEAD가 된다. + - bridge Javadoc과 README가 "append 쪽에서 먼저 실패해야 한다 — 별도 작업"이라고 적는다. 그런데 조치 현황은 완료다. +- 왜 중요한가: + - 지금은 HTTP가 서버에서 UUIDv7을 만들어 도달하지 않는다(`DurableOperationController.java:91`). + - 새 inbound adapter, 클라이언트 지정 id, 다른 id 생성기를 쓰는 기능이 생기면 원래 06-06과 같다. 업무 트랜잭션은 커밋되고, 실패는 나중에 relay에서 DEAD로 나타나 aggregate를 막는다. + - 상태 기록이 실제와 달라 후속 작업 목록에서 빠진다. +- 고치는 법: 원래 권고 (a)를 따른다. `EventId`를 정규 소문자 UUIDv7로 좁힌다. 또는 encoder가 encode 단계에서 같은 검사를 한다. `canonicalIdentity`의 digest 경로는 UUIDv5/v7 파생으로 바꾸거나 없앤다. 조치 현황의 06-06을 "부분"으로 고친다. +- 가이드 심각도: Medium · 우선순위 P2(원래 등급 유지) · 증거 E1 · 통제 M2(bridge에서만 강제). + +### Minor (Nice to Have) + +#### RR-05-05 — 게이지 갱신이 relay와 같은 단일 스레드에서 줄을 선다 + +- 위치: `composition/outbox-relay/.../OutboxMetrics.java:21-29,91-94`, `OutboxRelayScheduler.java:47,102-112`. +- 무엇: Javadoc은 게이지가 "relay와 무관한 자기 주기"로 갱신된다고 적는다. 실제로는 fixed-delay `@Scheduled` 작업이 모두 한 스레드를 쓴다. virtual thread 켬(템플릿 기본)이면 `SimpleAsyncTaskScheduler.fixedDelayExecutor`(core 1)이고, 끄면 `ThreadPoolTaskScheduler` pool 1이다. relay tick은 이제 최대 50회차라 한 tick 동안 게이지·reaper가 기다린다. +- 왜: broker가 느린데 발행은 성공할 때(예: 발행당 0.5초면 50×20×0.5초 ≈ 8분) 게이지가 갱신되지 않는다. 적체를 봐야 할 바로 그때다. relay-off·매 회차 실패 경우(06-05의 완료 기준)는 맞게 동작한다. +- 고치는 법: tick 상한을 회차 수가 아니라 시간(예: poll 주기의 몇 배)으로 둔다. 또는 게이지를 Micrometer의 지연 조회 gauge나 별도 executor로 옮긴다. 최소한 Javadoc을 "relay tick 사이에 갱신"으로 고친다. +- 심각도 Low · P3 · 증거 E1(Spring 7.0.9·Boot 4.0.8 바이트코드). + +#### RR-05-06 — 새 결과 `RELEASED`가 지표 registry에 없다 + +- 위치: `docs/registries/metrics.yaml:353`(`allowed_values: [PUBLISHED, FAILED, DEAD, IN_FLIGHT, STALE]`), `OutboxMetrics.java:65`(Javadoc에 RELEASED 없음), `OutboxMessagePublishAdapter.java:16`("four-valued outcome", 지금은 다섯). +- 무엇: relay는 종료 때 `outbox.publisher.published.total{outcome=RELEASED}`를 기록한다. registry 허용 값에는 없고, 실제로 나오지 않는 `IN_FLIGHT`는 남아 있다. `OutboxStatusRegistryContractTest`는 `outbox.pending.size` status만 비교해서 이 차이를 잡지 못한다. +- 고치는 법: 허용 값을 `OutboxRelayResult.Outcome`과 맞추고, 같은 계약 테스트에 이 label도 비교하게 한다. +- 심각도 Low · P3 · 증거 E1. + +#### RR-05-07 — vendored 제품 안에 두 개의 재시도 규칙이 생겼고, 고른 이유가 제품 쪽에 없다 + +- 위치: `messaging-core-api/.../FailureDescriptor.java:57-75`, `messaging-kafka/.../KafkaPublishFailureClassifier.java:19-25,62-77`, `messaging-runtime-core/.../DefaultMessagePublisher.java:266-268`, `messaging-spring-boot-starter/.../MessagingShutdownLifecycle.java:33-38,121-127`. +- 무엇: + - platform의 category 기본 규칙은 "인증·인가 실패는 자동 재시도하지 않는다"이다(`defaultRetryable(AUTHENTICATION)=false`, Javadoc). + - publish classifier는 이제 같은 category에 `retryable=true`를 붙인다. consumer 재시도 엔진은 두 값을 AND하므로 지금 동작은 안 바뀐다. 하지만 같은 제품이 같은 category를 두 의미로 쓴다. + - vendored 주석 세 곳이 "the application's outbox relay", `composition:outbox-relay OutboxRelayScheduler`를 이름으로 부른다. `PHASE`는 앱 테스트를 위해 public이 됐다. + - registry 간선은 그대로라 MSG-023의 의존 방향은 지켰다. 하지만 제품 문서가 소비자를 알게 됐다. + - "bridge(ACL)에서 category를 보고 번역하고 vendored는 그대로 둔다"는 대안을 왜 버렸는지가 `src/messaging/CLAUDE.md`에 없다. 같은 파일의 digest 헬퍼 절(01-11)처럼 남기는 관례가 이미 있다. +- 고치는 법: `FailureDescriptor` Javadoc에 "publish 거부의 retryable은 category 기본값과 다를 수 있다(인증·인가)"를 적는다. vendored 주석은 "a publisher that trusts the flag"처럼 소비자 이름 없이 쓴다. `src/messaging/CLAUDE.md`에 06-01 vendored 수정 목록과 ACL 대안을 버린 이유를 적는다. +- 심각도 Low · P3 · 증거 E1. + +#### RR-05-08 — `MessagingShutdownLifecycle`에 주인 없는 Javadoc이 남았다 + +- 위치: `messaging-spring-boot-starter/.../MessagingShutdownLifecycle.java:32`. +- 무엇: `POLL` 필드의 Javadoc("How often the drain is re-checked")이 새 `PHASE` Javadoc 바로 위에 붙어 떨어져 있다. `POLL`(40행)에는 설명이 없어졌다. +- 고치는 법: 32행 주석을 `POLL` 선언 위로 옮긴다. +- 심각도 Low · P3 · 증거 E1. + +#### RR-05-09 — 문서·주석이 이번 변경을 따라오지 못했다 + +- `V21__outbox_aggregate_sequence.sql:10`이 없는 클래스 `JpaOutboxAggregateSequences`를 가리킨다. 실제는 `JpaOutboxStore.nextSequence`다. +- `docs/manual/09-outbox-events.md:59-60`은 "application-core 헬퍼로 올리는 일은 01-09 후속"이라고 한다. 같은 diff에 `IntegrationEventDrafts`가 이미 있다. +- `OutboxRelayAutoConfiguration.java:96`과 README 트리의 "SKIP LOCKED 리더 선출" 설명이 남았다(NN-13). +- `docs/runbooks/outbox-publish-failed.md`·`outbox-dead-letter.md` 머리말의 `last_updated: 2026-06-11`이 내용 변경 뒤에도 그대로다. +- 고치는 법: 위치마다 현재 이름과 상태로 고친다. +- 심각도 Low · P3 · 증거 E1. + +#### RR-05-10 — 06 영역 발견 5건(NN-10~NN-14)이 조치 추적에서 빠졌다 + +- 위치: `docs/reviews/2026-11-01-maturity-review/README.md` 12절 색인(06-01~06-09만), 14·16절. +- 무엇: 영역 문서는 14건(High 2·Medium 10·Low 2)을 적는다. 색인·조치 현황·남은 것 어디에도 NN-10(payload 버전 호환성, Medium/P2), NN-11(outbox 두 모델 문서, Medium/P3), NN-12(batch×deadline vs lease 미검사, Medium/P3), NN-13(낡은 설명, Low/P3), NN-14(DLQ 사유 한 값, Low/P3)이 없다. 코드도 NN-13 일부만 바뀌었다. +- 고치는 법: 색인에 06-10~06-14로 올리고, 각 항목을 "남음" 또는 결정으로 닫는다. +- 심각도 Low · P3 · 증거 E1. + +## Declined to judge + +- V21의 `CREATE UNIQUE INDEX`(CONCURRENTLY 아님)가 큰 `outbox_event`에서 쓰기를 막는 시간 — 표 크기를 모르고, 마이그레이션 잠금 정책은 04 영역 몫이다. +- `MessagingInboxSchemaStream`의 `info()` → `baseline()` 사이 다중 인스턴스 동시 기동 경쟁 — Flyway가 같은 baseline marker면 건너뛴다고 보지만 실행으로 확인하지 않았다. +- `PUBLISH_RUNTIME_UNAVAILABLE`을 retryable로 바꾼 것이 "그 broker의 runtime이 영영 없는" 설정 오류를 무한 재시도로 숨기는지 — 기동 검증이 그 조합을 막는지 추적하지 않았다. +- `createAggregateSequence`의 PK 충돌로 실패한 쓰기 트랜잭션을 호출자가 재시도하는지·어떤 HTTP 응답이 되는지 — sample·persistence 영역 경로다. +- relay가 레코드 timestamp를 `occurredAt`으로 보내서, 오래 밀린 행이 topic 보존·timestamp 정책에 걸리는 문제 — 기존 동작이고 broker 설정에 달린다. 무한 재시도와 겹치는 부분만 RR-05-03에 적었다. +- relay를 끈 모든 인스턴스도 poll 주기마다 게이지 질의 2개를 돈다 — 부하는 작다고 보지만 재지 않았다. +- `messagingCodecs`가 handler bean을 일찍 만들어 생기는 순환 의존 — Javadoc이 알리고 Spring이 기동에서 거부한다. 실제 순환 사례로 시험하지 않았다. +- `OutboxRelayShutdownOrderTest`는 platform 대역(같은 phase)을 쓴다. 실제 `MessagingShutdownLifecycle` drain과 실제 SIGTERM은 확인하지 않았다. + +## 28개 관점 — 바뀐 관점만 + +| 번호 | 관점 | 이전 → 지금 | 한 줄 이유 | +| --- | --- | --- | --- | +| 2 | 구조적 성숙도 | P → O | 소비 경로에 application leaf(`adapter:inbound:messaging`)가 생겼다. application 소비 포트는 이유를 남기고 버렸다 | +| 6 | 실패 성숙도 | X → P | 일시 거부·종료·짧은 장애가 더는 DEAD가 되지 않는다. 끝나지 않는 재시도 행의 처분 수단이 없다(RR-05-03) | +| 13 | 확장성 | P → O | aggregate 하나가 poll 주기에 묶이지 않는다(tick당 최대 50회차) | +| 18 | 배포 성숙도 | X → P | 종료 순서를 relay가 소유하고 앱 경로 실연 lane이 main·nightly 게이트에 있다. 업그레이드 때 순서 번호가 1로 돌아간다(RR-05-02) | +| 22 | 추상화 성숙도 | P → O | outcome 어휘가 platform의 "지금만 거부"를 담는다(`REJECTED_RETRYABLE`) | +| 25 | 조직 확장성 | P → O | 소비 기능을 registry 간선을 새로 만들지 않고 정해진 leaf에 둔다 | +| 28 | 회복 가능성 | X → P | broker 장애 뒤 자동 재개된다. DEAD 수동 재구동 SQL은 일부 행에서 실패한다(RR-05-01) | + +## Assessment + +**Ready to merge? With fixes.** + +06-01~06-05·06-07~06-09의 수정은 코드와 테스트로 확인했고, 종료 순서와 재시도 분리는 설계대로 동작한다. 다만 DEAD runbook 재발행 SQL(RR-05-01)은 실 PG에서 실패가 재현됐고 고치기 쉬우므로 먼저 고친다. 업그레이드 때 순서 번호가 1로 돌아가는 문제(RR-05-02)는 파생 서비스가 이 변경을 받기 전에 시작값이나 절차를 정한다. diff --git a/docs/reviews/2026-11-03-rereview/06-bootstrap-build-ci.md b/docs/reviews/2026-11-03-rereview/06-bootstrap-build-ci.md new file mode 100644 index 00000000..62662716 --- /dev/null +++ b/docs/reviews/2026-11-03-rereview/06-bootstrap-build-ci.md @@ -0,0 +1,283 @@ +# 06 bootstrap·build·CI 재리뷰 (2026-11-03) + +리뷰 대상: Base `01a8a2a70` → Head `5786126c`, 영역 번호 06(slug `bootstrap-build-ci`). 원래 영역 문서는 +`docs/reviews/2026-11-01-maturity-review/07-bootstrap-composition-config.md`, +`08-build-ci-test.md`, `09-performance-measurement.md`(샘플 쪽)다. 경로는 저장소 루트 기준이다. + +## 범위 — 본 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/Dockerfile src/Dockerfile.sample +src/.env.example .github docker-compose*.yml infra/postgres infra/fileserver +scripts/run-compose-runtime-smoke.sh scripts/verify-compose-profile-contracts.sh AGENTS.md CLAUDE.md +docs/registries docs/testing docs/capability-status.md +``` + +`git diff --stat` 기준 259파일 +8,251 −2,008. 하위 에이전트 없이 여러 번에 나눠 직접 읽었다. + +- 전부 읽은 것: build-logic main diff 전체(`StrictLaneStagesPlugin`, `WorkflowGradleInvocations`, + `StrictTestLanePlugin`, `JavaConventionsPlugin`, `QualityConventionsPlugin`, `ModuleRegistry`, + `ArchitecturePlugin`, `ConfigContractPlugin`·`EnvContractVerifier`), 루트 `build.gradle`, optional-platforms의 + `settings.gradle`·`gradle.properties`·`build.gradle`, workflow diff 전체(`integration-main.yml` 전문, + `ci-quality-gates.yml`, `release.yml`), `config/spotbugs/exclude.xml` 전문, `container-images.properties`, + compose 파일·`compose-profile-contracts.json`·검사 스크립트 diff, app-bootstrap main diff 전체와 + `build.gradle` 전문, sample main diff 전체와 `application.yml` 전문, AGENTS.md·CLAUDE.md diff. +- 표본으로 읽은 것: repository-contract 태그 16개 클래스가 읽는 파일 목록(입력 선언과 대조), 새 system·integration + 테스트의 단언부, `env-keys.yaml` diff 앞부분, `docs/testing/TESTING_STRATEGY.md` 9절, `docs/capability-status.md` diff. +- pathspec 밖에서 확인용으로 읽은 것: support `StartupRuleRunner`·`StartupRule`·`StartupRuleAutoConfiguration`, + persistence-jpa `JpaStartupAutoConfiguration`의 rule bean 선언, `grpc/grpc-testkit/build.gradle`, + objectstorage `build.gradle`, SpotBugs 제외 표본 확인용 `JdbcOutboxRepository`·`MessageHeaders`·`AuthorizationPrincipal`. + +### 불러온 스킬과 적용한 기준 + +| 스킬 | 적용한 기준 | 무엇을 봤나 | +| --- | --- | --- | +| `superpowers:requesting-code-review` | 리뷰어 템플릿(Strengths → severity별 Issues → Declined → Assessment), "테스트가 mock이 아닌 실제 동작을 보는가", "읽지 않은 코드에 좋다고 하지 않는다" | 새 system 테스트가 실제 서버·실 PostgreSQL·실 OTLP 수신기를 쓰는지 확인. 의심 가는 것은 worktree에서 실행해 확인 | +| `ci-cd-and-automation` | "No gate can be skipped", Red flag "CI failures ignored or silenced", 캐시 최적화가 결과를 바꾸면 안 된다, CI 설정 안 비밀값 | strict lane 단계 연결(`verifyStrictLaneStages`), `--continue`, build cache가 실패해야 할 lane을 녹색으로 돌려주는지, Redis lane fixture 비밀번호 | +| `refactor` | 동작 보존, 중복 코드, 죽은 코드 | 샘플을 그대로 복제해도 안전한가 — 죽은 설정 블록, 두 갈래 충돌 변환, 같은 lane 중복 실행 | +| `documentation-and-adrs` | "Rules files are current and accurate", "Known gotchas documented inline", 결정에 이유가 남아 있는가 | AGENTS.md·CLAUDE.md·build-logic README·capability-status·env 레지스트리를 코드와 대조. 숨은 제약이 Javadoc에만 있는지 | + +### 실행한 명령과 결과 + +worktree `scratchpad/rr-06`(HEAD `5786126c`)에서 `flock heavy.lock`으로 감싸 실행했다. 시작 부하 6~23. 끝난 뒤 +`git worktree remove --force`로 지웠다. 메인 체크아웃은 건드리지 않았다. + +| # | 명령 | 결과 | +| --- | --- | --- | +| 1 | `MessagingEnvelopeSchemaResourceTest`에 `@Disabled` 테스트 1개 추가, `shared-contract/build.gradle`의 `rejectSkipped = false` → `./gradlew :shared-contract:messagingSharedSchemaQualificationTest` | SUCCESS, 결과 XML `skipped="1"` | +| 1-b | 같은 lane에서 `rejectSkipped = true`로만 바꾸고 같은 명령 | **`UP-TO-DATE`, BUILD SUCCESSFUL** | +| 1-c | `--rerun` | FAILED: "forbids skipped tests but observed 1 skipped test(s)" | +| 1-d | lane 결과 폴더를 지우고 다시 실행 | **`FROM-CACHE`, BUILD SUCCESSFUL** | +| 2 | support test에 probe 추가: JavaBean `@ConfigurationProperties("probe")` + non-static `@Bean StartupRule probeRule(ProbeSettings)`, `probe.name=bound` → `./gradlew :adapter:outbound:support:test --tests '*RR06EarlyRuleProbeTest*'` | runner 없음: `name=bound`. runner 있음: 기동 성공, **`name=null`**, 경고 없음. rule이 null을 위반으로 보면 "probe.name is missing"으로 기동 실패. 설정을 생성자 주입하는 변형은 "No default constructor found" | +| 3 | `./gradlew :sample-portfolio:spotbugsMain`(현재 exclude) | BugInstance 0 | +| 3-b | exclude에서 EI 패턴 1과 `~.*SecurityConfig` CSRF Match를 빼고 sample·application-core·domain-core·shared-contract·web·app-bootstrap·service-runtime·support `spotbugsMain --continue` | EI 23건 전부 협력 객체(리포지토리·유스케이스·`EntityManager`·예외 cause·`BeanFactory`). CSRF 4건: web `SecurityConfig`, `ManagementSecurityConfig`, `SampleManagementSecurityConfig`, `SampleDemoSecurityConfig` | +| 4 | `./gradlew :verifyStrictLaneStages --dry-run` | "every strict lane is in an executed stage" | +| 4-b | `integration-main.yml`의 `:integrationCheck` 줄에 `-x :adapter:outbound:persistence-jpa:postgresqlIdempotencyIntegrationTest` 추가 후 같은 명령 | **여전히 통과** | + +돌리지 않은 것: `ci`·`mainCheck`·`integrationCheck` 전체(README 16.2의 오케스트레이터 실행을 근거로 삼았다), +`docker build`, compose 실제 기동, GitHub Actions 실행. + +### 못 본 것 + +- 실제 CI runner에서의 workflow 실행과 `gradle/actions/setup-gradle`의 캐시 복원 범위. RR-06-02의 CI 전파는 action 설정 + (`cache-read-only`)에서 추론했다. +- app-bootstrap document-contract 21개 클래스 본문, `env-keys.yaml` diff 뒷부분(키 이름·주석만 훑음). +- sample posterimage 경로(application 클래스 45개)는 diff 표본만 봤다. + +## Strengths + +- **lane 도달성을 Gradle 자신의 계획으로 판정한다.** `src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesPlugin.java:104-145`. + 문자열 contains가 아니라 `--dry-run` task graph를 읽는다. `--dry-run`·`-p` 명령은 실행으로 세지 않는다. TestKit 6건과 reader 테스트 8건이 있다. +- **YAML folded block의 빈 줄 결함(22곳)을 검사로 고정했다.** `WorkflowGradleInvocations.java:95-131`, workflow 5개 diff. +- **캐시 허용을 lane 범주로 나누고 이유를 코드에 적었다.** `StrictTestLanePlugin.java:223-231, 307-333`. `StrictTestLaneConventionTest`가 FROM_CACHE와 SUCCESS를 TestKit으로 단언한다. +- **저장소를 읽는 테스트를 두 lane으로 나눴다.** `src/app-bootstrap/build.gradle:316-387`. 저장소 루트를 두 lane에만 준다. 그래서 태그 없이 저장소를 읽는 테스트는 `test`에서 실패한다. repository-contract 16개 클래스가 읽는 파일을 표본 대조했고 모두 선언된 입력 안에 있었다. +- **기동 rule이 DB 연결·마이그레이션 전에 돈다.** `src/adapter/outbound/support/.../startup/StartupRuleRunner.java:51-67`(BFPP). `StartupRuleRunnerTest`가 "다른 빈이 하나도 만들어지기 전"을 단언한다. +- **트레이스 수출을 실제 수신기로 검증한다.** `src/app-bootstrap/src/systemTest/.../TracingExportSystemTest.java:40-92`. OTLP 본문 바이트 안에서 응답의 trace id를 찾는다. mock이 아니다. +- **샘플 인가를 실행본 그대로 검증한다.** `SampleWorkLogAuthorizationSystemTest`는 `SamplePortfolioApplication` 전체를 RANDOM_PORT + 실 PostgreSQL로 띄워 401·403·204·201을 확인한다. +- **SQL 비용을 실제 서버에서 숫자로 고정한다.** `src/sample-portfolio/src/systemTest/.../WorkLogStatementCostSystemTest.java:85-131`(목록 20·100건 모두 2문장, batch 100건 8왕복, 제목 PATCH 시 컬렉션 쓰기 0). +- **중복 규칙을 DB가 지킨다.** `src/sample-portfolio/src/main/resources/db/sample-migration/V8_1__poster_title_unique.sql`은 기존 중복이 있으면 이유와 함께 실패한다. adapter는 제약 이름이 일치할 때만 409로 바꾼다(`PosterRepositoryAdapter.java:72-91`). +- **SpotBugs 제외에 이유가 붙어 있고 넓은 패턴은 필드 타입으로 좁혔다.** `src/config/spotbugs/exclude.xml:94-149`. 실험 3-b에서 EI 패턴 1을 빼고 8개 leaf를 돌렸다. 나온 EI 23건은 모두 협력 객체였다. 이 패턴이 진짜 결함을 가린 표본은 찾지 못했다. +- **Redis lane이 운영과 같은 인증 모양이다.** `docker-compose.infra.yml:140-180`이 ACL 파일을 그대로 마운트한다. `scripts/verify-compose-profile-contracts.sh` check 7이 계정·비밀번호·key pattern을 실제 마운트 파일과 대조한다. +- **복사본이 갈라지면 실패한다.** `src/optional-platforms/settings.gradle:23-36`이 `gradle.properties` 두 벌의 동일성을 검사한다. +- **미등록 leaf를 잡는다.** `ModuleRegistry.unregisteredBuildScripts`(`ModuleRegistry.java:189-246`) + `VerifyCleanArchitectureDependenciesTask`. + +## 발견 재확인 표 + +상태: 닫힘 / 부분 / 회귀 / 결정으로 닫힘. `>`는 다른 영역 소관. + +| ID | 상태 | 근거 | +| --- | --- | --- | +| 07-01 | 닫힘 | Boot tracing 모듈로 교체. `TracingExportSystemTest.java:58-92`가 실제 OTLP 수신과 trace id 일치를 본다. endpoint가 비면 exporter bean 0개(`:95-108`) | +| 07-02 | 닫힘(새 위험 RR-06-01) | `StartupRuleRunner.java:51-67` BFPP. `SecretSourceValidator`·`StartupSafetyValidator`가 rule로 옮겼다. rule을 static으로 선언해야 한다는 제약은 강제되지 않는다 | +| 07-03 | 닫힘 | `SampleDemoSecurityConfig.java:33-86` + 메서드 보안 유지(`SamplePortfolioApplication.java:31`). 실서버 테스트 `SampleWorkLogAuthorizationSystemTest` | +| 07-04 | 닫힘(대안 검증) | `Dockerfile.sample:56-63`에 `gradle.properties`·`build-logic/`. `DeveloperExperienceContractTest.java:384-401`이 두 Dockerfile 의존성 단계 COPY 줄 동일성을 단언. 실제 `docker build`는 이번에 다시 돌리지 않았다 | +| 07-05 | 닫힘(02-03과 묶음) | audience 필수. `application.yml:45-47` 주석 갱신. 본체는 02 영역 | +| 07-06 | 닫힘 | `logback-spring.xml:21-60`이 `app.logging.*`을 읽는다. `LoggingSettings` 삭제. `LoggingConfigurationRule`·`LoggingSettingsSourceSystemTest` | +| 07-07 | 닫힘(잔여 RR-06-08) | compose `stop_grace_period: 60s`(`docker-compose.yml:88`), `AWAIT_TERMINATION_SECONDS` 공개 상수, 합계 단언 테스트. drain 30초는 테스트에 리터럴로 남음 | +| 07-08 | 부분(RR-06-10) | durable-operation 모듈 분리, 권한 매핑 모듈 이동, fileserver 볼륨 overlay, dev/prod 프로필 정리 완료. 원래 항목 (6) `ConfigContractPlugin.java:24`가 redis-runtime을 이름으로 아는 것은 그대로 | +| 07-09 | 닫힘(01 영역과 공유) | AGENTS.md 기능 개발 프로토콜에 "sample은 배치 예시가 아니다" 추가, `scripts/new-feature.sh`·`verifyFeatureScaffold`(mainCheck). 표본만 확인 | +| 07-10 | 부분(RR-06-06, RR-06-07) | bootstrap 설정 strict 바인딩(`AsyncExecutorSettings`·`RuntimeSafetySettings`·`BootstrapSettings`·`SecretSourceSettings`), compose·logback이 `verifyEnvKeys` 입력. sample yml 죽은 블록과 smoke 래퍼·lane json의 키는 남음 | +| 07-11 | 닫힘(새 drift RR-06-11) | 지목된 줄은 모두 고침. 같은 종류의 새 drift가 생김 | +| 07-12 | 닫힘(문서) | `config/server.yml:15-22` 주석. 실측은 없음(주석이 그렇게 말함) | +| 07-13 | 닫힘 | `docker-compose.yml:61`, `docker-compose.dev.yml:67` loopback. `DeveloperExperienceContractTest.java:428-` 단언 | +| 07-14 | 닫힘 | `RuntimeEnvironmentProfileValidator.java:86` class literal | +| 08-01 | 부분(RR-06-03, RR-06-04) | main build는 닫힘: `integration-check`·`performance-check` 잡(`integration-main.yml:165-212`), sample systemTest가 mainCheck(`src/build.gradle:192`), `verifyStrictLaneStages`가 PR 게이트. optional-platforms build는 검사 밖이고 `grpcPerformanceTest`가 여전히 어디서도 돌지 않는다 | +| 08-02 | 닫힘(새 위험 RR-06-02) | `StrictTestLanePlugin.java:223-231`. app-bootstrap이 `systemTestCheck`에서 빠짐(`src/build.gradle:124-131`). lane 정책(`rejectSkipped`)이 캐시 키에 없다 | +| 08-03 | 닫힘 | `app-bootstrap/build.gradle:316-387`, `test`가 `repository-contract` 제외 | +| 08-04 | 부분(RR-06-09) | main-check `--continue`(`integration-main.yml:85`), 이미지 목록 한 파일(MinIO는 결정으로 objectstorage 소유), mirror prefix 안내. 원래 (d) MinIO lane 중복은 오히려 늘었다 | +| 08-05 | 닫힘 | `ModuleRegistry.java:189-246`, `VerifyCleanArchitectureDependenciesTask.java:65-72`, `ModuleRegistryTest` | +| 08-06 | 닫힘 | optional `gradle.properties` + 동일성 검사, ARCHITECTURE lane이 실서버 슬롯을 잡지 않음(`StrictTestLanePlugin.java:187-201`) | +| 08-07 | 결정으로 닫힘(잔여 RR-06-05) | MEDIUM으로 내림, 제외마다 이유. sample은 어떤 단계도 분석하지 않는다 | +| 09-01 | 닫힘 | 목록이 요약 projection을 쓴다. `WorkLogStatementCostSystemTest.java:85-94` | +| 09-02 | 닫힘 | `V8_1` 유일 인덱스 + adapter 변환 + `CreatePosterConcurrencyIntegrationTest`(integrationCheck) | +| 09-03 | 닫힘 | 07-03과 같은 수정 | +| 09-04 | 닫힘 | `SampleApiDocsSystemTest`(sample systemTest, mainCheck) | +| 09-05 | > 04 | persistence-jpa 소관 | +| 09-06 | 닫힘 | `WorkLogRepositoryAdapter.java:56-71` 관리 엔티티 갱신, `WorkLogEntity.replaceState`. 테스트 `:97-108` | +| 09-07 | 닫힘 | sample `application.yml:61-71` batch 50 + order_inserts. 테스트 `:120-131`(8왕복) | +| 09-08 | 부분(RR-06-06) | `SampleRuntimeDefaultsContractTest`는 키 3개만 본다. sample yml 머리말의 "읽는 설정만"은 사실이 아니다 | +| 09-09 | > 04 | persistence-jpa 소관 | +| 09-10 | 닫힘 | `application-local.yml:118` `${APP_SERVER_PORT:8080}` | +| 09-11 | 결정으로 닫힘 | 15절: Jackson 2 유지 | + +회귀로 판정한 발견은 없다. + +## Issues + +### Critical (Must Fix) + +없음. + +### Important (Should Fix) + +#### RR-06-01 · 기동 rule을 static이 아닌 `@Bean`으로 선언하면 설정이 조용히 바인딩되지 않는다 + +- **위치**: `src/adapter/outbound/support/src/main/java/dev/caskeleton/adapter/outbound/support/startup/StartupRuleRunner.java:51-67`(pathspec 밖, 07-02 수정), 제약 설명은 `StartupRule.java:12-22`와 `src/app-bootstrap/CLAUDE.md:88-90`뿐. 같은 방식으로 기대는 곳: `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/runtime/SecretSourceConfig.java:33-35`(`RequiredProductionSecrets`를 rule 실행 때 꺼냄). +- **무엇이 틀렸나**: runner가 `BeanFactoryPostProcessor`가 되면서 rule bean은 어떤 `BeanPostProcessor`보다 먼저 만들어진다. rule을 non-static `@Bean` 메서드로 선언하고 설정 bean을 인자로 받으면, 그 설정 bean도 BPP 없이 먼저 만들어진다. JavaBean 방식 `@ConfigurationProperties`의 바인딩은 BPP가 하므로 값이 들어가지 않는다. singleton이라 앱이 끝날 때까지 그 상태로 남는다. +- **증거 (E3)**: 실험 2. 같은 설정(`probe.name=bound`)으로 runner가 없으면 `bound`, runner가 있으면 `null`이었다. 기동은 성공했고 경고는 없었다. 생성자 주입 변형은 "No default constructor found"라는 엉뚱한 메시지로 실패했다. +- **왜 중요한가**: 이 제약은 Javadoc과 CLAUDE.md 한 줄에만 있다. 새 capability 작성자가 흔한 모양(설정 bean을 받는 `@Bean` 메서드)으로 rule을 쓰면, 그 rule은 기본값을 검사한다. 같은 설정 bean을 쓰는 다른 코드도 기본값으로 동작한다. 사용자 원칙 "개발자가 따로 기억해야 하는 숨은 위험은 결함"에 해당한다. 템플릿 자신도 CLAUDE.md의 "parameterless"를 지키지 않는다(`StartupSafetyValidator(ListableBeanFactory)`, `SecretSourceValidator(ObjectProvider)`). 현재 선언 13곳은 모두 static이라 지금 터지는 곳은 없다. +- **고치는 법**: runner가 rule을 꺼내기 전에 정의를 검사해 거절한다. `beanFactory.getBeanDefinition(name)`이 `AnnotatedBeanDefinition`이면 `getFactoryMethodMetadata().isStatic()`과 인자 타입(`Environment`·`ListableBeanFactory`·`ObjectProvider`만 허용)을 확인하고, 아니면 이름을 대며 기동을 실패시킨다. 더 단순한 대안은 rule 생성 전후 `getSingletonCount()`를 비교해 rule 말고 다른 singleton이 생겼으면 실패시키는 것이다. 둘 다 위 probe를 RED 테스트로 쓸 수 있다. `RequiredProductionSecrets`에도 같은 검사를 건다. +- **가이드 심각도·우선순위**: Medium · P2. + +#### RR-06-02 · build cache가 지금의 lane 정책이라면 실패했을 결과를 녹색으로 돌려준다 + +- **위치**: `src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictTestLanePlugin.java:223-231`(캐시 허용), `:277`(`isRejectSkipped()`는 `doLast`에서만 읽는다). CI 전파 경로: `.github/actions/setup-gradle-java/action.yml`(`cache-read-only: github.ref != main`). +- **무엇이 틀렸나**: 08-02 수정으로 TEST·ARCHITECTURE lane은 up-to-date와 build cache를 쓴다. 그런데 `rejectSkipped`는 task 입력이 아니다. lane이 skip을 포함한 채 통과해 캐시에 들어간 뒤 `rejectSkipped = true`로 바꾸면, 입력이 같아서 이전 결과를 그대로 쓴다. `doLast` 검사는 돌지 않는다. +- **증거 (E3)**: 실험 1. `rejectSkipped`를 true로 바꾼 직후 `UP-TO-DATE` 성공, 결과 폴더를 지우면 `FROM-CACHE` 성공. `--rerun`에서만 "forbids skipped tests"로 실패했다. 실패한 실행은 캐시에 저장되지 않으므로 녹색 항목이 계속 남는다. +- **왜 중요한가**: 정책을 강화하는 PR이 자기 효과를 보지 못하고 merge된다. main에서 저장한 캐시를 PR이 읽으므로(action 설정 기준, 실측 아님) CI에서도 같다. 테스트 클래스가 바뀔 때까지 강화가 적용되지 않는다. ci-cd 스킬의 "CI failures silenced"에 해당한다. 같은 변경으로 release 증거 잡(`release.yml` `webAdvancedTest`, gRPC 3 lane)도 캐시 결과를 증거로 올릴 수 있게 됐다. 원래 08-02 권고는 증거 잡에 `--rerun-tasks`였다. +- **고치는 법**: lane 정책을 입력으로 등록한다. `test.getInputs().property("strictLane.rejectSkipped", lane.isRejectSkipped())`, 그리고 `requires` 목록과 `explicitOnly` 여부도 같은 방식으로. TestKit에 "정책만 바꾼 두 번째 실행은 SUCCESS가 아니라 다시 실행한다"를 추가한다. release 증거 잡은 `--rerun-tasks`를 붙이거나 그 lane을 `doNotCacheIf`로 뺀다. +- **가이드 심각도·우선순위**: Medium · P2. + +#### RR-06-03 · `verifyStrictLaneStages`는 optional-platforms build를 보지 않는다 — `grpcPerformanceTest`가 여전히 어디서도 돌지 않는다 + +- **위치**: `StrictLaneStagesPlugin.java:129-137`(`root.getAllprojects()` — main build만), `src/optional-platforms/build.gradle:1-3`(`ca.strict-lane-stages` 미적용, `performanceCheck` 없음), `src/grpc/grpc-testkit/build.gradle:27-32`(`performance()`, `explicitOnly` 아님). 문서: `AGENTS.md:79-83`, `CLAUDE.md:40-42`, `src/build-logic/README.md:19`. +- **무엇이 틀렸나**: 문서는 "`explicitOnly`가 아닌 모든 strict lane"을 검사한다고 말한다. 실제로는 main build의 lane만 본다. optional build의 `grpcPerformanceTest`는 performance lane인데 어느 workflow도 부르지 않는다(release.yml은 다른 3 lane만 이름으로 부른다). 08-01이 찾은 모양 그대로다. +- **증거 (E2·E1)**: 실험 4에서 검사가 "every strict lane is in an executed stage"로 통과했다. 같은 시점에 `grpcPerformanceTest`를 부르는 run 줄은 workflow 15개에 없다(`grep`). optional build의 lane 연결은 아직 문자열 contains 테스트(`DeveloperExperienceContractTest.java:360-381`) 하나에 기댄다 — 원래 08-01이 기각한 방식이다. +- **왜 중요한가**: lane을 추가하는 사람은 "검사가 막아 준다"고 믿는다. optional build에서는 그 믿음이 틀린다. 지금 1개 lane이 그 상태다. +- **고치는 법**: optional build 루트에도 `ca.strict-lane-stages`를 적용하고 stage를 `ci`·`integrationCheck`·(신설) `performanceCheck` 또는 `explicitOnly`로 선언한다. workflow 쪽은 `-p optional-platforms `를 그 build의 실행으로 세도록 reader에 build 디렉터리 인자를 준다. `grpcPerformanceTest`는 주석의 의도대로 `explicitOnly("a measurement on a shared runner is a flaky test; run by name")`로 바꾼다. 문서의 "모든"을 범위에 맞게 고친다. +- **가이드 심각도·우선순위**: Medium · P2. + +### Minor (Nice to Have) + +#### RR-06-04 · stage 검사는 `-x` 제외·job 조건·`continue-on-error`를 보지 않는다 + +- **위치**: `WorkflowGradleInvocations.java:59-64`(`executesInStartBuild`), `:239-240`(`-x` 값을 건너뛰기만 함). +- **무엇이 틀렸나**: run 줄에 stage 이름만 있으면 실행으로 센다. `-x `으로 lane을 빼도, job이 `continue-on-error: true`나 `if:`로 막혀 있어도 통과한다. +- **증거 (E3)**: 실험 4-b. `:integrationCheck`에 `-x :adapter:outbound:persistence-jpa:postgresqlIdempotencyIntegrationTest`를 붙여도 통과했다. 그 lane은 integrationCheck에만 있으므로 어디서도 돌지 않게 된다. 지금 workflow에는 이런 줄이 없다. +- **고치는 법**: `-x` 값을 모아 plan에서 빼고 판정한다. `continue-on-error: true` job의 명령은 실행으로 세지 않는다. 둘 다 reader 단위 테스트 1건씩. +- **심각도·우선순위·증거**: Low · P3 · E3. + +#### RR-06-05 · sample은 SpotBugs를 한 번도 거치지 않는데 exclude에는 sample 항목이 있다. CSRF 제외 이유가 sample 데모 체인에는 맞지 않는다 + +- **위치**: `src/build.gradle:85-93`(`qualityCheck`는 `leafPaths` = sample 제외, `runOnCheck=false`), `src/config/spotbugs/exclude.xml:24-27`(`~.*SecurityConfig`), `:335`(sample `PosterImageUploadIntent`), `QualityConventionsPlugin.java:99-101`("A new finding fails qualityCheck"). +- **무엇이 틀렸나**: (1) 어떤 단계도 sample의 `spotbugsMain`을 부르지 않는다. 그래서 sample의 새 코드는 분석되지 않는다. exclude의 sample 항목은 닿지 않는 규칙이다. (2) `~.*SecurityConfig` 제외의 이유는 "stateless JWT, no ambient cookie auth"다. 새 `SampleDemoSecurityConfig`는 HTTP Basic이다. 브라우저는 Basic 자격 증명을 기억해 같은 origin 요청에 자동으로 붙인다. 이유가 이 클래스에는 거짓이다. +- **증거 (E3)**: 실험 3·3-b. 현재 exclude로 0건, Match를 빼면 `SampleDemoSecurityConfig`에 `SPRING_CSRF_PROTECTION_DISABLED`. +- **왜 중요한가**: 데모 계정 비밀번호가 공개이고 prod는 기동을 거부하므로 sample 자체의 피해는 없다. 문제는 복제되는 예시다. dev에서 실제 계정으로 이 체인을 복제하면 CSRF가 열린다. 그리고 그 사실을 알려 줄 도구가 sample에서는 꺼져 있다. +- **고치는 법**: sample job에 `:sample-portfolio:qualityCheck`를 넣거나 sample 항목을 지운다. CSRF Match는 클래스 이름 목록으로 좁히고, `SampleDemoSecurityConfig`는 이유("공개 데모 계정, prod 거부")를 단 별도 Match로 둔다. +- **심각도·우선순위·증거**: Low · P3 · E3. + +#### RR-06-06 · sample `application.yml` 머리말은 "읽는 설정만"이라고 말하지만 읽는 곳이 없는 블록이 남아 있다 + +- **위치**: `src/sample-portfolio/src/main/resources/application.yml:3`(머리말), `:210-211`(`app.messaging.broker`), `:212-216`(`app.notification.*`), `:217-235`(`app.outbound.http.*` 17키). +- **무엇이 틀렸나**: `app.outbound.http.*`는 저장소 어디에도 읽는 코드가 없다(`src/README.md:357`이 "canonical 설정이 아니다"라고 적는다). messaging·notification 모듈은 sample의 classpath에 없다(`sample-portfolio/build.gradle:66-88`). sample yml은 `verifyEnvKeys`의 설정 파일 입력도 아니다(`ConfigContractPlugin.java:26-45`). +- **왜 중요한가**: sample은 가장 먼저 복제된다. 복제한 사람은 이 키로 HTTP 타임아웃·재시도를 조정한다고 믿는다. 07-10의 (3)과 09-08이 노린 결함이다. +- **고치는 법**: 세 블록을 지운다. `SampleRuntimeDefaultsContractTest`에 "sample yml의 `app.*` 최상위 키는 sample classpath의 설정 prefix 중 하나"를 단언하거나, sample yml을 `verifyEnvKeys` 설정 입력에 넣는다. +- **심각도·우선순위·증거**: Low · P3 · E1. + +#### RR-06-07 · compose lane 계약 json과 smoke 래퍼의 `APP_*` 키는 env 계약 검사 밖이다 + +- **위치**: `scripts/run-compose-runtime-smoke.sh:41-53`(`CAPABILITIES_OFF`), `src/config/runtime/compose-profile-contracts.json`(각 lane `activationEnv`), `ConfigContractPlugin.java:46-57`(compose yml·logback만 operator 파일). +- **무엇이 틀렸나**: r3-f가 손으로 찾은 `CASKELETON_GRPC_ENABLED`(아무도 읽지 않는 키)와 같은 결함이 다시 생겨도 게이트가 모른다. 고친 키 `APP_GRPC_SERVER_ENABLED`와 기존 `APP_OBJECTSTORAGE_ENABLED`는 relaxed binding으로 동작하지만 레지스트리에 없다. +- **고치는 법**: `verifyEnvKeys`의 operator 입력에 lane json의 `activationEnv` 키와 스크립트의 `CAPABILITIES_OFF`를 더한다. 레지스트리에 없는 capability 끄기 키는 등록한다. +- **심각도·우선순위·증거**: Low · P3 · E1. + +#### RR-06-08 · 종료 예산의 web drain 30초가 테스트에 리터럴로 있고, runbook은 옛 예산을 말한다 + +- **위치**: `src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/DeveloperExperienceContractTest.java:410`(`webDrainSeconds = 30`), `docs/runbooks/job-timeout.md:51`(pathspec 밖, "shutdown 예산(20s) vs k8s 30s"). +- **무엇이 틀렸나**: drain은 `APP_SERVER_SHUTDOWN_TIMEOUT`으로 바뀌는 값이다. 레지스트리 기본값이 바뀌어도 테스트는 30으로 계산한다. 원래 완료 기준 "숫자는 한 곳"을 채우지 못했다. runbook의 20초는 이제 30+19초다. k8s grace 30초면 async 대기 중 SIGKILL이다. +- **고치는 법**: 테스트가 `env-keys.yaml`의 `APP_SERVER_SHUTDOWN_TIMEOUT` 기본값을 읽는다. runbook 문장을 49초 + preStop 기준으로 고친다. +- **심각도·우선순위·증거**: Low · P3 · E1. + +#### RR-06-09 · MinIO lane이 main push마다 두 잡에서 돈다 + +- **위치**: `src/adapter/outbound/objectstorage/build.gradle:162`(leaf `mainCheck` → MinIO 2 lane), 같은 lane이 `integration()`이라 `:integrationCheck`에도 들어간다. `integration-main.yml:67-85`와 `:165-176`이 같은 push에서 병렬로 돈다. PR 경로 필터 workflow `object-storage-qualification.yml:36,46`도 있다. +- **무엇이 틀렸나**: 원래 08-04 (d) "중복은 하나만"이 처리되지 않았다. 08-01 수정 뒤 실행 위치가 세 곳이 됐다. +- **고치는 법**: objectstorage `mainCheck`의 의존을 지운다. 컨테이너 lane은 integrationCheck가 소유한다는 규칙과도 맞는다. +- **심각도·우선순위·증거**: Low · P3 · E1. + +#### RR-06-10 · env 계약 태스크가 여전히 특정 leaf를 안다 (07-08 항목 6) + +- **위치**: `src/build-logic/src/main/java/dev/caskeleton/buildlogic/config/ConfigContractPlugin.java:24`(`dependsOn(':adapter:outbound:redis-runtime:compileJava')`), `:58-62`(그 leaf의 metadata 경로). +- **무엇이 틀렸나**: capability 기준 7("이 모듈을 아는 곳은 모듈 자신뿐")의 남은 한 곳이다. redis-runtime을 지우거나 옮기면 `verifyEnvKeys`가 깨진다. 14·16절 어디에도 이 항목의 처리나 보류 이유가 없다. +- **고치는 법**: metadata를 내보내는 leaf가 자기 산출물을 등록하는 방식(예: 각 leaf의 `spring-configuration-metadata.json`을 configuration으로 노출하고 app-bootstrap이 runtime classpath에서 모음)으로 바꾸거나, 보류 이유를 결정 기록에 남긴다. +- **심각도·우선순위·증거**: Low · P3 · E1. + +#### RR-06-11 · 이번 수정 뒤 새로 어긋난 문서·주석 + +- **무엇이 틀렸나** (모두 E1): + - `src/build-logic/README.md:64` "a lane never reports up-to-date" — 08-02 뒤 TEST·ARCHITECTURE lane은 up-to-date다. + - `src/grpc/grpc-testkit/build.gradle:7-9` "none of them can serve an up-to-date result" — 같은 이유로 거짓(pathspec 밖). + - `CLAUDE.md:134-137`, `AGENTS.md:205` — mainCheck 구성에 `:sample-portfolio:systemTest`와 `verifyFeatureScaffold`가 빠져 있다(`src/build.gradle:192,197`). + - `src/app-bootstrap/src/main/resources/config/runtime.yml:22`, `config/observability.yml:114` — "@ConfigurationProperties로 바인딩"이라고 말한다. 이제 `StrictSettingsBinder`이고, `app.logging`은 settings record가 없다. + - `src/sample-portfolio/.../bootstrap/management/SampleManagementSecurityConfig.java:24` "order 0으로 main chain보다 먼저" — 데모 체인은 `@Order(-100)`에 `/**`라 먼저 매칭된다. actuator 체인은 닿지 않는다(이전부터 있던 상태지만 이번 diff가 이 흐름을 바꿨다). + - `docs/capability-status.md:34` — "`postgresqlIdempotencyIntegrationTest`, but no workflow runs it"는 이제 거짓이다(integrationCheck). 같은 행의 `IdempotencyProviderSelectionConfig`·`SampleIdempotencyConfig`는 main 소스에 없다. + - `src/sample-portfolio/build.gradle:199` — jvmArgs를 지운 뒤 "Pin UTC" 주석만 남았다. +- **고치는 법**: 위 줄을 코드에 맞춘다. 문서 대조 parser를 두지 않는 방침이므로 이번 리뷰 목록으로 처리한다. +- **심각도·우선순위·증거**: Low · P3 · E1. + +#### RR-06-12 · 샘플의 "DB가 지키는 유일 규칙" 예시가 계약을 산문으로만 두고, 두 흐름이 충돌을 다르게 바꾼다 + +- **위치**: `src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/domain/poster/PosterRepository.java:8-13`(domain 포트 Javadoc이 application 예외를 약속), `PosterRepositoryAdapter.java:6,72-91`(adapter가 `application.poster.PosterTitleAlreadyExistsException`을 던짐), 비교: `WorkLogRepositoryAdapter.java:63-66`(Spring `ObjectOptimisticLockingFailureException`을 그대로 던짐). +- **무엇이 틀렸나**: domain 포트의 계약이 application 타입을 가리킨다. 코드로는 표현할 수 없어 Javadoc에만 있다. PosterRepository에는 fake도 공유 계약도 없어(단위 테스트는 Mockito mock) 이 약속을 실제 adapter만 지킨다. 같은 sample 안에서 WorkLog는 프레임워크 예외를, Poster는 application 예외를 adapter가 던진다. +- **왜 중요한가**: 이 sample은 09-02 수정의 따라 할 예시다. 복제하는 사람은 두 모양 중 하나를 고른다. AGENTS.md 테스트 규칙(fake와 adapter가 한 계약을 상속)도 이 포트에는 적용되지 않았다. +- **고치는 법**: 포트 옆(domain)에 `DuplicatePosterTitleException` 같은 타입을 두고 use case가 application 예외로 바꾸거나, 포트가 결과 타입을 돌려주게 한다. `PosterRepositoryContract`(fake + adapter)에 "같은 제목 두 번째 save는 거절"을 둔다. 매뉴얼에 충돌 변환 위치를 하나로 적는다. +- **심각도·우선순위·증거**: Low · P3 · E1. + +## Declined to judge + +- `AuthenticationModeCompositionConfig`가 여전히 `SmartInitializingSingleton`(모든 singleton 뒤)이다 — 빈 이름만 보므로 rule로 옮길 수 있지만, 바뀌는 것은 Redis 연결 하나라 피해가 작고 CLAUDE.md "빈이 필요한 검사는 빈으로 남는다"와 맞아 판단을 미룬다. +- Redis lane이 `APP_REDIS_NAMESPACE_ENVIRONMENT=prod`(local 프로필)를 쓴다 — 15절 결정(r3-K)이다. 새 위험은 문서화돼 있어 뒤집지 않았다. +- `performance-check` 잡의 `GRADLE_OPTS=-Dorg.gradle.project.performance.assertions.enabled=true`가 daemon까지 전달되는지 — 실행하지 않았다. +- `configuration-cache` 잡이 `performanceCheck`를 저장 가능성 검사에 넣지 않은 것 — 영향을 측정하지 않았다. +- `exclude.xml` CT group 1이 `@Configuration(proxyBeanMethods = false)` 클래스까지 덮는다. 이유("CGLIB 서브클래스")는 그 클래스에는 맞지 않는다. 다만 finalizer 공격 위험이 사실상 없어 결함으로 세지 않았다. +- `UNSAFE_HASH_EQUALS`의 `PostgreSqlIdempotencyStore` 제외 — 멱등 키가 주체별로 범위가 나뉘는지에 따라 판단이 달라진다. 02·04 영역 소관이라 미뤘다. +- `JdbcOutboxRepository.transition`이 `failureCode == null`이고 `now != null`이면 timestamp를 `last_failure_code` 자리에 묶는다 — SQL 주입 제외 표본을 보다 발견했다. messaging 영역(05) 소관이고 이번 diff가 아니다. +- sample 관리 포트에서 데모 체인이 GET을 모두 허용해 health 상세가 Basic 인증 시 보인다 — 공개 데모 계정이라 의미 있는 노출이 아니다. +- `.env.example`이 `APP_FILESERVER_PLATFORM_CLEANUP_ENABLED=true` 등 기본값을 바꾼 것 — 05 영역 결정(15절)이다. + +## 28개 관점 — 바뀐 관점만 + +원래 판정은 07 영역(`07-…md` 8절), 08 영역(`08-…md` 10절), 09 영역(README 11절)의 값이다. + +| 관점 | 영역 | 이전 → 지금 | 이유 | +| --- | --- | --- | --- | +| 2 구조적 성숙도 | 07 | P → O | durable operation·권한 매핑·볼륨이 모듈로 이동. 남은 것은 build-logic 한 곳(RR-06-10) | +| 5 위험 가시성 | 07 | X → P | 트레이스·인가·검사 순서가 고쳐지고 테스트로 보인다. rule static 제약은 숨어 있다(RR-06-01) | +| 5 위험 가시성 | 08 | P → P | 단계 검사가 생겼지만 optional build와 `-x`는 안 보인다(RR-06-03·04) | +| 5 위험 가시성 | 09 | X → P | 동시 중복·대표 쓰기·N+1이 실서버 테스트로 보인다. sample SpotBugs는 꺼져 있다(RR-06-05) | +| 6 실패 성숙도 | 08 | P → O | main-check `--continue`, 이미지 실패는 실패로 남는다 | +| 7 운영 성숙도 | 07 | P → O | span 수출, 종료 예산 합계 검사, 관리 포트 loopback. runbook drift는 Minor(RR-06-08) | +| 10 테스트 성숙도 | 09 | X → P | 실서버·실 PG 테스트가 대표 위험을 잡는다. Poster 포트는 공유 계약이 없다(RR-06-12) | +| 10 테스트 성숙도 | 08 | P → P | lane이 실제로 돈다. 캐시가 강화된 정책을 건너뛴다(RR-06-02) | +| 11 데이터 성숙도 | 09 | X → O | 유일 인덱스 + 기존 중복 시 마이그레이션 실패 | +| 12 동시성 성숙도 | 09 | X → O | 16 동시 생성에서 1행(동시성 integration 테스트) | +| 13 확장성 | 08 | P → P | main build는 lane 추가가 workflow를 몰라도 된다. optional build는 아직 이름 나열 | +| 14 성능 성숙도 | 08 | P → O | hermetic lane 캐시, 중복 systemTest 제거. `ci` 434→51초(캐시 있는 측정) | +| 16 의존성 성숙도 | 08 | P → O | 테스트 이미지 한 파일·digest, mirror prefix, 효과 없는 netty override 삭제 | +| 18 배포 성숙도 | 07 | P → O | `Dockerfile.sample` COPY 동일성 검사, 기본 이미지에서 VOLUME 제거, fileserver overlay | +| 19 설정 성숙도 | 07 | P → P | bootstrap strict 바인딩·로그 단일 출처는 됨. sample yml 죽은 키, lane 키 미검사(RR-06-06·07) | +| 20 개발자 경험 | 08 | P → O | 문서만 바꾼 커밋이 app-bootstrap `test`를 무효화하지 않는다 | +| 21 Guardrail 성숙도 | 07 | P → P | `@RequiresPermission` 실행본 검증은 생겼고, rule 선언 제약은 장치가 없다(RR-06-01) | +| 21 Guardrail 성숙도 | 08 | P → P | lane 도달성 M3(main build), optional build M0 | +| 26 Ownership | 07 | P → O | 권한 매핑·볼륨을 capability가 소유 | +| 27 삭제 가능성 | 07 | P → O | capability 한 줄을 지우면 bootstrap·compose·이미지에 흔적이 없다(주석 제외) | +| 28 회복 가능성 | 08 | P → O | 이미지 공급원이 사라지면 mirror prefix로 돌릴 수 있고, 다른 결과를 가리지 않는다 | + +## Assessment + +**Ready to merge? With fixes.** + +원래 07·08·09 발견은 대부분 코드와 실제 실행 테스트로 닫혔고 회귀는 없다. 다만 07-02·08-02 수정이 새 숨은 위험 두 개(rule 조기 생성, 캐시가 강화된 lane 정책을 건너뜀)를 만들었고, 08-01의 재발 방지 검사가 optional build를 덮지 못하므로 RR-06-01~03은 merge 전에 고치거나 결정 기록으로 받아들이는 것이 맞다. diff --git a/docs/reviews/2026-11-03-rereview/07-security.md b/docs/reviews/2026-11-03-rereview/07-security.md new file mode 100644 index 00000000..703ce010 --- /dev/null +++ b/docs/reviews/2026-11-03-rereview/07-security.md @@ -0,0 +1,214 @@ +# 07 보안 재리뷰 (2026-11-03) + +## 범위 + +### 본 pathspec + +브랜치 전체 `01a8a2a70..5786126c` 중 보안에 닿는 변경만 봤다. 영역이 여러 leaf에 걸쳐 있어서 파일 단위로 골랐다. + +- 인증·인가: `src/adapter/inbound/web/src/main/java/**/{auth,authz,settings,mvc/autoconfigure}/`, `src/composition/service-runtime/**/authorization/`, `src/application-core/**/security/`, `src/app-bootstrap/**/{security,runtime}/`, `src/app-bootstrap/src/main/resources/{config/security.yml,application*.yml}`, `src/sample-portfolio/**/bootstrap/security/`, `src/sample-portfolio/**/{controller,application/worklog}/`, `src/adapter/outbound/support/**/startup/` +- 파일 서버 소유자·대상: `src/application-fileserver/**/{lifecycle,upload}/`, `src/application-fileserver/src/testFixtures/**/FakeFileAccessPolicy.java`, `src/adapter/outbound/fileserver/**/RoleBasedFileAccessPolicy.java`, `src/adapter/inbound/web-fileserver/src/main/` +- 입력 상한: `src/adapter/inbound/graphql/**/cost/`, `src/adapter/inbound/web/**/mvc/filter/`, `src/adapter/inbound/websocket/**/stomp/`, `src/adapter/inbound/grpc/**/GrpcServer*.java`, `src/grpc/grpc-runtime/**/idempotency/` +- 헤더: `CorsExposedHeaders.java`, `SecurityConfig.java`, `WebMvcRequestIdFilter.java`, `IdempotencyKeyHeader.java`, `InvalidIdempotencyKeyException.java` +- 비밀값·compose: `SecretSource*.java`, `src/application-core/**/secret/`, `docker-compose*.yml`, `infra/redis-sdk/acl/`, `infra/fileserver/compose/`, `src/.env.example`, `src/config/runtime/compose-profile-contracts.json` +- SES 콜백: `src/adapter/outbound/notification/**/{callback,provider/ses,autoconfigure/NotificationCallbackProviderConfig.java,security/AesGcmCallbackPayloadProtection.java}`, `src/adapter/inbound/web-notification/**/callback/`, `src/composition/notification-platform/**/ProviderCallbackIngressBridge.java` +- 의존성·공급망: 모든 `gradle.lockfile`, `src/gradle/libs.versions.toml`, `JavaConventionsPlugin.java`, `src/adapter/outbound/objectstorage/src/test/**/MinioQualificationImage.java`, `minio-provider-evidence.json` +- 정적 분석: `src/config/spotbugs/exclude.xml`, `QualityConventionsPlugin.java` + +### 불러온 스킬과 적용한 기준 + +| 스킬 | 적용한 기준 | 무엇을 봤나 | +|---|---|---| +| `superpowers:requesting-code-review` | 리뷰어 템플릿(Strengths → severity별 Issues → Declined to judge → Assessment), 읽기 전용, 하위 에이전트 금지 | 이 문서의 형식. 칭찬은 읽은 줄에만 붙였다 | +| `security-and-hardening` | 신뢰 경계마다 STRIDE, Always/Never 목록(비밀값 커밋 금지, CORS `*` 금지, 입력 상한), 공급망 4단계(lockfile·새 의존성·출처) | 아래 경계 표, CORS 노출 목록, 비밀값 fixture, lockfile 좌표 비교, MinIO 이미지 출처 | +| `security-review` | 발견마다 공격 경로와 신뢰도, 거짓 양성 걸러내기(DoS·하드닝 부족·테스트 전용 파일 제외) | 하위 작업 분할 지시는 brief의 "하위 에이전트 금지"를 따라 쓰지 않고, 걸러내기 기준만 직접 적용했다. 그래서 High로 올릴 만한 직접 악용 경로는 없었고, 남은 발견은 개발자·운영자 행동이 조건인 Medium·Low다 | + +신뢰 경계와 STRIDE로 본 것: + +| 경계 | 들어오는 것 | 본 위협 | +|---|---|---| +| HTTP API (JWT·세션) | bearer token, 헤더, 본문 | S(다른 client 토큰), E(role 범위, 권한 검사 누락), D(본문 상한) | +| 샘플 HTTP Basic | 공개 데모 계정 | S·E(운영 복제) | +| SES/SNS 콜백 | 서명된 SNS envelope | S(인증서 URL), T, R(감사), replay | +| WebSocket·gRPC·GraphQL | 프레임, 메시지, 쿼리 | D(크기·연결·복잡도) | +| 설정·env·compose | env 값, ACL 파일 | T·I(fixture 비밀번호, 오타 키) | +| 공급망 | Maven 좌표, 컨테이너 이미지 | T(새 라이브러리, 커뮤니티 이미지) | + +### 실행한 명령과 결과 + +- `git diff --stat` / `git diff 01a8a2a70..5786126c -- <위 pathspec>`: 읽기. +- lockfile 좌표 비교(base·head의 모든 `gradle.lockfile`을 합쳐 `group:artifact:version` 집합 차이): 새 좌표 4개, 지운 좌표 0개. 넷 다 1차 공급자 것이다(`spring-boot-micrometer-tracing`, `spring-boot-micrometer-tracing-opentelemetry`, `spring-boot-opentelemetry` 4.0.8, `opentelemetry-exporter-sender-jdk` 1.55.0). `io.netty:*`는 base와 같은 4.2.17.Final이다. +- 별도 worktree(`scratchpad/rr-07`, 5786126c)에 probe 테스트 2개를 넣고 실행: + `flock .../heavy.lock ./gradlew :composition:service-runtime:test --tests '*Rr07SystemInvokedProbeTest' :sample-portfolio:test --tests '*Rr07DemoGuardProbeTest' --console=plain -i` + → `BUILD SUCCESSFUL in 16s`(실행 직전 load 27.65). 출력은 RR-07-01, RR-07-02 증거에 적었다. worktree는 `git worktree remove --force`로 지웠다. + +### 못 본 것 + +- 실제 IdP(Keycloak) 토큰으로 audience·role 범위를 확인하지 않았다. 단위 테스트와 코드만 읽었다. +- 게이트(ci·mainCheck·integrationCheck)는 다시 돌리지 않았다. README 16.2 결과를 그대로 둔다. +- compose lane(`local-redis`, `all-adapters`, notification)을 직접 띄우지 않았다. +- 의존성 CVE 데이터베이스 대조(OSV·dependency-check)는 하지 않았다. 새 좌표가 1차 공급자 것뿐이라는 것까지만 확인했다. +- 보안과 관계없는 나머지 diff(성능·메시징 재시도·JPA 매핑 등)는 보지 않았다. + +## Strengths + +- **JWT audience가 닫힌 기본값이 됐다.** `SecuritySettings.java:44`가 풀리지 않은 `${...}` 자리표시자를 "값 없음"으로 읽는다. `SecuritySettings.java:62`가 JWT 모드에서 빈 audience를 기동 거부한다. `JwtDecoderConfig.java:77-88`도 빈 목록이면 예외를 던져 두 번째 방어선이 된다. 목록 중 하나만 맞으면 통과한다(`JwtDecoderConfig.java:106-116`). +- **role 범위가 자기 client로 좁혀졌다.** `JwtToAuthenticatedPrincipalConverter.java:92-100`은 audience로 설정한 client의 `resource_access`만 읽는다. "다른 client role은 권한이 되지 않는다" 테스트가 있다(`JwtToAuthenticatedPrincipalConverterTest.java:81-82`). +- **`app.security`가 엄격 바인딩이다.** 오타 키와 아무 설정도 아닌 `APP_SECURITY_*` env가 기동을 막는다(`SecuritySettingsTest.java:59-79`). 같은 prefix를 느슨하게 두 번 바인딩하던 `AuthenticationModeSettings`가 지워졌다. +- **메서드 보안이 인증 체인과 분리됐다.** `WebMethodSecurityAutoConfiguration`이 따로 있어서 JWT 체인을 빼도 `@RequiresPermission`이 남는다. web 어댑터가 없는 조립은 `PermissionEnforcementGuard.java:41-61`이 기동 실패로 막는다. +- **샘플 권한이 실서버로 검증된다.** `SampleWorkLogAuthorizationSystemTest`가 실제 PostgreSQL과 RANDOM_PORT 서버로 익명 401, 권한 없는 삭제 403, 권한 있는 삭제 204, 남의 기록 수정 403을 본다. mock이 아니다. +- **prod 기동 규칙이 DB 연결 전에 돈다.** `StartupRuleRunner`가 BeanFactoryPostProcessor가 됐다. `SecretSourceValidator`, TLS `verify-full`, H2 금지, 데모 계정 거부가 datasource·Flyway보다 먼저 돈다. 기여 bean은 모두 `static`이다(`JpaStartupAutoConfiguration.java:163`, `RedisCapabilityConfig.java:91`). +- **SNS 인증서 실패가 "거절"이 아니라 "다시 보내라"다.** `NotificationCallbackMvcController.java:124`가 503과 `Retry-After`를 준다. replay 창은 근거가 있는 상수다(`SesCallbackAdapter.java:49`, SNS HTTP 재시도 상한 3600초). 중복은 `(provider_profile_id, event_fingerprint)` 유일 인덱스가 막는다. +- **전송 상한이 코드에 드러났다.** gRPC는 메시지 1 MiB·메타데이터 8 KiB·연결당 동시 호출·고정 크기 executor·기본 deadline을 builder에 건다(`GrpcServerRunner.java:99-110`). WebSocket은 메시지·버퍼·첫 메시지 시간·노드 연결 수(`WebSocketConfig.java:72-78`)와 세션당 구독 1개를 건다. session id가 없으면 구독을 받지 않는다(`WebSocketInboundAuthorizationInterceptor.java:92-96`). +- **GraphQL 점수가 우회 경로를 막는다.** 변수 기본값, 스키마 인자 기본값, 크기 없는 list, 중첩 list 곱셈을 모두 계산하고, 범위 밖 정수는 최대값으로 읽어 거부한다(`GraphQlDocumentComplexityScorer.java:262-327`). +- **헤더 처리가 한 규칙이다.** correlation ID는 요청 ID와 같은 문법이고 틀리면 고치지 않고 새로 만든다(`WebMvcRequestIdFilter.java:189`). `Idempotency-Key`는 응답에 되돌려 쓰지 않는다(`InvalidIdempotencyKeyException.java`). CORS 노출 목록은 코드가 소유하고 `*`를 거부한다(`CorsExposedHeaders.java:27-47`). +- **compose 관리 포트가 loopback이다.** `docker-compose.yml:61`, `docker-compose.dev.yml`. compose Redis는 `default` 사용자를 끄고 ACL 계정으로만 붙는다. +- **SpotBugs MEDIUM의 보안 제외가 위치 단위다.** 표본으로 확인했다. `JdbcOutboxRepository`의 SET 절은 모두 문자열 리터럴이고 값은 바인딩이다. `IdempotencyCapabilityGuard`의 SQL은 상수다. `GraphQlRequestBodyLimitFilter.reject`는 고정 본문을 쓴다. `SnsSignatureVerifier`의 호스트 정규식은 선형이다. `ContentType`은 정규식 전에 160자로 자른다. +- **MinIO 이미지가 digest로만 바뀐다.** 운영자 override도 같은 digest가 아니면 거부한다(`MinioQualificationImage.java:73`). compose 기본값과 evidence가 다르면 `ComposeMinioImageMatchesEvidenceTest`가 실패한다. 기각한 후보와 이유가 evidence 파일에 남아 있다. +- **파일 서버 소유자 회귀가 이제 잡힌다.** fake 정책이 소유자 규칙을 지키므로 05-08 변이(descriptor 제거)가 use case 테스트에서 죽는다. copy·move 대상 namespace는 허용 목록이다(`CopyFileApplicationUseCase.java:96`, `MoveFileApplicationUseCase.java:53`). + +## 발견 재확인 표 + +| ID | 상태 | 근거 | +|---|---|---| +| 02-03 | 닫힘 | `SecuritySettings.java:44,62`, `JwtDecoderConfig.java:77-88`, `JwtToAuthenticatedPrincipalConverter.java:92-100`. 완료 기준 2개(빈 audience 기동 실패, 다른 client role 무시) 모두 테스트가 있다 | +| 07-05 | 닫힘 | 02-03과 같은 코드. 결정 A대로 prod만이 아니라 JWT 모드 전체에서 거부한다 | +| 07-03 | 닫힘 | `SamplePortfolioApplication`이 JWT 체인만 빼고 `WebMethodSecurityAutoConfiguration`은 남긴다. 실서버 테스트가 403·204를 본다. 결정이 만든 새 위험은 RR-07-02 | +| 09-03 | 닫힘 | 익명 생성이 500이 아니라 401(`SampleWorkLogAuthorizationSystemTest`) | +| 01-06 | 닫힘, 새 결함 1 | 완료 기준 2개(web 없는 조립 기동 실패, relay의 장식용 권한 선언 제거)는 채웠다. 대신 들어온 `@SystemInvoked` 면제가 코드로 묶여 있지 않다 → RR-07-01 | +| 05-08 | 닫힘 | `FakeFileAccessPolicy.java:45-50`, `DownloadUseCasesTest.java:91,110`, `FileLifecycleUseCasesTest.java:340`. 규칙이 두 벌이다 → RR-07-06 | +| 05-12 | 닫힘 | `TusController.java:185`가 status 재조회(`file:read`) 없이 append 결과로 판단한다. 자동 finalize도 `file:upload`와 소유자 검사를 거친다 | +| 05-07 (대상·쿼터) | 결정으로 닫힘 | `TargetNamespacePolicy`(기본은 업로드 기본 namespace 하나). 동시 예약이 상한을 넘을 수 있는 것은 15절 결정 | +| 05-20 | 닫힘 | 창 1시간(`SesCallbackAdapter.java:49`), 인증서 실패 503(`ProviderCallbackIngressBridge.java:82`). 분류·중복 방지에 작은 틈 → RR-07-03, RR-07-07 | +| 05-09 | 결정으로 닫힘 | `pgsty/minio` digest 고정, 참조 한 곳(evidence), override digest 검사 | +| 03-01 | 닫힘 | `GraphQlDocumentComplexityScorer.java:262-295`, `PageVariables`(:385-) | +| 03-06 | 닫힘 | `StompConnectionLimit`, `WebSocketInboundAuthorizationInterceptor.java:55`, `WebSocketConfig.java:72-78` | +| 03-09 | 닫힘 | `GrpcServerRunner.java:99-110`, `GrpcServerSettings` 기본값 | +| 02-05 | 닫힘 | `SecurityConfig.corsConfigurationSource`가 `CorsExposedHeaders` 합집합을 노출, fileserver가 tus 헤더를 기여 | +| 02-09 | 결정으로 닫힘 | JSON 두 갈래를 테스트가 고정(`JsonBodyLimitFilterTest.java:47-77`). JSON 아닌 본문은 엔드포인트 몫(15절) | +| 02-11 | 닫힘 | `WebMvcRequestIdFilter.java:189` | +| 02-12 | 닫힘 | `IdempotencyKeyHeader`, 유일한 운영 KEYED 컨트롤러가 사용(`PosterImagePublicationController.java:64`) | +| 07-10 (보안 prefix) | 닫힘 | `SecuritySettings.bind`, `SecretSourceSettings.bind`. 다른 prefix는 이 영역 밖이라 보지 않았다 | +| 07-13 | 닫힘 | `docker-compose.yml:61`, `docker-compose.dev.yml` | +| 08-07 | 닫힘 | `QualityConventionsPlugin`에 MEDIUM과 측정 수, 제외마다 이유. 이유가 맞지 않게 된 기존 제외 1건 → RR-07-05 | + +회귀로 판정한 발견은 없다. + +## Issues + +### Critical (Must Fix) + +없음. + +### Important (Should Fix) + +#### RR-07-01 `@SystemInvoked`의 권한 검사 면제 조건이 Javadoc에만 있다 + +- 위치: `src/application-core/src/main/java/dev/caskeleton/application/security/SystemInvoked.java:19-20`, `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ApplicationBoundaryArchitectureTest.java:558`, `src/composition/service-runtime/src/main/java/dev/caskeleton/composition/runtime/authorization/PermissionEnforcementGuard.java:41-61` +- 무엇이 틀렸나: ArchUnit D4는 쓰기 유스케이스에 `@RequiresPermission`을 요구한다. 클래스에 `@SystemInvoked`가 붙으면 이 검사를 건너뛴다(:558). 면제의 전제는 "transport가 닿는 Spring 빈이 되면 안 된다"인데, 이 문장은 Javadoc(:19-20)과 `application-core/CLAUDE.md`에만 있다. 기동 검사(`PermissionEnforcementGuard`)는 `@RequiresPermission`이 붙은 빈만 본다. `@SystemInvoked` 빈은 보지 않는다. +- 왜 중요한가: D4가 실패하면 개발자(또는 에이전트)가 가장 쉽게 고르는 해법이 `@SystemInvoked(reason = "...")` 한 줄이다. 그 유스케이스를 컨트롤러가 부르면 모든 게이트가 통과한다. + - 누가: 그 서비스의 인증된 사용자 누구나(role 무관). + - 무엇으로: `@SystemInvoked`가 붙은 채 빈으로 등록된 쓰기 엔드포인트. + - 무엇을 얻나: role→permission 검사 없이 쓰기를 실행한다(권한 상승). 사용자 원칙 "개발자가 따로 기억해야 하는 숨은 위험은 결함"에 해당한다. +- 고치는 법: `PermissionEnforcementGuard`가 이미 모든 빈 정의를 훑는다. 같은 루프에서 클래스에 `@SystemInvoked`가 있으면 기동을 실패시킨다. 메시지는 "system-invoked use case must be constructed by its composition, not registered as a bean". 아래 probe를 RED 테스트로 쓴다. 보조로 ArchUnit "inbound adapter는 `@SystemInvoked` 클래스에 의존하지 않는다"를 둘 수 있다. +- 가이드 심각도·우선순위: Medium · P2. 개발자 실수가 조건이라 High가 아니다. +- 증거: E3. worktree에서 `@SystemInvoked` 클래스를 빈으로 등록하고 `PermissionEnforcementConfig`와 함께 띄웠다. 출력 `RR07 systemInvokedBean failed=false`(기동 성공). + +#### RR-07-02 데모 계정 거부가 정확히 `prod`일 때만 걸리고, 샘플에는 프로필 검증기가 없다 + +- 위치: `src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/bootstrap/security/SampleDemoAccountsProductionGuard.java:44-46`, `src/sample-portfolio/src/main/resources/application.yml:30`(`${SPRING_PROFILES_ACTIVE:local}`), `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/runtime/RuntimeEnvironmentProfileValidator.java:84-86`, `src/config/architecture/modules.json:387-390`, `src/sample-portfolio/src/test/java/dev/caskeleton/sample/portfolio/bootstrap/security/SampleDemoAccountsProductionGuardTest.java:70` +- 무엇이 틀렸나: 15절 결정의 이유는 "샘플을 복제해 운영에 올리는 위험을 코드로 막는다"이다. 구현은 금지 목록 방식이다. `RuntimeEnvironment.fromProfile`은 정확히 `prod`만 production으로 읽는다. 앱의 "환경 프로필 정확히 하나" 검사는 main class가 `CaSkeletonApplication`일 때만 돈다(:84-86). 샘플은 app-bootstrap에 의존하지 않아서 이 검사가 아예 없다(modules.json). 그래서 프로필 없음(yml 기본 `local`로 바뀜), `production`, `staging`으로 띄우면 데모 계정이 열린 채 기동한다. `Dockerfile.sample`도 프로필을 정하지 않는다. 테스트가 "프로필 없음이면 허용"을 고정해 둔다(:70). +- 왜 중요한가: + - 누가: 그 배포에 네트워크로 닿는 누구나. + - 무엇으로: README에 공개된 `demo-admin` / `demo-admin` HTTP Basic. + - 무엇을 얻나: admin role(`worklog:close` 삭제 등). 샘플을 베낀 서비스라면 그 서비스가 `admin`에 매핑한 권한 전부. + 결정 자체(prod 거부)는 그대로 지켰다. 문제는 결정이 막으려던 경로(복제 후 운영 배포)가 `prod`라는 이름 하나에만 걸려 있다는 것이다. +- 고치는 법: 결정을 넓히는 방향이라 뒤집지 않는다. + 1. 거부 조건을 허용 목록으로 바꾼다. `local`·`dev`·`test` 중 정확히 하나가 명시적으로 켜져 있을 때만 데모 계정을 허용한다. + 2. 샘플 yml의 `SPRING_PROFILES_ACTIVE:local` 기본값을 지운다. 기본값이 남아 있으면 1번만으로는 "프로필 없음"이 `local`로 바뀌어 통과한다. 대안은 데모 계정을 `app.sample.demo-accounts.enabled` 같은 명시 키로 켜고 이미지 기본값을 false로 두는 것이다. + 3. `theDemoAccountsAreAllowedWithNoProfileAtAll`을 반대 단언으로 바꾸고 `production`·`staging` 케이스를 더한다. +- 가이드 심각도·우선순위: Medium · P2. +- 증거: E3. worktree probe에서 `violations()` 결과: `production` 0건, `staging` 0건, `prd` 0건, `PROD ` 1건. + +### Minor (Nice to Have) + +#### RR-07-03 SNS 인증서 URL의 HTTP 4xx를 "검증 불가(503)"로 분류해서 위조 콜백이 거절도 감사도 되지 않는다 + +- 위치: `src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/NotificationCallbackProviderConfig.java:74-77`, `src/composition/notification-platform/src/main/java/dev/caskeleton/composition/notification/ProviderCallbackIngressBridge.java:82-92` +- 무엇이 틀렸나: 진짜 SNS 메시지의 `SigningCertURL`은 존재하는 인증서를 가리킨다. 호스트·경로 검사를 통과한 URL이 404·403을 주면 그 envelope은 위조다. 지금은 2xx가 아닌 모든 응답이 IOException·인터럽트와 같은 "일시 장애"로 묶인다. 결과는 503과 `Retry-After`이고, `securityAudit.callbackSignatureRejected`에 남지 않는다(WARNING 로그만). 주석은 "Not a security event"라고 단정한다. +- 왜 중요한가: + - 누가: 콜백 URL과 구독 topic ARN을 아는 외부인. + - 무엇으로: 허용 topic, 현재 `Timestamp`, `https://sns..amazonaws.com/SimpleNotificationService-<없는 id>.pem`을 넣은 envelope. + - 무엇을 얻나: 이벤트는 기록되지 않아 데이터 변조는 없다. 얻는 것은 서명 위조 시도가 감사 기록에서 빠지는 것(R)이다. 이전(500)에도 감사되지 않아서 회귀는 아니다. +- 고치는 법: 4xx는 `IllegalArgumentException`("SNS 서명 인증서가 아님") 쪽으로 보내 invalid + 감사로 처리한다. IOException·5xx·인터럽트만 `CallbackVerificationUnavailableException`으로 둔다. +- 가이드 심각도·우선순위: Low · P3. +- 증거: E1(코드 읽기). + +#### RR-07-04 Redis ACL fixture 파일이 "배포가 싣는 파일"로 소개되는데 공개 비밀번호의 `+@all` 계정을 담고 있다 + +- 위치: `infra/redis-sdk/acl/all-accounts.acl:8`(`ca-skeleton-cluster-bootstrap on >fixture-bootstrap ~* &* +@all`), `infra/redis-sdk/acl/README.md:23`, `docker-compose.infra.yml:140`, `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/runtime/SecretSourceValidator.java:33` +- 무엇이 틀렸나: README 표(:23)는 이 파일을 "the four accounts concatenated … this is what a deployment loads"라고 쓴다. 실제 파일은 8줄이고 superuser 1개가 들어 있다. 이번 브랜치가 compose 주석(:140)에 "with the accounts a deployment loads"를 새로 썼다. README 11-13행은 반대로 "배포는 파일 전체를 바꾼다"고 쓴다. prod 비밀 검사는 `__LOCAL_DEV_` 접두만 거부하고 `fixture-*` 값은 모른다. 이번 브랜치는 lane에서 앱을 fixture 비밀번호와 namespace `prod`로 붙이기 시작했다. +- 왜 중요한가: + - 누가: 이 파일을 그대로 운영 Redis에 올린 배포에서, Redis에 닿는 누구나(같은 클러스터의 다른 pod 등). + - 무엇으로: `AUTH ca-skeleton-cluster-bootstrap fixture-bootstrap`. + - 무엇을 얻나: 모든 키 읽기·삭제, `CONFIG`·`MODULE`을 포함한 서버 장악. + 운영자가 fixture를 복사해야 성립하므로 Low다. +- 고치는 법: README 표와 compose 주석을 "lane이 싣는 fixture. 배포는 같은 모양의 파일을 비밀 저장소 비밀번호로 새로 만든다"로 고친다. 계정 수를 실제와 맞춘다. prod `SecretSourceValidator`가 `fixture-` 접두 값도 sentinel처럼 거부한다. +- 가이드 심각도·우선순위: Low · P3. +- 증거: E1. + +#### RR-07-05 CSRF 제외 규칙의 이유가 새 샘플 보안 설정에는 맞지 않는다 + +- 위치: `src/config/spotbugs/exclude.xml:19-27`, `src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/bootstrap/security/SampleDemoSecurityConfig.java:71-73` +- 무엇이 틀렸나: `SPRING_CSRF_PROTECTION_DISABLED`를 `~.*SecurityConfig` 패턴으로 제외한다. 이유는 "stateless JWT bearer, ambient cookie auth 없음"이다. 새 `SampleDemoSecurityConfig`가 이름 패턴에 걸린다. 이 클래스는 CSRF를 끄고 HTTP Basic을 쓴다. HTTP Basic은 브라우저가 한 번 받은 자격을 자동으로 붙이는 수단이라 이유가 성립하지 않는다. 08-07이 정한 규칙("A pattern-wide Match needs a reason that holds for every class it can ever match", `QualityConventionsPlugin`)과 어긋난다. +- 왜 중요한가: 지금 실제 영향은 없다. 401이 `WWW-Authenticate: Bearer`라 브라우저가 Basic 자격을 저장하지 않고, 계정도 공개다. 다만 샘플을 베낀 서비스가 실제 Basic 계정을 넣으면 CSRF 경고가 조용히 사라진다. +- 고치는 법: 매치를 정확한 클래스 이름으로 좁힌다. 샘플용 Match를 따로 두고 "공개 계정이라 CSRF가 지킬 자격이 없다"는 이유를 단다. +- 가이드 심각도·우선순위: Low · P3. +- 증거: E1. + +#### RR-07-06 파일 소유자 규칙이 fake와 실제 정책에 두 벌 있고 공유 계약이 없다 + +- 위치: `src/application-fileserver/src/testFixtures/java/dev/caskeleton/application/fileserver/testkit/FakeFileAccessPolicy.java:45-50`, `src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/security/RoleBasedFileAccessPolicy.java:74-91` +- 무엇이 틀렸나: 05-08 변이를 잡는 장치는 fake가 실제 정책의 소유자 규칙을 베낀 것이다. 둘을 묶는 `FileAccessPolicyPort` 계약 테스트가 없다(`docs/testing/TESTING_STRATEGY.md` 9절에도 없음). 비교 방식도 다르다. fake는 `owner == subject.asOwner()` 하나로 비교하고, 실제 정책은 principalId와 tenant를 따로 비교한다. +- 왜 중요한가: 실제 정책이 바뀌면(예: 관리자 우회 추가) fake는 그대로 남는다. use case 테스트는 운영과 다른 소유자 규칙을 검증하게 된다. 다른 사용자 파일 접근(IDOR) 회귀를 막는 장치가 갈라진 복사본에 기대고 있다. +- 고치는 법: application-fileserver testFixtures에 `FileAccessPolicyPortContract`를 둔다. 케이스는 남의 파일 거부, 다른 tenant 거부, 소유자 없는 파일 거부, descriptor 없음은 역할만 확인. fake와 `RoleBasedFileAccessPolicyTest`가 상속한다(AGENTS.md의 공유 계약 규칙). +- 가이드 심각도·우선순위: Low · P3. +- 증거: E1. + +#### RR-07-07 replay 창 1시간의 중복 방지가 fingerprint 키 회전에 깨지고, Javadoc은 다른 유일 키를 말한다 + +- 위치: `src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/provider/ses/SesCallbackAdapter.java:36-40`, `SesEventNormalizer.java:78`, `src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/security/AesGcmCallbackPayloadProtection.java:130`, `src/adapter/outbound/persistence-notification/src/main/resources/db/migration/jpa/notification-platform/V1__notification_platform_core.sql:174-179` +- 무엇이 틀렸나: Javadoc은 "ledger가 `(provider_profile_id, provider_event_id)`로 유일하다"고 쓴다. SES 이벤트는 `provider_event_id`가 항상 비어 있다(:78). 실제로 막는 것은 `(provider_profile_id, event_fingerprint)` 유일 인덱스다. fingerprint는 현재 활성 HMAC 키로 만든다(:130). 키를 회전하면 같은 콜백이 다른 fingerprint가 된다. +- 왜 중요한가: 창이 5분에서 1시간으로 12배 늘었다. 회전 전에 받은 콜백을 SNS가(또는 그 메시지를 가진 사람이) 회전 뒤 다시 보내면 두 번 기록된다. 서명이 필요해서 위조는 아니다. 같은 bounce·complaint·delivery가 두 행이 된다. +- 고치는 법: Javadoc을 실제 인덱스로 고친다. SES 콜백은 서명 문자열에 포함된 SNS `MessageId`를 `provider_event_id`로 넣는다. 그러면 키와 무관한 유일성이 생긴다. +- 가이드 심각도·우선순위: Low · P3. +- 증거: E1. + +## Declined to judge + +- Keycloak은 사용자가 어떤 client의 role을 가지면 그 client를 `aud`에 넣는다. 그래서 다른 client(`azp`)가 받은 토큰도 이 서비스 audience를 담을 수 있다. `azp` 검사는 02-03 결정 범위 밖이고 IdP 설정에 달려 있어 판단을 미룬다. +- `realm_access.roles`와 최상위 `roles` claim은 client 구분 없이 읽는다. realm role은 15절 결정으로 유지됐다. 최상위 `roles`는 IdP mapper 설정에 달려 있다. +- `PermissionEnforcementGuard`는 pointcut이 맞는 아무 advisor나 "강제한다"로 인정한다. Javadoc이 이 한계를 적었고, 지금 템플릿에는 `@RequiresPermission` 빈에 맞는 다른 advisor bean이 없다. +- 들어온 `traceparent`가 trace id와 sampled 플래그를 정한다(Boot 기본 ParentBased 샘플러). 기존 설계이고, 영향이 비용·로그 상관 쪽이라 보안 결함으로 보지 않았다. +- `pgsty/minio`는 커뮤니티 fork이고 서명 검증(cosign 등)이 없다. digest 고정과 테스트·로컬 전용이라는 점, 소유자 결정(15절)을 보고 판단을 미룬다. +- 의존성 CVE 대조는 도구를 돌리지 않아 판단하지 않았다. +- fileserver 저장소 초기화 컨테이너가 root로 `chown`만 한다(`network_mode: none`, `read_only`). capability를 더 줄일 수 있지만 하드닝 제안이라 발견으로 올리지 않았다. +- 파일 쿼터 동시 예약이 상한을 넘을 수 있는 것은 15절 결정이다. +- HTTP client의 `PLAINTEXT_FALLBACK_FORBIDDEN`이 비운영에서 풀린 것은 설정 문서와 `ClientProfileValidator`의 prod 검사(:246)와 일치해서 결함으로 보지 않았다. + +## 28개 관점 — 바뀐 관점만 + +README 11절 종합 판정 대비, 보안 범위 안에서 바뀐 것만 적는다. + +| 관점 | 전 | 후 | 이유 | +|---|---|---|---| +| 5 위험 가시성 | X | P | 빈 audience가 기동 거부로 드러난다. `@SystemInvoked` 조건(RR-07-01)과 데모 거부 범위(RR-07-02)는 아직 코드 밖에 있다 | +| 10 테스트 성숙도 | X | P | 05-08 변이가 죽고, 샘플 권한을 실서버로 본다. 소유자 규칙의 공유 계약은 없다(RR-07-06) | +| 13 확장성 | X | P | WebSocket 연결·구독, gRPC 동시 호출·메시지 크기 상한이 생겼다. principal별 상한은 서비스 몫으로 문서화됐다 | +| 15 보안 성숙도 | X | P | 02-03이 닫혔다. Medium 2건(RR-07-01, RR-07-02)이 남았다 | + +## Assessment + +**Ready to merge? With fixes** + +Critical·High는 없고 보안 영역의 원래 발견은 모두 닫히거나 결정으로 닫혔다. 남은 Important 2건은 권한 검사를 비켜 가는 경로(`@SystemInvoked` 빈, `prod`가 아닌 이름의 데모 배포)를 코드가 막지 못하는 것이고, 각각 기동 검사 한 군데를 고치면 된다. diff --git a/docs/reviews/2026-11-03-rereview/README.md b/docs/reviews/2026-11-03-rereview/README.md new file mode 100644 index 00000000..b6dee03d --- /dev/null +++ b/docs/reviews/2026-11-03-rereview/README.md @@ -0,0 +1,69 @@ +# 재리뷰 — 2026-11-03 + +> 대상: 브랜치 `refactor/maturity-review-2026-11`, `01a8a2a70..5786126c`(커밋 3개, 1,323파일 +60k −9.6k). 2026-11-01 성숙도 리뷰(`../2026-11-01-maturity-review/README.md`)의 수정 전체를 다시 봤다. +> 방법: `superpowers:requesting-code-review`의 리뷰어 템플릿으로 영역 리뷰어 6명과 보안 리뷰어 1명(`security-auditor`)을 띄웠다. 리뷰어마다 영역 스킬을 불러 그 기준을 적용했다(각 문서 "범위" 절). 읽기 전용, 하위 에이전트 금지, 의심 결함은 별도 worktree의 임시 테스트로 확인. + +## 1. 결론 + +- **Critical 0, 회귀 0.** 원래 리뷰의 High·P1 수정은 모든 영역에서 닫혔다고 판정됐다. +- **모든 영역 판정: With fixes.** 수정이 새로 만든 결함과 덜 끝난 완료 기준이 있다. Important 27건(중복을 빼면 22건), Minor 41건. +- **정정 — 원래 리뷰의 발견 수는 119건이 아니라 124건이다.** 06 영역 문서의 `NN-10`~`NN-14` 5건이 색인에 들어가지 않아 어떤 수정 묶음에도 배정되지 않았다(오케스트레이터가 `NN-0x`만 `06-0x`로 바꾼 실수). 원래 README 14.3·16절의 "모든 발견 처리"는 이 5건에 대해 틀렸다. 이번 수정에서 `06-10`~`06-14`로 다시 매기고 처리한다. + +## 2. 영역별 + +| 문서 | 리뷰 스킬 | Important | Minor | 판정 | 부분으로 판정한 원래 발견 | +|---|---|---|---|---|---| +| [01 core·application](01-core-application.md) | clean-architecture, domain-driven-design, codebase-design | 5 | 5 | With fixes | 01-07 | +| [02 inbound](02-inbound-transports.md) | api-and-interface-design, security-and-hardening | 4 | 4 | With fixes | 03-01, 03-11 | +| [03 persistence](03-persistence.md) | jpa-patterns, supabase-postgres-best-practices | 4 | 6 | With fixes | 04-03, 04-10, 06-07 | +| [04 outbound](04-outbound-capabilities.md) | performance-optimization, observability-and-instrumentation, security-and-hardening | 5 | 6 | With fixes | 05-16, 05-17, 05-18, 05-21 | +| [05 messaging](05-messaging.md) | domain-driven-design, observability-and-instrumentation, doubt-driven-development | 4 | 6 | With fixes | 06-06, 06-10~14(미조치) | +| [06 bootstrap·build·CI](06-bootstrap-build-ci.md) | ci-cd-and-automation, refactor, documentation-and-adrs | 3 | 9 | With fixes | 07-08, 07-10, 08-01, 08-04 | +| [07 보안](07-security.md) | security-and-hardening, security-review | 2 | 5 | With fixes | — | + +## 3. Important (중복 묶음) + +| 묶음 | ID | 내용 | 증거 | +|---|---|---|---| +| 권한 탈출구 | RR-01-02 = RR-07-01 | `@SystemInvoked`가 쓰기 유스케이스 권한 선언 규칙을 면제하는데, "bean 금지"는 주석뿐 | 탐침 테스트(bean으로 기동됨) | +| 데모 계정 | RR-07-02 | 거부가 정확히 `prod`에서만. 프로필 없음·`production`·`staging`이면 `demo-admin` 로그인 가능 | 탐침 테스트 | +| 순서 번호 | RR-03-01 | counter 첫 생성이 겹치면 두 번째 쓰기가 409 | 실 PG | +| 순서 번호 | RR-03-02 = RR-05-02 | counter가 없으면 1부터 시작 → 옛 벽시계 번호(~1.7e15)보다 작아져 소비자 순서가 뒤로 감 | 실 PG | +| 트랜잭션 | RR-03-03 | JPA 경로에서 트랜잭션 마감 초과가 미분류 500 | H2 재현 | +| JPA 규칙 | RR-03-04 | `mappedBy` 없이 양쪽 매핑한 양방향이 금지 규칙 통과 | 임시 fixture | +| GraphQL | RR-02-01 | union 아래 복잡도 0·page 상한 미검사(03-01 부분) | 임시 테스트 | +| wire 계약 | RR-02-02 | 서블릿 `/error` 디스패치가 `success:true` + 요청 경로 원문 | 실 Tomcat | +| wire 계약 | RR-02-03 | `IDEMPOTENCY_UNAVAILABLE` 503을 "실행 전 거부"라 적지만 complete 단계에선 작업이 이미 돎 | 코드 | +| gRPC ledger | RR-02-04 | 시도(owner) 구분이 없어 takeover 뒤 옛 owner 기록이 새 시도를 덮음 | 계약 fake | +| HTTP client | RR-04-01 | 호출자 deadline으로 끊은 시도를 breaker가 상대 장애로 셈 | 임시 테스트 | +| HTTP client | RR-04-03 | JDK 스트리밍 본문이 2초 response-header timeout에서 잘림(문서와 반대) | 임시 테스트 | +| Redis | RR-04-02 | 캐시 조건부 쓰기가 멱등성·rate-limit·lease와 8개짜리 SCRIPT lane 공유 | 코드·기본값 | +| Redis | RR-04-05 | Redis 멱등성 계약의 실서버 실행이 어느 게이트에도 없음 | 코드 | +| 파일 쿼터 | RR-01-05 = RR-04-04 | move가 namespace 쿼터를 옮기지 않아 상한 우회·장부 어긋남 | 코드 | +| 파일 계약 | RR-01-04 (+RR-07-06) | fileserver 저장 포트 9개 중 7개 공유 계약 없음, 쿼터 fake가 실제와 다름, 소유자 규칙 두 벌 | 코드 | +| 생성 명령 | RR-01-01 | 생성된 저장소 계약에 트랜잭션 hook이 없어 매뉴얼대로 만든 adapter가 상속 불가 | 생성 후 실험 | +| 매뉴얼 | RR-01-03 | 매뉴얼 3곳이 수정 뒤 코드와 반대, `IntegrationEventDrafts`를 지키는 장치 없음 | 코드 대조 | +| outbox 운영 | RR-05-01 | DEAD 재발행 SQL이 `deferred_attempt_count`를 안 되돌려 다시 DEAD | 실 PG | +| outbox 운영 | RR-05-03 | 끝나지 않는 재시도 행을 구분·처분할 수단 없음, bridge가 원인 코드를 버림 | 코드 | +| 이벤트 ID | RR-05-04 | 06-06 완료 기준(append 시점 거부) 미충족 | 코드 | +| 기동 rule | RR-06-01 (≈RR-04-09) | 기동 rule을 non-static `@Bean`으로 쓰면 설정 bean이 조용히 바인딩 안 됨 | 탐침 테스트 | +| build cache | RR-06-02 | `rejectSkipped`가 캐시 입력이 아니라 실패해야 할 lane이 FROM-CACHE 통과 | 실행 | +| CI | RR-06-03 | `verifyStrictLaneStages`가 optional-platforms를 안 봄 — `grpcPerformanceTest` 미실행 | 실행 | + +Minor 41건은 각 문서에 있다. + +## 4. 결정 (2026-11-03, 사용자 위임) + +| 항목 | 결정 | 이유 | +|---|---|---| +| 순서 번호 seed (RR-03-02) | counter가 없으면 전역 floor부터 시작한다. floor는 V21 적용 시각의 마이크로초(옛 벽시계 번호의 상한)로 마이그레이션이 한 번 기록한다. V21은 남은 행이 있는 aggregate의 counter를 그 최대값으로 미리 만든다 | 정리(reaper)로 행이 사라진 aggregate도 소비자가 본 번호보다 작게 시작하지 않는다. 새 aggregate의 첫 번호가 커지는 비용은 순서 보장보다 작다 | +| 데모 계정 (RR-07-02) | 거부 목록(`prod`)이 아니라 허용 목록: `local`·`test`·`demo` 프로필이 명시적으로 켜졌을 때만 데모 계정을 만든다 | 프로필 이름이 하나 다르면 열리는 구조가 사용자 원칙("위험은 코드에 드러나야")과 반대다 | +| `@SystemInvoked` (RR-01-02) | 기동 시 `@SystemInvoked` 유스케이스가 bean으로 등록돼 있으면 실패, ArchUnit으로 inbound adapter가 직접 부르지 못하게 한다 | 주석뿐인 규칙을 코드로 | +| 멱등성 complete 단계 실패 (RR-02-03) | complete 단계의 저장소 실패는 "결과 불명"으로 따로 알린다(실행 전 503과 구분). 같은 키 재전송 시 서버가 replay·in-flight·회복 필요로 판정한다는 것을 계약에 적는다 | 클라이언트가 "실행 안 됨"으로 믿고 새 키로 다시 보내는 위험을 막는다 | +| Redis SCRIPT lane (RR-04-02) | 캐시 조건부 쓰기는 멱등성·lease와 다른 연결 예산을 쓴다 | 캐시는 성능 기능이고 멱등성·lease는 정합성 기능이다. 캐시 부하가 정합성을 굶기면 안 된다 | +| build cache와 lane 정책 (RR-06-02) | lane 정책 값(`rejectSkipped` 등)을 모두 캐시 입력으로 | 정책을 바꿨는데 옛 결과가 통과하면 게이트가 아니다 | +| 끝나지 않는 재시도 (RR-05-03) | bridge가 원인 코드를 행에 남기고, 오래 재시도 중인 행 수·나이를 지표로 내고, runbook에 park(수동 보류)·재개 절차와 테스트된 SQL을 둔다 | 무한 재시도(15절 결정)를 유지하되 운영자가 보고 멈출 수 있어야 한다 | + +## 5. 다음 + +위 Important 전부, Minor 41건, 06-10~14를 영역별 수정 묶음으로 고친다. 각 묶음은 `5786126c`에서 만든 worktree에서 RED→GREEN, 오케스트레이터가 합쳐 전체 게이트 후 커밋·push한다. 결과는 이 문서 6절.