runbook이 코드가 내지 않는 신호로 장애를 찾게 한다. actuator·cross-tenant
runbook은 아무 코드도 내지 않는 ACTUATOR_FORBIDDEN·AUTHZ_TENANT_MISMATCH를
증상으로 적고, 없는 경보·지표·로그 칸을 적는다. auth runbook은 로그에서
token payload·Authorization 원문을 보라고 하고(남지도 않고 남겨서도 안
된다), 없는 JWKS 캐시 손잡이와 decoder가 읽지 않는 Spring issuer 키를
적는다. rate-limit·dependency runbook은 없는 gateway 지표·헤더·
CACHE_UNAVAILABLE·dependency_name 칸을, web runbook은 연산마다의 TTL,
시험 도구 GracefulShutdownProbe, 없는 tag routeTemplate, 기동이 거부하는
CORS 설정을 「기동은 된다」고 적는다. job runbook은 내는 코드가 없는
JOB_DEAD_LETTER·JOB_TIMEOUT과 job.* 지표에 경보를 걸게 한다.
각 runbook을 지금 코드가 내는 신호로 다시 쓴다: 응답 코드·헤더, 보안
로그 줄 `security failure: code=… path=…`, 요청 로그 줄, ServerFailureLog
의 고정 문구(`dependency failure classified as … dependency=<이름>`,
`persistence failure classified as …`), 실제 설정 키
APP_SECURITY_JWT_ISSUER, registry에 있는 지표. 이 템플릿에 경보 규칙이
없다는 것, 내는 코드가 없는 코드·지표는 서비스가 낼 때만 있다는 것을
적는다. 진단 순서도 고친다: actuator 노출은 관리 포트 9001로 가르고,
INTERNAL_AUTH_MISCONFIGURATION은 issuer discovery(4xx·issuer 불일치·
jwks_uri 없음은 500, 연결 실패·5xx·JSON 아님은 503)부터, 종료 예산은
웹 drain 30s + async 19s + preStop의 합으로 본다. 같은 원인의 다른
자리(경보 이름을 지어 적은 job·outbox·internal-error-spike, traceId로
적은 칸, 지적 밖 auth·dependency·db·outbox runbook, error-codes.yaml 주석,
같은 틀린 신호를 적은 shared-contract README·web README·
DependencyFailureException Javadoc)도 고치고, 본문의 리뷰 ID는 지운다.
버린 안: 선언만 있는 두 코드를 내는 WARN·counter를 새로 만들기. actuator
노출 밖 경로는 메인 chain이 401 AUTH_TOKEN_MISSING(익명)·404(인증됨)로
답해 403 상황이 없고, cross-tenant는 정한 규칙(남의 것은 404)이라 판정
자리가 서비스 코드에 있다. 새 신호는 서비스가 더할 일로 runbook에 적는다.
위험: 문서만 바뀐다. runbook은 모두 status 초안으로 둔다.
dependency-unavailable이 적은 hikaricp.connections.pending·timeout 행과
job.* 행의 emitted_when은 관측 registry 변경(같은 묶음의 다른 PR)이
더하고, auth-jwks-unavailable의 「캐시가 지난 뒤 503」은 인증 PR의 JWKS
재조회 분류 수정이 만든다. 세 PR을 함께 병합한다.
검증: python3 scripts/check-docs.py·check-work-docs.py OK, desktop
:app-bootstrap:documentContractTest :app-bootstrap:repositoryContractTest,
scripts/verify.sh pr rc=0.
Refs: RR9-02-04, RR9-02-24, RR9-04-34, RR9-04-37
공개 경로 스냅숏은 이제 기본 공개 경로만이 아니라 profile 덮어쓰기와
운영 코드 filter chain의 `permitAll`·`securityMatcher` 문장까지 고정한다
(`docs/security/public-paths-snapshot.txt`). 그런데 그 검사를 설명하는 세
곳은 아직 「기본 공개 경로」만 본다고 적는다.
- gates.md 2절 `verifyPublicPathSnapshot` 행
- 루트 build.gradle `verifyPublicPathSnapshot` 태스크 description
- app-bootstrap build.gradle `publicPathSnapshotTest` 레인 description
세 곳 모두 지금 범위(기본값, profile 덮어쓰기, filter chain 문장)로 고친다.
동작 변경 없음.
검증: scripts/verify.sh docs(노트북) rc=0. 이 문구를 고정하는 시험은 없다
(git grep 'shipped public path default' -- '*.java': 0건).
Refs: round9 확인 리뷰(r9-be가 넘긴 Low, 공개 경로 범위 확장 뒤)
- 그룹 C 묶음 PR(#25 계약·오류 코드, #27 시험·빌드·스크립트, #26 문서)과 새 묶음
B20(objectstorage 포트 계약)을 4절 표에 적었다. #26은 #23·#24·#25 뒤에 병합한다.
- 그룹 C 묶음의 새 눈 리뷰가 찾은 기존 결함 다섯(RR9-03-31·32, RR9-04-43~45)을
색인·영역 문서·「고치며 찾은 것」에 더하고 총수를 158건으로 고쳤다. 묶음 PR이 만든
회귀는 그 PR에서 고쳤고 세지 않는다.
- 6절에 ⑦(callback의 본문 없는 응답을 Envelope 예외로 적는 권하는 안), 5절에 CI 세션
넘김 10번(build-logic AGENTS의 lane 문장)을 더했다.
검증: check-review-index.py(색인 158/158), check-docs.py·check-work-docs.py rc=0.
Refs: RR9-03-31, RR9-03-32, RR9-04-43, RR9-04-44, RR9-04-45
문제:
- ca.spring-library가 모든 spring leaf(30)의 testImplementation에
spring-boot-starter-webmvc-test를 넣어, MockMvc를 쓰지 않는 23 leaf가 Tomcat을
시험 classpath에 resolve하고 lock했다.
- container-images.properties 머리말은 「digest로 고정」이라는데 postgres-17·18이
tag만이었다. 머리말은 「쓰는 lane만 다시 돈다」고 했지만 파일 전체가 모든 Test
task의 입력이라 이미지 하나만 바꿔도 모든 lane이 다시 돈다. postgres-16-4는
아무도 읽지 않았다.
- libs.versions.toml에 아무도 읽지 않는 칸이 있었다(라이브러리 9, 버전 4,
루트에 적용하지 않는 플러그인 4).
- config/spotbugs/exclude.xml에 없는 클래스의 항목이 있었다(exclude-test.xml에
이미 있다).
- notification의 API surface가 상대 경로로 application-notification 소스를
가리켰고, ApiSurface 플러그인은 없는 추가 root를 말없이 건너뛰어 승인 update가
줄어든 표면을 기록할 수 있었다.
- verify-mongodb-platform.sh가 고르는 클래스가 없는 :app-bootstrap:test
--tests '*CleanArchitectureTest'를 불러 늘 실패했고, 이미지 기록이 카탈로그와
다른 tag였다.
고친 것:
- 규약은 spring-boot-starter-test만 준다. 시험이 실제로 쓰는 것을 leaf가 직접
선언한다. MockMvc를 쓰는 web·web-advanced·web-fileserver·web-notification·
app-bootstrap은 webmvc-test starter, graphql은 TestRestTemplate의
spring-boot-resttestclient, durable-operation은 WebApplicationContextRunner의
spring-web, 시험이 JSON을 읽는 objectstorage·persistence-jpa·persistence-mongo·
notification-platform은 jackson-databind, redis-runtime은 jackson-annotations
(compileOnly, 본 코드와 같은 이유)다. 모든 Java source set을 한 빌드에서 컴파일해
빠진 곳이 없음을 확인하고 lockfile을 다시 만들었다(Tomcat·webmvc 시험 자동설정이
빠짐). graphql·persistence-mongo AGENTS의 허용·시험 목록을 같이 고쳤다.
- postgres 17·18을 desktop runner에서 받은 digest로 고정했다(17.11, 18.6). 목록을
읽을 때 digest 없는 값을 GradleException으로 거절한다(ContainerImageCatalogTest).
머리말을 실제 캐시 동작으로 고쳤고 postgres-16-4를 지웠다. persistence-jpa
release registry의 PostgreSQL tag는 아무도 읽지 않아 지우고, 이미지는 카탈로그가
정한다고 적었다.
- 카탈로그의 미사용 칸을 지우고 머리말을 지금 쓰임에 맞췄다.
- 죽은 spotbugs 항목을 지웠다.
- notification은 project(':application-notification')로 root를 잡고, 없는 추가
root는 설정 단계에서 실패한다(ApiSurfaceConventionTest).
- mongo 스크립트는 :app-bootstrap:architectureTest를 부르고, 이미지 기록은
카탈로그 mongo-8 값을 읽는다.
- graphql build.gradle에 앞 커밋의 document-contract lane을 함께 둔다. 저장소 루트
(ca.repository.root)와 읽는 registry 파일은 그 lane만 받고, 시험은 그 속성으로만
루트를 읽는다(cwd에서 거슬러 찾지 않는다).
버린 대안: 이미지마다 쓰는 lane을 선언해 입력을 나누기 — lane 수십 개에 키
목록을 다시 적어야 하고 빠뜨리면 캐시가 거짓 통과한다.
검증: 아래 PR 본문(desktop resolveAndLockAll·build-logic test·모든 source set 컴파일·
leaf check).
BREAKING CHANGE: ca.spring-library가 시험 classpath에 spring-boot-starter-webmvc-test를
넣지 않는다. MockMvc·TestRestTemplate·Jackson을 그 starter로 받던 파생 leaf는 의존을
직접 선언해야 시험이 컴파일된다. 카탈로그의 digest 없는 이미지와 없는 API surface 추가
root는 설정 단계에서 실패한다. version catalog의 미사용 칸을 지웠다. 할 일은
docs/upgrade/2026-11-round9-build.md다.
Refs: RR9-04-06, RR9-04-11, RR9-04-12, RR9-04-13, RR9-04-14, RR9-04-15, RR9-04-16
문제:
- GraphQlDeploymentModeRegistryParityTest가 태그 없이 test에서
docs/registries/env-keys.yaml을 읽었다. 입력을 선언하지 않아 test 캐시가
registry 변경을 놓쳤고, modules.json을 거슬러 올라가 저장소 루트 가드를
우회했다(build-logic/AGENTS.md 「저장소 파일을 읽는 테스트」).
- 「값을 싣지 않는다」 단언 넷(WebSecurityContextBridgeTest, scalar 둘)이 예외
타입을 보지 않아, 메시지 null인 NPE로 바꿔도 통과했다.
- FileserverAdminControllerRequestBodyValidationTest는 @RequestBody가 하나도 없는
controller에도 통과했다.
- GraphQlRequestDeadlineTest가 sleep(500) 뒤에 하위 필드 부재를 단언했다. 부하에
따라 기다림이 짧으면 거짓 통과다.
- 두 동작을 한 시험에서 보던 셋(표 입력 반복문, when 둘).
고친 것:
- registry 대조 시험에 document-contract 태그를 달고 graphql leaf에
mainStage lane graphqlDocumentContractTest를 둔다(lane은 다음 커밋의
build.gradle에 있다. 그 파일의 다른 변경과 같이 간다).
- 부재 단언에 예외 타입(CoercingParseValueException,
UntrustedTenantInputException)을 먼저 둔다.
- admin 시험은 @RequestBody 매개변수 목록을 고정한 뒤 @Valid를 본다.
- deadline 시험은 slowNode 실행이 끝났다는 신호(Instrumentation
beginExecution 완료, 세대 번호로 이전 시험의 늦은 완료를 거른다)를 기다린 뒤
부재를 본다.
- 표 입력(scalar 넷의 부재 단언 포함)은 @ParameterizedTest로, 두 동작은 시험 둘로
나눴다. 고친 시험은 GWT와 catchThrowable로 when을 하나로 둔다.
- decisions 2.1에 「시험 형식 일괄 전환 안 함」(리뷰 README 6절 ④) 행을 더했다.
Refs: RR9-03-17, RR9-03-18, RR9-03-19, RR9-03-20, RR9-03-22
문제(구조 리뷰):
- application-notification 안내가 나가는 포트를 `*Port`로만 적어 provider·security
패키지와 이름이 다른 포트 일곱(NotificationProviderAdapter, TemplateRegistry 등)을
빠뜨렸다. provider를 더하는 세션이 같은 계약을 두 번 만들 수 있다.
- notification·fileserver testFixtures를 모든 포트에 있는 것처럼 적었다.
- application-objectstorage 안내가 adapter의 provider SPI 계약을 이 leaf 포트의
계약처럼 적었다. 이 leaf에는 포트 계약 시험이 없다.
- redis-runtime 안내가 redis-sdk를 포트 구현 leaf로 적었고, redis-sdk로 싣는 길에서는
APP_REDIS_ENABLED를 직접 줘야 한다는 것을 적지 않았다.
- provider callback은 본문 없이 status만 답하는데, Envelope가 아닌 응답이 fileserver
프로토콜 예외뿐인 것처럼 적혀 있었다. objectstorage README는 registry에 있는
APP_OBJECTSTORAGE_ENABLED를 「전용 키 없음」이라 했다.
고친 것: 위 문장을 코드대로 고치고, callback 응답(204·400·413·503, 본문 없음)을 HTTP
계약 §1·callback 문서·leaf 안내에 예외로 적었다. callback 동작은 그대로 둔다(인증 전
경로라 거절 이유를 싣지 않고, provider는 status로 재전송을 정한다).
검증: check-docs.py·check-work-docs.py rc=0. 이 문서들을 읽는 시험은 존재 확인뿐이다
(NotificationReleaseGateTest).
Refs: RR9-04-42
문제(새 눈 리뷰):
- web-notification 안내가 callback 서명 검증을 유스케이스가 한다고 적었다.
실제로는 composition의 ProviderCallbackIngressBridge가 outbound provider
adapter(SES는 SnsSignatureVerifier)로 검증하고 검증된 event만 넘긴다.
- application-notification 안내가 없는 패키지 platform.port.out을 나가는 포트
위치로 적었고, testFixtures를 「포트마다 fake 하나」라고 실제보다 크게 적었다.
- web-fileserver 책임 목록에 lifecycle(삭제·복사·이동)과 http(Range·조건부
다운로드 계획) 패키지가 없었다.
- redis-runtime README가 app.redis.* 기본값 위치를 잘못 적었다. objectstorage
README가 포트 개수를 복사했다.
- web 한도 표가 multipart 한도를 「전역 한도 없음」이라 했고, 아무도 막지 않는
칸을 「늘 애플리케이션」이라 했다.
- TESTING_STRATEGY가 묶음 태스크를 셋이라 세며 performanceCheck를 빠뜨렸다.
- roadmap messaging-r2 이력 블록의 날짜·이유가 틀렸다(6d27356e, 2026-09-25).
- 지운 ComposeMergeCharacterizationTest 행의 커밋이 지운 쪽 기준이 아니었다.
고친 것: 위 문장을 지금 코드대로 고쳤다. 공개 경로 스냅숏 문장과 fileserver
「오류 코드」 절 안내는 공개 표면 PR·계약 PR이 만드는 것이라 병합 순서로 맞춘다.
검증: check-docs.py·check-work-docs.py rc=0.
Refs: RR9-04-09, RR9-04-21, RR9-04-35, RR9-04-42, RR9-03-30
PR 전 리뷰(계약·시험 렌즈, 구조 리뷰) 발견을 고친다.
- 상태만 아는 503·429(Spring이 던진 ResponseStatusException 등)가 SERVER_BUSY·
RATE_LIMIT_EXCEEDED로 나가면서 Retry-After를 싣지 않았다. error dispatch는
싣는데 handleExceptionInternal은 안 실었다. registry 값을 같은 advisor로 단다.
- virtual thread admission filter가 보안 chain 앞이라 cross-origin 거절 503에 CORS
헤더가 없어 브라우저가 본문도 Retry-After도 못 읽었고, 인증 없는 요청도 permit을
썼다. chain 바로 뒤(-99)로 옮겼다.
- permit을 한 번만 돌려주는 가드, onTimeout 뒤 onComplete, onStartAsync 재등록을
지키는 시험이 없었다. 둘을 더했다.
- stream 위치 규칙이 writer와 WebStreamEvidence 두 곳에 있었다. 증거에
requireNext를 두고 writer가 쓰기 전에 부른다.
- fileserver Retry-After가 좁히기 식을 복사했고 SERVER_BUSY 값을 두 번 적었다.
ErrorResponseFactory.effectiveRetryable 하나를 같이 쓰고, 공용 이름의 code는
RetryAfterAdvisor 값을 읽는다. 재시도 불가 code 전부가 헤더를 싣지 않는지 본다.
- batch 전체 성공의 results[]에 "error": null이 나갔다. 항목 record가 null을
생략한다. batch 시험은 envelope wire 규칙을 실은 mapper로 키 집합을 본다.
- 알림 channel·locale 파싱이 두 controller에 있었다. NotificationVocabulary
하나로 모으고, detail은 web 검증 어휘(INVALID)를 쓴다. 예외 이름을
NotificationFieldRejectedException으로 바꿨다(THROWABLES_ARE_NAMED_EXCEPTION).
template 게시의 거절 시험을 더했다.
- patch 전체 검증 설명에서 상태 전이 예를 뺐다. 검증 대상은 web 표현 DTO이고
업무 규칙은 유스케이스의 것이다.
- web README의 RetryAfterHint 예시, upgrade 안내 행 넷(bulk 문구·null 키, stream
역행 항목, 상태만 아는 503·429의 Retry-After, admission filter 순서)과 부분 실패의
part 짚기(index)를 적었다.
Refs: RR9-03-01, RR9-03-02, RR9-03-06, RR9-03-13, RR9-03-15, RR9-03-23, RR9-03-24, RR9-03-25, RR9-03-27
`mainCheck`는 `:adapter:inbound:graphql:graphqlStableTest`에 기댄다
(build.gradle `mainCheck` 태스크). 그런데 루트 build.gradle Lifecycle 주석과
gates.md 1절 `mainCheck` 행에는 이 lane이 없다. docs/build.md 표는 gates.md
1절을 정본으로 가리키므로 정본이 빠진 셈이다.
build.gradle의 bootstrap 주석은 단계를 「migrate-and-start」로 적는다. 기본
조립은 web뿐이고 persistence-jpa 줄이 꺼져 있어 startup Flyway가 돌지 않는다.
「start」로 고치고, Flyway는 persistence-jpa 줄을 켰을 때만 돈다고 적는다.
동작 변경 없음: build.gradle은 주석만 바꿨다.
검증: scripts/verify.sh docs(노트북) rc=0.
Refs: round9 확인 리뷰(r9-be 그룹 C가 넘긴 Low 둘)
문제:
- application-notification·-fileserver·-objectstorage는 가장 가까운 AGENTS가
루트뿐이고 README가 없었다. web-notification·web-fileserver·redis-runtime도 자기
AGENTS·README가 없었다. 그 leaf를 고치는 세션은 지역 규칙(전송이 이름을 짓지
않음, 포화 코드의 갈림, callback 경로가 절대 경로인 이유 등)을 볼 곳이 없었다.
- docs/README.md 지도의 security/ 행이 rate-limiting.md를 덮지 않았다.
- shared-contract AGENTS 책임 목록이 PageMeta·ResponseMeta·Category·공용 carrier
예외 셋·ServerFailureLog·ActiveTrace를 빠뜨렸다.
- docs/web/repository-adaptation.md가 「애플리케이션 칸은 강제하지 않는다」고
했지만 web은 JSON 본문 1 MiB(app.web.mvc.max-json-body-size, 413)를 강제한다.
- openapi-32-compatibility.md가 아무도 만들지 않는 3.1.2 릴리스 산출물과 3.1
snapshot 불변식을 이 repo의 것처럼 적었다(샘플 삭제 뒤).
고친 것: leaf 여섯에 AGENTS.md(등록 정보, 책임, 규칙, 시험)·CLAUDE.md(@AGENTS.md)·
README.md(책임과 소유하지 않는 것, 공개 표면, 조립, 시험 명령, 더 읽을 곳)를 쓰고,
규칙의 정본은 가리키기만 했다. 지도 행, shared-contract 책임 목록, 본문 한도 표와
머리말, OpenAPI 문서를 고쳤다.
순서: 새 leaf 문서가 계약 PR(batch bulk envelope, 알림 VALIDATION_FAILED,
SERVER_BUSY, 전송이 이름을 짓지 않음)의 동작을 적는다. 그 PR 뒤에 병합한다.
검증: check-docs.py·check-work-docs.py rc=0.
Refs: RR9-04-35, RR9-04-36, RR9-04-42
문제: 살아 있는 문서가 지운 workflow·태스크·job과 옛 동작을 가리켰다.
- 단계 구성이 네 곳에 따로 적혔고 둘이 틀렸다. TESTING_STRATEGY의 repository
목록은 releaseCheck를 「ci + ...」라 했고, docs/build.md의 mainCheck·
qualificationCheck 행은 testQualityCheck·verifyFeatureScaffold·graphqlStableTest를
빠뜨렸다.
- capability-status가 지운 redis-sdk-topology.yml·notification-platform.yml·
verifyNotificationEvidence, app-bootstrap의 OutboxConfig(지금
:composition:outbox-relay), 없는 lane 이름을 증거로 들었다. 제거된 코드 표의
재배치 전 경로는 설명 없이 지금 트리에 없었다.
- docs/build.md·bootstrap-local.sh가 기본 조립이 Flyway를 돈다고 했다(기본은
web뿐). 알림 키 개수를 복사해 틀렸다.
- roadmap messaging-r2가 지운 VerifyMessagingEvidenceTask·
MessagingQualificationPlugin을 예시로 들었다.
- cache-redis README·build.gradle, httpclient build.gradle이 #13이 합친
integration job을 가리켰다.
- renovate.json·취약점 정책이 「두 봇」과 GitHub vulnerability alert를 전제했다.
이 Gitea repo에 Renovate 실행기는 없다.
- graphql AGENTS·README가 「모듈별 yml 금지·없음」이라 했지만 leaf는
config/graphql.yml을 직접 읽는다. 지운 execution profile을 적었다.
고친 것: 단계 구성은 gates.md 1절과 루트 build.gradle을 정본으로 가리키고, 남긴
표 행은 지금 태스크대로 고쳤다. capability-status 행 넷을 지금 job·태스크·모듈로
고치고, 제거된 코드 표의 경로가 지운 때의 배치라는 머리말과 지운
ComposeMergeCharacterizationTest 행을 더했다. 기본 조립·Flyway 설명, 알림 키(개수
대신 registry), roadmap(`> 이력`), 세 integration 설명(`main` job이
:integrationCheck :mainCheck를 함께 돈다), renovate·정책(실행기 없음, enforced는
trivy), graphql 설정 파일 설명을 고쳤다.
검증: check-docs.py·check-work-docs.py rc=0, 이 문서들을 읽는 시험은
CapabilityStatusDocumentTest(app-bootstrap document-contract)다.
Refs: RR9-04-09, RR9-04-10, RR9-04-20, RR9-04-21, RR9-04-22, RR9-04-25, RR9-04-28, RR9-03-30
문제: 서버 쪽 상한이 찬 거절이 전송마다 다른 코드였다. web-advanced는
ADMISSION_REFUSED(503), fileserver는 instance·전송 pool 포화까지
TRANSFER_ADMISSION_REJECTED(429 RATE_LIMIT), gRPC는 RATE_LIMIT_EXCEEDED
(RESOURCE_EXHAUSTED, "요청이 너무 잦습니다")였다. client는 자기 빈도 탓인지 서버
포화인지 가를 수 없었다. web은 상태만 아는 모든 503을 REQUEST_TIMEOUT으로 답했다
(§4는 비동기 시간 초과만). §4에 OPERATION_NOT_FOUND가 없었고, fileserver 오류
code 27개 중 23개가 계약 문서에 없었으며 예시가 "data": null을 실었다. fileserver는
Retry-After를 발생만 보고 붙여, 본문이 retryable=false로 좁힌 code에도 헤더가
나갔다. gRPC Javadoc과 graphql 스냅숏 머리말이 지운 이름(WORKLOG_NOT_FOUND, spi)을
적었다.
고른 방법(리뷰 README 6절 ②):
- 공용 OperationalError.SERVER_BUSY(503, TRANSIENT_DEPENDENCY, retryable,
Retry-After 1)를 더했다. registry 행, RetryAfterAdvisor, runbook
server-busy.md를 같이 둔다.
- web-advanced admission 거절, gRPC call admission(UNAVAILABLE), fileserver의
instance permit·직접 다운로드 permit·전송 pool 포화가 이 코드다. fileserver는
같은 이름의 FileserverErrorCode.SERVER_BUSY를 두고, 이름이 같은 code의 뜻이
같은지 FileserverExceptionTest가 이미 본다. 호출자 자기 scope의 동시 전송
초과만 TRANSFER_ADMISSION_REJECTED 429로 남는다.
- 상태만 아는 503은 SERVER_BUSY, AsyncRequestTimeoutException만
REQUEST_TIMEOUT이다(HttpStatusErrorCodes.forException).
- fileserver Retry-After는 본문과 같은 규칙(code와 발생이 모두 retryable)으로
붙인다. 재시도 불가 code인 ATOMIC_PUBLISH_UNSUPPORTED를 표에서 뺐다.
- docs/fileserver/http-contract.md에 오류 code 표 전체를 두고 예시의 data:null을
지웠다. http-contract §4에 OPERATION_NOT_FOUND와 SERVER_BUSY를 적었다.
- decisions 2.3에 결정 ①②③ 행을 더했다.
- 포화 시험의 sleep(200)을 첫 거절 신호로 바꾸고, timeout 시험이 code까지
본다(같은 파일이라 RR9-03-20의 그 부분을 여기서 고친다).
- web-advanced 파일의 spotless 정리(앞 커밋분)를 함께 싣는다.
버린 대안: JOB_EXECUTOR_REJECTED를 재사용 — 백그라운드 job 이름이라 요청 허가
거절을 읽는 client와 runbook을 잘못 이끈다.
위험·한계: 포화 거절로 분기하던 client와 재시도 정책, WebAdvancedError
.ADMISSION_REFUSED를 참조하던 코드, 모든 503을 REQUEST_TIMEOUT으로 보던 client가
바뀐다(upgrade 안내 8·9·13).
BREAKING CHANGE: 서버 포화 코드가 SERVER_BUSY 하나다(web-advanced
ADMISSION_REFUSED 삭제, fileserver instance·pool 포화 429 → 503, gRPC
RESOURCE_EXHAUSTED → UNAVAILABLE). 상태만 아는 503은 SERVER_BUSY다. 할 일은
docs/upgrade/2026-11-round9-contracts.md.
Refs: RR9-03-06, RR9-03-07, RR9-03-11, RR9-03-12, RR9-03-15, RR9-03-16, RR9-03-20
문제: fileserver·notification의 HTTP 표면이 공용 계약(web AGENTS B8,
http-contract §1, manual 11)과 달랐다.
- fileserver batch는 part가 실패해도 success:true였고 결과를 data.results에
넣었다. fullySucceeded()를 아무도 부르지 않았다. 계약끼리도 달랐다(web B8의
BATCH_PARTIAL_FAILURE vs fileserver 계약의 200 + results[].error).
- BulkEnvelope.partial의 error.message가 영어 고정 문구였고, BulkItemResult는
호출자 문구를 그대로 실었으며 null 키를 남겼다(mix-in 없음).
- Content-Range가 CORS 노출 목록에 없어 브라우저가 다운로드를 이어 받지 못했다.
- 알림 제출·template 게시의 모르는 channel·slot·locale이 details 없는
BAD_PARAMETER였고(주석은 validation error), template 경로가 lowerCamel이 아닌
/notification-templates였다.
- 전송 넷(raw·multipart·draft-12·tus)이 이름 없는 업로드에 "upload.bin"을
지어 넣었다. 앱 정책 OriginalFilenamePolicy의 기본값은 "file"이라 업무 규칙이
두 곳에 있었다(HARD-STOP 4).
- EnvelopeWireShapeTest는 http-contract §1의 증거로 쓰이는데 data null 키 생략,
String → Envelope, unsorted page의 sort:null, 부분 실패 문구를 보지 않았다.
고른 방법:
- 리뷰 README 6절 ①대로 fileserver batch도 공용 bulk envelope다. 모두 성공 →
success:true + results, 하나라도 실패 → success:false + BATCH_PARTIAL_FAILURE +
part별 details(index, status, id, code, message). 성공한 part는 되돌리지 않는다.
BatchUploadResponse는 쓰는 곳이 없어져 지웠다.
- BulkEnvelope.partial과 BulkItemResult.error(index, ApiErrorCode)는 category
고정 문구를 쓴다. BulkItemResult에 null 생략 mix-in을 더했다.
- 알림 controller는 NotificationFieldRejection(VALIDATION_FAILED carrier, 필드를
짚는 details 하나, 거절한 값은 싣지 않음)을 던진다. template 경로는
/notificationTemplates다. 읽는 endpoint가 없어 201에 Location을 싣지 않고,
manual 11 규칙에 그 경우를 적었다.
- 전송은 이름이 없으면 빈 이름을 넘기고 OriginalFilenamePolicy가 정한다.
- EnvelopeWireShapeTest에 빠진 넷을 더했다. EnvelopeTest의 when 둘인 시험을
둘로 나눴다.
버린 대안: /notification-templates를 별칭으로 남기기 — 같은 자원의 경로가 둘이
되고 인가·공개 경로 스냅숏이 둘을 따로 봐야 한다.
위험·한계: batch를 읽는 client, 알림 template 경로를 쓰는 client와 배포
스크립트, BulkItemResult.error(index, code, message)를 부르던 코드가 바뀐다
(upgrade 안내 6·7·10·11·12, 14).
BREAKING CHANGE: fileserver batch 응답이 공용 bulk envelope가 됐다. 알림
template 경로가 /notificationTemplates다. 알림의 모르는 vocabulary 값은
VALIDATION_FAILED다. BulkItemResult.error는 ApiErrorCode를 받는다. 이름 없는
업로드의 표시 이름이 "file"이다. 할 일은 docs/upgrade/2026-11-round9-contracts.md.
Refs: RR9-03-01, RR9-03-02, RR9-03-09, RR9-03-13, RR9-03-21, RR9-05-09
문제: web-advanced의 계약 문서와 코드가 다섯 곳에서 갈렸다.
- patch 거부가 세 코드로 갈렸다. 형식 오류는 PATCH_REJECTED(400), 빈
문서·연산 모양 오류·merge 깊이 초과는 IllegalArgumentException이라
BAD_PARAMETER(400), 너무 깊은 pointer는 권한 거절 PATCH_PATH_FORBIDDEN(403)
이었다. JSON이 아닌 본문과 결과가 대상 타입으로 읽히지 않는 patch는
Jackson 예외로 catch-all에 닿아 500 INTERNAL_ERROR였다.
- patch-contract.md는 결과를 문서 전체로 검증한다고 했지만 두 applier는
검증기를 받지 않았다.
- streaming-contract.md는 서버가 위치 증가를 강제하고 heartbeat·idle·max
age·버퍼 상한·drain 재연결을 한다고 했다. MvcStreamWriter는 그 어느 것도
하지 않았다.
- commit 뒤 Failure 기록이 어디에도 등록되지 않은 DEPENDENCY_FAILURE로
고정이라, STREAM_ITEM_TOO_LARGE 같은 carrier 코드가 사라졌다.
- virtual thread profile은 503 + Retry-After를 약속했지만 admission guard는
bean만 있었고 요청 경로에서 아무도 부르지 않았다.
- web AGENTS B2는 merge patch를 쓰지 않는다고 했고 patch-contract는 필드
변경에 merge patch를 쓰라고 했다(정본 충돌).
고른 방법:
- 형식이 틀린 patch 문서는 모두 JsonPatchRejectedException(PATCH_REJECTED)
이다. 본문 파싱과 결과 변환은 PatchBodies가 감싼다. 너무 깊은 pointer는
권한 검사 앞에서 400으로 거절한다. 대상 타입이 객체가 아닌 것은 서버
결함이라 IllegalStateException이다.
- 두 applier가 Bean Validation Validator를 받아 결과 객체 전체를 검증한다.
위반은 @Valid 본문과 같은 ConstraintViolationException → VALIDATION_FAILED.
- writer는 위치가 앞 항목보다 크지 않으면 그 항목을 쓰지 않고 INTERNAL_ERROR
Failure 기록으로 끝낸다. Failure 기록은 cause 사슬의 carrier 코드, 없으면
INTERNAL_ERROR, 문구는 category 고정 문구다.
- writer가 할 수 없는 것(heartbeat, idle·max age, 버퍼, drain)은 계약
문서를 고쳐 누가 하는지(WebStreamPolicy·Registry·DrainCoordinator를 쓰는
서비스) 적었다. 요청 thread의 동기 writer라 heartbeat를 넣으려면 thread
모델을 바꿔야 해서 버렸다.
- VirtualThreadAdmissionFilter가 모든 요청을 guard 아래 둔다(request-id
filter 바로 뒤). async 요청은 async가 끝날 때 permit을 돌려준다. guard에
Permit API를 더했다.
- 정본 충돌은 리뷰 README 6절 ③대로 patch-contract를 정본으로 두고 web
AGENTS B2가 그쪽을 가리킨다.
위험·한계: patch를 쓰는 서비스는 applier 생성자에 Validator를 넘겨야
컴파일된다. client가 보는 patch·stream 오류 코드가 바뀐다. virtual thread
profile을 켠 배포는 처음으로 상한에 걸릴 수 있다(upgrade 안내 1~5).
BREAKING CHANGE: JsonMergePatchApplier·JsonPatchApplier 생성자가 Validator를
받는다. patch 거부는 모두 PATCH_REJECTED(400), 결과 제약 위반은
VALIDATION_FAILED, stream Failure 코드는 실패의 코드나 INTERNAL_ERROR다. 할
일은 docs/upgrade/2026-11-round9-contracts.md.
Refs: RR9-03-23, RR9-03-24, RR9-03-25, RR9-03-26, RR9-03-27, RR9-03-28
- 2절: 기준 main 단계 결과(rc=0, 시험 1867건 실패 0, skip 19)와 pr 단계
시험 수를 적고, 「6절에 적는다」던 잘못된 가리킴을 지웠다. nightly·release
기준 실행을 접은 이유를 적었다.
- 4절: 열린 PR 번호(#16#19#20#21#22#23#24)와 병렬 그룹 A·B·C 표.
- RR9-03-30(Medium): compose 병합 특성 시험이 어느 lane에서도 돌지
않았다(integrationTest lane이 requires 클래스 넷만 고른다). B19(PR #24)가
고친다. 색인과 03-contract-testing.md에 더해 모두 153건이다.
검증: check-review-index.py(153/153), check-docs.py, check-work-docs.py rc=0.
문제: 기본 compose.yaml은 -XX:HeapDumpPath=/var/tmp/heap을 512m tmpfs로
붙였다. 컨테이너는 mem_limit 512m·swap 없음이고 힙은 그 75%(384m)다.
tmpfs에 쓴 페이지는 같은 컨테이너 메모리 한계에 잡힌다. 그래서
OutOfMemoryError 때 덤프를 쓰는 동안 컨테이너가 OOM kill(137)될 수 있었고,
runbook이 기대하는 깨끗한 끝(코드 3, ExitOnOutOfMemoryError)이 사라졌다.
덤프가 끝까지 써져도 tmpfs는 컨테이너가 끝나면 함께 사라져 읽을 수 없었다.
Dockerfile 주석은 오케스트레이터에 그 경로를 tmpfs로 붙이라고 했고,
internal-error-spike runbook은 없는 파일 이름(heapdump-<pid>.hprof)을 적었다.
고른 방법:
- 기본 compose.yaml은 그 경로에 아무것도 붙이지 않는다. 루트가 읽기
전용이라 JVM은 파일을 만들지 못하고 바로 코드 3으로 끝난다. 덤프를 남기는
dev lane(named volume heap-dumps)은 그대로다.
- scripts/verify-compose-profile-contracts.sh(prCheck의
verifyComposeProfiles)가 모든 lane에서 그 경로의 tmpfs를 거절한다. 경로는
Dockerfile의 -XX:HeapDumpPath에서 읽는다.
- Dockerfile 주석과 runbook 둘(runtime-jvm-oom 「진단」, internal-error-spike)에
덤프를 남기는 법(Kubernetes emptyDir without medium: Memory·PV, dev lane
volume)과 실제 파일 이름(java_pid<pid>.hprof)을 적었다.
- 버린 대안: 기본 compose에 named volume을 붙이기 — 기본 조립은 디스크에
아무것도 남기지 않는다는 결정(compose.yaml 「No volume」 주석)과 다르다.
- 고치며 찾은 것(RR9-03-30): ComposeMergeCharacterizationTest는 어느 lane에서도
돌지 않았다. integrationTest lane은 requires로 적은 클래스 넷만 고른다
(StrictTestLanePlugin). 그 시험이 보던 기본·dev 조합 렌더링과 계약 스크립트는
verifyComposeProfiles가 18개 lane으로 이미 본다. 시험과, 그 lane에 compose
파일을 입력으로 선언하던 블록을 지웠다.
검증(desktop):
- RED: 기준 ca1fbfde + 검사 스크립트만으로 :verifyComposeProfiles 실패
(기본 compose를 쓰는 lane마다 「heap dump path ... as a tmpfs」).
- 탐침(eclipse-temurin:21-jdk, 읽기 전용 루트, 메모리 192m·swap 없음,
-Xmx96m으로 OutOfMemoryError):
경로에 아무것도 없음 → "Unable to create /var/tmp/heap: Read-only file
system", 코드 3. tmpfs → 덤프를 쓰다 코드 137(OOM kill). 디스크 마운트 →
덤프 101MB가 남고 코드 3.
- GREEN: :verifyComposeProfiles(18 lane), :app-bootstrap:integrationTest,
repositoryContractTest, spotlessCheck — 71건 실패 0, skip 1, rc=0.
문제: 공개 경로 스냅숏(publicPathSnapshotTest)은 config/security.yml의
기본값 한 줄만 읽었다. 문서(docs/build.md, gates.md 「공개 경로·보안 체인」)는
보안 체인 전체를 지킨다고 했다. 그래서 둘이 검사를 지나갔다.
- application-local.yml이 public-paths를 /api/healthcheck로 덮는다.
- web-notification의 callback chain이 /internal/notification/callbacks/**를
anyRequest().permitAll()로 연다. actuator chain의 health·info·prometheus도
같다.
docs/build.md는 지운 PublicPathSnapshotPlugin.java와 없는
updatePublicPathSnapshot 태스크를 승인 방법으로 적었다.
관리 포트도 문서와 compose가 갈렸다. 관리 포트가 컨테이너 loopback에 묶인
뒤(MANAGEMENT_SERVER_ADDRESS 기본 127.0.0.1) compose.yaml·dev lane의
127.0.0.1:9001 publish는 아무것도 답하지 않는 줄이 됐고, service-runtime
README·Dockerfile은 Kubernetes 프로브가 닿는다고 적었다. dev lane은 원격
JMX(9999)를 인증·TLS 없이, jmxremote.host 없이 열었다(주석은 「localhost
only」).
고른 방법:
- 스냅숏에 두 절을 더한다. profile 파일이 public-paths를 리터럴로 덮으면
그 값, 모든 leaf 운영 코드에서 Spring Security를 import한 파일의
permitAll·securityMatcher 문장(파일 경로와 함께, 정렬). 그 소스와 baseline을
lane 입력으로 선언해 캐시가 변경을 놓치지 않게 했다.
- 기동한 SecurityFilterChain의 matcher를 reflection으로 읽는 안은 버렸다.
matcher가 Spring의 private 필드에 있어 버전마다 깨진다. 문장 글자만 보므로
상수로 만든 matcher의 값은 못 본다. 그 한계를 docs/build.md에 적었다.
- 관리 포트 publish 줄과 dev lane JMX를 지웠다. 컨테이너 안에서 읽는 명령
(docker compose exec app wget …, jcmd)을 주석에 적었다. Kubernetes는
MANAGEMENT_SERVER_ADDRESS를 바꾸거나 sidecar로 읽어야 한다고
service-runtime README·Dockerfile·docs/build.md에 적었다.
위험·한계: 파생 서비스가 자기 chain이나 profile 덮어쓰기를 두었다면 merge 뒤
스냅숏이 실패한다. 읽고 승인하면 된다(upgrade 안내 1). dev lane에서 원격
JMX로 보던 사람은 jcmd로 바꾼다(안내 4).
검증(desktop, --no-build-cache):
- RED: 기준 a7e38c10에 permitAll chain을 더한 탐침 트리에서 기존
publicPathSnapshotTest가 통과했다(rc=0) — 틈이 있다.
- GREEN: spotlessApply 뒤 :app-bootstrap:test --tests '*PublicPathSnapshotTest'
(새 렌더링 시험 둘), :app-bootstrap:publicPathSnapshotTest,
repositoryContractTest, spotlessCheck, :verifyComposeProfiles(18 lane) —
67건 실패 0, skip 1, rc=0.
- 변이: 새 스냅숏을 커밋한 트리에서 callback chain의 securityMatcher를
"/internal/**"로 넓히면 publicPathSnapshotTest가 실패한다.
BREAKING CHANGE: 공개 경로 스냅숏이 profile 덮어쓰기와 모든 모듈의
permitAll·securityMatcher 문장을 본다. compose가 관리 포트 9001과 dev lane
JMX 9999를 publish하지 않는다. 할 일은
docs/upgrade/2026-11-round9-public-surface.md.
문제: 모듈 README·AGENTS·매뉴얼·Javadoc이 옮기거나 이름을 바꾼 타입,
지운 샘플, 다른 repo로 옮긴 플랫폼을 그대로 가리켰다.
- 옮기거나 바꾼 타입: OutboxConfig(지금 :composition:outbox-relay의
OutboxRelayAutoConfiguration), IdempotencyProviderSelectionConfig(지금
:composition:idempotency의 IdempotencyAutoConfiguration),
TracingProperties·GraphQlPlatformProperties(지금 *Settings), SecretSource
(지금 application-core SecretSourcePort), JsonNullableModule(지금
JsonNullableJackson3Module), PeriodTest·OutboxEventIdFactory(샘플과 함께
지움).
- 지운 샘플: SampleDemoProfilesStartupSystemTest, 「sample 테스트」,
IdempotencyAutoConfiguration·ManagementSecurityConfig Javadoc의 샘플.
- 옮긴 플랫폼: graphql AGENTS·README가 messaging 플랫폼과 「두 패턴 공존」을
적었지만 그 플랫폼은 2026-11-08 messaging-library로 옮겼다. gRPC 문서는
grpc-library로 옮긴 플랫폼을 「vendored」·「벤더 starter」로 불렀다.
- leaf CLAUDE.md를 가리키던 곳(지금 AGENTS.md), 복사한 숫자(httpclient
java 파일 수, graphql systemTest 수), manual 06의 registry 머리말 옛 영어 인용.
고른 방법: 문장이 가리키는 대상만 지금 이름으로 바꾼다. 동작 설명은 그대로
둔다. 숫자는 지운다(레지스트리·빌드가 정한다).
검증:
- 노트북: check-docs.py rc=0. check-work-docs.py는 main의 operate.md 151줄
때문에만 rc=1.
- desktop(--no-build-cache, 트리 310eb524): 이 문서들을 읽는 시험
(:app-bootstrap:documentContractTest, repositoryContractTest —
DeveloperExperienceContractTest 포함, MongoNamespaceContractTest,
AwsQualificationClaimHonestyTest)과 Javadoc을 고친 두 leaf의
compileJava·spotlessCheck. 134건 실패 0, skip 1.
문제: docs/registries/env-keys.yaml·.env.example·배포 설정(profile 밖의
application.yml, config/*.yml, 모듈 module-defaults)이 서로 갈렸고
verifyEnvKeys는 그 차이를 보지 못했다.
- .env.example을 복사하면 기동이 실패하는 값이 있었다:
APP_DATASOURCE_CONNECTION_TIMEOUT=5s(Hikari long ms, registry 주석이
"기동 실패"라고 적은 그 값), APP_SECURITY_CORS_MAX_AGE=600s(long 초).
- 기본값과 다른 예시 값: cache·rate-limit Redis command timeout(2s·1s vs
200ms), APP_LOG_LEVEL_SQL(WARN vs INFO), FORWARD_HEADERS_STRATEGY(native
vs none — 프록시 없는 배포에서 forwarded 헤더를 믿게 된다),
POSITIVE_SOFT_TTL(빈 줄 — 빈 문자열이 기본값을 덮는다).
- registry가 폐기(deprecated_orphaned)로 적은 키 셋을 cache-redis 모듈 설정이
읽는다(COMMAND_TIMEOUT, SEMANTIC_REGION, KEY_HMAC_SECRET 참조).
- 폐기 키 45개가 .env.example에 값과 함께 남아, 복사하면 아무 일도 하지 않는
값을 켠 것으로 믿는다. 검사가 오히려 registry의 모든 APP_ 행을 예시에
요구해 폐기 행도 넣게 했다.
- 배포 설정이 읽는 APP_ 밖 placeholder 11개(SECURITY_PUBLIC_PATHS,
PRESENTATION_API_BASE_PATH, SPRING_JACKSON_DESER_* 등)에 registry 행이
없었다. 검사가 APP_ 이름만 보고, registry 파서도 APP_ 행만 읽어
MANAGEMENT_SERVER_ADDRESS 같은 행이 보이지 않았다.
- .env.example 머리말은 "빈 키는 기본값을 쓴다", "Seven values"라고 적었다.
고른 방법: 런타임 동작은 바꾸지 않고 registry와 예시를 배포 설정에 맞춘다.
그리고 verifyEnvKeys가 다섯을 더 본다.
1. registry 행은 접두어와 상관없이 읽는다.
2. 배포 설정의 placeholder는 접두어와 상관없이 행이 있어야 한다.
3. deprecated_orphaned 행은 배포 설정이 읽지 않고 .env.example에 없다.
4. .env.example 값은 registry default(행에 example이 있으면 그 값)와 같다.
빈 줄은 빈 문자열로 본다.
5. profile 밖 배포 설정의 placeholder 기본값은 registry default와 같다.
registry에 example 칸을 두었다(SMTP 587·timeout처럼 기본값이 아닌 권장값).
APP_ 밖 이름 11개는 지금 이름 그대로 등록했다. 바꾸면 파생 서비스의 배포
env가 소리 없이 무시된다. 이름 변경은 소유자 결정이다. registry 머리말을
실제 규칙(SPRING_·MANAGEMENT_·SERVER_·OTEL_ 이름공간과 옛 이름 둘)으로
고쳤다. gRPC를 켜려면 꼭 두는 APP_GRPC_SERVER_ALLOW_INSECURE_LOCAL과
.env.example의 MANAGEMENT_SERVER_ADDRESS를 더했다.
버린 대안: SECURITY_PUBLIC_PATHS·PRESENTATION_API_BASE_PATH를 APP_로 바꾸고
옛 이름을 fallback으로 두기 — 공개 경로 기본값이 4중 placeholder가 되고
공개 경로 스냅숏 파서까지 바꿔야 한다. 이름 정리는 따로 정한다.
위험·한계: 파생 서비스가 자기 placeholder를 등록하지 않았거나 예시 값이
기본값과 다르면 이제 verifyEnvKeys(mainCheck)가 실패한다(upgrade 안내 5·6).
예시 값이 바뀌어 옛 예시를 복사한 .env는 그대로 둔다 — 안내 1~4가 고칠
값을 적는다.
검증(desktop, --no-build-cache):
- RED: 기준 a7e38c10 + 시험만으로 EnvContractVerifierTest 22건 중 7건 실패
(새 검사 6건 + 메시지를 바꾼 기존 1건). 새 지킴 시험(example 행 통과)은
기준에서도 통과.
- GREEN: -p build-logic test, :app-bootstrap:verifyEnvKeys(314 env keys, 6
required placeholders, 370 rows), :app-bootstrap:test·repositoryContractTest·
documentContractTest, registry·예시를 읽는 leaf 시험(httpclient env
manifest, notification mode, redis-runtime required_when, support,
fileserver·notification platform, graphql registry parity, web CORS)
682건 실패 0, skip 5. rc=0.
BREAKING CHANGE: verifyEnvKeys가 접두어 밖 placeholder, 폐기 행의 사용,
예시·기본값 차이를 실패로 본다. .env.example에서 폐기 키가 빠지고 값 여덟이
기본값으로 바뀌었다. 할 일은 docs/upgrade/2026-11-round9-env-keys.md.
문제: 저장소 전체 ArchUnit suite가 약속한 것을 막지 못하는 길이 다섯이다.
1. controller가 domain repository 포트(생성 명령이 aggregate 옆
dev.caskeleton.domain.<feature>에 두는 <Aggregate>Repository)를 주입해도
걸리지 않는다. 규칙은 ..repository.. 패키지와 Spring Data·JPA 타입만 본다.
gRPC 서비스는 controller 판정에 들지 않는다(HARD-STOP 2).
2. ..adapter.inbound.. 밖의 사용자 전송(조립 모듈의 controller 등)이
@SystemInvoked 유스케이스를 new로 만들어 부르거나, 표시 없는 중간 클래스를
거쳐 부르면 통과한다. 매뉴얼 07은 이것을 "빌드 실패"라고 약속한다. app
AGENTS의 "bootstrap에 controller 금지"도 검사가 없다.
3. web 패키지 밖에 둔 Spring Security 요청 경로 확장점(JWT converter,
AuthorizationManager, AuthenticationProvider, 필터 chain DSL)은 servlet 타입을
쓰지 않아 사용자 전송으로 보이지 않는다.
4. 설정이 interceptor를 자기 클래스 타입 필드로 쥐고
registration.interceptors(x)로 넘기면, ArchUnit 1.3은 ChannelRegistration
(설정용 타입)만 기록해 설정이 사용자 전송이 되지 않는다.
5. capabilityProjects에 :adapter:inbound:messaging이 없어 저장소 전체 suite가
MessagingInboxAutoConfiguration을 읽지 않는다("suite가 모든 모듈을 본다"는
주석과 다름).
고른 방법:
1. ENDPOINTS_DO_NOT_HOLD_PERSISTENCE_PORTS: controller와 gRPC 서비스는
..domain..·..application..의 *Repository·*StorePort·*QueryPort에 의존하지
않는다.
2. CONTROLLERS_LIVE_IN_INBOUND_ADAPTERS, 그리고
USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS의 전이 대상에 @SystemInvoked
유스케이스 자신을 더한다.
3. org.springframework.security.web·config.annotation.web·
oauth2.server.resource·oauth2.jwt 패키지와 AuthenticationProvider·
AuthorizationManager를 사용자 전송·요청 처리기 목록에 더한다.
4. 설정이 의존하는 프로젝트 클래스가 요청 처리기 타입을 상속·구현하면 그
설정도 사용자 전송으로 본다.
5. capabilityProjects와 주석 처리된 runtimeOnly 줄에 inbound messaging을 더한다.
매뉴얼 07 표와 app AGENTS를 같이 고쳤다. 지금 운영 코드에 걸리는 곳은
없다(inbound가 그런 포트를 import한 곳 0, 조립 모듈 controller 0).
버린 대안: inbound가 application *Port 전부를 못 쓰게 하기 — web이
AuthorizationPort·CorrelationIdPort를 구현하고 쓰므로 맞는 코드가 걸린다.
IdFactory는 지금 DurableOperationController가 쓰고 있어 이번 규칙에서 뺐다
(그 controller의 id 생성은 리뷰 RR9-05-13로 따로 고친다).
위험·한계: 규칙 3·4는 목록·클래스 의존 방식이라, 목록에 없는 보안 타입이나
타입 이름이 남지 않는 길(bean 이름 조회, 함수로 감싸 넘기기)은 여전히
못 본다(매뉴얼 07 「규칙이 못 보는 길」). gRPC 서비스 fixture는 io.grpc가
architectureTest 컴파일 classpath에 없어 두지 않았다 — 판정은
BindableService 이름으로 한다.
검증(desktop, --no-build-cache):
- RED: 기준 a7e38c10 + 새 fixture와 시험(새 규칙 대신 기존 규칙을 부르는
변형)만으로 ArchitectureViolationFixtureTest 204건 중 5건 실패 — 다섯 위반
모두 기존 규칙에 안 걸림. 허용 시험은 통과.
- GREEN: :app-bootstrap:resolveAndLockAll --write-locks(잠금 변화 없음),
spotlessApply 뒤 :app-bootstrap:architectureTest 259건 실패 0,
:app-bootstrap:testQualityCheck, :app-bootstrap:spotlessCheck,
:verifyDependencyLocks, :architectureCheck rc=0. 로그 desktop
~/r9-be-logs/b14-{red,green2}.log.
Refs: docs/reviews/2026-11-12-round9-review RR9-05-01~05