fix!: r9 확인 리뷰가 찾은 결함 25건을 고친다

문제: r9 커밋(45d2a478)을 영역 4개로 다시 리뷰해 결함 25건을 찾았다
(Important 2, Minor 23, round6/01~04). Important 둘: r9가 @Configuration을
사용자 전송에서 통째로 빼서 설정 안의 RouterFunction·DataFetcher가
@SystemCaller를 불러도 잡히지 않는 회귀, 그리고 가이드대로 만든
CREATE INDEX CONCURRENTLY 마이그레이션이 Flyway 기본 트랜잭션 잠금과 서로
기다려 끝나지 않는 것(이전부터). 그 밖에 시작을 거절당한 같은 attempt가
기록 만료까지 503을 받는 것, gRPC 취소 판정과 raw status 설명의 로그 유출,
STOMP의 IAE ERROR 기록, 아무것도 잡지 못하던 shared-contract 패키지 규칙,
workflow 판독기의 거짓 통과 모양(-v·조건부 exit·Windows 기본 셸·요청형
trigger 등).

방법: 영역별 4묶음이 실패 테스트를 먼저 확인하고 고쳤다(재리뷰 README 17절).
- 설정과 그 중첩 클래스는 요청 처리기 타입에 의존하면 사용자 전송으로 센다.
- Flyway PostgreSQL 잠금을 세션 수준으로(transactional-lock=false), 직접
  만드는 Flyway는 FlywaySchemaPolicy 하나로. 버린 대안: CIC를 마이그레이션에서
  금지하고 운영 절차로.
- 같은 attempt로 다시 claim하면 lease가 지난 claim을 넘겨받는다. 옛 revision의
  늦은 시작이 ALREADY를 받아 이중 실행되던 것도 막았다.
- 네 전송이 IAE를 ServerFailureLog의 같은 WARN 한 줄로 남긴다.
- workflow 판독기가 세지 않는 이유를 셋으로 나누고 문서 5곳을 같은 말로.

위험·한계: Flyway 세션 잠금은 transaction-mode PgBouncer 뒤에서 깨진다
(Hikari 직접 연결 전제, 가이드에 적음). 배포 마이그레이션 도구도 같은 값을
써야 한다(업그레이드 안내). 같은 attempt를 두 호출이 동시에 쓰는 것은
저장소가 가려내지 않는다(호출자 계약으로 문서화).

검증: GATES

