round9 그룹 A의 예측 줄은 장부에 있지만 실측 줄이 없다. PR 셋이 같은
파일 끝을 건드리면 충돌하므로 세 PR이 모두 병합된 뒤로 미뤘다.
실측(작업 중 215분, 호출 2295, 출력 약 197만 토큰)과 예측을 벗어난
이유(새 눈 리뷰 4라운드, main 이동 두 번, desktop 잠금 대기 중 실행
교체)를 한 줄로 더한다.
위험: 장부에 한 줄을 더할 뿐이다.
검증: ledger.py append가 칸을 검사했다.
Refs: round9 그룹 A
job·outbox·internal-error-spike runbook이 근거를 템플릿 개발 때의 설계
번호(D2·D4·D7·D8, K8S-POD-LC-C2, WAF-REL05-C3, TPE-JDK21-C6,
OUT_OF_BRANCH_SCOPE), 옛 feature 브랜치 이름의 wiki 링크, 커밋 sha
bbe944bd로 적는다. 파생 서비스의 운영자는 그 번호와 브랜치를 찾을 수
없어 근거를 읽지 못한다.
번호마다 그 뜻을 문장으로 쓴다: 한도 없는 queue가 무너지는 이유,
CallerRunsPolicy가 요청 지연을 늘리는 이유, 종료 대기 19s와 k8s grace
period의 SIGKILL, 다시 해도 같은 오류는 곧바로 DLQ로. PARKED가 생긴
버전은 커밋 sha 대신 V22 migration으로 가리킨다. 「관련 branch」 줄은
지우고, 「관련 runbook」의 wiki 링크는 상대 링크로 바꾼다.
위험: 문서만 바뀐다. 절차와 SQL 블록은 그대로다.
검증: python3 scripts/check-work-docs.py --history docs/runbooks에서
걸린 줄 0, check-docs.py OK.
Refs: round9 그룹 A 범위 밖 후속 6
gRPC handler가 부른 @RequiresPermission 유스케이스가 권한 없는 호출자를
PERMISSION_DENIED로 돌려보내는지는 조각마다의 단위 시험으로만 본다.
인터셉터가 SecurityContext에 호출자를 두는 것, web method security가
그것을 읽는 것, 거부가 AUTHZ_INSUFFICIENT_PERMISSION carrier인 것,
예외 인터셉터가 그것을 PERMISSION_DENIED로 바꾸는 것이 따로 시험되고,
한 서버에서 함께 돌려 본 시험이 없다.
GrpcRequiresPermissionWireTest가 실제 loopback Netty 서버를 띄우고 web
어댑터의 MethodSecurityConfig·AuthorizationAdapter로 order:close 권한을
판정한다. 권한 없는 호출자는 PERMISSION_DENIED와 trailer
error-code=AUTHZ_INSUFFICIENT_PERMISSION을, 권한 있는 호출자는 같은
유스케이스의 응답을 받는다. 시험에만 :adapter:inbound:web·
:application-core를 testImplementation으로 더하고 lockfile을 다시
만든다. grpcTransportQualificationTest lane이 이 시험을 반드시 돌린다.
버린 안: app-bootstrap integrationTest에 두기. grpc 자동 설정은 모듈이
classpath에 있으면 켜지므로, app-bootstrap 시험 classpath에 grpc를
넣으면 그 leaf의 모든 시험에서 gRPC 서버 설정이 돈다. 운영 의존
(api·implementation)은 그대로라 registry edge는 바뀌지 않는다(의존
방향 검사는 운영 configuration만 본다).
위험: 시험 classpath만 커진다. gRPC lockfile을 자기 쪽에서 고친 파생
서비스는 upgrade 문서 7행대로 lockfile을 다시 만든다.
검증: desktop :adapter:inbound:grpc:check
:adapter:inbound:grpc:grpcTransportQualificationTest
:adapter:inbound:grpc:verifyDependencyLocks, scripts/verify.sh pr.
Refs: round9 그룹 A 범위 밖 후속 5
INTERNAL_AUTH_MISCONFIGURATION의 runbook은 JWT decoder 설정 오류(issuer
discovery 실패, jwks_uri 없음)를 다루지만 파일 이름과 runbook_link는
옛 이름 auth-public-path-misconfiguration이다. 제목만 바꾼 채로 두어
경보에서 링크를 따라온 사람이 공개 경로 문제로 읽는다. 본문이 다
쓰였는데도 status 초안이라 RunbookCoverageContractTest의 임시 목록
LEGACY_STUB_DEBT에 남아 있다.
파일을 auth-decoder-misconfiguration.md로 옮기고 runbook_link를
runbook://auth/decoder-misconfiguration으로 바꾼다. status를 운영으로
올리고 초안 꼬리 문단을 이 runbook이 다루는 범위(템플릿의
JwtDecoderConfig가 내는 신호) 한 줄로 바꾼다. 이 500의 처리로 공개 경로
되돌리기를 안내하던 진단·조치·에스컬레이션 문장은 지우고, 공개 경로
오류는 verifyPublicPathSnapshot이 잡는다는 한 줄만 남긴다. LEGACY_STUB_DEBT에서 빼고,
옛 이름을 가리키던 be-security 스킬·다른 runbook 두 곳을 고친다.
위험: runbook_link 값이 바뀐다. 옛 링크로 경보를 만든 서비스는 upgrade
문서 6행대로 바꾼다.
검증: python3 scripts/check-docs.py·check-work-docs.py OK, desktop
:app-bootstrap:documentContractTest :app-bootstrap:repositoryContractTest,
scripts/verify.sh pr.
BREAKING CHANGE: INTERNAL_AUTH_MISCONFIGURATION의 runbook_link가
runbook://auth/decoder-misconfiguration이다.
Refs: round9 그룹 A 범위 밖 후속 4
web ApiHeaders가 Deprecation·Date 헤더 이름 상수를 공개하지만 운영
코드와 시험 어디에서도 부르지 않는다. 헤더 registry는 지난 변경에서
쓰지 않는 Deprecation 행을 이미 지웠고, 상수만 남아 응답이 그 헤더를
보낸다고 읽힌다.
두 상수와 주석을 지우고 README의 ApiHeaders 절, 시험 도구 MainSources의
Javadoc 예시, docs/capability-status.md 제거 표를 맞춘다.
버린 안: @Deprecated로 한 판 남기기. 템플릿 안에 부르는 곳이 없고,
파생 서비스가 쓰고 있었다면 Spring HttpHeaders.DATE나 자기 상수로
바로 옮길 수 있다.
위험: 그 상수를 부르던 파생 서비스는 컴파일이 실패한다. upgrade
문서 5행이 옮기는 법을 적는다.
검증: desktop :adapter:inbound:web:check, scripts/verify.sh pr.
BREAKING CHANGE: ApiHeaders.DEPRECATION·ApiHeaders.DATE 상수가 없다.
Refs: round9 그룹 A 범위 밖 후속 3
GraphQlResolverObservationConvention·GraphQlDataLoaderObservationConvention
bean이 있지만 Spring for GraphQL observation에 붙지 않는다. 그래서
graphql.datafetcher·graphql.dataloader timer는 Spring 기본 tag
(graphql.field.name, graphql.loader.name, graphql.error.type)를 달고,
플랫폼이 정한 schema 좌표·resolver 무게·batch 크기 tag는 아무 지표에도
없다. 두 convention의 tag 이름도 뜻과 맞지 않는다: 무게를
graphql.operation.type으로, batch 크기를 graphql.complexity.bucket으로
단다. graphql.request는 오류가 없거나 복잡도를 세기 전에 끝난 요청에서
error.type·graphql.complexity.bucket을 빼는데, Prometheus registry는
이름이 같고 key 묶음이 다른 meter를 버린다. 먼저 등록된 쪽만 남고
성공이나 실패 한쪽이 /actuator/prometheus에서 사라진다.
Spring의 DataFetcherObservationConvention·DataLoaderObservationConvention을
구현한 adapter 둘(runtime 패키지)을 두고 GraphQlObservationConfiguration이
@ConditionalOnMissingBean으로 등록한다. resolver는 부모 타입과 field
이름으로 schema 좌표(Type.field)를 만들고, 좌표로 이름 붙일 수 없는
field(_Service.sdl 같은 federation field)는 unnamed와 기본 무게로 같은
key를 단다. DataLoader는 등록한 loader 이름, 또는 Spring이
@BatchMapping loader에 붙이는 schema 좌표(Book.author)를 이름으로 쓰고,
둘 다 아니면 unknown이다. graphql.request는 오류가 없으면
error.type=NONE, 복잡도를 세지 않았으면 graphql.complexity.bucket=unknown을
단다. tag 이름을 graphql.resolver.weight·graphql.batch.size.bucket으로
고치고 cardinality 허용 목록, metrics.yaml 세 행(Micrometer가 다는 error
tag 포함), 공개 API 스냅숏을 맞춘다. 응답 path와 batch key는 싣지 않는다.
버린 안: Spring 기본 convention을 두고 registry만 그 tag로 적기. 플랫폼
convention이 죽은 코드로 남고, field 이름만으로는 타입이 다른 같은 이름
field를 가를 수 없다. 기본 convention을 감싸 tag만 더하는 안은
graphql.error.type이 Micrometer의 error tag와 같은 값을 한 번 더 싣는다.
위험: 세 timer의 tag가 바뀐다. 옛 tag로 거른 대시보드·경보는 비고,
docs/upgrade/2026-11-round9-followups.md 1~4행이 옮기는 법을 적는다.
클래스 이름으로 등록한 loader는 unknown 하나로 묶인다. 자기
DataFetcherObservationConvention·DataLoaderObservationConvention bean을
둔 서비스는 그 bean이 그대로 쓰인다.
검증: desktop :adapter:inbound:graphql:check :adapter:inbound:graphql:systemTest
:adapter:inbound:graphql:verifyGraphQlApiSurface, scripts/verify.sh pr.
BREAKING CHANGE: graphql.datafetcher·graphql.dataloader timer의 tag가
graphql.schema.coordinate·graphql.outcome·graphql.resolver.weight와
graphql.dataloader.name·graphql.outcome·graphql.batch.size.bucket으로
바뀐다. graphql.request는 error.type=NONE·graphql.complexity.bucket=unknown을
단다. 두 convention의 tag key도 바뀐다.
Refs: round9 그룹 A 범위 밖 후속 1
실패한 managed 게시를 다시 하면 APPLIED가 되고, 중단한 stage의 재검증은
IllegalStateException이 되며, 불변 Set capability가 동작한다. 이 셋과
testFixtures의 fake·계약을 쓰는 법을 업그레이드 안내에 적는다.
Refs: RR9-03-31, RR9-03-33, RR9-03-35
문제: capability 기준 5(docs/manual/10-capabilities.md)는 포트를 가진 모듈의
testFixtures에 포트 계약을 두고 fake와 실제 adapter가 모두 통과하게 한다.
application-objectstorage에는 testFixtures도 fake도 없었다. 포트 수준 동작은 adapter
안의 local-dev 시험으로만 봤고, 포트 인터페이스는 결과와 예외를 적지 않았다.
capability-status는 app-bootstrap 통합 시험이 MinIO로 조립한다고 적었지만 실제로는
local-dev다.
고친 것:
- 포트 여덟의 Javadoc에 결과(APPLIED·REPLAYED·REJECTED 등)와 예외 타입을 적었다.
IllegalArgumentException은 요청 그대로를, IllegalStateException은 지금 상태에서의
거절이다. 유스케이스가 감싸 기능 오류로 바꾸고, 설정이 틀린 destination은 조립
오류(500)로 바꾼다(AGENTS 규칙). 예외 메시지는 구현의 것이라 계약이 단언하지 않는다.
- testFixtures testkit: 계약 셋(ManagedObjectStoragePortContract 관리 게시·조회·
전송·복구 조회·회수, StagedObjectPublicationPortContract 단계 게시·handoff·중단,
ObjectScanMaintenancePortContract scan gate), in-memory fake InMemoryObjectStorage,
destination 설명 ObjectStorageDestinationPolicy.
- fake(이 leaf test)와 adapter routing 구현(local-dev, adapter test contract/LocalDev*)이
같은 계약을 상속한다. adapter 쪽 destination 설명은 조립된 policySnapshot에서 읽는다.
- adapter에서 계약이 드러낸 것 둘:
- 실패한 managed 게시를 다시 하면 이번 호출이 게시했는데도 REPLAYED였다(stage 재시도는
APPLIED). 이제 PUBLISHED로 바꾼 호출 하나만 APPLIED다. 같은 key로 겹친 호출은
REPLAYED다(ManagedPublicationOutcomeTest가 겹침을 결정적으로 재현한다).
- 검증한 뒤 중단한 stage를 다시 검증하면 REPLAYED였다. 중단된 operation의 검증을
거절한다.
- 문서: application-objectstorage AGENTS·README, adapter README 「포트 계약」,
TESTING_STRATEGY 9.4, capability-status Object storage 증거 칸.
버린 대안: MinIO에서 포트 계약 돌리기. S3 provider는 readiness registry에서 아직 배포
대상이 아니다(docs/registries/object-storage-readiness.yaml). 포트 경로를 MinIO로 묶는
일은 S3를 배포 대상으로 올리는 일과 같이 간다. MinIO에서는 provider 계약이 돈다.
남은 것: adapter 전용 ObjectStorageProviderException이 포트 밖으로 나가 바이트
불일치·consumer 실패는 계약이 unchecked 예외까지만 단언한다(RR9-03-34, 따로 고친다).
검증: desktop, :application-objectstorage:check :adapter:outbound:objectstorage:check
:app-bootstrap:architectureTest architectureCheck -p build-logic test 726건 실패 0.
RED: main에 ManagedPublicationOutcomeTest만 → 실패. 돌연변이: adapter의 회수 재시도를
REPLAYED→APPLIED로 바꾸면 계약 1건이 실패한다.
Refs: RR9-03-31, RR9-03-35, RR9-04-46
관측 registry가 코드와 양쪽으로 어긋난다. metrics.yaml에는 아무 코드도
등록하지 않는 행 열하나와 코드에 없는 tag 값이 있고, 코드가 등록하는
graphql·notification·http.client·fileserver·mongodb·jpa.query 지표 다수가
없다. mdc-keys.yaml은 18키 중 코드가 넣는 5키만 맞고 required_in이 틀렸다.
headers.yaml은 X-Request-Id·X-Correlation-Id를 ulid로 적고 아무도 쓰지
않는 Deprecation·Sunset·tracestate를 적는다. 전송마다 correlation 규칙이
다른데 registry는 하나로 적는다. 단일 인스턴스 in-process lock은
lock.acquisition을 세지 않아 그 지표가 0이다. 밑줄 든 meter 이름 둘이
이름 규칙을 어긴다.
- 행마다 등록하는 main 파일(source)·상수(constant)·등록 주체
(registered_by)를 적고, MetricsRegistryCodeAlignmentTest가 행 → 코드(이름이
상수면 그 상수를 쓰는 곳까지)와 코드(글자·상수 이름의 builder·registry·
Metrics 호출) → 행 두 방향을 본다. 템플릿이 부르지 않는 공개 메서드로만
생기는 job.* 행은 emitted_when을 적는다. 버린 안: 행만 지우기(새 지표가
다시 빠진다).
- mdc-keys는 5키와 전송별 표, headers는 source가 든 33행(서비스 controller용
상수는 service: 출처), StructuredLog·HeaderRegistry 시험이 코드 상수와
집합을 대조한다. 두 registry 시험은 시험 도우미 MainSources를 같이 쓴다.
- slo_driven 행은 MetricsDistributionMeterFilter 대상과 같은 집합이다(두
방향 시험). histogram을 켜지 않는 hikaricp timer 행은 평균으로 경보한다.
graphql.datafetcher·dataloader 행에 Spring 기본 tag를 적는다.
- in-process lock을 MeteredDistributedLock으로 감싼다.
- http.client.ratelimit.rejected, fileserver.upload.offset.mismatch로
이름을 바꾸고 http.client.circuit.state.rejected를 상수로 둔다.
- CardinalityBounds(status 40·outcome 6·uri), MetricNaming 단위 규칙,
SLO filter 대상(http.server.requests·jvm.gc.pause)을 문서와 맞춘다.
위험: 지표 이름 둘이 바뀌고 단일 인스턴스 lock 지표가 생긴다. 그 이름으로
만든 대시보드·경보를 옮겨야 한다(docs/upgrade/2026-11-round9-observability.md
8~13행). ApachePoolMetricsBinder·MongoTransactionRetry 지연은 다른 묶음이
맡는다.
검증: 위와 같은 desktop 실행(묶음 셋을 합친 트리) rc=0.
Refs: RR9-02-05, RR9-02-07, RR9-02-08, RR9-02-27, RR9-03-05
BREAKING CHANGE: http.client.rate_limit.rejected → http.client.ratelimit.rejected,
fileserver.upload.offset_mismatch → fileserver.upload.offset.mismatch,
CardinalityBounds 상수. docs/upgrade/2026-11-round9-observability.md 8~13행.
로컬 비밀 기본값(compose·lane·application-local의 DB 비밀번호, MinIO
root, Keycloak admin)이 __LOCAL_DEV_ 접두어 규칙을 따르지 않아 prod
sentinel 검사가 그 값을 알아보지 못한다. secrets-classification.yaml은
구현 없는 masking_rule full_except_last_4를 약속하고, full로 적은 키 일부
(salt·PEM·HMAC/signing key, URI 사용자 정보)를 LogMaskingPatterns가 가리지
않는다. required_test는 없는 시험 이름이다. IP 신뢰 설정을 두 문서가
다르게 적는다(application-local은 framework, rate-limiting은 native).
- 기본값을 __LOCAL_DEV_db_password__·__LOCAL_DEV_minio_root__·
__LOCAL_DEV_keycloak_admin__로 바꾼다.
- masking_rule을 full|userinfo|none 셋으로 줄이고, LogMaskingPatterns의
키 목록을 넓히고 URI userinfo와 여러 줄 PEM 블록 가림을 더한다. 시험이 masking_rule 어휘,
required_test 클래스 존재, full·userinfo 행이 실제로 가려지는지 본다.
버린 안: full_except_last_4 구현(끝 네 자리를 남길 값이 없다).
- IP 신뢰는 native + 내부 proxy 목록 하나로 적는다.
위험: 로컬 compose 볼륨이 옛 비밀번호로 만들어졌으면 DB 접속이 실패한다
(docs/upgrade/2026-11-round9-observability.md 6행). 운영 값은 바뀌지
않는다.
검증: 위와 같은 desktop 실행(묶음 셋을 합친 트리) rc=0.
Refs: RR9-02-10, RR9-02-12, RR9-02-13
BREAKING CHANGE: 로컬 compose·lane의 비밀 기본값이 바뀐다. 옛 볼륨은
지우거나 env로 옛 값을 준다(docs/upgrade/2026-11-round9-observability.md 6~7행).
로그 줄이 남기지 말아야 할 값을 싣고, 남겨야 할 줄을 버린다. 401·403
보안 WARN, route를 못 찾은 요청 로그, 처리하지 못한 예외 ERROR가 원본
request URI(식별자·토큰이 든 경로)를 싣는다. outbox relay·파일 서버 정리
스케줄러는 실패를 통째로 남겨 SQL·제약 이름·값이 원인 사슬로 따라간다.
SamplingTurboFilter는 INFO 이하를 logger 구분 없이 표본으로 버려 감사
logger의 INFO 줄도 사라진다. JSON 로그 profile 칸은 Logback이 처음 읽은
환경 변수 값이라 Spring이 해석한 profile과 다를 수 있다. HeaderSanitizer는
운영 코드가 부르지 않는 공개 유틸리티로 남아 있다.
- LoggedPath: route template이 있으면 그것, 없으면 식별자가 들 수 있는
마디를 {}로 가린 경로. 세 줄이 모두 쓴다. 버린 안: 원본 URI 그대로 두고
문서로 경고(로그 수집기가 이미 받는다).
- 스케줄러 실패는 새 ServerFailureLog.forBackgroundTask로 남긴다: 분류된
persistence 실패는 원인 사슬 없이, 그 밖의 carrier는 client 쪽 코드여도
stack과 함께(요청이 없으니 결함이다). composition:outbox-relay에
shared-contract edge를 더한다(gradle/modules.json).
- SamplingTurboFilter는 AUDIT marker와 이름 끝 마디가 audit·security인
logger를 표본에서 뺀다(이름별 판정은 캐시).
- ResolvedProfileJsonProvider가 줄을 쓸 때의 해석된 profile을 쓴다.
- HeaderSanitizer와 시험을 지우고 capability-status 제거 표에 적는다.
위험: 경로를 보던 로그 검색이 가린 경로를 본다. 감사 줄이 표본에서 빠져
양이 늘 수 있다. docs/upgrade/2026-11-round9-observability.md 1~5행.
검증: desktop에서 바뀐 leaf check·:app-bootstrap:test·systemTest·
documentContractTest·repositoryContractTest, scripts/verify.sh pr rc=0
(묶음 셋을 합친 트리). 새 시험은 고치기 전 트리에서 실패했다(RED).
Refs: RR9-02-09, RR9-02-15, RR9-02-21, RR9-02-22, RR9-02-26
BREAKING CHANGE: 보안·요청·예외 로그 줄의 경로 값과 JSON profile 칸의 출처,
HeaderSanitizer 삭제. docs/upgrade/2026-11-round9-observability.md 1~5행.
@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.