Commit Graph
285 Commits
Author SHA1 Message Date
DongHyeonka 2f0aefadee fix(security)!: 모든 전송이 같은 호출자로 권한을 판정하고 JWT·tenant 빈틈을 막는다
@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행.
2026-11-13 12:24:54 +09:00
DongHyeonka 3b71a3ca32 docs(security): 공개 경로 스냅숏 검사의 설명을 넓어진 범위에 맞춘다
공개 경로 스냅숏은 이제 기본 공개 경로만이 아니라 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, 공개 경로 범위 확장 뒤)
2026-11-13 08:32:49 +09:00
DongHyeonka b671054653 merge: main(3d31896a, round9 묶음 #28)을 받는다 2026-11-13 08:31:11 +09:00
DongHyeonka 5c22e2d955 merge: PR #27을 합친 검사 브랜치에 넣는다
pr / done (pull_request) Successful in 12m50s
# Conflicts:
#	src/adapter/inbound/graphql/AGENTS.md
2026-11-13 07:30:18 +09:00
DongHyeonka 1386202f57 merge: PR #26을 합친 검사 브랜치에 넣는다
pr / done (pull_request) Canceled after 0s
2026-11-13 07:21:13 +09:00
DongHyeonka c9e0565f4e merge: PR #25을 합친 검사 브랜치에 넣는다 2026-11-13 07:21:13 +09:00
DongHyeonka 9ea5ac9447 merge: PR #24을 합친 검사 브랜치에 넣는다 2026-11-13 07:21:13 +09:00
DongHyeonka a50731c480 merge: PR #23을 합친 검사 브랜치에 넣는다 2026-11-13 07:21:13 +09:00
DongHyeonka 70c38375a9 merge: PR #22을 합친 검사 브랜치에 넣는다 2026-11-13 07:21:13 +09:00
DongHyeonka 1867764077 merge: PR #20을 합친 검사 브랜치에 넣는다 2026-11-13 07:21:13 +09:00
DongHyeonka 41b4bfb38d merge: PR #19을 합친 검사 브랜치에 넣는다 2026-11-13 07:21:13 +09:00
DongHyeonka 33d54c99bd docs(reviews): round9 기록에 그룹 C PR과 고치며 찾은 발견 다섯을 더한다
pr / done (pull_request) Canceled after 0s
- 그룹 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
2026-11-13 06:51:28 +09:00
DongHyeonka 7635105a6a Merge remote-tracking branch 'origin/main' into claude/r9-c-tests-build
pr / done (pull_request) Canceled after 0s
2026-11-13 06:34:33 +09:00
DongHyeonka cbfa776270 build!: 시험 classpath·이미지 고정·카탈로그·API surface 입력을 정본대로 맞춘다
문제:
- 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
2026-11-13 06:34:32 +09:00
DongHyeonka 1185b36a6d test: 거짓 통과·흔들림·저장소 읽기 경로를 막도록 시험을 고친다
문제:
- 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
2026-11-13 06:34:32 +09:00
DongHyeonka 4ca61cd9bc docs: 알림·파일·객체 저장소·Redis leaf 안내의 범위를 코드대로 좁히고 callback 예외를 적는다
pr / done (pull_request) Canceled after 0s
문제(구조 리뷰):
- 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
2026-11-13 05:35:51 +09:00
DongHyeonka 7fdbbcaa87 docs: leaf 안내와 web 한도 표의 틀린 위치·주체를 코드에 맞춘다
문제(새 눈 리뷰):
- 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
2026-11-13 05:20:40 +09:00
DongHyeonka 377cf17653 fix(http): 새 눈 리뷰가 찾은 계약 빈틈을 닫는다
pr / done (pull_request) Canceled after 0s
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
2026-11-13 05:09:45 +09:00
DongHyeonka 66a7190a83 docs(build): mainCheck·bootstrap 설명을 지금 태스크와 기본 조립에 맞춘다
`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 둘)
2026-11-13 05:05:46 +09:00
DongHyeonka 637eda286b Merge remote-tracking branch 'origin/main' into claude/r9-c-docs-body 2026-11-13 05:03:52 +09:00
DongHyeonka bb28dae5c9 docs: 안내가 없던 leaf 여섯에 AGENTS·README를 쓰고 web 문서 둘을 지금 동작에 맞춘다
문제:
- 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
2026-11-13 05:03:52 +09:00
DongHyeonka bae2965f06 docs: 단계표·capability 상태·설정 설명을 지금 빌드와 workflow에 맞춘다
문제: 살아 있는 문서가 지운 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
2026-11-13 05:03:52 +09:00
DongHyeonka f12d007e91 Merge remote-tracking branch 'origin/main' into claude/r9-c-contracts 2026-11-13 04:47:10 +09:00
DongHyeonka 697e62e8cb fix(errors)!: 서버 포화는 모든 전송이 공용 SERVER_BUSY 하나로 답한다
문제: 서버 쪽 상한이 찬 거절이 전송마다 다른 코드였다. 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
2026-11-13 04:47:03 +09:00
DongHyeonka 7b5b4c6983 fix(http)!: fileserver·notification HTTP와 bulk envelope를 공용 계약대로 답한다
문제: 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
2026-11-13 04:46:39 +09:00
DongHyeonka 18188f78c9 fix(web-advanced)!: patch·stream·virtual thread가 약속한 계약대로 답한다
문제: 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
2026-11-13 04:08:16 +09:00
donghyeon.kang 46a57bfcc4 Merge branch 'main' into claude/r9-compose-ops
pr / done (pull_request) Canceled after 0s
2026-11-12 18:59:08 +00:00
donghyeon.kang 44f7203560 Merge branch 'main' into claude/r9-public-surface
pr / done (pull_request) Canceled after 0s
2026-11-12 18:59:06 +00:00
donghyeon.kang 12a9c0baee Merge branch 'main' into claude/r9-stale-names
pr / done (pull_request) Canceled after 0s
2026-11-12 18:59:03 +00:00
donghyeon.kang d4ba8574d0 Merge branch 'main' into claude/r9-env-keys
pr / done (pull_request) Canceled after 0s
2026-11-12 18:58:58 +00:00
donghyeon.kang 3df1685104 Merge branch 'main' into claude/r9-arch-rules
pr / done (pull_request) Canceled after 0s
2026-11-12 18:58:56 +00:00
donghyeon.kang afaf408d70 Merge branch 'main' into claude/r9-review-record
pr / done (pull_request) Canceled after 0s
2026-11-12 18:58:54 +00:00
DongHyeonka 10751b4279 docs(reviews): round9 기록에 기준 게이트 결과·묶음 PR·고치며 찾은 발견을 더한다
pr / done (pull_request) Canceled after 0s
- 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.
2026-11-13 03:56:12 +09:00
DongHyeonka 5196e6c798 Merge remote-tracking branch 'origin/main' into claude/r9-compose-ops
pr / done (pull_request) Canceled after 0s
2026-11-13 03:55:39 +09:00
DongHyeonka 23139722e8 fix(compose): heap dump 경로를 컨테이너 메모리 한계 안의 tmpfs에 두지 않는다
문제: 기본 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.
2026-11-13 03:55:38 +09:00
DongHyeonka 35ecd63497 Merge remote-tracking branch 'origin/main' into claude/r9-public-surface
pr / done (pull_request) Canceled after 0s
2026-11-13 03:47:30 +09:00
DongHyeonka db81994490 fix(security)!: 공개 경로 스냅숏이 profile 덮어쓰기와 모듈 chain의 permitAll까지 고정한다
문제: 공개 경로 스냅숏(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.
2026-11-13 03:47:30 +09:00
DongHyeonka 0167b0974c Merge remote-tracking branch 'origin/main' into claude/r9-stale-names
pr / done (pull_request) Canceled after 0s
2026-11-13 03:23:03 +09:00
DongHyeonka f2d2267e2e docs: 옮기거나 지운 타입·샘플·플랫폼을 가리키던 안내를 지금 이름으로 고친다
문제: 모듈 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.
2026-11-13 03:23:03 +09:00
donghyeon.kang 2958392d20 Merge branch 'main' into claude/r9-env-keys
pr / done (pull_request) Canceled after 0s
2026-11-12 17:00:30 +00:00
donghyeon.kang b86ef0e8dd Merge branch 'main' into claude/r9-arch-rules
pr / done (pull_request) Canceled after 2m37s
2026-11-12 17:00:28 +00:00
donghyeon.kang 5260bf5763 Merge branch 'main' into claude/r9-review-record
pr / done (pull_request) Canceled after 2m25s
2026-11-12 17:00:27 +00:00
donghyeon.kang b7029ce7ce Merge branch 'main' into claude/r9-docs-work
pr / done (pull_request) Successful in 11m55s
2026-11-12 17:00:25 +00:00
donghyeon.kang 8a0b3004a4 Merge branch 'main' into claude/r9-env-keys
pr / done (pull_request) Canceled after 0s
2026-11-12 16:55:02 +00:00
donghyeon.kang 692f8fba71 Merge branch 'main' into claude/r9-arch-rules
pr / done (pull_request) Canceled after 0s
2026-11-12 16:55:01 +00:00
DongHyeonka bd17bf1f00 fix(env)!: env 계약을 배포 설정 동작에 맞추고 verifyEnvKeys가 그 차이를 잡게 한다
문제: 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.
2026-11-13 01:48:48 +09:00
donghyeon.kang 7304c03d6a Merge branch 'main' into claude/r9-review-record
pr / done (pull_request) Canceled after 0s
2026-11-12 16:45:46 +00:00
donghyeon.kang 04eb82139f Merge branch 'main' into claude/r9-docs-work
pr / done (pull_request) Canceled after 0s
2026-11-12 16:45:44 +00:00
DongHyeonka f4d832dfaf fix(arch): 아키텍처 규칙이 놓친 HARD-STOP 2 사각지대 다섯을 닫는다
pr / done (pull_request) Canceled after 0s
문제: 저장소 전체 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
2026-11-13 00:28:00 +09:00
DongHyeonka d82a534d23 revert: operate.md 줄 줄이기를 PR #15에 맡긴다
pr / done (pull_request) Successful in 11m58s
이 브랜치의 c0d7ad8f("operate.md를 150줄 안으로 줄이고 묶음 ID를
뺀다")를 되돌린다. 백엔드 CI 세션이 같은 줄을 PR #15(caa71d32)에서
다르게 고쳤고(4.4절 두 줄을 합쳐 150줄, ID 삭제), check-work-docs.py를
prCheck에 넣었다(13ed3a1d). 두 PR이 같은 줄을 고치면 병합 충돌이
난다.

위험·한계: PR #15가 병합되기 전에는 main의 operate.md가 151줄이고
"(W4 BE-OBS-A)"가 남아, 이 브랜치가 더한 ID 꼴 검사와 줄 수 검사로
check-work-docs.py가 rc=1이다. 지금 prCheck는 그 검사를 돌리지 않으므로
PR 단계는 막히지 않는다. #15가 병합되면 둘 다 풀린다.

검증: git diff origin/main -- docs/work/operate.md가 57·87줄의 /src
절차만 남는다. scripts/tests 158건 통과.
2026-11-12 22:27:58 +09:00