Files
clean-architecture-backend-…/docs/reviews/2026-09-24-src-maintainability-review.md
T
DongHyeonkaandClaude Opus 5.5 6d27356e2b refactor: 부가 기능을 capability 모듈로 포장하고 기본 조립을 web-only로 전환
설계: docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md
계획/진행 기록: docs/superpowers/plans/2026-09-25-capability-module-packaging.md

- Wave 0: 규칙 고정(AGENTS.md capability 완료 기준·테스트 규칙) + 차단 결함 7건
  (compose overlay 검사, redis-sdk CI job, 적용된 V9/V13 원복 + V16, @EnableScheduling,
  messaging bridge 순서, prod 에러 상세 validator, sample loggers read-only)
- Wave 1: 데이터·보안 Critical 10건 (durable operation 25P02, operation 유스케이스 이동,
  outbox 재인코딩, Kafka TLS/SASL, 알림 트랜잭션, SNS 서명, tus checksum, GraphQL fragment,
  Redis lane, gRPC FAILED_TERMINAL)
- Wave 2: 리팩터링 잔재·실험용 자리 삭제, outbox v1 fencing(V17), 멱등성 V2 정본화
- Wave 3: 라이브러리형 코드 정리(동작하지 않는 설정·인터페이스·gate 제거, web-advanced 분리)
- Wave 4: capability 11개를 "있으면 켜짐" 모듈로 포장, 끄는 장치 제거, 기본 조립 web-only,
  qualificationBootJar 분리
- Wave 5: 빌드 로직 축소(17.2k -> 10.8k줄), sample 테스트 컨벤션 적용

삭제한 코드는 docs/capability-status.md "제거된 코드" 표에 복구 커밋(208077fd)과 함께 기록.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-25 12:49:07 +09:00

182 KiB
Raw Blame History

src/ 유지보수성·구조 리뷰 (2차) — 2026-09-24

개요

항목 내용
목적 1차 리뷰(2026-09-24-src-module-code-review.md, 결함 중심)에서 빠진 관점 — 유지보수, 단일 책임, 공통 계약 추출, 디자인 패턴, 테스트 가독성(given/when/then), 빌드 인프라 비례성
기준 main @ 208077fd 작업 트리
방법 읽기 전용 리뷰 에이전트 11개 병렬: 모듈 그룹별 구조 리뷰 7개(S1–S7), 모듈 간 기능 중복(X1), 공통 유틸·전송 경계(X2), 빌드 비례성(BUILD), 테스트 구조(TEST). 건수 제한 없이, 비슷한 사례는 한 건으로 묶음
규칙 패턴은 코드를 줄이는 경우에만 권고. 반대로 구현 1개짜리 인터페이스·전달만 하는 계층은 삭제 권고

질문별 답

1. 유지보수·SRP·공통 계약 — 핵심은 "나쁜 코드"보다 "여러 세대와 미조립 코드의 공존"

모듈 경계(HARD-STOP 1·2·3·5)는 지켜지고 있다. 문제는 한 기능에 2~3세대 구현이 함께 있고, 그중 상당수가 실제 앱에 조립되지 않는다는 점이다. adopter는 어느 것이 정본인지 알 수 없고, 수정이 한쪽에만 들어가 이미 갈라진 곳이 여러 군데다.

조립되지 않은(도달 불가) 코드 추정치 — 그룹마다 측정 방법이 달라 겹침·오차가 있다. 일부는 의도적으로 제공하는 라이브러리 코드다.

영역 추정 근거
redis-sdk + redis-runtime의 SDK 전용 부분 약 25.7k S3 #3, 1차 G-6
graphql 약 14.7k 1차 J-10, S5
web (2세대 platform, WebFlux) 약 13.3k S5 #2·#4
persistence-mongo 약 13.1k S2 #2
messaging:* ≥12.7k S7
grpc:* / grpc-advanced 약 12.4k S7
persistence-jpa (플랫폼 라이브러리·V2·중복 엔진) 약 10.1k S2 #3·#4·#7
websocket 플랫폼 라이브러리 약 9.7k S6 #1
fileserver 어댑터 루트(R1/R2 publication) 약 8.7k S4 #1
notification (R1 4.5k + platform 0.9k + provider 5종 3.0k) 약 8.4k S1 #14, S4 #3
application-core 약 4.9k S1 #1–#3
objectstorage (direct/multipart, legacy adoption) 약 4.0k 1차 D-7, S4 #10
messaging 어댑터 R1 약 3.5k S4 #2
합계 약 15만 줄 (main 32만 줄의 약 절반)

여러 벌로 갈라진 기능과 권고(X1·X2 요약)

기능 현재 권고
Outbox 세대 3개. 실제 조립된 v1에만 fencing이 없음(중복 발행 위험). 고친 두 구현(V2, messaging)은 미조립 앱 쪽 1벌. v1 테이블 + V2/V1002 fencing 이식 후 V2 삭제(또는 반대). messaging outbox는 vendored라 유지
멱등성 v1/V2 계약 2개, store 3개, executor 조립 3곳, inbound 전용 ledger 3개 V2를 정본, v1 삭제, 조립 1곳
에러 어휘 HTTP 응답 형식 3개(Envelope, WebProblem, Fileserver problem), 코드 체계 4개. 같은 코드의 status·retryable이 전송마다 다름 ApiErrorCode 하나 + Envelope. shared 예외 5종에 ApiErrorCarrier 구현, GraphQL retryable은 코드별 값
caller 트랜잭션 guard 9벌 복사, 빠진 곳에서 dual-write 결함 persistence-jpa CallerTransaction.require 하나
테스트 fake 같은 포트 fake가 모듈마다 따로(TransactionPort 21~26개), 실제 adapter와 대조하는 kit는 1개 포트 소유 모듈 testFixtures에 추상 contract 클래스
시크릿·prod 판정·tenant·MDC 시크릿 경로 4갈래, prod 판정 재구현, TenantContext 2개(문법 다름), MdcKeys가 web에 갇힘 기존 정본(SecretSourcePort, RuntimeEnvironment)에 bridge 1줄씩, tenant 값 타입 1개, MdcKeys는 shared-contract로
capability 활성화 규칙 6곳에 흩어지고 기본값이 이미 3가지로 갈림 표 하나(키·기본값·필요 조건·prod secret)에서 validator·endpoint 파생
readiness/evidence/API-surface 카드 스키마 3개, API-surface gate 3개, moduleboundary 3벌 build-logic 구현 하나
작은 유틸 SHA-256 헬퍼 53개, JSON escape 3가지 동작, backoff "full jitter" 뜻 3가지, HMAC cursor codec 7개 shared-contract Sha256, Backoff, 서명 헬퍼(삭제 후 남으면)