Refs: docs/reviews/2026-11-03-rereview/README.md 17절
BREAKING CHANGE: Flyway PostgreSQL 잠금이 세션 수준이 되어 배포 도구에도
flyway.postgresql.transactional.lock=false가 필요하다. GraphQL·gRPC가 IAE를
WARN 한 줄로 남긴다. shared-contract 패키지 규칙이 실제로 검사한다.
This commit is contained in:
DongHyeonka
2026-11-05 20:37:55 +09:00
parent 45d2a478b8
commit 2c692554cb
97 changed files with 5152 additions and 934 deletions
+44 -9
View File
@@ -12,6 +12,24 @@ Design §31-§32. Flyway owns the schema; Hibernate only validates.
Migrating from inside the application in production means every instance of a rolling deploy races
to apply the same script, and the loser's failure is indistinguishable from a real one.
Whoever runs the migration holds Flyway's PostgreSQL migration lock for the session, not in a
transaction: `flyway.postgresql.transactional.lock=false`. Flyway's default (`true`) keeps a
transaction open until the whole run ends, and a concurrent index build waits for every transaction
older than itself, Flyway's own included — the deploy stops with no error and no time limit
("Concurrent index builds" below). The template sets it for every Flyway it runs: the module
defaults (`config/module-defaults/persistence-jpa.yml`, `spring.flyway.postgresql.transactional-lock:
false`) for the one Spring Boot builds at startup, and `FlywaySchemaPolicy.configure()` for every
stream it builds itself — a service's own stream starts from it too, and `JpaProductionArchitectureTest`
refuses production code that calls `Flyway.configure()` directly. The deployment-owned migration of
staging and prod is outside this repository: give its tool the same value
(`FLYWAY_POSTGRESQL_TRANSACTIONAL_LOCK=false`, or the key above in its configuration file).
A session lock assumes the connection Flyway takes stays its own for the whole run, which the
template's direct Hikari connection gives. Behind a pooler in transaction mode (PgBouncer
`pool_mode = transaction`) the unlock can reach another server connection and release nothing, and
the next migration waits for a lock that a pooled connection still holds. Run migrations over a
direct connection or a session-mode pool.
`ddl-auto` is `validate` or `none`. Never `update`: it never drops or narrows anything, so it
produces a schema that is neither the old one nor the one the migrations describe — silently, on
whichever instance started first.
@@ -84,30 +102,47 @@ stay that way (they are applied, and applied files are never edited); the test l
refuses any new one. `PostgreSqlMigrationLockWaitIntegrationTest`
(`postgresqlMigrationLockWaitIntegrationTest`) shows on real PostgreSQL that a bounded migration
gives up within the bound while another transaction holds the table, and leaves the version below
it; it also holds the inspector's copy of Flyway's list to Flyway itself (the statements it names
are exactly those Flyway refuses next to a `SET LOCAL`), and shows a `VACUUM FULL` run under
`mixed=true` waiting out a reader despite its `SET LOCAL`. The gRPC ledger's tree lives in the
it; it also compares the inspector's copy of Flyway's list with Flyway itself for the statements it
lists (each is named by the inspector exactly when Flyway refuses it next to a `SET LOCAL`), and
shows a `VACUUM FULL` run under `mixed=true` waiting out a reader despite its `SET LOCAL`. A
statement a Flyway upgrade adds to the list is outside that comparison; `LockWaitMigrationInspectorTest`
pins Flyway's own patterns (`PostgreSQLParser`), so such an upgrade fails the pull request's `ci`
until the copy follows. The gRPC ledger's tree lives in the
optional build, which cannot depend on the testkit: its `GrpcOperationLedgerMigrationLockWaitIT`
runs every ledger migration after V001, read from the tree, against a held ledger instead, so its
next migration is checked on real PostgreSQL. It finds and orders that tree with the testkit's own
`VersionedMigrationFiles`, which the ledger's `build.gradle` copies into its integration-test sources
at build time (`sharedMigrationFileSources`), so both builds read one definition. The rule came from
V21 having the bound and V22, in the same commit, not having it (re-review 2026-11-03 round 2,
RR-02-09; round 3, RR3-02-01, RR3-02-03, RR3-02-04; round 4, RR4-02-01).
RR-02-09; round 3, RR3-02-01, RR3-02-03, RR3-02-04; round 4, RR4-02-01; round 6, RR6-03-02,
RR6-03-03).
## Concurrent index builds
`CREATE INDEX CONCURRENTLY` cannot run inside a transaction block, and Flyway wraps migrations in
one by default. Flyway recognizes `CREATE`/`DROP INDEX CONCURRENTLY` and runs such a script outside
the transaction on its own (above), but not `REINDEX … CONCURRENTLY`; write the companion
configuration for every concurrent statement anyway, so the file says what it needs and no reader
has to know Flyway's list:
`CREATE INDEX CONCURRENTLY`, `DROP INDEX CONCURRENTLY` and `REINDEX … CONCURRENTLY` cannot run
inside a transaction block. Flyway recognizes `CREATE`/`DROP INDEX CONCURRENTLY` and runs such a
script outside a transaction on its own (above), but not `REINDEX … CONCURRENTLY`, which it runs in
the transaction for PostgreSQL to refuse. Write the companion configuration for every concurrent
statement anyway, so the file says what it needs and no reader has to know Flyway's list:
```conf
# V42__order_index.sql.conf
executeInTransaction=false
```
Outside a transaction, `CREATE INDEX CONCURRENTLY` and `REINDEX … CONCURRENTLY` still wait until
every transaction older than them has ended. Under Flyway's default lock that includes the
transaction Flyway itself keeps open, and Flyway waits for the build in turn: the deploy never ends,
and the table's other DDL and autovacuum queue behind the build meanwhile. The template's Flyway
holds its lock for the session instead ("Who may change the schema"), so the build waits only for
other transactions; a deployment tool left on Flyway's default stops on the first such migration.
`DROP INDEX CONCURRENTLY` does not wait that way. `PostgreSqlConcurrentIndexMigrationIntegrationTest`
(`postgresqlConcurrentIndexMigrationIntegrationTest`) applies both builds as a second deploy, with
the Flyway Spring Boot builds from the module defaults and with `FlywaySchemaPolicy.configure()`,
on real PostgreSQL. The other transactions still count: a long one an operator or a report keeps
open holds the build, and a file run outside a transaction cannot bound that wait with `SET LOCAL`.
Look for old transactions (`pg_stat_activity.xact_start`) before deploying one.
The testkit's `ConcurrentIndexMigrationInspector` checks a script for this in a migration test
(nothing checks it at startup), and additionally requires the migration to contain nothing else. A failed concurrent build leaves an invalid index behind;
recovering is a single `DROP INDEX` when the migration did nothing else, and a manual reconstruction
+3
View File
@@ -119,6 +119,9 @@ capability 스트림 db/migration/jpa/<capability> 각자 histor
`SamplePostgreSqlPersistenceConfig.sampleMigrationStrategy`
(`src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/bootstrap/persistence/SamplePostgreSqlPersistenceConfig.java`)와
`NotificationSchemaStream`(persistence-notification). 그러면 번호가 템플릿 스트림과 독립이라 V1부터 쓴다.
자기 스트림의 Flyway는 `Flyway.configure()`가 아니라 `FlywaySchemaPolicy.configure()`(persistence-jpa)로
만든다. Flyway의 PostgreSQL 잠금을 세션에 두어야 `CREATE INDEX CONCURRENTLY` 마이그레이션이 끝나고,
직접 부르면 `:app-bootstrap:architectureTest`가 실패한다(`docs/jpa/migration-guide.md` "Who may change the schema").
- **예외**: 템플릿 운영 스트림(`db/migration/postgresql`)에 직접 넣으면 upstream이 다음에 쓸 번호와
겹친다. 어쩔 수 없으면 upstream이 쓰지 않을 큰 번호대를 정해 문서에 적는다.
- 이미 적용된 파일은 고치지 않는다. 고치면 체크섬 불일치로 기동이 멈추고, `repair`는 쓰지 않는다
+8 -2
View File
@@ -54,8 +54,11 @@ DB 커밋 중 연결 끊김 ─────────────────
| 500 `IDEMPOTENCY_RECOVERY_REQUIRED` | 이전 시도 효과를 증명 못함 | 자동 재시도 안 함. 같은 키 재전송은 안전(재생·실행·다시 500을 서버가 판정, 다시 돌리지 않음). 업무 데이터로 확인하고, 효과가 없다고 확인된 뒤에만 운영 절차에 따라 새 키 |
| 500 `DB_COMPLETION_UNKNOWN`, `retryable=false` | DB 커밋 중 연결 끊김. 커밋됐을 수도 있음 | 키 없이 재시도 금지. KEYED면 같은 키로 재전송하면 서버가 판정 |
같은 키 재전송은 작업을 다시 돌리지 않는다. 다만 첫 시도가 processing lease(기본 30s)보다 오래 걸릴 때
보이는 모습은 저장소마다 다르다(재리뷰 2026-11-04 RR5-01-05, 정본 `docs/web/http-contract.md` 2절).
같은 키 재전송이 무엇을 막는지는 저장소마다 다르다(재리뷰 2026-11-04 RR5-01-05, 라운드6 RR6-02-05, 정본
`docs/web/http-contract.md` 2절). Redis 저장소에서 같은 키 재전송은 효과가 있었을 수 있는 작업을 다시 돌리지
않는다. PostgreSQL 저장소를 템플릿처럼 쓰기 트랜잭션 하나로 쓰면 실패한 요청의 기록은 롤백되어 다음 같은 키
요청이 다시 실행한다. 그래서 트랜잭션 밖 효과는 따로 멱등하게 만든다. 첫 시도가 processing lease(기본 30s)보다
오래 걸릴 때 보이는 모습도 저장소마다 다르다.
- **Redis**: 첫 시도가 실행을 시작한 뒤 lease가 지나면 그 기록을 넘겨주지 않고 500
`IDEMPOTENCY_RECOVERY_REQUIRED`로 답한다. 넘겨받는 것은 실행 전 claim과 재시도 가능한 실패뿐이다. 이 답은
@@ -71,6 +74,9 @@ DB 커밋 중 연결 끊김 ─────────────────
claim의 lease가 작업 시작 전에 끝나면 두 저장소 모두 시작을 거절하고(`LEASE_EXPIRED`), executor는 작업을
돌리지 않은 채 503 `IDEMPOTENCY_UNAVAILABLE`로 답한다. 다음 같은 키 요청이 그 claim을 넘겨받아 실행한다.
`IdempotencyClaimAttempt`를 재시도 사이에 들고 있다가 같은 attempt로 다시 부르는 호출자도 넘겨받는다(라운드6
RR6-02-01. 전에는 같은 claim을 재생받아 시작을 다시 거절당해 기록이 사라질 때까지 503이었다). 같은 attempt를
두 호출이 동시에 쓰면 서버가 가려내지 못하므로, 재시도는 앞 호출이 돌아온 뒤에 한다.
기록은 lease + `replay-ttl` 동안 남고, `replay-ttl`이 lease보다 짧으면 기동이 실패한다
(`IdempotencyStoreContract`, 재리뷰 2026-11-04 RR-01-11·RR-03-11). 작업이 실패로 끝나 executor가 포기나
재시도 가능으로 표시한 기록은 표시한 때부터 `failure-retention`(기본 24h) 동안 남는다(PostgreSQL을 트랜잭션
+12 -7
View File
@@ -102,14 +102,15 @@ JWT의 `realm_access.roles`와 **자기 client**(`app.security.audience`)의 `re
| bean 금지 | `@SystemInvoked` 유스케이스가 bean이면 기동 실패. 호출자가 `new`로 만들어 혼자 들고 있는 것만 허용한다 | `src/composition/service-runtime/src/main/java/dev/caskeleton/composition/runtime/authorization/PermissionEnforcementGuard.java` |
| 시스템 호출자만 | inbound adapter가 그 클래스에 의존하면 빌드 실패. `@SystemCaller(reason = "...")`를 단 클래스와 그 안에 중첩된 클래스만 예외 | `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`(`ApplicationBoundaryArchitectureTest`) |
| 표시 검사 | `@SystemCaller` 클래스와 그 안에 중첩된 클래스는 `..adapter.inbound.messaging..`·`..adapter.inbound.scheduler..`에만 있고, 사용자 전송 타입(controller·JAX-RS·GraphQL·STOMP mapping·gRPC·servlet)에 의존하지 않는다 | `SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`(같은 파일) |
| 전송 → 시스템 호출자 금지 | 사용자 전송 클래스가 `@SystemCaller`나, 그 클래스가 구현·상속하는 프로젝트 타입(작업의 인터페이스 등)에 의존하면 빌드 실패. 중간 클래스를 거쳐도 잡는다. 사용자 전송 클래스는 사용자 전송 패키지에 있는 클래스, 또는 사용자 전송 타입에 의존하는 클래스 가운데 설정(`@Configuration`·`@AutoConfiguration`)이 아닌 것이다. 그래서 handler를 bean으로 등록하는 설정은 같은 클래스에서 `WebMvcConfigurer`·interceptor·controller bean을 함께 만들어도 걸리지 않는다. 설정이 만드는 controller는 controller 자신이 검사받는다 | `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`(같은 파일) |
| 프로젝트 밖 상위 타입 금지 | `@SystemCaller` 클래스와 그 안에 중첩된 클래스(익명·지역 클래스 제외)는 프로젝트(`dev.caskeleton..`) 밖의 클래스·인터페이스를 상속·구현하지 않는다. `Runnable`은 누구나 의존하는 타입이라, endpoint가 작업을 `Runnable`로 주입받아도 위 규칙이 다른 사용과 구별하지 못하기 때문이다. 메시지 handler의 `MessageHandler<T>`는 프로젝트 타입이라 된다 | `SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`(같은 파일) |
| 전송 → 시스템 호출자 금지 | 사용자 전송 클래스가 `@SystemCaller`나, 그 클래스가 구현·상속하는 프로젝트 타입(작업의 인터페이스 등)에 의존하면 빌드 실패. 중간 클래스를 거쳐도 잡는다. 사용자 전송 클래스는 셋이다. ① 사용자 전송 패키지에 있는 클래스. ② 설정(`@Configuration`·`@AutoConfiguration`)과 그 안에 중첩된 클래스 가운데 요청 처리기 타입(함수형 `RouterFunction`·`HandlerFunction`, `@RestController`·`@RequestMapping`, servlet·`Filter`·`HandlerInterceptor`, `WebSocketHandler`, GraphQL `DataFetcher`·`RuntimeWiringConfigurer`, gRPC `BindableService`·`ServerInterceptor` 등)에 의존하는 것. 함수형 route나 data fetcher를 람다로 쓰면 그 코드가 설정 클래스의 메서드로 컴파일되어 설정이 곧 endpoint다. ③ 그 밖의 클래스 가운데 사용자 전송 타입에 의존하는 것. 그래서 handler를 bean으로 등록하는 설정은 같은 클래스에서 `WebMvcConfigurer`(설정 필드를 읽는 익명 클래스여도)·controller bean을 함께 만들어도 걸리지 않지만, 같은 클래스에 "지금 실행" route·data fetcher·interceptor를 직접 쓰면 걸린다. 요청 처리 코드는 handler를 등록하는 설정과 다른 클래스에 둔다. 설정이 만드는 controller는 controller 자신이 검사받는다 | `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`(같은 파일) |
| 프로젝트 밖 상위 타입 금지 | `@SystemCaller` 클래스와 그 안에 중첩된 클래스(익명·지역 클래스와 예외 제외)는 프로젝트(`dev.caskeleton..`) 밖의 클래스·인터페이스를 상속·구현하지 않는다. `Runnable`은 누구나 의존하는 타입이라, endpoint가 작업을 `Runnable`로 주입받아도 위 규칙이 다른 사용과 구별하지 못하기 때문이다. 메시지 handler의 `MessageHandler<T>`는 프로젝트 타입이라 된다. record·enum은 언어가 붙이는 상위 타입(`Record`, `Enum`과 `Enum`이 구현하는 `Comparable`·`Serializable`·`Constable`)만은 가져도 된다. 그래서 handler 안의 파싱 결과 record, 결과 enum, 독(poison) 메시지 예외, record로 쓴 handler는 통과하고, `Runnable`을 구현한 record는 걸린다 | `SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`(같은 파일) |
규칙은 "누가 닿으면 안 되나"가 아니라 "누가 닿아도 되나"를 적는다. 이 성질은 **패키지** 쪽에서만 온다.
패키지는 허용 목록이라, 나중에 새 전송 패키지가 생겨도 따로 고치지 않아도 막힌다. 사용자 전송 **타입**
쪽은 나열 목록이다(`ARE_USER_TRANSPORT_TYPES`). 시스템 패키지 안에 놓인 endpoint를 알아보는 데 쓰는
목록이라, 목록에 없는 전송 라이브러리로 만든 endpoint는 전송으로 보이지 않는다. 새 전송 라이브러리를
들이면 그 패키지를 이 목록에 더한다.
들이면 그 패키지를 이 목록에 더한다. 설정 안의 요청 처리 코드를 알아보는 요청 처리기 타입
(`ARE_REQUEST_HANDLER_TYPES`)도 나열 목록이라, 새 전송 라이브러리의 handler 타입을 함께 더한다.
D4 실패(`MUTATING_USE_CASES_DECLARE_REQUIRED_PERMISSION`)를 끄려고 이 표시를 쓰지 않는다. 사용자가 부르는
쓰기라면 권한을 선언하고 역할에 매핑한다. 같은 쓰기를 사용자도 시스템도 부르면 유스케이스를 둘로 나눈다
@@ -122,7 +123,10 @@ D4 실패(`MUTATING_USE_CASES_DECLARE_REQUIRED_PERMISSION`)를 끄려고 이 표
- 이름이나 `Object`로 bean을 찾는 코드: `getBean("nightlyJob")`, `Map<String, Object>` 주입 뒤 reflection 호출.
- 설정이 사용자 전송에 작업을 감싼 함수를 넘기는 코드: `new RunNowController(job::run)`처럼 controller는
`Runnable`만 받는다. 의존은 설정 → 작업 쪽에만 있고, 설정은 사용자 전송이 아니다.
`Runnable`만 받는다. 의존은 설정 → 작업 쪽에만 있고, 요청 처리 코드를 직접 갖지 않은 설정은 사용자 전송이
아니다.
- 설정 안의 요청 처리 코드가 요청 처리기 타입 목록(`ARE_REQUEST_HANDLER_TYPES`)에 없는 타입으로 쓰인 경우.
목록 방식이라, 목록에 없는 endpoint 타입으로 설정 안에 쓴 endpoint는 사용자 전송으로 보이지 않는다.
이 길을 막는 것은 ArchUnit 규칙이 아니라 다음 셋이다.
@@ -131,9 +135,10 @@ D4 실패(`MUTATING_USE_CASES_DECLARE_REQUIRED_PERMISSION`)를 끄려고 이 표
- 의존 방향 게이트(`src/config/architecture/modules.json`): 등록된 leaf 가운데 `adapter:inbound:messaging`에
의존할 수 있는 것은 조립 루트(`app-bootstrap`)뿐이다. 다른 leaf의 사용자 전송은 handler 타입을 컴파일조차
못 한다. 예약 작업은 서비스 자기 leaf에 있어서 같은 leaf의 controller와 사이에는 이 게이트가 없다. 그래서
위 두 길은 사실상 controller와 작업이 같은 leaf에 있을 때, 또는 둘을 모두 보는 설정에서 생긴다.
- 리뷰: 설정에서 시스템 호출자를 함수로 감싸 다른 bean에 넘기거나, 사용자 전송이 bean을 이름으로 찾는 코드는
리뷰에서 거절한다. 사용자도 같은 일을 시켜야 하면 위 문단대로 사용자용 유스케이스를 따로 만든다.
위 길들은 사실상 controller와 작업이 같은 leaf에 있을 때, 또는 둘을 모두 보는 설정에서 생긴다.
- 리뷰: 설정에서 시스템 호출자를 함수로 감싸 다른 bean에 넘기거나, 사용자 전송이 bean을 이름으로 찾거나, 목록에
없는 타입으로 설정 안에 endpoint를 쓰는 코드는 리뷰에서 거절한다. 사용자도 같은 일을 시켜야 하면 위 문단대로
사용자용 유스케이스를 따로 만든다.
## web 없는 조립
@@ -591,8 +591,12 @@ compose 실제 기동은 묶음 에이전트가 lane별로 확인했다: local-f
## 17. 커밋 단위 계획
저장소 정책이 `human-only`라 커밋하지 않았다. 사람이 그대로 쓸 수 있는 커밋 자료를
`../clean-architecture-backend-template-commit-kit/`(repo 밖, 같은 상위 폴더)에 두었다.
저장소 정책이 `human-only`라 커밋하지 않았다. 사람이 그대로 쓸 수 있는 커밋 자료(패치 세 개와 메시지)를
repo 밖 `../clean-architecture-backend-template-commit-kit/`에 두었다.
2026-11-03 소유자 지시로 이 세 커밋을 브랜치 `refactor/maturity-review-2026-11`에 만들고 push했다:
`34565130`(1), `1400dc15`(2), `5786126c`(3). 2026-11-05에 패치 세 개를 `01a8a2a70`에 차례로 적용한
트리가 세 커밋의 트리와 각각 같음을 확인하고 자료 폴더를 지웠다. 아래는 그때의 계획 기록이다.
### 17.1 고른 단위와 이유
@@ -608,8 +612,7 @@ compose 실제 기동은 묶음 에이전트가 lane별로 확인했다: local-f
- 발견 하나씩 커밋하려면 라운드 사이에 손으로 합친 충돌(14.1·16.1절)을 커밋마다 다시 풀고 중간 트리마다 게이트를 다시 돌려야 한다. 그 중간 트리는 검증된 적이 없다. 검증된 경계에서만 나누는 쪽을 골랐다.
- 리뷰어는 커밋 diff 대신 이 README의 13·14·16절 표(발견별 RED·GREEN·결정)를 따라가며 본다.
### 17.2 쓰는 법
### 17.2 쓰는 법 (끝남)
`../clean-architecture-backend-template-commit-kit/README.md`를 본다. 요약: 스크립트가 별도 worktree에
새 브랜치를 만들고 패치 세 개를 차례로 적용해 커밋한다. 메인 작업 트리는 건드리지 않는다. 마지막에
브랜치 트리가 메인 작업 트리와 같은지 비교한다.
자료 폴더의 스크립트가 별도 worktree에 새 브랜치를 만들고 패치 세 개를 차례로 적용해 커밋하는 방식이었다.
위 세 커밋으로 끝났고 자료 폴더는 2026-11-05에 지웠다.
@@ -361,3 +361,20 @@ Minor 중 RR5-01-01(`IDEMPOTENCY_RECOVERY_REQUIRED`의 클라이언트 안내가
| `scripts/verify-compose-profile-contracts.sh` | rc=0, 18 lane | — | 18.44 |
`mainCheck`·`integrationCheck`는 16.1절 수정 전 트리에서 돌았다. 그 수정은 httpclient만 바꿔서 httpclient `check`·`testQualityCheck`·`httpClientFailureInjectionTest`·`httpClientPerformanceTest`를 따로 다시 돌렸다(통과).
## 17. r9 확인 리뷰 round6과 수정 r10 (2026-11-05)
`45d2a478`(r9)을 영역 4개로 나눠 리뷰했다(`round6/01~04`). 결함 25건(Important 2, Minor 23). 01의 RR6-01-07과 02의 RR6-02-03은 같은 runbook 문장이라 한 번 고쳤다. 영역 묶음 4개가 `45d2a478`에서 고쳤고, 고치다 새로 찾은 결함도 고쳤다.
| 묶음 | 리뷰 결과 | 처리 | 결정 |
|---|---|---|---|
| r10-01 core·inbound | Important 1(RR6-01-01 회귀), Minor 8 | 설정·그 중첩 클래스는 요청 처리기 타입에 의존하면 사용자 전송으로 센다(A1 `RouterFunction`·A2 `DataFetcher` 위반 fixture, A5 허용 fixture). `SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`는 예외를 빼고 record·enum은 언어가 주는 상위 타입만 허용(`Runnable`을 구현한 record는 여전히 잡힘). gRPC는 `isCancelled()`일 때만 로그를 건너뛰고, 던진 raw status는 로그에 붙이지 않는다. `ServerFailureLog.refusedArgument`로 네 전송이 IAE를 같은 WARN 한 줄로 남긴다(GraphQL·gRPC 동작 변경). runbook 문구, GraphQL carrier 테스트. 이전부터의 `SHARED_CONTRACT_CONTAINS_ONLY_OPERATIONAL_CONTRACT_PACKAGES`를 `dev.caskeleton.shared..` 대상·정확한 12개 목록으로 고치고 "KNOWN DEFECT" 주석을 지웠다(업그레이드 B-42) | 요청 처리기 타입 목록은 리뷰어 예보다 넓게(설정에 중첩된 `@RestController`도 잡힘) |
| r10-02 멱등성·outbound | Minor 5 | 같은 attempt로 다시 claim하면 lease가 지난 `CLAIMED`와 `FAILED_RETRYABLE`을 넘겨받는다(Redis·PG·command fake·in-memory fake). 새로 찾아 고친 것: 옛 revision을 든 늦은 시작이 Redis에서 `ALREADY`를 받아 이중 실행됨 → 기록 revision이 핸들 revision + 1일 때만 `ALREADY`. PG의 다른 핸들 시작 답을 Redis와 같게(`NOT_OWNER`/`NOT_CLAIMED`). 같은 attempt의 `FAILED_RETRYABLE`·`ABANDONED` 답이 저장소마다 달랐던 것, in-memory fake가 fingerprint 검사 전에 기록을 넘겨준 것. command fake 위 계약이 시계를 움직인다(skip 17 → 0), fixture에 key TTL, 계약과 겹친 adapter 손 사본 20건 삭제. 503 뜻을 web README·인계 표에, 매뉴얼 05 첫 문장을 저장소별로 | RR6-02-01은 (a)안: 문서와 503 `retryable`이 약속하는 동작에 코드를 맞춘다. 같은 attempt를 두 호출이 **동시에** 쓰는 것은 attempt 정의(한 번의 순차 송신·재시도) 밖이라 저장소가 가려내지 않는다 — 결함이 아니라 호출자 계약으로 Javadoc·매뉴얼 05에 적었다 |
| r10-03 persistence | Important 1(RR6-03-01, 이전부터), Minor 4 | Flyway PostgreSQL 잠금을 세션 수준으로: module-defaults `spring.flyway.postgresql.transactional-lock: false`, 직접 만드는 Flyway는 `FlywaySchemaPolicy.configure()` 하나로(messaging은 persistence-jpa에 의존할 수 없어 같은 값 사본 + 대조 테스트), 직접 `Flyway.configure()`를 부르면 실패하는 ArchUnit 규칙, 실 PG IT(옛 설정 30초 정지 4/4 → 1.2초). 검사기의 `E'…\'…'` 판독과 중첩 주석, `PostgreSQLParser` 트랜잭션 밖 패턴을 PR `ci`에서 고정, IT 대조 목록 +6, ledger Spotless에서 Sync 사본 제외, "Flyway는 늘 트랜잭션으로 감싼다" 설명 정정. 새로 찾아 고친 것: 동시 인덱스 검사기가 `UNIQUE`·`REINDEX (CONCURRENTLY)`를 못 찾음 | RR6-03-01은 session-level 잠금(Flyway가 이 문제로 둔 공식 옵션). 버린 대안: CIC를 마이그레이션에서 금지하고 운영 절차로(큰 테이블 인덱스 추가가 번거로워짐). 전제: Hikari 직접 연결 — transaction-mode PgBouncer 뒤에서는 세션 잠금이 깨진다(가이드에 적음) |
| r10-04 build-logic | Minor 6 | 작업 없이 끝나는 Gradle 옵션(`-v`·`--help`·`--status`·`--stop`·`--foreground`, 묶음 포함)을 세지 않는다. `GradleCommandLineTest`가 판독기 옵션 표를 실행 중인 Gradle `--help`와 대조(9.2.0으로 돌리면 `task-graph`로 실패). 조건부 `exit 0`·`exec`·`set -n`·함수 안 exit·EXIT/ERR trap 뒤 명령, Windows일 수 있는 `runs-on`의 기본 셸, 요청형 trigger만 있는 workflow, 세는 호출자가 없는 `workflow_call`, 조건부 job을 `needs`로 기다리는 job을 세지 않는다. 세지 않는 이유를 셋(실패를 막지 못함 / 돌지 않을 수 있음 / 판독기가 읽지 않음)으로 나눠 메시지와 문서 5곳에 같은 말로 | 이 repo workflow에서 세는 명령 48개는 수정 전후 같다 |
합칠 때: 네 묶음 모두 `45d2a478` 기준이고 충돌 없이 적용됐다(92파일). 업그레이드 안내의 새 행 번호는 겹치지 않는다.
### 17.1 검증 위치 변경
2026-11-05 소유자 지시: 노트북에서 Gradle·Docker를 돌리지 않는다. 지시 전에 각 묶음이 로컬에서 RED·GREEN과 leaf `check`를 돌렸고, 지시 뒤의 변경(01의 A5 fixture 재작성, 03의 동시 인덱스 검사기 GREEN)과 합친 트리 전체는 desktop(`~/workspace/clean-architecture-backend-template`)에서 git pull 뒤 검증한다. 결과는 17.2절.
@@ -0,0 +1,218 @@
# 01 core·inbound r9 리뷰 (2026-11-05)
> 대상: `c508b1ba..45d2a478`의 r9-a 묶음. RR4-01-01·02(`@SystemCaller` 규칙), `graphql..` fixture, 원래 리뷰 16.3절
> (템플릿 패키지 목록 두 벌), RR4-03-03(전송별 실패 로그).
## 범위
### pathspec
```
src/application-core src/shared-contract src/adapter/inbound src/grpc src/composition/service-runtime src/app-bootstrap
docs/manual/07-authorization.md docs/runbooks/idempotency-unavailable.md docs/upgrade/2026-11-maturity-review.md
```
`git diff --stat c508b1ba..45d2a478 -- <pathspec>`: 57개 파일, +1956 −187. 새 파일(`ServerFailureLog`, `StompHandlerFailureLog`,
`TemplatePackageOwnershipDocumentTest`, fixture 13개)은 HEAD 전체를 읽었다. 바뀐 클래스는 diff와 함께 주변 코드
(`GrpcServerRunner` 인터셉터 순서, `WebSocketCorrelationInterceptor`, `GraphQlExceptionResolver`, `GlobalExceptionHandler`
전체 분기)를 읽었다.
### 불러온 스킬과 적용한 기준
| 스킬 | 기준 | 본 것 |
|---|---|---|
| `superpowers:requesting-code-review` | 주장(README 16절 r9-a)과 구현이 맞는가, 테스트가 이름대로의 동작을 보는가, 심각도 보정, Declined to judge, 읽기 전용(별도 worktree). 하위 에이전트는 띄우지 않고 diff를 여러 번에 나눠 직접 봤다 | 항목마다 닫힘 여부, 새 테스트의 이름과 준비 상태가 맞는지(RR6-01-04·08), 결함마다 실행 증거 |
| `clean-architecture` | Dependency Rule, "Main(조립 설정)은 바깥의 plugin", Humble Object(경계 코드는 얇게) | 조립 설정을 사용자 전송에서 뺀 판단이 "설정은 요청을 받지 않는다"는 가정에 기대는데, Spring 함수형 endpoint는 설정 클래스 안에 요청 처리 코드를 둔다(RR6-01-01). 템플릿 패키지 목록의 정본과 복사본 |
| `security-and-hardening` | 권한 검사는 모든 요청 경로에서, 민감 정보는 로그에 남기지 않는다("Never log sensitive data"), 오류 상세는 서버 로그로만 | 권한 없는 쓰기로 가는 우회 경로(RR6-01-01). 전송별 로그가 SQL·입력값을 싣는지(RR6-01-05·06). 4xx를 사고로 남기는지 |
### 실행한 명령과 결과
모든 실행은 `git worktree add --detach <scratchpad>/rr6-01 45d2a478`에서 했다. Gradle은 공유 `heavy.lock`으로 감쌌다.
탐침 코드(fixture·테스트)와 결과 파일은 공유 노트 폴더 `rr6-01-probes/`에 그대로 두었다. 고칠 때 fixture로 옮겨 쓸 수 있다.
| 명령 | 결과 | 직전 부하(1분) |
|---|---|---|
| `./gradlew :app-bootstrap:architectureTest --tests …Rr6ProbeTest :app-bootstrap:documentContractTest --tests …Rr6TablePairProbeTest :adapter:inbound:grpc:test --tests …Rr6GrpcProbeTest :adapter:inbound:websocket:test --tests …Rr6StompProbeTest --continue` | 표 대조·gRPC·STOMP 탐침 실행됨. architectureTest 탐침은 내 코드의 Error Prone 경고로 컴파일 실패 | 4.72 |
| `./gradlew :app-bootstrap:architectureTest --tests …Rr6ProbeTest` | rc=0. 탐침 A1~A7 결과는 결함마다 | 4.94 |
| `./gradlew :app-bootstrap:architectureTest --tests …Rr6AllRulesProbeTest` | 첫 실행은 내 탐침이 빈 규칙의 AssertionError를 안 잡아 실패. 고친 뒤 rc=0: 정적 `@ArchTest` 규칙 89개를 함수형 endpoint 설정 두 개에 돌려 위반 0(7개는 대상 클래스 없음) | 4.26 / 2.74 |
| `./gradlew :app-bootstrap:architectureTest --tests …Rr6SharedProbeTest` | rc=0. `dev.caskeleton.shared.rr6bogus` 클래스에 `SHARED_CONTRACT_CONTAINS_ONLY_OPERATIONAL_CONTRACT_PACKAGES` 위반 없음 | 2.39 |
탐침의 모양:
- A1·A2: `@Configuration`(사용자 전송 패키지 밖)이 `RouterFunction` 람다 / graphql-java `DataFetcher` 람다 안에서 `@SystemCaller` 작업을 부른다. 새 규칙과 `c508b1ba` 판정식(설정 제외 없음)을 같은 클래스에 돌렸다. A1c: 같은 route를 `@Component`에 두었다(통제군).
- A3·A7: `@SystemCaller` 안의 중첩 record·enum·예외, record로 쓴 `@SystemCaller`.
- A4: production 클래스 3,415개에서 사용자 전송 570개가 `MessageHandler`에 닿는지.
- A5: RR4-01-02 모양에서 익명 `WebMvcConfigurer`가 설정의 필드를 읽는다.
- A6: 프로젝트 추상 클래스가 `Runnable`을 구현하고 `@SystemCaller`가 그것을 상속한다.
- 표 대조 C0~C5: `TemplatePackageOwnershipDocumentTest`의 `root`를 임시 트리로 바꿔 표만 늘리기, 표에서 빼기(클래스에만 남김), 소유 leaf 바꾸기, 패키지 디렉터리 없애기, domain 표만 늘리기.
- gRPC: 실제 Netty 서버(127.0.0.1, 포트 0)에 `GrpcExceptionHandlingInterceptor`를 걸고 실제 클라이언트로 불렀다.
- STOMP: `StompHandlerFailureLogTest`와 같은 실제 `WebSocketAnnotationMethodMessageHandler`로 `@MessageMapping`이 `IllegalArgumentException`을 던지게 했다.
### 못 본 것
- 멱등성 저장소(store·Lua)와 그 계약 테스트 변경은 02 영역이라 판단하지 않았다. application-core의 executor·enum Javadoc 변경은 읽기만 했다.
- `src/grpc/grpc-operation-ledger-jpa` 변경(r9-c)은 03 영역이라 보지 않았다.
- r9 게이트(`ci`, `mainCheck` 등)는 다시 돌리지 않았다. 탐침은 `--tests`로 좁힌 실행뿐이다.
## 항목 재확인
| ID | 판정 | 근거 |
|---|---|---|
| RR4-01-01 (인터페이스·`Runnable` 주입을 못 봄, 문서가 반대로 적음) | 닫힘 | 대상 술어 `ApplicationBoundaryArchitectureTest.java:555-566`, 새 규칙 `:664-707`, fixture `SystemJobInterfaceInvokingControllerFixture`·`RunnableSystemJobFixture`·`IndirectlyRunnableSystemJobFixture`. 탐침 A6(상위 추상 클래스 경유 `Runnable`)도 잡힌다. 매뉴얼 07 `:118-131`이 못 보는 길(이름 조회, 설정이 넘기는 함수)을 바르게 적는다. 탐침 A4: production 사용자 전송은 `MessageHandler`에 닿지 않아 정석 handler 모양은 거짓 양성이 없다. 새 규칙의 거짓 양성은 RR6-01-03 |
| RR4-01-02 (웹 bean을 함께 만드는 설정의 거짓 양성) | 부분 | 두 모양(`WebMvcConfigurer`, controller bean)은 허용 fixture로 통과한다. 익명 configurer가 설정의 상태를 쓰면 아직 걸린다(RR6-01-02). 고친 방법(설정 통째로 제외)이 새 구멍을 냈다(RR6-01-01) |
| RR3-01-01 (사용자 전송 → `@SystemCaller` 금지, r6에서 닫힘) | 회귀 | 설정 안의 함수형 endpoint가 `@SystemCaller`를 불러도 더는 잡히지 않는다. `c508b1ba` 판정식은 잡았다(RR6-01-01) |
| `graphql..` fixture | 닫힘 | `GraphQlJavaSystemCallerFixture`(graphql 타입 하나만 씀), `ArchitectureViolationFixtureTest.aGraphQlJavaDataFetcherMarkedAsASystemCallerIsCaught`. `app-bootstrap/build.gradle:284` compileOnly, lockfile은 `architectureTestCompileClasspath` 표시만 늘었다 |
| 원래 리뷰 16.3 (템플릿 패키지 목록 두 벌) | 닫힘 | `TemplatePackageOwnershipDocumentTest`. 탐침 C1~C5가 표만·클래스만·소유 leaf·디렉터리 누락·domain 표를 모두 실패시켰고 C0은 통과했다. 목록에 없는 새 템플릿 패키지는 못 잡는다는 한계는 `src/application-core/CLAUDE.md:169-171`에 적혀 있다 |
| RR4-03-03 (gRPC가 회복 필요 실패를 로그에 안 남김) | 닫힘 | carrier 분기 `GrpcExceptionHandlingInterceptor.java:125-130`, 테스트 `aServerSideCarrierIsLoggedAtError…`. runbook `:50-56`에 전송별 상관 정보. gRPC MDC 주장은 인터셉터 순서(`GrpcServerRunner.java:117-133`, correlation이 exception 바깥)로 맞다 |
| r9-a가 새로 고친 것: gRPC `INTERNAL_ERROR` 무기록 | 부분 | 기록은 생겼다. 그러나 "클라이언트 취소" 판정이 틀리고(RR6-01-04), raw status 설명이 던진 경로로 로그에 남는다(RR6-01-05) |
| r9-a가 새로 고친 것: STOMP가 persistence SQL 원인을 로그에 씀 | 닫힘 | `StompHandlerFailureLog.java:31-35`, 실제 method handler 테스트. 다만 IAE를 ERROR로 남긴다(RR6-01-06) |
| web 로그 리팩터링 | 닫힘 | `GlobalExceptionHandler.java:171-183`. persistence(분류만, span 정리)·dependency·5xx·4xx 네 갈래가 전과 같다(E1, 분기 대조) |
## 결함
### RR6-01-01 · Important · 설정을 사용자 전송에서 통째로 빼서, 설정 안의 함수형 endpoint가 `@SystemCaller`를 불러도 잡히지 않는다 (회귀)
- **위치**: `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ApplicationBoundaryArchitectureTest.java:516-519`(설정 제외),
`:497-505`(Javadoc "Leaving it out opens nothing"), `docs/manual/07-authorization.md:105`, `:118-131`(「규칙이 못 보는 길」에 없음),
`docs/upgrade/2026-11-maturity-review.md` B-16.
- **무엇이 틀렸나**:
- r9는 `@Configuration`·`@AutoConfiguration` 클래스를 사용자 전송으로 세지 않는다. 근거는 "설정은 조립 루트지 요청이 들어오는 곳이 아니다"이다.
- Spring MVC 함수형 endpoint(`RouterFunction`)와 graphql-java `DataFetcher`는 요청 처리 코드를 람다로 쓴다. 람다 본문은 그 람다를 쓴 설정 클래스의 메서드로 컴파일된다. 그래서 그 설정 클래스가 곧 endpoint다.
- 탐침 A1: 사용자 전송 패키지 밖 `@Configuration`이 `POST /admin/nightly/run-now` route 람다에서 `@SystemCaller` 작업의 `run()`을 부른다. 새 규칙은 위반 0. `c508b1ba` 판정식은 위반 1. 같은 route를 `@Component`에 두면(A1c) 새 규칙도 위반 1.
- 탐침 A2: GraphQL `runNow` mutation의 `DataFetcher` 람다로 같은 모양. 새 규칙 위반 0, `c508b1ba` 판정식 위반 1.
- 다른 규칙도 막지 않는다. 정적 `@ArchTest` 규칙 89개를 두 설정에 돌려 위반이 0이었다.
- Javadoc은 "설정을 빼도 열리는 길이 없다. 설정이 만드는 controller는 자신이 검사받는다"고 적는다. 매뉴얼 07과 업그레이드 안내도 설정은 걸리지 않는다고만 적는다. 이 길은 「규칙이 못 보는 길」 목록에도 없다.
- **발생 조건·영향**:
- 조건: 파생 서비스가 "지금 실행" endpoint를 함수형으로 쓰고, 그 route 또는 fetcher를 작업과 같은 leaf의 설정 클래스(사용자 전송 패키지 밖)에 둔다. 매뉴얼 07 `:95`는 예약 작업이 controller와 같은 leaf에 놓이기 쉽다고 적는다. 함수형 endpoint는 Spring이 문서로 권하는 방식 가운데 하나다.
- 영향: 인증만 된 사용자 요청이 권한 검사 없는 `@SystemInvoked` 쓰기를 부른다. 빌드는 아무 신호도 내지 않는다. r6에서 막은 RR3-01-01과 같은 피해다.
- Important로 둔 이유: 이 커밋이 만든 회귀다. 문서 세 곳이 이 길이 닫혀 있다고 말한다. 조건은 RR3-01-01·RR4-01-01과 같은 "같은 leaf"라서 Critical·High는 아니다.
- **고치는 법**:
1. 설정 제외에 예외를 둔다. 설정이 요청 처리기를 만드는 타입에 직접 의존하면 사용자 전송으로 센다. 목록 예: `org.springframework.web.servlet.function..`, `org.springframework.web.reactive.function.server..`, `org.springframework.web.HttpRequestHandler`, `org.springframework.web.servlet.HandlerInterceptor`, `org.springframework.web.socket.WebSocketHandler`, `jakarta.servlet.Servlet`, `jakarta.servlet.Filter`, `graphql.schema.DataFetcher`, `org.springframework.graphql.execution.RuntimeWiringConfigurer`, `io.grpc.BindableService`, `io.grpc.ServerServiceDefinition`, `io.grpc.ServerCallHandler`. `WebMvcConfigurer`·`CorsRegistry` 같은 설정용 타입은 넣지 않는다(RR4-01-02 허용 fixture가 계속 통과해야 한다).
2. 위반 fixture 두 개를 더한다: A1(`RunNowRoutesConfiguration`)과 A2(`RunNowDataFetcherConfiguration`). 노트 폴더 `rr6-01-probes/`의 파일을 그대로 쓸 수 있다.
3. Javadoc `:497-505`, 매뉴얼 07 `:105`, 업그레이드 B-16을 "요청 처리기를 만들지 않는 설정"으로 고친다. 목록 방식이라 목록에 없는 endpoint 타입은 못 본다는 것을 「규칙이 못 보는 길」에 한 줄 더한다.
- **이번 커밋/이전부터**: 이번 커밋.
- **증거**: E2 — 탐침 A1·A2·A1c(`Rr6ProbeTest`), 규칙 89개(`Rr6AllRulesProbeTest`).
### RR6-01-02 · Minor · 설정 안의 익명 configurer가 설정의 필드를 쓰면 아직 "사용자 전송"으로 잡힌다 (RR4-01-02 일부 남음)
- **위치**: `ApplicationBoundaryArchitectureTest.java:507-523`, `docs/manual/07-authorization.md:105`
("같은 클래스에서 `WebMvcConfigurer`·interceptor·controller bean을 함께 만들어도 걸리지 않는다").
- **무엇이 틀렸나**:
- 제외는 설정 클래스 자신에만 적용된다. 그 안의 익명 클래스(`Config$1`)는 설정이 아니다.
- 익명 `WebMvcConfigurer`는 웹 타입에 의존하므로 사용자 전송이다. 설정의 필드를 읽으면 바깥 인스턴스(`this$0`)에 의존한다. 설정은 handler bean에 의존한다. 그래서 `Config$1 → Config → handler` 경로가 위반이 된다.
- 탐침 A5: 생성자에서 정한 `allowedOrigin` 필드를 `addCorsMappings`에서 읽는 익명 configurer와 handler bean을 한 설정에 두었다. 위반 1(`FeatureConfigWithAnonymousConfigurer$1 transitively depends on SystemCallerHandlerFixture`).
- 허용 fixture `SystemCallerBesideWebMvcRegistrationFixture`는 빈 익명 클래스라 바깥을 참조하지 않아 통과한다.
- **발생 조건·영향**: `WebMvcConfigurer`는 메서드가 여럿이라 람다로 못 쓰고 익명 클래스로 쓰는 것이 보통이다. 설정 값을 필드로 받아 쓰는 것도 흔하다. 빌드가 실패하고 메시지는 없는 경로를 말한다(실패 쪽으로 틀림). 매뉴얼은 걸리지 않는다고 적는다.
- **고치는 법**: 설정 안에 중첩된 클래스도 설정과 같이 취급한다. 단 RR6-01-01의 "요청 처리기를 만드는 타입" 예외는 똑같이 적용한다(익명 `HandlerInterceptor`·`Filter`는 계속 사용자 전송). 탐침 A5를 허용 fixture로 더한다.
- **이번 커밋/이전부터**: 이번 커밋(RR4-01-02 수정이 덜 끝남).
- **증거**: E2 — 탐침 A5.
### RR6-01-03 · Minor · `SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`가 handler 안의 중첩 record·enum·예외와 record로 쓴 handler를 거부한다 (거짓 양성)
- **위치**: `ApplicationBoundaryArchitectureTest.java:664-707`(규칙과 조건), `:660-661`(익명·지역 클래스만 뺀 이유), `docs/manual/07-authorization.md:106`.
- **무엇이 틀렸나**:
- 규칙은 `@SystemCaller` 클래스와 그 안에 중첩된 모든 이름 있는 클래스에 "프로젝트 밖 상위 타입 금지"를 건다.
- 중첩 record는 `java.lang.Record`, 중첩 enum은 `java.lang.Enum`·`Comparable`·`Serializable`·`Constable`, 중첩 예외는 `RuntimeException`·`Throwable`·`Serializable`을 상위 타입으로 가진다. 모두 위반이다(탐침 A3, 세 건). record로 쓴 `@SystemCaller`도 위반이다(A7).
- 규칙이 익명·지역 클래스를 빼는 이유는 "그 타입의 bean이 없다"이다. record·enum·예외 값도 bean이 아니고, 아무 endpoint도 그것을 `Record`·`Enum`·`Throwable`로 주입받지 않는다. 같은 이유가 적용되는데 빠지지 않았다.
- 위반 메시지는 "endpoint가 그 타입으로 주입받으면 보이지 않는다"고 말한다. 이 경우에는 맞지 않는다.
- **발생 조건·영향**: handler 안에 파싱 결과 record, 결과 enum, 독(poison) 메시지 예외를 두는 것은 흔한 모양이다. 빌드가 실패하고 개발자는 그 타입을 밖으로 옮겨야 한다. 권한 구멍은 아니다(실패 쪽).
- **고치는 법**: 조건 대상에서 record·enum·`Throwable` 하위 클래스를 뺀다(`isRecord`/`isEnum`/`isAssignableTo(Throwable.class)`). 표시한 클래스 자신의 상위 클래스 `java.lang.Record`는 `Object`처럼 무시한다. A3·A7을 허용 fixture로 더한다. 매뉴얼 07 `:106`의 "(익명·지역 클래스 제외)"를 "(익명·지역 클래스와 record·enum·예외 제외)"로 고친다.
- **이번 커밋/이전부터**: 이번 커밋.
- **증거**: E2 — 탐침 A3·A7.
### RR6-01-04 · Minor · gRPC가 "클라이언트 취소"를 status 코드로 판정해, 서비스가 `CANCELLED`로 끝낸 살아 있는 호출의 `INTERNAL_ERROR`를 아무 데도 남기지 않는다
- **위치**: `src/adapter/inbound/grpc/src/main/java/dev/caskeleton/adapter/inbound/grpc/GrpcExceptionHandlingInterceptor.java:146-149`,
Javadoc `:41-43`, `src/adapter/inbound/grpc/README.md:158`, 업그레이드 안내 "서버 로그" 행("클라이언트 취소 제외"),
테스트 `GrpcExceptionHandlingInterceptorTest.java:227-240`과 `:336-338`(`isCancelled()`가 늘 `false`).
- **무엇이 틀렸나**:
- `logUnrecognised`는 `status.getCode() == CANCELLED`이면 남기지 않는다. 이 코드는 "이 호출의 클라이언트가 취소했다"가 아니라 "서비스가 넘긴 status가 CANCELLED다"를 뜻한다.
- 서비스가 하위 gRPC 호출에서 받은 `CANCELLED`(프록시의 RST_STREAM CANCEL 등)를 그대로 던지거나 `onError`로 넘기면, 클라이언트는 기다리는 중인데 `INTERNAL_ERROR`를 받고 로그는 한 줄도 없다.
- 탐침(실제 Netty): `ErrorsCancelled`(`onError(CANCELLED)`)와 `ThrowsCancelled`(`throw CANCELLED`) 둘 다 클라이언트는 `INTERNAL`, 로그 0줄. 서버 쪽 `isCancelled()`는 `false`였다. 진짜 클라이언트 취소(`Slow` + `future.cancel`)는 `isCancelled()`가 `true`, 로그 0줄.
- 테스트 `aCallTheClientCancelledIsNotLogged`는 서비스가 `close(CANCELLED)`를 부르고 `isCancelled()`가 `false`인 호출을 만든다. 이름은 클라이언트 취소인데 보는 것은 서비스가 낸 CANCELLED다. 이 결함을 고정하는 테스트다.
- **발생 조건·영향**: 이 커밋이 닫으려던 문제("`INTERNAL_ERROR` 실패를 아무 데도 남기지 않음")가 이 경로에 남는다. 운영자는 `INTERNAL_ERROR` 응답을 보고도 서버 로그에서 원인을 못 찾는다.
- **고치는 법**: `close()`에서 `delegate.isCancelled()`로 판정한다(호출 자체가 취소됐을 때만 남기지 않음). 테스트 둘로 나눈다: `CapturingServerCall.isCancelled()`가 `true`인 호출은 남기지 않고, `false`인 호출에서 서비스가 `CANCELLED`로 끝내면 `unhandled failure … (status=CANCELLED)`로 남긴다. Javadoc·README·업그레이드 문구를 "클라이언트가 취소한 호출"로 맞춘다.
- **이번 커밋/이전부터**: 이번 커밋.
- **증거**: E3 — 실제 Netty 서버·클라이언트 탐침(`Rr6GrpcProbeTest`).
### RR6-01-05 · Minor · gRPC 서비스가 raw status를 던지면 그 설명(입력값이 든)이 로그에 남는다 — 문서는 "남기지 않는다"고 적는다
- **위치**: `GrpcExceptionHandlingInterceptor.java:142-144`(`closeWithError`가 `withCause(exception)`), `:150-157`(cause를 예외로 붙임),
Javadoc `:40-41`, `src/adapter/inbound/grpc/README.md:157-158`("raw status만 있으면 description은 남기지 않는다(입력이 들 수 있다)").
- **무엇이 틀렸나**:
- 서비스가 `onError(Status.X.withDescription(d).asRuntimeException())`로 끝내면 status에 cause가 없어 코드만 남는다.
- 같은 status를 `throw`하면 인터셉터가 그 예외를 cause로 붙인다. `StatusRuntimeException`의 메시지는 `코드: 설명`이라서 설명이 예외 메시지로 로그에 남는다.
- 탐침(실제 Netty): `ThrowsRawStatus`는 `throwable: INVALID_ARGUMENT: no customer with email alice@example.com`. `ErrorsRawStatus`는 같은 설명이 로그에 없다.
- grpc-java에서 `throw Status.X.withDescription(...).asRuntimeException()`은 흔한 관용구다. 테스트 `aRawStatusWithoutACauseIsLoggedByItsCodeAlone`은 `close` 경로만 본다.
- **발생 조건·영향**: 서비스가 입력값을 설명에 넣고 던지면 개인정보가 ERROR 로그(prod JSON의 `stack_trace`)에 남는다. 마스킹 decorator는 비밀 형식(토큰·비밀번호)만 가린다. 문서 주장과 코드가 다르다. 이 로그 줄 자체가 이 커밋에서 생겼다.
- **고치는 법**: `logUnrecognised`에서 cause가 `StatusRuntimeException`·`StatusException`이면(즉 cause가 raw status 자신이면) 그것을 붙이지 않는다. 그 예외에 다시 cause가 있으면 그 cause만 붙인다. 테스트: handler가 설명에 입력값을 넣은 status를 던지면 로그 줄과 예외 어디에도 설명이 없다.
- **이번 커밋/이전부터**: 이번 커밋.
- **증거**: E3 — 실제 Netty 탐침(`ThrowsRawStatus` / `ErrorsRawStatus`).
### RR6-01-06 · Minor · STOMP `@MessageMapping`의 `IllegalArgumentException`을 ERROR로, 메시지(입력값)까지 남긴다 — 다른 전송은 모두 클라이언트 쪽 `BAD_PARAMETER`로 본다
- **위치**: `src/adapter/inbound/websocket/src/main/java/dev/caskeleton/adapter/inbound/websocket/stomp/StompHandlerFailureLog.java:31-38`,
Javadoc `:17-20`, `src/adapter/inbound/websocket/README.md:37-39`.
비교: `GlobalExceptionHandler.java:97`(web: WARN, 클래스 이름만), `GraphQlWireErrorMapper.java:115-121`·`:188-189`(GraphQL: `BAD_PARAMETER`, 남기지 않음),
`GrpcExceptionHandlingInterceptor.java:131-132`(gRPC: 남기지 않음), `SafeStompSubProtocolErrorHandler.java:52`(STOMP 프레임: `BAD_PARAMETER`),
`src/shared-contract/README.md:81`("`IllegalArgumentException`은 모든 전송에서 `BAD_PARAMETER`").
- **무엇이 틀렸나**:
- advice는 carrier가 아니면 모두 `unhandled failure in a STOMP message handler`로 ERROR에 예외를 붙여 남긴다. IAE도 여기로 간다.
- 탐침: `throw new IllegalArgumentException("unknown recipient alice@example.com")` → `ERROR … | throwable: java.lang.IllegalArgumentException: unknown recipient alice@example.com`.
- web은 이 경우 메시지를 일부러 빼고 클래스 이름만 WARN으로 남긴다. GraphQL·gRPC는 남기지 않는다. advice의 Javadoc은 "클라이언트 쪽 거절을 오류로 남기던 것"을 고쳤다고 적는다.
- **발생 조건·영향**: 잘못된 입력 하나마다 ERROR 줄과 스택이 생기고, 입력값(이메일 등)이 로그에 남는다. "모든 전송이 같은 줄"이라는 r9 주장과 다르다.
- **고치는 법**: advice가 IAE를 `BAD_PARAMETER`로 보고 `ServerFailureLog.of(failure, OperationalError.BAD_PARAMETER)`를 쓴다(결과: 남기지 않음). web의 WARN 한 줄까지 맞추려면 "IAE → `BAD_PARAMETER`" 줄을 `ServerFailureLog`에 두고 네 전송이 같이 쓴다. STOMP 테스트에 IAE 경우를 더한다.
- **이번 커밋/이전부터**: 이번 커밋(advice가 새로 생김). web의 WARN 줄과 GraphQL·gRPC의 무기록이 다른 것은 이전부터.
- **증거**: E2 — `Rr6StompProbeTest`(실제 STOMP method handler).
### RR6-01-07 · Minor · runbook이 lease 만료 시작 거절의 문구를 "ERROR 줄의 message"에 있다고 적는다 — 실제로는 붙은 예외의 메시지다
- **위치**: `docs/runbooks/idempotency-unavailable.md:21-23`("The ERROR line's message then reads `the claim's processing lease ran out …`"), `:101`("When the message says …").
- **무엇이 틀렸나**:
- 그 거절은 `IdempotencyUnavailableException`(503)이다. 로그 줄의 message는 `ServerFailureLog`가 정한 `failure classified as IDEMPOTENCY_UNAVAILABLE (category=…, retryable=true)`다.
- "the claim's processing lease ran out …" 문구는 붙은 예외의 메시지다. prod 로그는 `LogstashEncoder`(`src/app-bootstrap/src/main/resources/logback-spring.xml:87`)라서 이 문구는 `message`가 아니라 `stack_trace` 필드에 있다.
- 같은 runbook의 `IDEMPOTENCY_RECOVERY_REQUIRED` 설명(`:51-61`)은 "예외가 붙고, 예외 메시지 끝에 digest"라고 바르게 적는다.
- **발생 조건·영향**: 운영자가 `message` 필드로 검색하면 찾지 못한다. "저장소는 멀쩡하다"는 판단의 근거를 놓치고 저장소 장애를 쫓는다.
- **고치는 법**: `:21-23`을 "the line has the exception attached; its message reads …"로, `:101`을 "When the exception message says …"로 고친다.
- **이번 커밋/이전부터**: 이번 커밋.
- **증거**: E1 — `IdempotencyExecutor.java:198-201`, `ServerFailureLog.java:66-71`, `logback-spring.xml:87` 대조.
### RR6-01-08 · Minor · GraphQL 테스트 `aClientSideCarrierIsNotLogged`가 carrier가 아니라 `IllegalArgumentException`을 넣는다
- **위치**: `src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/error/GraphQlWireErrorMapperTest.java:193-206`.
- **무엇이 틀렸나**: 이름은 "클라이언트 쪽 carrier는 남기지 않는다"인데 입력은 `new IllegalArgumentException("bad cursor")`다. `sharedCodeOf`의 carrier 분기(`failure instanceof ApiErrorCarrier`)가 아니라 IAE 분기를 지난다. 4xx carrier가 남지 않는다는 것은 이 테스트가 보지 않는다. gRPC·STOMP의 같은 이름 테스트는 실제 4xx carrier를 쓴다.
- **발생 조건·영향**: carrier 분기에서 로그 조건이 바뀌어도 이 테스트는 통과한다.
- **고치는 법**: 4xx carrier(예: 테스트 안의 작은 carrier에 `OperationalError.BAD_PARAMETER`, 또는 `IdempotencyInFlightException`)로 바꾼다. IAE 경우는 이름을 맞춘 별도 테스트로 남긴다.
- **이번 커밋/이전부터**: 이번 커밋.
- **증거**: E1 — 테스트 코드와 `GraphQlWireErrorMapper.java:184-190` 대조.
### RR6-01-09 · Minor · (이전부터) `SHARED_CONTRACT_CONTAINS_ONLY_OPERATIONAL_CONTRACT_PACKAGES`는 shared-contract 안에서 아무것도 잡지 못한다 — 코드에 "KNOWN DEFECT"로 남아 있다
- **위치**: `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ForbiddenApiArchitectureTest.java:98-114`(주석 "KNOWN DEFECT, deliberately left as found"), `:52-72`(허용 목록), `:78-80`(접두어 비교).
- **무엇이 틀렸나**:
- 허용 목록에 모듈 뿌리 `dev.caskeleton.shared`가 있고 비교는 접두어다. 그래서 `dev.caskeleton.shared` 아래 모든 패키지가 허용된다.
- 탐침: `dev.caskeleton.shared.rr6bogus.BusinessRuleInShared`(업무 규칙 흉내)에 위반이 없다.
- 지금 shared-contract의 `digest`·`observability`·`ratelimit`·`retry`·`runtime` 패키지는 목록에 없는데도 통과한다. 목록이 이미 실제와 다르다는 뜻이다.
- 대상 술어 `..shared..`는 모듈과 무관한 `…tenancy.shared` 같은 패키지를 잡아 목록에 예외(`:65`)를 늘렸다. 주석이 스스로 두 잘못을 적고 고치기를 미뤘다. 이 리뷰 시리즈의 README·라운드 문서 어디에도 기록되지 않았다(`docs/reviews/2026-11-0*` grep 0건).
- **발생 조건·영향**: shared-contract에 업무 개념 패키지가 생겨도 빌드가 모른다. CLAUDE.md 표는 shared-contract를 "Skeleton-wide operational contracts"로 묶는다. 이 규칙이 그 경계의 유일한 패키지 검사다. 소유자 지시("남은 문제 0")와도 어긋난다.
- **고치는 법**: 대상을 `dev.caskeleton.shared..`로 좁힌다. 허용은 정확히 같은 패키지 또는 그 아래로 하되 뿌리는 뿌리 자체(`package-info`)만 허용한다. 지금 있는 패키지 중 계약인 것을 목록에 넣는다(`digest`·`observability`·`ratelimit`·`retry`·`runtime`은 shared-contract CLAUDE.md "Responsibility"에 근거가 있다). `…tenancy.shared` 예외는 지운다. 위반 fixture는 `TemplatePackageOwnership`처럼 뿌리를 매개변수로 받는 판정식으로 fixture 뿌리에서 증명한다(주석이 미룬 이유 "fixture가 규칙의 분석 범위에 들어간다"를 이 방법이 푼다).
- **이번 커밋/이전부터**: 이전부터(`1400dc15` 이전, 2026-08 wave0 baseline에 처음 기록).
- **증거**: E2 — `Rr6SharedProbeTest`. E1 — 허용 목록과 `src/shared-contract/src/main/java/dev/caskeleton/shared/` 디렉터리 대조.
## Declined to judge
- 감싼 carrier: web·GraphQL·STOMP는 맨 위 예외만 carrier로 보고, gRPC는 원인 사슬을 따라간다(`carrierOf`). 그래서 다른 예외에 감싼 `PersistenceFailureException`은 web·GraphQL·STOMP에서 "unhandled"로 SQL 원인과 함께 남고 gRPC에서는 분류만 남는다. 이전부터의 차이다. 템플릿 코드에서 carrier를 감싸 던지는 곳은 찾지 못했고(GraphQL은 Spring이 `CompletionException`을 벗긴다), 현실 조건을 세우지 못해 판단하지 않았다.
- `DependencyFailureException`과 그 밖의 5xx carrier는 모든 전송에서 원인 사슬째 남는다. web은 전부터 그랬고 이번에 다른 전송으로 넓어졌다. 의존 클라이언트 예외 메시지가 자격 증명·URL을 싣는지는 클라이언트마다 달라 판단하지 않았다(마스킹 decorator가 알려진 비밀 형식은 가린다).
- GraphQL은 실패한 필드마다 한 줄을 남긴다. 키 N개가 5xx batch 코드로 실패하면 ERROR 줄도 N개다. 필드 단위 오류 설계의 결과이고 양은 재지 않았다.
- `docs/upgrade/2026-11-maturity-review.md` B-34가 템플릿 패키지 이름을 다시 나열한다(세 번째 복사본). 그 릴리스 시점의 변경 기록이라 갈라진 복사본으로 보지 않았다.
- STOMP에서 payload 변환·검증 실패(`MessageConversionException`, `MethodArgumentNotValidException`)는 여전히 ERROR로 남는다. 전에도 Spring이 그렇게 남겼고, STOMP 프레임 매핑도 이것을 클라이언트 코드로 분류하지 않아 RR6-01-06에 넣지 않았다.
- RR6-01-01 고치는 법의 endpoint 타입 목록이 완전한지는 확인하지 않았다. 목록 방식의 한계는 기존 `ARE_USER_TRANSPORT_TYPES`와 같다.
- 규칙 89개 탐침은 정적 `@ArchTest` 필드만 돌렸다. 이 스위트들에 메서드형 `@ArchTest`는 없다(grep).
## 결론
- 결함 9건: Important 1, Minor 8. 이번 커밋 8건, 이전부터 1건(RR6-01-09).
- 회귀 1건: `@Configuration` 제외(RR4-01-02 수정)가 RR3-01-01이 막은 "사용자 요청 → 시스템 호출자" 길을 함수형 endpoint에 다시 열었다(RR6-01-01). 가장 먼저 고칠 것이다.
- 닫힘: RR4-01-01, `graphql..` fixture, 원래 리뷰 16.3(세 방향 모두 탐침으로 확인), RR4-03-03, STOMP SQL 원인 기록, web 로그 리팩터링.
- 부분: RR4-01-02(익명 configurer 거짓 양성, RR6-01-02), gRPC `INTERNAL_ERROR` 기록(RR6-01-04·05).
- 판정: With fixes.
@@ -0,0 +1,231 @@
# 02 멱등성·outbound r9 리뷰 (2026-11-05)
대상: 수정 커밋 `45d2a478`(Base `c508b1ba`)의 r9-b 묶음 — CLAIMED → 시작의 lease, RR5-01-02~05, RR5-03-01,
RR4-03-01·02·04 — 와 README 16.1절의 httpclient drain 스레드 수정. 결함 ID 접두어 `RR6-02-`.
## 범위
### pathspec
```
src/application-core/src/main/java/dev/caskeleton/application/idempotency src/application-core/src/testFixtures
src/application-core/src/test src/adapter/outbound/cache-redis
src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/idempotency
src/adapter/outbound/persistence-jpa/src/test src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest
src/adapter/outbound/httpclient src/adapter/outbound/redis-runtime src/composition/idempotency src/.env.example
docs/web/http-contract.md docs/manual/05-idempotency.md docs/runbooks/idempotency-unavailable.md
docs/registries/env-keys.yaml
```
`git diff c508b1ba..45d2a478 -- <pathspec>`: 33파일, +1445 −115. 의미가 바뀐 공개 설명을 따라가느라 pathspec 밖
파일도 읽었다: `src/adapter/inbound/web/README.md`, `docs/upgrade/2026-11-maturity-review.md`,
`src/shared-contract/.../ServerFailureLog.java`, `src/app-bootstrap/src/main/resources/logback-spring.xml`,
`infra/redis-sdk/acl/*`, `docs/registries/error-codes.yaml`.
### 불러온 스킬과 적용한 기준
| 스킬 | 적용한 기준 | 무엇을 봤나 |
| --- | --- | --- |
| `superpowers:requesting-code-review` | 리뷰어 템플릿: 이 커밋이 만든 결함과 "고쳤다"는 주장의 닫힘을 따로, 심각도별, file:line 근거 | 항목 재확인 표, 결함 5건 |
| `api-and-interface-design` | 멱등 키 절: 원자적 claim, 처리 중 중복에 대한 의도된 응답, 결과는 성공·실패·불명 셋, 실패 의미 일관성(값 하나에 뜻 하나), Hyrum's Law(관찰되는 동작 변화는 계약 변화) | `LEASE_EXPIRED`가 두 저장소에서 같은 순서·같은 경계로 판정되는지, executor의 503이 "실행 안 됨"과 맞는지, 같은 attempt 재시도의 결과(RR6-02-01), 새 enum 값의 공개 영향(B-41) |
| `performance-optimization` | 측정 전후, 회귀 장치가 실제로 회귀를 잡는가, 스레드·큐 비용 | watchdog 스레드의 유휴 종료가 read당 비용을 바꾸지 않는지(코드), 유휴 종료 직후 새 예약이 고립되지 않는지(JDK 탐침 4만 회), RR4-03-01 RED 단언이 기계와 무관한지 |
| `doubt-driven-development` | 주장마다 반증을 먼저 시도. 하위 에이전트 금지라 fresh-context 리뷰어 대신 스스로 반대 논증을 세웠다(성능 저하된 단독 모드). 비대화 맥락이라 cross-model 검토는 하지 않았다 | "두 저장소 판정이 같다", "runbook 삭제가 원자적이고 ACL과 맞다", "watchdog 경쟁이 안전하다", "공유 계약이 세 구현에서 돈다"를 각각 실 Redis·실 PG·JDK 탐침으로 반증 시도. 결함마다 반대 논증을 적었다 |
### 실행한 명령과 결과
모두 별도 worktree(`git worktree add --detach <scratchpad>/rr6-02/wt 45d2a478`)에서, Gradle·Docker는 공유 잠금
`flock …/heavy.lock`으로 감쌌다.
1. 실 Redis 7.4 + `infra/redis-sdk/acl/lane-fixture-accounts.acl`(부하 3.25). runbook의 두 줄을 파일에서 그대로
꺼내 `redis-cli`에 넣었다(`probe/runbook-redis.sh`). advanced 계정: `SCRIPT LOAD` 성공, `ABANDONED` 기록에
`EVALSHA` → `1`·키 삭제, `EXECUTING` 기록 → `0`·상태 유지, 없는 키 → `0`, `EVAL` → `NOPERM`, 스크립트 캐시를
비운 뒤 → `NOSCRIPT`·삭제 없음. application 계정: `SCRIPT LOAD`·`EVALSHA` 모두 `NOPERM`.
2. `:adapter:outbound:cache-redis:test --tests '*RedisIdempotencyStoreContractTest' --tests '*RedisIdempotencyStoreAdapterTest'`
— worktree에서 `RedisIdempotencyStoreContractTest`에 `elapse → commands.advance(duration)` 3줄을 넣은 탐침
(부하 3.84). 계약 31 통과·skip 0, adapter 34 통과. 탐침은 되돌렸다.
3. 원래 코드로 `:adapter:outbound:cache-redis:test --tests '*RedisIdempotencyStoreContractTest' :application-core:test --tests '*idempotency*' :adapter:outbound:httpclient:test --tests '*ReadIdleInputStreamTest' --tests '*ClientRuntimeRegistryTest'`
(부하 4.11) — 모두 통과. command fake 계약 31 중 17 skip, in-memory fake 계약 31 중 17 skip,
`IdempotencyExecutorTest` 17, `ReadIdleInputStreamTest` 10, `ClientRuntimeRegistryTest` 4.
4. `java StpeRace.java 200 20000`, `java StpeRace.java 50 20000` — watchdog과 같은 설정(core 1,
`allowCoreThreadTimeOut`, keep-alive 200µs/50µs)의 실행기에 worker가 유휴 종료하는 순간 근처로 예약을 4만 번
넣었다. 고립된 예약 0, 최대 대기 5 ms, 스레드가 없는 상태에서 시작한 회차 4,823/350.
5. 실 Redis 7.4에서 출하 `CLAIM`·`TRANSITION` 프로그램을 `SCRIPT LOAD`+`EVALSHA`(advanced 계정)로 실행
(`probe/retained.sh`, 부하 2.81): 같은 attempt가 lease 1s를 넘긴 뒤 재시도 3회 모두 `REPLAYED_ACQUIRE` →
`LEASE_EXPIRED`, 새 attempt는 `TAKEN_OVER 2`(RR6-02-01).
6. `:adapter:outbound:cache-redis:redisContainerContractTest :adapter:outbound:persistence-jpa:postgresqlIdempotencyIntegrationTest`
(부하 3.37, 잠금 대기 약 10분 뒤 1분 14초) — live Redis lane 72 통과·skip 0(그중 `LiveRedisIdempotencyStoreContractTest`
31, `LiveRedisIdempotencyRunbookTest` 2), PG 멱등성 통합 10 통과.
7. `:adapter:outbound:persistence-jpa:jpaPlatformContractTest --tests '*PostgreSqlIdempotencyStoreContractTest'`
(부하 3.58) — 31 통과·skip 0(33초).
8. executor + Redis adapter + command fake 탐침 테스트(`Rr602RetainedAttemptProbeTest`, 부하 2.37): 같은 attempt
재시도 3회와 1시간 뒤 모두 503 `IDEMPOTENCY_UNAVAILABLE`, 새 attempt는 작업을 한 번 실행. 탐침 파일은 지웠다.
9. `java F.java` — JDK 21.0.12의 `Thread`에 `inheritedAccessControlContext` 필드가 있음을 확인(Declined 참고).
### 못 본 것
- pathspec 안의 r9-c 파일(`PostgreSqlMigrationLockWaitIntegrationTest`, `LockWaitMigrationInspectorTest`,
`VersionedMigrationFilesTest`)은 영역 03(persistence) 몫이라 깊게 보지 않았다.
- `httpclient`의 `httpClientPerformanceTest`·`httpClientFailureInjectionTest`는 다시 돌리지 않았다.
- 16.1절의 RED 주장(옛 `ClientRuntimeRegistry`에서 새 테스트 실패)은 다시 돌리지 않았다. 옛 코드가 scheduler를
멈추기 전에 예외를 던지므로 결정적으로 실패한다(코드 읽기).
- Redis cluster에서 runbook의 `NOSCRIPT` 절차는 실행하지 않았다(standalone만).
- 짝 프론트 repo 문서는 보지 않았다.
## 항목 재확인
| ID | 판정 | 근거 |
| --- | --- | --- |
| README 15 남음 — CLAIMED → 시작에서 PG는 lease를 보고 Redis는 보지 않음 | 닫힘 | Redis `IdempotencyScripts.java:155-162`, PG `PostgreSqlIdempotencyStore.java:197-204`·`IdempotencyTransitionGateway.java:42`, fixture `InMemorySemanticRedisCommands.java:280-283`, 계약 `IdempotencyStoreContract.java:731-771`(실 PG·실 Redis 모두 통과, 명령 6·7), executor `IdempotencyExecutor.java:195-201`. 두 저장소 모두 서버 시계로 `now ≥ leaseUntil`이면 만료(claim과 같은 경계), 이미 적용된 시작의 재시도(`ALREADY`)는 lease보다 먼저 판정. 같은 attempt 재시도는 RR6-02-01 |
| RR5-01-02 renew·inspect 값의 뜻 | 닫힘 | `IdempotencyRenewOutcome.java:4-35`, PG `:240-246`, Redis `IdempotencyScripts.java:235-240`, fixture `:327-332`, 계약 `:709-727`(`LEASE_EXPIRED` + 빈 owner). `ABANDONED`는 Javadoc 유지(권고안 중 하나)와 executor 주석 `:171-175` |
| RR5-01-03 포트 Javadoc "마지막 보고" | 닫힘 | `IdempotencyStorePort.java:12-23`, 계약 `:381-405`. 저장소·문서에 "last report" 문구 남지 않음(grep) |
| RR5-01-04 늦은 실패 경로 | 닫힘 | 계약 `:617-685`(실 PG·실 Redis 통과), adapter `RedisIdempotencyStoreAdapterTest.java:410-445`. 두 fake 위 시간 케이스 skip은 RR6-02-02 |
| RR5-01-05 PG 기본 모양 | 닫힘 | `http-contract.md:123-141`, `manual/05-idempotency.md:59-70`, runbook `:40-43`, `PostgreSqlIdempotencyIntegrationTest`의 두 새 테스트(명령 6). 매뉴얼 첫 문장은 RR6-02-05 |
| RR5-03-01 `APP_IDEMPOTENCY_TTL` 상한 안내 | 닫힘 | `env-keys.yaml:1603-1616`, `module-defaults/idempotency.yml:15-19`, `composition/idempotency/README.md:48`·`:76`, `.env.example:124-125`. `IdempotencySettings`의 `<` 비교와 문서의 "이하"가 같다 |
| RR4-03-01 watchdog RED 테스트가 병렬도 1에서 무력 | 닫힘 | `ReadIdleInputStreamTest.java:114`(닫은 스레드 이름 단언 — 옛 코드는 공용 풀이나 `Thread-N`에서 닫는다) |
| RR4-03-02 Redis 삭제가 두 명령 | 닫힘 | runbook `:126-145`, `LiveRedisIdempotencyRunbookTest`(명령 6), 실 `redis-cli`로 블록 그대로 실행(명령 1). Lua 한 번이라 확인과 삭제 사이 틈이 없다. ACL: advanced 계정에 `script|load`·`evalsha`가 있고 `eval`이 없음과 맞다 |
| RR4-03-04 watchdog 스레드 수명 | 닫힘 | `ReadIdleInputStream.java:51-59`·`:101-134`, 테스트 `:160-243`. 유휴 종료 직후 예약 경쟁은 JDK `processWorkerExit`가 큐를 다시 보고 worker를 만든다 — 명령 4에서 고립 0 |
| README 16.1 drain 스레드 join·예외 순서 | 닫힘 | `ClientRuntimeRegistry.java:148-195`: 런타임 실패가 먼저, scheduler 정지 실패는 suppressed. `awaitTermination` 뒤 같은 마감 안에서 join. 테스트 `ClientRuntimeRegistryTest.java:63-83` |
## 결함
### RR6-02-01 · Minor · 시작을 `LEASE_EXPIRED`로 거절당한 attempt는 같은 attempt로 다시 보내도 영원히 503이다
- **위치**: `src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/idempotency/IdempotencyScripts.java:82-89`
(CLAIM이 같은 owner·operation을 lease보다 먼저 `REPLAYED_ACQUIRE`로 답함), `:155-162`(시작 거절),
`src/adapter/outbound/persistence-jpa/.../postgresql/PostgreSqlIdempotencyStore.java:141-143`,
`src/application-core/.../idempotency/IdempotencyExecutor.java:142-143`·`:198-201`. 약속하는 문서:
`docs/web/http-contract.md:111`, `docs/manual/05-idempotency.md:72-73`, `src/application-core/README.md:274-275`.
- **무엇이 틀렸나**:
- 시작을 `LEASE_EXPIRED`로 거절당한 claim은 `CLAIMED`로 남는다.
- 같은 attempt(같은 owner token·operation id)로 다시 claim하면 CLAIM은 lease를 보기 전에 `REPLAYED_ACQUIRE`로
답한다. PG도 `sameClaimAttempt`가 만료 검사(`:147`)보다 앞이다.
- executor는 `ReplayedAcquire`를 `Acquired`처럼 시작으로 보낸다. 시작은 다시 `LEASE_EXPIRED`다.
- 그래서 그 attempt를 쥔 호출자는 기록이 사라질 때까지(lease + `replay-ttl`, 기본 약 24h) 매번 503을 받는다.
- 문서의 "다음 같은 키 요청이 그 claim을 넘겨받아 실행한다"는 새 attempt에만 맞다.
- **발생 조건·영향**:
- API는 attempt를 재시도 사이에 유지하라고 한다: `IdempotencyClaimAttempt` "Caller-retained identity for one
claim send/retry sequence", `IdempotencyExecutor#newAttempt` "retains across a lost response".
- 503은 `retryable=true`다. attempt를 유지하는 호출자(재시도 래퍼, 메시지 소비자)는 같은 attempt로 다시 보낸다.
- 템플릿 안의 호출자(`PublishPosterImageUseCase.java:106`)는 요청마다 새 attempt를 만들어 해당하지 않는다.
HTTP 재전송은 서버에서 새 attempt가 되어 HTTP 계약은 지켜진다.
- 중복 실행은 없다. 진행이 막힌다. 이 커밋 전에는 Redis가 그 claim을 시작해 실행했다.
- PG를 쓰기 트랜잭션 하나로 쓰면 503과 함께 기록이 롤백되어 해당하지 않는다. 호출마다 트랜잭션을 여는
모양에서는 같다.
- **고치는 법**(둘 중 하나를 정한다):
- (a) 두 저장소 claim에서 "lease가 지난 `CLAIMED`는 같은 attempt라도 넘겨받는다". Redis CLAIM의
`state == 'CLAIMED' and leaseOver` 분기를 `owner == ARGV[1]` 분기 앞으로, PG `claim`의 `:147` 검사를
`:141` 앞으로 옮긴다. 답은 `TakenOverClaimed`(attempt+1, 새 lease). command fake도 같게. 공유 계약에 "시작을
거절당한 attempt가 같은 attempt로 다시 claim하면 넘겨받아 시작한다" 케이스를 더한다. 주의: 같은 attempt의 멈춘
첫 호출이 나중에 시작을 보내면 Redis TRANSITION은 상태가 이미 `EXECUTING`일 때 revision을 보지 않고
`ALREADY`로 답한다(`:138-146`). 같은 attempt를 동시에 쓰는 이전부터의 위험(5차 리뷰 Declined)과 같은 것이다.
- (b) 동작을 두려면 `IdempotencyClaimAttempt`·`IdempotencyExecutor#newAttempt` Javadoc과 executor 메시지
(`:199-201`)에 "`LEASE_EXPIRED`로 거절된 attempt는 다시 쓰지 않고 새 attempt를 만든다"를 적는다. 문서 세 곳의
"다음 같은 키 요청"을 "다음 같은 키 요청(새 attempt)"으로 좁힌다. 공유 계약에 지금 동작을 고정하는 케이스를 둔다.
- **반대 논증**: attempt는 응답을 잃었을 때만 유지하고 명시적 거절 뒤에는 새로 만드는 것이 의도라면, 동작이 아니라
문서 누락이다. 그 의도는 어디에도 적혀 있지 않고, 503은 재시도하라고 말한다.
- **이번 커밋**. 가이드 심각도 Low · P3.
- **증거**: E3 — 실 Redis에서 출하 Lua(명령 5). E3 — executor까지 command fake 위에서(명령 8). PG는 E1(코드).
### RR6-02-02 · Minor · command fake 위 공유 계약이 시계를 움직일 수 있는데도 시간 케이스 17개를 skip한다
- **위치**: `src/application-core/src/testFixtures/.../testkit/IdempotencyStoreContract.java:64-69`(Javadoc),
`src/adapter/outbound/cache-redis/src/test/.../idempotency/RedisIdempotencyStoreContractTest.java:17-37`
(`elapse` override 없음), `src/adapter/outbound/redis-runtime/src/testFixtures/.../InMemorySemanticRedisCommands.java:44`
(`advance`), `RedisIdempotencyStoreAdapterTest.java:357-445`(손 사본).
- **무엇이 틀렸나**:
- 계약 Javadoc은 command fake 위 Redis store를 "시계를 움직일 수 없는 store"로 묶어 기본 `elapse`(abort)를 쓴다고 적는다.
- command fake는 `advance(Duration)`로 시계를 움직인다. adapter 테스트가 그것으로 시간 케이스를 손으로 다시 쓴다.
- 그래서 `RedisIdempotencyStoreContractTest`는 시간 케이스 17개를 skip한다. adapter 테스트는 그중 일부만 복사한다.
이 커밋이 사본을 4건 더 늘렸다(`:373-445`).
- 사본이 없는 시간 케이스(`aClaimMeetingAnExpiredExecutionLeavesTheRecordToItsHolder`,
`anExpiredExecutionsHolderCanStillReportAnUnknownEffect`, `aRenewedLeaseOutlivesItsFirstExpiry` 등)에서는
fixture의 Lua 사본이 단위 수준에서 검사되지 않는다.
- **발생 조건·영향**: fixture가 Lua와 갈라지면 단위 테스트가 못 잡는다. 실 Lua는 `redisContainerContractTest`가
잡으므로 운영 동작 피해는 없다. 잃는 것은 fixture를 쓰는 테스트의 신뢰도다.
- **고치는 법**: `RedisIdempotencyStoreContractTest`가 만든 `InMemorySemanticRedisCommands`를 필드로 두고
`elapse`에서 `commands.advance(duration)`을 부른다. 계약 Javadoc `:64-69`에서 command fake를 뺀다. 계약과 겹치는
adapter 손 사본은 지우거나 계약 케이스를 가리키게 한다. fixture는 멱등성 hash에 key TTL을 두지 않는다
(`InMemorySemanticRedisCommands.java:184-247`에 PEXPIRE 없음). 그래서 기록 수명 케이스
(`aLeaseLongerThanTheReplayTtlKeepsTheRecordForTheWholeLease` 등)는 기록이 영원히 남아서 통과한다. 그 케이스도
의미 있게 하려면 fixture CLAIM·TRANSITION·RENEW에 TTL을 둔다.
- **이전부터**(Javadoc 문장은 `5786126c`/`bbe944bd`). 이번 커밋이 손 사본을 늘렸다. 가이드 심각도 Low · P3.
- **증거**: E2 — `elapse` override 3줄을 넣은 탐침으로 31 통과·skip 0(명령 2). 원래 코드는 31 중 17 skip(명령 3).
### RR6-02-03 · Minor · runbook이 시작 거절 문장을 ERROR 줄의 "message"에서 찾으라고 한다
- **위치**: `docs/runbooks/idempotency-unavailable.md:20-24`, `:100-101`.
- **무엇이 틀렸나**:
- runbook은 "The ERROR line's message then reads `the claim's processing lease ran out before the action started; …`"라고 적는다.
- 실제 ERROR 줄의 메시지는 `failure classified as IDEMPOTENCY_UNAVAILABLE (category=TRANSIENT_DEPENDENCY, retryable=true)`다
(`ServerFailureLog.java` 5xx 분기). 그 문장은 줄에 붙은 예외의 메시지다.
- local·dev 밖 프로필의 로그는 `LogstashEncoder` JSON이다(`logback-spring.xml:84-100`). 예외는 `message`가 아니라
`stack_trace` 필드에 있다.
- 같은 runbook의 `IDEMPOTENCY_RECOVERY_REQUIRED` 항목(`:51-61`)은 "with the exception attached … The exception
message ends with"로 맞게 적는다.
- **발생 조건·영향**: 운영자가 로그 시스템에서 `message`로 이 문장을 찾으면 못 찾는다. 그러면 저장소 장애로 보고
저장소 담당을 부른다. 이 503을 저장소 장애와 가르는 것이 이 문단의 목적이다.
- **고치는 법**: `:22`를 "The ERROR line (`failure classified as IDEMPOTENCY_UNAVAILABLE …`) carries the exception,
whose message reads `…`; in JSON logs it is in `stack_trace`."로, `:100-101`의 "When the message says"를 "When the
attached exception's message says"로 고친다.
- **이번 커밋**. 가이드 심각도 Low · P3.
- **증거**: E1 — `ServerFailureLog.of`의 형식 문자열, logback 설정.
### RR6-02-04 · Minor · `IDEMPOTENCY_UNAVAILABLE`의 넓어진 뜻이 웹 어댑터 매핑 표와 프론트 인계 표에 없다
- **위치**: `src/adapter/inbound/web/README.md:243`, `docs/upgrade/2026-11-maturity-review.md:280`(7절 짝 프론트).
둘 다 pathspec 밖이다.
- **무엇이 틀렸나**:
- 이 커밋으로 503 `IDEMPOTENCY_UNAVAILABLE`은 "저장소가 응답하지 않음"과 "claim의 lease가 시작 전에 끝나 저장소가
시작을 거절함" 둘을 뜻한다.
- `http-contract.md:111`, `manual/05-idempotency.md:52`, runbook, `application-core/README.md:274-275`는 고쳤다.
- 위 두 곳은 여전히 "조정 저장소가 응답하지 않아 action 전에 거부", "실행 전 저장소 응답 없음"만 적는다.
- **발생 조건·영향**: 클라이언트 행동은 같다(같은 키로 나중에). 다만 매핑 표와 인계 표를 읽는 개발자는 이 503을
저장소 장애로만 읽는다. 갈라진 복사본이다.
- **고치는 법**: 두 행에 "또는 claim의 processing lease가 시작 전에 끝나 저장소가 시작을 거절함(실행 안 됨)"을 더한다.
- **이번 커밋**. 가이드 심각도 Low · P3.
- **증거**: E1 — `grep -rn IDEMPOTENCY_UNAVAILABLE`.
### RR6-02-05 · Minor · 매뉴얼 05의 첫 문장 "같은 키 재전송은 작업을 다시 돌리지 않는다"가 바로 아래 PostgreSQL 항목과 어긋난다
- **위치**: `docs/manual/05-idempotency.md:57-58`과 `:65-70`.
- **무엇이 틀렸나**:
- 문단 첫 문장은 "같은 키 재전송은 작업을 다시 돌리지 않는다"이고, 예외를 "첫 시도가 lease보다 오래 걸릴 때"로 좁힌다.
- 바로 아래 PostgreSQL 항목은 lease와 무관하게 "작업이 예외로 끝나면 실패 기록도 함께 롤백되어 다음 같은 키
요청이 다시 실행한다", "트랜잭션 밖 효과는 다음 요청에서 다시 일어날 수 있다"고 적는다.
- 그래서 첫 문장은 PostgreSQL 기본 모양에서 틀리다. `http-contract.md:119-122`는 같은 단언을 "이것은 Redis
저장소의 판정이다"로 좁혀 맞다.
- **발생 조건·영향**: 매뉴얼만 읽은 개발자가 PG provider에서 효과 불명 실패 뒤 같은 키 재전송도 막힌다고 믿는다.
그러면 트랜잭션 밖 효과(외부 호출, 메시지)를 따로 멱등하게 만들지 않는다.
- **고치는 법**: 첫 문장을 저장소별로 나눈다. 예: "Redis 저장소에서 같은 키 재전송은 효과가 있었을 수 있는 작업을
다시 돌리지 않는다. PostgreSQL 저장소를 쓰기 트랜잭션 하나로 쓰면 실패한 요청의 기록은 롤백되어 다음 같은 키
요청이 다시 실행한다(아래)."
- **이번 커밋**(PG 항목이 이 커밋에서 생겼다). 가이드 심각도 Low · P3.
- **증거**: E1. PG 동작 자체는 E3 — `aSameKeyClaimAfterTheFirstTransactionRolledBackItsAbandonedRecordRunsAfresh`(명령 6).
## Declined to judge
- **watchdog 스레드의 `inheritedAccessControlContext`**: JDK 21 `Thread`는 만드는 스레드의 스택에서
`AccessControlContext`를 잡는다(명령 9). 요청 스레드가 watchdog을 시작하면 그 스택의 ProtectionDomain(과 class
loader)이 스레드가 사는 동안 잡힌다. README의 "pins neither … a redeployed application's loader"보다 약간 넓다.
다만 스레드는 마지막 예약 뒤 60초 안에 끝나고, httpclient가 WAR 안에 있으면 같은 loader라 의미가 없다. httpclient를
공유 부모 loader에 두는 배포에서만 남는다. 템플릿은 실행 jar로 배포한다. 판단하지 않았다.
- **`ClientRuntimeRegistry.close()`의 interrupt 처리**: 닫는 스레드가 interrupt 상태면 `awaitTermination`이 바로
예외를 내고, close는 flag만 되살린 채 정상으로 돌아온다. 그때는 "스레드를 남기지 않는다"가 성립하지 않는다.
이전부터의 모양이고 Spring 종료 스레드는 보통 interrupt되지 않는다.
- **배포 중 섞인 버전**: 옛 인스턴스의 TRANSITION은 lease가 지난 claim을 시작하고 새 인스턴스는 거절한다. 배포
동안만이고 중복 실행은 없다.
- **`docs/registries/error-codes.yaml`의 `IDEMPOTENCY_UNAVAILABLE` `log_level: WARN`**: 전송은 5xx carrier를 ERROR로
남긴다(`ServerFailureLog`). 영역 밖이고 이전부터이며, `log_level`을 읽는 코드가 없어 규범인지 판단하지 않았다.
- **시작 호출의 operation id가 claim과 다를 때**: Redis는 `OPERATION_CONFLICT`, PG는 시작을 적용한다. 이전부터의
차이이고 executor는 항상 claim의 operation id를 넘긴다.
- **in-memory fake(application-core)가 lease를 모델링하지 않음**: 시간 케이스 17개 skip은 RR-01-06 결정의 설계다.
executor의 `LEASE_EXPIRED` → 503 매핑은 손 fake 단위 테스트(`IdempotencyExecutorTest`)와 위 탐침(명령 8)이 본다.
## 결론
- 고쳤다고 한 10개 항목은 모두 닫혔다. 회귀는 없다.
- 두 저장소의 `LEASE_EXPIRED` 판정은 같은 시계(서버), 같은 경계(`now ≥ leaseUntil`), 같은 순서(이미 적용된
시작의 재시도가 먼저)다. 공유 계약 31건이 실 PG·실 Redis에서 skip 없이 통과했다. executor의 503은 계약 문서와 맞다.
- runbook의 Redis 삭제는 Lua 한 번이라 원자적이고, 실 Redis에서 블록 그대로 advanced 계정으로 돈다.
- watchdog 유휴 종료 직후의 새 예약은 고립되지 않는다. drain 스레드 close는 join 마감과 예외 순서가 맞다.
- 결함 5건, 모두 Minor: 이번 커밋 4건(RR6-02-01·03·04·05), 이전부터 1건(RR6-02-02, 이번 커밋이 넓힘).
@@ -0,0 +1,194 @@
# 03 persistence r9 리뷰 (2026-11-05)
대상: 커밋 `45d2a478`(r9), Base `c508b1ba`. 리뷰어 1명이 직접 봤다(하위 에이전트 없음). 결함 ID는 `RR6-03-<순번>`이다.
## 범위
### pathspec
```
src/adapter/outbound/persistence-jpa src/sample-portfolio src/grpc/grpc-operation-ledger-jpa src/optional-platforms
docs/jpa docs/manual/04-persistence.md docs/upgrade/2026-11-maturity-review.md
```
`git diff c508b1ba..45d2a478 -- <pathspec>`의 15개 파일. persistence-jpa 안의 멱등성 store 변경(`IdempotencyTransitionGateway`, `PostgreSqlIdempotencyStore`, `PostgreSqlIdempotencyIntegrationTest`, README 멱등성 문단)은 02가 보므로 뺐다.
요구사항은 재리뷰 README 16절 r9-c 행이다. 항목은 RR4-02-01(`round4/review.md`), gRPC 버전 정규식 복사본(README 12절 r6-b), V21 주석(README 6절 r4-e 남음), r9-c가 새로 찾아 고친 가이드 오류 네 가지다.
판정에 필요해 함께 읽은 것:
- Flyway 11.14.1(lockfile 버전) `PostgreSQLParser`, `Parser`, `ParserSqlScript`, `SqlScriptMetadata`, `ConfigUtils` — Gradle 캐시의 jar를 scratchpad에서 디컴파일했다.
- `ConcurrentIndexMigrationInspector`, `PostgreSqlMigrationUpgradeContractTest`, `MigrationLockWaitTest`, `MigrationTrees`, `applied-migrations.sha256`.
- `persistence-jpa.yml`의 `spring.flyway` 절, 직접 `Flyway.configure()`를 부르는 main 코드 5곳.
- `.github/workflows/ci-quality-gates.yml`·`integration-main.yml`의 optional 빌드 job, `QualityConventionsPlugin`의 Spotless 설정.
- `docs/study/postgresql-jpa-walkthrough.ko.md` §8.2(pathspec 밖, 같은 주장이 있어서).
### 불러온 스킬과 적용한 기준
| 스킬 | 적용한 기준 | 본 것 |
| --- | --- | --- |
| `superpowers:requesting-code-review` | 리뷰어 템플릿: 계획(16절 r9-c) 대비 구현, 테스트가 진짜 동작을 보는가, 마이그레이션 전략, 문서 완결성, 심각도별 Issues, Declined to judge, 읽기 전용 checkout, 하위 에이전트 금지 | 네 항목이 정말 닫혔는지, 새 Flyway 대조 테스트가 주장하는 것을 실제로 지키는지 봤다. 이 문서 양식이 그 템플릿이다 |
| `jpa-patterns` | "Migrations: Flyway·Liquibase, Hibernate auto DDL 금지", "Testing Data Access: Testcontainers로 운영과 같게" | 가이드가 안내하는 마이그레이션 모양(CIC + `.sql.conf`)을 실제 Flyway·실 PostgreSQL로 끝까지 돌려 봤다(RR6-03-01). `ddl-auto: validate` 확인 |
| `supabase-postgres-best-practices` | `lock-short-transactions`(잠금을 짧게, 긴 트랜잭션 금지), `lock-advisory`(transaction-level과 session-level advisory lock의 차이), `query-*`의 인덱스 생성 | Flyway의 transaction-level advisory lock이 열어 둔 트랜잭션을 CIC가 기다리는 것(RR6-03-01), `lock_timeout` 상한 판정, E-문자열 escape(RR6-03-02) |
### 실행한 명령과 결과
모두 `scratchpad/rr6-03/wt`(detached `45d2a478` worktree)에서 공유 잠금(`flock …/heavy.lock`)으로 돌렸다. 괄호 안은 실행 직전 1분 부하다.
1. `./gradlew :adapter:outbound:persistence-jpa:test --tests '*LockWaitMigrationInspectorTest' --tests '*VersionedMigrationFilesTest' --tests '*MigrationLockWaitTest' --tests '*AppliedMigrationImmutabilityTest' --tests '*ConcurrentIndexMigrationInspectorTest' :sample-portfolio:test --tests '*SampleMigrationLockWaitTest'` (2.31) → rc=0. 71·3·2·2·4·1건, 실패 0.
2. `applied-migrations.sha256` 대조(python, LF 정규화, `MigrationTrees.ROOTS` 네 tree) → 파일 47, 고정 47, 빠짐·남음·불일치 0.
3. 검사기 오프라인 탐침: testFixtures 클래스로 `javac`·`java`, 입력 12개(E-문자열, 중첩 주석, dollar quote, `BEGIN ATOMIC`, 옛 `REINDEX VERBOSE` 등).
4. `./gradlew :adapter:outbound:persistence-jpa:postgresqlMigrationLockWaitIntegrationTest` (3.25) — worktree 사본에 탐침 9개를 더했다 → rc=0, 37/37(원래 28 + 탐침). 탐침 결과:
| 입력(앞에 `SET LOCAL lock_timeout = '5s';`) | Flyway mixed 거부 | 검사기 트랜잭션 밖 판정 | 일치 |
| --- | --- | --- | --- |
| `UPDATE probe SET note = E'it\'s'; VACUUM FULL probe` | 거부 | `[]` | **불일치** (RR6-03-02) |
| `/* outer /* inner */ VACUUM probe; */ SELECT 1` | 통과 | `[vacuum]` | 불일치(거부 쪽, Declined) |
| `REINDEX VERBOSE SCHEMA public` | 거부 | `[reindex verbose schema]` | 일치 |
| `CREATE INDEX CONCURRENTLY IF NOT EXISTS …` | 거부 | `[create index concurrently]` | 일치 |
| `VACUUM "public"."probe"` | 거부 | `[vacuum]` | 일치 |
| `CREATE TABLESPACE probe_ts LOCATION '/tmp'` | 거부 | `[create tablespace]` | 일치 |
| `ALTER TABLE probe DETACH PARTITION probe_p CONCURRENTLY` | 통과(PG 오류) | `[]` | 일치 |
| `CLUSTER` | 통과(PG 오류) | `[]` | 일치 |
그리고 SET LOCAL 없이 `INSERT … VALUES (1, E'it\'s'); ALTER TABLE probe ADD COLUMN c INT;`를 읽는 트랜잭션이 열린 채 Flyway로 적용했다 → 검사기 `[]`, Flyway는 15,018 ms 기다린 뒤 적용(상한 없음, RR6-03-02).
5. `./gradlew -p optional-platforms ci --dry-run` → ledger의 `sharedMigrationFileSources`, `spotlessJava`, `compileIntegrationTestJava`, `spotbugsIntegrationTest`가 `ci`에 있다. 정본이 깨지면 optional `ci`(PR마다 도는 job)에서 컴파일로 잡힌다.
6. `./gradlew -p optional-platforms :grpc:grpc-operation-ledger-jpa:compileIntegrationTestJava :grpc:grpc-operation-ledger-jpa:spotlessCheck :grpc:grpc-operation-ledger-jpa:spotbugsIntegrationTest` 두 번 (4.60) → 둘 다 rc=0, 두 번째는 네 태스크 모두 UP-TO-DATE.
7. 정본 `VersionedMigrationFiles`에 포맷이 틀린 메서드를 넣고 같은 명령 (4.35) → `sharedMigrationFileSources`·`compileIntegrationTestJava`가 다시 돌았다(정본을 따라온다). `spotlessJavaCheck`는 `build/generated/sources/sharedMigrationFiles/…/VersionedMigrationFiles.java`를 위반으로 댔다. 이어서 `-p optional-platforms :grpc:grpc-operation-ledger-jpa:spotlessApply` (4.77) → rc=0, 정본 diff 변화 없음 → `spotlessCheck` 다시 실패(RR6-03-04). 정본은 원래대로 되돌렸다.
8. `./gradlew -p optional-platforms :grpc:grpc-operation-ledger-jpa:integrationTest` (3.56) → rc=0, 46/46. lock-wait IT는 `inVersionOrder` 순서대로 V002·V003 두 건.
9. CIC 단독 마이그레이션 탐침(같은 IT lane, 4.11): `CREATE INDEX CONCURRENTLY ix_probe_note ON probe (note);` 하나만 든 V1을 Flyway 기본 설정으로 적용 → 10분 넘게 멈췄다. 컨테이너에서 `pg_stat_activity`·`pg_locks`를 보니 Flyway 연결(pid 62)이 `idle in transaction`으로 advisory `ExclusiveLock`을 들고 있고, CIC(pid 63)는 `Lock/virtualxid` `ShareLock`을 기다렸다(granted=f). `pg_terminate_backend(63)`로 끝냈다.
10. 두 번째 배포 탐침(같은 lane, 3.69): V1(테이블·인덱스)을 적용한 뒤 V2를 적용한다. 20초가 지나면 감시자가 `pg_cancel_backend`로 취소한다 → rc=0.
| V2 | `.sql.conf` | Flyway PostgreSQL 잠금 | 결과 |
| --- | --- | --- | --- |
| `CREATE INDEX CONCURRENTLY` | `executeInTransaction=false`(가이드 모양) | 기본(transactional) | **멈춤** → 20초에 취소, version 1 |
| `CREATE INDEX CONCURRENTLY` | 없음 | 기본 | **멈춤** |
| `CREATE INDEX CONCURRENTLY` | `executeInTransaction=false` | `flyway.postgresql.transactional.lock=false` | 20 ms에 적용, version 2 |
| `DROP INDEX CONCURRENTLY` | `executeInTransaction=false` | 기본 | 19 ms에 적용 |
| `REINDEX INDEX CONCURRENTLY` | `executeInTransaction=false` | 기본 | **멈춤** |
### 못 본 것
- IntelliJ 가져오기는 실행하지 않았다. Sync 방식의 IDE 영향은 정적 판단이다(Declined).
- staging·prod의 "deployment-owned migration" 도구가 저장소에 없다. RR6-03-01은 Flyway API·Spring Boot 기본값으로만 확인했다(Flyway CLI 기본값도 같다는 것은 E0).
- PostgreSQL 16.15 외 버전.
- 전체 `check`·`ci`·`mainCheck`·`integrationCheck`는 돌리지 않았다(총괄 게이트 몫). 위 좁힌 태스크만 돌렸다.
## 항목 재확인
| ID | 판정 | 근거 |
| --- | --- | --- |
| RR4-02-01 | 닫힘 | Flyway 11.14.1 `PostgreSQLParser#detectCanExecuteInTransaction`이 PG 12 이상에서 쓰는 정규식 6개와 `LockWaitMigrationInspector.java:154-161`이 같다(디컴파일 대조). 판정 규칙(`.sql.conf`가 있으면 그것, 없으면 문장 판정)은 `ParserSqlScript.executeInTransaction()`과 같다(`:243-247`). `VACUUM FULL` + `SET LOCAL`은 "cannot run in a transaction … keep it out of migrations"로 거부(`:275-280`, 명령 1). `REINDEX (CONCURRENTLY)`(`:82-83`), `GRANT … REFERENCES ON`(`:117`), `executeInTransaction=FALSE`(`:378-399`, Flyway `ConfigUtils.removeBoolean`과 같은 판정) 모두 고쳐졌다. 가이드 `docs/jpa/migration-guide.md:55-69`. 남은 lexer 빈틈은 이전부터의 RR6-03-02, 업그레이드 감시의 빈틈은 RR6-03-03 |
| gRPC 버전 정규식 복사본 | 닫힘 | `GrpcOperationLedgerMigrations.java:35-39`가 `VersionedMigrationFiles.inVersionOrder`를 쓰고 자체 정규식·`version()`이 지워졌다. `build.gradle:27-33` Sync. 정본을 바꾸면 optional 빌드가 따라오고(명령 7), 두 번째 실행은 UP-TO-DATE(명령 6), optional `ci`가 컴파일한다(명령 5). 새 `inVersionOrder`는 Flyway처럼 수로 비교하고 없는 자리를 0으로 보며 같은 버전을 거부한다(`VersionedMigrationFiles.java:54-98`, 테스트 2건). 부작용: RR6-03-04 |
| V21 주석 | 닫힘 | `V21__outbox_aggregate_sequence.sql:10`의 `JpaOutboxStore#nextSequence`가 있다(`JpaOutboxStore.java:133`). sha256 `applied-migrations.sha256:43`이 파일과 같다(명령 2) |
| 가이드 "CONCURRENTLY는 Flyway가 트랜잭션으로 감싼다" (r9-c가 새로 찾아 고침) | 부분 | 가이드 `:98-104`는 고쳤다. 같은 주장이 `ConcurrentIndexMigrationInspector.java:10-14`, `GrpcOperationLedgerMigrationLockWaitIT.java:32-33`, study 문서 `:1338-1344`에 남았다(RR6-03-05). 고친 문장이 안내하는 길(CIC·`REINDEX … CONCURRENTLY`를 자기 마이그레이션에)은 Flyway 기본 설정에서 멈춘다(RR6-03-01) |
| 동결 목록(`RELEASED_BEFORE_THE_RULE`) | 맞음 | `MigrationLockWaitTest.java:79-99`가 두 방향으로 통과(명령 1). 이번 커밋에서 목록·마이그레이션 파일 변경 없음. `SampleMigrationLockWaitTest`는 `isEqualTo(V8)`로 통과 |
| sha256 고정 목록 | 맞음 | 47/47 일치(명령 2), `AppliedMigrationImmutabilityTest` 2/2 |
## 결함
### RR6-03-01 · Important · CIC·`REINDEX … CONCURRENTLY` 마이그레이션은 Flyway 기본 설정에서 끝나지 않는다 — 가이드가 그 길을 안내한다
- **위치**:
- 안내: `docs/jpa/migration-guide.md:98-114`("Concurrent index builds": CIC 마이그레이션 + `executeInTransaction=false`), `:63-65`(r9: `REINDEX TABLE|INDEX CONCURRENTLY`는 `executeInTransaction=false`), `:101-104`(r9: 동반 설정을 늘 쓴다), `LockWaitMigrationInspector.java:286-290`(r9 메시지: "put create index concurrently in a migration of its own").
- 설정: `src/adapter/outbound/persistence-jpa/src/main/resources/config/module-defaults/persistence-jpa.yml:125-139`(`spring.flyway`에 `postgresql.transactional-lock` 없음). 직접 만드는 Flyway: `IdempotencySchemaStream.java:85`, `NotificationSchemaStream.java:58`, `MessagingInboxSchemaStream.java:77`, `SamplePostgreSqlPersistenceConfig.java:41`, `SchemaTenantMigrationOrchestrator.java:51`.
- **무엇이 틀렸나**:
- Flyway 11.14.1은 PostgreSQL에서 기본으로 transaction-level advisory lock을 쓴다.
- 그 잠금을 든 연결은 migrate가 끝날 때까지 트랜잭션을 열어 둔다(`idle in transaction`).
- `CREATE INDEX CONCURRENTLY`와 `REINDEX … CONCURRENTLY`는 먼저 시작한 트랜잭션이 모두 끝나기를 기다린다(virtualxid 대기).
- 그래서 CIC는 Flyway 자신의 잠금 트랜잭션을 기다리고, Flyway는 CIC를 기다린다. 둘 다 끝나지 않는다.
- 이 대기에는 상한이 없다. `executeInTransaction=false` 파일에는 `SET LOCAL lock_timeout`을 둘 수 없다.
- 명령 10: 가이드 모양 그대로(`.sql.conf` 포함) 두 번째 배포가 멈췄다. 같은 파일이 session-level 잠금(`flyway.postgresql.transactional.lock=false`)에서는 20 ms에 적용됐다. `DROP INDEX CONCURRENTLY`는 멈추지 않는다.
- **발생 조건·영향**:
- 가이드대로 운영 중인 큰 테이블에 CIC 마이그레이션으로 인덱스를 더하는 파생 서비스. 템플릿 자체에는 지금 그런 파일이 없다.
- dev·test(기동 때 migrate)에서는 앱 기동이 멈춘다. 배포 마이그레이션도 Flyway 기본값이면 배포가 끝나지 않는다.
- 그동안 CIC가 테이블에 `SHARE UPDATE EXCLUSIVE`를 들어 그 테이블의 다른 DDL·autovacuum이 막힌다. Flyway advisory lock 때문에 다른 인스턴스의 migrate도 줄을 선다.
- 실패가 아니라 멈춤이라 알람과 롤백이 늦다. 취소하면 INVALID 인덱스가 남는다.
- **테스트가 못 본 이유**: CIC 마이그레이션을 Flyway로 끝까지 돌린 테스트가 없다. `PostgreSqlMigrationUpgradeContractTest.java:72-81`은 CIC를 JDBC autocommit으로만 돌린다. r9의 IT는 CIC를 `SET LOCAL` 옆에 두어 Flyway가 파싱 단계에서 거부하는 것만 본다(`PostgreSqlMigrationLockWaitIntegrationTest.java:129-188`).
- **고치는 법** (하나를 고른다):
- (권장) Flyway의 PostgreSQL 잠금을 session-level로 바꾼다.
- module-defaults에 `spring.flyway.postgresql.transactional-lock: false`(Spring Boot 4.0.8 속성, 기본값 없음 → Flyway 기본 true).
- 직접 만드는 Flyway 5곳에 같은 값(`flyway.postgresql.transactional.lock=false`)을 공용 helper 하나로 넣는다.
- 가이드 "Who may change the schema"·"Concurrent index builds"에 배포 마이그레이션 도구도 같은 값을 써야 한다고 적는다.
- session-level advisory lock은 transaction-mode PgBouncer 뒤에서 깨진다. 템플릿은 Hikari 직접 연결이라는 전제를 같은 곳에 적는다.
- RED: 실 PG IT 하나. 템플릿 설정으로 만든 Flyway가 V1 적용 뒤 `.sql.conf`가 있는 CIC V2를 상한(예: 30초) 안에 적용하는지 본다. 지금 설정에서는 상한에 걸려 실패한다.
- (대안) CIC·`REINDEX … CONCURRENTLY`를 `VACUUM FULL`처럼 "마이그레이션에 두지 않고 운영 절차로" 한다. 검사기가 거부하고, 가이드 "Concurrent index builds"를 runbook 절차로 바꾸고, `ConcurrentIndexMigrationInspector`를 정리한다.
- **이번 커밋/이전부터**: 이전부터(가이드 "Concurrent index builds"). 이번 커밋이 같은 길을 더 안내했다(가이드 `:63-65`, `:101-104`, 검사기 메시지 `:286-290`).
- **증거**: E3 — 명령 9·10(`pg_stat_activity`·`pg_locks`로 대기 관계 확인). Flyway 잠금 동작은 E1(디컴파일한 `PostgreSQLParser`·Spring Boot `spring-configuration-metadata.json`의 `spring.flyway.postgresql.transactional-lock`).
### RR6-03-02 · Minor · `E'…\'…'` 문자열이 검사기의 문자열 판정을 어긋나게 해, 뒤의 잠금 문장과 트랜잭션 밖 문장을 못 본다
- **위치**: `LockWaitMigrationInspector.java:433-471`(`withoutCommentsAndLiterals`, `'` 처리 `:446-458`). `:370-372` `normalized`가 이 결과를 잠금 판정과 트랜잭션 밖 판정에 함께 쓴다.
- **무엇이 틀렸나**:
- PostgreSQL과 Flyway는 `E'it\'s'`의 `\'`를 문자열 안의 따옴표로 읽는다(Flyway `Parser.readToken`의 `E'` 분기).
- 검사기는 `''`만 escape로 읽는다. 그래서 `\'`에서 문자열을 닫는다.
- 그 뒤 `s'`의 따옴표가 새 문자열을 연다. 다음 따옴표까지(없으면 파일 끝까지)가 문자열로 지워진다.
- 명령 4: `INSERT INTO probe (id, note) VALUES (1, E'it\'s');` 다음 줄의 `ALTER TABLE probe ADD COLUMN c INT;`를 검사기는 못 봤다(`[]`). 실 PG에서 읽는 트랜잭션이 열린 채 Flyway로 적용하니 15,018 ms를 기다린 뒤 적용됐다.
- 같은 이유로 `UPDATE … E'it\'s'; VACUUM FULL probe;`를 검사기는 트랜잭션 안으로 판정했다. Flyway는 mixed로 거부했다.
- **발생 조건·영향**: 시드·데이터 마이그레이션이 E-문자열에 `\'`를 쓰고 그 뒤에 잠금 문장을 둔 파일. 검사기가 막으려는 상한 없는 잠금 대기가 그대로 통과한다. 모양이 드물어 Minor다.
- **고치는 법**: `'` 바로 앞 글자가 `e`/`E`이고 그 앞이 식별자 글자가 아니면 E-문자열로 읽어 `\` 다음 글자를 건너뛴다(`\\`, `\'`). RED: 위 두 입력을 `LockWaitMigrationInspectorTest`에 더한다. 두 번째 입력은 IT의 Flyway 대조 목록(`:129-153`)에도 더한다.
- **이번 커밋/이전부터**: 이전부터(RR3-02-01 때의 함수). 이번 커밋의 트랜잭션 밖 판정도 같은 출력을 써서 함께 틀린다.
- **증거**: E3 — 명령 3·4.
### RR6-03-03 · Minor · "Flyway를 올리면 IT가 실패한다"는 주장이 Flyway 목록에 문장이 더해지는 경우를 못 본다
- **위치**: `LockWaitMigrationInspector.java:151-152`, `PostgreSqlMigrationLockWaitIntegrationTest.java:45-50`·`:129-153`, `docs/jpa/migration-guide.md:87-88`.
- **무엇이 틀렸나**:
- Javadoc은 `postgresqlMigrationLockWaitIntegrationTest`가 목록을 Flyway에 묶어 두어 "목록을 바꾸는 Flyway 업그레이드는 거기서 실패한다"고 한다. 가이드도 "the statements it names are exactly those Flyway refuses"라고 한다.
- IT는 고정 문장 21개에서만 검사기와 Flyway를 대조한다. Flyway가 목록에 새 문장을 더하면, 그 문장이 21개 안에 없는 한 아무 테스트도 실패하지 않는다.
- 지금 목록의 일부도 대조에 없다: `CREATE`/`DROP TABLESPACE`, `CREATE`/`DROP SUBSCRIPTION`, `REINDEX SYSTEM`, 옛 문법 `REINDEX VERBOSE SCHEMA`. 명령 4로 TABLESPACE·`REINDEX VERBOSE`는 지금 일치함을 확인했다.
- 이 lane은 `integrationCheck`(main push)에서만 돈다. Flyway를 올리는 PR의 `ci`는 이 대조를 돌리지 않는다.
- **발생 조건·영향**: Flyway가 트랜잭션 밖 목록에 문장을 더하는 업그레이드. 그 문장과 `SET LOCAL`이 든 마이그레이션을 검사기가 통과시킨다. 기본 `mixed=false`에서는 배포 때 Flyway가 거부하고, `mixed=true`에서는 상한 없이 돈다. 검사기 사본이 조용히 Flyway와 갈라진다.
- **고치는 법**:
- persistence-jpa `test`(PR `ci`에서 도는 lane)에 테스트 하나를 둔다. `org.flywaydb.database.postgresql.PostgreSQLParser`의 static `Pattern` 필드를 reflection으로 읽어 `pattern()` 집합을 11.14.1 기준 값으로 고정한다. 다르면 "Flyway의 트랜잭션 밖 목록이 바뀌었다: `FLYWAY_OUTSIDE_A_TRANSACTION`과 IT 대조 목록을 갱신하라"로 실패한다. `flyway-database-postgresql`은 이미 testRuntimeClasspath에 있다(lockfile).
- IT 대조 목록에 위 네 대안을 더한다.
- Javadoc `:151-152`·가이드 `:87-88`을 실제로 지키는 범위로 고친다.
- **이번 커밋/이전부터**: 이번 커밋.
- **증거**: E1 — 디컴파일한 `PostgreSQLParser`와 IT 대조 목록 비교, lane 단계(`integration-main.yml`). E3 — 명령 4.
### RR6-03-04 · Minor · optional 빌드의 Spotless가 Sync로 가져온 사본을 검사하고, 안내한 `spotlessApply`는 아무것도 고치지 못한다
- **위치**: `src/grpc/grpc-operation-ledger-jpa/build.gradle:27-33`. Spotless 대상은 기본값이다(`src/build-logic/src/main/java/dev/caskeleton/buildlogic/quality/QualityConventionsPlugin.java:46-51`, target 미지정 → 모든 source set).
- **무엇이 틀렸나**:
- Sync 출력이 integrationTest source set의 소스 폴더가 됐다. Spotless 기본 대상은 모든 source set이라 `build/generated/sources/sharedMigrationFiles/…/VersionedMigrationFiles.java`도 검사한다(명령 5의 `spotlessJava`가 Sync에 의존).
- 정본의 포맷이 틀리면 optional 빌드는 생성 사본 경로를 대며 `spotlessApply`를 하라고 한다.
- 명령 7: `-p optional-platforms …:spotlessApply`는 rc=0으로 끝났지만 생성 사본만 고쳤다. 정본은 그대로였다. 다음 Sync가 사본을 되돌려 `spotlessCheck`가 다시 실패했다.
- **발생 조건·영향**: 정본을 고치다 포맷을 어긴 개발자가 optional 빌드만 돌릴 때. 안내대로 해도 고쳐지지 않는다. 주 빌드의 persistence-jpa `spotlessCheck`가 같은 PR에서 정본 경로로 잡으므로 피해는 혼란과 이중 보고다.
- **고치는 법**: ledger `build.gradle`에서 Sync 출력을 Spotless 대상에서 뺀다(예: `spotless { java { targetExclude('build/generated/sources/sharedMigrationFiles/**') } }`). 정본의 포맷은 주 빌드가 맡는다고 그 옆 주석(`:19-26`)에 적는다. RED: 정본에 포맷 위반을 넣으면 지금은 optional `spotlessCheck`가 사본 경로로 실패한다. 고친 뒤에는 통과하고, 주 빌드의 persistence-jpa `spotlessCheck`만 정본 경로로 실패한다.
- **이번 커밋/이전부터**: 이번 커밋.
- **증거**: E2 — 명령 5·6·7.
### RR6-03-05 · Minor · "Flyway는 마이그레이션을 늘 트랜잭션으로 감싼다"는 설명이 가이드 밖 세 곳에 남았다
- **위치**: `src/adapter/outbound/persistence-jpa/src/testFixtures/java/dev/caskeleton/adapter/outbound/persistence/testkit/migration/ConcurrentIndexMigrationInspector.java:10-14`, `src/grpc/grpc-operation-ledger-jpa/src/integrationTest/java/dev/caskeleton/grpc/ledger/GrpcOperationLedgerMigrationLockWaitIT.java:32-33`, `docs/study/postgresql-jpa-walkthrough.ko.md:1338-1344`(pathspec 밖).
- **무엇이 틀렸나**:
- r9-c는 가이드의 같은 오류만 고쳤다(가이드 `:55-63`, `:100-104`: Flyway는 CIC가 든 파일을 스스로 트랜잭션 밖에서 돌린다).
- testkit Javadoc과 study 문서는 아직 이렇게 말한다. "Flyway가 트랜잭션으로 감싸서 CIC 마이그레이션은 첫 배포에서 실패한다(좋은 경우)." "다른 문장과 섞이면 그것들은 커밋되고 인덱스만 안 된다(나쁜 경우)."
- Flyway 11.14.1에서 CIC만 든 파일은 트랜잭션 밖에서 돈다(그리고 RR6-03-01 때문에 멈춘다, 명령 9·10). 섞인 파일은 기본 `mixed=false`에서 아무것도 실행하기 전에 거부된다(명령 4). 두 설명이 모두 틀렸다.
- gRPC ledger IT Javadoc은 "마이그레이션을 Flyway가 돌리는 대로, 한 트랜잭션에서 돌린다"고 한다. Flyway가 트랜잭션 밖에서 돌릴 파일(CIC 등)은 IT가 다르게 돌린다. JDBC 트랜잭션 안에서 25001로 실패하고, 실패 메시지는 "SET LOCAL을 넣어라"라고 한다. 그 안내를 따르면 Flyway가 mixed로 거부한다.
- **발생 조건·영향**: 읽는 사람이 Flyway 동작을 잘못 배운다. 가이드와 testkit 설명이 서로 다르다. ledger에 CIC 마이그레이션을 더하는 사람은 따를 수 없는 안내를 받는다.
- **고치는 법**:
- 두 설명을 가이드 `:55-65`·`:98-104`와 같게 고친다(RR6-03-01에서 고른 방법을 반영한 뒤).
- ledger IT Javadoc은 이렇게 고친다. "지금 파일들(`SET LOCAL` + 트랜잭션 안 문장)은 Flyway도 한 트랜잭션에서 돌린다. Flyway가 트랜잭션 밖에서 돌릴 파일은 여기서 판정하지 못하니 이 테스트에 예외로 적는다." SQLState가 25001이면 실패 메시지에 같은 안내를 덧붙인다.
- **이번 커밋/이전부터**: 이전부터. r9-c가 가이드만 고치고 같은 주장의 다른 사본은 남겼다.
- **증거**: E1(세 문서·코드), E3(명령 4의 mixed 거부, 명령 10의 CIC 단독 배포).
## Declined to judge
- **검사기의 10단어 셈이 Flyway와 다르다.** 검사기는 괄호 안 단어와 식별자도 센다(`:317-355`). Flyway는 괄호 밖 키워드만 센다. 판정 단어가 문장의 첫 4개 키워드 안에 있고, 그 앞에 오는 괄호(`REINDEX` 옵션)는 많아야 6단어라 결과가 달라지는 입력이 없다. Javadoc `:294-296`의 "the way Flyway finds them"도 그래서 결함으로 올리지 않았다.
- **중첩 블록 주석.** `/* outer /* inner */ VACUUM probe; */`를 검사기는 트랜잭션 밖으로 판정했다(명령 4). PostgreSQL과 Flyway는 중첩을 센다. 거부 쪽 오판이고 실제 마이그레이션에서 보기 힘든 모양이다. 고친다면 RR6-03-02와 같은 함수다.
- **`.sql.conf`의 `executeInTransaction=true` + `SET LOCAL` + `VACUUM FULL`.** 검사기는 통과시킨다(`:243-248`). Javadoc `:61-63`은 `VACUUM FULL`을 늘 거부한다고 읽힌다. 그러나 PostgreSQL이 배포 때 25001로 거부해 잠금 대기가 생기지 않고, 이 조합을 쓸 이유가 없는 입력이다.
- **`REINDEX (CONCURRENTLY 'false')`.** 문자열 값이 `''`로 지워져 동시로 판정된다. PostgreSQL이 받는 값이지만 쓰는 사람을 상정하기 어렵다.
- **`.sql.conf`의 placeholder·환경 변수.** Flyway는 `${…}`를 치환하고 검사기는 `IllegalStateException`으로 실패한다(`:394-398`). 거부 쪽이다.
- **Sync 방식과 IDE.** 생성 폴더는 Gradle을 한 번 돌리기 전에는 없다. 생성 사본을 IDE에서 고치면 다음 Sync가 덮는다. 생성 소스의 일반적인 성질이고, IntelliJ 기본(Gradle에 빌드 위임)에서는 Sync가 먼저 돈다. 실행으로 확인하지 않았다.
- **persistence-jpa 디렉터리가 없는 파생 서비스.** ledger의 integrationTest가 컴파일되지 않는다. 문서화된 capability 제거는 `runtimeOnly` 줄을 지우는 것이지 디렉터리를 지우는 것이 아니다.
- **V002 주석 "Flyway runs each migration in a transaction"**(`V002__index_grpc_operation_ledger_finished_rows.sql:11`). RR6-03-05와 같은 오류다. 다만 적용된 마이그레이션이라 고치면 checksum이 바뀐다. 이 파일의 결론(빈 테이블이라 일반 인덱스)은 맞다. 고칠지는 소유자 판단이다.
- **`MessagingMigrationNamespaceTest`의 정규식 `V(\d+)__.+\.sql`.** 05 영역이다. 소수 버전을 실패시키는 쪽이라 조용히 빠지지 않는다.
- **Flyway `mixed=true`·전역 `executeInTransaction=false`를 쓰는 서비스.** 검사기 Javadoc `:63-65`와 가이드 `:62`에 가정으로 적혀 있다.
## 결론
결함 5건: Important 1건, Minor 4건. 이번 커밋 2건(RR6-03-03, RR6-03-04), 이전부터 3건(RR6-03-01, RR6-03-02, RR6-03-05). RR6-03-01은 이전부터지만 이번 커밋이 같은 길을 더 안내했다.
- r9-c가 맡은 세 항목(RR4-02-01, gRPC 버전 정규식 복사본, V21 주석)은 닫혔다. 검사기의 Flyway 목록은 11.14.1과 같다. 동결 목록과 sha256 목록도 맞다.
- r9-c가 새로 고친 가이드 오류는 부분 닫힘이다(RR6-03-05).
- 가장 큰 문제는 RR6-03-01이다. 가이드가 안내하는 CIC 마이그레이션이 Flyway 기본 설정에서 끝나지 않는다. 고치기 전에 소유자가 방법(session-level 잠금 또는 운영 절차로 이동)을 정해야 한다.
@@ -0,0 +1,169 @@
# 04 build-logic r9 리뷰 (2026-11-05)
> 대상: `c508b1ba..45d2a478`의 r9-d 묶음. 실패를 막지 못하는 workflow 명령, 실행되지 않는 줄의 `cd`, 실패 메시지,
> 짧은 플래그 묶음, httpclient 장애 주입 lane 중복 실행 제거.
## 범위
### pathspec
```
src/build-logic src/build.gradle src/adapter/outbound/httpclient/build.gradle .github AGENTS.md CLAUDE.md
src/README.md docs/upgrade/2026-11-maturity-review.md
```
`git diff c508b1ba..45d2a478 -- <pathspec>`: 11개 파일, +1985 −330. `.github`와 `src/build.gradle`은 이번 커밋에서 바뀌지 않았다. 새 `ShellScript.java`(1213줄)와 `WorkflowGradleInvocations.java`(778줄)는 diff가 아니라 HEAD 전체를 읽었다.
### 불러온 스킬과 적용한 기준
| 스킬 | 기준 | 본 것 |
|---|---|---|
| `superpowers:requesting-code-review` | 계획(README 16절 r9-d 주장)과 구현이 맞는가, 테스트가 실제 동작을 보는가, 심각도 보정, Declined to judge, 읽기 전용(별도 worktree) | r9-d 항목마다 닫힘 여부, 테스트가 주장하는 고정 범위(RR6-04-02), 결함마다 실행 증거 |
| `ci-cd-and-automation` | "No gate can be skipped", 레드 플래그 "CI failures ignored or silenced" | 검사가 단계를 실행으로 세는데 실제로는 돌지 않거나 실패가 삼켜지는 모양(거짓 통과). `mainCheck`에서 뺀 httpclient lane이 다른 단계에서 실제로 도는지 |
| `codebase-design` | 깊은 모듈, seam은 실제 adapter와 맞물려 검증되는가("One adapter means a hypothetical seam"), 인터페이스가 테스트 표면인가 | `ShellScript.commands(script, dir, options)` 인터페이스는 작고 `WorkflowGradleInvocations.read`로 테스트된다. 반면 Gradle 명령줄 판독은 Gradle 파서의 손 복사본인데 실행 중인 Gradle과 맞대는 계약 테스트가 두 모양뿐이다(RR6-04-02) |
### 실행한 명령과 결과
모든 실행은 `git worktree add --detach <scratchpad>/rr6-04/wt 45d2a478`에서 했다. Gradle은 공유 `heavy.lock`으로 감쌌다.
| 명령 | 결과 | 직전 부하(1분) |
|---|---|---|
| `./gradlew :mainCheck --dry-run` | rc=0, 계획에 `httpClientFailureInjectionTest` 0회 | 3.89 |
| `./gradlew :integrationCheck --dry-run` | rc=0, 계획에 `:adapter:outbound:httpclient:httpClientFailureInjectionTest` 1회 | 3.89 |
| `./gradlew :verifyStrictLaneStages --dry-run` / `-p optional-platforms …` | rc=0 / rc=0, 둘 다 "every strict lane is in an executed stage" | 3.79 |
| `./gradlew -p build-logic test --tests 'dev.caskeleton.buildlogic.strictlane.*'` | rc=0, 76개 통과, 실패·건너뜀 0 | 4.00 |
| Gradle 9.0.0·9.2.0·9.7.1 `gradle --help` | 옵션 표 대조: 9.0.0과 판독기 표가 정확히 같음. 9.2.0에 `--task-graph`, 9.7.1에 `--console-unicode`·`--develocity-url`·`--develocity-plugin-version`·`--non-interactive`·`--isolated-projects` 추가 | 3.80 |
| 임시 프로젝트(`ci` 태스크가 파일을 씀)에서 9.0.0·9.2.0 `gradle --no-daemon -q :ci --task-graph` | 9.0.0 rc=1(옵션 모름), 9.2.0 rc=0·작업 미실행 | 2.98 |
| 같은 프로젝트에서 9.0.0 `:ci -v`, `:ci --version`, `-v :ci`, `:ci --help`, `:ci -h`, `:ci --status`, `:ci -V` | `-V`만 작업 실행. 나머지 여섯은 rc=0·작업 미실행 | 5.20 |
| 판독기 probe: HEAD의 `ShellScript.java`·`WorkflowGradleInvocations.java`를 scratchpad로 꺼내 `javac`로 따로 컴파일하고 사례 workflow 12개를 읽힘 | 결과는 결함마다 적었다 | — |
| 같은 probe로 이 repo의 workflow 15개 | run 스크립트 104개 파싱 실패 0. 단계 명령 11개 모두 COUNTED | — |
| `c508b1ba`의 판독기와 HEAD 판독기를 같은 workflow 15개에 | 단계 명령 11개 판정 같음. 다른 것은 단계가 아닌 명령: task 단어 6개(`-P…=${{ matrix.x }}`가 한 단어로 읽힘)와 미집계 3개(`for`·명령 치환 안) | — |
| `bash -e`로 가짜 `gradlew`(호출을 기록하고 exit 1)를 부르는 스크립트 13개 | 결함마다 적었다 | — |
| GitHub 문서(workflow syntax의 shell 표·exit code 절·`needs` 절, container 문서) | 기본 셸: Linux·macOS `bash -e {0}`, `shell: bash`는 `bash --noprofile --norc -eo pipefail {0}`, Windows는 `pwsh`, container 안은 `sh` | — |
### 못 본 것
- 실제 GitHub runner 실행, pwsh 실행(이 환경에 pwsh가 없다).
- `--stop`: 같은 Gradle 버전의 다른 세션 데몬을 멈추므로 실행하지 않았다(Gradle `--help` 설명과 코드 경로로만 판단).
- `-p build-logic check` 전체와 javadoc: strictlane 테스트만 돌렸다.
- README 16절의 "run 스크립트 253개" 코퍼스: 이 repo의 104개만 다시 파싱했다.
## 항목 재확인
| ID | 판정 | 근거 |
|---|---|---|
| README 15절 남음: `\|\| true`, pipefail 없는 `\| tee`, `if ./gradlew ci; then` | 닫힘 | `ShellScript.java:953-998`. 테스트 `gradlewWhoseFailureIsHandledOrDroppedDoesNotCountAndSaysWhy`, `gradlewThatRunsOnlyUnderAConditionOrInALoopOrFunctionDoesNotCount`, TestKit `aStageCalledOnlyInShapesThatCannotFailTheStepFailsNamingWhy` |
| RR5-02-02 `&`, `false && cd src && ./gradlew ci` | 닫힘 | `ShellScript.java:566-570`, `:959-979`. 테스트 `gradlewInAnAndListCountsOnlyWhenTheListIsTheScriptsLastCommand`. `bash -e` probe(`false && ./gradlew :ci` / `echo done`)는 rc=0·호출 0이고 판독기는 세지 않는다 |
| RR5-02-01 heredoc·부르지 않은 함수·여러 줄 문자열·`\;` 뒤의 `cd` | 닫힘 | `ShellScript.java:290-303`(heredoc 본문), `:663-674`·`:784-791`(함수 정의), `:332-334`(여러 줄 문자열), `:318-323`(이스케이프). 테스트 `aCdTheShellDoesNotRunThereIsNotFollowed`, `aCdInAFunctionBodyIsNotFollowedAndTheCommandsAfterItDoNotCount` |
| RR5-02-03 다른 빌드로 읽힌 명령을 실패 메시지에 | 닫힘 | `StrictLaneStagesPlugin.java:200-220`, `WorkflowGradleInvocations.java:152-160`. TestKit `aStageCalledForAnotherBuildIsNamedWithThatBuildInTheFailure`(`scr`, `src/src`) |
| `-mx` 같은 짧은 플래그 묶음 | 닫힘 | `WorkflowGradleInvocations.java:696-760`. 값 옵션·플래그 표가 9.0.0 `--help`와 같다. 작업 없이 끝나는 플래그는 별도 결함 RR6-04-01 |
| "Gradle 9.0 파서 동작을 TestKit으로 고정" | 부분 | `StrictLaneStagesFunctionalTest.java:564-606`은 `-qm`·`-mx` 두 모양만 고정한다 → RR6-04-02 |
| `shell:` 기본값·`defaults.run.shell` | 부분 | Linux·macOS 기본과 `shell: bash`·`sh`, job·workflow `defaults.run.shell`은 맞게 읽는다(probe `10-defaults-shell`). Windows 기본 pwsh를 bash로 읽는다 → RR6-04-04 |
| httpclient 장애 주입 lane 두 번 실행 | 닫힘 | `src/adapter/outbound/httpclient/build.gradle:230-242`. `:mainCheck --dry-run` 0회, `:integrationCheck --dry-run` 1회. `.github/workflows/integration-main.yml:173-176`의 `integration-check`가 main push·nightly에 `:integrationCheck`를 돌리고 판독기가 COUNTED로 읽는다. 문서(`docs/upgrade/…:236`, `docs/capability-status.md:38`)도 같다 |
| 새로 찾아 고친 것(`$(( ))`, `help --task ci`, `${{ }}` 안 공백, `-x=b`) | 닫힘 | 테스트 `aScriptWithArithmeticIsReadAsShellAndItsLastGradlewCounts`, `bundledShortOptionsAreReadTheWayGradleReadsThem`. 실제 workflow 비교에서 `${{ }}`가 한 단어로 읽힌다 |
| "실제 workflow 판독 전후 같음" | 확인 | 단계 명령 11개 판정이 `c508b1ba`와 같다 |
## 결함
### RR6-04-01 · 작업을 실행하지 않고 끝나는 Gradle 옵션을 실행으로 센다
- 심각도: Minor (가이드 Low · P2)
- 위치: `src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocations.java:73-83`(`GRADLE_FLAGS`), `:728-744`(묶음 안의 글자), `:752-759`(`m`·`dry-run`만 계획 전용으로 본다)
- 무엇이 틀렸나: Gradle 9.0은 `-v`·`--version`, `-h`·`-?`·`--help`, `--status`를 받으면 정보만 찍고 작업 없이 0으로 끝난다. `--stop`도 데몬을 멈추고 끝난다. 판독기는 이 옵션들을 값 없는 플래그로만 읽는다. 그래서 `./gradlew :ci -v`를 `:ci` 실행으로 센다.
- 발생 조건·영향: 다른 도구처럼 `-v`를 "자세히"로 알고 붙인 workflow 명령이 대표적이다. 그 step은 Gradle 버전만 찍고 초록으로 끝난다. `verifyStrictLaneStages`도 통과한다. 단계와 그 lane은 아무 데서도 돌지 않는다. `-qm`을 계획 전용으로 막은 것과 같은 종류인데 빠졌다.
- 고치는 법: 작업 없이 끝나는 옵션 목록(`v`, `version`, `h`, `?`, `help`, `status`, `stop`)을 따로 둔다. 이 옵션이 단독으로든 묶음 안(`-qv`)으로든 나오면 "Gradle은 `<옵션>`을 받으면 작업을 실행하지 않고 끝난다"는 이유로 세지 않는다. 단위 테스트에 `:ci -v`, `:ci --help`, `-qv :ci`, `:ci --status`를 더한다. TestKit에는 `runner(":ci", "-v")`가 작업을 실행하지 않는다는 것을 고정한다(`--stop`은 TestKit에서도 돌리지 않는다).
- 이번 커밋/이전부터: 이전부터. 이번 커밋이 판독을 "Gradle 9.0 파서대로"로 다시 쓰고 `-qm`만 계획 전용에 더하면서 남았다.
- 증거: E3. 임시 프로젝트에서 Gradle 9.0.0 `gradle --no-daemon -q :ci -v`·`:ci --version`·`-v :ci`·`:ci --help`·`:ci -h`·`:ci --status` → 모두 rc=0, 작업 미실행(`-V`는 실행). 판독기 probe(`cases/06-early-exit-flags.yml`, `-qv`·`--stop` 포함 6개) → 모두 `executes(:ci, src)=true`.
### RR6-04-02 · Gradle을 올려 옵션 표가 낡아도 잡는 테스트가 없다 — 9.2의 `--task-graph`가 그 예
- 심각도: Minor (Low · P2)
- 위치: `WorkflowGradleInvocations.java:60-83`(9.0 값 옵션·플래그 표), `:658-660`(Javadoc "pinned by `StrictLaneStagesFunctionalTest`"), `src/build-logic/README.md:19`("the reader follows Gradle 9.0's parser, probed in round 9"), `src/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesFunctionalTest.java:564-606`(고정한 것은 `-qm`·`-mx`뿐)
- 무엇이 틀렸나: 옵션 표는 9.0.0 `--help`와 정확히 같다. 하지만 표를 실행 중인 Gradle과 비교하는 테스트가 없다. TestKit 테스트는 build-logic을 돌리는 Gradle(wrapper)에서 돌지만 두 모양만 본다. Gradle 9.2.0은 `--task-graph`("Print task graph instead of executing tasks")를 더했다. 9.2.0에서 `gradle :ci --task-graph`는 rc=0이고 작업을 실행하지 않는다. 판독기는 이 옵션을 모르는 긴 옵션으로 넘기고 `:ci` 실행으로 센다.
- 발생 조건·영향: wrapper를 9.2 이상으로 올린 뒤 계획만 보려고 `./gradlew :integrationCheck --task-graph` 같은 step을 둔 경우다. 이 repo의 `configuration-cache` job이 `--dry-run`으로 하는 일과 같은 용도다. 검사는 통과하고 lane은 돌지 않는다. wrapper 변경 PR은 `build-logic.yml`(경로 `src/gradle/**`)을 돌리지만 지금 테스트는 그대로 통과한다. 9.7.1은 값 옵션 `--console-unicode`·`--develocity-url`·`--develocity-plugin-version`과 플래그 `--non-interactive`·`--isolated-projects`도 더했다.
- 고치는 법: TestKit 테스트 하나를 더한다. `runner("--help")` 출력에서 옵션 이름을 뽑아 `GRADLE_FLAGS ∪ GRADLE_VALUE_OPTIONS`(그리고 RR6-04-01의 작업 없이 끝나는 목록)과 같다고 단언한다. 그러면 Gradle을 올리는 PR이 새 옵션마다 "값을 받는가, 작업을 실행하는가"를 정해야 통과한다. Javadoc과 README의 "고정" 문장은 실제로 고정한 범위로 고친다.
- 이번 커밋/이전부터: 이번 커밋. 표와 "고정" 주장을 이번에 새로 뒀다.
- 증거: E3. Gradle 9.0.0·9.2.0·9.7.1 `--help`의 옵션 이름과 판독기 표 대조(9.0.0: 표에 없는 옵션 0, 표에만 있는 옵션 0). 임시 프로젝트에서 9.0.0 `:ci --task-graph` → rc=1 "Problem configuring task :ci from command line", 9.2.0 → rc=0, "Tasks graph for: :ci", 작업 미실행. 판독기 probe(`cases/03-task-graph.yml`) → `executes=true`.
### RR6-04-03 · 스크립트가 그 명령 앞에서 끝날 수 있는 모양 중 맨 위의 `exit`만 본다
- 심각도: Minor (Low · P2)
- 위치: `src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/ShellScript.java:943-948`(맨 위에 혼자 있는 `exit`만 `terminated`), `:21-29`(Javadoc "anything after ... a top-level exit"), `:1144-1174`(`setEffect`가 `-n`을 모름)
- 무엇이 틀렸나: 판독기는 뒤 명령이 아예 돌지 않는 경우를 맨 위의 무조건 `exit` 하나로만 안다. 아래 모양에서 bash는 `./gradlew :ci`를 돌리지 않거나 그 실패를 버리고 step을 초록으로 끝낸다. 판독기는 모두 실행으로 센다.
- `if git diff --quiet origin/main -- .; then echo "no source change"; exit 0; fi` 다음 줄의 `./gradlew :ci`
- `[ "$SKIP_CI" = true ] && exit 0` 다음 줄
- `skip() { echo skip; exit 0; }`를 부른 다음 줄
- `exec ./gradlew :help` 다음 줄(셸이 Gradle로 바뀌어 다음 줄은 돌지 않는다)
- `set -n` 다음 줄(명령을 읽기만 하고 실행하지 않는다)
- `trap 'exit 0' EXIT` 뒤의 `./gradlew :ci`(돌지만 실패해도 step이 0으로 끝난다)
- 왜 결함인가: 같은 판독기는 step의 `if:`가 상태 함수가 아니면 "매 실행이 아니다"라며 세지 않는다. 스크립트 안의 조건부 `exit 0`도 같은 일을 한다. "바뀐 것이 없으면 건너뛴다"는 CI에서 흔한 모양이다.
- 고치는 법:
1. 맨 위가 아닌 곳(복합 명령, `&&`·`\|\|` 목록, 함수 본문)의 `exit`가 `exit 0`, 인자 없는 `exit`, 리터럴이 아닌 값이면 그 뒤 명령을 "앞의 `<exit>`가 그 전에 스크립트를 끝낼 수 있다"로 세지 않는다. `exit 1`처럼 0이 아닌 리터럴은 step을 실패로 끝내므로 지금처럼 둔다(이 repo `main-check` 첫 step의 `if …; then …; exit 1; fi` 모양).
2. 맨 위의 `exec <명령>`은 `exit`처럼 그 뒤를 끝낸 것으로 본다.
3. `set -n`·`set -o noexec`도 그 뒤를 끝낸 것으로 본다.
4. `trap`의 `EXIT`·`ERR` 동작에 `exit`가 있으면 그 뒤 명령을 세지 않는다.
5. 모양마다 RED 단위 테스트를 둔다.
- 이번 커밋/이전부터: 이전부터. 이번 커밋이 `exit`를 다루면서 무조건 `exit`만 막았다.
- 증거: E3. `bash -e`에 가짜 `gradlew`(호출을 기록하고 exit 1): 조건부 exit 두 모양·함수 안 exit·`set -n` → rc=0, 호출 0. `exec` → 다음 줄 호출 없음. `trap 'exit 0' EXIT` → 호출됐지만 rc=0. 판독기 probe(`cases/02-conditional-exit.yml`, `cases/11-more-exit.yml`) → 6개 모두 `executes=true`.
### RR6-04-04 · Windows runner의 기본 셸을 `bash -e`로 읽는다
- 심각도: Minor (Low · P3)
- 위치: `WorkflowGradleInvocations.java:32-35`(Javadoc "GitHub's default `bash -e`"), `:94-99`(`SHELLS`의 `""` → `bash -e`), `:298-310`(`runs-on`을 보지 않음), `src/build-logic/README.md:19`("a step whose `shell:` is not the default, `bash` or `sh`"), `docs/upgrade/2026-11-maturity-review.md:107`(B-36 "`shell:`이 기본·`bash`·`sh`가 아닌 단계도 세지 않는다")
- 무엇이 틀렸나: GitHub 문서에서 `shell`이 없을 때 Linux·macOS의 기본은 `bash -e {0}`이고 Windows의 기본은 `pwsh`다. pwsh에서 GitHub는 `$ErrorActionPreference = 'stop'`을 앞에, `if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE }`를 뒤에 붙인다. 네이티브 명령(`gradlew.bat`)이 0이 아닌 코드로 끝나도 스크립트는 멈추지 않는다. step 결과는 마지막 네이티브 명령의 코드다. 판독기는 `runs-on`을 보지 않고 모든 기본 셸을 `bash -e`로 읽는다.
- 발생 조건·영향: 파생 서비스가 `runs-on: windows-latest`(또는 matrix에 windows가 있는) job에서 `./gradlew :ci` 다음 줄에 `git status` 같은 네이티브 명령을 둔 경우다. Gradle이 실패해도 step은 초록이고 검사도 통과한다. 이 repo의 job 62개는 모두 `ubuntu-latest`라 지금은 해당하지 않는다. `container:` job의 기본은 `sh -e`인데 `-e` 켜짐·pipefail 없음이 같아 판정은 바뀌지 않는다. 주석의 "기본 = bash -e"만 정확하지 않다.
- 고치는 법: job의 `runs-on`을 읽는다. `shell`이 없고 `runs-on`이 `ubuntu-`·`macos-` 리터럴이 아니면(Windows 라벨, `${{ }}` 식, 알 수 없는 self-hosted 라벨) "기본 셸이 Windows의 pwsh일 수 있다"로 세지 않는다. Javadoc·README·B-36에는 "Linux·macOS의 기본"과 container의 `sh -e`를 적는다. `runs-on: windows-latest` RED 단위 테스트를 둔다.
- 이번 커밋/이전부터: 이번 커밋. 셸 판독과 "기본 = `bash -e`" 주장을 이번에 새로 뒀다.
- 증거: E3(판독기 probe `cases/01-windows.yml` → `executes=true`) + E1(GitHub workflow syntax의 shell 표와 "Exit codes and error action preference" 절, container 문서의 "The default shell for `run` steps inside a container is `sh`"). pwsh 실행은 하지 않았다.
### RR6-04-05 · 문서와 실패 메시지가 세지 않는 이유를 사실과 반대로 적는다
- 심각도: Minor (Low · P3)
- 위치: `docs/upgrade/2026-11-maturity-review.md:107`(B-36 괄호 안의 `\|\| exit 1`, "`if`·`for`·`case`·함수·`$( )`·`bash -c` 안"), `src/build-logic/README.md:19`("`\|\| true` or any `\|\|`", "the condition or body of `if`/`while`/`for`/`case`", "a command line Gradle rejects (`-mx` …)"), `AGENTS.md:87-89`("복합 명령·함수·명령 치환 안", "Gradle이 거부하는 명령줄(`-mx`)"), `CLAUDE.md:44-46`, `StrictLaneStagesPlugin.java:153-156`(요약 문구), `ShellScript.java:967-970`(`|| exit 1`에 "its failure is handled")
- 무엇이 틀렸나:
- `./gradlew ci || exit 1`, `if [ -n "$RUN" ]; then ./gradlew ci; fi`, `{ ./gradlew ci; }`, `( ./gradlew ci )`의 Gradle 실패는 `bash -e`에서 step을 실패시킨다. README 16절 결정대로 이 모양을 세지 않는 것(거짓 실패 쪽)은 맞다. 그런데 문서 넷과 실패 메시지는 이유를 "실패해도 단계를 실패시키지 못한다(a command whose failure cannot fail its step)"로 적는다. 사실과 반대다.
- 문서는 "Gradle이 거부하는 명령줄은 세지 않는다"고 적는다. 구현은 짧은 옵션 묶음만 본다. `./gradlew :ci --task-graph`(9.0에서 거부, rc=1)나 `./gradlew :ci -x --dry-run`은 Gradle이 거부하지만 판독기는 센다. 매 실행 빨간 step이라 조용한 통과는 아니다. 문서가 구현보다 넓게 약속한다.
- 영향: 실패를 workflow annotation으로 남기려고 `./gradlew ci || { echo "::error::ci failed"; exit 1; }`를 쓴 파생 서비스는 "your command cannot fail its step"을 받는다. 개발자는 검사가 틀렸다고 보고 우회를 찾는다. 해야 할 일(명령을 혼자 한 줄로 둔다)은 메시지에 없다.
- 고치는 법: 세지 않는 이유를 셋으로 나눠 문서와 메시지에 같은 말로 적는다.
1. 실패를 막지 못함: `|| true`·`|| :`, pipefail 없는 파이프 왼쪽, `!`, `&`, `if`·`while` 조건, `set +e` 뒤, 마지막이 아닌 `&&` 목록.
2. 돌지 않을 수 있음: 복합 명령·함수 본문 안, 맨 위 `exit` 뒤(RR6-04-03), 상태 함수가 아닌 `if:`.
3. 판독기가 읽지 않음(실패하면 step도 실패하지만 세지 않는다, 거짓 실패 쪽): `|| exit 1`, `|| { …; exit 1; }`, 서브셸·`{ }`, `$( )`, `bash -c`.
`listReason`은 `||` 오른쪽이 0이 아닌 `exit`면 "이 모양은 읽지 않는다. 명령을 혼자 한 줄로 두라"고 말한다. "Gradle이 거부하는 명령줄"은 "Gradle이 거부하는 짧은 옵션 묶음(`-mx`)"으로 좁힌다. 요약 문구와 AGENTS.md·CLAUDE.md·README·B-36을 함께 고친다.
- 이번 커밋/이전부터: 이번 커밋.
- 증거: E3. `bash -e` probe: `./gradlew :ci || exit 1`, `if true; then ./gradlew :ci; fi`, `{ ./gradlew :ci; }`, `( ./gradlew :ci )` 각각 다음 줄에 `echo done` → 모두 rc=1(step 실패). 판독기 probe(`cases/12-gated-but-uncounted.yml`) → 미집계, 이유 "its failure is handled by the `|| { echo "::error::ci failed"; exit 1; }` after it". 문서는 E1 대조.
### RR6-04-06 · 사람이나 다른 workflow가 시작해야만 도는 workflow·job을 실행으로 센다
- 심각도: Minor (Low · P3)
- 위치: `WorkflowGradleInvocations.java:364-410`(`dispatchOnlyReason`은 trigger가 모두 `workflow_dispatch`일 때만), `:528-542`(`uncountedReason`은 step과 자기 job의 `if:`만 본다)
- 무엇이 틀렸나: "`workflow_dispatch`로만 시작하는 workflow는 묻지 않으면 아무것도 돌리지 않으므로 세지 않는다"(RR2-04-04)는 규칙이 같은 이유의 다른 모양을 보지 않는다. 아래는 모두 판독기가 실행으로 센다.
- `on: [workflow_dispatch, repository_dispatch]`, `on: issue_comment`(ChatOps `/test`): 외부 요청이 있어야 돈다.
- `on: workflow_call`만 있는 재사용 workflow: 부르는 workflow가 없거나 조건부로 부르면 돌지 않는다.
- `needs:`로 기다리는 job이 상태 함수가 아닌 `if:`로 건너뛰어지는 job. GitHub 문서: "If a job fails or is skipped, all jobs that need it are skipped unless the jobs use a conditional expression that causes the job to continue."
- 발생 조건·영향: 파생 서비스가 무거운 단계를 ChatOps나 재사용 workflow, 또는 조건부 job 뒤로 옮긴 경우다. 검사는 통과하고 단계는 요청이 있을 때만 돈다. 이 repo의 workflow에는 지금 이 모양이 없다.
- 고치는 법:
1. 시작 trigger가 모두 요청형(`workflow_dispatch`, `repository_dispatch`, `issue_comment` 등)이면 세지 않는다.
2. `workflow_call`만 있는 workflow는 직접 세지 않는다. `jobs.<id>.uses: ./.github/workflows/<file>`로 부르는 job의 trigger와 `if:`를 물려받아 센다. 부르는 곳이 없으면 세지 않는다.
3. job의 `needs:`를 따라가며 각 job의 `if:`에 같은 규칙을 적용한다. 자기 `if:`에 `always()`·`!cancelled()`가 있으면 거기서 끊는다.
4. 모양마다 RED 테스트를 둔다.
- 이번 커밋/이전부터: 이전부터.
- 증거: E3(판독기 probe `cases/04-workflow-call.yml`, `07-triggers.yml`, `08-issue-comment.yml`, `09-needs.yml` → 모두 `executes=true`) + E1(GitHub workflow syntax `jobs.<job_id>.needs` 절).
## Declined to judge
- 경로·브랜치 필터(`paths:`, `branches:`)가 있는 trigger: 그 workflow가 도는 이벤트에서는 단계가 실제로 돈다. 어떤 필터가 충분한지는 저장소 정책이라 판단하지 않았다.
- 설계상 거짓 실패 모양(`timeout ./gradlew …`, `set +e` / `./gradlew …` / `exit $status`, `|| exit 1`, 서브셸·`eval`·`source` 안의 `cd` 뒤): README 16절 결정이라 다시 올리지 않았다. 이유 문구만 RR6-04-05에 넣었다.
- `${{ }}` 값이 `--dry-run`이나 `|| true`로 펼쳐지는 경우: 실행 전에는 값을 알 수 없다.
- `CDPATH`·심볼릭 링크로 `cd`가 다른 곳으로 가는 경우: GitHub runner 기본 환경에는 `CDPATH`가 없다.
- composite action(`.github/actions/*/action.yml`) 안의 `run:`: 판독기가 읽지 않는다. 거짓 실패 쪽이라 결함으로 올리지 않았다.
- httpclient 문서(`docs/httpclient/support-matrix.md:61,65`, `docs/httpclient/release-checklist.md:12`): 장애 주입 lane 주기에 main push가 빠졌고, `spring62CompatibilityTest`는 없는 lane 이름이다(실제 이름 `spring62ApiSurfaceScan`, 2026-09-18 리뷰가 이미 적음). pathspec 밖 다른 영역 파일이라 판정하지 않았다. 총괄이 해당 영역으로 넘길 것.
- 실제 GitHub runner와 pwsh 동작: 이 환경에서 실행할 수 없다. RR6-04-04는 문서 근거다.
## 결론
Critical 0, Important 0, 회귀 0. 결함 6건, 모두 Minor다.
- 이번 커밋 3건: RR6-04-02(옵션 표를 Gradle 올림에서 지키는 테스트 없음), RR6-04-04(Windows 기본 셸), RR6-04-05(세지 않는 이유 문구).
- 이전부터 3건: RR6-04-01(작업 없이 끝나는 Gradle 옵션), RR6-04-03(조건부 `exit`·`exec`·`set -n`·`trap`), RR6-04-06(요청형 trigger·`workflow_call`·`needs`).
r9-d가 고쳤다고 한 항목(README 15 남음, RR5-02-01·02·03, `-mx`, 장애 주입 lane 중복)은 모두 닫혔다. 이 repo의 실제 workflow 판정은 `c508b1ba`와 같고 두 빌드의 `verifyStrictLaneStages --dry-run`이 통과한다. 남은 결함은 모두 파생 서비스가 쓸 수 있는 모양에서 검사가 거짓으로 통과하거나 이유를 틀리게 말하는 것이다.
+7 -5
View File
@@ -19,8 +19,10 @@ status: active
action, so a client retry is safe.
- The same 503 when the store refused to start a claim whose processing lease had already run out
— the request spent longer than the lease between its claim and the start of its action (a
stalled process, a slow store call). The ERROR line's message then reads `the claim's processing
lease ran out before the action started; nothing ran: <scope>`, and the store may be healthy.
stalled process, a slow store call). The ERROR line, `failure classified as
IDEMPOTENCY_UNAVAILABLE (…)`, has the exception attached, and the exception's message reads `the
claim's processing lease ran out before the action started; nothing ran: <scope>` — in prod JSON
logs that is in `stack_trace`, not `message`. The store may be healthy.
Nothing ran here either, and the next request with the key takes the claim over and runs it.
- HTTP 503 `IDEMPOTENCY_COMPLETION_UNKNOWN` (`retryable=true`) is the same outage hitting after the
action ran: the store did not answer while the result was being recorded. When the use case called
@@ -98,9 +100,9 @@ status: active
## Action
- `IDEMPOTENCY_UNAVAILABLE`: restore the store; clients retry with the same key and backoff. When
the message says the claim's processing lease ran out before the action started, the store is
not the cause: find what held those requests between claim and start (thread dumps, GC pauses,
the store's latency in that window). Nothing to repair; the next same-key request runs.
the exception message says the claim's processing lease ran out before the action started, the
store is not the cause: find what held those requests between claim and start (thread dumps, GC
pauses, the store's latency in that window). Nothing to repair; the next same-key request runs.
- `IDEMPOTENCY_COMPLETION_UNKNOWN`: restore the store, then check the effects outside the
transaction for the failed requests (the ERROR log line names the code). A same-key resend replays
a result that was in fact recorded, gets `IDEMPOTENT_IN_FLIGHT` while the attempt's lease lasts,
+34 -10
View File
@@ -1336,15 +1336,35 @@ startup 동작으로는 절대 아니다.
### 8.2 `ConcurrentIndexMigrationInspector`
PostgreSQL은 `CREATE INDEX CONCURRENTLY`를 트랜잭션 블록 안에서 아예 거부하고, Flyway는
기본적으로 마이그레이션을 트랜잭션으로 감싼다. **그래서 첫 배포에서 실패하는데, 그게 좋은
경우다.**
PostgreSQL은 `CREATE INDEX CONCURRENTLY`·`DROP INDEX CONCURRENTLY`·`REINDEX … CONCURRENTLY`를
트랜잭션 블록 안에서 거부한다. Flyway 11은 `CREATE`/`DROP INDEX CONCURRENTLY`가 든 파일을 **스스로
트랜잭션 밖에서** 돌린다. `REINDEX … CONCURRENTLY`는 모른다. 그 파일은 트랜잭션 안에서 돌고, 배포 때
PostgreSQL이 거부한다. 그래서 검사기는 동시 인덱스 문장이 있으면 `.sql.conf`에
`executeInTransaction=false`를 적으라고 요구한다. Flyway가 알아서 빼 주는 문장에도 적는다. 파일이
자기에게 필요한 것을 스스로 말하게 하려는 것이다.
> 나쁜 경우는 다른 statement와 섞인 마이그레이션이다: 그것들은 커밋되고, concurrent index는
> 안 되고, 스키마는 **history row가 반대로 말하는 채로 부분 마이그레이션 상태로 남는다.**
> 다른 문장과 섞인 파일은 Flyway가 기본값(`mixed=false`)에서 **아무것도 실행하기 전에 거부**한다.
> 부분 적용은 일어나지 않는다. 그래도 한 파일에 하나만 두는 이유는 아래 `requireIsolatedStatement`의
> 복구 때문이다.
검사 대상: `create index concurrently`, `drop index concurrently`, `reindex index concurrently`,
`reindex table concurrently`, `reindex concurrently`.
트랜잭션 밖에서도 동시 빌드는 **자기보다 먼저 시작한 트랜잭션이 모두 끝나기를 기다린다.**
```
Flyway 기본값: 잠금 트랜잭션(열린 채) ──기다림──▶ 마이그레이션 끝
▲ │
└──────── CIC가 기다림 ◀───────────┘ → 배포가 끝나지 않는다
```
- Flyway는 기본으로 마이그레이션 잠금(PostgreSQL advisory lock)을 트랜잭션 안에 두고, 실행 내내 그
트랜잭션을 열어 둔다.
- CIC는 그 트랜잭션도 기다린다. Flyway는 CIC가 끝나기를 기다린다. 오류도 시간 제한도 없다.
- 템플릿은 잠금을 세션에 둔다. Spring Boot의 Flyway는 module-defaults의
`spring.flyway.postgresql.transactional-lock: false`, 템플릿이 직접 만드는 Flyway는
`FlywaySchemaPolicy.configure()`로 받는다. 배포 마이그레이션 도구도 같은 값이어야 한다
(`docs/jpa/migration-guide.md` "Who may change the schema").
검사 대상: `CREATE [UNIQUE] INDEX CONCURRENTLY`, `DROP INDEX CONCURRENTLY`, `REINDEX … CONCURRENTLY`
(`REINDEX (CONCURRENTLY) TABLE` 같은 괄호 옵션 포함).
`requireIsolatedStatement`도 있다 — concurrent 빌드가 실패하면 invalid index가 남고, 그
복구는 마이그레이션이 다른 걸 아무것도 안 했으면 `DROP INDEX` 하나지만 뭔가 했으면 부분
@@ -1700,15 +1720,19 @@ inserted == 1 → Acquired
COMPLETED이고 replay_until 지남 → resetClaim → TakenOverClaimed
request_hash 불일치 → FingerprintMismatch
COMPLETED이고 replay_until 있음 → CompletedReplay(payload, replayUntil)
같은 claim attempt(token+operationId) → ReplayedAcquire
같은 token, 다른 operationId → OwnerOperationConflict
ABANDONED → RecoveryRequired
CLAIMED이고 lease 만료 → resetClaim → TakenOverClaimed
FAILED_RETRYABLE → resetClaim → TakenOverClaimed
같은 claim attempt(token+operationId) → ReplayedAcquire
같은 token, 다른 operationId → OwnerOperationConflict
EXECUTING이고 lease 만료 → RecoveryRequired (행은 그대로)
ABANDONED → RecoveryRequired
그 외 → InProgress(retryAfter, attempt)
```
넘겨받기 두 줄이 같은 attempt의 재생보다 앞이다. 시작을 거절당했거나 재시도 가능 실패로 끝난 attempt가
같은 attempt로 다시 오면 재생이 아니라 넘겨받기다. 재생하면 시작할 수 없는 claim을 돌려줘 기록이 사라질
때까지 막혔다(라운드6 RR6-02-01, Redis CLAIM도 같은 순서).
**만료된 `CLAIMED`만 takeover하고, 만료된 `EXECUTING`은 reconciliation을 요구하되 행은 바꾸지
않는다.** 실행이 시작된 뒤의 blind retry를 하지 않는다는 뜻이다. 행을 그대로 두는 이유는 주인이 아직
돌고 있을 수 있어서다. 주인이 늦게 끝나면 그 결과가 기록되고 다음 claim이 재생한다(2026-11-04 소유자
+8 -4
View File
@@ -248,10 +248,14 @@ source set에서 태그 `jpa-contract`로 `jpaPlatformContractTest` lane이 돌
고쳤다. in-memory store는 `DirectTransactionPort`를 받으면 같은 규칙(트랜잭션 밖·읽기 전용 거부,
롤백 시 취소)으로 동작한다. 인자 없이 만들면 지금처럼 바로 쓴다(relay 테스트가 행을 미리 심는 용도).
- `IdempotencyStoreContract`의 시간 케이스(renew가 lease를 실제로 늘린다, review 05-02)는 시계를
가진 store(실 Redis, PostgreSQL)에서만 의미가 있다. 시계를 움직일 수 없는 store(in-memory fake,
command fake 위 Redis)는 `elapse`를 재정의하지 않고, 기본 `elapse`가 그 케이스를 abort해 보고서에
skipped로 남는다. 예전에는 no-op이라 시간이 흐르지 않은 채 통과했다(review 2026-11-03 RR-01-06).
PostgreSQL에서 renew가 lease를 늘리지 않게 바꾼 변이로 이 케이스가 실패함을 확인했다.
가진 store(실 Redis, PostgreSQL, command fake 위 Redis)에서만 의미가 있다. command fake는
`advance`로 시계를 움직이고 멱등성 기록에 key TTL을 두므로 `RedisIdempotencyStoreContractTest`가
`elapse`를 재정의해 시간 케이스를 모두 돌린다(라운드6 RR6-02-02 — 전에는 skip했고 adapter 테스트가 일부를
손으로 복사했다). 시계를 움직일 수 없는 in-memory fake는 `elapse`를 재정의하지 않고, 기본 `elapse`가 그
케이스를 abort해 보고서에 skipped로 남는다. 예전에는 no-op이라 시간이 흐르지 않은 채 통과했다(review
2026-11-03 RR-01-06). PostgreSQL에서 renew가 lease를 늘리지 않게 바꾼 변이로 이 케이스가 실패함을
확인했다. command fake의 claim key TTL을 replay TTL만으로 줄이거나 renew의 TTL 연장을 빼는 변이로 기록 수명
케이스 3건이 실패함을 확인했다.
- `OutboxAggregateSequenceContract`는 포트 Javadoc의 세 약속 중 둘을 보지 않았다(RR-01-06). "쓰기
트랜잭션 밖 거부"와 "롤백된 번호는 다시 준다"를 넣었다. fake는 `DirectTransactionPort`를 받으면 같은
규칙으로 동작한다(인자 없이 만들면 예전처럼 트랜잭션을 보지 않는다 — sample 테스트가 쓰는 방식).
File diff suppressed because one or more lines are too long