From 339cf8fdbf2f1d90b718ac403a3a8318dff58d8d Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Wed, 4 Nov 2026 02:06:33 +0900 Subject: [PATCH] =?UTF-8?q?docs(review):=203=EC=B0=A8=20=EC=88=98=EC=A0=95?= =?UTF-8?q?=EC=9D=98=20=ED=99=95=EC=9D=B8=20=EB=A6=AC=EB=B7=B0=20=EA=B2=B0?= =?UTF-8?q?=EA=B3=BC=EB=A5=BC=20=EA=B8=B0=EB=A1=9D=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 3차 수정 커밋(1885bf8d)이 또 새 결함을 만들었는지 알아야 리뷰 반복을 멈출 수 있다. 방법: 리뷰어 4명이 그 커밋만 영역별로 봤다. 새 Important 0, 회귀 0, Minor 19건. 재리뷰 README 9.1절의 멈춤 기준을 채웠다. Minor는 마지막 정리 라운드로 고치고, 그 뒤에는 Important만 고친다(11.1절). 위험·한계: Minor 중 JDK read-idle timeout 지연(공용 풀 포화 시)과 붙여 쓴 -x 거짓 통과는 동작에 닿는다. 아직 고치지 않았다. 검증: 리뷰 문서만 바뀐다. 리뷰어가 실행한 탐침은 각 문서 범위 절. Refs: docs/reviews/2026-11-03-rereview/README.md 11절 --- docs/reviews/2026-11-03-rereview/README.md | 24 ++ .../round3/01-core-app-inbound.md | 245 +++++++++++++++++ .../round3/02-persistence-messaging.md | 240 +++++++++++++++++ .../2026-11-03-rereview/round3/03-outbound.md | 227 ++++++++++++++++ .../round3/04-bootstrap-build-sample.md | 248 ++++++++++++++++++ 5 files changed, 984 insertions(+) create mode 100644 docs/reviews/2026-11-03-rereview/round3/01-core-app-inbound.md create mode 100644 docs/reviews/2026-11-03-rereview/round3/02-persistence-messaging.md create mode 100644 docs/reviews/2026-11-03-rereview/round3/03-outbound.md create mode 100644 docs/reviews/2026-11-03-rereview/round3/04-bootstrap-build-sample.md diff --git a/docs/reviews/2026-11-03-rereview/README.md b/docs/reviews/2026-11-03-rereview/README.md index bf9aba83..55545e28 100644 --- a/docs/reviews/2026-11-03-rereview/README.md +++ b/docs/reviews/2026-11-03-rereview/README.md @@ -184,3 +184,27 @@ Important 7건: - 실제 CI runner 실행: Gitea repo의 Actions가 꺼져 있어(`has_actions: false`) workflow가 돈 적이 없다. 켜는 것은 소유자 일이다. - 소유자 확인이 필요한 기본값: 10절 "결정" 칸 — 특히 lease 뒤 늦게 끝난 첫 시도의 결과를 버리는 것, workflow 명령에 `working-directory`가 필요해진 것. - 다음: 이 수정 커밋만 보는 확인 리뷰. 새 Important가 0이면 멈춘다(9.1절). + +## 11. 3차 확인 리뷰 (수정 커밋 `1885bf8d`만, 2026-11-04) + +3차 수정 커밋만 리뷰어 4명이 같은 템플릿·스킬 방식으로 봤다(`round3/01~04-*.md`). 심각도 기준(Important = 현실적 조건에서 틀린 동작·보안·데이터·공개 계약, 또는 운영자에게 틀린 조치를 시키는 문서)을 지침에 적었다. + +| 문서 | Important | Minor | 2차 발견 재확인 | 회귀 | +|---|---|---|---|---| +| [round3/01 core·inbound](round3/01-core-app-inbound.md) | 0 | 4 | RR-01-11~17 닫힘 | 0 | +| [round3/02 persistence·messaging](round3/02-persistence-messaging.md) | 0 | 5 | RR-02-09~16 닫힘(RR-02-10은 결정으로) | 0 | +| [round3/03 outbound](round3/03-outbound.md) | 0 | 5 | RR-01-11, RR-03-11~18 닫힘 | 0 | +| [round3/04 bootstrap·build·sample](round3/04-bootstrap-build-sample.md) | 0 | 5 | RR2-04-01~06 닫힘 | 0 | + +**9.1절 멈춤 기준을 채웠다**: 새 Important 0, 회귀 0. 리뷰어가 실행으로 확인한 것: `@SystemCaller` 위반 fixture가 실제로 실패, Redis Lua(abandon·늦은 complete 거부·기록 TTL), Flyway 안의 `SET LOCAL lock_timeout`(V22에서 그 줄을 지우면 lane 실패), 고친 마이그레이션 9개가 main `01a8a2a70`과 파생 서비스에 없음, 쿼터 SQL(실 PG), workflow 해석(축약 `-x`). + +Minor 19건 중 동작에 닿는 것: +- RR3-03-01 — JDK read-idle watchdog이 공용 `ForkJoinPool`에서 돌아, 공용 풀이 막히면 timeout이 늦다(300ms 설정이 2,699ms). 기본 transport(Apache)는 영향 없음. +- RR3-04-02 — 붙여 쓴 `-x`를 `verifyStrictLaneStages`가 읽지 않아 거짓 통과(이전부터). +- RR3-01-01 — `@SystemCaller` 규칙이 직접 의존만 본다. 같은 leaf 안에서 컨트롤러가 그 bean을 주입받으면 통과. +- RR3-04-01·03 — 인터페이스 타입 `static @Bean` 뒤의 `@Value` 비밀 목록, 코드가 든 Redis 계정 참조가 사전·`fixture-` 검사를 지난다(둘 다 이름을 대는 기동 실패이거나 비밀 아닌 경로). +- RR3-02-01·03·04 — 잠금 대기 검사기가 FK·trigger·`REINDEX`·`lock_timeout = 0`·소수 버전·gRPC ledger tree를 못 본다. + +### 11.1 결정 + +리뷰 반복은 여기서 멈춘다. Minor 19건은 사용자 지시("남은 부분 전부 진행")에 따라 마지막 정리 라운드(r6)로 고친다. r6의 멈춤 기준: 전체 게이트 통과 + r6 diff 확인 리뷰 1회에서 Important가 나오면 그것만 고치고, Minor는 남은 것으로 기록하고 더 돌지 않는다. diff --git a/docs/reviews/2026-11-03-rereview/round3/01-core-app-inbound.md b/docs/reviews/2026-11-03-rereview/round3/01-core-app-inbound.md new file mode 100644 index 00000000..bf2e6a0a --- /dev/null +++ b/docs/reviews/2026-11-03-rereview/round3/01-core-app-inbound.md @@ -0,0 +1,245 @@ +# 01 core·app·inbound·fileserver 3차 확인 리뷰 (2026-11-04) + +경로는 저장소 루트 기준이다. 코드 경로는 `src/`가 앞에 붙는다. + +## 범위 — 본 pathspec, 불러온 스킬과 적용한 기준, 실행한 명령과 결과, 못 본 것 + +### 본 pathspec + +- 리뷰 범위: Base `ecc74b7d` → Head `1885bf8d`(커밋 1개) 중 아래 pathspec. 57파일, +1,700 −199. + ```text + src/application-core src/application-fileserver src/adapter/inbound src/grpc src/composition/service-runtime + src/app-bootstrap/src/architectureTest docs/manual/07-authorization.md docs/manual/09-outbox-events.md + docs/adr/ADR-GRPC-004-retry-ownership-and-durable-idempotency.md docs/web/http-contract.md + docs/fileserver/operations.md docs/messaging/outbox-inbox.md + ``` +- 맡은 2차 재리뷰 발견: RR-01-12~17. RR-01-11은 03 리뷰어가 주로 보고, 이 문서는 `http-contract.md` 문구와 코드가 + 맞는지만 본다. +- 나눠 맡은 것: gRPC ledger 마이그레이션의 `lock_timeout`(V002·V003, `GrpcOperationLedgerMigrationLockWaitIT`)은 02 리뷰어 몫이다. + `application-core` 멱등성 변경은 계약(포트 Javadoc·공유 계약 케이스·executor 분기)만 봤다. +- 이 문서의 새 발견 ID는 `RR3-01-`로 시작한다. +- 읽은 방식: 하위 에이전트 없이 diff를 묶음별로 직접 읽었다. + 1. `@SystemCaller`·`@SystemInvoked`, ArchUnit 두 규칙과 fixture 6개, `PermissionEnforcementGuard`와 테스트, + `SystemInvokedConsumePathTest`, `InboxRedeliveryIntegrationTest` diff, 매뉴얼 07·09, messaging README·CLAUDE.md. + 2. `EnvelopeErrorController`·`HttpStatusErrorCodes`·새 `EnvelopeErrorControllerTest`, `http-contract.md` 두 절. + 3. `GraphQlClientPolicy` 삭제분과 옮긴 테스트. + 4. gRPC ledger `release` — 포트, JPA adapter, repository 쿼리, fake, 공유 계약 3케이스, ADR, `GrpcClaimToken` Javadoc. + 5. `DirectTransactionPort` 전체와 `TransactionPortContract` 새 케이스, `OverlappingWrites`. + 6. 멱등성 포트 Javadoc, `IdempotencyStoreContract` 시간 케이스 5개, `IdempotencyExecutor` claim·complete 분기. + 7. `FileQuotaLedgerContract` 롤백 케이스, `FakeFileQuotaService.inTransaction`, `operations.md` 「Namespace quota drift」. +- 범위 밖에서 확인용으로 읽은 것: + - 쿼터 장부 규칙: `DefaultCleanupService`(reclaim 조건·`isReclaimable`), `FinalizeUploadApplicationUseCase.commitReady`, + `CopyFileApplicationUseCase.publish`, `DefaultFileReconciliationService`, `MoveFileApplicationUseCase`, `FileState` 전이표. + - 쿼터 영속: `JpaFileQuota`, `JpaQuotaReclaim`, `FileserverQuotaRepository`, fileserver 마이그레이션 V1~V5. + - 멱등성: Redis `IdempotencyScripts.CLAIM`. + - 의존 경계: `modules.json`의 inbound leaf 간선, `adapter/inbound/messaging/gradle.lockfile`, `app-bootstrap/build.gradle`의 + architectureTest classpath. + +### 불러온 스킬과 적용한 기준 + +| 스킬 | 적용한 기준 | 무엇을 봤나 | +| --- | --- | --- | +| `superpowers:requesting-code-review` | 리뷰어 템플릿(Strengths → Critical/Important/Minor → Declined → Assessment), 실제 심각도로 분류, 읽지 않은 코드에 판정 금지, 하위 에이전트 금지 | 문서 양식 전체. 발견마다 round2 "고치는 법"과 9.1절·10절 결정을 코드로 대조 | +| `clean-architecture` | 의존은 안쪽으로, 경계는 다형성(포트)으로, composition root가 조립, framework는 바깥 원 | `@SystemCaller`가 application-core에 있는 방향, handler가 use case를 `new`로 만드는 조립 위치, 소비 경로가 web·messaging leaf 간선(`modules.json`)을 넘지 않는지 | +| `security-and-hardening` | 인가는 모든 요청에서, 신뢰 경계 지도, 숨은 우회 경로(STRIDE의 권한 상승) | 사용자 전송이 `@SystemInvoked` 쓰기에 닿는 경로를 직접 의존·중첩 클래스·한 단계 건너 호출로 나눠 탐침, 전송 타입 목록의 빈칸 | +| `api-and-interface-design` | 계약이 먼저, 일관된 오류 의미(status와 `error.code`), Hyrum's Law, 멱등 키의 세 결과와 in-flight 처리 | `/error` status 접기의 문서·코드 일치, 결과 불명 뒤 같은 키 재전송 판정이 Redis CLAIM과 executor에서 문서대로인지, ledger `release` 포트 시그니처 변경의 호환성 | + +### 실행한 명령과 결과 + +| 명령 | 결과 | +| --- | --- | +| `git diff --stat ecc74b7d..1885bf8d -- ` / `git diff …` | 57파일 +1,700 −199 | +| `git grep`으로 `effectivePageSize`, 옛 규칙 이름 `INBOUND_ADAPTERS_DO_NOT_REACH_SYSTEM_INVOKED_USE_CASES`, `.release(`·`deleteById`, `reservedBytes` 읽는 곳, `FileState.*` 전이 전수 | 복사본·옛 이름·다른 `release` 호출자 0건. `reservedBytes` 합산은 `status = 'RESERVED'` 쿼리 하나뿐 | +| `git worktree add --detach /rr3-01 1885bf8d` 후 architectureTest에 탐침 테스트 1개와 탐침 클래스 2개 추가, `flock … ./gradlew :app-bootstrap:architectureTest --tests 'dev.caskeleton.bootstrap.architecture.Rr3SystemCallerProbeTest' --console=plain -i` | `BUILD SUCCESSFUL in 14s`. 출력은 아래 표(RR3-01-01 증거) | +| `flock … docker run postgres:16-alpine` + `psql` — V1의 `fs_file`·`fs_quota_reservation`과 V5의 `fs_file` 변경을 만들고, 문서의 두 SQL 블록을 문서 그대로 `psql -v namespace=…`로 실행 | 보정 전 drift 2행(`ns-a +140`, `ns-b −140`) → 두 namespace 보정 → 0행. `RESERVED` 999 행은 그대로. 보정 뒤 newest-first reclaim 한 번 → drift 0행 유지. 넣은 행의 `reserved_bytes`가 180(RR3-01-03) | +| `git worktree remove --force /rr3-01`, 컨테이너 `docker rm -f` | 탐침과 함께 삭제. 이 체크아웃은 clean | + +탐침 출력(`RR3-PROBE` 줄 그대로): + +| 탐침 | 가져온 클래스 | `ONLY_SYSTEM_CALLERS_…` 위반 | `SYSTEM_CALLERS_ARE_…` 위반 | +| --- | --- | --- | --- | +| existing-fixture-web-marked | `SystemCallerControllerFixture` + use case | false | **true** | +| existing-fixture-rest-in-messaging | `SystemCallerRestControllerFixture` + use case | false | **true** | +| controller-calls-system-caller | `@RestController`가 `SystemCallerHandlerFixture`를 주입받아 `handle()` 호출 + handler + use case | false | false | +| nested-endpoint-in-system-caller | `..adapter.inbound.scheduler..`의 `@SystemCaller` 클래스 + 그 안의 `@RestController` nested 클래스(`@PostMapping`에서 use case 호출) + use case | false | false | + +### 못 본 것 + +- 전체 게이트는 다시 돌리지 않았다. 재리뷰 README 10.2절 결과를 읽기만 했다. +- `SystemInvokedConsumePathTest`, `InboxRedeliveryIntegrationTest`, gRPC ledger PG lane, `SpringTransactionContractTest`, + `PostgreSqlFileQuotaLedgerContractTest`, Redis·PG 멱등성 lane은 다시 돌리지 않았다. 10절의 r5-a·r5-b 검증 기록에 기댄다. +- JAX-RS·graphql-java `DataFetcher`로 만든 탐침은 돌리지 않았다. app-bootstrap architectureTest의 컴파일 classpath에 그 + 라이브러리가 없다. RR3-01-02는 규칙 코드를 읽은 것(E1)이다. +- 쿼터 SQL은 손으로 만든 시나리오 하나로 돌렸다. 실제 앱이 만든 데이터로 돌린 것은 아니다. + +## Strengths + +- 표시 검사가 실제로 실패한다. 기존 위반 fixture 두 개(`SystemCallerControllerFixture`, `SystemCallerRestControllerFixture`)를 + 탐침에서 따로 돌려 `SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS` 위반을 확인했다. 표시 없는 handler(`:214`), + web 패키지 표시(`:232`), messaging 패키지의 HTTP endpoint(`:241`)를 각각 단언한다 + (`src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ArchitectureViolationFixtureTest.java`). +- 패키지 쪽은 허용 목록이다(`ApplicationBoundaryArchitectureTest.java:456-457`). 새 inbound 패키지는 규칙을 고치지 않아도 표시를 + 달 수 없다. +- 기동 가드는 예외를 늘리지 않았다(`PermissionEnforcementGuard.java:69`). 버린 대안("handler만 주입받으면 허용")과 이유가 README에 + 남았다(`src/adapter/inbound/messaging/README.md:104-116`). +- 소비 경로가 단위·실제 lane 둘 다로 고정됐다. 단위는 가드 아래 기동과 use case bean 거부다(`SystemInvokedConsumePathTest.java:83,128`). + 실제 lane은 Kafka+PG `ProjectionHandler`가 같은 모양이다. +- `/error`의 status 접기를 문서·Javadoc·테스트가 같은 말로 적는다. 버린 대안도 Javadoc에 있다(`EnvelopeErrorController.java` 클래스 Javadoc, + `docs/web/http-contract.md:63-68`, `EnvelopeErrorControllerTest` 8케이스). +- ledger `release`가 다른 전이와 같은 조건부 한 문장이다(`GrpcOperationLedgerRepository.java:243-249`). fake와 PG가 공유 계약 + 3케이스를 같이 받는다(`GrpcOperationLedgerContract.java:438,452,470`). "삭제 뒤 attempt 1부터"라는 한계를 Javadoc과 ADR에 적었다. +- `DirectTransactionPort`가 스레드별 트랜잭션이다(`DirectTransactionPort.java:56`). 같은 모양의 계약 케이스를 fake와 Spring 어댑터가 + 둘 다 받는다(`TransactionPortContract.java:311`). 이제 `OverlappingWrites`가 fake에서도 두 트랜잭션을 연다. +- 쿼터 롤백 계약은 reserve·commit·reclaim을 한 호출자 트랜잭션에서 실패시키고 양쪽 scope를 본다(`FileQuotaLedgerContract.java:320`). + `inTransaction`을 abstract로 바꿔 구현마다 실제 롤백을 고르게 했다. +- 결과 불명 계약 문구가 코드와 맞는다. CLAIM은 lease가 지난 `EXECUTING`을 `ABANDONED`로 바꾸고 `RECOVERY_REQUIRED`를 준다 + (`IdempotencyScripts.java:89-93`). 늦게 끝난 holder의 complete는 `NOT_OWNER`이고 executor는 이것을 500으로 바꾼다 + (`IdempotencyExecutor.java:256`). 공유 계약이 둘 다 묶는다(`IdempotencyStoreContract.java:449,466`). + +## 발견 재확인 표 + +| ID | 상태 | 근거 | +| --- | --- | --- | +| RR-01-11 (문구만) | 닫힘 | `http-contract.md:119-127`의 "다시 돌리지 않는다·lease 뒤 500·늦은 완료도 500"이 Redis CLAIM(`IdempotencyScripts.java:89-93`), executor complete 분기(`IdempotencyExecutor.java:256`), 공유 계약(`IdempotencyStoreContract.java:449,466`)과 맞다. 예외 Javadoc의 롤백 범위도 "쓰기 트랜잭션 안에서 부른 경우"로 좁혔다(`IdempotencyCompletionUnknownException.java:11-16`). 저장소 구현의 닫힘 판정은 03 몫 | +| RR-01-12 | 닫힘(결정대로) | 9.1절 결정이 다 들어갔다. 사용자 전송만 막고 시스템 호출자는 표시로 허용한다(`ApplicationBoundaryArchitectureTest.java:515,539`, `SystemCaller.java`). 매뉴얼 09장 4단계는 테스트로 고정했다(`SystemInvokedConsumePathTest`, `InboxRedeliveryIntegrationTest`). 위반 fixture 실패는 탐침으로 재확인했다. 남은 틈 → RR3-01-01, 02, 04 | +| RR-01-13 | 닫힘 | "표에 있는 status만 그대로, 나머지는 class 코드로 접힌다"를 정본과 Javadoc에 적었다(`http-contract.md:63-68`). 실제 표(`HttpStatusErrorCodes.java:20-35`)와 문서의 status 목록이 같다. 파라미터 테스트 8케이스 | +| RR-01-14 | 닫힘 | `GraphQlClientPolicy.effectivePageSize` 삭제. 같은 규칙의 다른 복사본은 `GraphQlConnectionPolicy.java:35` 하나뿐이다(grep). 옮긴 테스트(`GraphQlConnectionAssemblerTest` backward 케이스), 업그레이드 안내 B-10 | +| RR-01-15 | 닫힘 | `release(identity, claimToken)`은 `DELETE … WHERE state = 'IN_PROGRESS' AND claim_attempt = :attempt` 한 문장이다(`GrpcOperationLedgerRepository.java:243-249`, `JpaGrpcOperationLedger.java:204`). fake도 같은 조건이다(`InMemoryOperationLedger.java:159`). 계약 3케이스. Javadoc은 "한 행 안에서만"으로 좁혔다(`GrpcClaimToken.java`). main 호출자는 없다(grep) | +| RR-01-16 | 닫힘 | `Map`(`DirectTransactionPort.java:56`)과 계약 케이스(`TransactionPortContract.java:311`). fake와 `SpringTransactionContractTest`(PG)가 상속한다 | +| RR-01-17 | 닫힘 | 롤백 계약 케이스는 fake와 `PostgreSqlFileQuotaLedgerContractTest`가 받는다(`FileQuotaLedgerContract.java:320`). 재계산 SQL은 `operations.md` 「Namespace quota drift」에 있다. SQL은 코드의 장부 규칙과 맞는다 — publish와 commit이 한 트랜잭션, 정리 reclaim과 `DELETED` 전이가 한 트랜잭션, `REJECTED`·`EXPIRED`는 `published_at`이 없다. 실 PG16에서 확인했다. 작은 틈 → RR3-01-03 | + +회귀로 판정한 발견은 없다. + +## Issues + +### Critical (Must Fix) + +없음. + +### Important (Should Fix) + +없음. + +### Minor (Nice to Have) + +#### RR3-01-01 · `@SystemCaller` 규칙은 표시된 클래스의 직접 의존만 본다 — 사용자 전송이 그 bean을 부르거나 그 안에 중첩되면 두 규칙 모두 통과한다 + +- **위치**: `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ApplicationBoundaryArchitectureTest.java:490-503`(`ARE_SYSTEM_CALLERS`), + `:515-527`(`ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`), `:539-555`(`SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`, `.areAnnotatedWith` `:542`), + `src/application-core/src/main/java/dev/caskeleton/application/security/SystemCaller.java:23-25`, `docs/manual/07-authorization.md:74` +- **무엇이 틀렸나**: + - (a) 한 단계 건너 호출. `@RestController`가 `@SystemCaller` handler·job bean을 주입받아 메서드를 부른다. 그 컨트롤러는 + `@SystemInvoked` 클래스에 직접 의존하지 않으므로 첫 규칙을 통과한다. 표시가 없으므로 둘째 규칙의 대상도 아니다. + - (b) 중첩 클래스. 첫 규칙은 `@SystemCaller` 안에 중첩된 클래스를 면제한다(`ARE_SYSTEM_CALLERS`). 둘째 규칙은 표시가 직접 붙은 + 클래스만 검사한다(`:542`). 그래서 표시된 job 안의 `@RestController` nested 클래스는 사용자 전송 타입에 의존해도 아무 규칙에도 + 걸리지 않는다. 면제하는 집합과 검사하는 집합이 다르다. + - 문서는 더 강하게 말한다. `SystemCaller.java:25` "nothing but this adapter holds it", 매뉴얼 07장 `:74` "사용자 요청 ─▶ web… ──✗──▶ + @SystemInvoked (빌드 실패)". +- **왜 중요한가**: + - 발생 조건: 사용자 전송과 `@SystemCaller`가 같은 Gradle leaf에 있어야 한다. 그 leaf의 컴파일 classpath에 web 타입도 있어야 한다. + - 등록된 leaf에서는 막힌다. `adapter:inbound:messaging`의 compileClasspath에는 spring-web이 없다(`gradle.lockfile:240`은 test 쪽만). + `adapter:inbound:web`은 messaging leaf에 의존할 수 없다(`modules.json` allowed_dependencies). + - `..adapter.inbound.scheduler..`는 등록된 leaf가 없다. 서비스가 이것을 자기 feature leaf에 두면 조건이 선다. sample-portfolio처럼 + `adapter.inbound.web`과 같은 leaf다. + - 영향: "지금 실행" 같은 관리 endpoint가 job bean을 부르면 권한 검사 없는 쓰기가 사용자 요청으로 돈다. 이 템플릿은 인가를 use case에 + 두므로 컨트롤러에는 권한 검사가 없다. 인증만 있으면 누구나 부를 수 있다. 빌드는 아무 신호도 내지 않는다. + - 일부는 이전부터다. 한 leaf 안에서 조립 모듈이 만든 scheduler bean을 컨트롤러가 주입받는 길은 지난 라운드에도 있었다. 이번 + 라운드는 시스템 호출자를 inbound 패키지의 bean으로 두는 길을 문서화된 정식 경로로 만들었고, 그 위에 "빌드 실패"를 적었다. + - Minor로 둔 이유(경계): 컨트롤러가 job을 부르는 코드가 눈에 보인다. 등록된 leaf 사이에서는 direction gate가 막는다. endpoint는 여전히 + 인증을 요구한다. (b)는 일부러 만들지 않으면 생기지 않는 모양이다. +- **고치는 법**: + 1. 둘째 규칙의 대상을 `.that(ARE_SYSTEM_CALLERS)`로 바꾼다. 면제한 중첩 클래스도 같은 검사를 받는다. + 2. 규칙 하나를 더한다. 사용자 전송 클래스는 `@SystemCaller` 클래스에 의존하지 않는다. 사용자 전송 클래스는 사용자 전송 패키지에 + 있거나 `ARE_USER_TRANSPORT_TYPES`에 의존하는 클래스다. handler를 등록하는 같은 leaf의 `@Configuration`은 막지 않아야 하므로 + "inbound 전체" 대신 이 범위로 한다. + 3. 위 탐침 두 개를 위반 fixture로 넣는다. + 4. 규칙을 더하지 않는다면, 매뉴얼 07장 `:74`와 `SystemCaller.java:25`에 "한 단계 의존만 본다"를 적는다. +- **가이드 심각도·우선순위**: Low · P3 (경계: 같은 leaf 조건이 서면 Medium) +- **증거**: E3 — 범위 절 탐침 표의 `controller-calls-system-caller`, `nested-endpoint-in-system-caller` 두 줄. 둘 다 두 규칙 모두 위반 없음. + +#### RR3-01-02 · 사용자 전송 "타입" 검사는 나열 목록이다 — README가 버린 대안의 이유가 이 절반에 그대로 남는다 + +- **위치**: `ApplicationBoundaryArchitectureTest.java:466-483`(`ARE_USER_TRANSPORT_TYPES`), `src/adapter/inbound/messaging/README.md:115-116`, + `docs/manual/07-authorization.md:89-90` +- **무엇이 틀렸나**: + - README는 "사용자 전송 패키지만 나열해 금지"를 버렸다. 이유는 "나중에 새 전송이 생기면 조용히 열린다"이다. 매뉴얼 07장도 + "새 전송이 생겨도 따로 고치지 않아도 막힌다"고 적는다. + - 규칙의 패키지 쪽은 허용 목록이라 이 말이 맞다. 그러나 "시스템 패키지 안에 놓인 전송 endpoint"를 잡는 타입 쪽은 나열 목록이다 + (Spring web·GraphQL·STOMP·gRPC·servlet·`jakarta.websocket`). + - 목록에 없는 전송이 있다. JAX-RS(`jakarta.ws.rs`), graphql-java `DataFetcher`(`graphql.schema`), DGS 등이다. 이런 endpoint를 + messaging·scheduler 패키지에 두고 표시를 달면 통과한다. +- **왜 중요한가**: 문서가 약속한 성질("새 전송도 자동으로 막힌다")이 규칙의 절반에서만 참이다. 그 프레임워크가 시스템 호출자 + leaf의 classpath에 있어야 하므로 발생 조건은 좁다. +- **고치는 법**: 두 문서에 "패키지는 허용 목록, 전송 타입은 목록이고 새 전송 라이브러리를 들이면 여기에 더한다"를 적는다. + `jakarta.ws.rs..`와 `graphql..`(graphql-java)는 지금 목록에 더한다. +- **가이드 심각도·우선순위**: Low · P3 · **증거**: E1(규칙 코드와 문서 대조) + +#### RR3-01-03 · 쿼터 보정 SQL이 COMMITTED 행에 `reserved_bytes = held`를 쓴다 — 코드는 확정 행의 예약 바이트를 0으로 둔다 + +- **위치**: `docs/fileserver/operations.md:183-187`, 비교 대상 `src/adapter/outbound/persistence-fileserver/src/main/java/dev/caskeleton/adapter/outbound/persistence/fileserver/repository/FileserverQuotaRepository.java` + `commit` 쿼리(`q.reservedBytes = 0`), 서술 `operations.md:135-136` +- **무엇이 틀렸나**: + - INSERT 값이 `held, held`라서 `reserved_bytes`와 `committed_bytes`가 둘 다 재계산 값이다. 코드의 commit은 COMMITTED로 바꾸면서 + `reserved_bytes`를 0으로 둔다. 코드가 만들지 않는 행 모양이다. + - 실 PG에서 보정 뒤 `ns-b | COMMITTED | 180 | 180`이 나왔다. + - 서술 `:135-136` "reclaim stops at zero and leaves the old booking behind"는 도착 namespace에 다른 파일의 booking이 없을 때만 맞다. + 있으면 reclaim이 그 파일들의 booking을 newest-first로 깎는다. PG 시나리오에서 `ns-b`의 두 행이 30→0, 50→40이 됐다. + drift 쿼리가 이것도 잡으므로 조치는 맞다. +- **왜 중요한가**: + - 지금 enforcement는 영향이 없다. `sumReservedBytes`가 `status = 'RESERVED'`만 합산한다(grep 결과 다른 읽는 곳 없음). + - 그러나 status 없이 `reserved_bytes`를 합산하는 운영 쿼리·대시보드는 보정한 namespace 크기만큼 부풀린다. 운영자가 손으로 넣는 + 행이 코드 규칙과 갈라지는 것이라 나중에 원인을 찾기 어렵다. +- **고치는 법**: INSERT 값을 `0, held`로 바꾼다. `:135-136`은 "도착 namespace에서 회수하므로, 그쪽 다른 파일의 booking을 깎거나 + 0에서 멈춘다"로 고친다. +- **가이드 심각도·우선순위**: Low · P3 +- **증거**: E3 — 실 PostgreSQL 16에 문서의 두 SQL을 그대로 실행했다(범위 절). drift 계산과 보정 결과는 맞고, 넣은 행의 + `reserved_bytes`만 코드와 다르다. + +#### RR3-01-04 · scheduler 쪽 `@SystemCaller` 경로를 문서마다 다르게 적는다 + +- **위치**: 허용 쪽 — `ApplicationBoundaryArchitectureTest.java:456-457`, `SystemCaller.java:10-11`, `SystemInvoked.java:20-22`, + `docs/manual/07-authorization.md:87`. 부정 쪽 — `docs/manual/07-authorization.md:75,105-106`, `src/application-core/CLAUDE.md:205-206`, + 업그레이드 안내 B-16 "해야 할 일" 칸 +- **무엇이 틀렸나**: + - 규칙과 두 Javadoc은 `..adapter.inbound.scheduler..`의 `@SystemCaller` scheduled job을 허용한다. README 10절 "결정" 칸의 + "scheduler 패키지도 `@SystemCaller` 허용"이다. + - 매뉴얼 07장은 다르게 적는다. 흐름도는 scheduler를 "조립 모듈이 new로 넘김" 하나로 그린다. 「지금 이해하면 되는 것」은 + "부르는 쪽은 스케줄러 조립이나 `@SystemCaller` 메시지 handler뿐이다"라고 적는다. + - application-core CLAUDE.md와 B-16도 scheduler는 composition으로만 적는다. +- **왜 중요한가**: 두 갈래 설명이다. scheduler 패키지에 대한 작업 순서·위치(등록 leaf 없음)·예시가 어디에도 없다. RR3-01-01의 + 조건이 서는 곳이 바로 이 패키지다. +- **고치는 법**: 하나를 고른다. + - 허용을 유지하면: 07장 흐름도와 「지금 이해하면 되는 것」, CLAUDE.md, B-16에 세 번째 경로를 넣는다. 어느 leaf에 + 두는지와 RR3-01-01의 주의도 적는다. + - 쓰지 않을 거면: `SYSTEM_DRIVEN_INBOUND_PACKAGES`에서 scheduler를 빼고 Javadoc을 맞춘다. +- **가이드 심각도·우선순위**: Low · P3 · **증거**: E1 + +## Declined to judge + +- gRPC ledger V002·V003 `SET LOCAL lock_timeout`과 `GrpcOperationLedgerMigrationLockWaitIT`: 02 리뷰어 몫으로 나눠 맡았다. +- Redis·PG 멱등성 store의 기록 수명(lease + replay TTL)과 설정 검사: 03 리뷰어 몫이다. CLAIM 스크립트는 계약 문구 대조에 필요한 만큼만 읽었다. +- `FakeFileQuotaService.inTransaction`은 `DirectTransactionPort.onRollback`과 따로 도는 두 번째 롤백 장치다. use case 테스트(fake + + `DirectTransactionPort`)에서는 여전히 쿼터가 롤백되지 않는다. 이번 라운드의 목표(포트가 `inNew`로 옮겨가면 잡기)는 계약 케이스가 + 채운다. use case 테스트가 롤백 뒤 쿼터를 단언하는 곳도 없어서 판정하지 않았다. +- `/error`에서 408·409·422가 400 `BAD_PARAMETER`로 접히는 것: 클라이언트가 보는 동작 변화지만, 버린 대안과 함께 Javadoc·정본에 결정으로 적혔다. +- `release`가 끝난 기록(`FAILED_TERMINAL` 등)을 지우지 못해 그 키를 다른 요청에 풀어 줄 길이 purge뿐인 것: ADR-GRPC-004에 버린 대안과 함께 적혔다. +- optional-platforms 빌드(`grpc:*`)가 ArchUnit import에 없는 것: `app-bootstrap/build.gradle` 주석에 소유자 결정으로 적힌 이전부터의 범위다. +- `PermissionEnforcementGuard`가 선언 타입이 인터페이스인 bean을 못 보는 것: 2차 재리뷰가 이미 판정을 미뤘고 이번 diff가 바꾸지 않았다. + +## 수렴 판단 + +**이 영역에서 이번 라운드가 만든 새 Important 이상은 없다.** + +- 2차 재리뷰 발견 RR-01-12~17은 모두 닫혔다. RR-01-11의 `http-contract.md` 문구도 코드와 맞는다. 회귀는 없다. +- 새 발견은 Minor 4건이다. 셋(RR3-01-01, 02, 04)은 `@SystemCaller` 규칙의 범위와 문서 표현이다. 하나(RR3-01-03)는 보정 SQL의 행 + 모양이다. +- 가장 무거운 것은 RR3-01-01이다. 같은 leaf에 사용자 전송과 시스템 호출자를 둔 서비스에서만 서는 경계 사례라 Minor로 뒀다. + 다음 정리 때 규칙 한 줄(중첩 클래스 검사)과 규칙 하나(전송 → 시스템 호출자 의존 금지)로 닫을 수 있다. +- 이 영역만 보면 다음 수정 라운드가 필요하다는 근거는 없다. + +## Assessment + +**Ready to merge? Yes** + +9.1절 결정과 round2 "고치는 법"이 코드·계약 테스트·문서에 들어갔다. 실 PG와 ArchUnit 탐침으로 확인한 결과 머지를 막는 결함은 없다. +남은 Minor 4건은 규칙 범위와 문서 표현이라 다음 정리 묶음에서 고치면 된다. diff --git a/docs/reviews/2026-11-03-rereview/round3/02-persistence-messaging.md b/docs/reviews/2026-11-03-rereview/round3/02-persistence-messaging.md new file mode 100644 index 00000000..bad1d503 --- /dev/null +++ b/docs/reviews/2026-11-03-rereview/round3/02-persistence-messaging.md @@ -0,0 +1,240 @@ +# 02 persistence·messaging 3차 확인 리뷰 (2026-11-04) + +경로는 저장소 루트 기준이다. 코드 경로는 `src/`가 앞에 붙는다. + +## 범위 — 본 pathspec, 불러온 스킬과 적용한 기준, 실행한 명령과 결과, 못 본 것 + +### 본 pathspec + +- 리뷰 범위: Base `ecc74b7d` → Head `1885bf8d`(커밋 1개, 3차 수정 묶음 r5-c) 중 아래 pathspec. 48파일, +1,719 −134. + ```text + src/adapter/outbound/persistence-jpa src/adapter/outbound/persistence-notification src/composition/outbox-relay + src/messaging src/sample-portfolio/src/main/resources/db src/sample-portfolio/src/test + src/grpc/grpc-operation-ledger-jpa/src/main/resources src/grpc/grpc-operation-ledger-jpa/src/integrationTest + docs/jpa docs/runbooks/migration-failed.md docs/runbooks/outbox-dead-letter.md docs/runbooks/outbox-publish-failed.md + docs/manual/04-persistence.md docs/manual/09-outbox-events.md docs/registries/metrics.yaml + docs/upgrade/2026-11-maturity-review.md + ``` +- 맡은 2차 재리뷰 발견: `round2/02-persistence-messaging.md`의 RR-02-09~16. +- 새 발견 ID는 `RR3-02-01`부터다. +- 이 pathspec 안이지만 다른 리뷰어 몫이라 결함 판정을 하지 않은 것: persistence-jpa의 PostgreSQL 멱등성 store 변경 + (`IdempotencyClaimGateway`, `IdempotencyTransitionGateway`, `PostgreSqlIdempotencyStoreContractTest`, README 「만료」 문단 — 03), + `docs/manual/09-outbox-events.md`의 `@SystemCaller` 소비 경로 절(01), `SampleDemoSecurityConfigTest`(04), + `JpaGrpcOperationLedgerContractIT`의 `release(identity, claimToken)`(01), metrics.yaml의 Redis lane 항목(03). +- 읽은 방식: 하위 에이전트 없이 여러 번에 나눠 직접 읽었다. + 1. 마이그레이션 8개 diff 전부와 `applied-migrations.sha256`, `git log`로 각 파일이 main(`01a8a2a70`)에 있었는지. + 2. `LockWaitMigrationInspector` 전문, `MigrationLockWaitTest`·`MigrationTrees`·`AppliedMigrationImmutabilityTest` diff, + `SampleMigrationLockWaitTest`, `LockWaitMigrationInspectorTest` 케이스, `ConcurrentIndexMigrationInspector`와 그 사용처. + 3. `PostgreSqlMigrationLockWaitIntegrationTest`, `GrpcOperationLedgerMigrationLockWaitIT`, `GrpcOperationLedgerMigrations` diff. + 4. `JpaOutboxStore`·`OutboxEventEntity` diff와 claim 경로(`PostgreSqlOutboxClaimRepository`의 `FOR UPDATE SKIP LOCKED`, + `OutboxEventJpaRepository`의 fenced UPDATE), entity를 바꾸는 다른 경로가 있는지(grep: claim만 있다). + 5. `OutboxMetrics`의 게이지 갱신, `countLongRetries` JPQL, `OutboxLongRetryRunbookContractTest`와 그 lane 설정. + 6. `SingleSidedAssociationCondition` diff와 새 fixture, `KafkaDeadLetterQuarantine`과 새 테스트. + 7. runbook 세 개·migration-guide·entity-mapping-guide·manual 04·09·metrics.yaml·upgrade 문서의 이 영역 diff, + 운영자가 쓰는 `infra/postgres/apply-capability-streams.sh`(Flyway CLI 기본 트랜잭션인지). + +### 불러온 스킬과 적용한 기준 + +| 스킬 | 적용한 기준 | 무엇을 봤나 | +|---|---|---| +| `superpowers:requesting-code-review` | 리뷰어 템플릿: 요구사항(9.1절 결정·round2 「고치는 법」) 정합, 테스트가 mock이 아닌 실제 동작을 보는지, 마이그레이션 전략·하위 호환, Declined to judge, 심각도 보정, 읽지 않은 코드를 칭찬하지 않기 | 발견 8건의 닫힘 여부, 새 lane이 RED가 되는지 직접 확인, 이미 적용된 파일을 고쳤는지 git 이력으로 확인 | +| `jpa-patterns` | Flyway가 스키마를 소유하고 Hibernate는 validate만, 짧은 트랜잭션, entity 갱신의 실제 SQL(전체 열 UPDATE), 연관관계 규칙(사용자 원칙 "양방향 금지") | `last_failure_code`를 `updatable`로 바꾼 뒤의 claim flush가 다른 relay·fenced UPDATE와 겹칠 때(RR-02-12), `why()` 메시지가 join column·join table 구조와 맞는지(RR-02-15·RR3-02-05) | +| `supabase-postgres-best-practices` | `lock-short-transactions`(DDL 잠금 대기는 `lock_timeout`으로 묶는다), `lock-skip-locked`(claim은 잠긴 행을 건너뛴다), `schema-foreign-key-indexes`(FK가 부모 표를 잠근다), `monitor-*`(`pg_stat_activity`·`pg_locks`로 원인 세션 찾기) | `SET LOCAL`이 Flyway 트랜잭션 안에서 걸리는지(실 PG lane, RED 확인), 트랜잭션 밖이면 무효인지(실 PG), 검사기가 못 잡는 잠금 문장(실 PG), runbook의 원인 세션 조회가 원인을 가려내는지(실 PG) | +| `observability-and-instrumentation` | 경보는 증상 기반·실행 가능·runbook 연결, 지표 label 집합이 작고 고정, 모르는 값은 조용히 버리지 말고 이름을 남긴다 | `outbox.pending.size{status=DEAD} > 0` p1 경보(해소 경로가 있는지 — 재발행·skip 모두 DEAD를 벗어난다), 모르는 상태 값 WARN 1회, lag 게이지가 그 행을 여전히 세는지 | + +### 실행한 명령과 결과 + +메인 작업 트리·index·HEAD는 바꾸지 않았다(끝에 `git status --short` 빈 출력). 실행은 scratchpad에서 했다. + +| 명령 | 실행 직전 부하(1분) | 결과 | +|---|---|---| +| `git diff --stat ecc74b7d..1885bf8d -- `, `git diff ...` | — | 48파일. 나눠서 전부 읽었다 | +| `git log --follow`·`git cat-file -e 01a8a2a70:` (고친 마이그레이션 9개) | — | 9개 모두 main에 없다. 처음 들어온 커밋은 `34565130`·`1400dc15`·`5786126c`·`bbe944bd`, 모두 이 브랜치에만 있다(`git branch -a --contains`: 이 브랜치와 그 origin 추적 브랜치). 파생 서비스 `tech-log-backend`에는 네 커밋 모두 없다 | +| 동결 목록 24개 각각 `git ls-tree 01a8a2a70` | — | 24개 모두 main에 있다 | +| `sha256sum` V20·V22·알림 V11~V13 vs `applied-migrations.sha256` | — | 5개 모두 일치 | +| `javac`+`java Probe` (scratchpad, `LockWaitMigrationInspector`를 `git show 1885bf8d:`로 꺼내 컴파일) | — | FK가 있는 `CREATE TABLE`, `CREATE TRIGGER`, `DROP TRIGGER`, `REINDEX TABLE` → `[]`(못 잡음). `SET LOCAL lock_timeout = 0` → 상한으로 인정. 열 이름 `lock` → 오탐. 대조군 `ALTER TABLE` → 잡음 | +| `flock heavy.lock exp.sh` (postgres:16-alpine, 컨테이너 안 psql) | 2.24 | rc=0. **EXP1**: `parent`에 쓴 트랜잭션을 12초 열어 둠 → `CREATE TABLE child (... REFERENCES parent)`가 `ShareRowExclusiveLock` granted=false로 11.09초 기다림, 그동안 3초 제한의 `INSERT INTO parent`가 `canceling statement due to statement timeout`(3.06초). **EXP2**: 트랜잭션 밖 `SET LOCAL lock_timeout`은 `WARNING: SET LOCAL can only be used in transaction blocks` | +| `flock heavy.lock exp2.sh` (같은 이미지) | 2.4 근처 | rc=0. `outbox_event`를 읽은 뒤 다른 문장을 하나 더 하고 idle in transaction인 세션(93)과, 다른 표만 읽은 보고 세션(91)을 열어 둠 → 상한 있는 `ALTER TABLE`은 `canceling statement due to lock timeout`. runbook 조회(`pg_stat_activity WHERE xact_start < now() - 5s`)는 **91·93 둘 다** 내고 93의 `query`는 `SELECT 1 AS later_statement`. `pg_locks`의 `relation = 'outbox_event'::regclass`는 93만 낸다 | +| worktree `git worktree add --detach /rr3-02 1885bf8d` 후 `flock heavy.lock ./gradlew :adapter:outbound:persistence-jpa:postgresqlMigrationLockWaitIntegrationTest :adapter:outbound:persistence-jpa:test --tests '*MigrationLockWaitTest' --tests '*LockWaitMigrationInspectorTest' --console=plain` | 3.19 | rc=0, 35초. lane 5/5(V20·V22·알림 V11·V12·V13 각각 5.25~5.60초 — 상한 5초에서 끝남), `MigrationLockWaitTest` 2/2, `LockWaitMigrationInspectorTest` 16/16 | +| 같은 worktree에서 V22의 `SET LOCAL` 줄을 지우고 같은 lane | — | **rc=1, V22 케이스만 FAILED**(5개 중 1개). lane이 상한 누락을 실제로 잡는다(RED 확인). 파일 되돌린 뒤 `git worktree remove --force` | +| `java Re.java` (scratchpad) | — | `V22_1__x.sql`: `MigrationTrees` 정규식 false, sample 정규식 true | + +### 못 본 것 + +- 알림·sample·grpc 마이그레이션의 실 PG 실행은 게이트 기록(재리뷰 README 10.2)과 위 lane 5개를 따랐다. sample V8_1은 실 PG + 잠금 대기 테스트가 없고 텍스트 검사만 있다(Declined 참고). +- `GrpcOperationLedgerMigrationLockWaitIT`는 직접 돌리지 않았다(`-p optional-platforms integrationCheck` 게이트 기록을 따름). + 이 테스트는 Flyway가 아니라 JDBC로 한 트랜잭션에 파일 전체를 실행한다. +- claim DEAD 전이와 옛 lease 소유자의 fenced UPDATE 경쟁은 실행하지 않았다. PostgreSQL READ COMMITTED의 `FOR UPDATE` + 재검사 규칙과 코드 경로로 판단했다(E1). +- 실제 Kafka broker, 다중 인스턴스 동시 기동은 실행하지 않았다. + +## Strengths + +- **이미 배포된 파일과 아닌 파일을 git 이력으로 갈랐다.** 고친 9개는 모두 main에 없고, 동결 목록 24개는 모두 main에 + 있다(위 명령). 각 파일 머리말이 "branch not merged, recreate the dev DB"를 적고, 업그레이드 안내 표 9행과 4.2절이 같은 + 조치를 말한다(`docs/upgrade/2026-11-maturity-review.md:30,141-147`). +- **잠금 상한이 실제 Flyway 실행에서 걸리는 것을 RED까지 확인할 수 있다.** `PostgreSqlMigrationLockWaitIntegrationTest.java:59-111`은 + 진짜 `Flyway.migrate()`를 읽기 트랜잭션 뒤에서 돌리고, 상한이 없으면 15초 뒤 적용되어 실패하는 모양이다. 이 리뷰에서 + V22의 상한을 지우자 그 케이스만 실패했다. +- **규칙이 다음 파일로 이어진다.** `MigrationLockWaitTest.java:60-91`은 새 파일을 거부하고, 동결 목록의 파일이 더는 걸리지 + 않으면 그것도 실패한다(목록이 조용히 남아 다음 파일을 숨기지 못한다). 목록 갱신 대상 tree는 `MigrationTrees` 하나로 + 합쳐 immutability 검사와 같은 목록을 쓴다. +- **claim DEAD의 원인 코드를 row lock 아래에서 쓴다.** `JpaOutboxStore.java:206-214`. claim이 `FOR UPDATE SKIP LOCKED`로 잡은 + 행만 바꾸고(`PostgreSqlOutboxClaimRepository.java:39`), 토큰을 먼저 올리므로 옛 lease 소유자의 fenced UPDATE는 잠금을 + 기다린 뒤 0행이 된다. entity를 바꾸는 경로는 claim 하나뿐이라 `updatable`로 바꿔도 잠금 없이 낡은 값을 덮는 경로가 없다. + 실 PG 테스트가 결과를 행에서 읽는다(`PostgreSqlOutboxDispositionRunbookIntegrationTest.java:84-100`). +- **DEAD 경보에 해소 경로가 있다.** `metrics.yaml:396`의 `DEAD > 0`은 runbook §4의 재발행·skip이 모두 행을 DEAD 밖으로 + 옮기므로 계속 울리는 경보가 되지 않는다. +- **모르는 상태 값이 게이지 전체를 끄지 않는다.** `JpaOutboxStore.java:281-300`. 이름과 행 수를 WARN 한 번으로 남기고, + 그 행은 `outbox.publisher.lag`(`status <> 'PUBLISHED'`)에는 계속 잡힌다. +- **runbook 숫자와 상수를 문서 입력이 선언된 main 단계 lane으로 묶었다.** `OutboxLongRetryRunbookContractTest`와 + `src/composition/outbox-relay/build.gradle:45-61`. 블록이 사라지거나 비교 연산자가 바뀌어도 빈 목록이라 실패한다. +- **header 테스트가 실제 바이트를 본다.** `KafkaDeadLetterQuarantineTest`는 `MockProducer`가 받은 레코드의 header 값을 읽고, + 이전 hop의 낡은 category를 지우는지도 본다. + +## 발견 재확인 표 + +| ID | 상태 | 근거 | +|---|---|---| +| RR-02-09 | 닫힘 | 8개 파일 첫 문장 `SET LOCAL lock_timeout = '5s'`(V20:27, V22:32, 알림 V11:25·V12:29·V13:22, V8_1:28, grpc V002:25·V003:27). 실 PG lane `postgresqlMigrationLockWaitIntegrationTest` 5/5, V22 상한을 지우면 RED(이 리뷰 실행, E2·E3). 텍스트 검사 `MigrationLockWaitTest`·`SampleMigrationLockWaitTest`. 가이드 `migration-guide.md:35-61`, runbook `outbox-dead-letter.md` §8·`migration-failed.md:43-49`. 잔여: 검사기 범위(RR3-02-01), 원인 세션 조회(RR3-02-02), 소수 버전(RR3-02-03), grpc tree(RR3-02-04) — 모두 Minor | +| RR-02-10 | 결정으로 닫힘 | 9.1절 밖이지만 round2 「고치는 법」의 문서 방향. `JpaOutboxStore.java` nextSequence Javadoc, 포트 `OutboxAggregateSequencePort.java:29-37`, runbook `outbox-dead-letter.md:139-145`, manual 09 73-78행 | +| RR-02-11 | 닫힘 | `JpaOutboxStore.java:281-309`, 단위 테스트 2개(아는 상태는 그대로 셈, WARN 1회), runbook `outbox-publish-failed.md:118-122`(롤백 전 보류 해제) | +| RR-02-12 | 닫힘 | `OutboxEventEntity.java:69`(`updatable` 허용), `JpaOutboxStore.java:206-214`, 단위 테스트, 실 PG 테스트(행의 `last_failure_code`가 `ATTEMPT_COUNTERS_INCONSISTENT`), `metrics.yaml:396` p1, runbook §1·§2 Step 1 | +| RR-02-13 | 닫힘 | `OutboxEventEntity.java:59-73`: `nextAttemptAt` Javadoc 제자리, V22 관련 틀린 문장 삭제 | +| RR-02-14 | 닫힘 | `OutboxLongRetryRunbookContractTest`, lane `outboxRelayDocumentContractTest`(`mainStage`, runbook을 input으로), runbook 89-90행 안내. JPQL도 `>=`로 같다(`OutboxEventJpaRepository` `countLongRetries`) | +| RR-02-15 | 닫힘(메시지·가이드 방향) | `SingleSidedAssociationCondition.java:130-138` `why()`, fixture `MutualForeignKey*Entity`, 테스트가 "two fields map one link"가 **없음**까지 단언, 가이드 `entity-mapping-guide.md:84-97`. 잔여: to-many 쌍의 메시지(RR3-02-05, Minor) | +| RR-02-16 | 닫힘 | `KafkaDeadLetterQuarantineTest`(두 category의 header 바이트), 업그레이드 안내 B-39(`docs/upgrade/2026-11-maturity-review.md:61`) | + +회귀로 판정한 발견은 없다. + +## Issues + +### Critical (Must Fix) + +없음. + +### Important (Should Fix) + +없음. + +### Minor (Nice to Have) + +#### RR3-02-01 — 잠금 대기 검사기가 FK·trigger·`REINDEX`를 못 잡고, `lock_timeout = 0`과 트랜잭션 밖 `SET LOCAL`을 상한으로 인정한다 + +- **위치**: `src/adapter/outbound/persistence-jpa/src/testFixtures/java/dev/caskeleton/adapter/outbound/persistence/testkit/migration/LockWaitMigrationInspector.java:43-58`, + `docs/jpa/migration-guide.md:51-52`. +- **무엇이 틀렸나**: + - 가이드는 검사기가 "names every statement that locks an existing table before the bound"라고 말한다. + - 검사기의 목록에는 `CREATE TABLE ... REFERENCES <기존 표>`가 없다. 이 문장은 부모 표에 `SHARE ROW EXCLUSIVE`를 건다. 그 잠금은 쓰기와 충돌한다. + - `CREATE TRIGGER`·`DROP TRIGGER`·`REINDEX`(비동시)·`REFRESH MATERIALIZED VIEW`(비동시)도 목록에 없다. + - `BOUND`는 값을 보지 않는다. `SET LOCAL lock_timeout = 0`(상한 없음)도 상한으로 센다. + - 검사기는 `.sql.conf`를 읽지 않는다. `executeInTransaction=false` 마이그레이션에서 `SET LOCAL`은 경고만 내고 효과가 없다. + 그 모양을 막는 `ConcurrentIndexMigrationInspector.requireIsolatedStatement`는 저장소 tree에 적용되지 않는다(사용처가 합성 입력 테스트뿐). + - `CREATE TABLE IF NOT EXISTS`로 "만든" 표는 이미 있던 표여도(adopt 경로) 그 뒤 `ALTER TABLE`이 면제된다. +- **증거(E3)**: + - 검사기를 컴파일해 돌렸다. FK가 있는 `CREATE TABLE`, `CREATE TRIGGER`, `DROP TRIGGER`, `REINDEX TABLE`이 모두 `[]`이었다. + - 실 PG 16에서 부모 표에 쓴 트랜잭션을 열어 두었다. `CREATE TABLE child (... REFERENCES parent)`가 11.09초 기다렸다. + 그동안 3초 제한의 `INSERT INTO parent`가 statement timeout으로 끝났다. RR-02-09와 같은 종류의 멈춤이다. + - 트랜잭션 밖 `SET LOCAL lock_timeout`은 `WARNING: SET LOCAL can only be used in transaction blocks`였다. +- **왜 중요한가**: + - 발생 조건: 서비스가 기존 업무 표를 가리키는 새 표를 만든다. 흔한 마이그레이션이다. 검사는 통과하고 상한은 없다. + - 영향: 배포 때 그 부모 표에 열린 쓰기가 있으면 부모 표의 쓰기가 마이그레이션 뒤에 줄을 선다. + - Minor로 둔 이유: 지금 저장소의 규칙 이후 마이그레이션 9개는 모두 첫 문장에 상한이 있어 이 빈틈에 걸리는 파일이 없다. + 검사기 Javadoc은 자기 목록과 "not a proof"를 적는다. 틀린 것은 가이드의 "every" 문장과 앞으로의 파일에 대한 보호 범위다. +- **고치는 법**: + 1. 목록에 `REFERENCES`(새 표·`ALTER TABLE` 모두, 대상은 참조되는 표), `CREATE/DROP TRIGGER ... ON`, 비동시 `REINDEX`·`REFRESH MATERIALIZED VIEW`·`CLUSTER`·`VACUUM FULL`을 더한다. + 2. `BOUND`가 0이 아닌 값만 인정하게 한다. + 3. `executeInTransaction=false`인 파일은 `SET LOCAL`을 상한으로 세지 않는다. 또는 `requireIsolatedStatement`를 저장소 tree 전체에 돌린다. + 4. 가이드 문장을 "목록의 문장을 찾는다"로 줄이고 목록을 적는다. +- Low · P3 · E3. **통제**: 목록 안의 문장은 M3, 목록 밖은 M1(가이드 문장만). + +#### RR3-02-02 — runbook의 원인 세션 조회가 원인을 가려내지 못한다 + +- **위치**: `docs/runbooks/migration-failed.md:46-49`, `docs/runbooks/outbox-dead-letter.md:133`. +- **무엇이 틀렸나**: + - 두 runbook은 "그 표를 건드린 열린 트랜잭션"이 원인이라고 말하고 `pg_stat_activity WHERE xact_start < now() - 5s`를 준 뒤 "End it"이라고 한다. + - 이 조회는 표를 가리지 않는다. 5초 넘게 열린 모든 트랜잭션이 나온다. + - idle in transaction 세션의 `query` 열은 **마지막** 문장이다. 원인 세션이 표를 읽은 뒤 다른 문장을 실행했으면 그 표 이름이 보이지 않는다. +- **증거(E3, 실 PG 16)**: 원인 세션(93)과 다른 표만 읽은 보고 세션(91)을 열어 두었다. 상한 있는 `ALTER TABLE`이 lock timeout으로 실패했다. + runbook 조회는 두 세션을 모두 냈다. 93의 `query`는 `SELECT 1 AS later_statement`였다. + `pg_locks`를 `relation = 'outbox_event'::regclass`로 거른 조회는 93만 냈다. +- **왜 중요한가**: 운영자가 원인을 못 고르면 다시 배포해도 같은 실패를 한다. 목록을 모두 끝내면 무관한 트랜잭션(보고·배치)이 롤백된다. + Minor로 둔 이유: 지시("원인을 끝낸다") 자체는 맞고, 원인은 목록 안에 있다. 상한 덕분에 운영자가 찾는 동안 서비스가 멈추지 않는다. +- **고치는 법**: 두 runbook의 조회를 표 이름으로 거른 `pg_locks` 조인으로 바꾼다. + `SELECT DISTINCT a.pid, a.state, a.xact_start, a.query FROM pg_locks l JOIN pg_stat_activity a USING (pid) WHERE l.relation = ''::regclass AND a.pid <> pg_backend_pid();` + `query`는 마지막 문장일 뿐이라는 한 줄을 붙인다. +- Low · P3 · E3. + +#### RR3-02-03 — 운영 tree 검사가 소수 버전 마이그레이션(`V22_1__`)을 건너뛴다 + +- **위치**: `src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/migration/MigrationTrees.java:58`, + 비교: `src/sample-portfolio/src/test/java/dev/caskeleton/sample/portfolio/bootstrap/persistence/SampleMigrationLockWaitTest.java:58`, `docs/manual/04-persistence.md:126`. +- **무엇이 틀렸나**: + - `MigrationTrees`는 `V\d+__.+\.sql`만 마이그레이션으로 본다. `V22_1__x.sql`은 빠진다(실행 확인). + - 같은 커밋의 sample 검사는 `V[0-9_]+__`로 소수 버전을 센다. "versioned migration"의 정의가 두 벌로 갈렸다. + - manual 04는 "같은 스트림 안에서 두 버전 사이에 끼워야 하면 소수 버전을 쓴다"고 안내한다. 운영 tree에 그런 파일을 두면 잠금 규칙과 checksum 고정 둘 다 받지 않는다. +- **왜 중요한가**: 사용자 원칙의 "갈라진 복사본"이다. 발생은 소수 버전을 운영 tree에 쓰는 경우로 드물다. + checksum 쪽 빈틈은 이 커밋 이전부터 있었다(정규식은 `AppliedMigrationImmutabilityTest`에서 옮겨 왔다). 잠금 규칙 쪽은 이 커밋이 물려받았다. +- **고치는 법**: `MigrationTrees`와 sample 검사가 정규식 하나(`V[0-9_]+__.+\.sql`, 필요하면 `.` 포함)를 함께 쓴다. 소수 버전 fixture로 두 검사를 한 번씩 고정한다. +- Low · P3 · E2. 이 커밋 이전부터(checksum 쪽) + 이 커밋이 물려받음(잠금 쪽). + +#### RR3-02-04 — gRPC ledger tree에는 잠금 규칙 검사가 없다 + +- **위치**: `src/grpc/grpc-operation-ledger-jpa/src/integrationTest/java/dev/caskeleton/grpc/ledger/GrpcOperationLedgerMigrationLockWaitIT.java:50-55`, + `docs/jpa/migration-guide.md:52-55`. +- **무엇이 틀렸나**: + - `MigrationTrees.ROOTS`에 `db/migration/grpc`가 없다. 텍스트 검사기를 이 tree에 돌리는 테스트도 없다. + - IT는 V002·V003 이름을 박아 두고 그 두 파일만 실 PG로 본다. 다음 `V004__`가 상한 없이 들어와도 모든 테스트가 통과한다. + - 가이드는 검사 대상을 "이 leaf DB에 도는 모든 tree"와 "서비스 스트림"으로 말한다. 템플릿이 가진 grpc tree는 어느 쪽에도 없다. +- **왜 중요한가**: RR-02-09의 원인("한 파일에 적은 규칙은 다음 파일의 규칙이 아니다")이 이 tree에는 그대로 남는다. ledger는 아직 어디에도 채택되지 않아 지금 피해는 없다. +- **고치는 법**: `GrpcOperationLedgerMigrations.IN_ORDER` 전체에 텍스트 검사를 돌리는 테스트를 하나 둔다. 등록상 testkit 의존이 막히면 `SampleMigrationLockWaitTest`처럼 검사를 그 leaf 테스트에 둔다. 또는 IT가 이름 목록 대신 V001 이후 전체를 매개변수로 받는다. +- Low · P3 · E1. + +#### RR3-02-05 — to-many 쌍에서 연관 규칙 메시지가 여전히 "한 링크"라고 틀리게 말한다 + +- **위치**: `src/adapter/outbound/persistence-jpa/src/testFixtures/java/dev/caskeleton/adapter/outbound/persistence/testkit/arch/SingleSidedAssociationCondition.java:125-138`. +- **무엇이 틀렸나**: + - 새 `why()`는 annotation 모양만 본다. `@ManyToMany` 둘, 또는 `@JoinColumn` 없는 `@OneToMany`와 `@ManyToOne`이면 "two fields map one link, and the read-only one does not follow"라고 한다. + - `mappedBy`가 없으면 두 `@ManyToMany`는 둘 다 소유 쪽이다. 기본 join table도 둘(`A_B`, `B_A`)이라 링크가 둘이고 읽기 전용 쪽이 없다. + - `@JoinColumn` 없는 `@OneToMany`는 join table을 쓰고 `@ManyToOne`은 FK 열을 쓴다. 이것도 링크 둘이다. + - 이 커밋의 Javadoc이 "two many-to-many collections, map one link from both ends"라고 새로 적었다. +- **왜 중요한가**: 거부 자체는 맞아 데이터 위험은 없다. RR-02-15가 지적한 "이유를 말하는 메시지가 틀리면 규칙을 믿지 않는다"가 이 두 모양에 남는다. `mappedBy`를 잊는 흔한 실수가 바로 두 번째 모양이다. +- **고치는 법**: `why()`가 join column 이름(또는 join table 유무)을 보고 "같은 열을 두 쪽이 매핑"일 때만 "one link"라고 한다. 아니면 두 to-many 모양에 맞는 문장("두 저장소가 따로 써져 서로 어긋난다")을 둔다. 각 모양의 fixture를 하나씩 둔다. +- Low · P3 · E1. + +## Declined to judge + +- 배포 도구가 실패한 pod를 자동 재시작하면 원인이 남아 있는 동안 시도마다 최대 5초씩 줄이 선다 — 배포 토폴로지(ArgoCD 등)가 저장소에 없고, 시도당 상한은 지켜진다. +- `lock_timeout`은 잠금 대기 하나마다 걸린다. V12처럼 문장이 여럿이면 전체 대기는 5초를 넘을 수 있다 — 각 대기와 각 줄서기는 5초로 묶이고, 문서의 "5초" 요약은 운영 판단을 바꾸지 않는다. +- runbook §1의 "alert payload 필수 field(`event_id` 등)"를 게이지 기반 두 번째 조건은 채울 수 없다 — runbook `status: stub`이고, §2 Step 1이 WARN과 SQL로 행을 찾게 한다. +- runbook·README 산문의 "10번"은 document-contract lane이 보지 않는다 — 운영자가 실행하는 것은 SQL 블록이고 그것은 묶였다. +- 검사기가 열 이름 `lock`을 `LOCK TABLE`로 오탐한다 — 엄격한 쪽으로 틀리고, 지금 저장소에 해당 파일이 없다. +- `reportedUnknownStatuses`는 비우지 않아 사라졌다 다시 나타난 모르는 상태를 다시 알리지 않는다 — 결정("WARN 한 번")대로다. +- sample V8_1은 실 PG 잠금 대기 테스트가 없다 — 같은 `SET LOCAL` 모양이 다른 5개 파일에서 실 PG로 확인됐고, 텍스트 검사가 있다. +- `GrpcOperationLedgerMigrationLockWaitIT`는 Flyway 대신 JDBC 한 트랜잭션으로 실행한다 — Flyway의 기본 실행(트랜잭션 하나)과 `SET LOCAL`의 효과가 같다. 운영자 경로 `apply-capability-streams.sh`도 Flyway CLI 기본(트랜잭션)이다. +- `spotbugsTestFixtures`의 ReDoS 경고 8건 — 입력이 저장소 마이그레이션 파일뿐이다(재리뷰 README 10.3에 기록됨). +- pathspec 안의 다른 영역 변경(멱등성 store, manual 09 `@SystemCaller` 절, `SampleDemoSecurityConfigTest`, ledger `release` 시그니처, Redis lane 지표 항목) — 01·03·04 리뷰어 몫이다. + +## 수렴 판단 — 이 라운드가 만든 새 Important 이상이 있는가 + +**없다.** + +- 맡은 2차 발견 8건(RR-02-09~16)은 모두 닫혔다(RR-02-10은 결정으로). 회귀는 없다. +- RR-02-09의 핵심 주장 두 가지를 실행으로 확인했다. + - `SET LOCAL lock_timeout`은 실제 Flyway 실행에서 5초에 걸린다. V22의 상한을 지우면 lane이 실패한다. + - 고친 9개 파일은 어느 배포에도 적용되지 않았다. 9개 모두 main과 파생 서비스에 없다. +- 브리프가 물은 세 가지에 대한 답: + - **이미 적용된 파일을 바꿨는가**: 아니다. 동결 목록 24개는 모두 main에 있다. + - **비트랜잭션 마이그레이션과 섞이면**: `SET LOCAL`은 효과가 없다. 지금 그런 파일은 없다. 검사기가 이 경우를 모른다(RR3-02-01). + - **DEAD 전이의 entity flush**: claim의 `FOR UPDATE` 아래에서만 일어나고 entity를 바꾸는 다른 경로가 없어 맞다. +- 새 Minor 5건은 모두 앞으로의 파일·문서 정밀도에 관한 것이다. 지금 코드에서 틀린 동작이나 데이터 손상을 만들지 않는다. + +이 영역은 멈추는 기준(새 Important 0)을 채운다. + +## Assessment + +**Ready to merge? Yes.** + +9.1절 결정(V21과 같은 `SET LOCAL lock_timeout`, 같은 모양의 실 PG lane)이 8개 파일에 구현됐다. lane이 상한 누락을 실제로 잡는 것도 확인했다. +남은 5건은 Minor다. 검사기 범위와 runbook 조회 정밀도는 다음 정리 때 고치면 된다. diff --git a/docs/reviews/2026-11-03-rereview/round3/03-outbound.md b/docs/reviews/2026-11-03-rereview/round3/03-outbound.md new file mode 100644 index 00000000..fa9ab0a4 --- /dev/null +++ b/docs/reviews/2026-11-03-rereview/round3/03-outbound.md @@ -0,0 +1,227 @@ +# 03 outbound·멱등성 3차 확인 리뷰 (2026-11-04) + +> 3차 확인 리뷰. 대상은 3차 수정 커밋 `1885bf8d`(Base `ecc74b7d`)의 수정 묶음 r5-a(멱등성·outbound)다. +> 경로는 따로 적지 않으면 `src/adapter/outbound/`를 생략한다. 새 발견 ID 접두어는 `RR3-03-`이다. + +## 범위 — 본 pathspec, 불러온 스킬과 적용한 기준, 실행한 명령과 결과, 못 본 것 + +### 본 pathspec + +``` +src/adapter/outbound/httpclient src/adapter/outbound/cache-redis src/adapter/outbound/redis-runtime +src/adapter/outbound/notification src/composition/idempotency src/shared-contract src/application-core +src/adapter/outbound/persistence-jpa/src/main/java/.../persistence/idempotency +src/adapter/outbound/persistence-jpa/src/test src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest +src/adapter/inbound/web docs/httpclient docs/manual/05-idempotency.md docs/web/http-contract.md +docs/runbooks/redis-capability-incident.md docs/registries/env-keys.yaml docs/registries/metrics.yaml +``` + +- `git diff --stat ecc74b7d..1885bf8d -- ` 기준 59파일, +1,854 −207. +- 끝까지 읽은 diff: 멱등성(Redis Lua·adapter·fake 사본, PG claim·transition gateway, 공유 계약, executor·결과 타입 Javadoc, + 설정 검사·yml·README), httpclient(watchdog, `HttpBodyReadException`, 헤더 목록, breaker Javadoc, 문서), redis-runtime(listener WARN), + notification(주석), Redis runbook·README·metrics 레지스트리, env 레지스트리, http-contract, 매뉴얼 05. +- 같은 pathspec이지만 다른 묶음(r5-b·r5-c)의 변경은 판정하지 않았다: `EnvelopeErrorController`, `SystemCaller`·`SystemInvoked`, + `DirectTransactionPort`·`TransactionPortContract`, outbox port Javadoc, persistence-jpa 마이그레이션 잠금 테스트·outbox 테스트·ArchUnit fixture. +- 판정에 필요해 pathspec 밖에서 읽은 것: `PostgreSqlIdempotencyStore`(claim 분기), `IdempotencyReaper`·`IdempotencyRecordJpaRepository`, + `IdempotencyAutoConfiguration`, `BlockingStreamingGateway`, `CountingBoundedInputStream`, `cache-redis/build.gradle`·`persistence-jpa/build.gradle`의 lane 정의, + `docs/runbooks/idempotency-unavailable.md`, `docs/upgrade/2026-11-maturity-review.md` B-24·B-30, `objectstorage/README.md`·`object-storage-qualification.yml`(RR-03-18 확인용). +- 재확인한 2차 발견: `round2/03-outbound.md`의 RR-03-11~18, `round2/01-core-app-inbound.md`의 RR-01-11. + +### 불러온 스킬과 적용한 기준 + +| 스킬 | 적용한 기준 | 무엇을 봤나 | +| --- | --- | --- | +| `superpowers:requesting-code-review` | 리뷰어 템플릿: 요구사항(round2 "고치는 법"·9.1절 결정) 대비 정렬, Critical/Important/Minor, 읽기 전용, 하위 에이전트 없음, 판단을 미룬 것을 한 줄씩 남김 | 출력 양식 전체, 발견 재확인 표, Declined to judge | +| `api-and-interface-design` | 멱등성 키 점검표: claim이 한 번의 원자 연산인가, 진행 중 중복에 고른 답(409)이 있는가, 성공·실패·불명 세 결과, "키 보존 기간이 가장 긴 재전송 경로보다 길어야 한다". 인터페이스 쪽은 Hyrum의 법칙(`InputStream.read`의 `IOException` 계약) | Redis Lua·PG SQL의 abandon·takeover 분기와 수명, 늦은 complete, 문서가 약속한 기억 기간(RR3-03-02), `HttpBodyReadException`의 형태 | +| `performance-optimization` | 추정 말고 잰다, 고친 뒤 같은 방법으로 다시 잰다, 숫자 없이 문제로 올리지 않는다 | watchdog의 read당 비용(전후 측정), 공용 풀 포화 때 timeout 시각(측정, RR3-03-01), lifetime 연장이 Redis·PG 저장량에 주는 영향(+lease, 무시할 수준이라 발견 아님) | +| `observability-and-instrumentation` | on-call 질문에 신호가 답하는가("어느 키가 회복 필요인가"), runbook이 실제 신호를 가리키는가, 계측 실패가 보이되 결과를 바꾸지 않는가, 레지스트리와 코드의 일치 | listener 첫 실패 WARN, Redis runbook·metrics 행, 멱등성 runbook의 회복 절차(RR3-03-03) | +| `doubt-driven-development` | 비자명한 주장마다 CLAIM을 적고 반대 논증으로 깨 보려 한다. 하위 에이전트 대신 직접 반대 논증을 썼다(브리프 지시). 비대화형이라 cross-model 검토는 건너뛰었다 | 아래 「반대 논증」 4건 | + +### 반대 논증 (doubt-driven, 직접 작성) + +| CLAIM | 반대 논증 | 결과 | +| --- | --- | --- | +| Redis와 PG가 "lease 지난 EXECUTING → 회복 필요, 다시 안 돌림"을 같이 지킨다 | Redis TRANSITION은 "이미 목표 상태"를 revision보다 먼저 본다. 늦은 holder의 complete가 ABANDONED 기록에서 `ALREADY`를 받아 성공으로 끝날 수 있지 않나? 같은 owner token이 남아 있다 | 깨지지 않음. 목표가 COMPLETED이고 상태가 ABANDONED라 `ALREADY`가 아니고, revision이 1 올라 `NOT_OWNER`다(실 Redis 탐침 B). `markFailed(ABANDONED)`만 `ALREADY`를 받는데 상태가 같아 무해하다(Declined) | +| 기록 수명 lease + replay TTL이 claim·takeover·renew 모두에서 지켜진다 | start 전이가 lease나 TTL을 다시 정하면 어긋난다. 옛 기록(`afterLease` 없음)의 renew는 `nil` 산술로 Lua 오류가 나지 않나? | 깨지지 않음. start는 lease·TTL을 건드리지 않는다(Redis `Transition(..., "", "")`, PG `START_SQL`). `HGET` 없음은 Lua `false`라 `or '0'`이 받는다(탐침 D: PTTL 9938) | +| 시간 케이스가 세 구현에서 실제로 돈다 | abort가 통과로 보이거나, PG lane이 Docker 없이 skip으로 통과할 수 있다 | 깨지지 않음. Live Redis lane은 `rejectSkipped = true`, PG는 `JpaPlatformContractSupport`가 Docker 없으면 던진다. 게이트 보고서에서 두 클래스 19/19, skip 0, 시간 케이스 약 2초(실제 sleep) | +| watchdog이 idle을 틀리게 판정하지 않는다 | 타이머가 공용 풀로 옮겨 가 늦게 깨면? 일찍 닫을 수는? | 일찍 닫지는 않는다(깰 때 시작 시각과 다시 비교). **늦게 깰 수는 있다** → RR3-03-01(E3) | + +### 실행한 명령과 결과 + +checkout·index·HEAD는 바꾸지 않았다. worktree와 Gradle은 쓰지 않았다(게이트 결과는 읽기만). 탐침은 +`git show 1885bf8d:`로 꺼낸 사본을 scratchpad에서 돌렸다. + +| 명령 | 결과 | +| --- | --- | +| `git diff --stat` / `git diff ecc74b7d..1885bf8d -- ` | 59파일 | +| `docker run --rm redis:7.4`(로컬 이미지 `b6b6e3dc0c09`, 고정 digest와 같은 id) + HEAD의 CLAIM·TRANSITION·RENEW Lua를 `redis-cli EVAL` | A: lease 3000·replay 1000 claim → `PTTL 3943`. B: A가 start → 1.2s 뒤 B claim → `RECOVERY_REQUIRED`, `state ABANDONED`, `PTTL 576`. A의 늦은 complete → `NOT_OWNER`, 늦은 `FAILED_RETRYABLE` → `NOT_OWNER`, 늦은 `ABANDONED` → `ALREADY`. C claim → `RECOVERY_REQUIRED`. 기록 수명 뒤 `EXISTS 0`, D claim → `ACQUIRED`. C: lease 1000·replay 5000 → renew 10000 → `PTTL 14952`. D: `afterLease` 없는 옛 기록 renew 10000 → `PTTL 9938` | +| `javac` + `PerReadBench` — `ecc74b7d`의 read별 타이머 vs HEAD의 watchdog, 끝없는 1바이트 stream, read-idle 3s | 3회: 옛 1,490~2,533ns/read, 새 24.6~25.3ns/read (load average 3.6) | +| `javac` + `StarveProbe` — 멈춘 stream 한 번 read, read-idle 300ms, 공용 `ForkJoinPool`을 블로킹 작업 2배수로 3초 채움 | 평소: 옛 303ms(`CompletableFutureDelayScheduler`가 닫음), 새 302ms(`ForkJoinPool.commonPool-worker-1`이 닫음). **공용 풀 포화: 옛 300ms, 새 2,699ms**. `-XX:ActiveProcessorCount=2`(공용 풀 병렬도 1): 새 300ms, 닫는 스레드가 매번 새 스레드(`Thread-1`, `Thread-3`) | +| `javac` + `SelfProbe` — JDK 본문처럼 `ArrayBlockingQueue.take`로 멈춘 read 42개를 공용 풀 작업으로 실행(병렬도 21) | 가장 늦은 timeout 306ms. 공용 풀 안의 멈춘 read 자체로는 막히지 않는다(아래 javap) | +| `javap -c` `ResponseSubscribers$HttpResponseInputStream`, `AbstractQueuedSynchronizer$ConditionObject`, `CompletableFuture` | JDK 본문은 `ArrayBlockingQueue.take`로 기다린다. `ConditionObject.await`는 `ForkJoinPool.managedBlock`을 불러 공용 풀이 보충 스레드를 만든다. `delayedExecutor(delay, unit)`의 실행기는 `ASYNC_POOL`(병렬도 > 1이면 공용 풀, 아니면 작업마다 새 스레드) | +| 게이트 JUnit 보고서 읽기(main 작업 트리 `build/test-results`, 시각 2026-11-03T16:34Z·16:35Z, 커밋 01:47 KST 직전) | `LiveRedisIdempotencyStoreContractTest` 19 tests, skipped 0. `PostgreSqlIdempotencyStoreContractTest` 19 tests, skipped 0. 새 시간 케이스 5개가 두 클래스 모두에서 1.5~2.3초 걸림 | + +### 못 본 것 + +- Gradle 테스트·게이트를 다시 돌리지 않았다(README 10.2절과 보고서만 읽었다). +- Redis Cluster·Sentinel topology lane, 장애 조치 중 `TIME`이 바뀌는 경우. +- JDK HTTP/2·TLS에서 공용 풀 스레드가 본문 stream을 닫을 때의 지연. +- PG 저장소를 여러 인스턴스·여러 트랜잭션 모양(유스케이스 트랜잭션 안 vs 호출마다 트랜잭션)으로 돌리는 경우. 아래 Declined. +- `failure-retention`이 짧을 때의 실제 동작은 코드로만 확인했다(E1). + +## Strengths + +- Redis CLAIM이 "lease 지난 EXECUTING"과 "실행 전 CLAIMED·재시도 가능 실패"를 따로 다룬다(`cache-redis/.../idempotency/IdempotencyScripts.java:87-105`). + 분기 순서(fingerprint → COMPLETED → ABANDONED → 같은 owner → lease)가 PG와 같다(`persistence-jpa/.../PostgreSqlIdempotencyStore.java:131-159`). + 실 Redis에서 늦은 complete·늦은 retryable 표시가 모두 `NOT_OWNER`로 막히는 것을 확인했다(탐침 B). +- 기록 수명 규칙이 두 저장소에서 같은 식이다. Redis는 `leaseMillis + afterLease`(`IdempotencyScripts.java:61,102`), PG는 + `recordLifetimeMillis`(`IdempotencyClaimGateway.java:173-175`)를 insert와 reset 둘 다에 쓴다. renew도 같은 여유를 유지한다 + (`IdempotencyScripts.java:213-218`, `IdempotencyTransitionGateway.java:54-57`). PG `RENEW_SQL`의 오른쪽이 갱신 전 행을 읽는다는 + 사실을 주석에 적었다. 옛 기록(`afterLease` 없음)도 처리한다(탐침 D). +- 공유 계약에 시간 케이스 5개가 생겼고(`application-core/.../testkit/IdempotencyStoreContract.java:431,449,466,484,501`), 두 실 저장소에서 + 실제로 돈다. PG 쪽 `elapse`가 배포와 같은 Spring Data reaper를 돌린다(`PostgreSqlIdempotencyStoreContractTest.java:122-131`). + 그래서 "reaper가 진행 중 행을 지운다"는 PG 쪽 RR-03-11 경로도 테스트가 본다. Redis lane은 `rejectSkipped = true`다 + (`cache-redis/build.gradle:81-92`). +- 설정 검사를 한 곳에 두고, 포트(`IdempotencyClaimRequest`)에 두지 않은 이유를 남겼다(`IdempotencySettings.java:67-80`, + `composition/idempotency/README.md`). env 레지스트리·`.env.example`·업그레이드 안내 B-24가 같은 규칙을 적는다. +- watchdog은 일찍 닫지 않는다. 깰 때마다 지금 read의 시작 시각과 비교하고, 닫기 직전에 시작 시각을 한 번 더 읽는다 + (`httpclient/.../jdk/ReadIdleInputStream.java:123-131`). 무장 해제와 재무장 사이의 경쟁을 volatile 두 개로 막았다(`:134-140`). + 비용 주장(read당 µs → 수십 ns)을 다시 재서 맞았다(`PerReadBench`). +- `HttpBodyReadException`이 `InputStream` 계약(`IOException`)을 지키면서 분류된 실패를 `failure()`로 싣는다. 버린 대안(문서만 고치기)과 + 이유가 Javadoc에 있다(`httpclient/.../api/error/HttpBodyReadException.java:17-20`). +- 금지 헤더 사본을 Spring 원본과 반사로 비교하는 테스트가 있다(`JdkStreamingRestrictedHeadersTest`). Spring이 바뀌면 테스트가 깨진다. +- listener 첫 실패만 WARN으로 남기고 나머지는 DEBUG다(`redis-runtime/.../RedisRuntimeOwner.java:357-369`). 로그 수를 세는 테스트가 있다 + (`RedisLaneMetricsTest.aFailingListenerIsReportedAtWarnOnlyTheFirstTime`). + +## 발견 재확인 표 + +| ID | 상태 | 근거 | +| --- | --- | --- | +| RR-01-11 | 닫힘 | 고치는 법 1: `IdempotencyScripts.java:89-95` EXECUTING+lease 만료 → `ABANDONED`·`RECOVERY_REQUIRED`, takeover는 `CLAIMED`·`FAILED_RETRYABLE`만(`:96`). fake 사본도 같다(`InMemorySemanticRedisCommands.java:226-243`). 2: 계약 `:449`(회복 필요), `:466`(늦은 complete 거부)이 Live Redis·PG에서 돌았다(보고서). 3: `IdempotencyCompletionUnknownException` Javadoc을 "쓰기 트랜잭션 안에서 부른 경우"로 좁혔다. 같은 문장의 runbook 사본은 남았다 → RR3-03-03 | +| RR-03-11 | 닫힘(9.1절 결정대로) | 설정: `IdempotencySettings.java:73` `replay-ttl < processing-lease`면 기동 실패, 테스트 2건. 저장소: Redis claim·takeover·renew(`IdempotencyScripts.java:61,102,213-218`), PG insert·reset·renew(`IdempotencyClaimGateway.java:133,162`, `IdempotencyTransitionGateway.java:54-57`). 계약 `:484`(replay TTL < lease), `:501`(같을 때)이 두 실 저장소에서 돌았다. 실 Redis 탐침 A·C | +| RR-03-12 | 닫힘 | `ReadIdleInputStream.java:72-87` skip을 감시되는 read 반복으로. 테스트 `aSkipLongerThanReadIdleOverASteadyBodySucceeds` | +| RR-03-13 | 닫힘 | stream당 watchdog 하나(`ReadIdleInputStream.java:95-141`). 재측정: 1.5~2.5µs → 25ns. 대신 timeout 동작이 공용 풀로 옮겨 갔다 → 새 Minor RR3-03-01. 문서의 "per-read timer" 표현은 남았다 → RR3-03-04 | +| RR-03-14 | 닫힘 | 고치는 법 (a)를 골랐다: `HttpBodyReadException extends IOException`, `ClassifiedBodyInputStream.java:37,46,55,64`, `BlockingStreamingResponse.body()` Javadoc, README·configuration-reference·operations. 테스트 `StreamingBodyLifetimeTest:76` 두 transport | +| RR-03-15 | 닫힘 | `JdkStreamingClientHttpRequest.java:136-144`가 같은 시스템 속성을 읽는다. 값 4가지로 Spring 원본과 비교하는 테스트 | +| RR-03-16 | 닫힘 | 맹점을 Javadoc(`AttemptResiliencePipeline.java:26-33`)과 configuration-reference "Two deadlines" 아래 문단에 적었다. Javadoc의 조건 문장을 코드에 맞췄다 | +| RR-03-17 | 닫힘 | runbook에서 미구현 지표 문장 정리(`redis-capability-incident.md:50-52,62-66`), README `opened` 설명(`cache-redis/README.md:218`), 레지스트리 histogram 표기(`metrics.yaml:553-560`), listener 첫 실패 WARN(`RedisRuntimeOwner.java:361`) | +| RR-03-18 | 닫힘 | `objectstorage/README.md:109-111`, `object-storage-qualification.yml:3-5`가 `integrationCheck`를 적는다. `cache-redis/README.md:349-351`에 멱등성 계약. `SesEventNormalizer.java:57-59` 주석 줄바꿈 | + +회귀로 판정한 발견은 없다. + +## Issues + +### Critical (Must Fix) + +없음. + +### Important (Should Fix) + +없음. + +### Minor (Nice to Have) + +#### RR3-03-01 · JDK read-idle timeout이 이제 공용 `ForkJoinPool`에서 돈다 — 공용 풀이 막히면 timeout이 늦게 난다 (이번 라운드) + +- **위치**: `httpclient/.../jdk/ReadIdleInputStream.java:113-117`(`CompletableFuture.delayedExecutor(left, NANOSECONDS).execute(this::watch)`), + `:143-150`(`idle()`이 `in.close()`). +- **무엇이 틀렸나**: + - `delayedExecutor(delay, unit)`는 시간이 되면 작업을 `ASYNC_POOL`에 넘긴다. 병렬도가 1보다 크면 공용 `ForkJoinPool`이다. + - 옛 코드는 `completeOnTimeout(...).thenRun(this::idle)`이라 JDK delay 스레드에서 바로 닫았다. 새 코드는 공용 풀 작업이 비어야 닫는다. + - Javadoc은 "one scheduled task per read-idle"까지만 적고 어느 스레드에서 도는지는 적지 않는다. +- **왜 중요한가**: + - 발생 조건: JDK transport(기본은 Apache) + 스트리밍 다운로드 + 같은 JVM의 공용 풀이 보충 스레드를 만들지 않는 블로킹 작업 + (소켓·JDBC 호출, `CountDownLatch`, `Thread.sleep`)으로 차 있음. 파생 서비스의 `CompletableFuture.supplyAsync(blockingCall)`(executor 생략)이 흔한 원인이다. + 템플릿 main 코드에는 그런 사용이 없다(grep). + - 영향: 멈춘 서버의 본문 read가 read-idle이 아니라 공용 풀이 빌 때까지 기다린다. 측정에서 300ms 설정이 2,699ms에 끝났다. + 공용 풀 작업이 끝없이 막혀 있으면 RR-04-03 이전처럼 스레드가 무기한 묶인다. 일찍 닫는 일은 없다(깰 때 시작 시각과 다시 비교). + - 공용 풀 안에서 JDK 본문을 읽다 멈춘 경우는 문제없다. JDK 본문의 `ArrayBlockingQueue.take`가 `managedBlock`으로 보충 스레드를 만든다(SelfProbe 306ms). + - 병렬도가 1 이하(CPU 1~2개 pod)면 깰 때마다 새 platform 스레드를 만든다. stream당 read-idle마다 1개라 비용은 작다. +- **고치는 법**: `watch()`는 O(1)이라 delay 스레드에서 돌려도 된다. `CompletableFuture.delayedExecutor(left, NANOSECONDS, Runnable::run)`로 + 옛 코드와 같은 스레드에서 판정하게 한다. 닫기(`in.close()`)를 delay 스레드에 두기 싫으면(round2 Declined의 HTTP/2·TLS 질문) transport가 가진 + 작은 daemon 실행기로 닫기만 넘긴다. 고른 쪽과 이유를 Javadoc에 적고, 공용 풀을 채운 상태에서 timeout 시각을 보는 테스트를 둔다(위 StarveProbe 모양). +- **가이드 심각도·우선순위**: Low · P3. 비기본 transport와 외부 원인(공용 풀 포화)이 겹쳐야 하고, 늦어질 뿐 데이터 피해는 없다. + 경계: 공용 풀이 영구히 막히는 다른 결함과 겹치면 무기한 대기라 Medium에 닿을 수 있다. 그 조건은 이 커밋 밖의 결함이 있어야 해서 낮은 쪽으로 뒀다. +- **증거**: E3 — `StarveProbe`(HEAD 코드 그대로 컴파일): 공용 풀 포화 때 옛 300ms, 새 2,699ms. 닫는 스레드 이름으로 실행 위치 확인. `javap`로 `ASYNC_POOL` 확인. + +#### RR3-03-02 · "서버가 기억하는 기간" 문서가 실패한 시도의 수명(`failure-retention`)을 빠뜨렸다 (이번 라운드) + +- **위치**: `docs/web/http-contract.md:125-127`, `docs/manual/05-idempotency.md:59`, `src/shared-contract/.../OperationalError.java:50`. + 실제 동작: `RedisIdempotencyStoreAdapter.java:271-277`(markFailed가 key TTL을 retention으로), PG `IdempotencyTransitionGateway` `FAIL_SQL` + (`expires_at = now + retention`), `IdempotencySettings.java:81-85`(failure-retention은 양수·30d 이하만 검사). +- **무엇이 틀렸나**: + - 새 문장은 "끝나지 않은 시도의 기록은 claim부터 processing lease + `replay-ttl` 동안 남는다"고 적는다. + - executor가 실패로 표시한 시도(action이 던짐·`EffectUnknown` → `ABANDONED`, `RetryableNoEffect` → `FAILED_RETRYABLE`)는 표시한 때부터 + `failure-retention` 동안 남는다. 두 저장소 모두 그렇다. + - `OperationalError` 주석 "a resend with the same key never runs it again"은 기한 없이 단정한다. http-contract 본문은 기한 뒤 새 요청이 된다고 바르게 적는다. +- **왜 중요한가**: 기본값(둘 다 24h)에서는 차이가 30초뿐이다. 운영자가 `APP_IDEMPOTENCY_FAILURE_RETENTION`을 `replay-ttl`보다 짧게 두면, 효과 불명으로 + 포기한 기록이 문서가 말한 기간보다 먼저 사라지고 같은 키 재전송이 작업을 다시 돌린다. 스킬 기준 "키 보존 기간은 가장 긴 재전송 경로보다 길어야 한다"에 걸리는 + 설정인데 문서가 그 변수를 언급하지 않는다. +- **고치는 법**: 기억 기간 문단에 세 번째 줄을 더한다("실패로 표시된 시도는 표시부터 `failure-retention`"). env 레지스트리의 `APP_IDEMPOTENCY_FAILURE_RETENTION`에 + 같은 관계를 적는다. `OperationalError` 주석에 "기록이 남아 있는 동안"을 붙인다. failure-retention ≥ replay-ttl을 기동 검사로 할지는 소유자 결정이다. +- **가이드 심각도·우선순위**: Low · P3(비기본 설정, 문서 정확도). **증거**: E1. + +#### RR3-03-03 · 멱등성 runbook의 회복 필요 절차가 이번 계약과 어긋나고, 따라 할 수 없다 (일부 이번 라운드, 일부 이전부터) + +- **위치**: `docs/runbooks/idempotency-unavailable.md:20-22,33-34,43-45`, `application-core/.../IdempotencyExecutor.java:123-126,348-350` + (`recovery(...)` 메시지에 scope digest가 없다. `diagnostic(scope)`(`:344`)은 in-flight·mismatch에만 쓰인다). +- **무엇이 틀렸나**: + - (a, 이번 라운드) RR-01-11 고치는 법 3은 "Effects inside the action's own transaction roll back"을 "쓰기 트랜잭션 안에서 부른 경우"로 좁히라고 했다. + 예외 Javadoc과 http-contract는 좁혔다. runbook의 같은 문장 "Effects in the action's own transaction rolled back"은 그대로다. 갈라진 사본이다. + - (b, 이전부터) runbook은 `IDEMPOTENCY_RECOVERY_REQUIRED`에서 "실패한 요청의 서버 로그 줄에서 scope digest를 찾으라"고 한다. + `IdempotencyRecoveryRequiredException`의 메시지는 "claim requires reconciliation" 같은 고정 문구라 digest가 없다. + - (c, 이전부터) "record를 complete하거나 release하라"고 하지만 그 일을 하는 도구·명령·SQL이 없다. +- **왜 중요한가**: 이번 라운드로 Redis 배포에서 lease가 지난 실행은 모두 회복 필요로 끝난다(9.1절 결정). 그 답을 받은 요청을 다루는 운영 절차가 첫 단계에서 막힌다. + 클라이언트 쪽 조치("업무 데이터로 확인")는 digest 없이도 할 수 있어서 피해는 진단 시간이다. +- **고치는 법**: (a) runbook 문장을 Javadoc과 같게 좁힌다. (b) `recovery(...)`에도 `diagnostic(scope)`를 실어 로그에 남긴다(in-flight와 같은 방식). + (c) Redis·PG 각각 기록을 보는 명령과, 확인 뒤 키를 비우는 절차를 적거나 "도구 없음, 기록 수명(lease + replay-ttl)이 지나면 풀린다"고 정직하게 적는다. +- **가이드 심각도·우선순위**: Low · P3. 경계: "주요 진단 정보 부족"은 가이드의 Medium 예시다. 업무 데이터 확인이라는 주 조치가 digest 없이 가능하고 (b)(c)가 + 이 커밋 전부터 있던 것이라 낮은 쪽으로 뒀다. **증거**: E1. + +#### RR3-03-04 · watchdog·계약으로 바뀐 뒤 옛 표현이 남은 문서 (이번 라운드) + +- **위치**: `src/adapter/outbound/httpclient/README.md:45`("the JDK transport arms its own per-read timer"), + `docs/httpclient/configuration-reference.md:107`("bounds each read with its own `read-idle` timer"), + `src/application-core/CLAUDE.md:271`("`IdempotencyStoreContract` holds the fake, Redis and PostgreSQL to both on real servers"). +- **무엇**: RR-03-13으로 read별 타이머가 stream당 watchdog이 됐다. 보장(한 read의 대기만 센다)은 같지만 두 문서가 옛 구현을 설명한다. + CLAUDE.md 문장은 in-memory fake도 시간 케이스를 실 서버에서 지킨다고 읽힌다. fake는 만료를 모델링하지 않아 시간 케이스를 abort한다(`IdempotencyStoreContract.java:110`). +- **고치는 법**: "a per-stream watchdog bounds each read's wait"로 고친다. CLAUDE.md는 "Redis와 PostgreSQL을 실 서버에서, fake는 시간 없는 케이스만"으로 고친다. +- **가이드 심각도·우선순위**: Low · P3. **증거**: E1. + +#### RR3-03-05 · Redis inspect가 `processingLeaseUntil`을 key TTL로 계산한다 — 이제 lease + replay TTL이다 (이전부터) + +- **위치**: `cache-redis/.../idempotency/RedisIdempotencyStoreAdapter.java:388-404`(`now.plusMillis(ttlMillis)`), INSPECT Lua `IdempotencyScripts.java:269-271`(`PTTL`을 돌려준다). +- **무엇**: 포트 `IdempotencyInspection.processingLeaseUntil`에 Redis는 key가 사라지는 시각을, PG는 실제 lease(`PostgreSqlIdempotencyStore.java:623`)를 넣는다. + 전에는 replay TTL(24h)로 틀렸고, 이번 수정으로 lease + replay TTL로 더 멀어졌다. 공유 계약이 이 필드를 보지 않아 두 저장소가 갈라진 채 통과한다. +- **왜 중요한가**: 지금은 이 값을 읽는 곳이 없다(executor는 owner·response만 쓴다). 다음에 "남은 lease가 있으면 이어서 실행" 같은 판단에 쓰면 Redis에서만 lease가 지난 + 실행을 이어 가게 된다. +- **고치는 법**: INSPECT가 CLAIMED·EXECUTING이면 `leaseUntil`(서버 ms)을 돌려주고 adapter가 그것을 쓴다. 공유 계약에 inspect lease 케이스 하나. +- **가이드 심각도·우선순위**: Low · P3(소비자 없음). **증거**: E1. + +## Declined to judge + +- PG 저장소의 트랜잭션 모양. 유스케이스가 `execute`를 쓰기 트랜잭션 하나로 감싸면(sample `PublishPosterImageUseCase`) 중복 요청은 409 대신 claim insert에서 기다리고, + claim의 abandon이나 executor의 실패 표시가 예외와 함께 롤백된다. persistence·core 영역의 판단이라 넘긴다. +- Redis start·renew에는 lease 만료 검사가 없고 PG에는 있다(`IdempotencyTransitionGateway.java:39,69`). lease가 지났지만 아무도 claim하지 않은 holder가 Redis에서는 시작·연장할 수 있다. + 어느 쪽도 두 번 실행하지 않고 executor는 renew를 부르지 않는다. 이 커밋 전부터의 차이다. +- 늦은 holder의 `markFailed(EFFECT_UNKNOWN_ABANDONED)`가 이미 ABANDONED인 기록에서 `ALREADY`를 받는다(TRANSITION이 목표 상태를 revision보다 먼저 본다). 상태가 같고 executor가 결과를 버리므로 무해하다고 봤다. +- 계약 케이스 `anExecutionIsRememberedPastItsLeaseEvenWhenTheReplayTtlIsNoLonger`의 여유는 0.5초다(기록 2초, 마지막 claim 1.5초). 부하 15의 게이트에서 통과했다. 0.5초 넘는 정지가 나면 흔들릴 수 있지만 재현하지 않았다. +- 10.3절 결정 "lease 뒤 늦게 끝난 첫 시도의 결과를 버린다". 결정이라 뒤집지 않는다. 만든 위험: executor는 lease를 연장하지 않으므로 기본 30초보다 오래 걸리는 action에 lease 뒤 중복 요청이 오면, 효과가 커밋된 첫 요청도 500을 받는다. http-contract `:119-124`에 적혀 있다. +- reaper는 앱 시계, 저장소는 DB 시계를 쓴다(`IdempotencyReaper`). 이전부터다. 이번 수정으로 여유가 lease 이상이 돼 위험은 줄었다. +- `HttpBodyReadException`이 `IOException`이라 "IOException이면 재시도"하는 호출자 코드는 비멱등 스트리밍 호출의 `PARTIAL_RESPONSE` 실패도 재시도한다. `bbe944bd` 전의 bare `IOException`과 같은 동작이고, 재시도 여부는 호출자 몫이며 `failure()`가 분류를 준다. +- 금지 헤더 계산의 `TreeSet.removeAll`은 인자 쪽이 크거나 같으면 대소문자를 가린다(`AbstractSet.removeAll`). Spring 원본과 같은 동작이고 테스트가 같음을 고정한다. +- `metrics.yaml`의 새 값 `histogram_buckets: percentile_histogram`. 이 값을 검사하는 schema는 없고(`MetricsAlertingContractTest`는 `slo_driven`만 본다) 주석이 뜻을 적는다. + +## 수렴 판단 + +- **이 라운드가 만든 새 Important 이상: 없음.** 이 영역의 2차 발견 9건(RR-01-11, RR-03-11~18)이 모두 닫혔고 회귀는 없다. +- 9.1절 결정 두 건(RR-01-11, RR-03-11)은 결정대로 구현됐다. 실 Redis에서 Lua를 직접 돌려 abandon·늦은 complete 거부·기록 수명·renew 여유를 확인했고(E3), + 공유 계약의 시간 케이스가 Live Redis와 실 PostgreSQL 모두에서 skip 없이 돌았다(E2, 게이트 보고서). +- 이 라운드가 만든 새 결함은 Minor 4건이다(RR3-03-01~04). 그중 동작 결함은 RR3-03-01 하나이고, 비기본 JDK transport에서 외부 원인(공용 풀 포화)이 겹칠 때 timeout이 늦어지는 것이다. + 나머지는 문서 정확도다. RR3-03-05와 RR3-03-03의 (b)(c)는 이전부터다. +- 따라서 이 영역만 보면 다음 수정 라운드가 필요하지 않다(9.1절 멈춤 기준 충족). + +## Assessment + +**Ready to merge: Yes.** 2차 발견 9건이 코드·실 서버 탐침·게이트 보고서로 닫혔고, 이 라운드가 만든 Important 이상은 없다. +남은 것은 Minor 5건이며, RR3-03-01(watchdog 실행 스레드)이 동작에 닿는 유일한 항목이다. diff --git a/docs/reviews/2026-11-03-rereview/round3/04-bootstrap-build-sample.md b/docs/reviews/2026-11-03-rereview/round3/04-bootstrap-build-sample.md new file mode 100644 index 00000000..342cfe49 --- /dev/null +++ b/docs/reviews/2026-11-03-rereview/round3/04-bootstrap-build-sample.md @@ -0,0 +1,248 @@ +# 04 bootstrap·build·sample 3차 확인 리뷰 (2026-11-04) + +리뷰 대상: Base `ecc74b7d` → Head `1885bf8d`(3차 수정 커밋, 묶음 r5-d), 영역 번호 04(slug `bootstrap-build-sample`). +재확인한 2차 재리뷰 발견: `round2/04-bootstrap-build-sample.md`의 RR2-04-01~06. 이번 발견 ID 접두어는 `RR3-04-`. +경로는 저장소 루트 기준이다. + +## 범위 — 본 pathspec, 불러온 스킬과 적용한 기준, 실행한 명령과 결과, 못 본 것 + +### 본 pathspec + +```text +src/app-bootstrap src/adapter/outbound/support src/adapter/outbound/objectstorage src/build-logic src/sample-portfolio +src/Dockerfile.sample src/.env.example src/config src/optional-platforms src/README.md .github AGENTS.md CLAUDE.md +docs/registries/secrets-classification.yaml docs/registries/env-keys.yaml docs/capability-status.md +docs/upgrade/2026-11-maturity-review.md infra +``` + +`git diff --stat` 기준 54파일 +1,994 −237. 하위 에이전트 없이 여러 번에 나눠 직접 읽었다. + +- 전부 읽은 것: `StartupRuleRunner`·`StartupRule` diff와 본문, `StartupRuleRunnerTest` diff, `SecretSourceValidator` diff와 본문, + `SecretSourceValidatorTest`·`SecretsClassificationRegistryTest` diff, `WorkflowGradleInvocations` diff와 `gradleInvocation` 본문, + `TaskSelectors` 전문, `StrictLaneStagesPlugin`·`StrictLaneStagesExtension` diff, `StrictLaneStagesFunctionalTest`·`TaskSelectorsTest` + diff, `EnvContractVerifier`·`ConfigContractPlugin`·`VerifyEnvKeysTask` diff, `SpringConfigConventionPlugin` diff, sample의 + `application.yml`·`SampleDemoAccountsProductionGuard`·`SampleDemoProfilesStartupSystemTest`·`application-test.yml`· + `SampleDemoSecurityConfigTest` diff, `Dockerfile.sample`·`.env.example`·`src/README.md`·sample README diff, 업그레이드 안내 B-14·B-15· + B-27·B-36 행, AGENTS.md·CLAUDE.md·`src/app-bootstrap/CLAUDE.md`·`src/app-bootstrap/README.md`·`infra/redis-sdk/acl/README.md`· + `docs/capability-status.md`·`src/config/spotbugs/exclude.xml`·`src/build-logic/README.md`·objectstorage README diff. +- 확인용으로 읽은 pathspec 밖 코드: `SecretReference`, `EnvironmentSecretSource`, `SecretSourceFactory`, + `RedisCredentialResolver`, `RedisRuntimeAutoConfiguration.redisResolvedCredentials`, `RedisAccountContribution`, + `RedisSdkComposition`, `RedisProductionSecrets`, `HttpClientAuthenticationAutoConfiguration.secretKey`, + `MongoCredentialResolver`, `GrpcServerSettings`, `infra/redis-sdk/acl/*.acl`, `compose-profile-contracts.json`의 Redis lane 행. +- 표본으로 읽은 것: `env-keys.yaml` diff(멱등성 행, r5-a 소관), 업그레이드 안내의 마이그레이션 표(r5-c 소관). + +### 불러온 스킬과 적용한 기준 + +| 스킬 | 적용한 기준 | 무엇을 봤나 | +| --- | --- | --- | +| `superpowers:requesting-code-review` | 리뷰어 템플릿(Strengths → severity별 Issues → Declined → Assessment), "spec이 말하지 않은 동작은 합리적인 사용자의 기대로 판단", 읽기 전용, 의심 결함은 별도 worktree에서 확인 | 2차 발견마다 "고치는 법"과 9.1절 결정을 채웠는지, 수정이 만든 새 결함. 의심 9건을 worktree 실험으로 확인 | +| `ci-cd-and-automation` | "No gate can be skipped", 게이트가 주장하는 것과 실제 파이프라인이 같아야 한다, 캐시 최적화가 결과나 증분을 깨면 안 된다 | `verifyStrictLaneStages`가 Gradle 계획과 같은 판정을 내리는지(축약·붙여 쓴 `-x`), 실제 `.github/workflows`를 어느 빌드의 어느 단계로 읽는지, `compileJava`→`processResources` 순서가 캐시·증분을 깨는지 | +| `security-and-hardening` | 위협 모델 먼저(신뢰 경계·자산), 비밀은 환경에서, 공개된 자격증명은 쓰지 않는다, 기본값은 닫힘 | prod `fixture-` 검사가 "비밀값"을 어디서 모으는지, 그 목록에서 빠지는 비밀(우회 경로), 거부 메시지가 값을 드러내지 않는지 | +| `codebase-design` | 인터페이스는 타입이 아니라 불변식까지다, seam에서 불변식을 지킨다, 갈라진 복사본은 결함 | `StartupRule`·`RequiredProductionSecrets` 인터페이스의 불변식(후처리기 없이 만들어짐)을 runner가 seam에서 강제하는지, `CLASSIFIED_SECRETS`·`TaskSelectors`·`EnvContractVerifier`의 두 "declared" 계산이 원본과 묶여 있는지 | + +### 실행한 명령과 결과 + +worktree `scratchpad/rr3-04`(HEAD `1885bf8d`)에서 Gradle을 `flock heavy.lock`으로 감싸 실행했다. 시작 부하 2.3. +probe 파일과 workflow 수정은 worktree에만 했고, 끝난 뒤 `git worktree remove --force`로 지웠다. 메인 체크아웃은 건드리지 않았다. + +| # | 명령 | 결과 | +| --- | --- | --- | +| 1 | support에 probe 추가 → `./gradlew :adapter:outbound:support:test --tests '*RR3ProbeTest*' -i` | rc=0(출력으로 판정). 아래 1-a~1-f | +| 1-a | `@Bean static RequiredProductionSecrets hiddenSecrets()`가 `@Value` 필드 클래스를 돌려줌, 읽는 규칙 없음(= prod 아닌 프로필) | **기동 성공**, 그 bean은 나중에 정상 생성되어 `x=bound` | +| 1-b | 같은 bean + `ObjectProvider`를 기동 중에 읽는 규칙(= prod의 `SecretSourceValidator`) | 기동 실패 `'hiddenSecrets' (...ValueFieldSecrets) ... needs one: [x (@Value)]`. 실패 직전 규칙이 본 값은 `null` | +| 1-c | `@Value`를 메타 애너테이션으로 단 필드를 가진 `@Import` 규칙 | 기동 실패, `[x (@Value)]` | +| 1-d | 생성자 `@Value` 매개변수 하나인 `@Import` 규칙 | 기동 실패 `No default constructor found`(이전부터 같은 동작, 조용하지 않다) | +| 1-e | 부모 클래스의 `@Autowired` setter를 상속한 `@Import` 규칙 | 기동 실패, `[setEnv() (@Autowired)]` | +| 1-f | `@Bean static StartupRule`(선언 타입이 인터페이스)이 `@Value` 필드 클래스를 돌려줌 | 기동 실패, `'hiddenRule' ... [x (@Value)]` | +| 2 | `./gradlew -p build-logic compileTestJava -xcompileJava --dry-run` | Gradle이 붙여 쓴 `-x`를 받는다. 계획에 `:compileJava`가 없다 | +| 3 | worktree의 `integration-main.yml` optional performance 줄을 바꿔 `./gradlew -p optional-platforms :verifyStrictLaneStages --dry-run` | `-x grpcPerformanceT`: **실패** `strict lane :grpc:grpc-testkit:grpcPerformanceTest is in no executed stage`(수정 동작). `-xgrpcPerformanceTest`: **통과** `every strict lane is in an executed stage` | +| 3-b | `./gradlew -p optional-platforms performanceCheck [-xgrpcPerformanceTest] --dry-run` | 없으면 `:grpc:grpc-testkit:grpcPerformanceTest`가 계획에 있고, 붙여 쓴 `-x`면 빠진다 | +| 4 | build-logic에 probe 추가 → `./gradlew -p build-logic test --tests '*RR3WorkflowDumpTest*'`(실제 `.github/workflows` 15개를 `WorkflowGradleInvocations.read`로 읽어 `executes(stage, build)` 출력) | 11줄. `src`: `:ci`·`:sample-portfolio:check` ← ci-quality-gates, `:mainCheck`·`:integrationCheck`·`:performanceCheck` ← integration-main, `:releaseCheck` ← release. `src/optional-platforms`: `:ci` ← ci-quality-gates, `:integrationCheck` ← integration-main·release, `:performanceCheck` ← integration-main, `:releaseCheck` ← release. 다른 빌드로 잘못 센 줄 없음 | +| 5 | `:adapter:outbound:objectstorage:compileJava`를 리소스를 바꿔 가며 세 번 | 다른 리소스 추가: `processResources`만 재실행, `compileJava UP-TO-DATE`. additional metadata 수정: `compileJava` 재실행. 원복: `compileJava FROM-CACHE` | +| 6 | `javap -c -p org/gradle/util/internal/NameMatcher.class`(Gradle 9.0.0 `gradle-core`) | 집합 6개(대소문자 무시·camel 전체·camel 앞부분·camel 앞부분 대소문자 무시·kebab 전체·kebab 앞부분)와 고르는 순서가 `TaskSelectors.matches`와 같은 모양. Levenshtein은 후보 제안에만 쓰인다 | + +돌리지 않은 것: `ci`·`mainCheck`·`integrationCheck` 전체(README 10.2절 오케스트레이터 실행을 근거로 삼았다), +`SampleDemoProfilesStartupSystemTest`(10.2절 `mainCheck`가 `:sample-portfolio:systemTest`를 돈다), `docker build`·`docker run` +(r5-d 보고의 실행 결과를 근거로 삼고 Dockerfile은 정적 확인), `SecretSourceValidator` 우회 경로 실험(코드 읽기로 판정). + +### 못 본 것 + +- 실제 CI runner에서의 workflow 실행(Gitea Actions가 꺼져 있다, README 10.3절). +- `app-bootstrap/src/architectureTest`(01 소관), sample `V8_1`과 `SampleMigrationLockWaitTest`(02 소관), `env-keys.yaml`의 멱등성 + 행 의미(r5-a 소관). +- 파생 서비스(tech-log-backend 등)의 rule·workflow가 새 검사에서 어떻게 되는지. + +## Strengths + +- **prod `fixture-` 검사가 비밀값만 읽고, 비밀 목록이 레지스트리와 묶여 있다.** + `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/runtime/SecretSourceValidator.java:62-81,124-138,170-202`. + 레지스트리 `secret` 행, 모듈이 기여한 비밀, 환경의 모든 `secret://…/` 대상을 모은다. 9.1절 결정("분류된 키만")보다 넓게 + 잡아 compose lane이 실제로 쓰는 모양(참조 + `REDIS_LANE_*`)을 덮는다. `CLASSIFIED_SECRETS`는 + `SecretsClassificationRegistryTest.java:85`가 레지스트리와 1:1로 묶는다. `HOSTNAME`이 통과하는 테스트는 실제 + `SystemEnvironmentPropertySource`를 쓴다(`SecretSourceValidatorTest.java:165`). 메시지는 변수 이름만 적고 값은 적지 않는다. +- **runner가 선언 모양이 아니라 bean이 필요로 하는 것을 본다.** `StartupRuleRunner.java:104-111,151-165,191-228`. + 실험 1-c·1-e·1-f에서 메타 애너테이션 `@Value`, 상속한 `@Autowired` setter, 인터페이스 타입 `static @Bean`이 돌려준 규칙이 + 모두 이름과 멤버를 대며 실패했다. 템플릿의 rule·비밀 목록 클래스 13개에는 해당 멤버가 없다(grep). 2차의 두 probe 모양(JavaBean + 설정 겸 비밀 목록, `@Value` 필드 규칙)은 `StartupRuleRunnerTest.java:168-241`이 RED로 고정한다. +- **축약 `-x`를 Gradle과 같은 규칙으로 맞춘다.** `TaskSelectors.java:114-170`, `StrictLaneStagesPlugin.java:126-157`. + 실험 3에서 2차가 거짓 통과로 잡은 `-x grpcPerformanceT`가 이제 실패한다. 실험 6에서 복사 원본(Gradle 9.0.0 `NameMatcher`)과 + 고르는 순서가 같다. 모호한 선택자는 후보 전부를 뺀 것으로 쳐서 닫힌 쪽으로 틀린다. +- **빌드 디렉터리를 설정이 아니라 저장소 구조에서 읽는다.** `StrictLaneStagesPlugin.java:239-250`, + `WorkflowGradleInvocations.java:255-370`. 실험 4에서 실제 workflow 15개의 모든 단계 실행이 맞는 빌드로 읽혔다. + `with: run:`과 `defaults.run`은 이제 명령이 아니다(`isStepRun`). +- **`compileJava`→`processResources` 순서가 캐시와 증분을 깨지 않는다.** `SpringConfigConventionPlugin.java:20-41`. + 실험 5: 다른 리소스 변경은 `compileJava`를 건드리지 않고, 입력은 additional metadata 파일 하나뿐이며, 원복하면 캐시를 다시 쓴다. +- **허용한 데모 프로필 셋이 같은 문서를 받고, 그 목록에서 테스트가 파생된다.** + `src/sample-portfolio/src/main/resources/application.yml:215-232`(`on-profile: local | test | demo`), + `SampleDemoProfilesStartupSystemTest.java:36-63`(`DEMO_PROFILES`에서 파라미터). object storage를 숨기던 테스트 리소스 복사본을 + 지웠다(`application-test.yml:176-177`, `SampleDemoSecurityConfigTest.java:54-58`). `Dockerfile.sample:8-22`는 이제 `demo`를 넘긴다. +- **lane json의 읽히지 않는 비-`APP_` 키가 실패한다.** `EnvContractVerifier.java:284,348-365`. 1차 사례 + `CASKELETON_GRPC_ENABLED`를 실패로 단언한다(`EnvContractVerifierTest.java:276-300`). + +## 발견 재확인 표 + +상태: 닫힘 / 부분 / 회귀 / 결정으로 닫힘. + +| ID | 상태 | 근거 | +| --- | --- | --- | +| RR2-04-01 | 닫힘(잔여 Minor RR3-04-03) | 검사 대상이 레지스트리 `secret` 행·모듈 기여·`secret://` 대상으로 좁혀짐(`SecretSourceValidator.java:170-202`). `HOSTNAME`·앱 이름·topic이 통과하는 테스트(`SecretSourceValidatorTest.java:165`). 코드가 들고 있는 Redis 계정 참조만 빠진다 | +| RR2-04-02 | 닫힘 | 세 프로필이 같은 yml 문서(`application.yml:224`), 각 프로필 기동 시스템 테스트(`SampleDemoProfilesStartupSystemTest.java:36-63`), guard remedy·README·Dockerfile이 `demo`로 맞춰짐(`SampleDemoAccountsProductionGuard.java:47-53`, `src/sample-portfolio/README.md:56-59`, `src/Dockerfile.sample:8-22`). r5-d가 이미지 실제 기동(프로필 없음 exit 71, `demo` ready)을 확인 | +| RR2-04-03 | 닫힘(잔여 Minor RR3-04-01) | "조용히 null"이 남는 경로는 찾지 못했다(실험 1-c·1-e·1-f, 기존 테스트 4건). 다만 인터페이스 타입 `static @Bean`이 돌려준 비밀 목록은 prod에서만 실패한다(실험 1-a·1-b) | +| RR2-04-04 | 닫힘(잔여 Minor RR3-04-02, 이전부터) | 지목한 네 가지 모두 고침: 축약 `-x`(실험 3), `workflow_dispatch` 전용(`WorkflowGradleInvocations.java:277-325`, TestKit), `working-directory`+`-p`(실험 4), `with: run:`(`isStepRun`). 붙여 쓴 `-x`는 이전부터 읽지 않는다 | +| RR2-04-05 | 닫힘 | 비-`APP_` 키는 `SPRING_`·`MANAGEMENT_`·`SERVER_` 이거나 `secret://` 대상이어야 한다(`EnvContractVerifier.java:348-365`). `property:` 행은 metadata에 있을 때만 읽힘(`:284`). `@ConditionalOnProperty` 스위치는 additional metadata로 선언(`objectstorage/.../additional-spring-configuration-metadata.json`) | +| RR2-04-06 | 닫힘 | capability-status gRPC 행(`app.grpc.server.*`, `GrpcServerSettings.java:27`과 일치), `.env.example:298-299`, `exclude.xml:474-480` 근거 문장, `Dockerfile.sample`, `StartupRuleRunner` Javadoc·`src/app-bootstrap/CLAUDE.md:89-95` | + +회귀로 판정한 발견은 없다. + +## Issues + +### Critical (Must Fix) + +없음. + +### Important (Should Fix) + +없음. + +### Minor (Nice to Have) + +#### RR3-04-01 · 인터페이스 타입 `static @Bean`이 돌려준 비밀 목록은 사전 검사를 지나, `@Value` 멤버가 prod에서만 기동을 막는다 (이번 라운드) + +- **위치**: `src/adapter/outbound/support/src/main/java/dev/caskeleton/adapter/outbound/support/startup/StartupRuleRunner.java:104-111` + (사전 검사가 `beanFactory.getType(name, false)`, 즉 `@Bean` 메서드의 선언 반환 타입을 본다), 같은 파일 `:63-64` Javadoc, + `docs/upgrade/2026-11-maturity-review.md:70` B-15("후자는 모든 프로필"). +- **무엇이 틀렸나**: 사전 검사의 목적은 주석대로 "prod 첫 기동이 아니라 쓴 곳에서 실패"다. 그런데 `@Bean static + RequiredProductionSecrets x() { return new MySecrets(); }`처럼 선언 타입이 인터페이스면, 사전 검사는 인터페이스만 보고 통과한다. + 런타임 클래스 검사는 그 bean이 기동 중에 만들어질 때만 돈다. 규칙은 모든 프로필에서 만들어지므로 규칙 쪽은 문제없다(실험 1-f). + 비밀 목록은 `SecretSourceValidator`가 prod에서만 꺼내므로, 그 클래스의 `@Value` 필드는 prod에서만 걸린다. +- **증거 (E3)**: 실험 1-a — 읽는 규칙이 없으면 기동 성공, bean은 나중에 정상 바인딩. 실험 1-b — 읽는 규칙이 있으면 + `'hiddenSecrets' ... needs one: [x (@Value)]`로 실패. +- **왜 중요한가**: + - 발생 조건: 템플릿 자신의 비밀 목록 선언이 모두 이 모양(`static RequiredProductionSecrets ...()`, 반환은 람다)이다. 이를 + 베낀 서비스가 람다 대신 `@Value` 필드를 가진 클래스를 돌려주면 dev·CI·staging(prod 프로필이 아니면)은 통과하고 첫 운영 배포가 + exit 78로 멈춘다. + - 조용한 실패는 아니다. 메시지가 bean·멤버를 짚고, rolling 배포면 옛 pod가 남는다. 문서가 금지한 모양이기도 하다. + - 그래서 경계 판단에서 낮은 쪽(Minor)으로 둔다. 다만 B-15는 "모든 프로필"이라고 약속하므로 운영자가 CI 통과를 근거로 안심한다. +- **고치는 법**: 사전 검사에서 `RequiredProductionSecrets` bean은 프로필과 무관하게 한 번 만들어(계약상 static·무인자라 비용이 + 없다) `refusePulledForward`와 런타임 클래스 검사를 거친다. 또는 예측 타입이 인터페이스·추상 타입이면 같은 처리를 한다. + 실험 1-a를 RED 테스트로 쓴다. +- **가이드 심각도·우선순위**: Low · P3. +- **증거 등급**: E3. + +#### RR3-04-02 · 붙여 쓴 `-x`는 여전히 읽지 않아 `verifyStrictLaneStages`가 거짓 통과한다 (이전부터) + +- **위치**: `src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocations.java:610-621` + (`-x`·`--exclude-task`만 인자를 받고, `-`로 시작하는 나머지 토큰은 버린다). 문서 주장: `StrictLaneStagesPlugin.java:33-34` + ("matched the way Gradle matches it"), `src/build-logic/README.md:19`, AGENTS.md:85. +- **무엇이 틀렸나**: Gradle 명령줄은 짧은 옵션에 값을 붙여 쓰는 것을 받는다(`-Dk=v`와 같은 규칙). `-xgrpcPerformanceTest`는 그 + 태스크를 계획에서 뺀다. reader는 이 토큰을 모르는 옵션으로 버린다. +- **증거 (E3)**: 실험 2와 3-b(Gradle이 붙여 쓴 `-x`로 lane을 뺀다), 실험 3(같은 줄로 optional 검사가 "every strict lane is in an + executed stage"로 통과). +- **왜 중요한가**: 이번 수정이 고친 축약 `-x`와 같은 종류의 거짓 통과다. 지금 workflow에는 이런 줄이 없다. 이 커밋이 만든 + 틈은 아니다(2차 코드도 같은 토큰을 버렸다). +- **고치는 법**: `token.startsWith("-x") && token.length() > 2`이면 나머지를 제외 선택자로 넣는다. 같은 자리에서 `-p`도 + 읽는다(지금은 버려져 main 빌드 실행으로 센다). reader 단위 테스트 2건. +- **가이드 심각도·우선순위**: Low · P3. +- **증거 등급**: E3. + +#### RR3-04-03 · 코드가 들고 있는 Redis 계정 참조는 `fixture-` 검사가 보지 않는다 (이번 라운드) + +- **위치**: `SecretSourceValidator.java:170-202`(참조를 Environment의 문자열 값에서만 모은다), + `src/adapter/outbound/redis-runtime/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/runtime/config/RedisRuntimeAutoConfiguration.java:147-156` + (`RedisAccountContribution` bean의 참조도 같은 secret source로 풀어 접속한다), + `src/adapter/outbound/redis-sdk/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/lettuce/connection/RedisSdkComposition.java:20,85`. +- **무엇이 틀렸나**: SDK admin plane 같은 모듈은 Redis 계정 참조를 bean(`RedisAccountContribution`)으로 넘긴다. Javadoc 예시는 + `secret://ca-skeleton-admin@environment/APP_REDIS_ADMIN`이다. 그 참조는 Environment 값이 아니므로 검사가 `APP_REDIS_ADMIN`을 + 모른다. 그 변수는 레지스트리 `secret` 행도, 모듈이 기여한 비밀도 아니다. lane ACL에는 같은 계정의 공개 비밀번호 + `fixture-admin`이 있다(`infra/redis-sdk/acl/lane-fixture-accounts.acl:5`). +- **왜 중요한가**: 2차 코드는 모든 값을 봤으므로 이 변수도 잡았다. 범위를 좁힌 결정(9.1절)이 낳은 작은 틈이다. 발생하려면 + 서비스가 admin 계정을 조립하고 lane ACL 비밀번호를 운영에 옮겨야 해서 드물다. 이 계정은 읽기 전용 진단 권한만 있다. +- **고치는 법**: `RedisAccountContribution`을 만드는 쪽(redis-sdk 조립)이 참조 이름을 `RequiredProductionSecrets`로도 내거나, + `SecretSourceValidator`가 `ObjectProvider`를 받지 않고도 볼 수 있게 참조를 설정 키로 받게 한다. + 최소한 ACL README의 "검사가 보는 비밀" 문장에 이 경로가 빠진다고 적는다. +- **가이드 심각도·우선순위**: Low · P3. +- **증거 등급**: E1(코드 읽기). + +#### RR3-04-04 · `EnvContractVerifier`의 "선언된 property" 계산이 둘로 갈라져, 단위 테스트는 운영 경로를 보지 않는다 (이번 라운드) + +- **위치**: `src/build-logic/src/main/java/dev/caskeleton/buildlogic/config/EnvContractVerifier.java:98-124`(7인자 overload가 scope + metadata 파일에서 계산), `VerifyEnvKeysTask.java:86-87`(태스크는 metadata classpath 전체에서 계산해 8인자 overload로), + `EnvContractVerifierTest.java:329-336`(모든 테스트가 7인자). +- **무엇이 틀렸나**: RR2-04-05의 새 규칙("`property:` 행은 선언됐을 때만 읽힘")의 입력을 두 곳이 다르게 만든다. 테스트가 부르는 + 쪽은 `app.redis.` scope 파일만, 태스크는 classpath의 모든 metadata다. 운영 계산(`propertiesUnder(..., "")`)은 단위 테스트에 없다. +- **왜 중요한가**: 규칙 자체는 `mainCheck`의 실제 `verifyEnvKeys`가 지금 저장소로 확인한다. 그러나 classpath 계산이 틀어져도 + (예: additional metadata를 못 읽음) 단위 테스트는 녹색이다. +- **고치는 법**: 7인자 overload가 declared를 따로 만들지 말고 호출자가 넘기게 하거나, `propertiesUnder`를 쓰는 테스트 하나를 둔다. +- **가이드 심각도·우선순위**: Low · P3. +- **증거 등급**: E1. + +#### RR3-04-05 · sample `application.yml` 주석이 시스템 테스트를 실제보다 강하게 말한다 (이번 라운드) + +- **위치**: `src/sample-portfolio/src/main/resources/application.yml:216-220`("starts the sample under each listed profile with + nothing but this file and a database address"). +- **무엇이 틀렸나**: `test` 프로필에서는 systemTest 소스셋의 `application-test.yml`도 함께 읽힌다. 테스트 Javadoc + (`SampleDemoProfilesStartupSystemTest.java:27-29`)은 이를 적는다. 출하 설정에서 `test`와 `demo`가 같은 문서를 받으므로 + 결론(세 프로필 모두 뜬다)은 `demo` 실행으로 성립한다. 주석 문장만 틀렸다. +- **고치는 법**: "`demo`·`local`은 이 파일만으로, `test`는 테스트 리소스를 더해 띄운다"로 고친다. +- **가이드 심각도·우선순위**: Low · P3. +- **증거 등급**: E1. + +## Declined to judge + +- 실험 1-d: 생성자 `@Value`를 가진 `@Import` 규칙이 `No default constructor found`로 실패한다 — 이전부터의 동작이고 모든 + 프로필에서 크게 실패한다. 새 메시지가 "static `@Bean`의 생성자 인자로 넘겨라"라고 바른 길을 알려 준다. +- 실험 1-b에서 규칙이 실패 직전에 바인딩 안 된 비밀 목록을 한 번 호출한다 — 바로 기동이 멈추므로 해가 없다. +- `ConfigTreePropertySource`(Kubernetes secret 파일 mount) 값은 `String`이 아니라서 `forEachStringValue`가 건너뛴다. 센티넬 + 검사는 이전부터 같다. `fixture-` 검사는 분류된 키를 `getProperty`로 풀어 잡으므로, 빠지는 것은 참조 자체를 파일로 mount한 + 드문 경우뿐이다. +- `RedisCredentialResolver`는 첫 `/`, `SecretReference.parse`는 마지막 `/`로 이름을 자른다 — 이름에 `/`가 든 환경 변수는 + 현실적이지 않다. 이전부터. +- HTTP client가 `secret://` 없는 평문 키 참조를 받는데 검사는 `secret://`만 모은다 — lane fixture 비밀번호가 흘러갈 경로가 아니다. +- `paths:` 필터가 있는 PR workflow, `needs:`로 조건부 job에 묶인 job의 명령을 실행으로 센다 — 이전부터의 reader 범위이고 지금 + 단계는 필터 없는 workflow가 돈다(실험 4). +- `cd && ../gradlew` 형태의 디렉터리 이동은 읽지 않는다 — 이전부터. 이번 결정(B-36)은 `working-directory`를 요구한다. +- 비-`APP_` 키 허용 접두사(`SPRING_`·`MANAGEMENT_`·`SERVER_`) 안의 오타는 통과한다 — RR2-04-05 고치는 법이 고른 수준이다. +- `SampleDemoProfilesStartupSystemTest`가 Docker 없으면 건너뛴다(`disabledWithoutDocker`, systemTest lane은 skip을 거부하지 않음) — + sample systemTest 전체가 같은 방식이다. 이전부터. +- `CLASSIFIED_SECRETS`가 레지스트리의 복사본이다 — 테스트가 1:1로 묶으므로 갈라질 수 없다. +- `TaskSelectors`가 Gradle 내부 클래스의 복사본이다 — 내부 API라서 부를 수 없고, Gradle 버전을 올리면 다시 맞춰야 한다. 실험 6에서 + 9.0.0과 같은 모양. +- `docs/upgrade` 표의 멱등성·마이그레이션 행 — r5-a·r5-c 소관. + +## 수렴 판단 — 이 라운드가 만든 새 Important 이상이 있는가 + +**없다.** + +- 2차의 Important 3건(RR2-04-01·02·03)은 모두 닫혔다. 01·03은 코드와 실험으로, 02는 시스템 테스트와 r5-d의 이미지 실행으로 확인했다. +- 이 라운드가 만든 새 결함은 Minor 4건(RR3-04-01·03·04·05)이다. 가장 무거운 RR3-04-01도 조용한 실패가 아니라 이름을 대는 + 기동 실패이고, 문서가 금지한 모양에서만 생긴다. +- RR3-04-02는 이전부터 있던 틈이다. + +이 영역은 다음 수정 라운드가 필요하지 않다. Minor는 후속 작업으로 둘 수 있다. + +## Assessment + +**Ready to merge? Yes.** + +2차의 RR2-04-01~06은 코드·테스트·실험으로 닫혔고 회귀는 없다. 남은 것은 Low 5건(이번 라운드 4, 이전부터 1)이며, +그중 운영에 닿는 RR3-04-01도 크게 실패하는 쪽이라 머지를 막지 않는다.