docs(review): r10 수정 커밋의 확인 리뷰 결과를 기록한다

문제: r10(6e992970)이 round6 결함 25건을 고쳤지만, 그 diff가 새 결함을
만들었는지 본 확인 리뷰가 없다(docs/improvement 09장 5절).

방법: 리뷰어 1명이 네 영역(core·inbound, 멱등성, persistence,
build-logic)을 직접 보고, 의심 결함은 desktop 임시 worktree에 탐침을
얹어 r9·r10에서 돌렸다. 결과는 결함 4건(Important 1, Minor 3, 회귀 1)과
round6 25건 중 닫힘 24·부분 1이다.
- RR7-01-01 회귀: 설정에 중첩된 JAX-RS·JSR-356 endpoint가
  @SystemCaller를 불러도 잡히지 않는다
- RR7-01-02: gRPC가 IAE를 원인으로 든 raw status를 던지면 INTERNAL로
  답하고 그 메시지를 ERROR로 남긴다
- RR7-03-01: 학습 문서의 "섞인 파일은 부분 적용되지 않는다"가
  .sql.conf가 붙으면 틀린다
- RR7-03-02(Important): 실패한 동시 인덱스 복구를 DROP INDEX 하나로
  안내하지만 실패 이력 행이 다음 배포를 막는다
버린 대안: round6처럼 영역마다 문서를 나누는 것. 리뷰어가 한 명이라
범위·명령 절이 네 번 반복된다. round4·5처럼 review.md 하나로 썼다.

위험·한계: 전체 ci·mainCheck·integrationCheck는 다시 돌리지 않았다
(재리뷰 README 17.2절 기록, E0). RR7-03-02의 권장안은 "이력을 고치지
않는다" 정책의 예외라 소유자 결정이 필요하고 실행해 보지 않았다.
round6 Declined 30건의 처리 기록이 README에 없다(총괄 몫).

검증: desktop 공유 잠금 아래에서 r10 :app-bootstrap:architectureTest
(원래 228 통과, 탐침 2 실패), r9 같은 명령 rc=0, 두 빌드
verifyStrictLaneStages --dry-run rc=0, -p build-logic test 162 통과,
grpc 탐침 1 실패(원래 17 통과), 동시 인덱스 IT(원래 4 통과, 탐침 2
실패), 이 문서를 얹은 트리의 :app-bootstrap:documentContractTest 65
통과.

