outbox 발행 대기가 publish()가 돌아온 뒤부터 재서, 호출을 붙잡은
publisher는 longestAttempt를 넘겨도 relay를 묶는다. SMTP 발송 pool은
대기열이 찰 때까지 thread 하나로 돌고, profile들의 max-concurrency가 pool이
담는 수를 넘어도 기동한다. 넘친 발송은 결과 불명으로 남는다. SMTP
profile timeout은 명령 하나만 묶어, 느린 relay에서 발송이 lease를 넘으면
lease 복구가 아직 도는 발송을 운영자 확인으로 넘긴다. Redis 캐시
command-timeout에 lane 대기 2초가 더해지고, 값 크기 상한은 설정할 길이
없다.
고른 방법: 발행 대기 마감은 publish() 전에 잡고 남은 시간만 기다린다.
기다리는 중 interrupt는 결과 불명, 이미 interrupt된 thread와 0 이하
longestAttempt는 보내지 않고 REJECTED_RETRYABLE로 돌려준다. SMTP pool은
dispatch-concurrency개 thread와 그 네 배 대기열로 고정한다. 한 family의
켜진 profile 전체를 보는 ProviderRuntimeAssembler.requireTogether를 두고,
SMTP는 max-concurrency 합이 pool보다 크거나 lease가 timeout 두 배 이하면
조립을 실패시킨다. profile timeout은 발송 한 번을 두 번 묶는다:
pool 대기가 넘으면 보내지 않고 재시도, 발송이 넘으면 PROVIDER_RESPONSE_LOST
로 남겨 다시 보내지 않는다. 두 시한은 completeOnTimeout이라 취소된다.
기본 timeout은 10초에서 30초로, socket timeout 합보다 길어야 한다.
Redis 연산 전체를 command-timeout 하나로 묶고
app.capabilities.cache.maximum-value-bytes를 다시 묶는다(1..16 MiB).
버린 대안: 발송 timeout에 재시도(같은 메일을 두 번 보낼 수 있다), 캐시
상한을 상수로 두기(큰 값을 쓰는 서비스가 바꿀 길이 없다), assembler가
assemble마다 합을 누적하기(조립 순서에 상태가 남는다).
위험·한계: 기동 조건이 늘었다(SMTP max-concurrency 합, lease와 SMTP
timeout, 캐시 값 상한 범위). 대기 시한이 돌려주는 stage는 일부러 버린다
(Error Prone 규칙대로 `unused`에 받고, SpotBugs DLS는 config/spotbugs/
exclude.xml에 그 메서드만 제외한다. Jetty abortAtDeadline 선례). send pool을 바꿔 끼운 배포는 부른 thread에서
돌리지 않는 executor여야 한다. outbox 새 거절 코드의 runbook 줄은 runbook
묶음에 넘긴다. claim·fence 커밋 위에 쌓았다.
검증: desktop RED(고치기 전 트리 + 새 시험, pr2-red2) 새 시험 실패.
GREEN은 PR 본문의 verify.sh pr 결과.
Refs: RR9-01-05, RR9-01-15, RR9-01-16, RR9-01-17, RR9-01-18
BREAKING CHANGE: SMTP profile들의 max-concurrency 합이 send pool(thread와 대기열)을 넘거나 dispatch.lease-duration이 SMTP timeout의 두 배 이하면 기동이 실패한다. SMTP 기본 timeout이 30초이고, 넘은 발송은 결과 불명이 된다. SmtpNotificationProviderAdapter 생성자가 timeout을 받는다. Redis 캐시 값이 maximum-value-bytes(기본 1 MiB)를 넘으면 기록하지 않는다. docs/upgrade/2026-11-round9-outbound.md
lease를 넘겨받는 저장소 다섯 곳이 앞 실행의 쓰기를 막지 못한다.
durable operation은 owner만 보고 써서 같은 worker id가 다시 claim하면
앞 실행의 결과가 남는다. 알림 lease 회복은 상태를 다시 읽은 뒤 조건
없이 되돌려 끝난 delivery를 다시 보낸다. 만료 sweep·전체 읽음은
기다린 행의 상태를 다시 보지 않는다. 멱등성 reaper는 앱 시계로 비교하고
한 번에 다 지우며, 같은 키 요청이 되살린 기록까지 지운다. fileserver
recovery enqueue는 동시 삽입에서 25P02로 실패하고, cleanup은 claim
lease가 끝난 뒤에도 항목을 시작한다. 저장소가 행에서 만드는 claim·lease
record는 잘못된 값을 IllegalArgumentException으로 거절해 web이 400으로
바꾼다.
고른 방법: 모든 쓰기를 owner·fence(·상태·만료) 조건을 단 한 문장으로
바꾼다. durable operation은 V23 lease_fence를 더하고 DurableOperationClaim
을 돌려준다. 알림 회복은 requeueAbandoned 한 문장이다. 만료 sweep은
subquery가 SKIP LOCKED로 쥔 행을 건너뛰고 바깥 UPDATE가 상태·만료를 다시
본다. 전체 읽음은 바깥 UPDATE가 상태를 다시 본다. reaper는 DB now()로
1000행씩, 트랜잭션마다 30초(SpringTransaction.DEFAULT_TIMEOUT_SECONDS)이고
바깥 DELETE에도 만료를 둔다. recovery는 INSERT … ON CONFLICT, cleanup은
lease 마지막 2분에 시작하지 않고 시도를 세지 않는 release로 돌려준다.
알림 provider timeout은 lease보다 짧아야 기동한다(호출이 lease를 넘으면
lease 복구가 아직 도는 호출을 맞추기로 넘긴다). 저장소가 만드는 record
일곱은 IllegalStateException으로 거절한다. 버린 대안: 읽고 비교한 뒤
쓰기(경합이 그대로 남음), 앱 쪽 락(인스턴스 사이에서 무의미).
위험·한계: 포트 시그니처가 바뀐다(DurableOperationStorePort,
RecipientLeaseStorePort.expiredDispatching, RecipientDeliveryStorePort
.requeueAbandoned, CleanupQueuePort.release). owner가 없거나 fence가
0인 V4 전 DISPATCHING 행은 회복이 고르지 않는다(안내 4행에 고치는 SQL).
provider timeout 검사는 필요조건일 뿐이고, 호출 전체를 묶는 것은 SES다.
검증: desktop RED(고치기 전 트리 + 새 시험, pr1-red3) 새 시험 13건
실패. GREEN은 PR 본문의 verify.sh pr·PostgreSQL lane 결과.
Refs: RR9-01-02, RR9-01-04, RR9-01-06, RR9-01-12, RR9-01-13, RR9-01-23, RR9-01-24, RR9-01-29, R1 넘김 DurableOperationStoreContractTest
BREAKING CHANGE: DurableOperationStorePort의 heartbeat·reportProgress·succeed·fail이 DurableOperationClaim을 받고 claimNext가 그것을 돌려준다. RecipientLeaseStorePort.expiredDispatching이 List<RecipientLease>를 돌려주고 RecipientDeliveryStorePort.requeueAbandoned, CleanupQueuePort.release가 새로 생긴다. IdempotencyReaper 생성자에서 Clock이 빠진다. 알림 provider timeout이 lease 이상이면 기동이 실패한다. 저장소가 만드는 claim·lease record가 IllegalStateException을 던진다. docs/upgrade/2026-11-round9-claim-fence.md
문제: 앞 커밋이 Gradle 루트를 저장소 루트로 옮기고 계층 폴더를 묶었다.
빌드 스크립트·build-logic·시험·workflow·스크립트·문서가 아직 옛 배치
(Gradle 루트 = src/)를 가정해 빌드가 되지 않는다.
고른 방법:
- Gradle 경로와 registry id는 그대로 둔다(:app-bootstrap, :application-core,
:composition:*). registry의 source_path만 새 폴더를 가리킨다. 폴더에 맞춘
이름(:domain:core, :application:core)은 프로젝트 이름 core가 둘이 되어
boot jar의 BOOT-INF/lib와 기본 capability가 겹치고, 파생 서비스의 모든
project(':…') 줄을 바꾸게 한다.
- registry는 gradle/modules.json, 시험 이미지 목록은
gradle/container-images.properties: 버전 카탈로그 옆, 빌드가 고정하는 것.
config/는 코드 검사 도구 설정만 둔다.
- build-logic: settings·architecture 플러그인의 저장소 루트를 Gradle 루트로
(getParentFile 제거). config contract의 파일 트리는 src/만 훑는다(루트를
훑으면 docs·.claude/worktrees까지 줍는다).
- 빌드 스크립트: rootProject.projectDir.parentFile → rootProject.projectDir,
rootProject.file('../…') → rootProject.file('…'), 옛 src 기준 include에
src/를 붙인다. notification API surface의 application-notification 소스
루트를 새 폴더로(놓치면 272개 타입이 surface에서 말없이 빠진다).
- 시험: 옛 src 기준 모듈 목록과 ../ 개수를 고친다. 없는 폴더를 말없이
건너뛰던 목록(MessagingAuthority, NotificationPayloadAtRest 등)을 새
폴더로, FileserverDocumentationCoverageTest는 Gradle 경로 → 폴더를
registry로 찾는다. Docker 계약은 WORKDIR /build, 새 jar 경로.
- Docker: 빌드 context를 저장소 루트로, .dockerignore는 허용 목록으로 다시
써서 전에 context였던 것만 들어가게 한다. compose의 build.context는 .,
env_file은 ./.env.
- workflow: working-directory: src 기본값과 그것을 되돌리던 줄을 지운다.
- scripts: verify.sh, ci/*, bootstrap-local, new-feature,
verify-feature-scaffold, mongo 검증, hooks, check-repo-layout 허용 목록.
check-docs의 경로 검사는 build-logic/·gradle/로 시작하는 경로도 본다.
- 문서: AGENTS.md 지도, README 구조 표, leaf AGENTS.md의 cd src, gates·
operate·결정 색인, src/bootstrap/AGENTS.md를 조립 계층 family 규칙으로
다시 쓴다. 기록 문서(docs/design·history·reviews, 지난 upgrade 안내,
capability-status 제거 표)는 머리 블록만 고친다. 파생 서비스용 안내
docs/upgrade/2026-11-relayout.md를 더한다.
위험: bootRun working dir가 저장소 루트가 되어 .env와 상대 경로 설정이
루트 기준이다. 루트 .env는 compose 보간에도 읽힌다(upgrade 안내 5절).
파생 서비스는 태그 pre-relayout-2026-11까지 받은 뒤 이 묶음을 받는다.
검증: desktop에서 캐시 없이 scripts/verify.sh docs·pr·main·release,
compose smoke 18 lane, 빠른 시작(scripts/verify.sh app). 결과는 PR 본문.
구조 리뷰(arch-reviewer) 지적 5건을 반영했다.
BREAKING CHANGE: Gradle은 저장소 루트에서 돈다(cd src 없음). registry는
gradle/modules.json, 이미지 빌드 context는 저장소 루트다. 옛 경로 → 새 경로
표는 docs/upgrade/2026-11-relayout.md.
Refs: design-docs repo-structure/01-backend-layout.md 6.1절 가-2·가-3
문제: `docs/notification`의 살아 있는 문서 10개가 영어였다. 번역하며 대조하니
설정 참조와 위협 모델이 지금 코드와 다른 말을 했다.
고친 것:
- 10개를 번역했다(ADR은 다른 세션 몫이라 두었다). 코드·설정 키·환경 변수·표 구조는
그대로다.
- 코드에 맞춘 주장:
- configuration-reference: 바인딩에 없는 `callbacks.trusted-proxies`
(`APP_NOTIFICATION_PLATFORM_CALLBACK_TRUSTED_PROXIES`)를 지우고 실제 방법
(`APP_SERVER_FORWARD_HEADERS_STRATEGY=native`, `server.tomcat.remoteip.internal-proxies`)을
적었다. 근거는 `notification.yml` 주석과 env-keys registry다.
- at-rest-threat-model: 「facade를 아무도 import하지 않아 JPA 영속성이 없다」는 낡았다.
지금은 persistence-notification의 `AutoConfiguration.imports`가 facade를 올리고,
`NotificationPayloadAtRestContractTest`가 그것을 단언한다. 지금 상태를 앞에 쓰고
결정 당시 분석은 `> 이력` 블록으로 옮겼다. 설정 참조와 YAML이 「교체 순서는 이
문서에 있다」고 하는데 없어서, `historical-keys`와 `SettingsSecretMaterialProvider`
대로 짧은 교체 순서를 더했다.
- module-mapping: plan API 모듈의 leaf `application-core` → `application-notification`,
「19 leaf」 → registry, relay 조립 `app-bootstrap` → `composition:outbox-relay`, 남은
provider 패키지는 `ses`·`smtp`뿐.
- `support-matrix.md`: 등급 칸 제목을 `등급`으로, 거부 절을 「## 지원하지 않는 것」으로
옮겼다. 등급 값(manifest의 키)은 그대로다.
- 테스트: `NotificationEvidenceVerifier`가 `Grade` 대신 `등급` 칸을 읽는다(영어 칸만
있으면 「등급을 매기는 표가 없다」로 닫힌 채 실패한다). `NotificationReleaseGateTest`는
거부 절 제목과 전달 보장·읽음 보장·정확히 한 번을 단언하고, 앞 절에는 한국어와 영어
표현이 모두 없어야 한다. `DEVICE_DELIVERED`·`DELIVERED` 승격 거부 문장도 한국어로 본다.
- 예외 목록에서 알림 language 줄 10개를 지웠다.
버린 대안: 등급 칸 제목을 `Grade`로 두기. 검증기가 읽는 키라서 바꾸지 않아도 됐지만,
한국어 문서에 영어 칸 하나가 남고 그 이유를 문서에 따로 적어야 한다. 검증기의 상수
하나를 바꾸는 쪽이 작다.
위험·한계: 위협 모델은 결정 기록 성격이 섞인 살아 있는 문서다. 결정 당시 글은
`> 이력` 블록에 뜻을 그대로 옮겼다.
검증: 최종 트리 기준(첫 커밋 본문 참고).
검증(desktop, 최종 트리 8295db89):
- `:adapter:outbound:notification:check` rc=0(375개 건너뜀 1 실패 0. `NotificationReleaseGateTest` 3,
`NotificationEvidenceVerifierTest` 7, `NotificationModeSsotTest` 3, `NotificationPayloadAtRestContractTest` 5),
`:mainCheck` rc=0(`notificationDocumentContractTest`의 저장소 문서 대조 통과), `testQualityCheck` rc=0.
- RED: 기준 커밋의 옛 문서에 대면 `NotificationReleaseGateTest` 2개와 저장소 문서 대조가 실패한다
("support-matrix.md has no table that assigns a grade (a '등급' column …)").
문제: 성숙도 리뷰 수정을 다시 읽은 재리뷰(Critical 0, 회귀 0)가
Important 27건·Minor 41건을 찾았다. 수정이 새로 만든 결함이 많았다.
@SystemInvoked가 권한 규칙의 탈출구가 됐고, 데모 계정 거부가 정확히
prod일 때만 걸렸고, outbox 순서 번호가 업그레이드 때 뒤로 갔고,
GraphQL union 아래 복잡도가 0이었고, 서블릿 오류 응답이 success:true로
나갔고, 호출자 deadline이 breaker를 열었다. 원래 리뷰 색인이 06 영역
발견 5건(06-10~14)을 빠뜨려 그동안 처리되지 않았다.
방법: 영역별 7묶음이 test-driven-development 절차로 실패 테스트를
먼저 쓰고 고쳤다. 결정은 재리뷰 README 4절에 적었다: 순서 번호는 V21이
기록한 전역 floor부터, 데모 계정은 local·test·demo 허용 목록,
@SystemInvoked bean은 기동 실패, complete 단계 실패는
IDEMPOTENCY_COMPLETION_UNKNOWN(결과 불명), 캐시 조건부 쓰기는 별도
SCRIPT lane, strict lane 정책은 build cache 입력, 끝나지 않는 재시도
행은 원인 코드·지표·PARKED 절차. 레지스트리가 선언만 하고 아무 코드도
내보내지 않던 redis.capability.* 지표 6개는 빼고 runbook을 실제
지표(redis.lane.*) 기준으로 고쳤다.
위험·한계: V21을 V22 없이 직접 고쳤다(어느 배포에도 아직 없음). 이
브랜치의 V21을 적용한 개발 DB는 다시 만들어야 한다. 서블릿 오류
디스패치를 보안 체인이 허용한다. 발행·저장소 포트 시그니처가 바뀌어
파생 서비스 코드가 깨진다. prod에서 fixture-로 시작하는 설정값은
기동을 막는다. httpclient failure-injection lane의 main 단계 중복
실행은 이전 결정대로 남겼다. 실제 CI runner 실행은 확인하지 못했다.
검증: ci, mainCheck, :integrationCheck, -p optional-platforms ci
integrationCheck performanceCheck, :performanceCheck, :releaseCheck
(-PgitRevision), verify-compose-profile-contracts(18 lane) 통과.
첫 실행의 실패 2건(FindSecBugs 1, sample 동시 생성 테스트의 v4 event
id)은 고친 뒤 ci·integrationCheck·mainCheck를 다시 돌려 통과했다.
Refs: docs/reviews/2026-11-03-rereview/README.md 3·4·6·7절
BREAKING CHANGE: outbox 발행 포트와 저장소 포트 시그니처, 순서 번호
첫 값(V21 floor 다음), 샘플 데모 계정 프로필 허용 목록, 새 오류 코드
IDEMPOTENCY_COMPLETION_UNKNOWN, prod의 fixture- 값 거부, 기동 rule은
static·의존 없음이어야 한다.
문제: 앞 커밋 뒤에도 알림·파일 서버 묶음이 합쳐지지 않았고, 포트 다수에
fake와 실제 구현이 함께 통과하는 공유 계약이 없었고, SpotBugs가 신뢰도
HIGH만 봤고, application-core에 관계없는 클래스 묶음 패키지(outbound)가
있었다. 묶음을 합치자 lane·검사가 새로 드러낸 결함도 있었다(JpaOutbox
Store가 읽기 전용 트랜잭션에서 이벤트를 조용히 잃음, gRPC admission
controller가 public synchronized라 외부 lock에 막힘, 소비자 decode 타입
등록 경로 없음, compose Redis 익명 접근, local-fileserver lane DB 없음).
방법: 리뷰 README 15절에 남은 결정을 모두 적고 그대로 고쳤다. 트랜잭션·
멱등성·발행·notification 포트에 testFixtures 계약 키트를 두고 fake와
PG·Redis 구현이 상속한다(fake 변이로 계약이 잡는지 확인). SpotBugs는
MEDIUM으로 내리고 진짜 결함은 고치고 오탐은 위치·패턴별 이유를 단
제외로 처리했다. 업무 기능 패키지 규칙을 application-core/CLAUDE.md에
정본으로 두고 ArchUnit 2개와 생성 명령이 강제한다. compose Redis는
infra/redis-sdk ACL로 뜬다. 묶음별 결과는 리뷰 README 16절에 있다.
위험·한계: APP_FLYWAY_ENABLED가 dev·prod에도 적용된다. app.security
오타 키가 이제 기동을 막는다. SES 콜백 replay 창 기본값이 1시간이다.
템플릿 패키지 목록은 CLAUDE.md 표와 TemplatePackageOwnership 두 곳에
있고 일치 검사는 없다. 실제 CI runner 실행은 확인하지 못했다.
검증: ci, mainCheck, integrationCheck, -p optional-platforms ci
integrationCheck, performanceCheck, releaseCheck(-PgitRevision),
verify-compose-profile-contracts(18 lane) 통과. compose lane 실제 기동:
local-fileserver, notification ingest·serving·handoff, local-redis,
all-adapters(smoke 3개 포함).
Refs: docs/reviews/2026-11-01-maturity-review/README.md 15·16절
BREAKING CHANGE: APP_FLYWAY_ENABLED가 dev·prod 프로필에도 적용되고,
app.security의 모르는 키는 기동을 거부한다. MessageHandler에
schemaVersions()가 생겨 decode 목록을 handler 선언에서 만든다.
- 결정 16: `ca-skeleton.*`·`backend.graphql` 등 → `app.*`(APP_* env 키 이름 유지), selector 키 상수 하나(`CapabilitySelectors`),
바인딩만 되던 `streaming-idle` 삭제
- `StrictSettingsBinder`가 env 오타까지 거부 — 모든 capability(graphql·websocket·mongo는 edge 제약으로 파일만 strict),
httpclient 리플렉션 `HttpClientEnvironmentKeys` 삭제
- persistence-jpa가 `APP_DATASOURCE_PASSWORD` secret 요구를 기여(bootstrap이 JPA 스위치를 읽지 않음), Redis ACL fixture에서 pub/sub 권한 제거
- 결함 수정: SMTP 설정 env 이름 충돌(P20-new-1), `bindExcept`가 system env까지 filter(P20-new-2), graphql 빈 deployment-mode 메시지(P20-new-6)
- 통합: P30과 충돌 11건(P30의 명시적 bean 구조 유지), P30 코드의 옛 키를 app.*로, persistence-jpa 포맷
- 현황표: 소유자 결정 36(persistence-jpa 설정은 플랫폼 키만 app.persistence-jpa.*로, 공유 기능 트리 예외), 재개 문서에 일시 정지 상태
Wave 3 종료 검증: check · ci verifyDependencyLocks --warning-mode=fail(714 task) · mainCheck · architectureCheck
verifyPublicPathSnapshot :app-bootstrap:verifyEnvKeys configContractCheck · :app-bootstrap:integrationTest
:sample-portfolio:integrationTest :sample-portfolio:systemTest · integrationCheck · -p build-logic test ·
-p optional-platforms ci · :app-bootstrap:qualificationBootJar releaseCheck 통과
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
- 결정 17: 자체 JDK HTTP gateway·SigV4 서명기 삭제, SES를 AWS SDK v2 `sesv2`로(기존 설정 계약 유지, SDK 재시도 끔,
기본 자격 증명 체인 끔, endpoint 라우팅 검사 유지) — 로컬 가짜 서버로 실제 SDK client 계약 테스트
- S2-#1b: notification persistence를 `adapter:outbound:persistence-notification`으로(migration V1–V10 바이트·위치 동일,
persistence-jpa → application-notification edge 제거), composition이 새 leaf를 가져옴
- 레지스트리 2개 삭제, provider 상태 전이표 하나, `ProviderCapabilities.dispatchOnly(...)`, dispatch record 전이 메서드,
미조립 회전 경로·중복 제출 진입점·테스트 전용 생성자 삭제
- 통합: at-rest 계약 테스트가 새 leaf 경로를 보고 `src/main/java`만 훑게(ORCH-new-2), app-bootstrap 알림 선택 주석(P23-new-3)
검증: ./gradlew check architectureCheck verifyDependencyLocks verifyPublicPathSnapshot :app-bootstrap:verifyEnvKeys
configContractCheck :app-bootstrap:integrationTest :sample-portfolio:integrationTest
persistence-jpa jpaPlatformContractTest jpaPlatformMigrationTest --continue 통과(704 task)
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Maps the 31-module plan onto the registry's 19 leaves as packages; the two
edges the registry forbids (provider->httpclient, inbox->messaging) are
replaced by application-owned ports. See docs/notification/module-mapping.md.
Acceptance is not delivery: ProviderSubmissionResult refuses to carry a
delivery outcome, and AMBIGUOUS is a first-class terminal state that blocks
automatic retry and fallback until reconciliation resolves it.
Providers: SES (SigV4 + SNS callback), Twilio (X-Twilio-Signature +
reconciliation), FCM (FID-primary batch), APNs, Web Push (RFC 8030/8291/8292),
SMTP and webhook. Contact points are AES-256-GCM encrypted with a separate
HMAC lookup fingerprint; nothing raw reaches a log, metric tag or exception.
Dispatch commits the attempt row, calls the provider with no transaction open,
then records the outcome; the durable queue uses FOR UPDATE SKIP LOCKED.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>