@RequiresPermission이 web 밖에서 늘 거부한다. gRPC·STOMP는 인증한
호출자를 SecurityContext에 넣지 않아 권한 있는 호출자도 거부되고, 거부는
web 403, gRPC INTERNAL+ERROR, GraphQL 가린 INTERNAL_ERROR+ERROR로 갈린다.
GraphQL 정책은 하위 좌표(User.salary) 규칙을 받고 판정하지 않는다. 배포
jar가 SPRING_PROFILES_ACTIVE=test로 떠 prod 검사가 꺼진다. JWT 변환은
최상위 roles claim을 권한으로 읽고, sub 없는 token을 통과시켜 뒤에서 500이
되고, 틀린 tenant claim을 AUTH_TOKEN_MALFORMED로 본다. 모르는 profile의
알림 callback은 500+ERROR이고 공격자 문자열을 감사 WARN에 남긴다. patch
거부는 요청이 쓴 이름을 제한 없이 되풀이한다. tenant 입력 이름 거부가
web·GraphQL에서 갈리고, 익명 GraphQL tenant 출처가 SYSTEM이다. STOMP
거부는 자기 로그가 없고 설정 주석이 순서를 틀리게 적는다.
- AuthorizationDeniedException을 AUTHZ_INSUFFICIENT_PERMISSION carrier로
만들고 method security가 그것을 그대로 던진다. 전송마다 이미 있는
carrier 대응이 같은 코드로 답한다(gRPC PERMISSION_DENIED, GraphQL
FORBIDDEN). 버린 안: 전송마다 AccessDeniedException 대응 추가(네 곳에
같은 표를 둔다).
- gRPC listener callback과 STOMP frame 처리 동안 호출자를 SecurityContext에
둔다(spring-security-core 의존, lockfile 갱신). Authentication이면
그대로, 아니면 권한 없는 인증 token이다. 역할은 AuthenticatedPrincipal
에서만 읽는다.
- GraphQL 실행 전 판정이 fragment를 한 번씩 펼치며 typed parent로 좌표를
모은다. root는 늘, 하위 좌표는 규칙이 있을 때 판정하고 interface·구현
좌표의 규칙도 본다.
- 배포 산출물은 test profile을 기동 실패로 거부한다.
- JWT: 최상위 roles를 버리고, sub 없음·틀린 tenant는 401
AUTH_CLAIM_MAPPING_FAILED다.
- callback은 profile을 먼저 찾고 없으면 감사 없이 400이다
(ProviderCallbackAdapterRegistry.require → find).
- patch 거부는 이름을 16개·128자·안전 문자만 되풀이한다.
- tenant 입력 이름 어휘를 TenantId.namesATenant 하나로 모으고, 익명
GraphQL 출처를 ANONYMOUS로 둔다(값 public, 거부는 하지 않는다 — 공개
DataLoader가 그 tenant로 돈다).
- STOMP 거부는 사유·command만 담은 WARN 한 줄을 남긴다(session id는
SockJS가 client URL에서 받아 뺀다).
- 고치며 찾음: decoder를 만든 뒤 JWKS 재조회를 IdP가 받지 않으면 라이브러리
문구("…decode the Jwt: <HTTP 오류>") 때문에 401 AUTH_TOKEN_MALFORMED로
분류됐다. 원인 사슬의 HTTP·I/O 실패를 먼저 보고 503
AUTH_JWKS_UNAVAILABLE로 답한다.
위험: 응답이 바뀐다(gRPC·GraphQL 거부 코드, sub 없음 401, JWKS 재조회
실패 503, 모르는 callback 400, test profile 기동 실패). 할 일은
docs/upgrade/2026-11-round9-authz.md 1~11행이다. registry 구현은 find를
구현해야 컴파일된다.
검증: desktop에서 바뀐 leaf check·systemTest, :app-bootstrap:test·
architectureTest·documentContractTest, verifyDependencyLocks rc=0. 새
시험은 고치기 전 트리에서 실패했다(RED).
Refs: RR9-02-02, RR9-02-16, RR9-02-17, RR9-02-18, RR9-02-20, RR9-02-23,
RR9-02-25, RR9-02-28, RR9-02-29
BREAKING CHANGE: gRPC·GraphQL 권한 거부 코드, JWT sub 없음·틀린 tenant
응답, 모르는 알림 callback 응답, test profile 기동, registry require→find
가 바뀐다. 옮기는 법은 docs/upgrade/2026-11-round9-authz.md 1~11행.
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.