Refs: docs/reviews/2026-11-03-rereview/round7/review.md
This commit is contained in:
DongHyeonka
2026-11-06 22:06:16 +09:00
parent 0647735055
commit 3add4917d2
@@ -0,0 +1,337 @@
# round7 — r10 수정 커밋 확인 리뷰 (2026-11-06)
> 대상: 커밋 `6e992970`(r10, round6 결함 25건 수정), Base `45d2a478`(r9). 리뷰를 시작한 HEAD는 `06477350`
> (브랜치 `claude/t1-baseline-7d623a`, `claude/improvement-manual-6ae516`에서 딴 worktree)다. `6e992970` 뒤의 커밋 넷은
> `docs/improvement/`·`docs/manual/README.md`·리뷰 README·계획서만 바꿨고 이 리뷰의 대상 파일은 건드리지 않았다
> (`git diff --stat 6e992970 06477350`).
>
> 방법: 리뷰어 1명이 네 영역을 직접 봤다(하위 에이전트 없음, `docs/improvement/09-working-method.md` 6절). 절차는
> `docs/improvement/` 01장 1절, 02장 3.2·8.2절, 09장 5절을 따랐다. 결함 ID는 `RR7-<영역>-<순번>`이고 영역 번호는
> round6과 같다(01 core·inbound, 02 멱등성·outbound, 03 persistence, 04 build-logic). 리뷰는 읽기 전용이다. 의심 결함은
> desktop의 임시 worktree에 탐침을 얹어 확인했고, worktree는 끝나고 지웠다.
## 범위
### pathspec
커밋 전체: `git diff --stat 45d2a478..6e992970` → 97개 파일, +5143 −925. 영역별로 나눠 봤다.
| 영역 | pathspec | `git diff --shortstat` |
| --- | --- | --- |
| 01 core·inbound | `src/app-bootstrap/src/architectureTest src/shared-contract src/adapter/inbound/{web,graphql,grpc,websocket} docs/manual/07-authorization.md` | 33개 파일, +1076 −132 |
| 02 멱등성·outbound | `src/application-core src/adapter/outbound/cache-redis src/adapter/outbound/redis-runtime …/idempotency/postgresql/PostgreSqlIdempotencyStore.java docs/manual/05-idempotency.md docs/runbooks/idempotency-unavailable.md` | 15개 파일, +412 −461 |
| 03 persistence | `src/adapter/outbound/persistence-jpa src/adapter/outbound/persistence-notification src/adapter/inbound/messaging src/sample-portfolio src/grpc docs/jpa docs/manual/04-persistence.md docs/study` | 31개 파일, +875 −135 |
| 04 build-logic | `src/build-logic AGENTS.md CLAUDE.md src/README.md` | 11개 파일, +1947 −201 |
나머지는 `docs/upgrade/2026-11-maturity-review.md`, `docs/testing/TESTING_STRATEGY.md`, `docs/reviews/**`다. 앞의 둘은 해당
영역과 함께 읽었다. `docs/reviews/**`(round6 문서 넷, 재리뷰 README 17절, 성숙도 리뷰 README 17절)는 리뷰 기록이라 결함
대상이 아니고 「항목 재확인」의 근거로만 읽었다.
`ShellScript.java`(1659줄)와 `WorkflowGradleInvocations.java`(1248줄)는 diff와 함께 `6e992970`의 새 메서드 전체를 읽었다.
### 함께 읽은 주변 코드
- 01: `ApplicationBoundaryArchitectureTest`의 `ARE_USER_TRANSPORT_TYPES`(`:471-491`)와 새 `ARE_REQUEST_HANDLER_TYPES`
(`:498-548`)·`ARE_USER_TRANSPORTS`(`:565-590`), `SystemCallerHandlerFixture`, `GraphQlWireErrorMapper.sharedCodeOf`,
`GrpcExceptionHandlingInterceptor.interceptCall`·`closeWithError` 경로, `ServerFailureLog.of`, app-bootstrap lockfile의
`architectureTestCompileClasspath`(`jakarta.ws.rs-api`, `jakarta.websocket-api`가 있다).
- 02: Redis `IdempotencyScripts.CLAIM`·`TRANSITION` 전체, `PostgreSqlIdempotencyStore.claim`·`markExecutionStarted`,
`IdempotencyExecutor`의 claim·start 분기, `newAttempt`를 부르는 운영 코드(`PublishPosterImageUseCase:106`, 요청마다
새 attempt), `IdempotencyStoreContract`의 새 케이스 6개, 지운 adapter 테스트 20개와 계약 케이스의 대응,
`docs/web/http-contract.md` §2 표, `docs/registries/error-codes.yaml`의 `IDEMPOTENCY_UNAVAILABLE`.
- 03: `FlywaySchemaPolicy` 전체, 운영·테스트 코드의 `Flyway.configure` 호출 전부(grep), 새
`PostgreSqlConcurrentIndexMigrationIntegrationTest` 전체, `ConcurrentIndexMigrationInspector` 전체, 각 leaf
lockfile의 `flyway-database-postgresql`.
- 04: `.github/workflows/` 15개의 `on:`·`runs-on:`, `src/gradle/wrapper/gradle-wrapper.properties`(9.0.0),
`GradleCommandLineTest`, `build-logic.yml`(이 테스트를 도는 workflow, `src/gradle/**` 경로 포함).
### 불러온 스킬과 적용한 기준
| 스킬 | 적용한 기준 | 본 것 |
| --- | --- | --- |
| `superpowers:requesting-code-review` | 리뷰어 템플릿: 계획(재리뷰 README 17절 r10 행) 대비 구현, 테스트가 진짜 동작을 보는가, 문서 완결성, 심각도별 Issues, Declined to judge, 읽기 전용, 하위 리뷰어를 띄우지 않음 | 25건마다 닫힘 여부(「항목 재확인」), 고친 규칙이 원래 잡던 것을 놓치지 않는가(RR7-01-01), 새 문서 문장이 사실인가(RR7-03-01). 템플릿은 리뷰어 subagent를 띄우라고 하지만 매뉴얼 09장 6절대로 이 세션이 직접 리뷰했다. 템플릿의 Issues·Declined는 매뉴얼 02장 8.2절 순서로 옮겼고, Strengths는 「결론」에 적었다 |
| `research-first` | 크기(중간) → 목적·선행 사례·필요 정보·격차·확인 | 선행 사례로 round4~6 확인 리뷰 문서의 범위·탐침·Declined 처리 방식을 따랐다. 보고에 사고 순서 흔적을 남겼다 |
영역 스킬(`clean-architecture`, `ci-cd-and-automation`, `supabase-postgres-best-practices`)은 따로 부르지 않았다. 각
영역의 판정 기준은 round6 문서가 그 스킬로 세운 기준(설정은 조립 루트이지 입구가 아니다 / 게이트는 거짓 통과가 없어야
한다 / Flyway 잠금과 CIC의 대기 관계)을 그대로 썼다.
### 실행한 명령과 결과
모두 desktop(`~/workspace/clean-architecture-backend-template`)의 임시 detached worktree `/tmp/r7/wt10`(`6e992970`)과
`/tmp/r7/wt9`(`45d2a478`)에서, 탐침 파일만 얹어 공유 잠금(`flock /tmp/claude-gates/heavy.lock`)으로 돌렸다. 괄호 안은
잠금을 얻은 뒤의 1분 부하다. 탐침 코드, 실행 스크립트, 로그, 테스트 보고서(XML)는 공유 노트 폴더 `r7-probes/`에 있다
(저장소 밖). 탐침은 고칠 때 fixture·RED 테스트로 옮겨 쓸 수 있게 테스트 모양으로 썼다.
| # | 명령 (worktree) | 결과 | 시간 | 부하 |
| --- | --- | --- | --- | --- |
| 1 | `./gradlew :app-bootstrap:architectureTest` (r10 + 탐침 fixture 3개·`Round7ProbeTest`) | rc=1. 231개 중 원래 228개 통과, 탐침 3개 중 2개 실패: 설정에 중첩된 JAX-RS resource 위반 0건, 설정에 중첩된 `@ServerEndpoint` 위반 0건. 최상위 JAX-RS resource는 1건(통과) | 51초 | 1.13 |
| 2 | 같은 명령 (r9 + 같은 탐침) | rc=0. 219개 모두 통과: 탐침 셋 모두 위반 1건 | 142초 | 4.70 |
| 3 | `./gradlew :verifyStrictLaneStages --dry-run` (r10) | rc=0, "every strict lane is in an executed stage" | 23초 | 7.83 |
| 4 | `./gradlew -p optional-platforms :verifyStrictLaneStages --dry-run` (r10) | rc=0, 같은 출력 | 16초 | 5.77 |
| 5 | `unzip -p flyway-database-postgresql-11.14.1.jar …/PostgreSQLConfigurationExtension.class \| strings` (Gradle 캐시) | 상수 `FLYWAY_POSTGRESQL_TRANSACTIONAL_LOCK`, `flyway.postgresql.transactional.lock`이 있다 | — | — |
| 6 | `./gradlew :adapter:inbound:grpc:test --tests '*GrpcExceptionHandlingInterceptorTest'` (r10 + 탐침 1개) | rc=1. 18개 중 원래 17개 통과, 탐침 실패: 원인이 `IllegalArgumentException`인 raw status를 던지면 `INTERNAL`·ERROR(예외 메시지 `unknown recipient alice@example.com` 첨부), 같은 status를 `close`로 넘기면 `INVALID_ARGUMENT`·WARN(메시지 없음) | 19초 | 2.78 |
| 7 | `./gradlew -p build-logic test` (r10) | rc=0, 테스트 162개, 실패·건너뜀 0 | 56초 | 5.40 |
| 8 | `./gradlew :adapter:outbound:persistence-jpa:postgresqlConcurrentIndexMigrationIntegrationTest` (r10 + 탐침 2개) | 첫 실행 rc=1: 탐침 코드가 Error Prone `StringConcatToTextBlock`(-Werror)으로 컴파일 실패(68초, 7.17). 탐침을 고쳐 다시 실행: rc=1, 6개 중 원래 4개 통과(CIC·`REINDEX … CONCURRENTLY` × Spring Boot 조립·정책), 탐침 2개 중 1개 실패 — 아래 표 | 124초 | 3.75 |
| 9 | 같은 lane (r10 + 탐침 3개) | rc=1, 7개 중 원래 4개 통과, 탐침 3개 중 2개 실패(8의 것과 복구 탐침) — 아래 표 | 22초 | 1.42 |
명령 8·9의 PostgreSQL 탐침. V1은 `probe` 테이블과 일반 인덱스, 그리고 `note`가 겹치는 행 하나를 넣는다. 모두
`FlywaySchemaPolicy.configure()`(세션 잠금)로 적용했다.
| V2 | `.sql.conf` | 결과 |
| --- | --- | --- |
| `INSERT … (3001, 'partial');` + `CREATE UNIQUE INDEX CONCURRENTLY …;` | 없음 | Flyway가 실행 전에 거부("Detected both transactional and non-transactional statements … mixed is false"). 행 3001 없음, 이력 V1만 |
| 같음 | `executeInTransaction=false` | `FlywayMigrateException` SQLState 23505. **행 3001이 남았다**(부분 적용), `ix_probe_note_u valid=false`, 이력 `2 success=false` |
| `CREATE UNIQUE INDEX CONCURRENTLY …;` 하나 | `executeInTransaction=false` | 23505로 실패. 겹친 행을 지우고 가이드대로 `DROP INDEX ix_probe_note_u` 뒤 다시 배포 → `FlywayValidateException: Validate failed: … Detected failed migration to version 2 (unique note).` 이력 `2 success=false`가 남아 다음 배포가 막힌다 |
임시 worktree 둘과 `/tmp/r7`은 끝나고 지웠다(`git worktree list`에 남은 것 0). desktop checkout의 브랜치는 건드리지 않았다.
### 못 본 것
- 전체 `ci`·`mainCheck`·`integrationCheck`는 돌리지 않았다. `6e992970`과 같은 트리(`2c692554`)가 desktop에서 모두 통과한
기록이 재리뷰 README 17.2절에 있다(E0). 이 리뷰는 판정에 필요한 lane만 다시 돌렸다(위 표).
- 실제 GitHub runner, Windows runner의 `pwsh`. RR6-04-04 닫힘은 코드(E1)와 `-p build-logic test`(E2)로만 봤다.
- JAX-RS·JSR-356 endpoint를 실제로 띄운 실행. RR7-01-01은 ArchUnit 규칙의 판정만 확인했다(규칙이 막는다고 약속한 것이
판정이다).
- Flyway CLI와 실제 배포 마이그레이션 도구. 업그레이드 안내 15행의 환경 변수 이름은 플러그인 jar의 상수로만 확인했다(명령 5, E1).
- `flyway repair`를 실제로 돌린 복구. RR7-03-02의 권장안은 실행하지 않은 제안이다.
- RR6-02-02의 변이 3건, RR6-03-04의 optional `spotlessCheck`는 다시 돌리지 않았다(재리뷰 README 17절 기록, E0).
## 항목 재확인
재리뷰 README 17절이 고쳤다고 한 round6 결함 25건이다. 경로의 앞부분은 줄였다(`ApplicationBoundaryArchitectureTest`는
`src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/` 아래, 나머지는 파일 이름으로 찾는다).
| ID | 판정 | 근거 |
| --- | --- | --- |
| RR6-01-01 (Important, 회귀) | 닫힘 — 단 고친 방식이 RR7-01-01을 만들었다 | 설정과 그 중첩 클래스는 `ARE_REQUEST_HANDLER_TYPES`에 의존하면 사용자 전송이다(`ApplicationBoundaryArchitectureTest.java:565-590`). 함수형 route·`DataFetcher`·중첩 `HandlerFunction` 위반 fixture가 잡힌다(`ArchitectureViolationFixtureTest.java:565-617`, 명령 1의 228개 통과) |
| RR6-01-02 | 닫힘 | 설정 필드를 읽는 익명 `WebMvcConfigurer`가 통과한다(`ArchitectureViolationFixtureTest.java:619`, 명령 1). 같은 변경이 중첩 클래스 판정을 좁혔다 → RR7-01-01 |
| RR6-01-03 | 닫힘 | 예외 제외(`:749`), record·enum은 언어가 주는 상위 타입만 허용(`:798-809`). `Runnable` record는 여전히 잡힌다(fixture, 명령 1) |
| RR6-01-04 | 닫힘 | 판정이 status 코드에서 `delegate.isCancelled()`로 바뀌었다(`GrpcExceptionHandlingInterceptor.java:143`). 살아 있는 호출의 `CANCELLED`는 남는다(테스트 `aCancelledStatusTheServiceClosesALiveCallWithIsLoggedAsUnhandled`) |
| RR6-01-05 | 닫힘 | 던진 raw status는 그 status 예외를 붙이지 않고 그 뒤의 원인만 붙인다(`:173-180`). 설명은 남지 않는다(테스트 2건, 명령 6). 던진 raw status의 원인이 `IllegalArgumentException`이면 그 메시지가 붙고 답도 `onError`와 다르다 → RR7-01-02(이전부터) |
| RR6-01-06 | 닫힘 | 네 전송이 `ServerFailureLog.refusedArgument`(`ServerFailureLog.java:91`)의 WARN 한 줄을 쓴다: web `GlobalExceptionHandler.java:88`, GraphQL `GraphQlWireErrorMapper.java:130-140`, gRPC `GrpcExceptionHandlingInterceptor.java:137-139`, STOMP `StompHandlerFailureLog.java:39-43`. 전송마다 메시지·예외가 없음을 단언하는 테스트가 있다 |
| RR6-01-07 | 닫힘 | runbook이 그 문구를 붙은 예외의 메시지(prod JSON의 `stack_trace`)로 적는다(`idempotency-unavailable.md:22-25`, `:103`) |
| RR6-01-08 | 닫힘 | 테스트가 4xx carrier(`IdempotencyInFlightException`)를 넣는다(`GraphQlWireErrorMapperTest.java:194-205`) |
| RR6-01-09 (이전부터) | 닫힘 | 대상이 `dev.caskeleton.shared..`이고 허용은 정확한 12개 패키지(`ForbiddenApiArchitectureTest.java:59-72`, `:114-127`). fixture는 대리 뿌리로 증명하고, 목록과 모듈의 실제 패키지가 같은지 본다(`SharedContractPackageRuleTest`). 모듈 패키지 12개와 `CLAUDE.md` 목록이 같다(`ls`로 확인). "KNOWN DEFECT" 주석은 지워졌다 |
| RR6-02-01 | 닫힘 | Redis CLAIM이 넘겨받기를 같은 owner 재생보다 먼저 본다(`IdempotencyScripts.java:86-98`). 시작의 ALREADY는 기록 revision이 핸들 + 1일 때만(`:160-162`). PG도 같은 순서(`PostgreSqlIdempotencyStore.java:141-160`)이고 시작 digest가 핸들의 attempt·revision을 담는다(`:193`). command fake·in-memory fake도 같은 순서. 계약 케이스 6개(`anAttemptWhoseStartWasRefusedTakesItsClaimOverWhenItClaimsAgain`, `aLateStartThroughTheHandleBeforeTheTakeoverIsRefusedAsAStaleOwner` 등)가 Redis·PG·두 fake에 걸린다. 운영 호출자는 요청마다 새 attempt를 만들어(`PublishPosterImageUseCase.java:106`) 바뀐 순서가 운영 요청의 재생을 바꾸지 않는다 |
| RR6-02-02 | 닫힘 | command fake가 hash TTL·`PTTL`을 모델링한다(`InMemorySemanticRedisCommands.java:684-709`). `TESTING_STRATEGY.md`가 skip 0과 변이 3건을 적는다. 이 리뷰에서 변이는 다시 돌리지 않았다(E0) |
| RR6-02-03 | 닫힘 | RR6-01-07과 같은 문장 |
| RR6-02-04 | 닫힘 | web README 매핑 표(`src/adapter/inbound/web/README.md:243`), 인계 표(`docs/upgrade/2026-11-maturity-review.md:284`)가 `docs/web/http-contract.md:111`과 같은 뜻이다 |
| RR6-02-05 | 닫힘 | 매뉴얼 05 첫 문단이 저장소별로 나뉜다(`docs/manual/05-idempotency.md:57-61`) |
| RR6-03-01 (Important, 이전부터) | 닫힘 | module-defaults `spring.flyway.postgresql.transactional-lock: false`(`persistence-jpa.yml:140-149`), 직접 만드는 Flyway는 `FlywaySchemaPolicy.configure()`(`:115-122`), 운영 코드의 `Flyway.configure` 호출은 ArchUnit이 거부(`JpaProductionArchitectureTest.java:169-190`, grep으로 남은 운영 호출 0 — messaging inbox stream의 사본만 예외이고 대조 테스트가 있다). 실 PG IT 4건이 Spring Boot 조립과 정책 양쪽으로 CIC·`REINDEX … CONCURRENTLY`를 끝낸다(명령 8·9에서 원래 4건 통과, E3). Flyway 플러그인 jar의 환경 변수 이름이 업그레이드 안내 15행과 같다(명령 5) |
| RR6-03-02 | 닫힘 | E-문자열(`LockWaitMigrationInspector.java:477-507`)과 중첩 주석(`:510-528`). 테스트 6건 |
| RR6-03-03 | 닫힘 | `PostgreSQLParser`의 static `Pattern` 8개를 값까지 고정하는 테스트가 PR `ci` lane에 있다(`LockWaitMigrationInspectorTest.java:274-298`). Javadoc·가이드가 "대조 목록의 문장만"으로 고쳐졌다 |
| RR6-03-04 | 닫힘(E1) | ledger Spotless가 Sync 출력을 뺀다(`src/grpc/grpc-operation-ledger-jpa/build.gradle:37-41`). 이 리뷰에서 다시 돌리지 않았다 |
| RR6-03-05 | 부분 | 세 곳이 "Flyway가 늘 트랜잭션으로 감싼다"를 더 말하지 않는다. 그러나 고쳐 쓴 학습 문서가 "섞인 파일은 부분 적용되지 않는다"는 새 틀린 문장을 넣었다 → RR7-03-01 |
| RR6-04-01 | 닫힘 | 작업 없이 끝나는 옵션 표(`WorkflowGradleInvocations.java:134-142`)와 판정. `GradleCommandLineTest`가 `--stop`·`--foreground` 밖의 옵션을 실제 launcher로 돌린다 |
| RR6-04-02 | 닫힘 | `GradleCommandLineTest.java:60`이 판독기 옵션 표를 이 빌드를 돌리는 Gradle(`build.gradle:110`의 `ca.gradle.home`, wrapper 9.0.0)의 `--help`와 비교한다. 이 테스트를 도는 `build-logic.yml`의 경로 필터에 `src/gradle/**`가 있어(`:12`, `:18`) wrapper를 올리는 PR에서 돈다 |
| RR6-04-03 | 닫힘 | 조건부·함수 안 `exit 0`, `exec`, `set -n`, EXIT·ERR trap(`ShellScript.java:1225-1460`). 서브셸·파이프·명령 치환 안의 `exit`은 그 셸만 끝낸다고 바르게 뺀다. `source`·`eval` 뒤는 디렉터리를 못 읽어 세지 않는다 |
| RR6-04-04 | 닫힘(E1·E2) | 셸 없는 step은 `container:`나 Linux·macOS label일 때만 센다(`WorkflowGradleInvocations.java:753-787`). 이 repo workflow 15개는 모두 `ubuntu-latest`다 |
| RR6-04-05 | 닫힘 | 세지 않는 이유 셋이 `NOT_COUNTED`(`StrictLaneStagesPlugin.java:61-75`), 두 판독기의 메시지, `AGENTS.md`·`CLAUDE.md`·`src/README.md`·build-logic README·업그레이드 B-36에서 같은 분류다(문장 대조) |
| RR6-04-06 | 닫힘 | 요청형 trigger·`types`, `workflow_call`의 호출자, `needs` 사슬(`WorkflowGradleInvocations.java:570-750`). 두 빌드의 `verifyStrictLaneStages --dry-run`이 이 repo workflow로 통과한다(명령 3·4) |
## 결함
### RR7-01-01 · Minor · 설정에 중첩된 JAX-RS resource와 JSR-356 endpoint가 `@SystemCaller`를 불러도 잡히지 않는다 (회귀)
- **위치**:
- 규칙: `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ApplicationBoundaryArchitectureTest.java:565-590`
(`ARE_USER_TRANSPORTS` — 설정이거나 설정에 중첩된 클래스는 `ARE_REQUEST_HANDLER_TYPES`로만 판정, `:574-579`), `:583-590`
(`isOrIsNestedInAConfiguration`).
- 두 목록: `:471-491`(`ARE_USER_TRANSPORT_TYPES` — `jakarta.ws.rs..`, `jakarta.websocket..`, `org.springframework.web..`,
`org.springframework.messaging.simp..` 전체), `:498-548`(`REQUEST_HANDLER_TYPE_NAMES`·`ARE_REQUEST_HANDLER_TYPES` — JAX-RS 항목이 없고,
`jakarta.websocket`은 `Endpoint` 하나뿐이다).
- 안내: `docs/manual/07-authorization.md:105`(② 설정과 그 안에 중첩된 클래스는 요청 처리기 타입으로 판정),
`:108-113`("새 전송 라이브러리를 들이면 … 요청 처리기 타입도 … 함께 더한다").
- **무엇이 틀렸나**:
- r9는 `@Configuration`이 붙은 클래스 자신만 사용자 전송에서 뺐다. 그 안에 중첩된 클래스는 다른 클래스처럼
`ARE_USER_TRANSPORT_TYPES`로 판정했다.
- r10은 설정에 중첩된 클래스도 좁은 목록 `ARE_REQUEST_HANDLER_TYPES`로 판정한다. 설정 필드를 읽는 익명
`WebMvcConfigurer`를 풀어 주려는 변경(RR6-01-02)이다.
- 그런데 좁은 목록이 넓은 목록의 라이브러리를 다 덮지 않는다. `ARE_USER_TRANSPORT_TYPES`가 아는 JAX-RS
(`@Path`·`@POST`)와 JSR-356 annotated endpoint(`@ServerEndpoint`·`@OnMessage`·`Session`)의 handler 타입이
`ARE_REQUEST_HANDLER_TYPES`에 없다.
- 그래서 설정에 중첩된 JAX-RS resource나 `@ServerEndpoint`가 시스템 호출자를 부르면 r9에서는 잡혔고 r10에서는
잡히지 않는다. 같은 resource를 최상위 클래스로 쓰면 r10에서도 잡힌다(명령 1·2).
- 매뉴얼 07은 두 목록을 함께 늘리라고 하지만, 이 커밋이 만든 두 목록의 첫 내용부터 그 규칙을 따르지 않는다.
- **발생 조건·영향**:
- JAX-RS(Jersey 등)나 JSR-356 endpoint를 들인 파생 서비스가 "지금 실행" endpoint를 그 handler를 등록하는 설정
안에 중첩 클래스로 쓰고, 그 endpoint가 `@SystemCaller`를 부른다.
- 사용자 요청이 권한 검사 없는 `@SystemInvoked` 쓰기에 닿는다. 그 길을 막겠다는 규칙(`USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`)이
조용히 통과한다.
- 템플릿에는 JAX-RS·JSR-356 endpoint가 없고, 중첩 클래스로 쓰는 모양도 드물어 Minor다. 같은 방식으로 WebFlux
`WebFilter`·`WebHandler`(`org.springframework.web.server..`)도 빠진다(E1, 실행하지 않음).
- **테스트가 못 본 이유**: r10의 fixture는 좁은 목록에 든 타입(`RouterFunction`, `HandlerFunction`, `DataFetcher`)만
설정 안에 쓴다. 넓은 목록에만 있는 라이브러리를 설정에 중첩한 fixture가 없고, 두 목록이 같은 라이브러리를 덮는지
보는 테스트도 없다.
- **고치는 법**:
- (권장) `ARE_REQUEST_HANDLER_TYPES`에 넓은 목록이 이미 아는 라이브러리의 handler 타입을 더한다. JAX-RS:
`jakarta.ws.rs.Path`와 HTTP 메서드 annotation(`GET`·`POST`·`PUT`·`DELETE`·`PATCH`·`HEAD`·`OPTIONS`),
`jakarta.ws.rs.container..`. JSR-356: `jakarta.websocket.server.ServerEndpoint`, `jakarta.websocket.OnMessage`·`OnOpen`,
`jakarta.websocket.Session`, `jakarta.websocket.MessageHandler`. WebFlux: `org.springframework.web.server.WebFilter`·`WebHandler`·`ServerWebExchange`.
그리고 두 목록이 같은 라이브러리를 덮는지 보는 테스트를 둔다. 넓은 목록의 라이브러리 뿌리마다 좁은 목록에
항목이 하나 이상 있어야 한다. 그래야 매뉴얼 07의 "함께 더한다"가 글로만 남지 않는다(부록 A10).
- (대안) 설정 자신은 지금처럼 좁은 목록으로, 설정에 중첩된 클래스는 넓은 목록에서 설정 타입(`*Configurer`,
`*Registry`, `*Registration`)만 빼고 판정한다. 목록에 없는 새 라이브러리에서 잡히는 쪽(fail closed)이지만, 빼는
목록이 하나 더 생긴다.
- RED: 명령 1의 탐침 fixture 둘(설정에 중첩된 `@Path` resource, `@ServerEndpoint`)을
`ArchitectureViolationFixtureTest`의 위반 fixture로 옮긴다. `6e992970`에서는 위반 0건으로 실패하고, `45d2a478`에서는
통과한다(명령 2).
- **이번 커밋/이전부터**: 이번 커밋(회귀).
- **증거**: E2 — 명령 1(r10: 중첩 JAX-RS 0건, 중첩 `@ServerEndpoint` 0건, 최상위 JAX-RS 1건), 명령 2(r9: 셋 모두 1건).
WebFlux 부분은 E1.
### RR7-01-02 · Minor · gRPC 서비스가 `IllegalArgumentException`을 원인으로 든 raw status를 던지면 `INTERNAL_ERROR`로 답하고 그 메시지를 ERROR로 남긴다 — 같은 status를 `onError`로 넘기면 `BAD_PARAMETER`·WARN이다
- **위치**:
- 코드: `src/adapter/inbound/grpc/src/main/java/dev/caskeleton/adapter/inbound/grpc/GrpcExceptionHandlingInterceptor.java:137`
(`status.getCause() instanceof IllegalArgumentException` — 던진 경우 원인은 status 예외다), `:153`
(`closeWithError`가 던진 예외를 status의 원인으로 둔다), `:156-180`(`logUnrecognised`가 `failureBehind`로 status 예외
뒤의 원인을 붙인다).
- 문서: `src/adapter/inbound/grpc/README.md:157-158`("`IllegalArgumentException`은 … WARN 한 줄 … 만 남긴다(메시지
없음)"), `:160-161`("raw status는 `onError`로 넘겼든 던졌든 …"), `src/shared-contract/README.md:94-98`("네 전송
모두 … 메시지는 입력값이 들 수 있어 남기지 않고 예외도 붙이지 않는다").
- **무엇이 틀렸나**:
- `onError(Status.INVALID_ARGUMENT.withCause(iae).asRuntimeException())`는 `close(Status.fromThrowable(t))`가 된다.
status의 원인이 `IllegalArgumentException`이라 `BAD_PARAMETER`로 답하고 WARN 한 줄만 남긴다.
- 같은 예외를 던지면 `closeWithError`가 그 status 예외를 원인으로 둔다. `:137`은 원인 자리의 status 예외를 보고
`IllegalArgumentException`이 아니라고 판정한다. `INTERNAL_ERROR`로 답한다.
- 이어서 r10의 `failureBehind`가 status 예외를 벗기고 그 뒤의 `IllegalArgumentException`을 ERROR 줄에 붙인다. 메시지
(명령 6: `unknown recipient alice@example.com`)가 로그에 남는다.
- README는 이 전송에서 `IllegalArgumentException`이 메시지 없는 WARN 한 줄만 남는다고 하고, raw status는 넘기든 던지든
같게 다룬다고 한다. 둘 다 이 경로에서 사실이 아니다.
- **발생 조건·영향**:
- 입력 검증 실패를 `Status.INVALID_ARGUMENT.withCause(e).asRuntimeException()`로 던지는 gRPC 서비스(grpc-java의 흔한
모양). 클라이언트는 `INVALID_ARGUMENT` 대신 재시도할 수 없는 `INTERNAL`을 받는다. 같은 실패가 넘기는 방식에 따라 다른
코드가 된다.
- 서버 로그에 입력값이 든 메시지가 ERROR와 스택으로 남는다. RR6-01-05·06이 막으려던 것이다.
- grpc 어댑터는 기본 조립에 없고 이 모양을 쓰는 서비스에서만 생겨 Minor다.
- **테스트가 못 본 이유**: r10이 더한 테스트는 원인이 `IllegalStateException`인 raw status(`aThrownRawStatusWithACauseIsLoggedWithTheCauseAlone`)와
원인 없는 raw status만 던진다. 원인이 `IllegalArgumentException`인 raw status를 던진 경우와 넘긴 경우를 비교하는 테스트가
없다.
- **고치는 법**: `close`가 판정에 쓰는 원인을 `failureBehind(status.getCause())`로 한 번 구하고, carrier·
`IllegalArgumentException` 판정과 로그에 같은 값을 쓴다. 그러면 던진 경우도 `BAD_PARAMETER`·WARN이 된다. RED: 명령 6의
탐침(`r7probeARawStatusWithAnIllegalArgumentCauseIsAnsweredTheSameThrownOrPassed`)이 지금 `INTERNAL` ≠
`INVALID_ARGUMENT`로 실패한다. 로그 줄이 WARN이고 예외가 붙지 않는다는 단언을 더한다.
- **이번 커밋/이전부터**: 이전부터. r9도 같은 답을 했고, 붙인 status 예외의 원인 사슬로 같은 메시지를 남겼다. r10이 RR6-01-05를
고치며 이 경로를 직접 다시 썼는데 이 경우를 놓쳤다.
- **증거**: E2 — 명령 6. r9의 로그 내용은 E1(그때 `logUnrecognised`가 붙인 것이 status 예외 자체였다).
### RR7-03-01 · Minor · 학습 문서가 "섞인 파일은 부분 적용되지 않는다"고 적지만, 가이드가 요구하는 `.sql.conf`를 붙이면 부분 적용된다
- **위치**:
- `docs/study/postgresql-jpa-walkthrough.ko.md:1346-1348`(r10이 쓴 문장: "다른 문장과 섞인 파일은 Flyway가 기본값
(`mixed=false`)에서 아무것도 실행하기 전에 거부한다. 부분 적용은 일어나지 않는다").
- 같은 주장의 근거가 된 Javadoc: `src/adapter/outbound/persistence-jpa/src/testFixtures/java/dev/caskeleton/adapter/outbound/persistence/testkit/migration/ConcurrentIndexMigrationInspector.java:16-19`.
- **무엇이 틀렸나**:
- Flyway의 `mixed=false` 거부는 `.sql.conf`가 트랜잭션 여부를 정하지 않은 파일에만 걸린다.
- 같은 문서 바로 위 문단, 가이드 "Concurrent index builds", 검사기 `validate`는 동시 인덱스 문장마다
`executeInTransaction=false`를 적으라고 한다.
- 그 설정이 붙은 섞인 파일은 Flyway가 거부하지 않고 문장마다 트랜잭션 없이 돌린다. 앞 문장은 커밋되고, 동시 인덱스가
실패하면 무효 인덱스와 `success=false` 이력이 남는다(명령 8: 행 3001이 남음).
- 그래서 그 문장은 문서가 안내하는 모양에서 틀렸다. r10이 고친 옛 문장("그것들은 커밋되고 인덱스만 안 된다")이 오히려
이 모양에서는 맞았다.
- **발생 조건·영향**: 학습 문서를 읽고 "섞어도 Flyway가 막아 준다"고 믿은 개발자가 `.sql.conf`를 붙인 채 다른 문장과 동시
인덱스를 한 파일에 둔다. 검사기 `requireIsolatedStatement`가 그 파일을 거부하지만, 검사기는 서비스가 마이그레이션 테스트를
둘 때만 돈다(가이드 `:146-147` "nothing checks it at startup"). 그 밖에서는 부분 적용된 스키마와 실패 이력이 남는다.
문서 오류라 Minor다.
- **테스트가 못 본 이유**: 문서 문장이다. `.sql.conf`가 있는 섞인 파일을 Flyway로 끝까지 돌린 테스트가 없다. 새 IT는 한 문장짜리
파일만 돌린다.
- **고치는 법**: 문장을 둘로 나눈다. "`.sql.conf` 없이 섞으면 Flyway가 실행 전에 거부한다. `executeInTransaction=false`를
붙이고 섞으면 Flyway가 문장마다 따로 커밋해 부분 적용된다. 그래서 동시 인덱스 문장은 혼자 둔다(`requireIsolatedStatement`)."
검사기 Javadoc `:16-19`에도 "설정 파일이 없을 때"를 붙인다. 회귀를 막으려면 명령 8의 두 탐침을 IT에 옮긴다(`.sql.conf`
없음 → 실행 전 거부, 있음 → 부분 적용을 사실로 고정).
- **이번 커밋/이전부터**: 이번 커밋(RR6-03-05를 고치며 쓴 문장).
- **증거**: E3 — 명령 8.
### RR7-03-02 · Important · 실패한 동시 인덱스 마이그레이션의 복구를 "`DROP INDEX` 하나"라고 안내하지만, 남은 실패 이력이 다음 배포를 막는다
- **위치**:
- 안내(같은 문장 세 벌): `docs/jpa/migration-guide.md:147-149`, `ConcurrentIndexMigrationInspector.java:70-73`
(`requireIsolatedStatement` Javadoc), `docs/study/postgresql-jpa-walkthrough.ko.md:1369-1371`.
- 막는 규칙: `docs/jpa/migration-guide.md:37-48`("Validation fails closed and never repairs", repair는 승인된 관리자
작업으로만), `docs/runbooks/migration-failed.md:42-66`(실패 분류에 이 경우가 없다), `:95`("delete or rewrite Flyway
history to make validation green" 금지), `:107`(history repair 전 DB 소유자에게 올린다).
- **무엇이 틀렸나**:
- Flyway는 트랜잭션 밖에서 돈 마이그레이션이 실패하면 이력에 `success=false` 행을 남긴다(명령 8·9).
- 다음 배포의 validate는 그 행 때문에 실패한다: "Detected failed migration to version 2". 무효 인덱스를 지우고 원인
데이터를 고쳐도 같다(명령 9).
- 그래서 "마이그레이션이 다른 일을 하지 않았으면 `DROP INDEX` 하나로 복구된다"는 안내를 따르면 배포는 여전히 막힌다.
실패 이력 행도 지워야 한다(`flyway repair` 또는 그 행 삭제).
- 그런데 같은 가이드는 repair를 승인된 관리자 작업으로만 두고, runbook은 이력 수정을 금지한 채 이 실패를 분류하지 않는다.
문서 어디에도 이 경우의 실행 가능한 복구 절차가 없다.
- **발생 조건·영향**:
- 가이드대로 동시 인덱스 마이그레이션을 쓴 파생 서비스에서 빌드가 실패한다. 유일 인덱스의 중복 값, deadlock,
`statement_timeout`, 오래 걸려 운영자가 취소한 경우다.
- 운영자는 안내대로 `DROP INDEX`하고 다시 배포하지만 validate 실패로 기동이 또 멈춘다(dev·test는 앱 기동, staging·prod는
배포 도구). runbook에서는 이 실패를 찾을 수 없고, 금지 목록이 유일한 해결(실패 이력 행 제거)을 막는다.
- 데이터 손실은 없고 실패가 닫힌 쪽(기동 거부)이다. 그래도 운영자에게 효과 없는 조치를 시키는 문서라 매뉴얼 02장 3.2절의
Important 정의에 든다. r10 전에는 Flyway 기본 잠금 때문에 동시 빌드가 실패까지 가지 못하고 멈췄다(취소하면 같은 상태).
r10이 빌드를 실제로 돌게 해서 이 경로가 흔해졌다.
- **테스트가 못 본 이유**: 새 IT는 성공하는 동시 빌드와 상한에 걸려 취소되는 경우만 본다. 실패한 동시 빌드 뒤의 재배포를 돌린
테스트가 없다.
- **고치는 법**:
- (권장) 세 문장을 "무효 인덱스를 `DROP INDEX`하고, 실패 이력 행을 지운 뒤(아래 SQL), 원인을 고쳐 다시 배포한다"로 고친다.
이력 행 삭제는 `DELETE FROM <history_table> WHERE version = '<v>' AND NOT success` 한 줄로, 성공한 행과 checksum은
건드리지 않는다. runbook 「Classify the failure」에 "트랜잭션 밖 마이그레이션 실패(`success=false` 행)" 항목과 그 SQL을
더하고, 「Do not」의 이력 수정 금지에 이 예외를 적는다. 이 예외는 "repair하지 않는다"는 정책을 좁히므로 소유자 확인이
필요하다(08장 3절).
- (대안) `flyway repair`를 이 경우에 허용한다. repair는 실패 행 삭제 말고도 적용된 마이그레이션의 checksum·설명을 다시
맞추므로, 가이드 `:44-48`이 막으려는 checksum 불일치까지 지운다. 권하지 않는다.
- RED: 명령 9의 복구 탐침(`r7probeAFailedConcurrentBuildIsRecoveredByDroppingTheInvalidIndex`)을 IT에 옮기고, 문서가
정한 절차(`DROP INDEX` + 실패 행 삭제)를 그대로 실행하게 고친다. 지금 문서 절차(`DROP INDEX`만)로는
`FlywayValidateException`으로 실패한다.
- **이번 커밋/이전부터**: 이전부터(가이드 문장은 `6d27356e`부터). r10이 바로 옆 문단을 고쳐 쓰고 동시 빌드를 실제로 돌게 했다.
- **증거**: E3 — 명령 8·9(실 PostgreSQL 16, Flyway 11.14.1, 정책 세션 잠금).
## Declined to judge
이번 리뷰가 판단하지 않은 것:
- **`paths:`·`branches:` 필터가 있는 trigger**(04). r10이 "workflow가 언제 도는가"를 이벤트와 `types`로 정했지만 필터는
보지 않는다. 그래서 `pull_request: paths: [...]`인 workflow(`fileserver-pr.yml`, `build-logic.yml` 등)도 "모든 변경에
도는" workflow로 센다. 지금 단계 명령은 필터 없는 workflow에서만 돌아 거짓 통과는 없다. round6 04가 "어떤 필터가 충분한지는
저장소 정책"이라며 판단하지 않은 항목이고, 아직 결정이 없다. 총괄이 결정으로 닫을 것.
- **`new FluentConfiguration()`·`new ClassicConfiguration()`으로 만든 Flyway**(03). `JpaProductionArchitectureTest`는
`Flyway.configure(...)` 호출만 거부한다. 다른 생성 경로는 Flyway 기본(트랜잭션) 잠금을 다시 갖는다. 문서는 "`Flyway.configure()`를
거부한다"고 정확히 적고, 그 경로를 쓰는 코드는 이 repo에 없다.
- **`docs/registries/error-codes.yaml`의 `IDEMPOTENCY_UNAVAILABLE` `log_level: WARN`**(02, pathspec 밖). 전송은 5xx
carrier를 ERROR로 남기고(`ServerFailureLog.java:71-76`), r10의 runbook도 ERROR라고 적는다. round6 02가 판단하지 않고 넘긴
항목이고 아직 처리 기록이 없다.
- **같은 owner token에 다른 operation id**(02). r10이 claim 순서를 바꿔, 이 조합은 재시도 가능 실패·lease 지난 claim에서
`OwnerOperationConflict` 대신 넘겨받기가 된다. 아무것도 실행되지 않은 기록이라 넘겨받아도 안전하고,
`OwnerOperationConflict`에는 Javadoc 약속도 계약 케이스도 없다. 운영 호출자는 요청마다 새 attempt를 만든다.
- **설정이 `RequestMethod`·`@CrossOrigin`·`HttpServletRequest`를 쓰는 경우**(01). `ARE_REQUEST_HANDLER_TYPES`가
`org.springframework.web.bind.annotation..`·`jakarta.servlet.http..`를 통째로 담아, 그런 설정이 시스템 호출자를 bean으로
등록하면 거짓 실패한다. 지금 트리에는 없다(명령 1에서 원래 228개 통과).
- **`trap '…; exit $rc' EXIT` 관용구, `kill $$`와 신호 trap**(04). 앞의 것은 "0으로 끝날 수 있음"으로 읽어 세지 않는다(거짓
실패, 재리뷰 README 16절이 받은 방향). 뒤의 것은 판독기가 모델링하지 않는 거짓 통과지만 일부러 만든 모양이다.
- **`ConcurrentIndexMigrationInspector`가 주석을 지우지 않는다**(03). 주석 안의 `CREATE INDEX CONCURRENTLY`도 동시 문장으로
센다. 거부 쪽이고 이전부터다.
round6이 판단하지 않은 항목의 처리 기록이 없다. round6 문서 넷의 「Declined to judge」는 30건이다(01: 7, 02: 6, 03: 10,
04: 7). 재리뷰 README 17절에는 그 배정이나 결정이 없다. r10이 그중 03의 "중첩 블록 주석"만 함께 고쳤다. 매뉴얼 09장 5절
종료 조건 2와 01장 1절 완료 기준은 총괄이 이 항목을 다음 묶음에 배정하거나 결정으로 닫으라고 한다. 이 리뷰는 그 항목들을
다시 판정하지 않았다. 그중 이 리뷰가 지나가며 보고 아직 사실이 그대로인 것은 셋이다. 위의 trigger 필터와 레지스트리
log level, 그리고 round6 04의 httpclient 문서 항목이다. `docs/httpclient/release-checklist.md:12`와
`docs/httpclient/support-matrix.md:61,72,86`이 없는 lane `spring62CompatibilityTest`를 적는다. 실제 lane은
`spring62ApiSurfaceScan`이다(`src/adapter/outbound/httpclient/build.gradle:187`).
## 결론
결함 4건: Critical 0, Important 1, Minor 3. 회귀 1건(RR7-01-01).
| ID | 심각도 | 이번 커밋 / 이전부터 | 증거 | 부록 패턴 |
| --- | --- | --- | --- | --- |
| RR7-01-01 | Minor | 이번 커밋(회귀) | E2 | A1(두 목록이 같은 전송을 다르게 덮는다), A12 |
| RR7-01-02 | Minor | 이전부터(r10이 같은 경로를 고치며 놓침) | E2 | A8 |
| RR7-03-01 | Minor | 이번 커밋 | E3 | A2, A12 |
| RR7-03-02 | Important | 이전부터(r10이 그 경로를 흔하게 만듦) | E3 | A2 |
- round6 25건: 닫힘 24, 부분 1(RR6-03-05 → RR7-03-01). 두 Important(RR6-01-01, RR6-03-01)는 닫혔다.
- 02 멱등성·04 build-logic 영역에서는 새 결함을 찾지 못했다. 두 저장소·두 fake의 claim 순서와 시작 확인 조건이 서로 같고 계약
케이스가 넷 모두에 걸린다. 판독기는 이 repo workflow로 두 빌드 모두 통과하고 테스트 162개가 통과한다.
- 결정이 필요한 것: RR7-03-02의 복구 절차는 "이력을 고치지 않는다" 정책의 예외다. 선택지는 (a) 실패 행만 지우는 SQL을
runbook에 예외로 둔다(권장, checksum은 건드리지 않음), (b) 이 경우 `flyway repair`를 허용한다. 승인자는 소유자다.
- 매뉴얼 09장 5절의 종료 조건 1(발견 0)이 아직 아니다. 위 4건과 round6·이번 Declined를 총괄이 다음 수정 묶음에 배정하거나
결정으로 닫아야 한다.