diff --git a/docs/reviews/2026-11-03-rereview/round8/01-transport-errors.md b/docs/reviews/2026-11-03-rereview/round8/01-transport-errors.md new file mode 100644 index 00000000..647f2357 --- /dev/null +++ b/docs/reviews/2026-11-03-rereview/round8/01-transport-errors.md @@ -0,0 +1,163 @@ +# 01 전송 오류 처리 round7 수정 확인 리뷰 (2026-11-07) + +> 대상: `5f6a86d7`(RR7-01-03~06: 네 전송이 원인 사슬의 첫 carrier를 보고, 락 timeout을 carrier로, STOMP 거부를 WARN 한 줄로)와 +> `ef8ef170`(`Retry-After`를 레지스트리대로, GraphQL `@Argument` 변환 실패를 `BAD_PARAMETER`로). +> 범위 `2c8a359d..83a12f66`, 기준 커밋 `83a12f66`(브랜치 `claude/integration-r8-a4196a`, 리뷰 브랜치 `refactor/maturity-review-2026-11`에서 딴 통합 결과). +> 독립 리뷰어 둘 중 정본 리뷰어(세션 r8-review-a)가 썼다. 이 라운드의 영역 표와 나눈 이유는 아래 「범위」에 있고, 다른 영역 문서는 이 표를 가리킨다. +> 이 라운드의 색인 절은 두 리뷰를 합친 뒤 총괄이 README에 쓴다(`docs/work/improve.md` 4.1절 7단계). 그 전까지 색인 검사는 rc=1이다(RR8-06-01). + +## 범위 + +### pathspec + +``` +src/shared-contract src/adapter/inbound/web src/adapter/inbound/graphql src/adapter/inbound/grpc src/adapter/inbound/websocket +src/application-core/src/main/java/dev/caskeleton/application/lock src/application-core/src/test/java/dev/caskeleton/application/lock +src/app-bootstrap/src/test docs/runbooks/lock-acquisition-timeout.md +``` + +`git diff --stat 2c8a359d..83a12f66 -- `: 30개 파일, +1056 −125. + +범위 전체(`docs/reviews/**` 제외)는 116개 파일 +3,747줄이다. 확인 리뷰 상한(추가 1,500줄, `docs/work/improve.md` 4.4절)을 넘어 영역 여섯으로 +나눴다. 한 세션이 여섯 영역을 차례로 봤다. + +| 영역 | 대상 커밋 | `git diff --shortstat` | +|---|---|---| +| 01 전송 오류(이 문서) | `5f6a86d7`, `ef8ef170` | 30 파일, +1056 −125 | +| [02 아키텍처 규칙](02-architecture-rules.md) | `a8166598` | 14 파일, +725 −94 | +| [03 마이그레이션·Flyway 규칙](03-migration.md) | `6ec0c4f7`, `6764246a` | 28 파일, +747 −125 | +| [04 멱등 저장소](04-idempotency.md) | `14435106` | 12 파일, +382 −61 | +| [05 build-logic·httpclient·작은 문서](05-build-logic-httpclient.md) | `6cd5e925`, `a490c20f`, `c746f980`, `eab82df1`, `ac3c6a81` | 11 파일, +547 −100 | +| [06 매뉴얼·검사 스크립트](06-manual-scripts.md) | `b872b0ea`, `73d39212`, `6dd9ef76`, `b619c442`, `447a77a3`, `b7d13104`, `81ef58ab` | 18 파일, +253 −67 | +| 공통 문서(영역마다 자기 행을 읽음) | `docs/upgrade/2026-11-maturity-review.md`, `src/application-core/README.md`, `src/adapter/outbound/persistence-jpa/README.md` | 3 파일, +37 −15 | + +여섯 영역과 공통 문서의 합이 범위 전체와 같다(116 파일, +3,747 −587, 빠진 파일 0). + +함께 읽은 주변 코드: `GraphQlExceptionResolver` 전체(등록된 매핑이 어떻게 고르는지), web `GlobalExceptionHandler` 전체와 sample +`DomainExceptionHandler`(도메인 advice 순서), `ServerFailureLog.of`, `MeteredDistributedLock`·`LockRegistryDistributedLock`(락 timeout이 어디서 +로그를 남기는지), `docs/registries/metrics.yaml`의 `lock.acquisition`, `EnvelopeErrorController` Javadoc(필터가 던진 실패), `RetryAfterAdvisor`와 +`docs/registries/error-codes.yaml`의 `retry_after_seconds` 행 전체. + +### 수정 보고의 「새로 가정하는 것」 + +수정 보고는 repo에 없다(공유 노트 `r8-f1-transport-errors.md`). 그 노트 「정한 기본값」, 두 커밋 본문 「위험·한계」, README 18.4·18.7절에서 뽑았다. + +| 가정 | 확인 | +|---|---| +| 원인 사슬의 첫 carrier를 보면 바뀌는 응답은 "지금 500 `INTERNAL_ERROR`로 뭉개지는 경우뿐"이다(소유자 결정의 전제, README 18.4절 RR7-01-05 행) | **거짓.** GraphQL은 원인 사슬의 carrier를 등록된 application 매핑보다 먼저 본다. 앱이 등록한 실패가 carrier를 원인으로 들면 그 매핑의 코드 대신 carrier 코드로 답한다. 수정 전에는 매핑 코드였다(RR8-01-01) | +| 4xx carrier는 서버 로그를 남기지 않아도 된다("4xx라 'unhandled exception' ERROR 줄이 사라진다", B-45) | 락 timeout에는 문제가 된다. 이제 어느 락에서 났는지 서버에 아무 흔적이 없는데, runbook은 그 정보가 없는 metric과 없는 테이블을 보라고 한다(RR8-01-02) | +| Spring 7.0.9 변환기는 받은 메시지를 읽기 실패에만 싣는다(STOMP 쓰기/읽기 실패 구분) | 참. 노트의 바이트코드 확인과 테스트 `aReplyTheConverterCannotWriteIsLoggedAtErrorWithTheFailure`가 지킨다 | +| `RetryAfterAdvisor` 표와 레지스트리를 `OperationalError` 코드만 대조해도 된다 | 참. 레지스트리에 `retry_after_seconds`가 있는 행 17개가 모두 `OperationalError` 코드이고 표의 17개와 같다(`error-codes.yaml`을 grep으로 셈). 다른 leaf 코드는 `RetryAfterHint`로 말한다 | +| GraphQL `BindException`은 인자 binder만 던진다 | 참으로 봤다. 템플릿 GraphQL 코드에 `BindException`을 만드는 곳이 없다(grep) | + +### 불러온 스킬과 적용한 기준 + +| 스킬 | 기준 | 본 것 | +|---|---|---| +| `superpowers:requesting-code-review` | 주장과 구현이 맞나, 테스트가 이름대로 보나, 심각도 보정, 읽기 전용. 하위 에이전트는 repo 설정이 막아 직접 봤다 | 고친 항목마다 닫힘, 바뀐 판정 순서가 다른 경로의 답을 바꾸는지 | +| `docs/work/reference/review-criteria.md` 1·3·4·6절 | 약속과 실제가 다른 곳, Critical/Important/Minor, E 수준, 관점 6·8·17 | 소유자 결정의 전제, runbook 조치, 공개 응답 코드 | +| `docs/work/reference/defect-patterns.md` | 같은 규칙을 경계마다 다시 구현(A1), 글로만 있는 약속 | 네 전송의 판정 순서, web 도메인 advice와 GraphQL 등록 매핑 | + +### 실행한 명령과 결과 + +desktop 임시 worktree `~/workspace/r8-review-a`(`83a12f66`)와 `~/workspace/r8-review-a-base`(`2c8a359d`)에 탐침을 얹고 +`flock /tmp/claude-gates/heavy.lock` 아래에서 차례로 `--no-build-cache`로 돌렸다. 로그 desktop `~/r8-review-a-logs/`(`summary.txt`), +탐침 코드와 돌리는 법은 공유 노트 폴더 `r8-review-a-probes/`에 있다. 명령 번호는 여섯 영역 문서가 같이 쓴다. + +| # | 명령 | 대상 | 결과 | 시간 | 직전 부하(1분) | +|---|---|---|---|---|---| +| A1 | `:adapter:inbound:graphql:test --tests '*Rr8RegisteredMappingProbeTest'` | `83a12f66` + 탐침 | rc=0. 등록 매핑의 실패가 carrier를 원인으로 들면 `code=DB_UNAVAILABLE category=DEPENDENCY`, 원인이 없으면 `ORDER_UNAVAILABLE` | 19초 | 1.29 | +| A2 | 같은 명령 | `2c8a359d` + 같은 탐침 | rc=0. 두 경우 모두 `code=ORDER_UNAVAILABLE category=BUSINESS` | 18초 | 2.19 | +| A8 | 바뀐 leaf 테스트 `--rerun`(shared-contract, application-core, web, graphql, grpc, websocket, httpclient, cache-redis, persistence-jpa `test`, app-bootstrap `architectureTest`) | `83a12f66` + 탐침 | 03 영역 문서 「실행한 명령과 결과」 | — | — | + +탐침 `Rr8RegisteredMappingProbeTest`는 `GraphQlExceptionResolver`에 앱 실패 `OrderUnavailableException`을 `ORDER_UNAVAILABLE`(`BUSINESS`)로 +등록하고, 그 실패가 `PersistenceFailureException(DB_UNAVAILABLE)`을 원인으로 든 경우와 원인 없는 경우를 `GraphQlWireErrorMapper.map`에 넣는다. + +### 못 본 것 + +- 실제 GraphQL·gRPC 서버 기동: 판정은 매퍼·인터셉터 단위로 봤다. 묶음 보고의 systemTest·qualification lane 통과는 E0다. +- STOMP 필수 header 누락(`MessageHandlingException`) ERROR 유지는 결정 색인 2.3절의 기본값이라 다시 판정하지 않았다. + +## 항목 재확인 + +| ID | 판정 | 근거 | +|---|---|---| +| RR7-01-03 (gRPC가 던진 raw status와 넘긴 raw status의 판정이 다름) | 닫힘 | `GrpcExceptionHandlingInterceptor.java:135-150`이 status 예외를 벗긴 실패 하나(`failureBehind`)로 carrier·IAE 판정과 로그를 한다. 테스트 `GrpcExceptionHandlingInterceptorTest`의 던짐/넘김 두 경우 | +| RR7-01-04 (락 timeout이 500) | 닫힘 | `LockAcquisitionTimeoutException implements ApiErrorCarrier`(`LockAcquisitionTimeoutException.java:16-17`), `RetryAfterAdvisor.java:35`. web 409·`Retry-After: 1`, GraphQL 같은 코드 테스트. 다만 4xx가 되며 진단 흔적이 사라진 것은 RR8-01-02 | +| RR7-01-05 (감싼 carrier를 gRPC만 봄) | 부분 | 네 전송 일곱 자리가 `ApiErrorCarrier.firstIn` 하나를 쓴다(grep). 그런데 GraphQL에서는 이 판정이 등록된 application 매핑보다 앞서, 결정이 전제한 범위 밖의 응답까지 바꿨다(RR8-01-01) | +| RR7-01-06 (STOMP 거부 ERROR + 입력) | 닫힘 | `StompHandlerFailureLog.java:64-92`, 실제 handler 경로 테스트 `aClientArgumentRefusalIsLoggedAtWarnByItsTypeWithoutItsMessage` 4건과 쓰기 실패 ERROR 테스트 | +| r8-f1 범위 밖 1(`Retry-After` 7개 누락) | 닫힘 | `RetryAfterAdvisor.java:19-43`이 레지스트리 17행과 같다. 대조 테스트 `OperationalErrorRegistryContractTest.everyRegisteredRetryAfterIsTheHeaderTheWebAdapterSends` | +| r8-f1 범위 밖 2(GraphQL `BindException`) | 닫힘 | `GraphQlWireErrorMapper.java:221-224`, 실제 binder 경로 테스트 `GraphQlArgumentBindingFailureTest` | + +## 결함 + +### RR8-01-01 · Important · GraphQL이 원인 사슬의 carrier를 앱이 등록한 매핑보다 먼저 보아, 등록한 실패가 carrier를 원인으로 들면 앱이 정한 코드 대신 carrier 코드로 답한다 (회귀) + +- **위치**: + - 코드: `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/error/GraphQlWireErrorMapper.java:121-131`(`map`: 공유 코드가 있으면 등록 매핑을 보지 않음), `:210-219`(`sharedCodeOf`가 원인 사슬 전체에서 carrier를 찾음). + - 코드(약속): `GraphQlExceptionResolver.java:10-14`("Registered ones — the failures the application deliberately models — map to their own code"). + - 결정·문서: `docs/work/reference/decisions.md:88`(「감싼 carrier를 전송이 읽는 법」: "감싼 carrier의 응답이 500 `INTERNAL_ERROR` 대신 그 carrier의 코드가 된다"), `docs/reviews/2026-11-03-rereview/README.md:506`(결정 근거 "바뀌는 응답은 지금 500 `INTERNAL_ERROR`로 뭉개지는 경우뿐이다"), `docs/upgrade/2026-11-maturity-review.md:104`(B-46 "전에는 500 `INTERNAL_ERROR`"), `src/adapter/inbound/graphql/README.md:66-80`, `src/adapter/inbound/graphql/CLAUDE.md:122-126`. + - 비교(web): `GlobalExceptionHandler.java:56-60`("domain exceptions are handled by a separate `@RestControllerAdvice`"), sample `DomainExceptionHandler.java:26`(`@Order(Ordered.HIGHEST_PRECEDENCE)`). +- **무엇이 틀렸나**: + - GraphQL 판정 순서는 플랫폼 거부 → carrier → 등록된 application 매핑 → 거부된 인자다. + - 수정 전에는 carrier 단계가 실패 **자신**만 봤다. 그래서 앱이 등록한 실패(carrier 아님)는 원인에 무엇이 있든 등록 매핑으로 갔다. + - 수정 뒤에는 carrier 단계가 원인 사슬 전체를 본다. 앱이 등록한 실패가 carrier를 원인으로 들면 carrier 단계에서 끝나고, 등록 매핑은 보지 않는다. + - 탐침: 같은 실패(`OrderUnavailableException`, 원인 `PersistenceFailureException(DB_UNAVAILABLE)`)가 `2c8a359d`에서는 `ORDER_UNAVAILABLE`, `83a12f66`에서는 `DB_UNAVAILABLE`(`DEPENDENCY`)로 나갔다. + - 소유자 결정은 "바뀌는 응답은 500 `INTERNAL_ERROR`로 뭉개지던 경우뿐"이라는 전제로 내려졌다. 이 경우는 500이 아니라 앱이 정한 코드였다. 결정 범위 밖의 공개 응답이 바뀌었다. + - web은 다르게 답한다. 앱의 도메인 advice(sample처럼 `HIGHEST_PRECEDENCE`)가 그 실패 타입을 받아 앱 코드로 답한다. 같은 유스케이스 실패에 web은 `ORDER_UNAVAILABLE`, GraphQL은 `DB_UNAVAILABLE`이다. 커밋 제목("네 전송이 같은 실패에 같은 코드로")과도 반대다. +- **발생 조건·영향**: + - 조건: 앱이 `GraphQlExceptionResolver`에 자기 실패를 등록하고, 그 실패를 만들 때 하위 실패를 원인으로 넘긴다(`new X(..., cause)`). 원인을 넘기는 것은 로그를 위한 Java의 보통 관례다. 예: 결제 의존 실패(`DependencyFailureException`)를 `PaymentUnavailableException`으로 바꿔 던짐. + - 영향: 클라이언트가 분기하는 `extensions.code`·`classification`·`retryable`이 앱이 정한 값에서 인프라 코드로 바뀐다. 예에서 `PAYMENT_UNAVAILABLE`을 기다리는 클라이언트가 `DEPENDENCY_5XX_SERVER`를 받는다. 업그레이드 안내 B-46은 이 변화를 적지 않아 서비스가 미리 알 수 없다. + - Important로 둔 이유: 공개 응답 코드가 앱이 일부러 정한 값과 다르게 나가고, 이번 수정이 만든 회귀다. 템플릿 자체에는 원인을 든 등록 매핑이 없어 템플릿 테스트에서는 드러나지 않는다. +- **테스트가 못 본 이유**: 새 테스트 `aCarrierWrappedInAnotherExceptionKeepsItsOwnCode`는 등록 매핑이 없는 `masking()` 매퍼로 감싼 carrier만 본다. 등록 매핑과 감싼 carrier가 함께 있는 경우가 없다. +- **고치는 법**: + - 권장: 판정 순서를 플랫폼 거부 → 실패 **자신**이 carrier → 등록된 application 매핑 → 원인 사슬의 첫 carrier → 거부된 인자로 바꾼다. 등록 매핑은 앱이 그 타입에 내린 결정이라 원인보다 앞선다. web의 도메인 advice 순서와 같아진다. 로그 줄은 지금처럼 찾은 carrier로 정한다. + - 대안: 지금 순서를 두고 "등록한 실패는 carrier를 원인으로 넘기지 않는다"를 매퍼 Javadoc·GraphQL README·B-46에 적는다. 앱 코드에 원인 버리기를 강요하고 web과 계속 다르다. + - RED 테스트 모양: 탐침 `Rr8RegisteredMappingProbeTest`를 `GraphQlWireErrorMapperTest`의 테스트로 옮긴다. 등록 매핑 + carrier 원인 → `ORDER_UNAVAILABLE`을 단언하면 `83a12f66`에서 `DB_UNAVAILABLE`로 실패한다. + - 고치는 법이 공개 응답을 되돌리므로 `docs/work/improve.md` 7절대로 소유자 확인이 필요하다. 다만 결정 전제 밖에서 바뀐 것을 결정 범위로 되돌리는 것이다. +- **이번 수정 / 이전부터**: 이번 수정(회귀). +- **증거**: E2 — 명령 A1·A2(같은 탐침을 두 커밋에서). 순서·문서 대조는 E1. + +### RR8-01-02 · Important · 락 timeout이 4xx가 되며 어느 락인지 서버 어디에도 남지 않는데, runbook은 그 정보가 없는 metric과 없는 테이블을 보라고 한다 + +- **위치**: + - 문서: `docs/runbooks/lock-acquisition-timeout.md:17`("A 4xx answer, so no server ERROR line — look at the metric"), `:25`("Check `lock.acquisition` metric for lock name and duration"), `:26`("check DB `integration_lock` table"). + - 레지스트리·코드: `docs/registries/metrics.yaml:301-318`(`lock.acquisition`은 `outcome` tag 하나뿐인 counter, "key 는 tag 로 넣지 않는다"), `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/lock/MeteredDistributedLock.java:48-50`(timeout은 세기만 하고 로그 없음), `src/adapter/outbound/persistence-jpa/src/main/resources/db/migration/postgresql/V4__int_lock.sql`(테이블 이름 `INT_LOCK`, `LOCK_KEY`는 key의 UUID). + - 코드(약속): `LockAcquisitionTimeoutException.java:14`("`getMessage()` is server-log-only"), `src/application-core/README.md:585`("진단용 `getMessage()`(key·waitTime 포함)는 서버 로그 전용"), `ServerFailureLog.java:76-83`(5xx가 아닌 carrier는 로그 없음). +- **무엇이 틀렸나**: + - 수정 전에는 락 timeout이 500 "unhandled exception" ERROR로 남았고, 그 예외 메시지에 락 key와 대기 시간이 있었다(r8-f1 RED 로그의 `unhandled exception on uri=…` + 예외). + - 수정 뒤에는 4xx carrier라 `ServerFailureLog.of`가 아무것도 남기지 않는다. 락 adapter(`MeteredDistributedLock`, `LockRegistryDistributedLock`)도 timeout에 로그를 남기지 않는다. 이제 "어느 락이 막혔나"는 서버 어디에도 없다. + - runbook은 "metric을 보라", "metric에서 lock name과 duration을 확인하라"고 한다. `lock.acquisition`은 `outcome` 하나만 tag로 가진 counter다. 이름도 시간도 없다. 레지스트리는 key를 tag로 넣지 말라고 적는다. + - runbook은 holder를 `integration_lock` 테이블에서 찾으라고 한다. 테이블은 `INT_LOCK`이고, `LOCK_KEY`는 key 자체가 아니라 key의 UUID다. `APP_MULTI_INSTANCE_ENABLED=false`(기본, in-process 락)이면 테이블이 쓰이지 않는다. + - 예외 Javadoc과 application-core README는 메시지가 "서버 로그 전용"이라고 적는다. 그 메시지를 남기는 서버 로그는 이제 없다. +- **발생 조건·영향**: + - 조건: 락 경합이 늘어 409 `LOCK_ACQUISITION_TIMEOUT`이 쌓이고, 운영자가 이 runbook을 연다. + - 영향: 운영자는 runbook대로 metric에서 락 이름을 찾지 못하고, 없는 테이블을 조회한다. 어느 임계 구역이 경합하는지 알아낼 길이 runbook에 없다. 수정 전에는 적어도 ERROR 로그에 key가 있었다. + - Important로 둔 이유: 운영자에게 틀린 조치를 시키는 runbook이다(`review-criteria.md` 3절). runbook이 `status: stub`이어도 `error_codes`가 이 코드를 가리키는 유일한 문서다. +- **테스트가 못 본 이유**: runbook을 읽는 테스트(`RunbookCoverageContractTest`)는 front matter의 `error_codes`와 stub 여부만 본다. 이 runbook은 그 테스트의 stub 허용 목록(`RunbookCoverageContractTest.java:101`)에 있다. 본문 절차를 실행하는 lane이 없다. 4xx carrier가 로그를 남기지 않는 것은 의도된 동작이고, 락에 대해 그 결과를 따로 보는 테스트가 없다. +- **고치는 법**: + - 권장: runbook Diagnosis를 있는 정보로 다시 쓴다. ① 경합 비율은 `lock.acquisition{outcome=timeout}`(이름·시간 없음을 명시). ② multi-instance면 holder는 `INT_LOCK`의 `REGION`·`CLIENT_ID`·`CREATED_DATE`로 보고, `LOCK_KEY`가 key의 UUID라 key 이름을 직접 볼 수 없다고 적는다. ③ 그 SQL에 `runbook-sql` 표시를 달아 다른 runbook처럼 실 PostgreSQL lane이 읽어 돌린다. 예외 Javadoc·application-core README의 "서버 로그 전용"은 "로그에 남지 않는다. 클라이언트에 보내지 않는다"로 고친다. + - 대안: 락 timeout에 WARN 한 줄(key의 digest, 대기 시간)을 남기는 곳을 정한다(`MeteredDistributedLock`). key에 엔티티 id가 들 수 있어 원문은 남기지 않는다(persistence-jpa `CLAUDE.md` 「Non-negotiables」). 그러면 runbook이 그 줄을 가리킬 수 있다. 로그 정책을 바꾸므로 소유자 결정이다. + - RED 테스트 모양: 권장안은 문서 수정이라 코드 RED가 없다. runbook SQL을 실 PostgreSQL에서 돌리는 테스트를 더하면, 지금 runbook의 `integration_lock`로는 "relation does not exist"로 실패한다. +- **이번 수정 / 이전부터**: 섞임. Diagnosis 두 줄의 잘못은 이전부터다. 이번 수정이 key가 남던 유일한 로그를 없애고 runbook에 "metric을 보라"를 더해, 틀린 안내가 유일한 진단 경로가 됐다. +- **증거**: E1 — 위 `file:line`(레지스트리 정의, adapter 코드, `ServerFailureLog.of`의 분기). + +## 18.6절에서 넘어온 항목 판정 + +README 18.6절 4번이 "다음 확인 리뷰가 판정한다"고 넘긴 전송 오류 항목이다. + +| 항목 | 판정 | 근거 | +|---|---|---| +| web 필터가 던진 carrier는 `EnvelopeErrorController`가 status만 봐 500 `INTERNAL_ERROR` | 결함 아님 | `EnvelopeErrorController.java:6-21` Javadoc이 필터가 던진 실패를 status로 분류한다고 적고, 다른 status가 필요한 필터는 `EnvelopeResponseWriter`로 그 코드를 쓰라고 안내한다. 템플릿 필터(web·web-advanced·graphql) 가운데 carrier를 던지는 것은 없다(grep: `JsonBodyLimitFilter`는 `MaxUploadSizeExceededException`, web-advanced carrier는 handler·resolver에서 던짐). carrier 계약(`ApiErrorCarrier`·shared-contract README)은 전송 처리기를 말하고 필터는 말하지 않는다 | + +## Declined to judge + +- `MethodArgumentTypeMismatchException`·`HttpMessageNotReadableException`처럼 Spring MVC가 감싸 web 전용 처리기로 가는 실패에 carrier가 원인으로 있는 경우(사용자 `Converter`나 Jackson creator가 carrier를 던짐): web은 원인을 보지 않고 `BAD_PARAMETER`·`VALIDATION_FAILED`로 답하고, STOMP는 `ConversionFailedException`의 원인 carrier로 로그를 정한다. 결정 「감싼 carrier를 전송이 읽는 법」이 전송 처리기 앞단(인자 변환)까지 덮는지 정해진 것이 없다. 템플릿에 carrier를 던지는 변환기가 없어(grep) 결함으로 세지 않았다. 맡긴 쪽이 결정 범위를 정할 일이다. + +## 결론 + +Critical 0, Important 2, Minor 0, 회귀 1(RR8-01-01). 결함 2건: 이번 수정 1건, 섞임 1건. + +- RR7-01-03·04·06과 r8-f1 범위 밖 두 건은 닫혔다. RR7-01-05는 네 전송이 같은 함수를 쓰게 됐지만, GraphQL에서 그 함수의 자리가 등록 매핑보다 앞이라 + 결정 범위 밖의 응답을 바꿨다. +- 락 timeout은 이제 맞는 코드로 답하지만, 진단 흔적이 사라진 자리를 runbook이 틀린 안내로 채우고 있다. diff --git a/docs/reviews/2026-11-03-rereview/round8/02-architecture-rules.md b/docs/reviews/2026-11-03-rereview/round8/02-architecture-rules.md new file mode 100644 index 00000000..ebb6a4bf --- /dev/null +++ b/docs/reviews/2026-11-03-rereview/round8/02-architecture-rules.md @@ -0,0 +1,104 @@ +# 02 아키텍처 규칙 round7 수정 확인 리뷰 (2026-11-07) + +> 대상: `a8166598`(RR7-01-01·02: 설정 클래스 자신만 요청 처리기 목록으로, 중첩 클래스는 사용자 전송 목록에서 설정용 타입을 뺀 것으로 판정. +> route 등록 판정은 문서를 동작에 맞춤). 범위 `2c8a359d..83a12f66`, 기준 커밋 `83a12f66`. 영역 표와 명령 번호는 +> [01 문서](01-transport-errors.md) 「범위」·「실행한 명령과 결과」에 있다. + +## 범위 + +### pathspec + +``` +src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ApplicationBoundaryArchitectureTest.java +src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/UserTransportTypeListsTest.java +src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ArchitectureViolationFixtureTest.java +src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/allowed/configuration +src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/configuration +docs/manual/07-authorization.md +``` + +`git diff --stat 2c8a359d..83a12f66 -- `: 14개 파일, +725 −94. `ArchitectureViolationFixtureTest`의 Flyway 부분(`6764246a`)은 +03에서 봤다. 매뉴얼 07의 이력 ID 걷어내기(`81ef58ab`)는 06에서 봤다. + +함께 읽은 주변 코드: `ApplicationBoundaryArchitectureTest`의 `SYSTEM_DRIVEN_INBOUND_PACKAGES`·`ARE_USER_TRANSPORT_TYPES`·`ARE_USER_TRANSPORTS`(`:450-680`), +websocket adapter의 STOMP 설정(`WebSocketConfig.configureClientInboundChannel`)과 그 interceptor 둘, 매뉴얼 07 「시스템이 부르는 쓰기」·「규칙이 못 보는 길」, +업그레이드 안내 B-16. + +### 수정 보고의 「새로 가정하는 것」 + +공유 노트 `r8-f2-arch-rules.md`의 칸을 옮겼다. + +| 가정 | 확인 | +|---|---| +| 1. 설정용 타입(`servlet.config.annotation`, `reactive.config`, `socket.config.annotation`, `messaging.simp.config`, `web.cors`, `RequestMethod`)의 코드는 기동 때만 돈다. 이것을 구현해 요청마다 도는 클래스(CORS source·processor)는 요청 타입을 파라미터로 받아 따로 잡힌다 | 참. CORS source·processor는 `HttpServletRequest`(`jakarta.servlet.http`)나 `ServerWebExchange`(`org.springframework.web.server`)를 받아 사용자 전송 타입으로 잡힌다. `WebMvcConfigurer`의 `addInterceptors`·`addArgumentResolvers`는 `HandlerInterceptor`·`HandlerMethodArgumentResolver`(사용자 전송 타입, 설정용 아님)를 이름에 남겨 잡힌다 | +| 2. 설정용 타입에만 의존하는 중첩 클래스는 요청 경로가 아니다 | 대체로 참. 다만 설정용 타입 `ChannelRegistration`(`messaging.simp.config`)이 받는 STOMP inbound channel interceptor는 요청(클라이언트 프레임)마다 돈다. 그 interceptor 타입은 사용자 전송 목록에 없어 이 가정과 상관없이 보이지 않는다(RR8-02-01) | +| 3. `@CrossOrigin`은 handler annotation, `HttpServletRequest`를 받는 설정 람다는 요청 처리 코드다 | 참. 거짓 실패 쪽이다 | + +### 불러온 스킬과 적용한 기준 + +| 스킬 | 기준 | 본 것 | +|---|---|---| +| `superpowers:requesting-code-review` | 주장과 구현, 테스트가 이름대로, 읽기 전용 | RR7-01-01·02 닫힘, 새 목록 셋의 경계 | +| `docs/work/reference/review-criteria.md` 7절 | 규칙 테스트가 위반·허용 fixture를 둘 다 가지나 | 새 fixture 9개(위반 5, 허용 4)와 목록 대조 테스트 | +| `docs/work/reference/defect-patterns.md` A1·A10 | 갈라진 목록, 글로만 있는 약속 | 사용자 전송 목록이 템플릿 자신의 STOMP 진입 타입을 덮는지 | + +### 실행한 명령과 결과 + +명령 A8(`:app-bootstrap:architectureTest --rerun` 포함)의 결과는 [03 문서](03-migration.md) 「실행한 명령과 결과」에 있다. 이 영역의 발견은 +탐침 없이 코드로 확인했다. STOMP channel interceptor 탐침을 쓰려 했으나 `spring-messaging`이 `architectureTestCompileClasspath`에 없다 +(`src/app-bootstrap/gradle.lockfile:364`, runtime에만 있음). lockfile을 바꾸는 탐침은 리뷰 범위를 넘어 쓰지 않았다. + +### 못 본 것 + +- JAX-RS·JSR-356 런타임 기동: 템플릿에 런타임이 없다. 규칙 판정만 봤다(묶음 보고의 fixture 테스트, E0). + +## 항목 재확인 + +| ID | 판정 | 근거 | +|---|---|---| +| RR7-01-01 (설정에 중첩된 JAX-RS 자원·`@ServerEndpoint` 회귀) | 닫힘 | `ApplicationBoundaryArchitectureTest.java:653-667`(`waysInFor`: 중첩 클래스는 `MAKE_A_NESTED_CLASS_A_WAY_IN` = 사용자 전송 목록 − 설정용), 위반 fixture `jaxrs/RunNowResourceConfigurationFixture`·`RunNowThroughTheConfigurationFixture`·`jsr356/RunNowEndpointConfigurationFixture`와 테스트 셋. 목록 대조 `UserTransportTypeListsTest` 두 테스트 | +| RR7-01-02 (메서드 참조 route 등록의 거짓 실패와 문서) | 닫힘 | 판정은 그대로, Javadoc(`:549-563`)·실패 메시지(`:801-812`)·매뉴얼 07 `:106`·B-16이 "등록도 사용자 전송"으로 맞음. 위반 fixture `RoutesBesideASystemCallerConfigurationFixture`, 허용 fixture `OrderRoutesConfigurationFixture`, CORS 두 모양 허용 fixture | +| round7 1차 Declined ①(WebFlux `WebFilter`·`WebHandler`가 중첩 클래스에서 빠짐) | 닫힘 | 중첩 클래스가 `org.springframework.web..` 전체를 보는 사용자 전송 목록으로 판정된다(`:471-481`) | + +## 결함 + +### RR8-02-01 · Minor · STOMP inbound channel interceptor(`ChannelInterceptor`)가 사용자 전송 타입이 아니어서, 클라이언트 프레임마다 도는 interceptor가 `@SystemCaller`를 불러도 잡히지 않는다 — 매뉴얼 07은 설정에 중첩된 클래스는 이 사각지대에 들지 않는다고 적는다 + +- **위치**: + - 코드: `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ApplicationBoundaryArchitectureTest.java:471-481`(`org.springframework.messaging`은 `simp`만), `:483-487`(이름 둘: `Controller`, `MessageMapping`), `:614-615`(중첩 클래스 판정), `:580-586`(`messaging.simp.config`가 설정용 타입). + - 템플릿의 같은 진입점: `src/adapter/inbound/websocket/src/main/java/dev/caskeleton/adapter/inbound/websocket/stomp/WebSocketConfig.java:92-94`(`configureClientInboundChannel`이 interceptor를 등록), `WebSocketCorrelationInterceptor`·`WebSocketInboundAuthorizationInterceptor`(`ChannelInterceptor` 구현). + - 문서: `docs/manual/07-authorization.md:133-135`("설정 안에 중첩한 클래스는 더 넓은 사용자 전송 타입 목록으로 보므로 여기에 들지 않는다"), `:84`("사용자 전송: 사용자가 보낸 요청이 들어오는 inbound adapter다(web·GraphQL·gRPC·WebSocket)"). +- **무엇이 틀렸나**: + - STOMP 클라이언트가 보낸 프레임은 모두 inbound channel interceptor를 지난다. 템플릿도 이 자리에서 인증·상관 id를 처리한다. + - interceptor 타입 `org.springframework.messaging.support.ChannelInterceptor`와 그 인자 `Message`·`MessageChannel`은 사용자 전송 목록 밖이다. 목록은 `org.springframework.messaging` 가운데 `simp`와 `@MessageMapping`만 담는다. + - 그래서 `WebSocketMessageBrokerConfigurer`를 구현한 설정이 `configureClientInboundChannel`에서 익명 `ChannelInterceptor`를 등록하고, 그 `preSend`가 `@SystemCaller`를 불러도 잡히지 않는다. 설정 자신은 설정용 타입(`ChannelRegistration`)만 쓰고, 중첩된 익명 interceptor는 목록 밖 타입만 쓴다. `simp` 타입(`StompHeaderAccessor`)을 쓰지 않는 최상위 interceptor 클래스도 같다. + - 이번 수정은 매뉴얼 07 「규칙이 못 보는 길」에 "설정 안에 중첩한 클래스는 … 여기에 들지 않는다"를 더했다. STOMP interceptor는 그 문장이 덮는다고 말하는 경우인데 잡히지 않는다. +- **발생 조건·영향**: + - 조건: 서비스가 STOMP inbound interceptor에서 작업을 부르고(예: 특정 destination의 프레임이 오면 정산 작업을 돌림), `simp` 타입을 쓰지 않는다. + - 영향: 인증만 된 WebSocket 클라이언트가 권한 검사 없는 `@SystemInvoked` 쓰기를 부른다. 빌드는 신호를 내지 않는다. + - Minor로 둔 이유: interceptor에서 작업을 부르는 모양이 드물고, 대부분의 interceptor는 `StompHeaderAccessor`를 써서 잡힌다. +- **테스트가 못 본 이유**: STOMP 쪽 fixture는 `@MessageMapping`·`WebSocketHandler`·`@ServerEndpoint` 모양만 있다. `UserTransportTypeListsTest`는 목록끼리의 관계만 본다. 목록이 각 전송의 진입 타입을 덮는지는 보지 않는다. +- **고치는 법**: + - 권장: `USER_TRANSPORT_TYPE_NAMES`에 `org.springframework.messaging.support.ChannelInterceptor`와 `org.springframework.messaging.support.ExecutorChannelInterceptor`를 더한다. 두 타입은 템플릿에서 websocket adapter만 쓴다(grep). broker listener의 `@Payload`·`@Header`를 피하려던 이유(`:463-465`)와 부딪히지 않는다. 함수형 인터페이스가 아니라 설정 자신이 람다로 쓸 수 없으므로 요청 처리기 목록에는 넣지 않아도 된다. + - 대안: 매뉴얼 07 「규칙이 못 보는 길」에 STOMP channel interceptor를 사각지대로 적고, `:135` 문장을 "목록에 든 타입에 한해"로 좁힌다. 막지 않고 리뷰에 맡긴다. + - RED 테스트 모양: 위반 fixture 둘(설정에 중첩된 익명 interceptor, `simp` 타입을 쓰지 않는 최상위 interceptor)이 `@SystemCaller`를 부르고, `83a12f66`에서 위반 0으로 실패하는 것을 본다. 허용 fixture: 같은 설정이 interceptor 없이 broker만 설정. fixture는 `spring-messaging`이 필요해 `architectureTestCompileOnly`와 lockfile을 함께 바꾼다. +- **이번 수정 / 이전부터**: 섞임. 목록의 빈칸은 이전부터다(r8-f2 보고 「범위 밖」이 같은 것을 적었다). 이번 수정이 매뉴얼에 "중첩 클래스는 사각지대에 들지 않는다"를 더했다. +- **증거**: E1 — 위 `file:line`. 탐침은 컴파일 classpath 때문에 쓰지 않았다(「실행한 명령과 결과」). + +## 18.6절에서 넘어온 항목 판정 + +| 항목 | 판정 | 근거 | +|---|---|---| +| STOMP channel interceptor 타입이 사용자 전송 목록에 없음 | 결함 → RR8-02-01 | 위 | +| 설정 클래스 자신에 직접 쓴 WebFlux `WebFilter`·`WebHandler`가 요청 처리기 목록 밖 | 결함 아님 | 매뉴얼 07 `:133-135` 「규칙이 못 보는 길」이 "설정 클래스 자신에 쓴 요청 처리 코드가 요청 처리기 타입 목록에 없는 타입으로 쓰인 경우"를 사각지대로 적고, 막는 것을 리뷰로 둔다(`:145-147`). 템플릿은 서블릿 스택이고 WebFlux가 classpath에 없다. 중첩 클래스로 둔 WebFlux 타입은 이번 수정으로 잡힌다 | + +## Declined to judge + +없다. + +## 결론 + +Critical 0, Important 0, Minor 1, 회귀 0. 결함 1건(섞임). + +- RR7-01-01·02는 닫혔다. 목록을 셋으로 나누고 대조 테스트를 둔 방법은 round7 권장안보다 r9 동작에 가깝고, 고른 이유가 커밋 본문에 있다. +- 남은 것은 사용자 전송 목록이 템플릿 자신의 STOMP 진입 타입 하나를 덮지 않는 것이다. 이번 수정의 매뉴얼 문장이 그 빈칸을 덮었다고 말한다. diff --git a/docs/reviews/2026-11-03-rereview/round8/03-migration.md b/docs/reviews/2026-11-03-rereview/round8/03-migration.md new file mode 100644 index 00000000..598604b8 --- /dev/null +++ b/docs/reviews/2026-11-03-rereview/round8/03-migration.md @@ -0,0 +1,152 @@ +# 03 마이그레이션·Flyway 규칙 round7 수정 확인 리뷰 (2026-11-07) + +> 대상: `6ec0c4f7`(RR7-03-01~05: 실패한 동시 인덱스 마이그레이션 복구 절차, 검사기 설명, ledger IT)과 `6764246a`(RR7-03-06: Flyway 규칙이 설정 +> 객체를 직접 만드는 길도 막음). 범위 `2c8a359d..83a12f66`, 기준 커밋 `83a12f66`. 영역 표는 [01 문서](01-transport-errors.md) 「범위」에 있다. + +## 범위 + +### pathspec + +``` +docs/jpa docs/runbooks/migration-failed.md docs/study docs/manual/04-persistence.md +src/adapter/outbound/persistence-jpa/build.gradle src/adapter/outbound/persistence-jpa/CLAUDE.md +src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/migration +src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest src/adapter/outbound/persistence-jpa/src/test +src/adapter/outbound/persistence-jpa/src/testFixtures src/grpc +src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/JpaProductionArchitectureTest.java +src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/allowed/persistence +src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/persistence +``` + +`git diff --stat 2c8a359d..83a12f66 -- `: 28개 파일, +747 −125. `ArchitectureViolationFixtureTest`의 Flyway 테스트 두 개는 02의 +pathspec에 들지만 여기서 봤다. 매뉴얼 04의 이력 ID 걷어내기(`81ef58ab`)는 06에서 봤다. + +함께 읽은 주변 코드: `PostgreSqlConcurrentIndexMigrationIntegrationTest` 전체(도우미 `within`·`cancelLockWaits`·`aftermath`), +`LockWaitMigrationInspector`의 `LOCKING` 패턴과 `outsideATransaction`, migration-guide 「Bound the lock wait」·「Concurrent index builds」, +`docs/jpa/runbooks.md` 「An invalid index exists」, PostgreSQL `DROP INDEX CONCURRENTLY`의 단계(아래 탐침으로 확인). + +### 수정 보고의 「새로 가정하는 것」 + +수정 보고는 repo에 없다(공유 노트 `r8-f3-persistence.md`에 이 칸이 없다). 두 커밋 본문 「위험·한계」와 README 18.4절 결정 칸에서 뽑았다. + +| 가정 | 확인 | +|---|---| +| 동시 인덱스 문장 하나만 든 마이그레이션이 실패하면, 무효 인덱스를 지우고 그 버전의 실패 행만 지운 뒤 다시 배포하면 된다(runbook 절차, 소유자 결정 (a)) | **`CREATE`·`REINDEX`에는 참, `DROP INDEX CONCURRENTLY`에는 거짓.** 실패한 drop이 남긴 무효 인덱스는 그 마이그레이션이 지우려던 인덱스다. 절차대로 지우면 재배포의 `DROP INDEX CONCURRENTLY`가 "does not exist"로 다시 실패한다(RR8-03-01, 명령 A7) | +| runbook의 `DELETE`는 한 행만 지운다 | 참. 탐침에서 1행(명령 A7). 0행이면 다시 분류하라는 안내가 있다 | +| 검사기 변경으로 새로 걸리는 파일은 PostgreSQL이 배포 때 거부하는 파일뿐이다 | 참. 바뀐 분기는 Flyway가 트랜잭션 밖에서만 돌리는 잠금 문장(`VACUUM FULL`, `REINDEX SCHEMA|DATABASE|SYSTEM`)이 `.sql.conf`의 `executeInTransaction=true`로 트랜잭션 안에 들어간 경우뿐이다(`LockWaitMigrationInspector.java:256-273`) | +| ledger 복사 파일 두 개(`ConcurrentIndexMigrationInspector`, `MigrationResource`)는 JDK만 쓴다 | 참. 두 파일의 import가 `java.*`뿐이다 | +| Flyway `Configuration`에 대입 가능한 타입의 생성자 접근을 막으면 직접 만든 설정이 모두 걸린다 | 참으로 봤다. 하위 클래스의 생성자도 상위 생성자를 부른다. 리플렉션·`configuration(Map)`으로 잠금 값을 덮는 길은 커밋 본문이 한계로 적었다 | + +### 불러온 스킬과 적용한 기준 + +| 스킬 | 기준 | 본 것 | +|---|---|---| +| `superpowers:requesting-code-review` | 주장과 구현, 읽기 전용 | RR7-03-01~06 닫힘, runbook 절차가 범위로 적은 세 문장 모두에서 맞는지 | +| `docs/work/reference/review-criteria.md` 1절 「운영자에게 틀린 조치를 시키는 문서」 | 문서대로 실행한 결과 | runbook SQL을 runbook에서 읽어 실 PostgreSQL에서 그대로 돌림 | +| `docs/work/improve.md` 4.1절 5단계(탐침) | 코드 읽기로 정해지지 않는 동작은 별도 worktree 탐침으로 | `DROP INDEX CONCURRENTLY`가 기다리다 취소되면 무엇을 남기는지(무효 표시가 먼저 커밋되는지) | + +### 실행한 명령과 결과 + +명령 번호는 여섯 영역 문서가 같이 쓴다(A1·A2는 01, A3~A6은 04). desktop `~/workspace/r8-review-a`(`83a12f66` + 탐침), 공유 잠금, +`--no-build-cache`, 로그 `~/r8-review-a-logs/`. + +| # | 명령 | 결과 | 시간 | 직전 부하(1분) | +|---|---|---|---|---| +| A7 | `:adapter:outbound:persistence-jpa:postgresqlConcurrentIndexMigrationIntegrationTest --tests '*PostgreSqlConcurrentIndexMigrationIntegrationTest.rr8probe*'` | rc=0. 결과는 아래 표 | 36초 | 2.27 | +| A8 | `:shared-contract:test --rerun :application-core:test --rerun :adapter:inbound:web:test --rerun :adapter:inbound:graphql:test --rerun :adapter:inbound:grpc:test --rerun :adapter:inbound:websocket:test --rerun :adapter:outbound:httpclient:test --rerun :adapter:outbound:cache-redis:test --rerun :adapter:outbound:persistence-jpa:test --rerun :app-bootstrap:architectureTest --rerun --continue` | 아래 「A8 결과」 | — | — | + +탐침 `rr8probeAFailedConcurrentDropRecoveredByTheRunbook`(기존 lane 클래스에 넣은 메서드, 공유 노트 `r8-review-a-probes/drop-index-probe.java.txt`): +V1이 표를 만들고 `ix_probe_id`를 만든다. 다른 연결이 그 표를 읽은 채 트랜잭션을 열어 둔다. V2 `DROP INDEX CONCURRENTLY ix_probe_id`(`.sql.conf` +`executeInTransaction=false`)를 템플릿 Flyway로 배포하고, 기존 도우미 `within`이 30초 뒤 잠금 대기를 취소한다. 그다음 runbook의 SQL 세 블록을 +runbook 파일에서 읽어(`OutboxRunbookSql`) 차례로 돌리고 다시 배포한다. + +| 단계 | 결과 | +|---|---| +| 배포 | 30초 안에 끝나지 않아 취소. `57014 canceling statement due to user request` | +| 실패 뒤 | `indexes [ix_probe_id false, probe_pkey true], history [1 true, 2 false]` — 무효 인덱스 + 실패 행 | +| runbook 1단계(빌드 확인) | 0행 | +| runbook 2단계(무효 인덱스 drop) 뒤 | `indexes [probe_pkey true]` | +| runbook 4단계(실패 행 delete) | 1행 | +| runbook 5단계(다시 배포) | 실패. `42704 ERROR: index "ix_probe_id" does not exist` | +| 다시 배포 뒤 | `history [1 true, 2 false]` — 처음과 같은 막힌 상태 | + +#### A8 결과 + +rc=0, 1분 52초, 직전 부하 1.57. `175 actionable tasks: 122 executed, 53 up-to-date`, FROM-CACHE 0. 테스트 태스크 10개가 모두 실행됐다(로그 `> Task` 줄). +결과 XML 합계(탐침 포함, 실패·오류 0): + +| leaf | 테스트 | skip | +|---|---|---| +| shared-contract `test` | 269 | 0 | +| application-core `test` | 426(탐침 3) | 19(in-memory fake 시간 케이스, 이전부터) | +| web `test` | 341 | 0 | +| graphql `test` | 405(탐침 1) | 0 | +| grpc `test` | 74 | 0 | +| websocket `test` | 105 | 0 | +| httpclient `test` | 360 | 0 | +| cache-redis `test` | 228(탐침 3) | 0 | +| persistence-jpa `test` | 666 | 0 | +| app-bootstrap `architectureTest` | 242 | 0 | + +A9 `-p build-logic test --rerun`: rc=0, 41초, 직전 부하 5.13, 173건 실패·skip 0(05 영역). + +### 못 본 것 + +- ledger optional 빌드의 lane(`-p optional-platforms … integrationTest`): 묶음 보고의 실행(E0)만 있다. 바뀐 코드는 IT 도우미라 다시 돌리지 않았다. +- `REINDEX … CONCURRENTLY` 실패의 복구: `_ccnew` 인덱스가 남고 원래 인덱스는 살아 있어 2단계가 맞는 조치다. 코드로만 봤다. + +## 항목 재확인 + +| ID | 판정 | 근거 | +|---|---|---| +| RR7-03-01 (ledger IT의 없는 예외 목록) | 닫힘 | `GrpcOperationLedgerMigrationLockWaitIT.java`의 `RUN_OUTSIDE_A_TRANSACTION`과 그 목록을 가이드에 묶는 테스트, 파일마다 따로 실행하는 `GrpcOperationLedgerMigrations.before` | +| RR7-03-02 (REINDEX 다섯 형태 설명) | 닫힘 | 가이드 `:80-91`·`:136-141`, 검사기 Javadoc, 학습 문서 8.2절이 "SCHEMA·DATABASE는 Flyway가 트랜잭션 밖, INDEX·TABLE CONCURRENTLY는 안"으로 같다 | +| RR7-03-03 (실패 행 때문에 다음 배포가 막힘) | 부분 | `CREATE [UNIQUE] INDEX CONCURRENTLY`는 runbook 절차로 복구된다(기존 IT). `DROP INDEX CONCURRENTLY`는 같은 절차로 다시 막힌다(RR8-03-01) | +| RR7-03-04 ("섞인 파일은 부분 적용되지 않는다") | 닫힘 | 설정 없음/`executeInTransaction=false` 두 경우를 IT가 고정, 문서가 두 경우를 나눠 적음 | +| RR7-03-05 (`executeInTransaction=true` + `VACUUM FULL` 통과) | 닫힘 | `LockWaitMigrationInspector.java:256-273`(트랜잭션 안에서 돌 수 없는 문장은 `.sql.conf`와 상관없이 거부), 테스트 2건 | +| RR7-03-06 (Flyway 설정 객체 직접 생성) | 닫힘 | `JpaProductionArchitectureTest`의 `EVERY_FLYWAY_STARTS_FROM_THE_SCHEMA_POLICY`(생성자 접근 규칙), 위반 fixture 4개·허용 fixture 1개 | + +## 결함 + +### RR8-03-01 · Important · 실패한 `DROP INDEX CONCURRENTLY` 마이그레이션에 runbook 복구 절차를 그대로 따르면 재배포가 "index does not exist"로 다시 실패해 같은 막힌 상태로 돌아간다 + +- **위치**: + - 문서: `docs/runbooks/migration-failed.md:115-120`(이 절의 대상에 `DROP INDEX CONCURRENTLY`를 넣음), `:132-133`(2단계 "Drop the invalid index the build left"), `:154`(5단계 "Flyway runs the same migration from the start and builds the index"). + - 같은 절차를 가리키는 곳: `docs/jpa/migration-guide.md:168-173`, `docs/jpa/runbooks.md:76-80`, `docs/study/postgresql-jpa-walkthrough.ko.md:1381-1383`, `ConcurrentIndexMigrationInspector.java:23-30`·`:107-115`(Javadoc과 실패 메시지). + - 테스트: `PostgreSqlConcurrentIndexMigrationIntegrationTest.aFailedConcurrentIndexMigrationIsRecoveredByTheRunbookProcedure`는 `CREATE UNIQUE INDEX CONCURRENTLY` 한 경우만 돌린다. +- **무엇이 틀렸나**: + - `DROP INDEX CONCURRENTLY`는 인덱스를 먼저 무효로 표시해 커밋하고, 그 표를 쓰는 트랜잭션이 끝나기를 기다린 뒤 지운다. 기다리는 중에 취소·`statement_timeout`·`lock_timeout`으로 실패하면 그 인덱스는 무효로 남고 Flyway는 실패 행을 남긴다(탐침 「실패 뒤」). + - runbook 2단계는 그 무효 인덱스를 지우라고 한다. 그 인덱스가 바로 마이그레이션이 지우려던 인덱스다. 4단계로 실패 행을 지우고 5단계로 다시 배포하면, 같은 `DROP INDEX CONCURRENTLY ix_probe_id`가 "does not exist"(`42704`)로 실패하고 실패 행이 다시 생긴다(탐침 「다시 배포 뒤」). + - 5단계 문장 "builds the index"는 drop 마이그레이션에 맞지 않는다. 절의 범위 문장(`:117-118`)은 drop을 대상에 넣는다. +- **발생 조건·영향**: + - 조건: 서비스가 쓰지 않는 인덱스를 `DROP INDEX CONCURRENTLY `(`IF EXISTS` 없이) 마이그레이션으로 지운다. 배포가 오래 열린 트랜잭션(보고서 쿼리, 운영자가 열어 둔 `BEGIN`) 뒤에서 기다리다 취소된다. 가이드도 "오래 열린 트랜잭션이 빌드를 잡는다"고 적을 만큼 흔한 상황이다. + - 영향: P1 runbook을 따른 운영자가 같은 실패를 되풀이한다. 새 릴리스는 계속 기동하지 못한다. runbook은 0행이면 다시 분류하라고만 하고, 이 경우를 다루지 않는다. 운영자가 결국 "이력을 고치지 않는다"의 예외를 넓히거나 마이그레이션 파일을 고치는 쪽(둘 다 금지)으로 밀린다. + - Important로 둔 이유: 운영자에게 틀린 조치를 시키는 runbook이고, 문서대로 실 PostgreSQL에서 실행해 재현했다. +- **테스트가 못 본 이유**: runbook을 실행하는 IT가 unique `CREATE` 실패 한 경우만 본다. 절의 범위는 `CREATE`·`DROP`·`REINDEX` 셋이다. +- **고치는 법**: + - 권장: runbook 2단계를 문장 종류로 나눈다. 실패한 마이그레이션이 `CREATE`·`REINDEX`면 남은 무효 인덱스(`REINDEX`면 `_ccnew`)를 지운다. `DROP INDEX CONCURRENTLY`면 지우지 않는다 — 다시 배포한 같은 문장이 무효 인덱스를 지운다. 5단계 문장도 "runs the same statement again"으로 고친다. 가이드·학습 문서·검사기 메시지의 한 줄 요약도 같이 고친다. IT에 탐침 모양(drop을 기다리게 한 뒤 취소)을 더해 고친 절차로 재배포가 성공하는지 본다. + - 대안: 가이드와 `ConcurrentIndexMigrationInspector`가 `DROP INDEX CONCURRENTLY`에 `IF EXISTS`를 요구한다. 그러면 지금 절차도 통한다. 이미 배포된 파일은 고칠 수 없어, 새 파일부터만 지켜진다. + - RED 테스트 모양: 탐침 `rr8probeAFailedConcurrentDropRecoveredByTheRunbook`을 단언으로 바꾼다(재배포 뒤 `history [1 true, 2 true]`). `83a12f66`의 runbook으로는 `42704`로 실패한다. +- **이번 수정 / 이전부터**: 이번 수정. 이 runbook 절은 `6ec0c4f7`이 새로 만들었다. +- **증거**: E3 — 명령 A7(runbook SQL을 runbook 파일에서 읽어 실 PostgreSQL에서 그대로 실행). + +### RR8-03-02 · Minor · 동시 인덱스 IT의 Javadoc이 runbook에 없는 절 이름("A concurrent index migration failed")을 가리킨다 + +- **위치**: `src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlConcurrentIndexMigrationIntegrationTest.java:65-66`. 실제 절 제목은 `docs/runbooks/migration-failed.md:113` "Recover a failed concurrent index migration"이다. +- **무엇이 틀렸나**: 클래스 Javadoc이 runbook의 `("A concurrent index migration failed")` 절을 읽는다고 적는다. 그런 제목은 없다. 비슷한 말은 Diagnosis 목록의 한 줄(`:66`, 소문자)뿐이다. 다른 문서(가이드, 검사기, `docs/jpa/runbooks.md`)는 모두 올바른 제목을 쓴다. +- **발생 조건·영향**: 테스트를 읽고 runbook 절을 찾는 사람이 틀린 이름으로 찾는다. 동작 영향은 없다. +- **테스트가 못 본 이유**: Javadoc의 인용은 검사 대상이 아니다. +- **고치는 법**: Javadoc을 `"Recover a failed concurrent index migration"`으로 고친다. RED 없음(문구). +- **이번 수정 / 이전부터**: 이번 수정. +- **증거**: E1 — 위 `file:line`. + +## Declined to judge + +없다. + +## 결론 + +Critical 0, Important 1, Minor 1, 회귀 0. 결함 2건, 모두 이번 수정이 만들었다. + +- RR7-03-01·02·04·05·06은 닫혔다. 검사기 변경과 Flyway 규칙은 주장대로 동작하고 위반·허용 fixture를 둘 다 가진다. +- RR7-03-03은 부분이다. 새 runbook 절차는 `CREATE` 실패에는 맞지만, 절이 대상으로 넣은 `DROP INDEX CONCURRENTLY` 실패에는 같은 막힌 상태로 돌아간다. diff --git a/docs/reviews/2026-11-03-rereview/round8/04-idempotency.md b/docs/reviews/2026-11-03-rereview/round8/04-idempotency.md new file mode 100644 index 00000000..6d4480ba --- /dev/null +++ b/docs/reviews/2026-11-03-rereview/round8/04-idempotency.md @@ -0,0 +1,138 @@ +# 04 멱등 저장소 round7 수정 확인 리뷰 (2026-11-07) + +> 대상: `14435106`(RR7-02-02와 멱등 남은 차이 3건: 이미 적용된 전이는 그 전이를 적용한 핸들에게만 "이미 처리됨"으로 확인). +> 범위 `2c8a359d..83a12f66`, 기준 커밋 `83a12f66`. 영역 표는 [01 문서](01-transport-errors.md) 「범위」에 있다. + +## 범위 + +### pathspec + +``` +src/application-core/src/main/java/dev/caskeleton/application/idempotency src/application-core/src/testFixtures +src/application-core/CLAUDE.md src/adapter/outbound/cache-redis src/adapter/outbound/redis-runtime +src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/idempotency docs/testing +``` + +`git diff --stat 2c8a359d..83a12f66 -- `: 12개 파일, +382 −61. 공통 문서(application-core·persistence-jpa README, 업그레이드 +안내 5절, 결정 색인 2.4절)의 이 커밋 행도 읽었다. + +함께 읽은 주변 코드: Redis `TRANSITION` 스크립트 전체(`IdempotencyScripts.java:130-200`)와 `RedisIdempotencyStoreAdapter`의 결과 변환, +`PostgreSqlIdempotencyStore`의 `markFailed`·`replayVerdict`·`appliedFrom`, `InMemoryIdempotencyStore` 전체, `IdempotencyExecutor`가 시작 결과를 쓰는 곳 +(`:192-196`), 결과 enum 넷의 Javadoc. + +### 수정 보고의 「새로 가정하는 것」 + +공유 노트 `r8-f4-idempotency.md`에 이 칸이 없다. 노트 「정한 규칙」·「범위 밖」과 커밋 본문 「위험·한계」, README 18.6절에서 뽑았다. + +| 가정 | 확인 | +|---|---| +| "적용한 핸들" = owner identity가 같고 기록보다 revision이 하나 낮은 핸들. 이것으로 다섯 전이의 재전송을 가른다 | 전이 **종류**를 함께 보지 않는 곳이 있다. Redis는 start 재전송에 기록 상태(`EXECUTING`)와 revision만 본다. renew를 적용한 핸들이 start를 보내면 "이미 시작됨"이다(RR8-04-02) | +| 템플릿 호출자(`IdempotencyExecutor`)는 넘겨받기 전 핸들로 다시 보내지 않고 renew·release를 부르지 않아 HTTP 동작은 같다 | 참. `IdempotencyExecutor`에 `renew`·`releaseBeforeExecution` 호출이 없다(grep). 아래 두 결함은 포트를 직접 부르는 코드에서만 드러난다 | +| 적용한 핸들의 markFailed 재전송이 다른 retention·disposition이면 저장소마다 답이 다르고 Javadoc과도 다르다(커밋 본문 「위험·한계」, 범위 밖으로 남김) | 참. 명령 A3~A6이 세 저장소(실 Redis·실 PostgreSQL 포함)에서 확인했다(RR8-04-01) | + +### 불러온 스킬과 적용한 기준 + +| 스킬 | 기준 | 본 것 | +|---|---|---| +| `superpowers:requesting-code-review` | 주장과 구현, 읽기 전용 | 결정 「넘겨받기 전 핸들의 재전송」이 세 저장소에 같게 들어갔는지 | +| `docs/work/reference/review-criteria.md` 7절 「fake와 공유 계약」 | fake와 실제 adapter가 같은 계약을 상속, 계약 밖 동작은 결함 | 계약에 없는 재전송 모양에서 세 저장소의 답 | +| `docs/work/reference/defect-patterns.md` A6(계약 밖 fake) | fake가 실제와 갈라짐 | fake가 Redis 쪽으로 맞춰지며 PostgreSQL과 갈라진 곳 | + +### 실행한 명령과 결과 + +탐침 세 메서드를 공유 계약 `IdempotencyStoreContract`(testFixtures)에 넣어 네 하위 클래스가 모두 돌게 했다(공유 노트 +`r8-review-a-probes/idempotency-probe.java.txt`). 각 메서드는 결과를 단언하지 않고 파일 `rr8-idempotency.txt`에 적는다. desktop +`~/workspace/r8-review-a`(`83a12f66` + 탐침), 공유 잠금, `--no-build-cache`, 로그 `~/r8-review-a-logs/`. + +| # | 명령 | 저장소 | rc | 시간 | 직전 부하(1분) | +|---|---|---|---|---|---| +| A3 | `:application-core:test --tests '*InMemoryIdempotencyStoreContractTest'` | in-memory fake | 0 | 9초 | 2.68 | +| A4 | `:adapter:outbound:cache-redis:test --tests '*.RedisIdempotencyStoreContractTest'` | Redis 명령 fake(Lua의 Java 사본) | 0 | 9초 | 2.89 | +| A5 | `:adapter:outbound:cache-redis:redisContainerContractTest` | 실 Redis(Testcontainers, `LiveRedisIdempotencyStoreContractTest`) | 0 | 78초 | 3.30 | +| A6 | `:adapter:outbound:persistence-jpa:jpaPlatformContractTest --tests '*PostgreSqlIdempotencyStoreContractTest'` | 실 PostgreSQL | 0 | 68초 | 1.47 | + +| 탐침 | fake | Redis 명령 fake | 실 Redis | 실 PostgreSQL | Javadoc이 말하는 답 | +|---|---|---|---|---|---| +| 적용한 핸들이 markFailed를 같은 disposition·**다른 retention**(1시간 → 2시간)으로 다시 보냄 | `ALREADY_MARKED_SAME_OPERATION` | `ALREADY_MARKED_SAME_OPERATION` | `ALREADY_MARKED_SAME_OPERATION` | `OPERATION_CONFLICT` | `OPERATION_CONFLICT` | +| 적용한 핸들이 markFailed를 **다른 disposition**(`NO_EFFECT_RETRYABLE` → `EFFECT_UNKNOWN_ABANDONED`)으로 다시 보냄 | `NOT_OWNER` | `NOT_OWNER` | `NOT_OWNER` | `NOT_OWNER` | `OPERATION_CONFLICT` | +| 시작한 핸들로 renew(`RENEWED`)한 뒤 **같은 핸들로 start** | `NOT_OWNER` | `ALREADY_STARTED_SAME_OPERATION` | `ALREADY_STARTED_SAME_OPERATION` | `NOT_OWNER` | `NOT_OWNER`(이 핸들이 적용한 start가 아니다) | + +A8(application-core·cache-redis·persistence-jpa `test` 포함)은 [03 문서](03-migration.md) 「A8 결과」에 있다. + +### 못 본 것 + +- Redis 클러스터·sentinel 위상: 탐침은 standalone 실 Redis만 봤다. 판정은 스크립트 하나 안에서 끝나 위상과 상관없다고 봤다(E1). + +## 항목 재확인 + +| ID | 판정 | 근거 | +|---|---|---| +| RR7-02-02 (fake가 적용한 핸들의 재전송에 `NOT_OWNER`) | 닫힘 | `InMemoryIdempotencyStore`가 마지막 전이와 그 핸들·인자를 기억한다(`Applied`, `repeats`). 계약 케이스 `aStartResentThroughTheHandleItWasAppliedFrom…`·`aRenewalResent…`·`aFailureResentThroughTheHandleItWasAppliedFromIsConfirmed`가 네 저장소에서 통과(A3~A6, 계약 전체 실행) | +| 넘겨받기 전 핸들의 complete·markFailed 재전송 → `NOT_OWNER` | 닫힘 | Redis `TRANSITION`의 ALREADY 조건이 `rev == handle rev + 1`만(`IdempotencyScripts.java:164`), PostgreSQL `replayVerdict`·complete가 `appliedFrom`을 봄. 계약 케이스 둘 | +| release한 핸들의 start(`ABSENT`·`NOT_OWNER` 둘 다) | 닫힘 | `IdempotencyStartOutcome` Javadoc, 계약 케이스가 다음 claim의 시작까지 본다 | + +## 결함 + +### RR8-04-01 · Minor · 적용한 핸들이 markFailed를 다른 retention이나 disposition으로 다시 보내면 세 저장소의 답이 서로, 그리고 포트 Javadoc과 다르다 — 이번 수정이 fake를 Redis 쪽으로 옮겨 PostgreSQL과 갈라졌다 + +- **위치**: + - 포트 Javadoc: `src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyFailOutcome.java:18-23`(`OPERATION_CONFLICT`: "this failure was already recorded with another disposition or retention"). + - fake: `src/application-core/src/testFixtures/java/dev/caskeleton/application/idempotency/testkit/InMemoryIdempotencyStore.java:190-194`(disposition만 비교, 다른 disposition은 "as in the stores" `NOT_OWNER`). + - Redis: `src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/idempotency/IdempotencyScripts.java:148-166`(기록 상태와 revision만 비교, retention은 기록에 없음), `RedisIdempotencyStoreAdapter.java:294`. + - PostgreSQL: `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/idempotency/postgresql/PostgreSqlIdempotencyStore.java:336-355`(전이 종류가 disposition마다 다르고, digest에 retention이 든다). + - 계약: `IdempotencyStoreContract`에 이 두 모양의 케이스가 없다. +- **무엇이 틀렸나**: + - 다른 retention: fake와 Redis는 retention을 기억하지 않아 "이미 처리됨"(`ALREADY_MARKED_SAME_OPERATION`), PostgreSQL은 digest가 달라 `OPERATION_CONFLICT`다. Javadoc은 `OPERATION_CONFLICT`라고 적는다. + - 다른 disposition: 세 저장소 모두 `NOT_OWNER`다(기록 상태나 전이 종류가 달라 재전송으로 보지 않고 revision 검사로 내려간다). Javadoc은 `OPERATION_CONFLICT`라고 적는다. + - 이번 수정 전 fake는 적용한 핸들의 재전송을 모두 `NOT_OWNER`로 답했다. 이번 수정이 disposition만 기억하게 해 다른 retention에 Redis와 같은 "이미 처리됨"을 준다. fake 주석은 다른 disposition을 "as in the stores"라고 적지만, 그 답은 포트 Javadoc과 다르다. 이 결정은 결정 색인에 없다. +- **발생 조건·영향**: + - 조건: 포트를 직접 부르는 코드가 응답을 잃은 markFailed를 다른 retention이나 disposition으로 다시 보낸다(예: 재시도 사이에 설정을 다시 읽음, 실패를 다시 분류함). 템플릿 executor는 같은 값으로만 보낸다. + - 영향: 같은 호출에 저장소를 바꾸면 답이 바뀐다. "이미 처리됨"을 받은 호출자는 자기가 정한 retention이 기록된 줄 안다. fake로 테스트한 서비스는 PostgreSQL에서 다른 답을 받는다(fake가 계약 밖으로 갈라진 A6 모양). + - Minor로 둔 이유: 템플릿 호출 경로에는 없고, 데이터 손상 없이 답의 이름만 다르다. +- **테스트가 못 본 이유**: 공유 계약은 같은 인자의 재전송과 다른 lease의 renew 재전송만 본다. markFailed의 인자 차이 케이스가 없다. +- **고치는 법**: + - 권장: 계약을 하나로 정하고 공유 계약 케이스 둘을 더한다. 안: 다른 disposition은 `OPERATION_CONFLICT`(Javadoc대로, 세 저장소 모두 바꿈), 다른 retention은 "이미 처리됨"(retention은 이미 기록된 실패의 보관 기간이라 결과를 바꾸지 않는다 — Javadoc과 PostgreSQL digest에서 retention을 뺌). 이렇게 하면 Redis 기록 모양(Lua)을 바꾸지 않는다. 계약을 적은 곳끼리 다르고 결정이 없으므로 `docs/work/improve.md` 7절대로 고치기 전에 소유자에게 묻는다. + - 대안: Javadoc을 지금 동작에 맞춘다(다른 disposition은 `NOT_OWNER`, 다른 retention은 저장소마다 다름을 명시). 계약 케이스는 `isIn(...)`으로 둔다. 갈라짐을 그대로 문서화하는 것이라 A6 모양이 남는다. + - RED 테스트 모양: 공유 계약에 두 케이스를 정한 답으로 더한다. `83a12f66`에서 탐침 표의 칸대로 저장소 일부가 실패한다. +- **이번 수정 / 이전부터**: 섞임. Redis·PostgreSQL의 답과 Javadoc의 불일치는 이전부터다. fake가 다른 retention에 "이미 처리됨"을 주게 된 것은 이번 수정이다. r8-f4 보고 「범위 밖」 1과 README 18.6절이 같은 것을 적었다. +- **증거**: E3 — 명령 A3~A6(실 Redis·실 PostgreSQL 포함). 코드 경로는 E1. + +### RR8-04-02 · Minor · Redis는 renew를 적용한 핸들이 start를 보내도 "이미 시작됨"으로 답해, 그 답을 받은 호출자가 작업을 다시 실행한다 — fake와 PostgreSQL은 `NOT_OWNER`다 + +- **위치**: + - Redis: `IdempotencyScripts.java:148-166`(`state == toState`이고 `rev == handle rev + 1`이면 ALREADY. 마지막 전이가 무엇이었는지 보지 않음), `RedisIdempotencyStoreAdapter.java:175`(ALREADY → `ALREADY_STARTED_SAME_OPERATION`). 명령 fake `InMemorySemanticRedisCommands.java:287`도 같다. + - 포트 Javadoc: `IdempotencyStartOutcome.java:7-14`("This exact start — from the handle presented — was already applied"). + - 호출자: `src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyExecutor.java:194-195`(`STARTED`와 `ALREADY_STARTED_SAME_OPERATION`이 같은 분기로 action을 실행). +- **무엇이 틀렸나**: + - 호출자가 시작한 핸들 h(revision r)로 renew하면 기록은 `EXECUTING`·revision r+1이 된다. 그 뒤 같은 h로 start를 보내면 Redis는 기록 상태가 start의 목표 상태(`EXECUTING`)와 같고 revision이 h보다 하나 높다는 것만 보고 "이미 시작됨"이라 답한다. 그 revision을 만든 것은 start가 아니라 renew다. + - fake와 PostgreSQL은 마지막 전이 종류(RENEW)를 보고 재전송이 아니라고 판정해 `NOT_OWNER`로 답한다(탐침 셋째 행). + - 이번 수정의 규칙("이미 적용된 전이는 그 전이를 적용한 핸들에게만")은 Redis에서 전이 종류 없이 revision 차이로만 구현돼, 같은 상태에 머무는 전이(renew) 뒤의 start를 구별하지 못한다. +- **발생 조건·영향**: + - 조건: 포트를 직접 쓰는 호출자가 긴 작업에 renew를 쓰고, start 응답을 잃었다고 보고 같은 핸들로 start를 다시 보낸다. 템플릿 executor는 renew를 부르지 않는다. + - 영향: 호출자는 "이미 시작됨"을 자기 start의 확인으로 받고 action을 실행한다. 이미 실행 중인 작업이 한 번 더 돈다. round6 RR6-02-01이 막으려던 중복 실행과 같은 모양이다. + - Minor로 둔 이유: 템플릿 호출 경로에는 없고, 호출자가 시작 응답을 받은 핸들로 renew까지 한 뒤 start를 다시 보내는 드문 순서가 필요하다. +- **테스트가 못 본 이유**: 공유 계약의 start 재전송 케이스는 start 바로 뒤의 재전송만 본다. renew가 끼어든 순서가 없다. +- **고치는 법**: + - 권장: Redis 기록에 마지막 전이 종류를 남기고(`HSET … 'lastKind'`), ALREADY 조건에 "마지막 전이가 이 전이"를 더한다. renew는 이미 `renewedFromRev`를 따로 남기므로(`:245`), 같은 방식으로 start·complete·fail도 적는다. 명령 fake를 같이 고친다. + - 대안: `TRANSITION`의 start 분기만 "기록에 `renewedFromRev`가 있으면 ALREADY가 아니다"로 막는다. 지금 유일한 같은 상태 전이가 renew라서 충분하지만, 같은 상태 전이가 늘면 다시 갈라진다. + - RED 테스트 모양: 탐침 셋째를 공유 계약 케이스로 옮긴다(renew 뒤 같은 핸들의 start → `NOT_OWNER`). `83a12f66`에서 Redis 명령 fake와 실 Redis가 `ALREADY_STARTED_SAME_OPERATION`으로 실패한다. +- **이번 수정 / 이전부터**: 이전부터. start의 ALREADY 조건은 round6부터 `rev == handle rev + 1`이었다. r8-f4 보고 「범위 밖」 2와 README 18.6절이 같은 것을 적었다. +- **증거**: E3 — 명령 A4·A5(Redis 명령 fake와 실 Redis), A3·A6(fake·실 PostgreSQL 비교). + +## 18.6절에서 넘어온 항목 판정 + +| 항목 | 판정 | 근거 | +|---|---|---| +| 적용한 핸들의 markFailed를 다른 retention으로 다시 보낼 때 저장소·Javadoc 불일치 | 결함 → RR8-04-01 | 명령 A3~A6 | +| Redis TRANSITION의 start ALREADY가 전이 종류를 보지 않음 | 결함 → RR8-04-02 | 명령 A3~A6 | + +## Declined to judge + +없다. + +## 결론 + +Critical 0, Important 0, Minor 2, 회귀 0. 결함 2건: 섞임 1건, 이전부터 1건. + +- RR7-02-02와 멱등 남은 차이 3건은 닫혔다. 새 계약 케이스 10개가 네 저장소에서 같다. +- 남은 둘은 같은 원인의 다른 모양이다. "적용한 핸들"을 revision 하나로만 가려, 인자가 다른 재전송(RR8-04-01)과 같은 상태에 머무는 전이 뒤의 재전송(RR8-04-02)에서 저장소가 갈라진다. diff --git a/docs/reviews/2026-11-03-rereview/round8/05-build-logic-httpclient.md b/docs/reviews/2026-11-03-rereview/round8/05-build-logic-httpclient.md new file mode 100644 index 00000000..021a668f --- /dev/null +++ b/docs/reviews/2026-11-03-rereview/round8/05-build-logic-httpclient.md @@ -0,0 +1,79 @@ +# 05 build-logic·httpclient·작은 문서 round7 수정 확인 리뷰 (2026-11-07) + +> 대상: `6cd5e925`(RR7-05-01: `paths` 필터 trigger로만 도는 workflow를 단계 실행으로 세지 않음), `a490c20f`(태그 push·`release`로만 도는 +> workflow는 `releaseCheck`에만 셈), `c746f980`(RR7-02-01: interrupt된 스레드의 `close()`도 drain 스레드 종료를 기다림), `eab82df1`(깨진 상대 +> 링크 셋), `ac3c6a81`(`AGENTS.md` 커밋 예외 문장). 범위 `2c8a359d..83a12f66`, 기준 커밋 `83a12f66`. 영역 표는 [01 문서](01-transport-errors.md) +> 「범위」에 있다. + +## 범위 + +### pathspec + +``` +src/build-logic src/adapter/outbound/httpclient AGENTS.md src/README.md +src/adapter/outbound/fileserver/README.md src/adapter/outbound/objectstorage/README.md +``` + +`git diff --stat 2c8a359d..83a12f66 -- `: 11개 파일, +547 −100. 업그레이드 안내 B-36 행과 결정 색인 2.7절의 두 행도 읽었다. + +함께 읽은 주변 코드: `WorkflowGradleInvocations`의 trigger 판독 전체(`triggers`·`blockTriggers`·`flowTrigger`·`start`·`flow`)와 `StrictLaneStagesPlugin.problems` +(`Invocation.executes`를 부르는 유일한 곳), `ClientRuntimeRegistry`의 `close`·`stopDrainThread`·drain 스케줄러 생성. + +### 수정 보고의 「새로 가정하는 것」 + +공유 노트 `r8-f5-small-fixes.md` 「정한 기본값」과 두 커밋 본문 「위험·한계」에서 뽑았다. + +| 가정 | 확인 | +|---|---| +| `branches`·`branches-ignore` 없이 `tags`·`tags-ignore`만 단 `push`는 branch push로 시작하지 않는다 | 참. GitHub Actions는 ref 종류 하나에만 필터를 달면 다른 종류의 이벤트로는 workflow를 시작하지 않는다. 판독기는 그 조합만 `RELEASE`로 본다(`WorkflowGradleInvocations.java` `Trigger.of`) | +| `tags`와 `paths`를 함께 단 push는 어느 단계에도 세지 않는다(거짓 실패 쪽) | 참. `flow`가 `paths` 필터를 태그보다 먼저 보아 `PATH_FILTERED`가 된다. 거짓 통과는 없다 | +| 이 repo의 `release.yml`이 부르는 `-p optional-platforms integrationCheck`는 이제 세지 않아도 `integration-main.yml`이 같은 단계를 돈다 | 참. `integration-main.yml`의 그 명령은 필터 없는 `push`(main)·`schedule` workflow에 있다(grep) | +| `Invocation.executes`·`whyNotExecuting`의 두 인자 판정을 모든 호출자가 쓴다 | 참. `StrictLaneStagesPlugin.java:165`·`:236` 두 곳뿐이고 둘 다 단계 이름을 넘긴다 | +| interrupt된 `close()`는 최대 5초까지 막힐 수 있다 | 참. 마감은 처음 한 번 잡고(`ClientRuntimeRegistry.java:184`), 다시 기다릴 때도 같은 마감을 쓴다. 마감이 지나면 `IllegalStateException`이다. `awaitTermination`이 interrupt를 던지면 flag가 지워져 다음 대기는 바로 끝나지 않는다 | + +### 불러온 스킬과 적용한 기준 + +| 스킬 | 기준 | 본 것 | +|---|---|---| +| `superpowers:requesting-code-review` | 주장과 구현, 읽기 전용 | 세 항목 닫힘, trigger 조합별 판정 | +| `docs/work/reference/gates.md` 6절 「거짓 통과」 | 게이트가 막겠다는 것을 막는가 | 새 `RELEASE`·`PATH_FILTERED` 분기가 다른 trigger를 세는 쪽으로 잘못 넓히는 경우 | + +### 실행한 명령과 결과 + +| # | 명령 | 대상 | 결과 | 시간 | 직전 부하(1분) | +|---|---|---|---|---|---| +| A9 | `-p build-logic test --rerun` | `83a12f66` + 탐침(build-logic에는 탐침 없음) | rc=0, 173건 실패·skip 0, FROM-CACHE 0 | 41초 | 5.13 | +| A8 | httpclient `test --rerun` 포함 | 같음 | rc=0, httpclient 360건 실패 0([03 문서](03-migration.md) 「A8 결과」) | — | — | + +trigger 조합은 코드로 따라갔다. 따라간 조합: `pull_request` + `paths`(PATH_FILTERED), `push: tags`(RELEASE), `push: tags` + `paths`(PATH_FILTERED), +`release` + `workflow_dispatch`(RELEASE), `push: tags` + 필터 없는 `pull_request`(CHANGE), `schedule` + `push: paths`(CHANGE), +`workflow_call`만 있고 RELEASE caller만 부름(RELEASE), `push: branches: [main]`(CHANGE). + +### 못 본 것 + +- 실제 GitHub runner의 trigger 동작: 판독기는 workflow 파일만 읽는다. GitHub 문서의 필터 규칙과 대조했다(E1). +- interrupt된 채 5초 마감을 넘기는 `close()` 경로: 테스트가 없다(커밋 본문이 적음). 코드로만 봤다. + +## 항목 재확인 + +| ID | 판정 | 근거 | +|---|---|---| +| RR7-05-01 (`paths` 필터 workflow를 단계 실행으로 셈) | 닫힘 | `flow`가 `paths`·`paths-ignore`가 붙은 change trigger를 `PATH_FILTERED`로 보고, change trigger가 그것뿐이면 이유와 함께 세지 않는다. `WorkflowGradleInvocationsTest`의 필터 workflow 셋 | +| 태그·릴리스 workflow(18.4절 넷째 결정) | 닫힘 | `Invocation.whyNotExecuting(taskPath, buildDirectory)`가 `RELEASE` workflow의 명령을 `:releaseCheck`에만 센다. `StrictLaneStagesFunctionalTest`(TestKit)가 다른 단계에서 실패, `releaseCheck`에서 통과를 본다 | +| RR7-02-01 (interrupt된 `close()`) | 닫힘 | `ClientRuntimeRegistry.java:178-215`, 테스트 `closingFromAnInterruptedThreadStillWaitsForTheDrainThread` | +| 깨진 상대 링크 셋 | 닫힘 | `python3 scripts/check-work-docs.py --links`를 lychee 범위(`gates.md` 2절 명령)에 돌려 572개 파일, 링크 520개, 깨짐 0(노트북, 이 리뷰에서 다시 돌림) | +| `AGENTS.md` 커밋 예외 문장 | 닫힘 | `AGENTS.md:118-119`와 `docs/work/README.md` 4절, 결정 색인 「커밋 예외」가 "brief가 허용한 것만, commit과 push는 따로"로 같다 | + +## 결함 + +없다. + +## Declined to judge + +없다. + +## 결론 + +Critical 0, Important 0, Minor 0. 결함 0건. + +- 세 수정과 문서 둘이 주장대로다. 판독기의 새 분기는 세지 않는 쪽(거짓 실패)으로만 넓어졌고, 세는 쪽으로 넓어진 trigger 조합을 찾지 못했다. diff --git a/docs/reviews/2026-11-03-rereview/round8/06-manual-scripts.md b/docs/reviews/2026-11-03-rereview/round8/06-manual-scripts.md new file mode 100644 index 00000000..41d4794b --- /dev/null +++ b/docs/reviews/2026-11-03-rereview/round8/06-manual-scripts.md @@ -0,0 +1,112 @@ +# 06 매뉴얼·검사 스크립트 round7 범위 확인 리뷰 (2026-11-07) + +> 대상: `b872b0ea`·`6dd9ef76`·`b7d13104`(이력 검사 패턴), `73d39212`(cold-read 시험 1회차 빈틈), `b619c442`(독립 리뷰어 둘), `447a77a3`(운영 +> playbook 빈틈 여섯), `81ef58ab`(매뉴얼 본문 이력 ID 19줄). 범위 `2c8a359d..83a12f66`, 기준 커밋 `83a12f66`. 영역 표는 +> [01 문서](01-transport-errors.md) 「범위」에 있다. 이 커밋들은 round7 결함 수정이 아니라 같은 통합 브랜치에 합쳐진 매뉴얼 수정이다. brief의 +> 범위가 `2c8a359d..83a12f66` 전체라 함께 봤다. + +## 범위 + +### pathspec + +``` +docs/work scripts CLAUDE.md +docs/manual/03-placement.md docs/manual/05-idempotency.md docs/manual/06-errors.md docs/manual/08-testing.md +docs/manual/09-outbox-events.md docs/manual/README.md +``` + +`git diff --stat 2c8a359d..83a12f66 -- `: 18개 파일, +253 −67. 매뉴얼 04·07의 이력 ID 걷어내기 hunk도 여기서 봤다(그 파일은 03·02의 +pathspec). `docs/work/evidence.md`는 기록이라 결론에 쓰인 사실만 대조했다. + +함께 읽은 주변 코드: `scripts/check-review-index.py` 전체, `scripts/check-work-docs.py`의 `HISTORY_PATTERNS`, `.github/workflows/link-check.yml` +범위, `docs/reviews/2026-11-01-maturity-review/README.md` 13·14절(매뉴얼이 새로 적은 날짜의 출처). + +### 수정 보고의 「새로 가정하는 것」 + +수정 보고는 공유 노트 `manual-gap-fix-1.md`·`t4-2-manual-history-ids.md`다. 이 칸이 없어 「정한 기본값」과 커밋 본문에서 뽑았다. + +| 가정 | 확인 | +|---|---| +| 독립 리뷰어 둘일 때 정본 리뷰어만 리뷰 폴더에 문서를 커밋하고, 그 라운드 색인 절은 총괄이 쓴다 | 두 규칙이 함께 있으면, 정본 리뷰어의 커밋은 색인 검사를 rc=1로 남긴다. 같은 매뉴얼이 리뷰어에게 rc=0을 요구한다(RR8-06-01) | +| "상한에 가까움" = 추가 1,000줄 이상(기본값) | 판정 대상이 아니다(기본값). 이 라운드는 +3,747줄이라 해당한다 | +| 매뉴얼 본문의 「1라운드」는 2026-11-01에 한 첫 수정이다 | 참. `2026-11-01-maturity-review/README.md:368`(합친 트리 게이트 2026-11-01 23:32~23:45), `:399`(2라운드 지시 2026-11-01 23:20). 커밋 `34565130`의 날짜(2026-11-03)는 그 작업을 나중에 커밋한 날이다(13절 "커밋하지 않았다") | +| lychee 범위 상대 링크 검사 명령(`gates.md` 2절)이 workflow 범위와 같다 | 참. `link-check.yml`의 범위와 같고, 노트북에서 돌려 572개 파일·링크 520개·깨짐 0 | + +### 불러온 스킬과 적용한 기준 + +| 스킬 | 기준 | 본 것 | +|---|---|---| +| `superpowers:requesting-code-review` | 주장과 구현, 읽기 전용 | 매뉴얼 문장끼리 모순, 검사 스크립트와 문장의 약속 | +| `docs/work/reference/review-criteria.md` 1절 | 문서끼리 다르게 말하거나 문서대로 하면 실패하는 곳 | 이 리뷰 자신이 정본 리뷰어로 그 절차를 따라 함 | + +### 실행한 명령과 결과(노트북, Python 검사만) + +| # | 명령 | 결과 | +|---|---|---| +| N1 | `python3 scripts/check-work-docs.py` | rc=0. 분량 상한 안(improve.md 141/150, README 76/80 등), 이력 ID 0줄, 상대 링크 115개 | +| N2 | `python3 scripts/check-work-docs.py --history docs/manual` | rc=0. 13개 파일, 이력 ID 0줄 | +| N3 | `python3 scripts/check-work-docs.py --links $(git ls-files … lychee 범위 …)`(`gates.md` 2절 명령 그대로) | rc=0. 572개 파일, 링크 520개, 깨짐 0 | +| N4 | `python3 scripts/check-review-index.py docs/reviews/2026-11-03-rereview`(이 라운드 문서 여섯을 둔 작업 트리) | rc=1. 발견 제목 180개 중 색인에 없음 8개 — 이 라운드 발견 전부(RR8-01-01·02, RR8-02-01, RR8-03-01·02, RR8-04-01·02, RR8-06-01) | +| N5 | N4와 같은 검사를 임시 복사본에 돌림: README 끝에 이 리뷰 보고의 색인 표를 붙인 사본 | rc=0. 180/180 | + +N4·N5는 RR8-06-01의 증거다. N1~N3은 desktop에서 다시 돌리지 않았다(`docs/work/operate.md` 4.1절은 보고 증거로 쓸 때 desktop에서 한 번 더 돌리라고 +한다. 이 검사들은 결론에 쓰지 않은 확인이라 노트북 결과만 적는다). + +### 못 본 것 + +- design-docs 쪽 변경(`c47451a`, `7703b85` 등): 이 repo 밖이라 범위 밖이다. +- 매뉴얼이 바뀐 절차(독립 리뷰어 둘, push 전 검증)를 실제로 따라 해 보는 cold-read 시험: 이 리뷰가 독립 리뷰어 절차를 따랐을 뿐, 다른 절차는 시험하지 않았다. + +## 항목 재확인 + +이 커밋들은 round7 발견을 고친 것이 아니라 고친 항목이 없다. 처리 표 `docs/work/evidence.md` 8·9절의 행이 그 커밋의 주장이다. 결론에 쓰인 +날짜·문장 다섯을 대조했고 맞았다(위 표 셋째 줄, 매뉴얼 03·05·06·08·09의 바뀐 문장). + +## 결함 + +### RR8-06-01 · Minor · 독립 리뷰어 둘이면 정본 리뷰어가 리뷰 폴더에 커밋한 문서가 색인 검사를 rc=1로 남기는데, 같은 매뉴얼이 리뷰어에게 rc=0을 요구한다 + +- **위치**: + - `docs/work/improve.md:45`(7단계: "한 라운드를 여러 리뷰 세션이 나눠 보면 색인 절도 맡긴 쪽이 쓰고, 리뷰어는 보고에 같은 표를 둔다"), `:46`(8단계: 색인 검사 "rc=0이어야 한다"), `:54`("리뷰 폴더에 문서를 커밋하는 것은 brief가 정한 정본 리뷰어뿐이다"), `:97`(완료 기준 "색인 검사가 rc=0이다"). + - `docs/work/delegate.md:38`("그 라운드 색인 절은 총괄이 쓰고"), `docs/work/reference/decisions.md:35`(「리뷰 README 분담」). + - 검사: `scripts/check-review-index.py`는 영역 문서의 모든 발견 제목이 README에 있어야 rc=0이다. +- **무엇이 틀렸나**: + - 독립 리뷰어 둘이면 정본 리뷰어가 영역 문서를 리뷰 폴더에 커밋한다. 그 문서의 발견 제목(`### RR-NN-MM`)은 아직 README에 없다. 색인 절은 총괄이 두 리뷰를 합친 뒤 쓴다. + - 그래서 정본 리뷰어의 커밋 직후 색인 검사는 반드시 rc=1이다(명령 N4). + - 같은 매뉴얼의 8단계와 5절 완료 기준은 리뷰어에게 rc=0을 요구한다. 정본 리뷰어는 README를 쓰지 말라는 규칙과 rc=0을 보이라는 규칙을 함께 지킬 수 없다. + - 두 규칙은 이 범위의 서로 다른 커밋이 만들었다: 7·8단계는 `73d39212`, 정본 리뷰어 커밋은 `b619c442`. +- **발생 조건·영향**: + - 조건: `improve.md` 4.1절의 세 경우(멈추는 확인 리뷰, 추가 1,000줄 이상, Important 이상을 고친 수정)마다다. 이 라운드가 그 경우다. + - 영향: 정본 리뷰어는 rc=1을 보고하거나, 금지된 README 색인 절을 쓰게 된다. 총괄이 합치기 전까지 리뷰 브랜치의 색인 검사가 빨갛다. 그 사이 브랜치를 합치면 색인 검사로 막으려던 "색인에서 빠진 발견"과 구별되지 않는다. + - Minor로 둔 이유: 거짓 실패 쪽이고, 총괄이 색인 절을 쓰면 닫힌다. +- **테스트가 못 본 이유**: 매뉴얼 문장끼리의 모순은 `check-work-docs.py`가 보지 않는다. 독립 리뷰어 절차를 처음 따른 것이 이 라운드다. +- **고치는 법**: + - 권장: 8단계와 5절에 독립 리뷰어 둘의 경우를 적는다. "정본 리뷰어는 리뷰 폴더 README를 고치지 않고, 보고의 색인 표를 붙인 임시 사본으로 색인 검사를 돌려 rc=0을 보인다. 커밋한 트리의 rc=1은 총괄이 색인 절을 쓰면 닫힌다." 이 리뷰가 그렇게 했다(명령 N5). + - 대안 1: `check-review-index.py`에 색인 표 파일을 따로 받는 옵션(`--extra-index <파일>`)을 더해, 정본 리뷰어가 보고 표를 넘겨 돌린다. + - 대안 2: 정본 리뷰어가 README에 그 라운드 색인 절을 먼저 쓰고, 총괄은 합칠 때 다른 쪽 발견의 새 ID와 대응표만 더한다. 결정 「리뷰 README 분담」을 바꾸므로 결정 기록이 필요하다. + - RED 테스트 모양: 매뉴얼 문장이라 없다. 확인은 다음 독립 리뷰 라운드의 정본 리뷰어가 매뉴얼대로 해서 rc=0을 보이는지다. +- **이번 수정 / 이전부터**: 이번 수정. +- **증거**: E2 — 명령 N4(커밋 전 작업 트리에서 rc=1), N5(보고 표를 붙인 사본에서 rc=0). 문장 대조는 E1. + +## 18.6절에서 넘어온 항목 판정 + +| 항목 | 판정 | 근거 | +|---|---|---| +| `docs/manual`·`docs/work` 밖 문서(`AGENTS.md`, `docs/httpclient/*.md`, `src/adapter/inbound/web/README.md` 등)의 본문 이력 ID | 소유자 결정 필요 | 매뉴얼 규칙(`docs/work/README.md` 8절, `docs-writing.md` 6단계)은 `docs/work/`와 매뉴얼 본문을 대상으로 적는다. 그 밖 문서에 넓힐지는 정해진 것이 없다(README 18.6절). 아래 「결정이 필요한 것」 | + +### 결정이 필요한 것 + +| 항목 | 선택지 | 권하는 안과 이유 | 정할 사람 | +|---|---|---|---| +| 이력 ID 0 규칙을 `docs/manual`·`docs/work` 밖으로 넓힐지 | (a) 넓히지 않는다. 그 밖 문서는 모듈·설계 기록이라 리뷰 ID가 추적용이다 (b) 진입 문서만 넓힌다: `AGENTS.md`와 leaf `CLAUDE.md`(새 세션이 처음 읽는 규칙) (c) `docs/reviews/**` 밖 전부 | (b). 새 세션이 처음 읽는 규칙 문서에서만 ID가 이해를 막는다(매뉴얼 규칙을 만든 이유와 같다). 모듈 README·설계 문서의 ID는 같은 repo의 리뷰 문서로 따라갈 수 있다. (c)는 65줄을 걷어내야 하고(t4-2 노트) 이력 근거를 잃는다 | 소유자 | + +## Declined to judge + +없다. + +## 결론 + +Critical 0, Important 0, Minor 1, 회귀 0. 결함 1건(이번 수정). 결정 필요 1건(18.6절에서 넘어온 이력 ID 범위). + +- 이력 검사 패턴과 매뉴얼 날짜 치환은 주장대로다. 링크 검사 명령은 workflow 범위와 같다. +- 독립 리뷰어 절차는 이 라운드에서 처음 쓰였고, 정본 리뷰어의 색인 검사 단계 하나가 다른 규칙과 부딪힌다.