디자인 패턴 — 코드가 줄어드는 곳에만 권고했다.

  • Template Method: httpclient blocking/reactive 공통 코어(약 600~700줄 감소, S3 #1).
  • 상태 전이표(State): ProviderRuntime, FileState, LocalPersistentControlPlane의 전이 규칙(S4 #5·#14, S1 #13).
  • Strategy / EnumMap 표: GraphQL 에러 category switch 3개, Redis 스크립트 status switch 5개(S5 #6, S3 #5).
  • 정적 factory / Value Object: PublishResult 7-인자 생성 28회, fileserver 원시 String 검증 73곳(S7 #6, S4 #8).
  • Rule 목록: startup validator 19개 → StartupRule 목록 + runner 1개(S6 #3).
  • 반대 방향(삭제): 구현 1개짜리 인터페이스·레지스트리·facade 다수 — httpclient 4개, application-fileserver 6개, notification 레지스트리 2개, PolicyTransactionPort 계열, SelectedObjectStorageProviderFactory, fileserver R2 routing 계층 등.

2. 테스트 given/when/then

  • // given // when // then을 모두 갖춘 파일: 1,500개 중 0개(일부만 5개). 다만 6줄 이상 테스트의 71%는 빈 줄로 단계를 나누고, 이름은 전부 camelCase 행동 문장이라 흐름 자체는 대체로 보인다.
  • 더 급한 문제 두 가지: (a) fake가 실제 adapter와 같은 계약 테스트를 통과하지 않는다 — 1차 리뷰의 "fake가 숨긴 결함" 6건 중 5건이 여기에 해당. (b) 이름이 약속한 성질을 단언하지 않는 테스트가 약 1,050개(12%).
  • adopter가 복사하는 sample-portfolio가 가장 약하다(DisplayName 0%, 단계 분리 54%, 115줄 테스트).
  • 제안: GWT 주석을 규칙으로(본문 3문장 이상이면 필수, // when은 정확히 하나), 이름에 적은 성질은 반드시 단언, 포트별 추상 contract 테스트, Mockito는 프레임워크 경계에만. 새로 쓰거나 고치는 테스트에만 적용하고 sample부터 모범 사례로 재작성. 주석 게이트(자동 강제)는 만들지 않음 — 이유는 TEST 절.

3. 빌드 인프라 — 목적 대비 과하다. 목적에 필요한 부분은 약 13%

  • build-logic + build-tools 16,768줄 중 아키텍처 강제(A)는 2,242줄(13%), 핵심만 따지면 1,301줄(8%). 기능별 증거 검사(E)가 7,760줄(46%)로 가장 크다.
  • Gradle 방향 게이트와 ArchUnit 규칙 105개는 필요한 크기다. 줄일 대상이 아니다.
  • 최근 "gradle 얇게" 리팩터에서 빌드 코드가 늘었다: ace8aaae(09-17) → 208077fd(09-24) 사이 build-logic/build-tools/script plugin 합계 약 4.7k → 17.1k줄(직접 측정). leaf 스크립트는 215줄만 줄었다.
  • 권고: O3 — build-logic에는 아키텍처 코어(registry, 방향·순수성 task)·컨벤션·레인 하나만 두고, 기능별 검사는 소유 leaf의 테스트로 옮긴다(목표 약 3.5–4k줄, build-tools 0). 그 전에 어느 안을 고르든 안전한 정리 11개로 약 3.4k줄 감소, 잃는 보호 없음. 09-16 단계 분리 계획의 미이행분(PR에 남은 2단계 게이트 11개)은 삭제가 아니라 단계만 옮긴다.
  • 빈틈 하나: 빌드 단계 순수성 검사가 application-*만 본다. domain-core에 외부 의존을 추가해도 빌드는 통과한다(필터 3줄 추가로 해결).

결정 필요 (승인자: 저장소 소유자)

# 결정 권고
D1 미조립 대형 코드 처리 — redis-sdk, Mongo advanced/reactive, graphql advanced/compat, websocket 플랫폼, web 2세대·WebFlux, notification provider 5종, fileserver R2 publication, messaging experimental/rabbit/avro 등, grpc-advanced family별로 "삭제 / optional-platforms 같은 별도 build로 이동 / 유지" 중 선택. 기본값은 이동(공개 약속 유지, 기본 빌드에서 제외)
D2 Outbox 정본 v1 테이블 유지 + fencing 이식, V2 삭제 (반대도 가능. 목표는 1벌)
D3 멱등성 정본 V2 (Redis·소유자 fencing이 V2에만 있음)
D4 WebFlux 지원 현재 어떤 조합으로도 켜지지 않음. 삭제 권고. 유지하려면 starter-web을 leaf에서 빼고 composition이 선택
D5 빌드 목표안 O3 (순서: 단계 재배치 → 안전한 정리 → O3)
D6 테스트 컨벤션 제안안 채택 여부, @DisplayName 언어(기본 영어)

권고 순서

  1. 1차 Critical 수정과 함께 contract 테스트 추가. fake가 결함을 숨긴 6개 포트의 추상 contract를 수정 PR에 같이 넣는다. contract가 현재 코드에서 먼저 실패하면 그것이 회귀 테스트다.
  2. 빌드 안전 정리 1–11 + 단계 재배치(BUILD 절 "바로 할 것"). 서로 독립적이고 보호 손실 없음.
  3. D1–D4 결정 후 삭제/이동. 가장 큰 LOC 감소. 그 뒤 outbox·멱등성·에러 어휘를 하나로 합친다.
  4. 테스트 컨벤션 문서화 + sample-portfolio를 모범 사례로 재작성. 나머지는 손대는 테스트부터.

1차 리뷰 보정

  • 1차 B-2(SNS 서명 우회): 영향 서술 중 "위조 callback이 SesSuppressionUpdater로 suppression을 만든다"는 과장이다. 이 클래스는 참조가 0이다(S4 #3). 서명 검증 우회 자체는 유효하다.
  • 1차 A-2(websocket prod 판정): 수정이 더 간단하다. bridge 없이 RuntimeEnvironment.isProductionActive(...) 정적 호출 한 줄이면 된다(X2 P1-2).
  • 1차 O-2 이후 측정: build 코드 증가 수치는 이 문서의 직접 측정값(약 4.7k → 17.1k)을 기준으로 한다(BUILD 에이전트는 6.3k → 17.0k로 셈, 포함 범위 차이).

검증 기록

항목 결과
방식 전부 읽기 전용(grep·git·스크립트). Gradle과 테스트는 실행하지 않음
직접 재확인 build-logic+build-tools 합계 16,768줄 일치; 09-17→09-24 증가 약 4.7k→17.1k; GWT 주석 완비 파일 0개; web·web-fileserver 둘 다 implementation spring-boot-starter-web(WebFlux 비활성 근거); application-core에 domain-core 의존 없음; 순수성 task가 application-*만 순회; persistence-mongo는 app-bootstrap runtimeOnly이고 다른 main 소스의 Mongo 타입 참조 없음
추정치 도달 불가 LOC, 약한 단언 수, 중복률은 이름 참조·regex 기반 추정. 리플렉션·문자열 bean 참조는 반영 안 됨

그룹별 상세

아래는 각 에이전트 결과 원문이다. BUILD → TEST → X1 → X2 → S1–S7 순서.

BUILD — 빌드 인프라가 목적에 비해 과한가

결론

  • 대부분 과하다. 목적("빌드 시점에 아키텍처 위반을 막는 것", 카테고리 A)은 build-logic+build-tools 16,768줄 중 2,242줄(13%). 꼭 필요한 registry·의존 방향·순수성 검사만 따지면 1,301줄(8%).
  • 가장 큰 덩어리는 기능(capability)별 증거 검사. jpa·notification·messaging·mongo 전용 검사(E) 7,760줄(46%), 테스트 레인 검증(C) 2,559줄, 릴리스·스냅샷류(D) 2,714줄.
  • 아키텍처 게이트 자체는 적정. Gradle 방향 게이트와 ArchUnit 규칙 105개는 필요한 크기. 문제는 그 주변의 증거 검사 플랫폼.
  • "gradle을 얇게" 리팩터에서 코드가 두 배. 09-17(ace8aaae) → 09-24(208077fd) 사이 included build 코드 6,276 → 17,010줄, 같은 기간 leaf·root 스크립트는 3,947 → 3,732줄(215줄 감소). 줄어든 스크립트 로직이 Java 플러그인으로 옮겨 가면서 두 배 이상 커짐.
  • 09-16 단계 분리 계획은 절반만 이행. 2단계(main)로 내려야 할 env 키·공개 경로 스냅샷·전체 system 테스트·API surface·기능 검사가 지금도 PR 게이트에서 돈다.

인벤토리

카테고리: A 아키텍처, B 품질 도구, C 테스트 레인·증거, D 릴리스·스냅샷, E 기능별, F 개발 편의. 단계: PR = 1단계(머지 차단), main = 2단계, tag = 3단계. ✗ = 계획(docs/superpowers/plans/2026-09-16-ci-stage-separation.md)과 현재 위치 불일치.

# 구성요소 LOC (main+test) 쓰는 곳 / 호출 경로 막는 것 카테고리 판정 단계 현재→목표
1 ca.architecture-registry, ca.optional-architecture-registry (ModuleRegistry, ModuleRegistrySettingsInstaller) 353+162 src/settings.gradle:13, optional-platforms/settings.gradle:6 registry 모듈만 include, 디렉터리 매핑, registry 형식 A KEEP 설정 단계 ✓
2 ca.architecture: verifyModuleDependencyDirection, verifyCleanArchitectureDependencies, verifyModuleDependencyPurity (+ResolvedComponents) 619+167 build.gradle:21, optional-platforms/build.gradle:2 → architectureCheck → ci HS5, application-* 프레임워크 순수성 A KEEP, 순수성 필터에 domain-core·shared-contract 추가 PR ✓
3 verifyNoIgnoredSourcePackages 128+0 architectureCheck Git 무시 패키지의 소스 A 인접 KEEP (1차 O-3 수정) PR→main
4 ca.runtime-membership 194+124 build.gradle:20, ArchitecturePlugin.java:216-225 조립 루트 런타임 모듈 ⊆ registry A DELETE (#2와 중복) PR→없음
5 ca.dependency-policy 400+95 app-bootstrap/build.gradle:376-390, notification/build.gradle:63, messaging/build.gradle:44 → check fileserver 미포함, yaml/jackson 부재 A/E REPLACE-WITH-NATIVE PR ✓
6 ArchUnit (app-bootstrap/src/architectureTest) 7,786 (규칙·지원 6,342 + fixture 1,444), 그 밖에 leaf ArchUnit 26파일 3,052 architectureTestLaneCheck → architectureCheck HS1-4 import 규칙 (@ArchTest 105, @Test 109) A KEEP PR ✓
7 ca.java-conventions (+verifyDependencyLocks, resolveAndLockAll) 206+0 모든 Java leaf toolchain, -Werror, STRICT lock, BOM B SIMPLIFY (quarantineTest 삭제, leaf 버전 고정) PR ✓
8 ca.quality-conventions (+qualityCheck, auxiliaryStyleCheck) 209+0 모든 Java leaf Spotless, Checkstyle, Error Prone, SpotBugs B KEEP PR ✓ (5분 넘으면 SpotBugs만 main)
9 ca.java-library, ca.spring-library, ca.spring-config, ca.platform-module, ca.grpc-platform-module 83+105 leaf 6/22/21/38/4 leaf 종류별 조합 B KEEP —
10 ca.test-jvm-agents 90+0 모든 Java leaf Mockito agent B SIMPLIFY → java-conventions 약 5줄 —
11 ca.auxiliary-source-set 151+145 15 leaf 추가 source set B REPLACE-WITH-NATIVE (jvm-test-suite, ADR-BUILD-001 선례) —
12 ca.strict-test-lane 573+424 모든 Java leaf, 선언 레인 47개, root 집계(build.gradle:109-130) 레인이 0개 실행·skip·필수 클래스 누락 시 실패 C KEEP, "필수 테스트 실행 + skip 금지"의 유일한 구현으로 SIMPLIFY 레인별
13 ca.strict-qualification 393+273 9 leaf, 13회 등록 #12와 같은 검사 3중(*RequiredClasses + listener + XML 재읽기) C MERGE → #12 PR/main
14 ca.evidence + JUnitEvidence + RequiredTestExecution 239+116 build.gradle:18, #15, graphql JUnit XML 기준 skip 금지 C MERGE 후 DELETE —
15 ca.conditional-transport-qualification 91+236 build.gradle:19, ci-quality-gates.yml:71 선택 transport 테스트 skip 금지 C/E MERGE → app-bootstrap 레인 1개 PR→main ✗
16 build-tools junit (JUnitEvidenceReader) 138+76 messaging, jpa XML 재읽기 C MERGE —
17 ca.api-surface (+ApiSurfacePolicy, JavaPublicTypes) 549+172 mongo·jpa·graphql check 공개 타입 목록 변경 D SIMPLIFY: 유일 구현으로, #27·jpa-adopter 흡수 PR→main ✗
18 ca.public-path-snapshot 288+37 (+#19와 공유 contract test 265) build.gradle:23, ci-quality-gates.yml:62, releaseCheck, notification-platform.yml:89 permitAll 경로 기준선 D (보안) SIMPLIFY → app-bootstrap approval test (approvaltests 이미 의존성, app-bootstrap/build.gradle:255) PR→main ✗
19 ca.archive-hygiene 216+46 build.gradle:22 → releaseCheck SHA가 붙은 오래된 jar D DELETE (leaf 버전 고정 시 원인 소멸; 이미지는 stageDockerJar rename 경유 app-bootstrap/build.gradle:306-311) tag→없음
20 ca.release-provenance 138+71 root, optional-platforms; 모든 leaf jar 버전(JavaConventionsPlugin.java:45-48) 버전·SHA 추적 D SIMPLIFY → app-bootstrap springBoot { buildInfo() } (런타임에서 Build-Revision 읽는 곳 0) tag ✓
21 ca.jmh-benchmarks 166+79 4 leaf, workflow 호출 0 — D REPLACE-WITH-NATIVE (me.champeau.jmh) 또는 DELETE 없음
22 ca.config-contract / verifyEnvKeys 476+211 configContractCheck → ci, notification-platform.yml:89 env-keys.yaml(5,869줄) ↔ 설정 바인딩 D SIMPLIFY → app-bootstrap JUnit (선례 OperationalErrorRegistryContractTest, build.gradle:103-106) PR→main ✗
23 ca.graphql-platform 188+0 graphqlStableTest(ci-quality-gates.yml:68), verifyGraphQlProductionJar(check) stable 레인, jar 내용 E SIMPLIFY: 레인은 #12로, jar 검사만 PR→main ✗ (레인)
24 ca.jpa-test-lanes 159+118 persistence-jpa PostgreSQL 레인 목록 E SIMPLIFY → leaf strictTestLanes main
25 ca.redis-topology-lane 242+133 cache-redis, redis-sdk-topology.yml topology 레인 + 자체 tracker E SIMPLIFY → #12 레인 PR(경로 필터) ✓
26 ca.jpa-evidence + ca.jpa-qualification 2,838+744 jpa check(build.gradle:184-185), ci-quality-gates.yml:188-207, jpa-release.yml, jpa-r2-evidence.yml readiness card, evidence manifest E 플랫폼 DELETE, registry 검사만 leaf 테스트로 PR→main/tag ✗
27 ca.notification-api-surface + ca.notification-evidence 851+250 build.gradle:24-25, notification check(:84-87) API 목록, evidence E MERGE(API → #17) / DELETE(evidence) PR→main ✗
28 ca.notification-configuration 222+140 build.gradle:26, notification check 설정 계약 E SIMPLIFY → leaf 테스트 PR→main ✗
29 ca.messaging-qualification + ca.messaging-certification 819+253 build.gradle:28, leaf 4, integration-main.yml:209, messaging-certification.yml:44 계약 evidence, 해시 E SIMPLIFY → leaf 테스트 main ✓ / PR(경로) ✓
30 ca.mongo-verification 544+223 mongo check(build.gradle:226-228) 레인 태그 분리, 자체 XML reader E DELETE/SIMPLIFY PR→main ✗
31 ca.developer-bootstrap + ca.bootrun-dotenv 320+184 build.gradle:29 (1차 O-1 Critical 원인), README.md:42 로컬 기동 순서 F SIMPLIFY (app-bootstrap에만 또는 scripts/) 없음
32 architectureCheck / verifyDependencyLocks — ci-quality-gates.yml:62 A, B A/B KEEP PR ✓
33 ci (build.gradle:138-147) — PR PR 게이트 — SIMPLIFY (#34-36 빼기) PR
34 qualificationCheck / systemTestCheck — ci 전체 앱 기동 테스트 C KEEP PR→main ✗
35 sampleWebContractCheck, configContractCheck — ci 실서버 sample, env 키 D KEEP PR→main ✗
36 quarantineTest (build.gradle:88) — ci-quality-gates.yml:212-216 @Tag("quarantine") 0개 C DELETE PR(참고)→없음
37 integrationCheck, releaseCheck — integration-main.yml, release.yml:60 컨테이너 레인 / 릴리스 C/D KEEP (releaseCheck는 ci를 다시 돌림) main ✓ / tag ✓
38 .github/workflows 18개 2,767 PR 1,358 · main 339 · tag 709 · 야간 298 · reusable 63 — 혼합 SIMPLIFY —

카테고리별 LOC

카테고리 build-logic build-tools 합계 비율
A 아키텍처 2,242 0 2,242 13.4%
B 품질 도구 989 0 989 5.9%
C 레인·증거 2,345 214 2,559 15.3%
D 릴리스·스냅샷 2,027 687 2,714 16.2%
E 기능별 840 6,920 7,760 46.3%
F 개발 편의 504 0 504 3.0%
합계 8,947 7,821 16,768

표 밖: leaf build.gradle 74개 3,531줄 = 의존성 857, plugins 295, 주석·빈 줄 1,400, 그 외 로직 979(그중 약 660줄이 레인 DSL: strictTestLanes 413, auxiliarySourceSets 122, strictQualification 약 125). leaf 파일 안의 아키텍처 검사 로직은 0줄. 요약: 목적(A)에 쓰이는 빌드 코드 약 1.3–2.2k줄, 나머지 14.5k줄은 다른 목적.

중복

  1. 의존 방향을 4번 검사. 컴파일러(registry에 없는 모듈은 classpath에 없어 import 실패) / verifyModuleDependencyDirection(73개 leaf 전부, 선언 edge와 컴파일 가시 edge) / verifyCompositionRuntimeMembership("미등록"이 될 수 있는 건 :sample-portfolio뿐 → 방향 게이트가 이미 차단) / ArchUnit adapter 패키지 규칙 약 7개(AdapterBoundaryArchitectureTest.java:76-392). 09-16 계획이 runtime-membership 삭제를 "runtimeClasspathManifest를 RuntimeMembershipClasspathAgreementTest가 읽는다"며 기각했으나 지금 두 이름 모두 grep 0 → 근거 소멸. ArchUnit 쪽 중복은 비용이 작고 modules.json이 느슨해져도 잡아내므로 유지.
  2. "필수 테스트 실행 + skip 금지" 구현 6개(1차 O-8의 5개 + MongoJUnitXml, RedisTopologyExecutionTracker): listener 방식 StrictLaneExecutionTracker, RejectSkippedTestsListener, RedisTopologyExecutionTracker; JUnit XML 파서 JUnitEvidence.java(128), JUnitEvidenceReader.java(114), MongoJUnitXml.java(79). #12가 이미 필수 클래스별 실행과 skip 금지를 모두 하므로(StrictTestLanePlugin.java 후반) #13·#14·#15·#16은 부분집합.
  3. API surface 검사 3개: ca.api-surface(javac 파싱), NotificationApiSurfaceVerifier(정규식), JpaAdopterApiSurfaceVerifier(import 정규식).
  4. fileserver 제외 규칙이 두 곳에서 모순: modules.json은 app-bootstrap → application-fileserver, adapter-outbound-fileserver 허용, dependencyPolicy는 같은 모듈을 absent로 금지. app-bootstrap 외에 fileserver edge를 허용받은 모듈 없음 → registry에서 두 항목을 빼면 방향 게이트가 전이 의존까지 차단.
  5. HS1은 빌드 단계에서 뚫려 있음. 순수성 task는 application-*만 검사(ArchitecturePlugin.java:147) → domain-core에 외부 의존성을 추가해도 빌드 통과(ArchUnit DOMAIN_IS_PURE는 실제 import한 경우만).
  6. CI가 아키텍처 게이트를 반복 실행: notification-platform.yml:84-85, fileserver-certification.yml:50, jpa-release.yml:123-125, releaseCheck는 ci 전체 재실행.
  7. 기능 전용 플러그인 5개가 root에(build.gradle:24-28) → :domain-core:check 한 번에도 notification·jpa·messaging 플러그인 설정 실행.
  8. ArchUnit이 모든 leaf를 보지 않음. 대상은 app-bootstrap architectureTest 런타임 classpath; websocket·grpc 어댑터는 conditionalTransportBuildContractTest 쪽에만(app-bootstrap/build.gradle:261-263), optional-platforms 18 leaf와 sample도 빠짐. 전 leaf를 보는 HS5 게이트는 Gradle 방향 task뿐.

2026-09-16 계획 이행 상태

  • Track A: 완료(커밋 기록 기준).
  • B1 공통화: 부분 — composite action은 널리 쓰임; _reusable-gradle.yml은 job 2개만 쓰고 그중 하나는 항상 실패(1차 O-2).
  • B2 release 1개로: 미완 — tag v* 트리거 workflow 3개(release.yml, jpa-release.yml, fileserver-certification.yml).
  • B3 PR은 변경 모듈만: 부분 — 경로 필터는 pr-adapters, notification, fileserver-pr, redis, messaging; ci-quality-gates는 PR마다 55개 leaf :ci 전체; object-storage-qualification은 경로 필터 없이 PR마다 MinIO 컨테이너.
  • B4 게이트 재배치: 미이행 — 표의 ✗ 11개가 여전히 PR.
  • B5 gate matrix: 방향 변경(매트릭스 파일 삭제, ci-quality-gates.yml:5-10).
  • B6 도달 불가 task: 잔존(jmh 4 leaf, 테스트 0개 quarantine).
  • Track C: 대부분 완료 — 이미지 build·push, CycloneDX SBOM, Trivy 스캔 있음, 서명 없음(cosign 0).

목표안 비교

안 build-logic+tools LOC leaf build workflows HS1 HS2/HS3 HS5 잃는 것 작업 규모 위험
O1 중복만 정리 약 12,500–13,000 약 3,450 약 2,700 ArchUnit + 컴파일러 registry + ArchUnit Gradle 게이트 없음 파일 약 25개 삭제, leaf 약 12개 낮음
O2 단계 재배치만 16,768 약 3,520 약 2,720 동일 동일 동일 없음(유지비 그대로) root 약 20줄, leaf 3, workflow 3 낮음
O3 아키텍처 코어 + 컨벤션만 build-logic, 기능 검사는 소유 leaf 테스트로 약 3,500–4,000 (build-tools 0) + leaf 테스트 +2,000–3,000 약 3,200 약 2,400 ArchUnit + 순수성 task(domain-core 포함) 동일 Gradle 게이트 빌드 산출물로서의 evidence manifest, 삭제 플러그인의 TestKit 파일 약 120개 삭제, 테스트 30–40개 신설, leaf 약 20, workflow 약 8 중간
O4 ArchUnit 중심 (Gradle 방향 task 제거) 약 2,000–2,500 약 3,200 약 2,400 동일 동일 ArchUnit만 선언만 된 edge, runtimeOnly edge, app-bootstrap classpath 밖 leaf 전부 중간 HS5 약화, 높음
O5 Gradle 기본 기능만 (Groovy 스크립트 플러그인, TestKit 없음) 약 800–1,200 약 3,200 약 2,400 동일 동일 약 100줄 Groovy 게이트 자체 테스트, configuration cache·parallel 안전성 재증명(ArchitecturePlugin.java:91-95) 큼(09-18 Groovy→Java 전환 되돌림) 높음

권고: O3 (순서: O2 → 바로 할 것 → O3)

  • 이유: 목적에 필요한 빌드 코드는 registry, 방향·순수성 task, 컨벤션, 레인 하나로 충분(HS1-4는 ArchUnit이 이미 담당). 이미 내려진 결정과 같은 방향(13-build-dependency-ci.md §0 "build-tools evidence/readiness/qualification 플랫폼은 축소", "특수 plugin은 opt-in", §0-A 기능 계약은 "owner module test가 소유"). 선례 두 개(ADR-BUILD-001, OperationalErrorRegistryContractTest).
  • 틀리면 반박되는 가정: (1) evidence manifest를 build-tools 밖에서 읽는 곳 없음(grep: build-tools, CI artifact 업로드 ci-quality-gates.yml:195-201, 문서뿐) — 감사·릴리스 소비자가 있으면 JPA manifest만 tag 단계에. (2) build-tools 로직 대부분 Gradle 무관(98파일 중 68파일, 3,416/5,888줄이 org.gradle 미import) → 테스트로 이전은 기계적. (3) 73개 leaf + 빌드 2개 전부를 보는 HS5 게이트는 Gradle 방향 task뿐. (4) leaf 테스트로 옮기는 검사는 읽는 파일을 inputs로 선언(안 하면 1차 O-4처럼 UP-TO-DATE 거짓 통과).
  • 가장 강한 반론: 09-16 기록상 감사가 삭제하자던 17건이 실행으로 반박됐고 "작동하게 만드는 데는 코드가 든다"; Gradle task는 @Disabled로 조용히 꺼질 수 없지만 테스트는 가능. 답: 옮긴 테스트는 rejectSkipped 레인에서; 소유자 원칙상 이 검사들은 어차피 2단계 항목.
  • 솔직한 평가: A 자체(TestKit 포함 약 1.3k줄)와 ArchUnit은 규모가 정당 — 줄일 대상 아님.

바로 할 것 (어느 안을 고르든 안전)

  1. ca.runtime-membership과 연결 코드 삭제(−318줄, 방향 게이트가 대신).
  2. quarantineTest 삭제: JavaConventionsPlugin.java:149-165, build.gradle:88-92, CI job(약 −30줄).
  3. redis-sdk job 삭제(1차 O-2, 약 −12줄).
  4. ca.strict-qualification 13건을 strictTestLanes의 requires + rejectSkipped로(−666줄); messaging evidence reader가 읽는 XML 경로만 레인 기본 경로로.
  5. ca.evidence 삭제, conditional-transport를 app-bootstrap 레인으로(−682줄).
  6. XML reader 통합: JUnitEvidenceReader, MongoJUnitXml(−293줄).
  7. API surface 구현 하나로(약 −550줄).
  8. dependency-policy를 Gradle 기본 기능으로(−495줄): fileserver는 app-bootstrap allowed_dependencies에서 두 항목 제거; yaml/jackson은 constraints { … version { rejectAll() } }(rejectAll이 모듈 유입 시 해석을 실패시키는지 leaf 1개로 먼저 확인 — 미검증).
  9. 순수성 task 필터에 domain-core·shared-contract 추가(+약 3줄) → HS1 빌드 단계 공백 해소.
  10. CI 아키텍처 게이트 중복 실행 제거(약 −10줄).
  11. ca.test-jvm-agents를 java-conventions에 합침(−80줄), jmh는 me.champeau.jmh 또는 삭제(−245줄).
  12. 단계만 옮기기(삭제 없음): ci에서 configContractCheck, qualificationCheck, sampleWebContractCheck 제거; ci-quality-gates.yml:62에서 :verifyPublicPathSnapshot 제거; graphqlStable·conditionalTransport, jpa-candidate job, configuration-cache job을 integration-main으로; notification·jpa·mongo·api-surface 검사를 leaf check에서 떼어 mainCheck로; build-logic·build-tools job에 경로 필터.

1–11 합계 약 3,400줄 감소, 잃는 보호 없음.

조사 범위

전체: root build·settings, build-logic build.gradle·README, ArchitecturePlugin과 task 3개, ModuleRegistry·installer, RuntimeMembership, Java·Quality·레인 컨벤션, StrictTestLanePlugin, StrictQualificationExtension, EvidenceExtension, ci-quality-gates.yml, 09-16 계획, 1차 Group O, 13-build §0. 훑음: build-tools(구조, task 등록, Gradle API 비중, API surface verifier 2개), 나머지 workflow(트리거·job·gradle 호출), leaf build(스크립트 분류 + 3개 정독), ArchUnit(규칙 이름 + 2개 파일). 추정: rejectAll 동작, 각 안의 LOC, PR 소요 시간. git 이력상 build-logic·build-tools는 60b6a319에서 새로 추가된 것으로만 보여 09-18 이전 구성요소별 도입 이유는 추적 불가.

TEST — 테스트 가독성과 구조

결론

given/when/then 흐름은 이미 상당 부분 보인다. 6줄 이상 테스트의 71%(5,313/7,463)는 빈 줄로 단계를 나누고, 이름은 8,743개 전부 camelCase 행동 문장이다. 필요한 일은 스타일 신규 도입이 아니라 지금 스타일을 규칙으로 적고 // given // when // then 주석을 명시하는 것이다(주석을 모두 갖춘 파일은 현재 0개).

가독성보다 급한 문제 두 가지:

  • fake가 실제 adapter와 같은 계약 테스트를 통과하지 않는다. 1차 리뷰의 "fake가 결함을 숨긴 6건" 중 5건은 공유 contract 테스트나 실제 구현을 거치는 테스트가 있었으면 잡혔을 것으로 판단. 나머지 tus 1건은 "테스트 하나에 행동 하나" 규칙으로 잡혔을 것.
  • 이름이 약속한 것을 단언하지 않는 테스트가 많다. 존재·타입·예외 없음만 확인하는 테스트 약 1,050개(12%).

adopter가 복사하는 sample-portfolio가 가장 약하다(DisplayName 0%, 단계 분리 54%, 115줄 테스트 1개) → migration은 sample부터. 8,764개 전체 재작성은 권하지 않는다.

계층별 평가

blank% = 6줄 이상 테스트 중 빈 줄로 단계를 나눈 비율, DN% = @DisplayName 메서드 비율, weak% = 존재·타입·no-throw 단언만 있는 비율.

계층 / 모듈 그룹 샘플 파일 GWT가 보이나? 이름 단언 품질 주요 문제
domain (domain-core 2 + sample domain) DomainCoreContractTest, WorkLogTest, PosterTest 짧아서 대체로 보임, WorkLogTest는 빈 줄 없음 camelCase, DN 0% 값과 reason 코드까지 WorkLogTest.java:35 NPE 타입만; WorkLogTest.java:65, PosterTest.java:46 한 테스트에 행동 2개. 좋은 예 PosterTest.java:73
shared-contract (242) TraceParentTest, OperationalErrorTest 대부분 한 줄(blank 27%) DN 2% 구체적 값 표 형태인데 파라미터화 안 됨(30개·32개가 거의 같음)
application-* (667) SubmitDurableOperationUseCaseTest, CacheAsideExecutorTest, DispatchOutcomeRecorderTest 좋음(78%) 영어 문장, DN 14% weak 16% fake 중복(TransactionPort 15개), DispatchOutcomeRecorderTest.java:169 no-op fake. 좋은 예 SubmitDurableOperationUseCaseTest.java:92
persistence (1,497) OutboxStoreAdapterTest, DurableOperationStoreContractTest, PostgreSqlWorkClaimContractTest, MongoChangeStreamRunnerTest, sample WorkLogRepositoryAdapter(Integration)Test 좋음(81%) DN 52% weak 15%, 필드 10개 한 줄씩 단언 "contract" 테스트가 adapter가 아니라 raw SQL 검증; OutboxStoreAdapterTest.java:140 행동 5개. 좋은 예 MongoChangeStreamRunnerTest.java:28
outbound 기타 (1,804) RedisHashOperationsContractTest, LiveRedisGuardrailTest, RoutingNotifierTest, FailOpenDependencyLoggerTest, DefaultGenericHttpGatewayTest, LocalPersistentControlPlaneTest 74% DN 33% weak 12%, 30줄 넘는 테스트 143개 Redis *ContractTest 16클래스(160 tests)가 in-memory에서만; PII 부재 단언이 항상 통과
inbound (2,139) TusProtocolContractTest, NotificationCallbackMvcControllerTest, RateLimitKeyResolverTest, GlobalExceptionHandlerTest, GraphQlMutationIdempotencyContextTest, HandshakeAdmissionPipelineTest 65% DN 47% weak 11%, envelope 필드 줄마다 단언 수락+거부를 한 테스트에(#11을 숨김), 컨트롤러 직접 호출로 HTTP 경로 우회. 좋은 예 HandshakeAdmissionPipelineTest.java:103
grpc:* (588) GrpcIdempotencyInterceptorTest, GrpcOperationLedgerRepositoryTest, InMemoryOperationLedger 68% DN 98% weak 3%, 최고 fake가 FAILED→COMMITTED 허용(#15), 공유 ledger contract 없음
messaging:* (829) MessagingAdapterContract, InMemoryHarnessContractTest, OutboxRelayTest 80% DN 18% weak 15%(대부분 validator 예외 타입) 공유 contract 모범 사례가 이미 있음. 단 relay 테스트 fake가 인코딩을 안 해 #7을 숨김. 좋은 예 OutboxRelayTest.java:46
bootstrap (757) ArchitectureViolationFixtureTest, CapabilityDependencyValidatorTest, TracingActivationContextTest, MetricsContractConfigTest 57% DN 26% weak 6% 복붙 테스트 55개, assertThat(context).isNotNull()
sample-portfolio (218) 파일 9개 54% DN 0% weak 11% 115줄 테스트, 동작이 다른 FakeRepo 2개, 인자 7개 생성자 호출 7번 반복, TransactionPort fake 10개

Findings (영향 큰 순)

  1. [Required] fake가 실제 adapter와 같은 계약으로 묶여 있지 않다. 일부 fake는 Javadoc에 "adapter와 같은 의미"라고 적었지만(InMemoryDurableOperationStore.java:12-19, InMemoryOperationLedger.java:15-19) 확인하는 테스트가 없다. 반대 계약 검증도 있다: GrpcOperationLedgerRepositoryTest.java:191은 JPA 쪽에서 "FAILED는 종료 상태"를 검증, fake는 그 상태에서 COMMITTED 허용. DurableOperationStoreContractTest.java:183은 adapter를 거치지 않고 raw SQL로 충돌만 확인(예외 타입만).

  2. [Required] 이름이 약속한 성질을 단언하지 않는다.

    • PostgreSqlWorkClaimContractTest.java:78 claimsAreDeterministicallyOrdered: 순서는 안 보고 isNotEmpty()만.
    • WorkLogUseCasesTest.java:281 batchCreatePersistsEveryItemAtomically: 트랜잭션 fake가 그냥 통과시켜 원자성 증명 불가, 개수 2개만.
    • RoutingNotifierTest.java:174: 예외 메시지가 "provider-failure"라 원래 PII가 없어 doesNotContain("secret@gmail.com")은 절대 실패 안 함(FailOpenDependencyLoggerTest.java:71 동일).
    • NotificationCallbackMvcControllerTest.java:118 "…BeforeIngress": 미리 만든 byte[]를 컨트롤러에 직접 넘겨 converter 경로 우회.
    • MetricsContractConfigTest.java:57: SLO 버킷 대신 isNotEmpty().
    • SampleApplicationContextTest.java:45, TracingActivationContextTest.java:79: assertThat(context).isNotNull().
    • 규모 추정: presence만 133, 예외 타입만 672, no-throw만 123, 섞임 124 → 약 1,050개(12%). 단언 없는 93개는 대부분 ArchUnit .check()라 정상. presence만 7개를 직접 봤더니 5개는 실제로 약함. 예외 타입만은 대부분 validator 테스트라 "틀린 이유로도 통과"(예: WorkLogTest.java:35는 어느 인자가 null이어도 NPE).
  3. [Required] 한 테스트에 행동이 여러 개. 약 646개(7.4%): 예외 단언 블록 2개 이상 484개 ∪ 단언 뒤 다시 행동 181개. 결함을 숨긴 사례: TusProtocolContractTest.java:149는 수락과 거부를 한 테스트에 묶고 chunk 2에는 틀린 checksum만 보내 누적 digest 버그(1차 C-1)가 안 보임. 규칙 "// when은 정확히 하나"로 GWT 요청과 이 문제가 같이 풀림.

  4. [Required] 복사 원본인 sample이 가장 약하다. PosterImagePublicationWorkflowTest.java:73: 115줄, mock 3개, thenAnswer 안에서 assert, inline FQCN, 인자 16개 생성자, 행동 4개. FakeRepo 두 벌이 다르게 동작: WorkLogUseCasesTest.java:45는 upsert + 필터, CreateWorkLogOutboxTest.java:48은 append + findPage 빈 결과; 둘 다 실제 adapter와 달리 정렬 무시(WorkLogRepositoryAdapter.java:71-74). WorkLogRepositoryAdapterTest.java:70 "maps to entity and back": id만 확인.

  5. [Consider] fake 중복. 테스트 구현 3개 이상인 포트 42개, 구현 합계 198개(lambda fake 미포함 → 하한). TransactionPort 26개/25파일/4모듈(application-notification은 공유 PlatformFakes.java:54가 있는데도 10개 파일이 따로), MessagePublisher 15, ObjectControlStore 7(한 모듈 안, 이름만 다른 InMemory/Map/Recording/Noop), RedisRuntimeClient 7(BrokenClient 4), Clock 직접 상속한 가변 시계 10.

  6. [Consider] 표 형태 테스트가 파라미터화 안 됨. @ParameterizedTest는 45개 파일뿐. 대상: TraceParentTest(30), OperationalErrorTest(32), ArchitectureViolationFixtureTest(55), OutboxStoreAdapterTest.java:140.

  7. [Consider] 예외 단언이 when과 then을 한 식에 묶음. assertThatThrownBy 계열 2,400개(27%), catchThrowable 26개. 캐스팅 관용구 extracting(ex -> ((X) ex).reason()) 9개 파일 18줄.

  8. [Consider] 내부 구현을 직접 다루는 테스트 약 170개(2%, 상한). reflection 42, 컨트롤러 직접 호출 9, verify만 있는 테스트 31, 타입 모양 확인 89(architectureTest lane 밖).

  9. [Nit] assertThat(x.contains(y)).isTrue() 14개 파일 29줄; DisplayName 3,430개 영어, 한국어 1개(MetricsAlertingContractTest.java:205), 상당수는 메서드 이름을 띄어 쓴 것뿐.

Fakes와 contract 테스트

port fakes (개수, 위치) 실제 adapter 공유 contract? 발견된 차이
DurableOperationStorePort 2 — application-core/.../InMemoryDurableOperationStore.java, web testFixtures TestDurableOperationStore.java DurableOperationStoreAdapter 없음, PG 테스트는 raw SQL 1차 #4 재제출 25P02, fake는 통과
GrpcOperationLedger 1 — grpc-policy/.../InMemoryOperationLedger.java JpaGrpcOperationLedger 없음 1차 #15 FAILED→COMMITTED
RedisCommandGateway 1 (2.4k줄) — InMemoryRedisCommandGateway LettuceRedisCommandGateway 부분적: LiveRedisOperationsFixture는 있으나 contract 16클래스(160 tests)가 new RedisOperationsFixture()에 고정, live는 20 tests HDEL/PEXPIRE 미재현
UploadApplicationService (tus) 1 — InMemoryUploadApplicationService.java:117 DefaultUploadApplicationService 없음 fake가 버그와 같은 누적 digest. contract만으로 부족, chunk 2 정상 케이스 필요
DeliveryProjectionStorePort 3 — DispatchOutcomeRecorderTest.java:169(no-op), NotificationPlatformNoops, ProviderEventLateMatchTest.java:211 JpaDeliveryAttemptStore 없음 projection 덮어쓰기(1차 B-5)
MessagePublisher 15 / 10파일 DefaultMessagePublisher 없음, relay는 RecordingOutboxPublisher(OutboxRelayTest.java:416) 1차 #7 재인코딩 실패
WorkLogRepository (sample) 2, 서로 다른 동작 WorkLogRepositoryAdapter 없음 정렬 무시, save 의미 불일치
IdempotencyStorePort 4 (app-core, web ×2, sample) IdempotencyStoreAdapter, RedisIdempotencyStoreAdapter 없음 미평가
ObjectControlStore 7 (objectstorage 한 모듈) LocalDevObjectControlStore, S3ConditionalObjectControlStore 없음 미평가

권장 패턴: 저장소 안에 이미 있는 MessagingAdapterContract(messaging-testkit/.../MessagingAdapterContract.java:19, 사용처 InMemoryHarnessContractTest.java:14)를 표준으로.

포트 소유 모듈의 testFixtures:
  abstract class XxxContract { protected abstract Xxx subject(); @Test ... }
fake 쪽 unit lane:        InMemoryXxxContractTest → @Nested class Contract extends XxxContract
adapter 쪽 PG/live lane:  JpaXxxContractTest      → 같은 @Nested 구조

static kit 방식(LegacyOutboxAppendContract)은 쓰지 않는다 — 새 검증을 추가해도 사용하는 쪽이 호출하기 전까지 어디서도 실행되지 않음. 추상 클래스 방식은 케이스를 추가하는 순간 모든 구현에서 돈다. application-core/src/testFixtures는 이미 있지만 지금은 persistence-jpa PG lane만 소비(persistence-jpa/build.gradle:88) → 다른 모듈은 testImplementation(testFixtures(project(':application-core'))) 추가. Object Mother는 이미 쓰는 OutboxFixtures.pending(), ContractMessage.orderCreated() 형태가 기본; builder는 인자 6개 이상이고 테스트마다 필드 2개 이상 바꿀 때만(CreateWorkLogCommand 9, PublishPosterImageCommand 10, UpdateWorkLogCommand 6).

제안 컨벤션 (새로 쓰거나 고치는 테스트에만)

  1. 이름: lowerCamelCase 행동 문장 <상황/주체><결과>(지금 방식 유지; test/should 접두어·snake_case 도입 안 함). 이름에 적은 성질은 반드시 단언한다.
  2. @DisplayName: 선택. 메서드 이름으로 못 쓰는 내용(숫자, 기호, "왜")이 있을 때만. 언어는 저장소 단위로 하나 — 기본 영어(현재 3,430개). 한국어 전환은 소유자 결정, 바꾸더라도 새 테스트부터. (반론: 한국어 팀은 IDE 리포트에서 한국어가 잘 읽힘 — 파일마다 섞이는 비용이 더 큼.)
  3. GWT 주석: 본문 statement 3개 이상이면 // given // when // then 필수 + 구역 사이 빈 줄. 준비할 게 없으면 // given 생략. 한 줄 테스트(순수 함수 입력 → 단언 1개)와 ArchUnit .check()는 주석 없이. // when은 정확히 하나 — 두 번 필요하면 테스트를 둘로. 예외 테스트는 catchThrowable로 when 분리; 기존 assertThatThrownBy는 손댈 때 // when & then 표시까지 허용.
  4. @Nested: 테스트 10개 이상이고 대상 연산 2개 이상인 클래스에서만, 연산 단위 한 단계. contract 테스트에도 사용.
  5. 단언: then은 when의 결과 하나에 대해서만. 여러 필드는 usingRecursiveComparison().isEqualTo(expected) 또는 extracting(..).containsExactly(..). isNotNull/isNotEmpty/isPresent/doesNotThrowAnyException만으로 끝내지 않음(이름이 "예외 없음" 자체를 말할 때만 예외). 예외는 타입 + reason/message(isInstanceOfSatisfying). assertThat(x).contains(y) 형태. 표 형태 입력은 @ParameterizedTest.
  6. fake vs mock: 포트는 hand-rolled fake, 포트당 하나, 포트 소유 모듈 testFixtures에. adapter가 있는 포트면 fake와 adapter가 같은 XxxContract 통과. Mockito는 프레임워크 경계(Spring Data repo, SDK client)와 장애 주입에만, thenAnswer 안에서 assert 금지. no-op fake는 결과를 단언하지 않는 협력자에만.

Before — src/sample-portfolio/src/test/java/dev/caskeleton/sample/portfolio/application/worklog/WorkLogUseCasesTest.java:232-264

  @Test
  void updateRejectsRevertingStatusToOpen() {
    FakeRepo repo = new FakeRepo();
    WorkLog created =
        new CreateWorkLogUseCase(
                repo, IDS, STUB_EVENT_IDS, NO_OP_OUTBOX, NO_CORRELATION, UTC_CLOCK, TX)
            .handle(createCmd("status revert"));
    WorkLog inProgress =
        new UpdateWorkLogUseCase(repo, TX)
            .handle(
                new UpdateWorkLogCommand(
                    created.id(),
                    Patch.absent(),
                    Patch.absent(),
                    Patch.absent(),
                    Patch.absent(),
                    Patch.of(WorkLogStatus.IN_PROGRESS)));

    assertThatThrownBy(
            () ->
                new UpdateWorkLogUseCase(repo, TX)
                    .handle(
                        new UpdateWorkLogCommand(
                            inProgress.id(),
                            Patch.absent(),
                            Patch.absent(),
                            Patch.absent(),
                            Patch.absent(),
                            Patch.of(WorkLogStatus.OPEN))))
        .isInstanceOf(WorkLogInvariantException.class)
        .extracting(ex -> ((WorkLogInvariantException) ex).reason())
        .isEqualTo(WorkLogInvariantException.Reason.INVALID_STATUS_TRANSITION);
  }

After — 같은 동작 검증(필드는 JUnit 기본 수명이라 테스트마다 새 인스턴스)

  private final FakeRepo repo = new FakeRepo(); // sample testFixtures 공유 fake로 이동 예정
  private final CreateWorkLogUseCase create =
      new CreateWorkLogUseCase(repo, IDS, STUB_EVENT_IDS, NO_OP_OUTBOX, NO_CORRELATION, UTC_CLOCK, TX);
  private final UpdateWorkLogUseCase update = new UpdateWorkLogUseCase(repo, TX);

  @Nested
  class Update {

    @Test
    void rejectsMovingAnInProgressWorkLogBackToOpen() {
      // given
      WorkLog inProgress = update.handle(statusChange(aCreatedWorkLog().id(), IN_PROGRESS));

      // when
      Throwable thrown = catchThrowable(() -> update.handle(statusChange(inProgress.id(), OPEN)));

      // then
      assertThat(thrown)
          .isInstanceOfSatisfying(
              WorkLogInvariantException.class,
              e -> assertThat(e.reason()).isEqualTo(Reason.INVALID_STATUS_TRANSITION));
    }
  }

  private WorkLog aCreatedWorkLog() {
    return create.handle(createCmd("any title"));
  }

  private static UpdateWorkLogCommand statusChange(WorkLogId id, WorkLogStatus status) {
    return new UpdateWorkLogCommand(
        id, Patch.absent(), Patch.absent(), Patch.absent(), Patch.absent(), Patch.of(status));
  }

Migration과 enforcement 계획

  1. 규칙 문서화 (PR 1개). 위 6개 규칙을 canonical AGENTS.md "테스트 전략"에 약 25줄, CLAUDE.md Testing에는 포인터 한 줄. 이후 적용 범위는 새로 쓰거나 고친 테스트.
  2. sample-portfolio 전체 (62 files / 218 tests). WorkLogRepositoryContract를 만들어 fake와 WorkLogRepositoryAdapter(integrationTest lane) 양쪽에서; TransactionPort fake 하나로; PosterImagePublicationWorkflowTest 행동별 분리.
  3. divergence가 확인된 6개 포트의 contract를 1차 Wave 1 수정과 같은 PR에서. contract가 현재 코드에서 먼저 실패하면 그 자체가 회귀 테스트. Redis는 contract 16클래스를 fixture 타입으로 추상화하고 live lane subclass 추가. 공용 RecordingTransactionPort는 application-core testFixtures.
  4. 계층별 모범 모듈 하나씩(수정 때문에 어차피 손대는 곳): application-core operation/idempotency, persistence-jpa operation/outbox, web error, cache-redis sdk/lettuce/operations.
  5. 약한 단언 정리(목록, 게이트 아님). presence만 133 + no-throw만 123은 모듈별로; 예외 타입만 672는 이름이 reason을 약속하는 경우만; 나머지는 손댈 때(boy-scout).

Enforcement 판단

  • GWT 주석 게이트는 만들지 않는다: 주석은 bytecode에 없어 ArchUnit이 못 봄; Checkstyle로 "statement 3개 이상 메서드"만 골라 검사하기 어려움; 이 저장소는 텍스트 파서 게이트를 이미 지웠음(verifyDocumentedLeafCount 삭제); // when이 있다고 행동 하나가 증명되지도 않음.
  • Consider: Checkstyle MethodLength(max 50)를 test에 — 설정 파일을 main/test가 공유(QualityConventionsPlugin.java:60), 현재 50줄 초과 테스트 68개를 baseline 억제 필요, integrationTest/systemTest lane은 Checkstyle 대상 아님 → 비용 작지만 효과 중간 이하, 지금은 보류 권고.
  • 실질적 강제 수단은 구조: fake와 adapter가 같은 추상 contract를 상속하면 한쪽만 약해지는 일이 없다.

Coverage note

범위: 등록 leaf 73개의 main·testFixtures 제외 모든 source set; @Test/... 파일 1,483, 메서드 8,743(호출 측 1,500/8,764와 차이는 regex 차이). 스크립트: scratchpad {stats,methods,weak2,fakes,tgrep}.py. 약 40개 파일을 메서드 단위로 읽고 약한 단언 분류 14개는 본문 직접 판정. 한계: 분류는 AST 아닌 regex 추정; lambda fake 미포함; graphql·websocket systemTest 깊게 안 읽음; "5/6건을 잡았을 것"은 판단(tus·notification 건은 누락 케이스 추가 가정); 단언 강도를 정확히 재려면 한두 모듈에 PIT mutation 테스트.

X1 — 모듈 간 기능 중복

기능 지도 (현재 → 권고)

기능 현재 구현 공유 계약? 갈라짐? 권고 크기
Outbox 저장 모델 3개(outbox_event, *_v2 테이블 5개, messaging_outbox), append 포트 4개, claim SQL 4개, relay 3개(+Debezium CDC), retry 정책 3개, 정리 작업 2개. 기본 조립은 v1만 app-core에 세대 3개 공존, messaging은 별도 예 앱 쪽 1개(v1 테이블 + fencing claim), V2 삭제; messaging outbox는 유지 L
요청 멱등성 계약 2개(v1/V2), store 3개, executor 조립 위치 3곳, inbound 전용 ledger 3개(websocket SPI, graphql context, grpc ledger) app-core v1+V2 예 V2를 정본, v1 삭제, 조립 1곳, inbound는 V2 사용 M
자연키 생성-또는-반환 durable operation(예외 catch), notification request(ON CONFLICT), 미사용 upsert executor 없음 예 (Critical #4) durable operation을 notification 방식으로, upsert executor 삭제 S
Inbox / 소비자 dedup app-core inbox(소비자 0), messaging inbox(미조립), mongo 변경 dedup, notification provider ledger 포트 2개 복붙 흔적 33% app-core inbox 삭제, 나머지 유지 M
lock / lease / fencing app-core 포트 4개(lock, lease, cache refresh, operation lease), row lease 약 9개, 범용 claim executor(참조 0) owner·attempt record 중복 예 미사용분 삭제, fencing은 contract kit로 검증 M
caller 트랜잭션 guard 9벌 복사 없음 예 (E-3) persistence-jpa 안 helper 1개 S
Backoff 계산식 10개 없음 "full jitter" 뜻 3가지 앱 쪽 5곳에 shared-contract Backoff S
Rate limit shared-contract 포트 + Redis 구현(조립됨), web 전용 병렬 타입 세트(구현체 0) 있음 예 (FAIL_OPEN 허용 여부) web 병렬 타입 삭제 S
Admission / in-flight 약 11개 없음 예 (gRPC M1 수정이 1곳만) 유지, Semaphore 사용 S
Kafka producer 2개(legacy seam, platform) messaging bridge 둘 다 TLS/SASL 없음 outbox 정리에 포함 M
파일 control plane / canonical JSON 직접 짠 JSON parser 3개, 파일 CAS store 3개, FilePublicationPort 소비자 0 없음 예 결정 필요(삭제 권고) L
readiness / evidence / API-surface / moduleboundary 카드 스키마 3개, 검증기 3개, family별 evidence plugin 5개, API-surface gate 3개, moduleboundary 3벌(main 1.7k줄) build-logic에 범용 plugin 있음 예 build-logic으로 통합 L
테스트 fake / contract kit TransactionPort fake 21개 등; 실제 adapter에 도는 kit는 1개 ADR-BUILD-001 (testFixtures) first-pass fake 결함 6건 포트별 kit를 testFixtures에 M

발견 (효과 큰 순)

1. [Required] Outbox: 세대 3개 공존, 실제 조립된 v1이 가장 약함

  • 구현: 조립(v1) LegacyOutboxAppendPort → OutboxStoreAdapter → PostgreSqlOutboxClaimRepository/H2OutboxClaimRepository → PublishPendingOutboxEventsUseCase + OutboxRelayScheduler → OutboxReaper (ca-skeleton.outbox.enabled=true일 때만). canonical 추가분 OutboxAppendPort → CanonicalOutboxAppendAdapter(같은 outbox_event). V2(미조립) OutboxAppendPortV2, OutboxPollingDeliveryPortV2, PostgreSqlImmutableOutboxAppendAdapter(376), PostgreSqlPollingDeliveryAdapter(549), PublishNextOutboxDeliveryUseCase, OutboxV2RetryPolicy, migration jpa/outbox-storage, jpa/outbox-polling. messaging JdbcOutboxRepository(721), OutboxRelay, OutboxRelayWorker, OutboxRetryScheduler, OutboxCleanupJob, messaging_outbox.
  • 조립 상태: V2 adapter는 stereotype 없음(PostgreSqlPollingDeliveryAdapter.java:29-43), main 참조 0, migration location 미설정(grep outbox-storage|outbox-polling → 테스트만). messaging relay는 @ConditionalOnBean(OutboxRepository)(MessagingReliabilityAutoConfiguration.java:81)인데 앱에 bean 없음; app-bootstrap·adapter main의 messaging.reliability import 0. "새 코드는 이것을 쓰라"는 OutboxAppendPort(LegacyOutboxAppendPort.java:6) 소비자 0, 소비자 7곳 모두 LegacyOutboxAppendPort.
  • 갈라진 증거: v1은 fencing 없음 — claim이 IN_FLIGHT 행 재획득(PostgreSqlOutboxClaimRepository.java:15-29), markPublished/markFailed가 eventId만으로 씀(OutboxStoreAdapter.java:93,106), claim·발행·결과 기록이 별도 트랜잭션(PublishPendingOutboxEventsUseCase.java:91,142,160). messaging V1002__messaging_outbox_lease_fencing.sql:1-14 주석이 바로 이 시나리오("A 멈춤 → B 재claim·발행 → A가 FAILED로 덮어씀 → 중복 발행")를 버그로 설명하고 lease_owner/lease_token으로 고침; V2도 owner CAS로 고침. 고친 두 구현은 미조립, 조립된 v1은 미수정. 추가: CanonicalOutboxAppendAdapter만 트랜잭션 guard 없음(1차 E-3); canonical 이벤트가 v1 claim을 타며 aggregate 순서 깨짐(1차 E-5); OutboxBackoffPolicy·OutboxV2RetryPolicy 역할 중복(1차 A-3); legacy producer(KafkaSenderAutoConfiguration.java:61-81)도 TLS/SASL 없음(Critical #8과 같은 문제).
  • 권고: 앱 outbox 1벌 — 저장소는 소비자와 V13/V14 canonical 컬럼이 있는 outbox_event; claim에 V2/V1002의 owner+token CAS 이식 후 V2(app-core outbox/v2 약 800줄, persistence-jpa 1,055줄, migration 2종) 삭제; append 포트는 OutboxAppendPort 하나(legacy는 cutover 후 삭제). 계약 위치 application-core outbox, contract kit는 기존 application-core/src/testFixtures/.../LegacyOutboxAppendContract 확장 + fencing 시나리오. messaging outbox는 vendored라 유지하되 src/messaging/CLAUDE.md에 "앱은 messaging_outbox를 쓰지 않는다" 명시.
  • adopter가 몰라도 되는 것: 어느 append 포트/테이블이 정본인지, 어느 relay가 도는지.
  • 가정/반론: V2 cutover 설계(2026-09-18-outbox-v2-* spec)를 계속 추진할 계획 없음 / V2가 더 안전 → 그렇다면 V2를 조립하고 v1 삭제. 어느 쪽이든 목표는 1벌. 승인자: 소유자.

2. [Required] 멱등성: 계약 2개, store 3개, 조립 3곳, inbound 전용 ledger 3개

  • 구현: v1 IdempotencyStorePort/IdempotencyExecutor/IdempotencyStoreAdapter(+H2·PG claim repo); V2 IdempotencyStorePortV2/IdempotencyExecutorV2, PostgreSqlOwnerSafeIdempotencyStore(662), RedisIdempotencyStoreAdapter(534) — v1과 같은 idempotency_record 테이블을 상태 어휘만 바꿔 사용(jpa/idempotency/V1__expand_owner_safe_v2.sql:107). inbound 전용: websocket CommittedResultLedger(inbound가 정의한 저장 SPI, main 구현 0), graphql GraphQlMutationIdempotencyInterceptor(요청 경로 밖), grpc GrpcOperationLedger + JpaGrpcOperationLedger(optional build, 별도 테이블).
  • 소비자: v1 executor는 sample PublishPosterImageUseCase.java:121만; IdempotencyExecutorV2는 조립 클래스(RedisIdempotencyConfig, PostgreSqlIdempotencyProviderConfig, IdempotencyProviderSelectionConfig) 외 호출자 0.
  • 갈라진 증거: V2 executor 두 곳에서 다르게 조립 — Redis는 getProcessingLease() 읽음(RedisIdempotencyConfig.java:71-73), PostgreSQL은 Duration.ofMinutes(2)·"json.v1" 하드코딩(PostgreSqlIdempotencyProviderConfig.java:36,39). v1 완료 기록 실패 시 action 재실행 결함(1차 A-8). 자연키 dedup 두 방식: JpaNotificationRequestStore.java:47-77 ON CONFLICT DO NOTHING 후 승자 읽기(주석에 25P02 이유) vs DurableOperationStoreAdapter.java:60 catch 후 같은 트랜잭션 재조회(Critical #4); 범용 RegisteredPostgreSqlUpsertExecutor 참조 0.
  • 권고: V2를 정본으로 하고 이름에서 v2 제거(application-core idempotency); sample을 V2로 옮기고 v1 전부 삭제; executor는 IdempotencyProviderSelectionConfig 한 곳에서 IdempotencySettings로, provider는 store bean만; websocket CommittedResultLedger 삭제(inbound가 저장 SPI를 갖는 건 방향이 틀림); graphql은 V2에 연결하거나 idempotencyKey allowlist 제거; DurableOperationStoreAdapter는 notification 방식으로, upsert executor 삭제; grpc ledger는 유지(vendored, ADR-GRPC-004).
  • 반론: v1이 더 단순 — 하지만 Redis는 V2만 구현하고 소유자 fencing은 V2에만 있음.

3. [Required] 테스트 fake: 같은 포트를 모듈마다 따로 흉내, 실제 adapter와 대조하는 kit 거의 없음

  • 구현(테스트 source set): TransactionPort fake 21개(application-notification 11, sample 6, app-core 4), ObjectControlStore fake 7개(한 leaf 안), IdempotencyStorePort 4 + V2 3, DurableOperationStorePort 2(app-core InMemoryDurableOperationStore, web testFixtures/TestDurableOperationStore), OutboxRepository 3, InboxRepository 2.
  • 갈라진 증거: 1차 공통 패턴 4(grpc ledger fake, tus fake digest, Redis fake HDEL/PEXPIRE, notification recorder, durable operation, messaging fake publisher); PG contract test가 adapter를 거치지 않고 raw SQL만 실행; app-core DistributedLockPortContractTest.java:46은 테스트 안에 정의한 FakeDistributedLockPort를 검증(fake를 테스트); 실제 adapter에 도는 kit는 LegacyOutboxAppendContract 하나뿐.
  • 권고: 포트 소유 leaf의 src/testFixtures(ADR-BUILD-001)에 포트별 contract kit를 두고 fake와 실제 adapter 양쪽에서 실행. 우선순위: DurableOperationStorePort, IdempotencyStorePortV2, GrpcOperationLedger(grpc-testkit), RecipientLeaseStorePort, tus upload, Redis gateway. DirectTransactionPort는 application-core testFixtures에 1개. ObjectControlStore fake는 @TempDir 위 LocalDevObjectControlStore로 대체.
  • 반론: 실DB lane이 느림 — kit는 fake에서도 돌아 최소한 fake 의미 = 실제 adapter 의미를 보장.

4. [Required] caller 트랜잭션 guard 9벌 복사, 빠진 곳에서 결함

  • 구현: persistence-jpa 7곳(OutboxStoreAdapter:130, DurableOperationStoreAdapter:178, JpaLiveEventReplayAdapter:163, PostgreSqlImmutableOutboxAppendAdapter:337, PostgreSqlSameStoreInboxAdapter:502, PostgreSqlPollingDeliveryAdapter:488, IdempotencyCapabilityGuard:93), messaging 2곳(JdbcOutboxRepository:229, JdbcInboxRepository:102).
  • 갈라짐: CanonicalOutboxAppendAdapter 0건(E-3, 조용한 dual-write); notification JPA store 11개도 0건.
  • 권고: persistence-jpa transaction 패키지 CallerTransaction.require(op) 하나(messaging은 vendored라 자기 것 유지). @Transactional(MANDATORY)는 V2 adapter가 bean이 아니라 proxy가 안 붙어 불가. Size S.

5. [Required] Rate limit: 공유 계약이 있는데 web에 같은 이름의 병렬 세트

  • 조립된 경로 RateLimitInterceptor → dev.caskeleton.shared.ratelimit.EdgeRateLimitPort → RedisEdgeRateLimitAdapter(이 저장소에서 공유 계약을 올바르게 만든 유일한 사례). 병렬 세트 web ratelimit/WebRateLimiter, RateLimitDecision, RateLimitFailurePolicy — WebMvcThrottleFilter:10-11,41, WebFluxThrottleFilter:10-11,44가 쓰고 main 구현 0(testFixtures CountingRateLimiter뿐).
  • 갈라짐: web enum은 FAIL_OPEN 허용, shared enum은 FAIL_CLOSED만; 단순 클래스 이름이 같아 import 오선택 쉬움.
  • 권고: web 병렬 타입·throttle filter 삭제 또는 EdgeRateLimitPort로 재연결(1차 I-8과 같은 결정). Size S.

6. [Required] lock / lease / claim: 소비자가 있는 포트와 구현체가 있는 포트가 어긋남

  • app-core: DistributedLockPort(JDBC 구현, 비즈니스 소비자 0); DistributedLeasePort + LeaseWatchdog(Redis 구현, 소비자 0, LeaseGuarantee에 EFFICIENCY_ONLY 하나뿐); CacheRefreshCoordinationPort(소비자 CacheAsideExecutor 있음, main 구현은 Disabled뿐).
  • 중복 value type: IdempotencyOwner·InboxOwner 필드 동일(scope, ownerToken, attempt, stateRevision, claimOperationId); IdempotencyClaimAttempt, InboxClaimAttempt, LeaseAttempt 같은 구조.
  • 미사용 범용: postgresql/lock/PostgreSqlWorkClaimExecutor·WorkQueue* 참조 0 — 그 사이 outbox, durable operation, notification, fileserver가 claim SQL을 각자 작성.
  • 갈라짐: fencing 있음(messaging outbox, V2, fileserver LeaseFence) vs 없음(v1 outbox, notification recipients.save — 1차 B-5).
  • 권고: claim executor 삭제(테이블마다 순서 요구가 달라 SQL 공유 이득 없음); lock과 lease 중 하나만(멱등성처럼 "포트 1 + provider 2" 또는 Redis lease adapter가 CacheRefreshCoordinationPort 구현) — 결정 필요; app-core inbox 삭제로 중복 record 해소; 공유할 것은 규칙 하나("종결 쓰기는 owner+token을 명시하고 밀려난 쪽의 쓰기는 아무것도 매칭하지 않는다") → ClaimFencingContract kit를 application-core testFixtures에 두고 각 row lease store에서 실행.

7. [Required] readiness / evidence / API-surface / moduleboundary: 같은 일을 하는 자체 프레임워크 여러 벌

  • readiness 카드 스키마 3개: config/jpa/readiness-cards.yaml:2(kebab-case, state: selected, build-tools JpaReadinessRegistryValidator), config/messaging/readiness-cards.yaml:1(camelCase, maturity:, app-bootstrap MessagingCapabilityRegistryContractTest:128), docs/registries/object-storage-readiness.yaml:5(snake_case, claimed_level: R1, ContractRegistrySchemaGovernanceTest:32 + objectstorage test).
  • evidence plugin family별: jpa 2,838줄, messaging 819, notification 851, mongo 544 — 범용 ca.strict-qualification은 leaf 9개에 이미 적용.
  • API-surface gate 3개: ca.api-surface(build-logic), ca.notification-api-surface(156줄 verifier), jpa verifyJpaAdopterApiSurface(JpaQualificationPlugin.java:57-62) — persistence-jpa는 ca.api-surface(build.gradle:8,167)와 이것을 둘 다 적용.
  • moduleboundary: *StableModule, *ModuleBoundary, *ModulePurity가 web/graphql/websocket main에 3벌(1,723줄), 테스트 *BuildModel/*SourceGraph도 3벌.
  • 갈라짐: jpa 카드가 messaging에 없는 messaging-cdc-dispatch.v1을 가리키고 성숙도 어휘 불일치(1차 E-11).
  • 권고: build-logic에 카드 스키마 1개 + 검증기 1개(id, R0–R3, family 간 prerequisite, 필수 task, 증거 selector, 한계), family plugin에는 증거 실행기만; API-surface는 ca.api-surface 하나로; moduleboundary는 production jar에서 빼서 ca.architecture/ArchUnit 규칙 1개로. Size L. 반론: 빌드 시점 코드라 런타임 위험 없음 — 단 family 간 참조가 이미 깨짐.

8. [Consider] 파일 publication: control plane·canonical JSON codec 중복 (결정 필요)

  • 구현: app-core filepublication(399) → fileserver 최상위 패키지(publication plane 8,567줄, FileserverControlRecordCodec 855 포함), FilePublicationPort main 소비자 0; deprecated FileExportPort → FilesystemCsvExportAdapter; objectstorage CanonicalJsonObjectControlRecordCodec(898), CanonicalJsonReader/Writer, ObjectControlStore(sample만 사용, app-bootstrap edge 없음).
  • 갈라짐: UTF-8 처리 — FileserverControlRecordCodec.java:842 strict(REPORT) vs LocalPublicationJournalCodec.java:156, CanonicalJsonReader.java:16 느슨한 new String; 원자적 쓰기 — LocalPublicationJournal.java:104-118 temp + ATOMIC_MOVE vs LocalDevObjectControlStore.java:54-57 제자리 CREATE_NEW(1차 D-5).
  • 권고: fileserver HTTP 플랫폼과 objectstorage는 유지(docs/storage-capability-boundary.md에 결정 문서화). 소비자 0인 FilePublicationPort plane은 삭제 권고 — CSV가 필요하면 StreamingCsvEncoder를 StagedObjectPublicationPort 앞에; parser 3개 → 1개. 둘 다 유지해야 하면 canonical JSON을 shared-contract로(두 leaf 모두 edge 있음). 반론: R2의 표 형식 정책(수식 무력화 등)은 인코더 계층 문제. 승인자: 소유자.

9. [Consider] Backoff 계산식 10개, "full jitter" 뜻 3가지

  • OutboxBackoffPolicy.java:63-65: base·2ⁿ + U(0,base) (이름과 달리 더하기 jitter, 상한 없음); httpclient :78, jpa :60: U(0,capped]; messaging :56: capped·U[0,1); notification RetryBackoff.java:43: base 하한. jpa 한 leaf에 BackoffCalculator·TransactionRetryBackoff 두 벌; grpc GrpcRetryCoordinator 소비자 0.
  • 권고: shared-contract Backoff(base, max, multiplier, Jitter)(stdlib만) — app-core outbox, httpclient, jpa 2곳(notification은 registry edge 추가 필요); mongo(edge 없음), messaging, grpc는 자기 것 유지. 반론: 공식은 20줄 — 가치는 "같은 이름 = 같은 의미" 보장.

10. [FYI] 받아들일 수 있는 중복

  • admission 제한 약 11개: transport별 거부 처리가 달라 합치지 않음. 단 GrpcAdmissionController.java:53-59 check-then-increment는 Semaphore.tryAcquire로(M1 수정이 GrpcStreamAdmission에만 적용).
  • gRPC 스택 2개: 기본 adapter:inbound:grpc(623줄)와 optional build grpc:*(약 2만 줄) — 별도 build는 의도된 결정.
  • SHA-256 hex 헬퍼 65벌: app-core Sha256 record가 이미 있음; notification MessageDigestPort는 과한 추상화 → 정리 시 흡수.

조사 범위와 한계

읽기 전용 grep/find/wc/sed; 기능마다 구현체·포트·main/test 참조 수·조립 조건(@Conditional*, stereotype)·migration 대조. "소비자 0" = 클래스명 grep -w로 main source set 확인(리플렉션·SPI 미확인). 실행 미확인: v1 outbox 이중 발행 경합, V2·v1 idempotency_record 공존 문제; 33% 복붙 비율은 정규화 줄 비교(84/253). 깊게 안 봄: fileserver platform/**, objectstorage direct/multipart, messaging 내부 중복.

X2 — 공통 유틸리티와 전송 경계 계약

Part 1: 작은 유틸리티

utility implementations (count) canonical exists? diverged? recommendation where it lives
시크릿 조회 경로 앱 쪽 5개: SecretSourcePort, S3ProviderBinding.SecretResolver, RedisSdkAutoConfiguration.RedisSecretSource, MongoCredentialResolver, notification SecretMaterialProvider; 벤더 쪽 2개: messaging CredentialProvider, grpc GrpcCallCredentialProvider 있음: application/outbound/SecretSourcePort + support EnvironmentSecretSource 있음(Spring Environment / 프로세스 env / 무조건 거부로 갈림) Required: 새 타입 없이 cache-redis 같은 1줄 bridge bean 경로 유지, bridge는 각 capability config
prod 판정 정본 1개 + 다른 구현 5종(websocket, messaging(벤더), grpc 설정값(벤더), 같은 이름의 httpclient enum, sample 3곳) 있음: shared.runtime.RuntimeEnvironment 있음(websocket은 trim·소문자 안 함, production도 prod) Required: 1줄 교체 shared-contract(기존)
Settings 바인딩·검증 @ConfigurationProperties 파일 64개, 방식 3가지, 오타 키 거부는 4곳 일부: StrictSettingsBinder(support), 규칙 문서 없음 있음 Required(문서화) 규칙은 root CLAUDE.md, 코드는 support
서명된 불투명 토큰(cursor/resume) HMAC codec 7개 없음 있음(TTL, kid, version 지원 제각각) Consider: 먼저 삭제, 서명 계층 하나로 정한 뒤 공용 헬퍼 shared-contract (grpc는 자체 사본)
SHA-256·hex MessageDigest.getInstance 파일 66개, private helper 53개(47파일) 없음 없음 Consider shared-contract Sha256 (예외 아래)
JSON 문자열 escape 직접 구현 8개(앱 7, 벤더 1) 없음 있음(동작 3가지) Consider shared-contract 또는 기존 Jackson
Clock Clock bean 3개, 주입 Clock 우회 약 20곳 있음: BootstrapClockAutoConfiguration:21-24 있음(한 클래스 안에서 두 시간 소스 혼용) Consider: 기존 bean 주입 —
상수 시간 비교 MessageDigest.isEqual 19파일, 이것 없이 HMAC 검증하는 곳 0 stdlib 없음 FYI —
Base64url 18파일, stdlib 한 줄 stdlib 없음 FYI —
마스킹 toString 약 45개, 표기 4종(REDACTED, redacted, <redacted>, ***), 로그 마스크 **** 로그는 LogMaskingPatterns 표기만 FYI (타입별 필요, 줄일 것 없음) —
requireNonBlank/requirePositive inline 검사 448곳(342파일), 이름 붙은 helper 14, requirePositive(Duration) 12 없음 메시지만 FYI (관용구) —
Size/Duration 파싱 직접 파서 0 (Spring 바인딩 + env-keys.yaml 규칙 30s, 10MB) Spring 없음 FYI —

P1-1 [Required] 시크릿 조회 경로 4갈래, bridge는 Redis 하나에만

  • 정본 SecretSourcePort(application-core), bootstrap SecretSourceFactory가 strategy 선택.
  • S3는 System::getenv 고정(adapter/outbound/objectstorage/.../s3/S3ObjectStorageProviderContribution.java:41) → Spring property source·정본 strategy 둘 다 미적용.
  • Redis 기본값도 System.getenv(RedisSdkAutoConfiguration.java:212-216)지만 cache-redis가 RedisCapabilityConfig.java:68에서 SecretSourcePort로 연결 → 결과적으로 정본 사용. 따라 할 모범 사례.
  • Mongo는 기본값 MongoCredentialResolver.unconfigured(), bridge 없음 → adopter가 Vault strategy를 설정해도 Mongo 연결만 실패.
  • 수정: S3와 Mongo에 Redis 같은 bridge bean(secretSource::resolve), 새 추상화 없음.

P1-2 [Required] websocket prod 판정이 아직 직접 구현(BOOT-002 미해결)

  • adapter/inbound/websocket/.../config/WebSocketPlatformSafetyConfiguration.java:78-85: "prod".equals(profile) || "production".equals(profile) → Prod·앞뒤 공백 미인식(fail-open). 정본 RuntimeEnvironment.fromProfile은 trim + 소문자.
  • websocket은 shared-contract에 의존 가능 → fileserver처럼 RuntimeEnvironment.isProductionActive(List.of(environment.getActiveProfiles())) 한 줄(FileserverSecurityConfiguration.java:81 참고). 1차는 "bridge가 outbound leaf에 있어 못 쓴다"고 봤지만 정적 메서드 직접 호출이면 bridge 불필요.
  • 규칙상 허용되는 별도 구현: MessagingAdminDurabilityValidator.java:25 Set.of("prod","production"), grpc GrpcTlsProfile.Environment(기본값 LOCAL, GrpcPlatformProperties:26) — 벤더 영역이라 자체 어휘 허용(RuntimeEnvironment Javadoc). 단 grpc bridge를 붙일 때 RuntimeEnvironment → GrpcTlsProfile.Environment 매핑 필요; GraphQL이 좋은 예(CapabilityDependencyValidator.java:29-30,163-185가 deployment mode를 runtime 환경과 대조).
  • httpclient profile/RuntimeEnvironment는 정본에서 값을 만들어 동작은 문제없으나(HttpClientProfileAutoConfiguration:154-159) 이름이 같아 혼동 → Nit: HttpClientHardening 등으로 개명.

P1-3 [Required(문서)] Settings 검증 방식 3가지, 새 capability가 따를 규칙 없음

  • @ConfigurationProperties 파일 64개 기준: Bean Validation annotation 5, compact constructor throw 19, 별도 *StartupValidator/*SettingsValidator 34(중복 집계 있음).
  • 오타 키 거부는 4곳: StrictSettingsBinder의 fileserver·httpclient, ignoreUnknownFields=false의 GrpcServerProperties:17·GrpcPlatformProperties:19. 나머지 약 60개는 오타 키를 조용히 무시.
  • root CLAUDE.md·AGENTS.md에 규칙 없음(web/CLAUDE.md:65 B4는 request DTO 전용).
  • 잠재 충돌(런타임 미검증): ca-skeleton.grpc는 strict이고 platform 필드가 없음(GrpcServerProperties.java:22-40)인데 벤더 prefix가 ca-skeleton.grpc.platform → 두 gRPC stack을 같이 올리면 adapter 바인딩에서 "unbound"로 기동 실패 가능성 높음.
  • 수정: root 문서에 한 줄 — "capability settings는 master-gated auto-config 안에서 StrictSettingsBinder로 바인딩, 값 검증은 compact constructor"(StrictSettingsBinder Javadoc에 근거 있음); gRPC adapter prefix 분리.

P1-4 [Consider] HMAC 서명 cursor·resume token codec 7개, 모두 production에서 생성 안 됨

codec 위치 상태
cursor/CursorCodec web TTL 24h, kid 없음, test 전용, dev key 하드코딩("ca-skeleton-dev-cursor-key-0001", CursorCodec.java:38-40)
HmacWebCursorCodec web pagination keyring 지원
HmacGraphQlCursorCodec graphql kid 있음, 만료 없음
SignedJsonCursorCodec persistence-jpa version 있음, kid 없음
MongoKeysetCursorCodec persistence-mongo kid·만료 없음
ResumeTokenCodec websocket kid·만료 있음
GrpcResumeTokenCodec grpc(벤더) kid·만료 있음
  • 이름 grep 기준 7개 모두 production에서 new 없음. inbound·outbound 양쪽에 서명 codec → adopter가 어느 계층에서 서명할지 모름; 같은 이름 CursorCodec 2개(web 클래스, persistence-jpa 인터페이스).
  • 권고: (1) web cursor/CursorCodec 삭제 (2) 서명 계층 하나 — inbound에서 서명, persistence는 typed keyset만 (3) 남은 코드가 2개를 넘으면 stdlib sign/verify 헬퍼(약 80 LOC, kid + 선택적 만료)를 shared-contract에.

P1-5 [Consider] SHA-256 보일러플레이트 — 예외 래핑 65곳 중 64곳 IllegalStateException, 호출부마다 6~8줄; 결과 바이트는 모든 곳 동일(UTF-8, 소문자 HexFormat.of(), charset 없는 getBytes() 0곳) → V1 fingerprint(EnvelopeHashV1, PartitionKeyV1)를 교체해도 바이트 불변. shared-contract Sha256.digest(byte[])/Sha256.hex(String)로 약 51개 파일에서 약 350줄 감소(objectstorage 14, fileserver 12, messaging adapter 6). 자체 사본 유지: shared-contract에 의존할 수 없는 persistence-mongo(4), application-notification(3), application-objectstorage(2)(application-core가 shared-contract를 implementation으로 선언해 전달 안 됨, application-core/build.gradle:11); messaging(2)·grpc(2)는 벤더 규칙.

P1-6 [Consider] JSON 문자열 escape 3가지로 갈림 — RFC 8259 제어문자까지(5개: OutboxEnvelopeJson.java:44, redis-sdk JsonEnvelopeFraming.java:166, LocalPublicationJournalCodec.java:121, sample PosterEventPublisher.java:89, WorkLogReservedIntegrationEventMapper.java:56); ASCII만 허용·나머지 거부(CanonicalJsonWriter.java:82, digest 입력용 → 유지); \와 "만(sample PosterImagePublicationEventPublisher.java:76-78 — 제어문자가 들어오면 잘못된 JSON, 지금 값은 ID·media type이라 위험 낮지만 sample은 adopter가 복사). 수정: sample 3곳은 Jackson, outbox adapter·fileserver 2곳은 공용 JsonStrings.quote(약 25 LOC), redis-sdk·messaging은 자체 사본.

P1-7 [Consider] Clock 우회 — RoutingObjectMutationAdapter는 clock 필드가 있는데(:60,70) Instant.now() 14번(:128-349), 게다가 설정 코드가 Clock.systemUTC()로 생성; objectstorage 설정 5곳 직접 Clock.systemUTC()(ObjectStorageCapabilityConfig.java:78, ObjectStorageScanMaintenanceConfig.java:19, ObjectStorageBindingCompiler.java:40, S3ObjectStorageProviderContribution.java:33,35); 그 밖에 MvcStreamWriter ×5, WebFluxPlatformAutoConfiguration.java:54, LocalFilePublicationAdapter.java:184,229, FileserverR2Config.java:65, LiveEventStompBroadcaster.java:99, MongoTenantClientRegistry.java:70, KeyOperationRequests.java:139. 수정: 기존 Clock bean 주입(adopter가 Clock을 바꾸면 테스트 시간이 이 코드에도 적용).

Part 2: 전송 경계 관심사

concern implementations shared contract? diverged? recommendation
에러 어휘·wire 매핑 경로 9개 이상(아래) 있음: ApiErrorCode, ApiErrorCarrier, Category, OperationalError, error-codes.yaml 있음 Required: 계약 적용 범위 확대, 병행 어휘 정리
Carrier 적용 범위 web만 타입별 handler로 매핑 ApiErrorCarrier 있음 Required: 1줄 변경 5개
Request·trace·correlation id web 필터 3, GraphQL은 Spring id, websocket 자체 id, gRPC 없음 일부: TraceParent(3곳), MdcKeys는 web에만 있음 파서 정리 Required, 키 이동 Consider
인증 컨텍스트·tenant 전송마다 principal/tenant 타입 따로 AuthorizationPrincipal(web만) 있음(tenant 문법) tenant Required, principal Consider
Rate limit MVC RateLimitInterceptor + 연결 안 된 병행 stack EdgeRateLimitPort 병행 구현 Required(삭제)
Body/message 크기 제한 전송별 knob 불필요 에러 코드만 다름 FYI
CORS/origin 검증기 3, env key 3 없음 기본값 다름 Consider: websocket 안의 2개만 합침
응답 envelope 같은 servlet 앱에서 Envelope·problem+json 혼재 Envelope 있음 Required

에러 매핑 구현(module · class · LOC): web — GlobalExceptionHandler 417, ErrorResponseFactory 35, ClientSafeErrorMessages/ProblemCode 81, ProblemCatalog 183, problem-catalog.yaml, WebMvcProblemExceptionHandler 174, WebFluxProblemExceptionHandler 164, BudgetProblemMapper 76, ThrottleProblemWriter 78; web-fileserver — FileserverExceptionHandler 46, FileserverProblemFactory 45; graphql — GraphQlWireErrorMapper 124, GraphQlPlatformRejectionMapper 136, GraphQlErrorCategory 40, GraphQlErrorCode 113, GraphQlRequestErrorMapper 57(참조 0); websocket — SafeStompSubProtocolErrorHandler 32, WebSocketCloseCode 95; grpc adapter — GrpcStatusMapper 57, GrpcExceptionHandlingInterceptor 131; grpc 벤더 — GrpcErrorMapper 182(규칙상 유지).

P2-1 [Required] 같은 코드 이름이 status나 retryable이 다르게 나감

  • VALIDATION_FAILED: OperationalError.java:15·error-codes.yaml:756-758 400, problem-catalog.yaml 422.
  • budget 경로 크기 초과: URI_TOO_LONG(원래 414, OperationalError:41)이 REQUEST_TOO_LARGE(413)로(BudgetProblemMapper.java:34), JSON 깊이 초과는 VALIDATION_FAILED(422)로(:37). WebMvcBudgetExceptionHandler는 backend.web.budgets.enabled=true면 켜져(:40) Envelope servlet 앱 안에서 budget 초과만 problem+json.
  • ProblemCode는 이름이 다른 동의어 병행 어휘(error-codes.yaml에서 0건): RATE_LIMITED/RATE_LIMIT_EXCEEDED, REQUEST_TOO_LARGE/PAYLOAD_TOO_LARGE, IDEMPOTENCY_KEY_REUSED/IDEMPOTENT_REQUEST_MISMATCH, AUTHENTICATION_REQUIRED/UNAUTHENTICATED, ACCESS_DENIED/FORBIDDEN.
  • GraphQL은 retryable을 코드별이 아니라 category에서 계산(GraphQlWireError.java:73, GraphQlErrorCategory:13-28, GraphQlWireErrorMapper.java:104-106) — shared README는 "retryable은 코드별 값": RATE_LIMIT_EXCEEDED REST true(OperationalError:46) vs GraphQL false; DB_DEADLOCK/DB_SERIALIZATION_FAILURE/LOCK_ACQUISITION_TIMEOUT true vs false; DB_QUERY_CANCELED false(:61) vs true.
  • 사용자 메시지: web 코드별 영어(ClientSafeErrorMessages.java:14), GraphQL category별 한국어(GraphQlWireErrorMapper.java:114). gRPC trailer에는 retryable 없음(GrpcStatusMapper.trailersFor).
  • 수정: (a) GraphQL fromApiError에서 retryable = code.retryable(), 플랫폼 자체 코드만 category 기본값 (b) ProblemCode·ProblemCatalog 제거, problem document는 ApiErrorCode의 httpStatus()·code()에서(약 260 LOC + yaml 감소) (c) Envelope 계약이 켜져 있으면 budget handler도 Envelope (d) client-safe 메시지 표 하나로.

P2-2 [Required] shared 예외가 ApiErrorCarrier를 구현하지 않아 web에서만 제대로 매핑

  • MappingException(shared/error/MappingException.java:11), AdapterDisabledException(:13), application-core Idempotency{InFlight,RequestMismatch,ScopeMissing}Exception은 평범한 RuntimeException. web은 타입별 handler(GlobalExceptionHandler.java:79,91,193,205,218); GraphQL(GraphQlWireErrorMapper.mapCommon)·gRPC(GrpcExceptionHandlingInterceptor.java:105,121)는 instanceof ApiErrorCarrier만 봐서 INTERNAL_ERROR.
  • IllegalArgumentException: web 400 BAD_PARAMETER(:103-109), GraphQL·gRPC INTERNAL_ERROR → 같은 검증 실패가 REST에선 클라이언트 잘못, 다른 전송에선 서버 장애.
  • 수정: 위 5종이 ApiErrorCarrier 구현(errorCode() 1줄씩) → 모든 전송의 기존 carrier 분기가 처리, web 타입별 handler 5개 삭제 가능. IAE → 400은 정책 결정(전송 전체에 한 번에 적용 또는 web에서도 제거).

P2-3 [Required] HTTP 에러 응답 모양이 기능마다 다름 — shared README는 Envelope가 RFC 7807을 대체(D5); 같은 servlet 앱에서 fileserver는 항상 problem+json(FileserverExceptionHandler.java:35-40), budget 초과 problem+json, 나머지 Envelope; WebFlux엔 Envelope advice 없음(flag off면 Spring 기본 형식). FileserverErrorCode는 이미 ApiErrorCode 구현 → Envelope 전환 거의 무비용; UNAUTHENTICATED, PRECONDITION_FAILED, UNSUPPORTED_MEDIA_TYPE은 OperationalError와 이름이 같음(status 같으나 코드 문자열이 enum 두 곳에 정의). 허용: GraphQL·gRPC(프로토콜이 형식 결정), STOMP close code, notification callback(외부 provider용 본문 없는 204/400/413, NotificationCallbackMvcController.java:87-98).

P2-4 [Required] 한 요청 안에서 traceparent를 두 번, 다른 규칙으로 파싱 — WebMvcRequestIdFilter.java:49-50·WebFluxRequestContextFilter.java:46-47은 정규식 사본(version 무시, 전부 0인 trace-id 허용) vs RequestLoggingFilter.java:57-69는 엄격한 TraceParent.parse(version 00만, 전부 0 거부); 두 필터 기본 동시 활성(WebMvcPlatformAutoConfiguration.java:50-54,146-150) → request attribute WebTraceId와 MDC trace_id(Envelope meta.traceId)가 다른 값이 될 수 있음; request id도 두 필터가 각각 생성 가능(RequestLoggingFilter:60). 수정: 정규식 2개 삭제, TraceParent.parse 사용. (1차 I-4와 같은 영역)

P2-5 [Consider] correlation이 HTTP 밖으로 이어지지 않음 — MdcKeys(13 LOC)가 adapter/inbound/web/observability에 있어 다른 inbound가 못 씀; MDC.put 1파일(RequestLoggingFilter); CorrelationIdPort 구현은 web MDC adapter 하나 → STOMP·gRPC 호출에서 outbox 등의 correlation 단절; GraphQL executionId는 Spring GraphQL request id(GraphQlPlatformWebInterceptor.java:156-159), X-Request-Id·로그와 무관. 수정: MdcKeys를 shared-contract로(원본 docs/registries/mdc-keys.yaml), 전송마다 MDC 채우는 얇은 코드, GraphQL은 platform request id.

P2-6 [Required(tenant) / Consider(principal)] 인증 컨텍스트

  • 같은 이름 TenantContext 두 개, 허용 값 다름: web [A-Za-z0-9][A-Za-z0-9_.-]{0,63}(web/core/TenantContext.java:20) vs graphql 비어 있지 않고 128자 이하면 무엇이든(graphql/context/TenantContext.java:17,30) → 같은 tenant가 한 전송은 통과, 다른 전송은 거부. 수정: application-core tenant id 값 타입 하나 + 두 context가 감쌈.
  • principal 전송마다: web AuthenticatedPrincipal(19) + ActorContext(52) + SecurityIdentity(22); graphql GraphQlPrincipalResolver(기본 anonymous → web 필터 체인이 검증한 JWT를 안 씀); websocket request.getPrincipal(); gRPC GrpcAuthenticationPolicy는 boolean만(principal·tenant 없음).
  • 가명 처리도 전송마다: UserPrincipalPseudonymizerPort(APP_PRIVACY_PSEUDONYMIZATION_SALT), GraphQL GraphQlIdentityFingerprinter(150, 자체 key), 키 없는 ActorRef.sha256Prefix, websocket salt SHA-256 → 같은 사용자가 전송마다 다른 가명으로 로그.
  • 권고: application AuthorizationPrincipal에 tenant 추가, 모든 전송이 이것을 생성; bootstrap에 Spring Security → GraphQL 기본 bridge resolver.

P2-7 [Required] 연결되지 않은 두 번째 rate-limit stack — WebRateLimiter(25), WebMvcThrottleFilter(136), WebFluxThrottleFilter(142), ThrottleProblemWriter(78) 모두 Spring 어노테이션 없음, production 생성 0, 테스트 0; 동작하는 것은 RateLimitInterceptor(EdgeRateLimitPort, :75)뿐 → 삭제. WebFlux·websocket·gRPC엔 rate limit 없음; GraphQL-over-HTTP가 MVC interceptor에 걸리는지 미확인(걸려도 모든 요청이 POST /graphql 하나). client IP 신뢰 규칙도 모듈 안에서 두 갈래: ForwardedHeaderClientIpResolver.java:11-16(trusted-proxy 없이 XFF 첫 hop) vs ExternalRequestUrlResolver.java:31(trusted proxy 요청만) — 1차 I-5.

P2-8 [Consider] Origin 검증기 3개 — web WebCorsPolicyValidator.java:59, websocket WebSocketOriginPolicy.java:95, WebSocketProperties @AssertTrue가 각자 "wildcard 없이 정확 일치" 구현; env key 3개 기본값 다름(APP_SECURITY_CORS_ORIGINS 빈 값, APP_WEBSOCKET_ALLOWED_ORIGINS http://localhost:3000, APP_WEBSOCKET_PLATFORM_ALLOWED_ORIGINS 빈 값). websocket 안의 두 사본만 합침(모듈 간 공유는 약 40 LOC라 가치 없음).

P2-9 [FYI] 크기 제한 — knob은 전송마다 맞음(web budgets, graphql maxBodyBytes/maxDocumentBytes, websocket maxMessageBytes, grpc maxInboundMessageBytes); 위반 코드는 다름(PAYLOAD_TOO_LARGE, REQUEST_TOO_LARGE, GRAPHQL_DOCUMENT_SHAPE_REJECTED, close 1009, RESOURCE_EXHAUSTED) → P2-1 정리 때 이름만 통일. websocket STOMP는 모든 실패를 WEBSOCKET_REQUEST_REJECTED 하나로(SafeStompSubProtocolErrorHandler.java:12, carrier 코드 소실). gRPC adapter GrpcStatusMapper와 벤더 GrpcErrorMapper는 bridge 미연결이며 그 사실이 grpc/CLAUDE.md:88-93에 기재 → 공존 가능.

Coverage note

대상: src/*/src/main/java 73개 source set(grpc-codegen fixture, build/, bin/ 제외); 개수는 ERE grep(이름 기준 helper 수는 최소치); 벤더 영역은 규칙상 자체 사본이라 권고 제외. 미확인: MVC rate-limit interceptor가 GraphQL route에 걸리는지, ca-skeleton.grpc prefix 충돌의 실제 기동 실패 여부, Spring GraphQL request.getId() 값. capability 단위 중복은 X1 담당, grpc-advanced edge·notification callback 서명 검증은 상수 시간 비교 여부만 확인.

S1 — Core and application leaves

Path abbreviations: AC/ = src/application-core/src/main/java/dev/caskeleton/application/, AN/ = src/application-notification/src/main/java/dev/caskeleton/application/notification/, AF/ = src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/, AO/ = src/application-objectstorage/src/main/java/dev/caskeleton/application/, SC/ = src/shared-contract/src/main/java/dev/caskeleton/shared/

Per-leaf maintainability verdict

leaf main LOC verdict one-line reason
domain-core 110 HEALTHY 마커 3개 + ID 인터페이스 2개. 단, application-core가 이 leaf에 의존하지 않아 production에서 안 쓰임(#16)
shared-contract 2.8k NEEDS_WORK 한 leaf만 쓰는 타입 약 550줄; CLAUDE.md 책임 목록은 13개 패키지 중 6개만 설명
application-core 9.1k OVERBUILT 약 4.9k줄(54%)이 production 호출 경로 밖; idempotency 2세대·outbox 3세대 공존
application-notification 17.0k OVERBUILT R1 4.5k(1차) + platform 미사용 약 0.9k; 생성자 15개짜리 dispatch 서비스; 같은 전략만 담은 레지스트리
application-fileserver 6.8k NEEDS_WORK use-case 계약 밖 *Service/Default* 쌍 10개; retire 로직 3곳 복사, 이미 다름; 에러 코드마다 예외 클래스
application-objectstorage 2.7k NEEDS_WORK 포트만 담은 단순 구조. 거의 같은 식별자 클래스 6개, 복사된 가드, deprecated legacy 네임스페이스

Findings (highest leverage first)

  1. [Required][duplication] idempotency 엔진 2세대 공존, V2는 bean만 있고 호출자 0 — AC/idempotency/IdempotencyExecutor.java:19, AC/idempotency/v2/IdempotencyExecutorV2.java:33,94

    • Evidence: V1 = executor + IdempotencyStorePort + IdempotencyScope; V2 = executor + IdempotencyStorePortV2 + IdempotencyScopeDigest + outcome 타입 13종(767줄). V2 executor는 PostgreSqlIdempotencyProviderConfig.java:51, RedisIdempotencyConfig.java:68에서 생성만, main execute 호출 0; 실제 호출은 sample V1(PublishPosterImageUseCase.java:61)뿐; bootstrap에 두 세대 bean 수를 세는 배타성 가드(IdempotencyProviderSelectionConfig.java:42-57, IdempotencyComposition.java, 112줄); 실패 처리 이미 다름(1차 A-8).
    • Remedy: 한 세대로 — V2 정본(web·sample scope 생성 이전, V1·가드 삭제) 또는 소비자 생길 때까지 V2 삭제. Size L · 약 300줄 + 가드 112줄(또는 반대로 V2 767줄 + 어댑터 2개).
  2. [Required][duplication] outbox 포트 3세대, 실제 사용은 legacy 하나 — AC/outbox/LegacyOutboxAppendPort.java:11, AC/outbox/OutboxAppendPort.java:13, AC/outbox/v2/OutboxAppendPortV2.java:9 (append 포트 3개 중 main 호출자는 sample이 쓰는 legacy뿐; 폴링 포트 둘 OutboxStorePort.java:14·OutboxPollingDeliveryPortV2.java:7; retry 정책 둘 OutboxBackoffPolicy.java:15·OutboxV2RetryPolicy.java:16; ClaimedOutboxEvent.java:11이 legacy·canonical을 sealed로 묶음). Remedy: 한 세대만(append 1, 폴링 1, retry 1), 1차 A-3의 V2 publish 466줄 포함. Size L · 약 0.7–1.0k줄, 포트 4개. 반론: 세대 전환 중 — 템플릿 adopter에겐 옮겨올 세대 이력이 없음.

  3. [Required][reachability] application-core 호출자 없는 코드 약 2.8k줄(#1·#2 제외) — 호출자 자체 없음: cache executor 계열 20파일 1,488줄(AC/cache/CacheAsideExecutor.java:19, @Deprecated, "shipped runtime does not compose"), LeaseWatchdog(AC/lease/LeaseWatchdog.java:28) 228줄, TransactionCompletionResolver/CompletionResolution 50줄. 어댑터 구현은 있으나 use case가 안 부름: lease/* 399, inbox/* 213(InboxOwner·InboxClaimAttempt는 idempotency/v2 같은 역할 타입과 필드 동일), filepublication/* 399, EphemeralFanoutPort 58. Remedy: use case가 생길 때 추가, 유지하면 별도 library leaf/testFixtures. Size L. 반론: H5 결정이 "검증된 reference"로 유지 — 코드 스스로 @Deprecated.

  4. [Required][SRP|readability] NotificationDispatchService 한 클래스가 흐름 제어·record 복사·실패 분류 — AN/platform/dispatch/NotificationDispatchService.java:72-87,202-231,253-288,483-508 (생성자 15개; 22필드 record를 필드별로 재조립하는 곳이 이 파일 2곳 + DispatchOutcomeRecorder.java:66-90,108-132 2곳 → record() 105줄; catch 분기 :253-288은 provider 결과 분류 정책; 종료 상태 계산 :473-475·:510-514 두 번; FQN 11줄; record 전체 재작성 방식이 1차 B-5(stale snapshot 덮어쓰기)의 구조적 원인). Remedy: record 전이 메서드(DeliveryAttemptRecord.completed(result, at)/leaseLost(at), RecipientDeliveryRecord.advancedRoute(now)), catch 분기는 ProviderOutcomeClassifier 정적 메서드. Size M · 약 150줄.

  5. [Required][duplication] fileserver retire 절차 3곳 복사, 이미 다름 — AF/lifecycle/DefaultFileLifecycleService.java:84-104, AF/admin/DefaultFileserverAdminService.java:159-181, AF/upload/DefaultUploadApplicationService.java:250-270 (셋 다 markDeleting 후 cleanupQueue.enqueue; lifecycle은 content 키 없으면 DELETING→DELETED, admin forceDelete엔 이 분기 없음 → content 없는 레코드가 DELETING에 남음(바로 위 주석 "must not ... leave a file unreachable"과 모순); cancel 쪽은 1차 C-4). Remedy: retire(FileRecord) 하나. Size S.

  6. [Required][structure] fileserver 인바운드가 use-case 계약 밖 — AF/upload/UploadApplicationService.java 외 9개 (이 leaf의 @UseCaseCapability/CommandUseCase/QueryUseCase 0건(notification은 17/18) → capability fitness gate 미적용; 인터페이스 6개 CleanupService, WriterLeaseCoordinator, FileLifecycleService, TransferAdmissionController, FileReconciliationService, FileStateMachine은 두 번째 구현·fake 없음). Remedy: 최소안은 6개 인터페이스 삭제; 템플릿 정합은 transport가 부르는 연산을 *UseCase + capability 선언으로. Size M/L.

  7. [Consider][duplication|pattern] 에러 코드마다 예외 서브클래스 약 45개, 타입 분기는 5개 — AF/api/error/*Exception.java(23파일, 571줄), AN/platform/api/error/*Exception.java(25파일, 323줄) (transport는 code/context로 매핑(FileserverExceptionHandler.java:35); 타입 catch는 fileserver 3(AmbiguousCompletion, UploadOffsetMismatch, FileNotFound) + notification 2; notification 예외 12개는 throw 0; FileTooLargeException.java:8 생성자가 아무 context나 받아 타입≠code 가능; FileNotFoundException, FileAlreadyExistsException, InvalidPathException은 JDK 이름과 같아 어댑터가 FQN으로 구분(LocalPersistentRootAttestor.java:283)). Remedy: base를 구체 클래스 + of(code, …), 서브클래스는 타입 분기 5개만. Size M · 약 700줄.

  8. [Consider][over-abstraction] PolicyTransactionPort 계열이 호출 1곳을 위해 존재 — AC/transaction/PolicyTransactionPort.java:9, AF/upload/FileserverCompensationTransaction.java:20-59 (main inTransaction 호출 1곳, 정책 7개 중 MAINTENANCE_NEW만; 결과 5종을 전부 예외로 되돌려 결국 inNew와 같음; 딸린 타입 7개 약 290줄). Remedy: TransactionPort.inNew 사용, persistence-jpa SpringPolicyTransactionPort까지 삭제. Size M.

  9. [Consider][over-abstraction] 같은 전략만 담은 레지스트리 2개 — AN/platform/callback/ProviderEventProjectorRegistry.java:7(구현은 StandardDeliveryProjector 하나; Twilio/Ses 서브클래스는 providerId만 넘기고 "No provider-specific transitions are needed"), AN/platform/dispatch/TemplateRendererRegistry.java:10(모든 channel에 같은 클래스 등록, NotificationPlatformProviderConfig.java:55-77). Remedy: 구현체 직접 주입. Size S · 타입 7개, 약 140줄.

  10. [Consider][duplication] 알림 제출 진입점 두 벌 — AN/platform/dispatch/NotificationSubmissionService.java:38,81-90,186-191 vs Submit/ScheduleNotificationApplicationUseCase.java (prepare → inWrite(commit) → recordAccepted 흐름·주석까지 복사; NotificationOrchestrator의 유일한 소비자는 호출자 없는 ReactorNotificationOrchestrator(1차 B-8)). Remedy: Reactor facade와 함께 NotificationOrchestrator·서비스 public 진입 메서드 삭제. Size S.

  11. [Consider][duplication] SHA-256 헬퍼 분산, RequestFingerprint 이름 충돌 — AN/platform/dispatch/MessageDigestPort.java(stdlib 해시를 outbound 포트+어댑터로 감쌈; 다른 7곳은 MessageDigest.getInstance("SHA-256") 직접, 예 AO/objectstorage/model/ObjectDigest.java:35), AN/platform/dispatch/RequestFingerprint.java:15 vs AC/idempotency/RequestFingerprint.java:13(grep 결과가 섞임 — 이 리뷰의 도달성 스캔도 한 번 잘못 셈). Remedy: application-core Sha256.hex(byte[]) 하나, 포트·어댑터 삭제, notification 쪽은 PlanFingerprint로 개명. Size S.

  12. [Consider][over-abstraction] fileserver content SPI를 application이 안 씀 — AF/api/content/{BlockingContentStore,AsyncContentStore,CopyCapableContentStore,CapacityAwareContentStore,DelegatedDownloadStore}.java (application은 좁은 gateway 8개만; BlockingContentStore는 어댑터만 참조; 나머지 4개 + record 3개는 구현·호출 0, 143줄). Remedy: 확장 4개 삭제, BlockingContentStore는 어댑터 내부로. Size S · 약 190줄.

  13. [Consider][pattern] FileStateMachine 인터페이스 → enum 메서드 — AF/api/FileStateMachine.java:9, AF/api/DefaultFileStateMachine.java (전이표 Map 하나를 인터페이스·구현·bean으로 감쌈; 반대로 notification RecipientDeliveryState는 전이표 없이 여러 파일에서 제각각 전이 결정). Remedy: FileState.canTransitionTo(target). Size S.

  14. [Consider][reachability] notification platform에서 R1 외 약 920줄(40파일) 미사용 — AN/platform/api/error/(throw 0 예외 12), AN/platform/security/{NotificationRedactor,SafeDiagnosticContext,SensitiveValueClassifier}.java(157), AN/platform/sms/*(218), push/, email/, webpush/. Remedy: 삭제. Size S.

  15. [Consider][structure] shared-contract가 한 leaf만 쓰는 타입 보관소 — SC/activation/*(207, app-bootstrap만), SC/opstore/*(128, graphql advanced/**만, 구현 0), SC/ratelimit/{RateLimitPolicy,RateLimitAlgorithm,RateLimitEvaluationDedupPolicy}.java(216, cache-redis만; RateLimitEvaluationDedupPolicy.java:9-10은 "Redis program" 전제 — 어댑터 구현 설정); src/shared-contract/CLAUDE.md 책임 목록은 13개 패키지 중 6개만. Remedy: 유일한 소비자 leaf로 이동, opstore 삭제. Size M.

  16. [Consider][structure] 문서가 말하는 application-core → domain-core 의존이 빌드에 없음 — src/application-core/build.gradle:11 (registry는 허용, CLAUDE.md:54·AGENTS.md 작업 순서도 전제; 실제 의존은 b3add016(2026-07-28)에서 빠짐; application-* 전체 dev.caskeleton.domain import 0; 그 결과 domain-core IdFactory 대신 NotificationIdGeneratorPort, UploadIdentifierFactory가 따로 생김). Remedy: 의존 한 줄 복원, 또는 domain-core를 "fork에서만 쓰는 leaf"로 문서화. Size S.

  17. [Consider][duplication] objectstorage 식별자·가드 복사, legacy 네임스페이스 공존 — AO/objectstorage/identity/{ObjectId,ObjectReference,ObjectStageHandle,ObjectVersionToken,PartReceiptToken,DirectTransferSessionId}.java(40줄 클래스 6개, 이름·검증 호출만 다름), AO/objectstorage/model/ObjectModelSupport.java:11 vs AO/objectstorage/request/ObjectRequestSupport.java:18(본문 같고 인자 순서만 반대), AO/storage/ObjectStoragePort.java:6,28(legacy application.storage 284줄은 sample만; Javadoc이 "the only dependency"와 "Legacy compatibility only"를 동시에). Remedy: 식별자 record + toString만 재정의, 가드 하나, legacy 네임스페이스는 sample로 옮길지 결정. Size S/M · 약 160줄.

  18. [Consider][structure] 포트·서비스 이름 규칙이 leaf마다 다름 — AF/api/metadata/FileQuotaService.java(outbound인데 Service); CLAUDE.md는 outbound = *Port; fileserver outbound 이름: Store 7, Gateway 8, Port 5, 그 외 Probe/Queue/Ledger/Locator/Service/Factory/Verifier; notification outbound: Port 34, StorePort 15, Registry/Ledger/Inbox/Protector; 인바운드 *UseCase/*ApplicationUseCase/*Service+Default* 혼재; V2 접미사 타입 5개; 파일 관련 어휘 4곳(filepublication, deprecated fileexport, fileserver, objectstorage). Remedy: outbound *Port, inbound *UseCase로 기계적 개명, #1·#2 정리 뒤 V2 제거. Size M.

  19. [Nit][readability] 이력 주석 약 50곳("used to", "Replaces an injected", "There were two V2 store contracts" — 예 NotificationDispatchService.java:57-62,187-189,264-267,334-339, IdempotencyExecutorV2.java:17-31); inline FQN notification 82줄, application-core 7줄.

  20. [Nit][structure] notification dispatch/ 패키지에 여러 기능 — AN/platform/dispatch/(46파일, 3.8k줄)에 제출, 템플릿 게시, 조회, ContactPoint*(contact/ 패키지가 따로 있는데도), reconciliation, worker. Remedy: submission/, dispatch/, reconciliation/. Size M(이동만).

Cross-module leads (not investigated)

  • messaging:* 자체 outbox/inbox(messaging-outbox-jdbc-postgresql, messaging-inbox-jdbc-postgresql/IdempotentConsumer.java)와 application-core outbox/inbox 같은 패턴 3~4벌.
  • UUIDv7 생성: notification UuidV7Generator, fileserver RandomUploadIdentifierFactory, sample Uuid*IdFactory.
  • outbound 어댑터(RedisIdempotencyConfig.java:68)가 application executor 조립.
  • 어댑터 Local*Gateway 7개(383줄)는 LocalBlockingContentStore를 넘기기만.
  • persistence-jpa SpringPolicyTransactionPort는 #8과 함께 정리.
  • fileserver 전이 규칙이 DefaultFileStateMachine과 persistence FileTransitionRepository SQL 두 곳.

Coverage note

정독: dispatch/submission 서비스·제출 use case, 두 idempotency executor, outbox/transaction 포트, fileserver upload/lifecycle/admin/error/content, objectstorage identity/support, shared-contract ratelimit/opstore. 도달성은 클래스 이름 grep으로 이 leaf들 밖 main에서의 전이 참조(리플렉션·문자열 bean 미포착; 이름 충돌로 한 번 잘못 셈 → 수동 교정). 훑음: notification policy/observation/provider, fileserver finalize/cleanup.

S2 — Persistence leaves

Path prefixes: JPA/ = src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/, MONGO/ = src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/, FS/ = src/adapter/outbound/persistence-fileserver/src/main/java/dev/caskeleton/adapter/outbound/persistence/fileserver/

Per-leaf maintainability verdict

leaf main LOC verdict one-line reason
persistence-jpa 26,317 OVERBUILT Three things in one: a JPA platform library (~13.6k), skeleton-wide stores (~5.7k), the notification feature (~7.1k). Only 16.2k statically reachable from wiring; supported adopter surface is 20 types.
persistence-mongo 23,188 OVERBUILT allowed_dependencies is [] → implements no application port, no production consumer; 13.1k lines not referenced even by its own auto-config.
persistence-fileserver 2,538 HEALTHY One self-contained feature; its tests/docs were left in another leaf; same gate repeated on root config and 9 classes.

Q1 (is persistence-jpa one leaf?): No — three things. Skeleton-wide stores (outbox, idempotency, inbox, operation, liveevent, lock) implement application-core ports and belong here; notification is the same case fileserver was and should come out the same way (#1). Q2 (how much Mongo is "advanced"?): advanced = 3.4k; reactive + change streams ~2.7–4k (excluded from the shipped jar). What an adopter needs: ~1–1.5k (opt-in gate, client profile, health, startup validator).

Findings (highest leverage first)

  1. [Required][structure] persistence-jpa carries notification persistence (27% of the leaf) — JPA/notification/** (7,066 lines), db/migration/jpa/notification-platform (841 SQL lines)

    • Evidence: notification imports only application.notification (184) and itself; 0 imports from other persistence.*; only reverse edge JPA/autoconfigure/PersistenceJpaAutoConfiguration.java:6,24 → forces persistence-jpa → application-notification (modules.json:68), so every JPA deployment resolves notification. Three things exist only to exclude it: JPA/config/PersistenceJpaConfig.java:87 (OPT_IN_NOTIFICATION_PACKAGE), a 19-package list repeated in @EntityScan and @EnableJpaRepositories (only 5 packages hold entities), PersistenceEntityScanCoverageTest. JPA/notification/crypto (505 lines) is test-only, a parallel copy of the wired adapter/outbound/notification/.../AesGcmNotificationPayloadProtection.
    • Remedy: new module using the persistence-fileserver/build.gradle:3-14 recipe; delete crypto. Size L · Removes the jpa→application-notification edge, both 19×2 lists, the constant, the coverage test, 505 dead lines.
    • Assumption/Counter: notification ITs need jpa's container fixture (reuse via testFixtures) / one more registry leaf.
  2. [Required][reachability] persistence-mongo: a 23k-line platform with no consumer — modules.json:84, src/app-bootstrap/build.gradle:129

    • Evidence: runtimeOnly, no main source names a Mongo type; reachability from its 3 auto-config entry points 10.1k/23.2k; unreferenced by any wiring: transaction 1.6k, schema 1.9k, migration 1.2k, query 1.5k, security.admin 0.6k, advanced 3.4k. Nothing imports MONGO/advanced/autoconfigure/MongoAdvancedConfiguration.java → every ca-skeleton.persistence-mongo.advanced.*.enabled flag is bound by nobody. 10 interfaces without implementation: MongoSearchOperations, MongoVectorSearchOperations, MongoTimeSeriesOperations, MongoGridFsCompatibilityReader, MongoIntegrationEventPublisher, MongoChangeToIntegrationEventMapper, MongoDataKeyResolver, MongoTenantDatabaseResolver, MongoTenantMigrationCheckpointStore, TenantScopedMongoOperations. Carrying cost: 16k test lines, 261-line build.gradle, 2 release scripts.
    • Remedy: keep a "Stable core" ~1.5k (MongoOptInAutoConfigurationImportFilter, MongoRootAutoConfiguration, MongoPersistenceSettings, client/*, MongoProfileProperties, health/startup/topology); delete the rest (git keeps it) or move to a separately versioned library. Size L · Removes ~20k main + ~14k test.
    • Assumption/Counter: tech-log-backend does not use platform types (to check) / leaf CLAUDE.md declares an intentional platform with an API snapshot.
  3. [Required][duplication/reachability] Two transaction/retry engines, one used — JPA/transaction/, JPA/autoconfigure/PersistenceJpaRuntimeConfig.java:54-78

    • Evidence: live: SpringTransactionPort.java:29 → SpringPolicyTransactionPort + TransactionRetryBackoff + TransactionRetryClassifier (40001/40P01 hard-coded :8-9). Second: SpringJpaTransactionExecutor, FullTransactionRetryCoordinator, DefaultJpaRetryPolicy, BackoffCalculator, RetryBudget, PersistenceFailureTranslatorChain, EvidenceAwareJpaTransactionManager, CompletionUnknownRecorder, TransactionProfileRegistry — beans created, JpaTransactionExecutor 0 consumers, last three referenced only from Javadoc/tests. JpaTransactionAutoConfiguration.java:37 claims "the retry coordinator implements PolicyTransactionPort" — false. SQLSTATE tables duplicated: failure.SqlStateErrorMapping (Standard/PostgreSql/H2) and postgresql.error.PostgreSqlState + h2/H2FailureTranslator.java:48-52; 40001 in 4 places.
    • Remedy: keep the port-backed engine, delete the second; one SQLSTATE enum per vendor for mapping and retry. Size L · Removes ~1.2k lines, 2 of 4 tables.
    • Assumption/Counter: CLAUDE.md invariant "CompletionUnknown is not retried" is enforced only by the unused engine — move it into the live one if it matters.
  4. [Required][duplication] Three outbox generations and two idempotency generations side by side — JPA/outbox/OutboxStoreAdapter.java:43, JPA/outbox/CanonicalOutboxAppendAdapter.java:28, JPA/postgresql/outbox/* (1,055), JPA/postgresql/inbox/* (596), JPA/idempotency/IdempotencyStoreAdapter.java:30 vs JPA/postgresql/idempotency/PostgreSqlOwnerSafeIdempotencyStore.java:61

    • Evidence: V2 outbox, V2 polling, inbox adapters constructed by no production code (only CandidateAdapterCompositionTest + ITs); outbox/entity/OutboxEventEntity.java has 57 public methods (legacy + canonical columns); outbox migrations across 3 streams (postgresql/V3,V13,V14, jpa/outbox-storage, jpa/outbox-polling).
    • Remedy: finish the migration, one generation per capability; keep possibly-applied migrations, delete code only. Size L · Removes ~1.7k (unwired V2) or ~1k (legacy) + matching port versions.
    • Assumption/Counter: adopters start from an empty DB / README treats "implemented-candidate" as deliberate staging.
  5. [Required][duplication] Mongo reactive twin stack — excluded from the jar, already diverged once — MONGO/reactive/**, MONGO/transaction/*Reactive*, MONGO/transaction/session/ReactiveMongoCausalSessionExecutor.java, MONGO/changestream/**

    • Evidence: executor, consistency binder, scoped operations, collection access, transaction executor, session factory, causal session each exist twice; ~2.7k lines / 30 files touch reactor; app-bootstrap/build.gradle:129-135 excludes the reactive starter ("kept for a future promotion"); ReactiveMongoConsistencyBinder Javadoc: "The imperative binder was given this contract and the reactive one was not."
    • Remedy: delete the reactive half and change streams (first-pass change-stream defects go with it). Size L · Removes ~4k lines, reactor-test, reactive starter.
  6. [Required][duplication] Owner-lease claim mechanics copy-pasted across PostgreSQL stores — JPA/postgresql/inbox/PostgreSqlSameStoreInboxAdapter.java:223-277 vs PostgreSqlOwnerSafeIdempotencyStore.java:120-170

    • Evidence: same claim decision sequence; digestFields identical twice (inbox:559, PostgreSqlPollingDeliveryAdapter.java:523); write-tx guard 4× (inbox:501, polling:487, PostgreSqlImmutableOutboxAppendAdapter.java:336, IdempotencyCapabilityGuard.java:93); capability_schema_registry check 6× (4 stores + NotificationSchemaActivation + FS/FileserverSchemaActivation.java) — copies disagree (= 2 vs >= 2; only 2 of 6 handle an unreadable registry); only idempotency was split into collaborators.
    • Remedy: package-private PostgreSqlStoreSupport (write-tx guard, capability check, db now, owner token, digest) + CapabilitySchemaRequirement record; fold in first-pass E-3 guard for outbox/operation/liveevent. Size M · Removes ~200 lines, 5 SQL copies.
  7. [Required][reachability] JPA platform library outside the supported surface — docs/architecture/jpa-adopter-api-surface.txt (20 types) vs jpa-api-surface.txt (311)

    • Evidence: types referenced by composition/sample match the 20-type list exactly. Outside it and unused beyond the leaf: springdata (1.0k), hibernate.batch/bulk/stateless (0.8k), postgresql.{copy,json,range,write,array,lock} (1.8k), api.query (0.4k), envers/querydsl/cache (0.6k), experimental (1.5k). 8 single-impl interfaces without test/outside reference: JpaBatchExecutor, BulkDmlExecutor, StatelessSessionRunner, PostgreSqlCopyLoader, PostgreSqlUpsertExecutor, WorkClaimExecutor, EnversHistoryReader, JpaTransactionExecutor. postgresql/lock/PostgreSqlWorkClaimExecutor (generic SKIP LOCKED claimer) has 0 callers while 6 places hand-write SKIP LOCKED (PostgreSqlOutboxClaimRepository, PostgreSqlPollingDeliveryAdapter, RecipientClaimSql, JpaRecipientLeaseStore, JdbcReconciliationJobStore, DurableOperationJpaRepository).
    • Remedy: shrink to supported surface + what stores use. Size L · Removes ~6–7k lines.
    • Counter: design doc describes "18 Stable modules" — but the leaf's own surface file says public implementation types are not compatibility promises.
  8. [Consider][structure] Three wiring styles, stale rationale — JPA/config/JpaAdapterComponentsConfig.java, JPA/notification/configuration/NotificationJpaPersistenceFacade.java, FS/FileserverJpaPersistenceConfig.java (scanned stereotypes with per-class conditions / explicit facades / "deliberately no stereotype" classes nothing constructs; the paragraph "Both composition roots component-scan dev.caskeleton.adapter" in 4 classes + CandidateAdapterCompositionTest.java:18 is false — CaSkeletonApplication.java:106 excludes adapter.outbound.persistence..*; fileserver repeats its gate 10×; Mongo repeats enabled 8×). Remedy: explicit @Bean wiring per feature config only; drop per-class stereotypes/conditions, stale paragraphs, candidate test. Size M.

  9. [Consider][structure] Features scattered by vendor; two unrelated "inbox" packages — outbox over 5 Java locations (outbox/, outbox/entity/, postgresql/PostgreSqlOutboxClaimRepository.java, postgresql/outbox/, h2/H2OutboxClaimRepository.java) and 3 migration dirs; idempotency over 6 locations; postgresql/inbox (message dedupe, application.inbox) vs notification/platform/inbox (user inbox). Remedy: package by feature (outbox/{jpa,postgresql,h2}), rename the first to messageinbox. Size M (moves).

  10. [Consider][over-abstraction] Promotion/benchmark gates on the production classpath — JPA experimental/next/* (186); Mongo advanced/MongoAdvancedPromotionGate.java (incl. addsStarterDependency() { return false; } :41-46), MongoAdvancedPromotionEvidence, MongoVectorSearchBenchmarkGate, MongoSearchReadinessGate — test-only, parallel designs; Mongo CLAUDE.md already moved release gating to the testkit. Remedy: testkit or delete. Size S · ~450 lines.

  11. [Consider][structure] Fileserver extraction left its tests behind — persistence-jpa/build.gradle:86-87 (4 fileserver ITs in jpa's postgresqlIntegrationTest; FS/JpaFileQuotaService.reservedBytes/committedBytes public only for them; leaf has no CLAUDE.md/README; removing fileserver means editing jpa). Remedy: own IT source set via testFixtures(project(':adapter:outbound:persistence-jpa')) + short CLAUDE.md. Size M.

  12. [Consider][readability] Javadoc tells history — comment lines 21% of JPA main, 28% of Mongo main; ~90 files with "used to", "until now", "nothing registered", "documented as registered and never was"; worst: JpaAdapterComponentsConfig.java (52 comment vs 13 code lines), MongoPlatformAutoConfiguration.java:140-145,176-180,322-325,410-412,431-434, MongoRootAutoConfiguration, PostgreSqlPersistenceConfig.java, PersistenceJpaConfig.java:90, MongoAdvancedPromotionGate.java:28-30 (MNG-008). Remedy: 1–2 lines of invariant, history to git/ADR. Size M.

  13. [Nit][readability] JpaTransactionAutoConfiguration.java:40 is a plain factory instantiated twice (PersistenceJpaRuntimeConfig.java:58,70); new JpaTransactionSettings(null ×9) at SpringTransactionPort.java:42,53 despite defaultSettings() at :221; 36 port implementations use 7 naming conventions (*StoreAdapter, *Adapter, Jpa*Store, Jdbc*, PostgreSql*Store, port-like SpringTransactionPort/DomainContextAuditContextPort, JpaFileQuotaService). Remedy: inline factory, JpaTransactionSettings.defaults(), <Tech><Port> naming.

  14. [Nit][docs] jpa CLAUDE.md "NoSQL extension rule" (:306-316) says create a Mongo leaf (exists); MapStruct section (:281-304) for an unused tool; jpa-adopter-api-surface.txt:11 lists moved FileserverSchemaActivation; Mongo CLAUDE.md :157 MongoAdvancedProperties (class is MongoAdvancedSettings); JpaAdapterComponentsConfig {@link} into a leaf not on its classpath.

Cross-module leads (not investigated)

  • application-core port versions IdempotencyStorePort/V2, OutboxAppendPort/LegacyOutboxAppendPort/OutboxAppendPortV2, OutboxStorePort/OutboxPollingDeliveryPortV2 are the root cause of #4.
  • Idempotency claim decision table duplicated in cache-redis RedisIdempotencyStoreAdapter and PostgreSqlOwnerSafeIdempotencyStore.claim → one pure function in application-core.
  • Signed cursor codecs ×4: jpa SignedJsonCursorCodec, mongo MongoKeysetCursorCodec, web CursorCodec/WebCursorKeyRing, graphql HmacGraphQlCursorCodec.
  • Failure hierarchies ×3: jpa api/error (23 types), mongo api/error (25), shared-contract PersistenceFailureException.
  • sample-portfolio/.../SamplePostgreSqlPersistenceConfig.java:71-78 redeclares claim-repository beans of PostgreSqlPersistenceConfig.
  • JPA wiring split between the leaf's PersistenceJpaRuntimeConfig and bootstrap's JpaPlatformAutoConfiguration/JpaPlatformRuntimeAutoConfiguration.

Coverage note

Reachability computed from auto-config entry points, scanned stereotypes and types referenced by composition/sample main code (imports, same-package names, FQNs; strings/reflection not tracked → approximate). Read in full: wiring/config of all three leaves, claim/helper paths of the 4 PostgreSQL stores, transaction wiring, each CLAUDE.md. Not in depth: notification store internals, Mongo schema/migration/query internals.

S3 — Redis와 outbound HTTP client

Leaf별 유지보수성 판정

leaf main LOC 판정 한 줄 사유
redis-runtime 7,306 OVERBUILT 약 절반이 redis-sdk 전용: gateway 118개 메서드 중 약 110개, lane 6개 중 4개, raw/admin/pubsub 역할, SDK 설정 섹션
redis-sdk 21,724 OVERBUILT 내부는 정돈(sync/reactive가 *OperationRequests 3.3k 공유)되어 있으나 명령 하나 추가에 leaf 3개·약 10개 파일 수정, 소비자 없음
cache-redis 4,574 NEEDS_WORK capability별 패키지는 좋음. "lease 빌림 → 대기 → 실패 분류" 틀이 15곳에 복사되어 이미 달라짐
httpclient 16,828 NEEDS_WORK autoconfig·패키지 분리는 좋음. blocking/reactive가 사실상 두 벌(동일 코드 약 675줄), 진입점 6개가 호출 파이프라인을 각자 조립

Findings (영향 큰 순)

  1. [Required][duplication] httpclient blocking/reactive 병렬 스택이 이미 갈라짐 — src/adapter/outbound/httpclient/.../restclient/DefaultGenericHttpGateway.java ↔ .../webclient/DefaultReactiveHttpGateway.java 외 14쌍

    • 근거: 짝 15개(약 3.1k줄 대 약 3.0k줄), 이름만 바꾸면 같은 줄 약 675줄. BlockingClientRuntime↔ReactiveClientRuntime 86%, RestClientRuntimeFactory↔WebClientRuntimeFactory 80%, DefaultHttpServiceRegistry↔DefaultReactiveHttpServiceRegistry 80%, KernelHttpExchangeAdapter↔ReactiveKernelHttpExchangeAdapter 102줄 동일. 이미 갈라진 곳(1차 categoryOf 외): 401 credential refresh가 blocking에만 있음(DefaultGenericHttpGateway.java:213-225 vs reactive :314 false 고정); AttemptBudgetCalculator 생성 방식 상이(:194 vs :275); reactive firstByteDelivered false 고정(ReactiveAttemptExecutor.java:157,164,172); withCredentialQuery 수정이 한쪽 먼저(주석 ReactiveAttemptExecutor.java:206); reactive runtime이 BlockingExecutionSupport 반환(ReactiveClientRuntime.java:117).
    • Remedy: Template Method — AbstractLogicalCall(context/finish/ambiguous/retryExhausted/onRetryGranted/credentialRequest + attempt guard; RetryContext 17-arg 생성 한 곳), AttemptCore(observation, mapResponse, mapFailure, credential 병합), 공통 필드는 ClientRuntime으로, permit 획득을 Permits acquire() 하나로(AttemptResiliencePipeline.java:69-86 = ReactiveAttemptResiliencePipeline.java:50-70), registry·kernel adapter는 요청 매핑 static helper 공유. Size L · Removes 약 600~700줄, "두 번 고치기" 제거.
    • 가정/반론: Mono와 동기 흐름을 한 추상화에 억지로 넣으면 읽기 어려움 → 합치는 범위는 순수 함수(매핑, 컨텍스트 생성)와 permit 획득까지, 재시도 루프(sleep vs Mono.delay)는 두 벌 유지.
  2. [Required][duplication/structure] 진입점 6개가 호출 파이프라인을 각자 조립, 적용 단계가 제각각

    • 근거: lease → metadata → prepare → admission → deadline → credential → observation을 각자 손으로 조립. Generic/Reactive와 BlockingStreamingGateway는 admission·deadline·credential 모두 O; DefaultReactiveSseGateway는 credential만; DefaultDynamicTargetGateway는 자체 binding; ReactiveStreamingGateway.java:50-107은 셋 다 X. BlockingStreamingGateway.java:63-68 주석은 이 누락을 버그로 적고 고쳤는데 reactive streaming은 그대로 → 인증 profile에서 streaming 요청이 credential 없이 나갈 수 있음(동작 테스트로 확인 필요, correctness backlog).
    • Remedy: CallSetup.prepare(lease, operation)이 metadata/prepared/deadline/admission/credentials 반환, 진입점은 전송 방식만 다르게 + 명시적 opt-out. Size M · Removes 약 150줄, 공통 단계 추가 시 1곳 수정.
    • 가정/반론: streaming에서 retry 없음은 의도 → 공통 범위는 retry 이전 단계까지.
  3. [Required][over-abstraction] 118개 메서드 RedisCommandGateway는 template에 불필요 — src/adapter/outbound/redis-runtime/.../lettuce/operations/RedisCommandGateway.java(1227), LettuceRedisCommandGateway.java(1282)

    • 근거: 배선된 semantic adapter·health가 쓰는 메서드 8개(get, set, getAndDelete, incrementBy, loadScript, evaluateRegisteredForList, evaluateRegisteredForLong, ping), 죽은 realtime이 11개, 나머지 약 99개는 redis-sdk 전용. production lane은 REGULAR/SCRIPT뿐(BLOCKING/TRANSACTION/PUBSUB/ADMIN은 RedisSdkAutoConfiguration.java:277-282 한도 설정에만). runtime이 SDK 개념에 역의존: RedisConnectionKind.forCommand(RedisCommandDescriptor)(호출자 SDK CommandPolicyGuard.java:104), sendApprovedRaw/sendAdminDiagnostic/sendExtension(:1107-1134). RedisSdkSettings의 Limits/Blocking/Transaction/PubSub/Advanced/Raw/Admin 섹션 약 350줄도 SDK용. production 클래스가 Sdk 이름·...redis.sdk 패키지를 쓰고 redis-sdk와 split package 9개 공유.
    • Remedy: 8개 메서드 SemanticRedisCommands(fake용 인터페이스는 유지), lane 2개, 역할 APPLICATION/ADVANCED만, RedisRuntimeSettings로 개명, ...redis.runtime.* 패키지. Size L(대부분 삭제) · Removes 약 4k/7.3k줄 + 2,481줄 test fake 축소.
    • 가정/반론: redis-sdk 유지 결정 시 잘라낸 메서드는 redis-sdk 확장 인터페이스로 이동. runtime 계약은 어느 경우든 8개로.
  4. [Required][duplication] cache-redis "lease 빌림 → .get(timeout) → 예외 처리" 틀 15곳 복사, 이미 달라짐 — idempotency 6, lease 4, cache 4, rate-limit 1 (+probe 1, realtime 5)

    • 근거: try (borrow) {...get(..NANOSECONDS)} catch Interrupted catch Exception 반복. RedisOperationException.metadata().ambiguousExecution()로 "안 보냄/보냈는지 모름" 구분하는 곳은 rate-limit뿐(RedisEdgeRateLimitAdapter.java:123-131); 나머지 셋은 lane 거절도 Indeterminate(1차 #1 부수 증상과 같은 원인). Lua 응답 디코더 3벌: IdempotencyScripts.java:286-300, RateLimitScripts.java:275-285, LeaseScripts.java:169-185.
    • Remedy: SemanticRedisCall.run(kind, capability, op, gw -> stage, onReply, onFailure(NOT_SENT|AMBIGUOUS|INTERRUPTED)) + 1차 #8의 RegisteredLuaScript에 reply 디코딩까지. Size M · Removes 약 180줄.
    • 가정/반론: capability마다 fallback이 다름 → fallback은 호출자, 분류만 공통.
  5. [Consider][pattern] RedisIdempotencyStoreAdapter.transition 파라미터 15개(outcome enum 7개), complete/markFailed/releaseBeforeExecution은 이를 안 쓰고 재구현 — :420-481, :212-252, :270-306, :311-338 (같은 status 문자열 위 switch 5개). Remedy: IdempotencyScripts.Reply에서 enum ScriptStatus로 한 번 파싱, 호출부는 Map<ScriptStatus,O>. Size M · Removes 약 120줄(#4와 합치면 534 → 약 300줄). 반론: 명시적 switch가 리뷰 쉬움 — 단 5벌이 이미 서로 다른 default.

  6. [Consider][over-abstraction] 대체 불가능한 확장 지점 — HttpClientObservationAutoConfiguration.java:23-35 (@ConditionalOnMissingBean HttpClientTagPolicy 소비처 없음; BlockingExecutionSupport.standard()가 HttpClientTagPolicy.standard()를 다시 만들어(BlockingExecutionSupport.java:77) override 무효; BlockingExecutionSupport는 구성요소 19개 묶음, 11개가 상태 없는 new X()). Remedy: bean 삭제 또는 support에 주입, ExecutionSupport로 개명. Size S.

  7. [Consider][over-abstraction] 구현 1개짜리 인터페이스(테스트 대역 없음) — RetryCoordinator(참조 0), RetryEligibilityEngine/Default…, ExecutionEvidenceClassifier/Default…, BackoffStrategy/ExponentialFullJitterBackoff(테스트도 Default* 직접 생성). Remedy: 인터페이스 삭제·구현체 개명. Size S · 개념 4개 제거. 반론: design 문서가 SPI로 기재 — 교체 소비자 없음.

  8. [Consider][reachability] httpclient에서 HttpClientPlatformAutoConfiguration으로 도달 불가 약 820줄 — BoundedErrorBody(54줄, main·test 참조 0 → 즉시 삭제), MultipartReplayability, SafeHttpLogEvent, spring7/*(107), migration/*(164)는 테스트만 참조, http3/*(392, Experimental, compileOnly Jetty + 별도 lane). Remedy: http3만 유지, 나머지 삭제 또는 docs로. Size S~M.

  9. [Consider][SRP] RedisTopologyClientFactory(662줄) 역할 과다 — URI/TLS/ClientOptions factory + RuntimeClient 구현 3개(:427 Standalone, :475 Cluster, :551 RoleRouting) + 참조 카운트(SharedClientResources :382) + ShutdownBudget. Remedy: 구현 3개를 package-private top-level로 이동(이동만). Size M · 파일 약 350줄로.

  10. [Consider][duplication] settings → profile 필드 단위 복사 — HttpClientProfileFactory.java:40-153 (Pool 11, Timeout 9, Tls 8 필드…; valueOf(x.toUpperCase()) 8번). Remedy: settings 필드를 enum 타입으로(binder가 대소문자 무시 변환). Size S. 반론: @DefaultValue가 Spring 타입이라 profile 레코드 직접 바인딩 불가 — 복사 구조 자체는 정당.

  11. [Nit][readability] 이력 서술 주석 — httpclient "used to/no longer" 27곳(ProtocolEvidenceReader.java:8, HttpClientTransportAutoConfiguration.java:66, BlockingStreamingGateway.java:63), RedisCapabilityConfig.java:30-33 "376 lines … (BOOT-007)", CapabilityKeyspace.java:11, redis leaf 23곳; 인라인 FQN 약 160줄(HttpMethod/HttpStatus 충돌만 정당; RedisKeys.java:37-80 javax.crypto, RedisIdempotencyStoreAdapter.java:435, ReactiveAttemptExecutor.java:208-213). Remedy: 불변 조건만 남기고 이력은 git/ADR로.

  12. [Nit][structure] cache-redis 세부 — CacheKeys가 가변 generation 상태 보유(RedisCacheRegionAdapter.java:421-450) → RegionGeneration 분리; HMAC KeyDigest가 설정 패키지(capability/RedisKeys.java)에 있고 RedisNamespace.prefix() 대신 env:service:domain 재조립; cache-redis/CLAUDE.md의 "legacy cache router" 존재하지 않음.

  13. [Nit] 기타 — Jackson 2 사용 main 파일은 RemoteProblemDecoder 하나(build.gradle:58-66 주석은 "two files") → Jackson 3로 옮기면 의존성 1개 감소; "runtime draining"·"retry budget exhausted"를 HttpRateLimitRejectedException으로 던짐(DefaultGenericHttpGateway.java:182,280, reactive :265,351) → 텔레메트리 카테고리 오기; RedisSdkAutoConfiguration.java:297-338 health indicator 둘은 DOWN 값만 달라 하나로.

Cross-module leads (조사 안 함)

  • RedisSdkAutoConfiguration.RedisSecretSource + System.getenv fallback(:213-217,375) vs SecretSourcePort(RedisCapabilityConfig.java:68); httpclient는 port 직접.
  • HttpClientEnvironmentKeys(179줄, 리플렉션 env 이름 파생) vs support StrictSettingsBinder.
  • TLS material 로딩: RedisTopologyClientFactory.java:327-380, RedisSdkAutoConfiguration.java:253 vs httpclient/security/TlsMaterialProvider.java.
  • ca-skeleton.capabilities.* selector 문자열이 bootstrap/persistence-jpa/redis main 16개 파일에 흩어짐(RedisCorrectnessRoles.java 포함).
  • secret://<source>/<name> 파싱(RedisKeys.java)의 다른 leaf 존재 여부.

Coverage note

깊게: httpclient gateway·executor·resilience·runtime·support·autoconfig, cache-redis main 전체, redis-runtime gateway 사용처·lane·settings·autoconfig·topology. 훑음: redis-sdk(구조·크기), httpclient profile/security/dynamic. 수치는 grep·정규화 diff 추정. #2 reactive streaming credential 누락은 동작 테스트로 확인 필요.

S4 — 그 밖의 outbound capability adapter

Leaf별 유지보수성 판정

leaf main LOC 판정 한 줄 이유
adapter/outbound/notification 13,512 OVERBUILT provider 7종 중 조립되는 건 SES·SMTP 2종. 나머지 5종 약 2.75k줄은 테스트에서만 생성
adapter/outbound/fileserver 14,230 OVERBUILT 루트 패키지 8.7k줄(R1/R2 publication)의 port 호출처 0. platform/**와 코드 공유 없는 별도 제품
adapter/outbound/objectstorage 14,478 OVERBUILT legacy/신규 두 세대 공존. legacy adoption은 SPI 구현체가 없어 켜면 기동 실패. direct/multipart는 1차 D#7
adapter/outbound/messaging 4,249 OVERBUILT 79%(3.36k줄)가 연결되지 않은 R1 compiler/encoder
adapter/outbound/messaging-kafka 367 HEALTHY 작은 R0 seam
adapter/outbound/support 279 HEALTHY 결함은 1차에서 다룸
adapter/outbound/identifier 83 HEALTHY UuidCodec은 1차에서 다룸

Findings (영향 큰 순)

  1. [Required][reachability/structure] fileserver 루트 패키지 publication 제품군(R1+R2) 호출처 없음 — src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/*.java (31파일, 8,659줄)

    • 근거: main에서 FilePublicationPort/FileExportPort를 쓰는 곳은 이 leaf와 application-core뿐(sample·composition·bootstrap 0). FileserverR2Config.java:20-23은 component scan으로, FileExportConfig.java:23,49는 bean 등록. 루트 패키지와 platform/**는 서로 import 0. leaf 안에 FilePublicationPort 계열 구현 3개(FilesystemCsvExportAdapter, LocalFilePublicationAdapter, R2 provider).
    • Remedy: 삭제. 유지 결정이면 별도 optional leaf로 추출. Size L · Removes 약 8.7k줄, 설정 네임스페이스 2개(app.fileserver.*, app.file-export.*), FileserverActivationValidator.
    • 가정/반론: 어떤 fork도 R2 publication을 안 씀 / CLAUDE.md가 "first qualified R2 provider"로 공개 API 취급.
  2. [Required][reachability] messaging R1 compiler/encoder 체인 미연결 — src/adapter/outbound/messaging/.../envelope(1,573) + contract(628) + destination(723) + config(439)

    • 근거: 진입점 JsonSchemaIntegrationEventEncoder가 main에 나오는 곳은 app-bootstrap/.../OutboxCanonicalTransportRequirementValidator.java:55의 에러 메시지 문자열뿐; CompiledMessagingDescriptor main 참조 0; CLAUDE.md "R1 compiler is intentionally not wired". 그런데 NetworkNT validator가 runtime 의존성(implementation(libs.json.schema.validator)), schema 리소스 9개·YAML 배제 정책 유지. realtime/MessagingDurableFanoutAdapter(+RealtimeFanoutEnvelopeJson, 138줄)는 생성처·테스트 0. leaf에 R0 legacy(MessageBroker)·R1(미연결)·canonical bridge 세 세대 공존.
    • Remedy: R1 체인·realtime fanout 삭제(evidence 생성에 필요하면 qualification source set으로). Size L · Removes 약 3.5k줄 + runtime 의존성 1개.
    • 가정/반론: R1 encoder는 canonical bridge(vendored messaging-schema-*)로 대체됨 / R2 qualification evidence가 사용 — 그래도 test 전용이면 충분.
  3. [Required][reachability] notification provider 5종 미조립, 확장 슬롯도 비어 있음 — .../platform/provider/{apns,fcm,twilio,webpush,webhook} (2,750줄)

    • 근거: ProviderRuntimeAssembler 구현은 SesProviderRuntimeAssembler.java:28, SmtpProviderRuntimeAssembler.java:48 2개; ProviderCallbackAssembler는 SES 1개; 둘 다 AssembledProvider.dispatchOnly 반환(:98, :112) → projector/reconciliation 슬롯·MapProviderEventProjectorRegistry·CapabilityReconciliationGateway에 production 입력 없음. 참조 0: SesDeliveryProjector, TwilioDeliveryProjector, SesSuppressionUpdater, FcmContactPointUpdater, TwilioReconciliationCapability. 자격증명 회전 경로(ProviderRuntimeRotator, RuntimeDrainCoordinator, CredentialProbe 구현 0) 미연결. 설정 문서는 7종 모두 유효값으로 기재(docs/notification/configuration-reference.md:64); Provider.validate는 APNs topic·VAPID·Twilio secret까지 검사 후 NotificationProviderAssembly.java:141-143에서 "missing assembler"로 실패.
    • 1차 B#2 보정: B#2는 위조 callback이 SesSuppressionUpdater로 suppression을 만든다고 적었으나 이 클래스는 참조 0 → 그 영향 서술은 과장(서명 우회 자체는 유효).
    • Remedy: 5종을 extension source set/sample로 이동 또는 삭제; ProviderType을 SES/SMTP로; 빈 projector/reconciliation 슬롯 제거. Size L · Removes 약 3.0k줄, 개념 6개.
    • 가정/반론: support-matrix가 "contract implemented / unqualified"로 광고 — 계약 보존이 목적이면 이동이 맞음.
  4. [Required][duplication(어긋남)] SMTP capability 두 곳에 서로 다른 값 — SmtpProviderRuntimeAssembler.java:138-152 vs SmtpNotificationProviderAdapter.java:75-76 (maxPayload 26,214,400 vs 25,000,000; TTL 24h vs 1d; assembler는 자기 사본(:126), SES assembler는 adapter.capabilities()(SesProviderRuntimeAssembler.java:95); 11개 위치 인자 new ProviderCapabilities(false,false,…) 8곳). Remedy: 사본 삭제·adapter.capabilities() 사용, named factory(application-notification record라 cross-leaf). Size S.

  5. [Required][SRP] LocalPersistentControlPlane 7가지 일 — .../fileserver/LocalPersistentControlPlane.java (1,470줄; #1에서 유지할 때만)

    • ① 레코드 repository(:176-352, :728-790) ② 상태 전이표(validateOperationTransition, isAllowedAdjacentTransition :499-592) ③ 2단 lock manager(static stripe, FileLock, ThreadLocal 재진입, static POISONED_OPERATION_LOCK_ROOTS :40-46, :205-268, :1377-1449) ④ durable write 프로토콜(temp→force→replace→read-back→repair :352-497) ⑤ 보안 디렉터리 syscall facade SystemSecureRecordOperations(:1036-1272) ⑥ fault-injection 타입 7개 + test 생성자·factory 6개(:62-147, :1273-1376) ⑦ R1 호환 decode(:1318).
    • Remedy: 전이표 → DurablePublicationRecord.State.canAdvanceTo()(objectstorage는 이미 ObjectOperationStateMachine으로 분리); 나머지 OperationLockManager, DurableRecordFile, 얇은 repository로. Size L · 한 번 수정 시 읽을 범위 1.4k → 약 300줄.
  6. [Required][duplication(어긋남)] "attested root 아래 private shard" 구현 3벌 — LocalPersistentControlPlane.java:668-715 / LocalPersistentPayloadOperations.java:356-406,607-700,780-1064 / LocalPersistentRootAttestor.java:662-773 (각자 FaultCallback, IdentityVerifier, FailureKind, 예외, SecureShard/ShardAttributes, System* facade 약 550줄; 검증도 다름 — control은 symlink·Files.getFileStore, payload는 fileKey 공백·store 이름; forceDirectory 3곳(:808, LocalPublicationJournal.java:209, LocalFilePublicationAdapter.java:338), MessageDigest.getInstance 7개 파일). Remedy: package-private AttestedDirectory 하나 + System 구현 1 + fault test double 1. Size M · Removes 약 400줄, seam 인터페이스 9개. 반론: crash qualification 테스트가 FaultPoint에 묶여 이전 비용 큼.

  7. [Required][duplication(어긋남)] 손으로 만든 flat JSON parser 2개 — FileserverControlRecordCodec.java:655-855 vs LocalPublicationJournalCodec.java:110-266 (control은 엄격한 decodeUtf8, journal은 new String(bytes, UTF_8)로 잘못된 byte를 대체 문자로 조용히 변환; 빈 객체·쉼표 루프 상이). Remedy: FlatCanonicalJson 하나. Size S · 약 120줄. 반론: R1 journal은 읽기 전용 호환이라 관대 decode 의도 — 그렇다면 한 줄 명시.

  8. [Consider][Value Object] 원시 String 검증 73곳 — FileserverControlRecordCodec.java:463-558(codec이 validator 13개 겸함), FileserverR2Validation.java:36-125 (requireText 22, requireDigest 12, requireFileId 8; requireDigest(value, field)와 requireSha256(label, value)는 인자 순서만 다른 중복). Remedy: Sha256Hex, FileId, RouteToken, SafeSegment record. Size M.

  9. [Consider][pattern] notification provider 공통 템플릿은 절반만 있음 — 공유: ProviderResults, NotificationHttpGateway. HTTP adapter 5개가 각자 재구현: completedFuture(send), nanoTime, protector.reveal(AccessContext.dispatch), request map, exchange, 2xx→accepted 아니면 rejected(classifier.classify), transport catch(ApnsNotificationProviderAdapter.java:74-100, SesNotificationProviderAdapter.java:105, TwilioSmsProviderAdapter.java:76-126, WebPushNotificationProviderAdapter.java:80, WebhookNotificationProviderAdapter.java:107); classifier가 new ProviderFailure(…5인자) 18회. callback SPI는 있고 구현은 SES·Twilio(미연결). Remedy: #3 적용 시 HTTP provider는 SES 하나라 불필요; 3개 이상 유지 시 HttpProviderSend.run(...) helper + ProviderResults.failure(code, category, reason) factory(success mapper 인자). Size M · 약 150줄.

  10. [Consider][reachability] objectstorage legacy adoption은 켜면 기동 실패 — .../maintenance/*(609줄), config/ObjectStorageLegacyMigrationConfig.java, LegacyObjectAdoptionSettings (LegacyObjectInspector, LegacyAdoptionApprovalReplayStore 구현체 없음; Ed25519LegacyAdoptionApprovalVerifier main 참조 0; readiness ObjectStorageCapabilityEvidence/Card(112줄) 테스트 전용; control/ObjectControlRecordEnvelope 참조 0). Remedy: 삭제 또는 별도 migration 도구. Size M · 약 800줄. 반론: fork가 구현을 공급하는 SPI일 수 있음 → 그렇다면 README에 필수 bean 명시.

  11. [Consider][structure] objectstorage 세대 구분·패키지 위치 불명확 — 루트 ObjectStorageConfig.java, config/RoutingObjectMutationAdapter.java:52-57,96-170,273-406 (legacy(ObjectStoragePort, 동기 S3Client)와 신규(S3AsyncClient+netty)가 코드 공유 없이 공존; port 구현 4개가 config/; managed publish(약 230줄)는 router inline, staged는 kernel/ → 비대칭). Remedy: legacy → legacy/, Routing*Adapter → routing/, kernel/ManagedObjectPublicationKernel 추출. Size M. sample이 legacy 기본 사용 → legacy 삭제는 sample 이전 후.

  12. [Consider][over-abstraction] SelectedObjectStorageProviderFactory는 factory가 아님 — telescoping 생성자 4개, Object 슬롯 3개를 Class<T> cast로 꺼내는 type-unsafe service locator(슬롯은 미연결 direct/multipart 전용). Remedy: record ProviderInstance(ObjectStorageProvider, ObjectControlStore, Runnable close). Size S · 약 70줄.

  13. [Consider][over-abstraction] provider 1개인데 fileserver R2 routing 계층 — RoutingFilePublicationAdapter, FilePublicationProvider(구현 1), LocalPersistentPublicationProvider.java:60-86(destination마다 넘긴 뒤 "전부 같은 인스턴스인지" 재검증). Remedy: provider가 (controlPlane, payload, Map<id, CompiledFileDestination>)를 받게 하고 router·interface 삭제. Size S.

  14. [Consider][State 전이표] ProviderRuntime 상태 전이가 7개 메서드에 흩어짐 — ProviderRuntime.java:127-241, RegistryProviderRuntimeControl.java:30-45 (markAuthenticationFailed만 무조건 set → DISABLED·DRAINING도 덮어씀). Remedy: EnumMap<State, Set<State>> + transition(target, reason). Size S · 약 70줄.

  15. [Consider][readability] Settings가 모든 provider 필드를 한 record에 — NotificationPlatformSettings.java:209-256,280 (switch (resolved.name()) 문자열 분기, 테스트 호환용 11-인자 오버로드). Remedy: enum switch, #3과 함께 미조립 provider 필드 제거. Size S.

  16. [Nit][readability] 이력 서술 주석 notification 56건·fileserver 18건(예: ProviderType.java:10-19, 예외 메시지 :85 "used to bind successfully…", MapProviderCallbackAdapterRegistry.java:10-15, AesGcmCallbackPayloadProtection.java:11-15); objectstorage main inline FQN 84줄(RoutingObjectMutationAdapter.java:74,80, ObjectStorageConfig.java @Conditional) — objectstorage CLAUDE에 금지 규칙 없음.

  17. [Nit][structure] 용어 혼재 — fileserver 한 leaf 안에서 루트는 *Config, platform은 *Configuration; notification *ProviderProperties 7개는 @ConfigurationProperties가 아닌 파생 값 → *ProviderProfile; 클래스 이름의 버전 라벨(FileserverR2Config, R2PublishedReferenceCodec).

Cross-module leads (조사 안 함)

  • 손으로 만든 canonical JSON codec이 3개 leaf에: fileserver 2벌, objectstorage control/CanonicalJsonReader/Writer, messaging DeterministicEnvelopeWriter.
  • 로컬 보안 파일시스템 primitive 중복: fileserver LocalPersistent*·platform/local/SafeFileChannelFactory·SecureDirectoryWalk vs objectstorage LocalObjectPathGuard·LocalDev*Store.
  • notification JdkNotificationHttpGateway·AwsSignatureV4Signer vs adapter:outbound:httpclient + objectstorage의 AWS SDK.
  • adapter LocalJsonSchemaRegistry vs vendored messaging-schema-json; adapter:outbound:messaging-kafka vs vendored messaging/messaging-kafka.
  • ProviderCapabilities(application-notification) 11개 위치 인자 → named factory.

Coverage note

구조: fileserver 루트 대형 파일 5개 outline·핵심 구간, notification provider/assembly/runtime, objectstorage config/kernel/maintenance/readiness, 네 leaf 전체 타입의 main 참조 grep(.imports/spring.factories 확인, 문자열·reflection wiring은 grep 한계). 얕게: notification template/security/observation, fileserver platform/local, objectstorage s3/*.

S5 — Inbound HTTP / GraphQL

Leaf별 유지보수성 판정

leaf main LOC 판정 이유
src/adapter/inbound/web 23,095 (340 파일) OVERBUILT servlet 진입점에서 닿는 코드 155/340 파일, 9.8k/23.1k LOC. 관심사마다 구현 두 벌. WebFlux 쪽은 어떤 조합으로도 안 켜짐
src/adapter/inbound/web-fileserver 3,976 (62 파일) NEEDS_WORK 전부 도달하나 reactive 907줄은 안 켜짐; 별도 problem+json 형식; 업로드 정책이 4개 transport에 복사; leaf 문서 없음
src/adapter/inbound/graphql 25,984 (400 파일) OVERBUILT 도달 136/400(1차와 같음). 배선된 코어는 정리됐으나 에러 진입점 우회, autoconfig 706줄, 부팅마다 reflection 아키텍처 검사

발견 (효과 큰 순)

  1. [Required][duplication] HTTP 에러 어휘가 web+fileserver 안에 3개, 이미 갈라짐 — web/.../error/ClientSafeValidationDetails.java:18-43 외

    • 응답 형식 3개·코드 체계 4개: Envelope(GlobalExceptionHandler, AuthErrorResponseWriter, RateLimitInterceptor; 코드 OperationalError, RateLimitTransportError); WebProblem(ProblemCode enum, ProblemCatalog.standard() ProblemCatalog.java:51-162, problem-catalog.yaml이 같은 목록 세 벌; MVC/WebFlux problem handler, ThrottleProblemWriter, BudgetProblemMapper, WebMvcBudgetExceptionHandler); FileserverProblem(필드 15개 problem+json, FileserverExceptionHandler.java:24-40).
    • 갈라짐 1 — 검증 규칙표 두 벌: ClientSafeValidationDetails(NotNull→NOT_NULL, 고정 문구, 점 경로) vs validation/WebValidationIssueMapper.java:56-86(must-not-be-null, 치환된 메시지를 그대로 노출(${만 거름), RFC 6901 pointer) → README "치환 메시지 미노출" 규칙을 한쪽만 지킴.
    • 갈라짐 2 — 운영은 spring.mvc.problemdetails.enabled=false(app-bootstrap/.../application.yml:17-22)라 WebProblem은 fixture(ContractFixtureApplication.java:35-40)에서만; 반대로 fileserver는 D5(ProblemDetail 거부)와 달리 운영에서 problem+json을 보내는데 FileserverErrorCode는 이미 ApiErrorCode 구현.
    • 조치: HTTP 에러 형식을 Envelope 하나로; WebProblem 어휘(yaml, 핸들러 2, writer 3 포함) 삭제 또는 testFixtures로; fileserver는 ErrorResponseFactory.envelope(code,…, details)(프로토콜이 요구하는 Draft12OffsetProblem만 유지); 검증 규칙표 하나로. 규모 L · 약 1.3k LOC, 응답 형식 2개, 코드 체계 1개 제거.
    • 가정/반론: fileserver 클라이언트가 problem+json 의존 가능 / 템플릿이라 외부 소비자가 없는 지금이 가장 쌈.
  2. [Required][reachability/duplication] WebFlux 쌍둥이 코드는 어떤 조합에서도 안 켜짐 — web/build.gradle:26, web-fileserver/build.gradle:27

    • 근거: 두 leaf 모두 implementation spring-boot-starter-web → 소비자 classpath에 DispatcherServlet → Boot는 항상 SERVLET → @ConditionalOnWebApplication(REACTIVE) 모두 false. FileserverReactiveConfiguration.java:24-30 Javadoc도 "inert in the shipped composition".
    • 규모: web main 약 1.8k(webflux/* 1,010, advanced/webflux 525, callback/reactive 221), fileserver reactive 907, test 약 2k, strict lane 2개(webFluxContractTest, webFluxPerformanceTest).
    • 중복 정도: 주석·import 제외 쌍마다 40–69% 동일(problem handler 0.69, budget 0.49, throttle 0.44, request-id 0.40). transport 중립 코어(core/, budget/, operation/, ProblemCatalog, WebValidationExceptionMapper)는 이미 있음 → 중립 코어를 더 뽑아도 줄어드는 양은 300줄 미만.
    • 갈라짐: NoResourceFoundException→404는 MVC에만(WebMvcProblemExceptionHandler.java:150); reactive fileserver에는 tus/draft12/lifecycle/describe 없음. WebFluxPlatformAutoConfiguration.java:34-37의 중복 정당화("공유 설정을 쓰면 servlet 타입이 딸려 온다")는 사실이 아님(중복 bean 7개 — 주석은 6개 — 모두 stdlib/Jackson만 import).
    • 조치: reactive 껍데기 삭제. 꼭 지원해야 하면 graphql처럼 leaf에서 starter-web을 빼서 서버 선택을 composition으로, 공통 bean 7개는 WebPlatformCommonConfiguration으로. 규모 L · main 약 2.7k + test 약 2k, lane 2개 제거.
    • 반론: 설계서가 WebFlux를 Stable로 약속 — 실행할 composition이 repo에 없음.
  3. [Required][over-abstraction] WebMvcPlatformAutoConfiguration: bean 14개 중 9개는 운영에서 읽는 곳 없음, startup check는 실패 불가 — mvc/autoconfigure/WebMvcPlatformAutoConfiguration.java:56-178

    • 읽는 곳 없는 bean: webOperationCatalog(읽는 FunctionalRouteRegistry, WebRouteInventory 둘 다 도달 불가), webBudgetCatalog, webProblemCatalog, webProblemFactory, webValidationExceptionMapper, webValidationIssueMapper, webWireTypeManifest, webUriPolicy, webMethodPolicy. WebMvcEvidenceFilter.java:52-57은 매 요청 tracker 생성하지만 main의 markApplication*/snapshot()/requireTracker 호출 0. WebMvcPlatformStartupCheck.java:33-53은 같은 클래스가 무조건 만드는 bean 3개의 존재만 확인 → 실패 불가. WebPlatformSnapshot 필드 7개 중 4개는 항상 빔.
    • 조치: bean 9개, evidence filter 배선, startup check, admin/platform 삭제. 규모 M · 약 600 LOC, 개념 약 12개.
  4. [Required][structure] web 안에 같은 관심사가 "1세대(운영·sample 사용)"와 "2세대 platform(읽는 곳 0)" 두 벌 (1차 I-8 확장)

    • 조건부 요청: ETags/PreconditionFailedException(sample 사용, handler 있음) vs EntityTag*/ConditionalReadEvaluator/MutationPreconditionEvaluator/WebPreconditionFailedException(test만, handler 없어 실제로 쓰면 500; WebPreconditionFailedException.java:13이 스스로 인정).
    • 페이지네이션: PageParams/SortParam vs WebCollectionRequestParser + catalog 5종(약 1.1k). cursor codec은 web 2벌(cursor/CursorCodec, pagination/HmacWebCursorCodec) + graphql 1벌(HmacGraphQlCursorCodec), 셋 다 운영 경로 밖.
    • 헤더 상수: 같은 패키지 http/ApiHeaders와 http/WebHeaderName 11개 겹침(표준 헤더는 Spring HttpHeaders에 이미 있음).
    • rate limit: RateLimitInterceptor(운영) vs WebRateLimiter + Web{Mvc,Flux}ThrottleFilter + admission/* + advanced/ratelimit(fixture 전용).
    • 로깅: RequestLoggingFilter vs WebAccessLog*/WebAudit*(381). 동시 실행 제한 semaphore 3벌: SemaphoreAdmissionController, VirtualThreadAdmissionGuard, BlockingBridgeBudget.
    • 조치: 관심사마다 하나만(기본은 2세대 삭제 — 1세대가 문서·sample·handler와 연결). 규모 L · 약 5k LOC, 병렬 개념 약 8개.
    • 반론: 2세대가 설계 목표일 수 있음 → 그렇다면 1세대를 옮기고 삭제. 둘 다 두는 것이 최악.
  5. [Required][duplication] Retry-After 초 계산 3벌, 결과 다름 — 운영 ratelimit/RateLimitInterceptor.java:107-111은 "0" 가능; error/ThrottleProblemWriter.java:72-76은 최소 1("0은 즉시 재시도" 주석); mvc/operation/OperationHttpController.java:81, ReactiveOperationHttpController.java:100은 toSeconds() 버림. 조치: RetryAfter.seconds(Duration) 하나. 규모 S.

  6. [Required][duplication/pattern] GraphQL 에러 "단일 진입점"이 우회되고 Category switch 3개 — runtime/GraphQlWireErrorMapper.java:23,57-72

    • Javadoc "Everything routes through here"인데 요청 단계 경로 2곳(GraphQlPlatformWebInterceptor.java:165, GraphQlPlatformInstrumentation.java:88)은 GraphQlPlatformRejectionMapper.map을 직접 호출; mapRequestRejection 호출처 0, 본문이 mapFieldFailure와 동일. 결과: adopter GraphQlPrincipalResolver가 ApiErrorCarrier를 던지면 요청 단계는 INTERNAL_ERROR, 필드 단계는 제 코드.
    • Category switch 3개(category :102, clientMessage :112, GraphQlWireErrors.classificationOf :54); mapKnown instanceof 분기 9개(GraphQlPlatformRejectionMapper.java:54-121); "요청한 리소스를 찾을 수 없습니다." 3곳 중복. 실제 매퍼는 runtime/, 참조 0인 것(GraphQlRequestErrorMapper, GraphQlSubscriptionExceptionResolver, GraphQlNullabilityContract, 186줄)은 error/.
    • 조치: 세 호출부가 하나의 map(Throwable, ctx); EnumMap<Category, Rendering> 표로 switch 3개 대체; platform 예외가 code/category/message 인터페이스를 구현해 instanceof 사슬 제거; 실제 쓰는 에러 클래스는 error/로, 참조 0 삭제. 규모 M · 약 250 LOC.
  7. [Consider][SRP] GraphQlPlatformAutoConfiguration 706줄 + 부팅마다 reflection 아키텍처 검사 — autoconfigure/GraphQlPlatformAutoConfiguration.java:83,151 (bean 약 40개가 10가지 기능: startup 검증, runtime 감지, body limit, chain, auth, cost, 에러, 관측 7, preparsed cache, DataLoader; graphQlControllerBoundaryCheck가 architecture/(969 LOC)를 매 부팅 실행 — 같은 경계를 app-bootstrap ArchUnit AdapterBoundaryArchitectureTest.java:50,345가 빌드 때 이미 검사; Javadoc(:76) "A real @AutoConfiguration"인데 실제는 FQN @Configuration, :626-660 FQN 투성이). 조치: 기능별 @Configuration으로 나누고 root에서 import, architecture/는 ArchUnit test로. 규모 L.

  8. [Consider][over-abstraction] web이 하위 leaf 패키지 구조를 앎 — web/.../moduleboundary/WebStableModule.java:119-172 (web main이 web-fileserver 패키지 12개 선언 — 방향이 거꾸로 된 지식; test WebBuildModel.java:190-207은 형제 leaf 디렉터리를 경로로 스캔; main 669줄은 test에서만; graphql도 같은 구조(main 535); 자체 import 스캐너 285/293줄은 ArchUnit layeredArchitecture()/slices()로 대체 가능). 조치: leaf마다 ArchUnit 규칙 하나, enum·스캐너 삭제. 규모 M · 약 2.1k LOC.

  9. [Consider][structure] notification HTTP는 일반 web leaf 소속이 아님 — web/.../notification/platform/** (18 파일, 1,168줄; web에서 application-notification을 import하는 유일한 패키지(17곳); web 쪽은 core·observability만 사용; web-fileserver 분리 이유(web-fileserver/build.gradle:8-20)와 같은 모양; 이 패키지 때문에 모든 HTTP 앱이 application-notification을 classpath에 둠(web/build.gradle:18); web CLAUDE.md Allowed 목록에 이 의존 없음). 조치: adapter:inbound:web-notification leaf. 규모 M.

  10. [Consider][SRP] fileserver 업로드 세션 정책(namespace, 만료 시각)이 4개 transport에 복사 — FileUploadController.java:180-187, TusController.java:105-110, Draft12UploadController.java:86-93, reactive/FileUploadHandler.java:116-123 (TTL 설정 3개·검증 복사: FileserverWebProperties.java:24-26, TusProperties.java:22, Draft12Properties.java:16-21; 만료 계산은 세션 정책이라 HARD-STOP 4에 가까움). 조치: application-fileserver가 UploadMode별로 계산. 규모 S-M.

  11. [Consider][pattern] compat/GraphQlSchemaComparator.java(791줄, S5 최대 파일) + GraphQlChangeKind.java(285줄)는 graphql-java 기능 재구현 — graphql-java 25에 graphql.schema.diff.SchemaDiff/DiffCategory 있음; compat 패키지는 도달 불가. 조치: 삭제(1,562 LOC), 필요하면 SchemaDiff 빌드 태스크. 가정: 세부 분류가 SchemaDiff와 같게 나오는지 미확인.

  12. [Nit][pattern] profile-name record 5개 복사본, 1개는 이미 다름 — operation/{Admission,Authorization,Response}ProfileName, CachePolicyName, budget/WebBudgetProfileName = [a-z][a-z0-9.-]{2,63}; ratelimit/RateLimitProfileName만 [a-z][a-z0-9-]{0,63}. 조치: ProfileName 하나 또는 #3과 함께 삭제. 약 140줄.

  13. [Nit][over-abstraction] GraphQL Unsupported 플래그 6개는 "켜면 부팅 실패"만 — GraphQlPlatformSettings.java:151-176, GraphQlPlatformStartupValidator.java:54-72, 문자열 with(String,…). 미구현 기능에는 설정 키를 두지 않음.

  14. [Nit][readability] web README :3 패키지 루트 dev.caskeleton.adapter.web 틀림; web 문서에 WebFlux·notification·problem catalog·advanced·operationasync 전혀 없음(LOC 절반 이상); web-fileserver CLAUDE.md/README 없음; 주석 비율 web 30%, graphql 33%; 이력 서술 web 34, graphql 74; graphql "design §" 92회, "Task N" 17회; inline FQN web 58, graphql 92; GraphQlPlatformWebInterceptor.java:66 생성자 인자 9개(anonymous 관련 3값 parameter object).

다른 모듈로 이어지는 단서 (조사 안 함)

  • Category→status/message switch가 grpc GrpcStatusMapper.java:40에도; web 영어 문구, graphql 한국어 문구로 이미 다름 → shared-contract 표 하나 후보.
  • moduleboundary 세 번째 사본: websocket WebSocketStableModule.java(394), WebSocketBuildModel(264).
  • request context 타입 3종: web core/WebRequestContext, graphql GraphQlRequestContext, shared TenantContext.
  • release/promotion gate(web advanced/release, graphql release)가 websocket/grpc에도 반복되는지.
  • bulkhead: graphql GraphQlBlockingBridge, fileserver BlockingTransferExecutor, httpclient 겹침 여부.

검토 범위

자세히: leaf 문서, 두 web autoconfig, error/validation/ratelimit/conditional, graphql autoconfig/error/runtime, fileserver 컨트롤러·problem·reactive 설정. 도달성은 servlet 진입점(autoconfig, 스캔 대상 stereotype, 다른 main leaf import, sample 제외) 스크립트. 대충: advanced/*, pagination 내부, compat 내부. 1차 결함은 재보고 안 함.

S6 — Realtime/gRPC inbound adapters, composition roots, sample

Per-leaf maintainability verdict

leaf main LOC verdict one-line reason
adapter-inbound-websocket 12,954 OVERBUILT 문서상 기능은 stomp/ 8클래스(479줄)뿐. 나머지 약 9.7k줄은 leaf 자체 @Configuration에서도 닿지 않고, 두 composition root 어디에도 조립 안 됨
adapter-inbound-grpc 623 HEALTHY 9파일, config 1, runner 1. 다른 곳에 gRPC 스택이 하나 더 있다는 것만 문제(lead)
app-bootstrap 6,366 NEEDS_WORK 활성화 규칙 6곳 이상에 흩어지고 기본값이 이미 다름; validator 19개가 5패키지·3 lifecycle; scan 제외 regex가 약 12개 leaf 내부 패키지를 앎
sample-portfolio 9,496 NEEDS_WORK WorkLog slice는 복사할 만함. 그러나 main의 48%가 poster-image; bootstrap 코드 약 540줄 복사; bootstrap이 결함으로 규정한 scan 방식 사용; yml 1/3 미사용
composition-fileserver-platform 868 HEALTHY root 1개 + @Import로 얇게 조립. 오래된 주석, 쓰지 않는 registry edge 1개

그룹 질문에 대한 답

  • 활성화 지도가 한눈에 읽히는가: 아니다. 스위치↔capability 대응이 MasterSwitch(shared-contract, 9개), auto-config 9개의 @ConditionalOnProperty 문자열, CapabilityDependencyValidator·DataSourceRequirement·RedisActivationValidator·SecretSourceValidator·OutboxRelayBrokerRequirementValidator, AdapterActivationEndpoint, build.gradle dependencyPolicy, docs/capability-status.md에 나뉘고 이미 서로 어긋남(#2, #5). bean 등록 경로도 3가지(component scan, AutoConfiguration.imports, spring.factories EPP 6개).
  • sample이 복사할 만한가: WorkLog는 그렇다(얇은 컨트롤러, 순수 Java use case + @Bean 명시 wiring, 직접 만든 fake 테스트). 모듈 전체로는 아니다(#7–#11).
  • capability 하나 켜려면: Outbox+relay = 스위치 5개(APP_OUTBOX_ENABLED, APP_OUTBOX_RELAY_ENABLED, APP_PERSISTENCE_JPA_ENABLED, APP_MESSAGING_ENABLED, APP_MESSAGING_BROKER) + broker starter 의존성 + APP_MESSAGING_KAFKA_BROKERS, yml 3개와 build.gradle, 검증 클래스 4개. Redis cache = redis.yml·capabilities.yml 스위치 1개씩, 연결 env(APP_REDIS_MODE/NODES)는 어느 yml에도 없음, prod HMAC secret, 검증 클래스 2개. 전체 표면: bootstrap yml 19개(1,388줄, 52% 주석), env placeholder 273개, .env.example 401줄.

Findings (highest leverage first)

  1. [Required][reachability] websocket leaf가 안 쓰는 플랫폼 라이브러리를 보유 — src/adapter/inbound/websocket/src/main/java/.../websocket/

    • Evidence: 7개 Spring config에서 닿는 코드는 48클래스 3,230줄; 닿지 않음: advanced/ 4,041, outbound 689, moduleboundary 519, handler 467, evidence 407, release 311. release/WebSocketStableReleaseGate, advanced/release/AdvancedPromotionGate는 테스트만 호출; moduleboundary/WebSocketStableModule(394줄 enum)은 leaf 안의 두 번째 모듈 registry; WebSocketAdvancedCapability.java:71 "Read by the startup validator"는 거짓(호출처 ResumeTokenTest:184-186뿐); STOMP 스택 2개(stomp/WebSocketConfig vs advanced/stomp/** 1,491줄), StompBrokerExclusivity는 둘의 충돌 방지용으로만 존재.
    • Remedy: stomp/ + safety config만 남기고 gate·moduleboundary·evidence는 test source로; 플랫폼 라이브러리는 optional-platforms 같은 별도 build로 빼거나 삭제; STOMP 스택 하나로. Size L · 기본 빌드에서 약 9–12k줄 제거.
    • 가정/반론: 향후 채택용 vendored 라이브러리 → 그렇다면 messaging:*처럼 별도 family로, inbound adapter leaf 안에 둘 이유 없음.
  2. [Required][duplication] capability 의존 규칙 6곳, 기본값 이미 갈라짐 (1차 L-6보다 넓음)

    • Evidence: ca-skeleton.outbox.relay-enabled 없을 때 해석 셋: CapabilityDependencyValidator.java:54,196-198 false, OutboxConfig.java:66 matchIfMissing = true, OutboxRelayBrokerRequirementValidator.java:50 Boolean.TRUE → ORBRV는 "키 없을 때"만 실패, 명시적 true면 CDV가 EPP 단계에서 먼저 거부. capabilities.idempotency.provider 기본값이 CDV:89·DSR:37·RAV:69는 "disabled", SecretSourceValidator.java:137은 "jdbc". Redis role 표 두 벌(RedisActivationValidator.java:27-33 맵 vs SecretSourceValidator prefix 분기); SecretSourceValidator.java:31 REDIS_ENABLED_PROPERTY는 MasterSwitch.REDIS 중복. 같은 키 문자열 반복: idempotency.provider 9회/6파일, relay-enabled 7회/3파일, multi-instance-enabled 5회/3파일.
    • Remedy: 규칙을 표 하나로(RuntimeNumericBoundsValidator.BOUNDS 모양): 키·기본값·필요한 것(JPA/MESSAGING/REDIS)·prod secret. CDV, DSR, Redis 모순 검사, 필요 secret 목록, endpoint를 표에서 파생. Size M · 약 350줄, 클래스 4개 제거.
    • 가정/반론: 표가 작은 DSL로 커질 수 있음 / 소비처 이미 5곳, 기본값 drift 실재.
  3. [Required][SRP|duplication] startup validator 19개가 3 lifecycle·5 패키지에 흩어짐

    • Evidence: EPP 3, InitializingBean 4, SmartInitializingSingleton 12; 12개는 Environment만 받음; 합계 약 1.5k줄(main의 24%). OSIV 검사 두 벌: OpenInViewSafetyValidator.java:26-27(모든 profile 거부) vs JpaDangerousConfigurationGuard.java:51(local-convenience 허용) — 앞의 것이 무조건 등록(RuntimeSafetyConfig.java:28-30)이라 뒤의 예외는 죽은 코드. ddl-auto 검사 두 벌(JpaSchemaSafetyValidator, JpaDangerousConfigurationGuard:62-65). isProdActive() 5곳 복사(JpaSchemaSafetyValidator:51, FlywayProdSafetyValidator:55, PersistenceVendorProdSafetyValidator:81, PostgreSqlTransportSecurityValidator:86, SecretSourceValidator:161). runtime/startup/(CLAUDE.md상 vocabulary 패키지)에 guard 3개. CDV는 EPP와 CapabilityDependencyStartupCheck에서 두 번 실행.
    • Remedy: StartupRule { List<String> violations(Environment) } 목록 + EPP runner 하나; bean 필요한 검사 3개만 bean; OSIV/DDL 하나로. Size M · 약 500줄, 클래스 약 10개 제거.
  4. [Required][structure] root가 넓게 scan한 뒤 다른 leaf 패키지를 blacklist — app-bootstrap/.../CaSkeletonApplication.java:42,58,96-117

    • Evidence: AUTO_CONFIGURED_PACKAGES에 약 12개 leaf 내부 패키지를 가리키는 alternative 18개; bootstrap.notification(:98)은 존재하지 않는 패키지. scan이 실제로 잡는 stereotype 38개(web 27, bootstrap 8), regex가 빼는 것 70개. @ConfigurationPropertiesScan에 별도 whitelist 11개.
    • Remedy: scan을 dev.caskeleton.bootstrap(autoconfigure 제외)로 좁히고, adapter:inbound:web은 persistence/httpclient처럼 자기 AutoConfiguration.imports publish. Size M · regex, whitelist, parity 테스트, "새 패키지를 root에도 등록" 규칙 제거.
    • 반론: web advice·controller 순서를 auto-config로 옮길 때 추가 작업.
  5. [Required][structure] Fileserver는 build에서 빠졌는데 스위치·설정은 남음

    • Evidence: app-bootstrap/build.gradle:376-390 dependencyPolicy가 4개 모듈을 runtime에서 제외; 그런데 application.yml:244가 config/fileserver.yml(116줄) import; MasterSwitch.FILESERVER*가 endpoint에 보고되고 DataSourceRequirement.java:54-59는 이 capability 때문에 pool을 열며, CaSkeletonApplication regex에 3개 항목; docs/capability-status.md:27-28 WIRED=yes. 결과(코드상 추론, 미실행): shipped jar에서 APP_FILESERVER_PLATFORM_ENABLED=true → fileserver bean 없음, 에러 없음, DB pool만 열림.
    • Remedy: fileserver 설정을 composition 모듈 채택 문서/테스트 resource로; "스위치 켜졌는데 capability auto-config 클래스가 없으면 실패" 검사(ClassUtils.isPresent). Size S–M · root에서 약 130줄.
  6. [Required][duplication] idempotency 설정이 binder 3개·yml 2개, 서로 불일치

    • Evidence: IdempotencySettings(ca-skeleton.idempotency, config/idempotency.yml:9), IdempotencyProviderSettings(provider만), cache-redis RedisCapabilitySettings. APP_IDEMPOTENCY_TTL이 두 키에 바인딩(capabilities.yml:34). PostgreSqlIdempotencyProviderConfig.java:36,39는 lease 2분·codec json.v1 하드코딩, capabilities.yml:33,38은 30s·json-v2 광고(PostgreSQL provider는 안 읽음). 같은 패턴: APP_RATE_LIMIT_DEFAULT_POLICY_ID가 ratelimit.yml:10·capabilities.yml:55 둘 다.
    • Remedy: ca-skeleton.capabilities.idempotency settings record 하나를 모든 provider가 사용; config/idempotency.yml·하드코딩 상수 삭제. Size M.
  7. [Required][duplication] sample이 bootstrap 인프라 약 540줄 복사, 이미 갈라짐 — sample-portfolio/.../bootstrap/{tracing,idempotency,settings,logging,metrics,context,management} (difflib 유사도 0.22–0.89; SampleIdempotencyConfig Javadoc "Sample-local copy"; SampleTracingSampleRateResolver의 "staging" -> 0.10 자체 profile 어휘 — bootstrap CLAUDE.md는 RuntimeEnvironment 밖 profile 판정 금지; 원인: app-bootstrap이 라이브러리가 아니라 두 번째 root는 복사할 수밖에 없음). Remedy: root 무관 부분을 두 root가 쓰는 library leaf로(composition:fileserver-platform 모양, registry edge 추가). Size M · 약 500줄.

  8. [Required][structure] sample root가 bootstrap이 결함이라 적은 scan 방식을 가르침 — SamplePortfolioApplication.java (@ComponentScan("dev.caskeleton") + @ConfigurationPropertiesScan("dev.caskeleton"), 타입 3개만 제외; CaSkeletonApplication Javadoc은 이를 "꺼진 capability의 settings가 바인딩되는 원인"으로 설명). Remedy: sample 패키지만 scan, leaf는 auto-config(#4 이후). Size S–M.

  9. [Required][reachability] sample application.yml 327줄 중 109줄을 읽는 코드 없음 — ca-skeleton.capabilities.cache(30), app.cache.redis(25), app.outbound.http(20), ca-skeleton.logging(17), app.notification(5), app.messaging(4), ca-skeleton.bootstrap(2) (1차의 rate-limit 6줄 제외; sample classpath에 binder 없음). Remedy: 삭제. Size S.

  10. [Consider][structure] sample 대표 예제가 poster-image에 묻힘 — poster-image 약 4.6k줄 vs WorkLog 2.2k; application/에 종류별(command/, query/, event/, port/, exception/)과 기능별(poster/, posterimage/, worklog/) 패키지 혼재; 상태 머신 PosterImageUploadIntent(333줄, 필드 24)가 application 계층(WorkLog는 domain); PublishPosterImageUseCase 생성자 14개; legacy API 모드 약 420줄; WorkLogSortField(domain)가 HTTP 이름(fromRequest)과 persistence property 이름을 둘 다 앎; sample-portfolio/CLAUDE.md:15-21은 WorkLog만, 경로 틀림. Remedy: 기능별 패키지, poster-image는 별도 sample 모듈/objectstorage 검증 consumer로 이동, legacy 모드 삭제. Size L. 반론: object-storage publication·idempotency V2를 끝까지 쓰는 유일한 consumer → 삭제가 아니라 이동.

  11. [Consider][duplication] sample 컨트롤러·테스트 반복 — toId() 4벌(WorkLogController:239, PosterController:161, LegacyPosterImageController:49, PosterImagePublicationController:110); sort 파싱 2벌(WorkLogController:99-113, PosterController:91-105); WorkLogController.requireIfMatch:209가 update 전에 get use case를 추가 호출(컨트롤러가 use case 2개 조율, 읽기-비교가 트랜잭션 밖); 테스트 9개 파일이 TransactionPort fake를 각자 작성, testFixtures에 공용 fake 없음. Remedy: UpdateWorkLogCommand에 expectedVersion, id/sort helper 하나, InlineTransactionPort를 testFixtures로. Size S.

  12. [Consider][over-abstraction] JPA 정책 클래스 — JpaPlatformAutoConfiguration은 auto-config가 아니라 factory·report·16개 항목 정적 catalog 겸용; jpaDataSourceProfileValidator bean(JpaPlatformRuntimeAutoConfiguration:59-64) 주입처 없음(PersistenceJpaRootAutoConfiguration:43이 따로 new); app.jpa-platform.addons-enabled(:30) 테스트만 설정. Remedy: 개명/inline, 미사용 bean·플래그 삭제. Size S.

  13. [Consider][over-abstraction] 역할 없는 startup 예외 subclass 4개 — runtime/startup/{MigrationFailed,ProfileMismatch,RequiredAdapterDisabled,StartupValidation}Exception (각자 StartupErrorCode를 부모에 넘기기만; 타입 구분 55곳 모두 테스트). Remedy: 구체 클래스 하나 + errorCode() 단언. Size S.

  14. [Consider][structure] 스위치 prefix·"capability" 뜻 제각각 — prefix 셋: ca-skeleton.*(jpa, mongo, notification, outbox, tracing, grpc), app.*(messaging, redis, fileserver, httpclient, websocket, rate-limit), backend.graphql; "capability" 4가지 뜻(@UseCaseCapability, master switch, capabilities.* provider selector, JpaCapability/WebSocketAdvancedCapability); outbox·tracing·lock 스위치는 MasterSwitch에 없어 endpoint에 미보고. Remedy: MasterSwitch.legacyProperties() 이관 장치로 prefix 통일. Size M. 반론: property 이름 변경은 fork breaking.

  15. [Consider][structure] bootstrap :test에 저장소 governance 테스트 약 7.6k줄 — src/test/.../contract/ (47파일 중 33개가 docs/registry/yml을 직접 읽음). Remedy: architectureTest처럼 별도 lane. Size M.

  16. [Nit][readability] 이력/리뷰 ID 주석: bootstrap 105줄(주석 비율 25%), websocket 35%; CapabilityDependencyEnvironmentValidator.java 30줄 Javadoc이 3줄짜리 클래스 설명; hikari connection-timeout 주석 "It shipped as 5s…"; config yml 15개가 같은 3줄 헤더 반복; OpenInViewSafetyValidator 예외 메시지에 "D2"; FileserverPlatformAutoConfiguration의 "identifier generator" 설명 틀림(identifier 의존성 없음 → registry edge adapter-outbound-identifier도 미사용).

  17. [Nit] TracingSettings.sampleRate가 String이라 3곳에서 파싱(클래스 5개, 377줄; TracingSampleRateResolver inline FQN) → 범위 검증 붙은 Double.

Cross-module leads (not investigated)

  • gRPC 서버 스택 2개: adapter/inbound/grpc(GrpcServerRunner, GrpcStatusMapper) vs grpc/grpc-server + grpc-spring-boot-starter(GrpcErrorMapper), 둘 다 조립 안 됨.
  • inline TransactionPort fake가 저장소 전체 테스트 19곳 이상 → application-core testFixtures로 하나.
  • 복사용 예제 CreateWorkLogUseCase가 LegacyOutboxAppendPort 사용(MSG-015 cutover 관련).
  • docs/capability-status.md:27-28 WIRED=yes vs dependencyPolicy 모순; MasterSwitch(shared-contract)가 shipped build에 없는 capability 나열.
  • DefaultUploadApplicationService 생성자 14개(application-fileserver), FileserverUploadServiceConfiguration.java:74에서 조립.

Coverage note

깊게: bootstrap activation/, autoconfigure/{idempotency,jpa,outbox,redis}, CaSkeletonApplication, validator 목록·핵심 본문, yml; sample entry, bootstrap/*, 컨트롤러, 대표 use case·테스트, yml; gRPC main 전체. websocket 도달 가능성은 단순 이름 참조 그래프(Spring config root, reflection 미반영).

S7 — Vendored platforms (messaging:*, grpc:*, grpc-advanced:*)

Per-family / per-leaf maintainability verdict

leaf or family main LOC verdict one-line reason
messaging-core-api 3,948 NEEDS_WORK 예외 서브클래스 12개 미사용, MessageHandler 연결 없음, boolean 12개 capability
messaging-schema-api / schema-json 654 / 226 HEALTHY 조립되는 코덱은 json 하나; schema-api는 core-api와 합칠 후보
schema-avro / schema-protobuf / cloudevents / claim-check 1,190 OVERBUILT 쓰는 곳 없음(100% 도달 불가); starter가 cloudevents·claim-check edge를 쓰지 않으면서 달고 있음
policy / transport-spi / runtime-core / security / observability 5,140 HEALTHY 발행 경로, 도달 불가 0–38%
messaging-kafka 3,454 NEEDS_WORK 71% 도달 불가(consume 쪽 전체), 645줄 registrar
rabbit + starter-rabbit 2,625 OVERBUILT 기동 시 선택하면 거부; 운영 코드에 RabbitChannelPublisher 구현 없음
pulsar / nats / kafka-share / stream-bridge 2,082 OVERBUILT vendor SDK 의존성 없음, 쓰는 곳 없음
reliability-api / outbox-jdbc / inbox-jdbc 3,599 NEEDS_WORK leaf 하나가 서로 다른 일 4가지; 호출자 없는 port 메서드
admin-api + admin-runtime 2,858 NEEDS_WORK 진입점 없음, leaf 2개로 나눈 이유 없음
messaging-spring-boot-starter 3,328 NEEDS_WORK 550줄 god config, 20필드 union settings, 쓰는 곳 없는 facade 3개
starter-kafka / testkit 197 / 1,145 HEALTHY capability artifact / 테스트 지원
grpc-core-api 1,897 NEEDS_WORK registry 내용을 코드로 재기술(GrpcStableModuleCatalog)
grpc policy+server+client+discovery+admin 8,197 NEEDS_WORK 의존성 경계 1개를 leaf 5개로 쪼갬; io.grpc import는 운영 파일 5개뿐
grpc-proto-contract + codegen 1,297 OVERBUILT protoc/Buf를 regex로 재구현
grpc-observability 354 NEEDS_WORK 쓰는 곳 0
grpc-operation-ledger-jpa / starter / testkit 336 / 494 / 2,323 HEALTHY JPA·Spring·netty라는 실제 의존성 경계
advanced bootstrap/edition/streaming/resilience/diagnostics 3,021 OVERBUILT stdlib뿐인 leaf 5개, 런타임 진입점 0
grpc-advanced-compat 962 NEEDS_WORK reactor·spring-integration 실제 의존성 있음, gate 클래스 섞임

도달성(starter/adapter/app-bootstrap main에서 클래스 이름 참조 전이 폐포, 과대 추정 → 도달 불가 수치는 하한): messaging testkit 제외 ≥12.7k/29.3k LOC(43%), grpc starter 기준 12.4k/16.6k(75%) 도달 불가.

Findings (highest leverage first)

  1. [Required][granularity|reachability] 선택 불가하거나 쓰는 곳 없는 messaging leaf 10개가 기본 빌드에 — messaging-pulsar-experimental, -nats-experimental, -kafka-share-experimental, -spring-cloud-stream-bridge(build.gradle에 SCSt 의존성 없음), -rabbit + -starter-rabbit(MessagingProviderSelection.java:69 기동 거부), -schema-avro, -schema-protobuf, -cloudevents, -claim-check

    • Evidence: 운영 5,897 + 테스트 4,016 LOC; pulsar/nats/kafka-share/stream-bridge는 vendor 의존성 없이 자체 *SendOperation seam만(PulsarMessagingTransport.java:264); starter가 cloudevents·claim-check를 implementation으로 달지만 main 참조 0(messaging-spring-boot-starter/build.gradle:36,43); MessagingSettings.Experimental/Bridge(:150,:212)는 바인딩만.
    • Remedy: grpc처럼 optional-platforms build로 이동; experimental 4개와 Debezium은 삭제 권고; starter edge 2개·설정 클래스 2개 삭제. Size M · 기본 빌드 leaf 10개, 약 5.9k LOC.
    • Assumption/Counter: 기본 adopter는 Kafka 발행만 / docs/messaging/support-matrix.md 공개 약속 — 이동은 삭제가 아님.
  2. [Required][structure|over-abstraction] consume 계약 3개, 조립 0 — messaging-core-api/.../delivery/MessageHandler.java:15(참조 0), DefaultDeliveryProcessor.java:40(Function<MessageEnvelope<EncodedMessage>,HandleResult>), reliability-api/.../IdempotentMessageHandler.java:21

    • Evidence: MessagingTransport.register() main 호출 0; 자동 조립 transport는 발행 전용 생성자(KafkaMessagingTransport.java:80-91 → KAFKA_CONSUMER_NOT_CONFIGURED); KafkaConsumerRegistrar(645), KafkaBatchConsumerRegistrar, delivery/retry mapper 합쳐 약 2.4k LOC 도달 불가.
    • Remedy: MessageHandler<T> 하나로; DefaultDeliveryProcessor가 codec registry로 decode; starter-kafka가 consumerFactory로 registrar 조립(@ConditionalOnBean(MessageHandler.class)). consume을 범위에서 빼면 handler 3종·registrar를 #1처럼 이동. Size M.
    • Counter: README(messaging-spring-boot-starter/README.md:34) "직접 조립" — 예제 없고 계약 3개라 따라갈 수 없음.
  3. [Required][granularity] grpc 18 leaf → 9 leaf — io.grpc import 운영 파일 5개뿐(grpc-policy 4, GrpcServerInterceptorChain)

    • Evidence: grpc-client는 api "io.grpc:grpc-api"(build.gradle:12) 선언하나 io.grpc import 0; grpc-codegen의 proto-contract 의존(:13), grpc-advanced-edition의 project 의존 3개(:9-11)는 미사용. 실제 의존성 경계는 core-api(0), ledger-jpa(JPA), observability(Micrometer), compat(reactor/SI), starter, testkit. 설계서 §2(2026-08-30-grpc-platform-adaptation-design.md:78-81)도 advanced는 "합쳐도 불변 조건 유지".
    • Remedy: policy+server+client+discovery+admin → grpc-runtime; proto-contract+codegen → grpc-contract; advanced 5개 → grpc-advanced, compat 유지. "grpc:* → grpc-advanced:* 금지"는 prefix 두 개로 표현. Size L(이동만) · leaf 9개, phantom edge 5개.
    • Counter: 원본 31-모듈 계획과의 1:1 대응 — Gradle이 강제하는 규칙은 없음.
  4. [Required][over-abstraction] governance를 운영 코드로 구현 — grpc/advanced main의 gate/guard/matrix/promotion/catalog 약 1,690줄

    • Evidence: 인자 없이 상수를 반환하는 메서드 11개 — GrpcStableBuildInvariant.java:26, GrpcKotlinCompatibilityGate.java:67, GrpcWebCompatibilityGate.java:54, GrpcServletStartupValidator.java:49, GrpcEdition2026Guard.java:18,46, GrpcEdition2024Gate.java:50,59, GrpcResolverSafetyPolicy.java:77,82, GrpcXdsStartupGuard.java:98. GrpcStableModuleCatalog.java는 leaf 목록을 core-api 안에 재기술(registry SSOT 규칙 위반). GrpcRawApiImportRule/GrpcApplicationBoundaryRules(200줄)는 문자열로 ArchUnit 흉내, 자기 테스트에서만.
    • Remedy: 상수 gate, catalog, invariant, GrpcAdvancedInfrastructureTestkit 삭제; import rule은 ArchUnit으로. Size M · 약 700–1,000 LOC. 1차 N-9(validateAdvancedIsolation)와 겹침.
    • Counter: 테스트가 "결정을 붙든다" — return false를 검증하는 테스트는 오타만 막음.
  5. [Required][SRP] messaging-outbox-jdbc-postgresql이 서로 다른 일 4가지 — vendor 중립 relay 7클래스(약 877), PostgreSQL repository(721), Debezium 4개(약 351, SDK 없음, 참조 0), JdbcAdminOperationJournal(326, 오류 메시지 문자열에서만 언급). leaf 19클래스 중 Spring JDBC import는 3개(Jdbc*); inbox도 6개 중 5개가 stdlib.

    • Remedy: messaging-reliability(reliability-api + relay/inbox 로직, stdlib) + messaging-reliability-jdbc-postgresql(Jdbc 3종), Debezium 삭제. Size M · leaf 3→2, 약 350 LOC.
  6. [Required][duplication|pattern] PublishResult 7-인자 생성 11개 파일 28회 — 실제 모양은 rejected/ambiguous/confirmed 3가지. PublishEvidence.ambiguous()가 있는데 7곳이 new PublishEvidence(true, MAY_HAVE_BEEN_TRANSMITTED, false, NONE) 직접 사용(PublishResults.java:43-67); rejectedLocally 4곳 복사(KafkaMessagingTransport.java:200, RabbitMessagingTransport.java:271, PulsarMessagingTransport.java:246, NatsJetStreamTransport.java:263); PulsarPreSendRejection·NatsPreSendRejection Javadoc만 다름. Remedy: PublishResult.rejected/ambiguous/confirmed 정적 factory, PreSendRejection은 transport-spi 하나. Size S–M · 약 200 LOC.

  7. [Required][duplication] envelope ↔ canonical header 변환 3번 작성 — KafkaHeaderMapper.java:32-100 + KafkaDeliveryMapper.java:66-125, RabbitHeaderMapper.java:31 + RabbitDeliveryMapper.java:65-94, DebeziumOutboxEventRouter.java:35(ReservedHeaders 참조 31개). Remedy: core-api CanonicalEnvelopeHeaders에 write(envelope, BiConsumer<String,String>)·read(Function<String,String>); broker mapper는 연결 코드만, RESERVED_HEADER_FORGED 규칙 한 곳. Size M · 약 300 LOC.

  8. [Consider][over-abstraction] outbox port·repository 죽은 표면 — OutboxRepository.java:36 leaseBatch(deprecated, main 0), 4-인자 claimBatch·3-인자 markAmbiguous 오버로드(main 0), JdbcOutboxRepository.java:426-455 *Unfenced 4개(main 0), :600-721 손 JSON 직렬화 약 115줄. Remedy: 메서드 7개 삭제, JSON은 Jackson(starter 런타임에 있음) 또는 jsonb_each_text. Size M · 약 250 LOC(purge 오버로드는 1차 M-6).

  9. [Consider][SRP] starter 조립 구조 — MessagingCoreAutoConfiguration.java 550줄·@Bean 28·inline FQN 46줄; BrokerSettings.java:42는 Kafka·Rabbit 20필드 union record인데 broker 중립 core starter에; Blocking/Reactive/Batch facade(약 566 LOC)는 외부 사용 0인데 Reactive 때문에 api 'io.projectreactor:reactor-core'(build.gradle:54)가 모든 앱에 노출. Remedy: config/validation, publish pipeline, observability 세 configuration; broker별 필드는 broker starter가 Binder로; facade 삭제 또는 reactor compileOnly. Size M.

  10. [Consider][over-abstraction] 미사용 API 타입(1차 M-9 목록 외) — MessagingException 서브클래스 23개 중 12개 main 참조 0(Authentication, BrokerUnavailable, Consumer, DeadLetter, HandlerTimeout, HeaderRejected, PublishAmbiguous, PublishRejected, Redrive, RetryExhausted, Routing, SettlementUnknown; 각 약 50줄, (category, retryable)만 다름; 서브클래스별 catch는 1곳); MessageHandler, KafkaTopologyInspector, RabbitRequestReply, ReliableMessagePublisher, InboxRecord 구현·참조 0. Remedy: 삭제. Size M · 약 750 LOC. Counter: public surface breaking — 구현·사용처 없음.

  11. [Consider][pattern] MessagingCapabilities 위치 boolean 12개 — KafkaMessagingTransport.java:62-63 new MessagingCapabilities(true, true, …, true), 생성 11곳, main에서 읽는 flag는 12개 중 3개. Remedy: EnumSet<Capability>, 안 읽는 flag 삭제. Size S.

  12. [Consider][granularity] messaging API leaf 병합 — core-api + schema-api → 1개; admin-api + admin-runtime → 1개. #1·#5와 합치면 기본 빌드 messaging leaf 27 → 14. transport-spi·runtime-core는 bridge 격리 규칙 때문에 유지. Size M.

  13. [Consider][reinvention] GrpcProtoContractValidator(447줄 regex .proto 파서)와 grpc-codegen(Buf lint/breaking 재구현, Java import regex) — 근거 "Buf CLI가 없다"(grpc-codegen/build.gradle:8-9); protoc은 Maven artifact, Buf도 Gradle로 받을 수 있음; 실제 stub 생성 0건. Remedy: com.google.protobuf 플러그인 + buf를 CI에서, 두 leaf 삭제. Size L · 약 1.1k LOC. 반론: 설계 결정 D5/D6.

  14. [Consider][structure] 패키지·leaf 이름 불일치, 용어 혼재 — dev.caskeleton.grpc.resilience/streaming은 grpc-policy의 패키지인데 grpc-advanced-resilience/-streaming은 leaf 이름; discovery는 반대; grpc-policy에 interceptor·writer·rotation manager 같은 런타임 코드; 지원 등급 이름 4개(CapabilityTier{M1..M3}, CompatibilityMatrix.Tier, GrpcCapabilityGrade, GrpcEvidenceGrade). Remedy: #3으로 대부분 해소, 용어 하나로. Size S.

  15. [Consider][readability] messaging main 주석 30%(9,234/30,446), grpc 17%; "used to / no longer" 78줄(KafkaConsumerRegistrar 6줄), 리뷰 ID MSG-* 9곳(MessagingCoreAutoConfiguration.java:370,442,480 등); inline FQN 190줄(KafkaConsumerRegistrar 31, DefaultBatchMessagePublisher 20). Remedy: 이력은 git/ADR, OpenRewrite ShortenFullyQualifiedTypeReferences. Size M(기계적).

  16. [Nit][structure] dev.caskeleton.messaging.autoconfigure 패키지가 leaf 3개에 걸침(package-private StartupProfileValidation 때문); registry의 starter-kafka allowed_dependencies 10개인데 build.gradle은 2개만 사용; KafkaConsumerRegistrar.dispatch 75줄(:264).

Cross-module leads (not investigated)

  • outbox relay 3개: application-core/.../PublishPendingOutboxEventsUseCase, .../outbox/v2/PublishNextOutboxDeliveryUseCase, messaging OutboxRelay.
  • 멱등성 저장소 3개: application idempotency, grpc-operation-ledger-jpa, messaging-inbox-jdbc.
  • Kafka producer 경로 2개: adapter/outbound/messaging-kafka LegacyKafkaMessagingRootAutoConfiguration(R0) vs KafkaMessagingTransport.
  • lease/claimBatch: JpaRecipientLeaseStore.claimBatch vs OutboxRepository.claimBatch.
  • messaging 기본 off 처리 두 곳: DisabledMessagingSentinelAutoConfiguration(app-bootstrap) vs starter master switch.

Coverage note

leaf 45개 전부 LOC/파일, 의존성 선언, import, 도달성 계산. 자세히: starter 3종·조립 클래스, transport 4종 publish/classify, outbox/inbox, core-api publish·error·capabilities, grpc starter·core-api·advanced gate, 설계서 §2. rabbit/kafka consumer 내부, grpc-policy streaming 개별 클래스는 이름·크기만.