문제: core 계층(application·domain·shared-contract), app-bootstrap,
composition, registry, build-logic, optional 빌드의 모듈 문서가 영어다.
세션이 처음 읽는 지역 규칙인데 소유자는 2026-11-07에 살아 있는 문서를
모두 한국어로 쓰기로 정했다. leaf CLAUDE.md 셋은 Spring Boot 버전을
4.0.0으로 복사해 두었는데 실제 버전(libs.versions.toml)과 다르다.
방법: 뜻을 그대로 옮기고 코드·명령·경로·식별자·표 구조는 원문으로
둔다. 버전은 `src/gradle/libs.versions.toml`을 가리키는 말로 바꾼다.
다른 문서·코드가 제목으로 가리키는 절(application-core의
Naming convention·Package ownership·Canonical use case shape·Allowed
transactional shapes, shared-contract의 Responsibility·Forbidden,
messaging의 발행 재시도 절)은 영어 원제를 괄호로 남겨 그 참조가
계속 찾아지게 한다. 참조하는 쪽을 고치는 것은 이 작업 범위 밖이다.
코드와 어긋난 주장은 코드에 맞춘다: TransactionPort 구현을
`adapter-persistence`에서 `adapter:outbound:persistence-jpa`의
`SpringTransaction`으로, registry README의 빈 의존 목록 예를
persistence-mongo(실제 목록은 application-core·shared-contract)에서
domain-core·shared-contract·messaging-core-api로 고친다.
TemplatePackageOwnershipDocumentTest는 표 머리 문자열로 표를 찾으므로
머리 상수를 한국어 머리(`| 패키지 (...) |`)로 맞춘다. 표와 기계 사본을
대조하는 계약은 그대로다.
위험: 영어 원제를 괄호로 남긴 제목은 참조하는 문서가 한국어 제목으로
바뀌면 괄호를 지울 수 있다. 본문의 짧은 이력 번호(07-08, 06-01,
11-M9)는 뜻을 바꾸지 않으려고 그대로 옮겼다.
검증: python3 scripts/check-docs.py rc=0(번역한 파일의 language 줄 8개,
number 줄 3개 지움), check-work-docs.py rc=0, --links(gates.md 범위)
깨진 링크 0, unittest discover scripts/tests 43개 통과.
문제: `MessagingAdmissionControllerTest.aWaitingCallerIsAdmittedOnceAPermitIsReturned`가
desktop 부하가 높을 때 가끔 실패한다(구조 정리 게이트에서 부하 7에 한 번,
이번에 부하 24~27에서 20번 중 한 번).
원인: 이 테스트는 대상 하나(`order.created`)로 허가 하나를 쥔 뒤, 같은 대상으로
대기자를 띄우고 곧바로 허가를 돌려준다. 그런데 대상별 상한(2인자 생성자에서는
프로세스 상한과 같은 1)이 나중에 더해지면서 같은 대상의 두 번째 호출은
프로세스 허가를 기다리지 않고 바로 `DESTINATION_IN_FLIGHT_LIMIT_EXCEEDED`로
거절된다. 그래서 테스트는 main 스레드의 `complete`가 대기자의 `admit`보다
먼저 돌 때만 통과한다(그때는 대기자가 기다릴 일이 없다). 부하가 높아 대기자가
먼저 돌면 거절되고 in-flight가 0이 되어 실패한다. 테스트 이름이 말하는
"기다리던 호출이 허가를 받는다"는 어느 쪽에서도 시험되지 않았다.
고친 방법:
- 대기자를 다른 대상으로 보내 프로세스 허가만 다투게 한다.
- 대기자가 실제로 limiter의 bounded wait에 들어가(TIMED_WAITING) 줄을 선 뒤에
허가를 돌려준다. 순서를 테스트가 정하므로 스레드 일정에 기대지 않는다.
- 대기자의 거절을 잡아 단언한다(전에는 스레드 밖으로 사라졌다).
- 대기 상한을 2초에서 30초로 늘린다. 부하가 높을 때 상한이 먼저 끝나 생기는
다른 갈림을 막는다. 대기자는 허가를 받는 즉시 끝나므로 평소 시간은 같다.
버린 대안: 같은 대상을 두고 3인자 생성자로 대상별 상한을 2로 주기. 그러면
대상별 상한 1·프로세스 상한 1 조합(2인자 생성자 기본)의 동작을 시험에서
숨긴다. 그 동작 자체를 바꾸는 것은 이 변경의 범위가 아니다.
위험·한계: 2인자 생성자 Javadoc은 "only ceiling is the process-wide one"이라
하지만 한 대상이 프로세스 허가를 모두 쥐면 같은 대상의 호출은 기다리지 않고
바로 거절된다. 운영 조립(`MessagingPublishConfiguration`)은 3인자 생성자로
대상별 상한(기본 64)을 따로 주므로 영향이 없다. 문서와 동작 중 무엇을 맞출지는
별도로 남긴다.
검증(desktop, `--no-build-cache`):
- RED: 새 테스트 모양에 대기자를 같은 대상으로 두면 매번 실패한다. 메시지
"the waiter must be queued on the permit before it is returned (refused:
MessageBackpressureException: order.created already holds its 1 in-flight
publishes ...) expected: TIMED_WAITING but was: TERMINATED".
- GREEN: `:messaging:messaging-policy:check :messaging:messaging-policy:testQualityCheck`
rc=0, 테스트 43 실패 0.
- 부하: busy loop 24개(12코어)를 건 채 이 클래스를 `--rerun`으로 20번 연속
돌렸다. 고친 트리 20/20 통과(1분 부하 8→24). 같은 부하에서 고치기 전 트리는
20번 중 1번 실패(8번째, "expected: 1 but was: 0", 대기자가 위 거절을 받음).
로그 desktop `~/i1-layout-docs-logs/flaky/`.
문제: :messaging:messaging-kafka:verifyMessagingCertificationEvidence가
rc=1이다. 커밋된 증거 broker-certification-evidence.jsonl(2026-08-24)의
brokerImage는 apache/kafka:4.1.0인데, 2026-11-03 container-images.properties
가 kafka 이미지를 digest로 고정한 뒤 레인은
apache/kafka@sha256:bff074a5…로 돈다. 시나리오 넷의 결과는 같고 이미지
이름만 다르다. 이 workflow는 messaging 경로가 바뀔 때만 PR에서 돌아
그동안 드러나지 않았다.
고른 방법: 게이트가 안내하는 대로 이번 실행이 만든 jsonl로 커밋된
파일을 바꾼다(증거는 실행 기록이다). 손으로 이미지 이름만 고치지
않는다.
위험·한계: gitCommit 칸은 레인을 돌린 트리의 커밋(8d69e599, 이 파일만 다르다)을
가리킨다. 레인은 실 Kafka 컨테이너와 Toxiproxy가 있는 곳에서만 돈다.
검증(desktop, ~/t1-layout-logs/):
- 고치기 전(트리 2b3354a4): verifyMessagingCertificationEvidence rc=1.
claimed/produced 차이는 brokerImage(apache/kafka:4.1.0 ↔
apache/kafka@sha256:bff074a5…)뿐이고 시나리오·결과·testId는 같다
- 고친 뒤(트리 4b304c59): :messaging:messaging-kafka:verifyMessagingCertificationEvidence
-PcertificationCommit=8d69e599… :messaging:messaging-testkit:check
:messaging:messaging-kafka:check rc=0 (messagingCertificationTest 실행)
문제: src/ 최상위에 계층 폴더와 들여온 제품 폴더(messaging, grpc,
grpc-advanced)와 optional 빌드 폴더(optional-platforms)가 같은 높이로
놓여, 무엇이 이 애플리케이션의 계층인지 폴더만으로 안 보인다.
src/config/에는 빌드 전체 설정과 기능 하나가 주인인 데이터(jpa,
messaging, mongodb)가 섞여 있다.
고른 방법(소유자 결정 2026-11-07, 설계 가-1):
- git mv로 src/platforms/{messaging,grpc,grpc-advanced,optional-build}.
registry source_path 28행만 바꾸고 Gradle 경로(:messaging:*, :grpc:*)는
그대로다. optional 빌드의 이름(optional-platforms)도 그대로다.
- optional 빌드가 한 단계 깊어져, build-logic이 "optional 빌드의 부모 =
주 빌드"로 가정한 네 곳(registry settings, ArchitecturePlugin, 테스트
이미지 catalog, checkstyle·spotbugs 설정)을 MainBuild(위로 올라가며
registry·설정 파일을 찾음)로 바꾼다.
- settings.gradle·build.gradle의 상대 경로, workflow의 -p 값과 경로,
buf 작업 폴더를 고친다. buf breaking은 이동 전 baseline에서도 옛
경로로 비교해 이동 PR에서 건너뛰지 않는다.
- config/jpa, config/messaging, config/mongodb의 데이터를 주인 leaf의
release/로 옮기고 읽는 빌드 줄·테스트·스크립트·문서를 고친다.
- 루트 CLAUDE.md 5절에 최상위 폴더 지도를 한 줄로 적는다.
버린 대안: Gradle 루트를 저장소 루트로(가-3, CI 재편 때 다시 봄),
application-* 묶기(가-2, 파생 서비스 충돌이 큼).
위험·한계: Gradle 문서의 "이름 = 위치" 권고와 한 단계 어긋난다
(:messaging:x가 platforms/messaging/x). 옮긴 폴더를 고쳐 쓰던 파생
서비스는 이름 바뀜 충돌이 날 수 있다(B-52). docs/capability-status.md
「제거된 코드」 표와 docs/work/evidence.md의 옛 경로는 이력이라 두었다.
검증(desktop, 트리 2b3354a4, ~/t1-layout-logs/):
- ./gradlew :ci :verifyDependencyLocks --warning-mode=fail --continue
첫 실행 rc=1: MessagingAuthorityContractTest가 src/messaging을 찾아 실패
→ 경로를 고침. 두 번째 rc=1: messaging-policy
MessagingAdmissionControllerTest.aWaitingCallerIsAdmittedOnceAPermitIsReturned
(2초 대기 경쟁, 부하 7.3에서 한 번 실패, 코드 변경 없는 leaf) → --rerun
3회 모두 통과. 세 번째 rc=0
- -p platforms/optional-build ci rc=0, 두 빌드의 verifyStrictLaneStages
--dry-run rc=0, -p build-logic check rc=0
- :app-bootstrap:documentContractTest
:adapter:outbound:persistence-mongo:mongoDocumentContractTest rc=0
- ./gradlew projects(주 빌드)와 optional 빌드 projects의 프로젝트 목록이
이동 전 트리와 같다(Gradle 경로 불변)
- check-work-docs.py, 상대 링크 검사 rc=0
Refs: design-docs repo-structure/README.md 3.1, repo-structure/01-backend-layout.md 6.1
BREAKING CHANGE: src/messaging·src/grpc·src/grpc-advanced·src/optional-platforms가 src/platforms/ 아래로, src/config/{jpa,messaging,mongodb}가 주인 leaf의 release/로 옮겨졌다. optional 빌드는 -p platforms/optional-build로 부른다. docs/upgrade/2026-11-maturity-review.md B-52.