# application-core — 설계 결정 참조 애플리케이션 유스케이스 계층. 패키지 루트: `dev.caskeleton.application`. 허용/금지 의존, 유스케이스 형태, 트랜잭션 모드, 명명 규칙 같은 **모듈 규칙**은 [CLAUDE.md](CLAUDE.md) 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔 참조용 기록이다 — 코드를 읽다 "왜 이렇게 했나"가 궁금할 때 본다. 아래 설명은 별도 추적 ID를 몰라도 읽히도록 결정의 배경과 트레이드오프를 문장으로 풀어 둔다. 이 계층을 관통하는 큰 원칙 하나: **application-core 는 프레임워크-free 다.** Spring/JPA/HTTP 타입뿐 아니라 SLF4J/JUL/Logback/Log4j/Micrometer도 직접 들이지 않고, 필요한 인프라 능력 (트랜잭션·락·인가·알림·운영 진단 등)은 전부 구체적인 목적의 `*Port` 인터페이스로 추상화한다. 구현은 adapter 모듈에 있고 컴파일 타임엔 보이지 않는다. Gradle `verifyApplicationCoreDependencyPurity`와 ArchUnit `APPLICATION_HAS_NO_DIAGNOSTIC_FRAMEWORK`가 이 계약을 자동 검증한다. Cache도 같은 원칙을 따른다. `cache` 패키지에는 cache-redis가 구현하는 `CacheRegionPort`와 그 값 타입만 있다. Redis key, codec, Micrometer 렌더링은 adapter가 소유한다. --- ## 메시징 semantic contract R1 `messaging.contract`와 `messaging.event`는 feature가 integration event를 동적 JSON이나 provider 타입으로 넘기지 않게 만드는 application 경계다. - `IntegrationPayload` 구현은 feature가 소유한 불변 typed record다. - `IntegrationEventContractContribution`은 contract ID와 payload version을 분리하고, exact final record type token, 실제 record component 순서, repository-local schema resource/hash와 provider-neutral `ContractDescriptor`만 기여한다. assignable-type 탐색, `Class.forName`, Java class-name routing, `Map`, raw JSON string/tree는 이 SPI에 들어오지 않는다. - `IntegrationEventDraft`는 canonical event/aggregate/order/correlation identity와 typed payload를 보유한다. tenant가 없는 모드도 null 대신 canonical system tenant scope를 `AggregateIdentity`에 넣어 dedupe/order identity가 PostgreSQL nullable uniqueness에 기대지 않게 한다. 새 event의 event id와 causation id는 정규 소문자 UUIDv7이어야 한다 (`IntegrationIdentity.isCanonicalUuidV7`). messaging platform의 `MessageId`가 그것만 바꾸지 않고 싣기 때문이다. draft가 거부하므로 그런 id는 업무 트랜잭션 안에서 실패하고, 커밋된 뒤 relay에서 DEAD가 되지 않는다(리뷰 2026-11-01 06-06, 재리뷰 2026-11-03 RR-05-04). 저장 문법 `EventId`는 이 규칙 전에 쓰인 행을 읽으려고 넓게 남아 있다. - draft는 `IntegrationEventDrafts.draft(...)`로만 만든다. 계약 id·버전·목적지, correlation fallback(요청 값이 `IntegrationIdentity` 문법에 맞지 않으면 event id), tenant 없는 기능의 `SINGLE_TENANT_SCOPE`가 거기 한 번 있다. 운영 코드가 생성자를 직접 부르면 `INTEGRATION_EVENT_DRAFTS_ARE_BUILT_BY_THE_SHARED_HELPER`가 막는다. 식별자 문법·길이는 `IntegrationIdentity`가 정본이고, 값을 미리 검사할 때는 `isCanonical(value, bound)`를 부른다. - `IntegrationEventEncoderPort` 뒤의 adapter가 deterministic encoding을 수행하고 `ValidatedIntegrationEvent`를 돌려준다. 템플릿의 구현은 `adapter:outbound:support`의 `JsonIntegrationEventEncoder`다(envelope v1 + payload record의 결정적 JSON, 선언한 schema hash를 classpath 파일과 대조). 결과는 logical destination, exact US-ASCII partition key, exact encoded envelope bytes, schema/envelope hash와 catalog/binding revision을 defensive copy로 보존한다. - `ContractDescriptor`는 owner module, logical destination, serializer ID, ordering requirement, payload/envelope byte limit, sensitivity classification, same-event requeue horizon만 표현한다. physical topic, Kafka cluster/security topology는 deployment binding의 책임이다. 이 절의 타입은 framework-free semantic contract다. 결정적 writer는 `adapter:outbound:support`의 `JsonIntegrationEventEncoder`, outbox append·claim은 `adapter:outbound:persistence-jpa`, relay 조립은 `composition:outbox-relay`, 발행은 `adapter:outbound:messaging`의 platform bridge가 맡는다. payload를 JSON Schema로 매번 검증하는 validator는 템플릿에 없다(서비스가 encoder bean을 바꿔 둔다). ### payload version 올리기 (리뷰 2026-11-01 06-10) payload schema는 version마다 `contracts/messaging//v.schema.json` 파일 하나다. 한 번 출시한 version 파일은 고치지 않는다. 이미 그 version으로 쓰인 event가 outbox·broker·DLQ에 남아 있고, 소비자는 그 schema로 만들어져 있다. 그래서 schema를 가진 leaf는 출시한 version의 SHA-256을 `src/test/resources/contracts/released-payload-schemas.sha256`에 고정하고, testFixtures의 `ReleasedPayloadSchemaContract`를 상속한 테스트가 두 가지를 막는다. - 출시한 version 파일의 바이트가 바뀌면 실패한다(필드 삭제·타입 변경 같은 깨지는 변경 포함). - 고정되지 않은 version 파일이 있으면 실패한다. 새 version은 manifest에 한 줄을 더하는 순간 출시된다. 필드를 바꾸거나 지우거나 더하는 변경은 새 version으로 낸다(설계 문서 2026-07-28 §14.4 STRICT_VERSIONED). 1. 새 version 추가: `v.schema.json`, 새 payload record, 새 `IntegrationEventContractContribution`. 옛 version의 contribution은 그대로 둔다. encoder catalog는 `(contractId, payloadVersion)`마다 하나라 두 version이 함께 등록된다. 2. 소비자 배포: 모든 소비자가 v과 v을 둘 다 읽게 한다. outbox에 이미 쌓인 v 행은 저장된 바이트 그대로 나가므로, 생산자를 바꾼 뒤에도 한동안 두 version이 함께 도착한다. 3. 생산자 전환: draft를 v contract로 만든다. 이 커밋에서 manifest에 v 줄을 더한다. 4. 옛 version 제거: outbox·broker·DLQ·archive에 v이 더 남지 않았을 때만 contribution과 파일을 지우고 manifest 줄도 지운다. 지우는 줄은 리뷰에서 보이는 변경이다. 고른 방법과 버린 대안: 출시한 version 파일의 해시 고정(위). 버린 대안 — 직전 version과 새 version의 JSON Schema diff로 호환성을 검사하는 fixture: payload schema가 닫혀 있어(`unevaluatedProperties: false`) 필드 하나를 더해도 옛 소비자의 검증이 깨지므로, diff는 거의 모든 새 version을 "깨짐"으로 판정한다. 설계도 diff heuristic으로 호환성을 주장하지 않기로 했다(§14.4). 외부 schema registry 도입 — 이 템플릿 범위에 비해 운영 비용이 크다. --- ## 유스케이스 계약 (usecase / command / query / capability) ### UseCase / CommandUseCase / QueryUseCase - inbound port(헥사고날의 primary port)다. 모든 구체 유스케이스는 쓰기면 `CommandUseCase`, 읽기면 `QueryUseCase` 를 extends 해서 **연산의 종류를 타입에 박아 둔다.** 이렇게 해야 capability·트랜잭션 모드 같은 계약을 컴파일/ArchUnit 단계에서 강제할 수 있다. 클래스 이름은 반드시 `UseCase` 로 끝난다(ArchUnit 강제). - 제네릭 입출력 타입(``)에는 web 요청 DTO·JPA 엔티티·외부 클라이언트 응답 타입이 올 수 없다. 입력은 `Command`/`Query`, 출력은 도메인 객체·도메인 프로젝션·`Void` 만 허용. 이 자리에 transport 타입이 들어오면 application 계층 경계가 깨진다. ### Command / Query (마커) - 둘 다 마커 인터페이스. `Command` = 쓰기 의도, `Query` = 읽기 의도. - 반드시 불변 타입(가능하면 `record`)이고 도메인 타입·원시 값 객체로만 구성한다. web DTO, JPA 엔티티, 외부 응답 타입은 필드에 넣을 수 없다 — 이게 들어오면 transport 관심사가 application 계층으로 새는 것. ### UseCaseCapability (모든 유스케이스 필수 애너테이션) - 모든 구체 `*UseCase` 클래스에 필수. 유스케이스의 **트랜잭션 모양·멱등성·리포지토리 접근·외부 호출 여부를 본문을 읽지 않고도** 알 수 있게 만든다. ArchUnit 이 모든 구체 inbound port 에 이 애너테이션이 일관되게 붙어 있는지 검사한다. - 일관성 규칙(ArchUnit 으로 강제): - `QueryUseCase` 구현은 `transactionMode = READ_ONLY` + `repositoryAccess = READ_REPOSITORY` 여야 한다. - `transactionMode = REQUIRES_NEW` 는 outbox / audit / compensation 흐름 전용이다. - 외부 `*Port`(outbound adapter 에 바인딩된 포트)를 호출하려면 `externalOutboundAllowed = true` 가 필요하다. 없으면 outbound 어댑터 호출 금지. - `repositoryAccess` 가 `WRITE_REPOSITORY` 가 아닌 유스케이스는 리포지토리 포트의 쓰기 메서드(save/delete/update/insert)를 호출할 수 없다 — `read_only_use_cases_do_not_call_repository_write_methods` 규칙이 막는다. 단 정적 분석은 **직접 호출만** 잡으므로, helper/mapper 를 거친 쓰기는 리뷰가 본다. - `bulkWrite = true` 는 `WRITE_REPOSITORY` 를 함께 요구한다(대량 쓰기도 결국 쓰기). `bulk_write_capability_requires_write_repository_access` 가 강제. - 이 애너테이션은 `docs/registries/capabilities.yaml` 의 7개 capability 를 코드로 구현한 것이며, **코드가 SSOT** 다. 추가 플래그의 의미: - `sensitiveRead` — PII/자격증명/비밀을 읽는 유스케이스 선언. 필드 단위 마커(엔티티 FQN + 필드명 테이블)와 자동 강제는 이 영역의 책임이고 아직 미구현이라, 지금은 리뷰 기반의 선언적 계약이다. 이 마커를 **도메인/JPA 엔티티 애너테이션으로 표현하면 안 된다**(프레임워크 의존이 도메인에 새는 것을 막기 위함). - `bulkWrite` — 단일 트랜잭션에서 100행/배치를 초과하는 쓰기(registry 임계치 = 100). 임계치 미만이면 평범한 `WRITE_REPOSITORY` 선언으로 충분하다. - `crossTenantAdmin` — 테넌트 경계를 넘는 admin 연산. cross-tenant 접근 정책 자체는 이 영역의 책임(여기선 어휘만 제공). single-tenant 유스케이스에 붙이면 리뷰 reject. --- ## 트랜잭션 경계 (transaction) ### TransactionPort - **존재 이유**: application 유스케이스가 `org.springframework.transaction.annotation.Transactional` 을 import 하지 않고도 트랜잭션 의도를 선언하게 하기 위한 추상화다. 구현(보통 `SpringTransaction`)은 persistence adapter 가 Spring `PlatformTransactionManager` 로 제공한다. application/domain 을 프레임워크-free 로 유지하는 핵심 장치. - 네 가지 경계: - `inWrite` — REQUIRED + read-write, `READ_COMMITTED`. command 유스케이스 기본. - `inRootWrite` — 물리 root 전용 REQUIRED + read-write, `READ_COMMITTED`. 실제 ambient transaction 이 하나라도 있으면 action 실행 전에 `NestedRootTransactionRejectedException` 으로 거부한다. 성공 값은 commit 이 끝난 뒤에만 호출자에게 반환되며, commit 실패는 그대로 전파된다. - `inRead` — REQUIRED + read-only, `READ_COMMITTED`. query 유스케이스 기본. - `inNew` — REQUIRES_NEW + read-write. UseCaseCapability 에 `REQUIRES_NEW` 를 명시한 유스케이스(outbox/audit/compensation)에서만 허용. - **root-only 사용 조건**: `inRootWrite` 는 join 가능한 일반 command 경계의 대체물이 아니다. 외부 효과를 commit 이후에만 시작해야 하는 orchestration처럼 물리 root를 증명해야 하는 경우에만 쓴다. 기존 transaction 안에서 `REQUIRES_NEW` 로 몰래 분리하지 않고 fail-fast하므로, 호출자는 transaction 없는 진입점에서 이 경계를 시작해야 한다. - **콜백 시그니처(D11)**: 네 메서드 모두 `Supplier`/`Runnable` 을 받아 checked exception 을 던질 수 없다. Spring `TransactionCallback` 제약과 동일하다. 그래서 호출자는 도메인 checked exception 을 `RuntimeException` 하위로 감싸야 한다(`DomainException extends RuntimeException`). `IOException` → `UncheckedIOException`, `SQLException` 은 Spring `DataAccessException` 계층이 자동 변환한다. 콜백 안에서 던진 `RuntimeException` 은 롤백 + 호출자 전파. - **`inNew` 풀 사이징 비용(D12)**: REQUIRES_NEW 는 바깥 트랜잭션의 커넥션을 잡아둔 채 **새 물리 JDBC 커넥션을 추가로** 잡는다. 즉 미완료 `inNew` 호출 하나당 풀에서 커넥션 하나를 더 쓴다. ``` hikari.maximumPoolSize >= (concurrent_threads × (1 + max_inNew_depth)) + 1 ``` 여기서 `max_inNew_depth` 는 스레드당 미완료 `inNew` 중첩의 최대 깊이다. **금지**: 많은 레코드를 도는 루프 안에서 `inNew` 호출(예: per-row outbox dispatch). 풀 고갈 + 데드락 위험. 레코드를 한 번의 `inNew` 안에서 배치 처리하거나, 루프를 트랜잭션 경계 밖으로 빼라. - **금지 목록**: `NESTED`/`NEVER` propagation, `READ_UNCOMMITTED` isolation, application 패키지에서 `@Transactional` 직접 사용, `inRootWrite` 의 ambient transaction 진입, `inNew` 의 per-record 루프 호출. ### TransactionMode - `WRITE` / `READ_ONLY` / `REQUIRES_NEW`. TransactionPort API 와 UseCaseCapability 양쪽에서 쓰여, 유스케이스의 트랜잭션 계약을 본문 없이 드러낸다. - `READ_ONLY` 일 때 persistence adapter 는 `readOnly = true` 를 켜서 드라이버 읽기 최적화 (Hibernate flush-mode MANUAL 등)를 적용하는 것이 좋다. ### Isolation - `READ_COMMITTED` 가 고정 기본값이고, **모든 트랜잭션 템플릿에 명시적으로** 설정한다. vendor 기본값에 위임하지 않는 이유: 엔진마다 기본 isolation 이 다르다(PostgreSQL = READ COMMITTED, MySQL InnoDB = REPEATABLE READ). 위임하면 같은 코드가 DB 에 따라 다른 isolation 으로 도는 silent 위험이 생긴다. - `REPEATABLE_READ` / `SERIALIZABLE` 은 쓰기 무거운/읽기 일관성 유스케이스를 위한 명시적 opt-in. `READ_UNCOMMITTED` 는 금지라 enum 에 아예 선언하지 않았다. - 단, 더 엄격한 레벨을 TransactionPort 호출 경로로 라우팅하는 per-use-case 선택 메커니즘은 관련 추상화 설계와의 공동 변경이라 아직 `planned` 다. 그전까지 이 상수들은 **어휘만** 선언하고, 실제 호출 경로는 `READ_COMMITTED` 로 고정된다. --- ## 인가 (security) 인증("누구냐")은 web/security adapter 책임이고, 이 패키지는 인가("이걸 해도 되냐")만 소유한다. ### AuthorizationPort - 제품 인가 enforcement point(PEP). 인증된 호출자가 권한이 필요한 연산을 수행해도 되는지 결정한다. 인증된 principal 의 raw role 을 입력으로 받는다(인증 자체는 베이스라인 소유). - **왜 포트인가, `@PreAuthorize` 가 아니라**: Spring method-security 애너테이션은 빈을 `org.springframework.security` 타입에 묶는다. application/domain 은 프레임워크-free 여야 하므로 (TransactionPort 선례), enforcement *결정* 은 평범한 Java 포트로 표현하고 Spring 의존 enforcement *메커니즘*(커스텀 `AuthorizationManager`)은 web adapter 에 둔다. - **fail-closed**: 호출자가 필요한 권한을 가진 경우에만 정상 반환한다. 그 외(미지 role, role 없음, 매핑 누락)는 전부 `AuthorizationDeniedException`. ### RequiresPermission (애너테이션) - 인증된 호출자가 가드된 유스케이스를 호출하려면 가져야 하는 `Permission` 을 선언한다. 값은 `resource:action` 토큰(예: `"worklog:close"`). `@UseCaseCapability` 패턴을 그대로 따라, 유스케이스가 요구하는 권한을 본문 없이 보이게 한다. - **순수 선언 — Spring-free**: Spring Security 타입을 일절 담지 않는다. 실제 enforcement 는 web adapter 의 `RequiresPermissionAuthorizationManager` 가 RUNTIME retention 으로 이 애너테이션을 읽어 `AuthorizationPort` 에 위임한다. enforcement 가 Spring AOP 프록시를 거치므로 self-invocation 이나 비-Spring 빈 호출은 우회된다 — 모든 mutating 진입점을 가드하는 책임은 아키텍처 강제 규칙 몫이다. - **적용 대상**: skeleton 기본은 mutating/민감 유스케이스(`repositoryAccess = WRITE_REPOSITORY`)에 필수, public read 는 항상 면제(D4). 타입/메서드 어디에도 붙일 수 있다. ### AuthorizationPrincipal - `AuthorizationPort` 가 소비하는 프레임워크-free 호출자 뷰 — IdP subject + 호출자의 raw role 이름. web adapter 는 Spring 인지 principal(`AuthenticatedPrincipal`, Keycloak 스타일 raw role)을 노출하지만 application 계층은 그 타입을 import 할 수 없으므로, enforcement point 가 이 추상으로 내려 매핑한다. - **role 은 raw, Spring authority 가 아니다**: role set 은 IdP 가 발급한 그대로의 문자열 (`"admin"`, `"user"`)이며 `ROLE_*` GrantedAuthority 형태가 아니다. role→permission 해석이 raw 이름을 키로 쓰므로(D3), 둘을 섞으면 권한 0개로 해석돼 fail-closed denial 이 된다. ### AuthorizationDeniedException - 인증된 호출자가 필요한 `Permission` 을 못 가졌을 때 `AuthorizationPort` 가 던진다. - **프레임워크-free, application 소유**: application 계층은 Spring Security 에 의존할 수 없어 Spring `AccessDeniedException` 을 던질 수 없다. web adapter 의 method-security enforcement point 가 경계에서 이 예외를 잡아 Spring authorization 실패로 번역하고, error pipeline 이 `AUTHZ_INSUFFICIENT_PERMISSION` 403 으로 매핑한다(코드 SSOT 는 베이스라인 소유). - **fail-closed**: denial 은 필요한 권한과 호출자 subject 만 담고, 호출자의 *유효 권한 집합* 은 절대 담지 않는다(인가 표면을 클라이언트에 노출하지 않기 위함). --- ## 멱등성 (idempotency) application 계층이 claim·replay·복구 **정책** 을 소유하고, 저장은 `IdempotencyStorePort` 로 위임한다. 패키지는 `dev.caskeleton.application.idempotency` 하나다. 예전 V1(`IdempotencyScope`, `tryBegin/complete/discard`)은 삭제됐고, owner-safe 계약이 유일한 세대다. ### IdempotencyExecutor - application 유스케이스 경계에서 멱등 실행을 조율한다. 입력은 `IdempotencyScopeDigest`, `RequestFingerprint`, caller 가 응답 유실 뒤에도 보관하는 `IdempotencyClaimAttempt` (`newAttempt(operationId)` 로 만든다), `IdempotentAction`, `IdempotentResponseCodec` 이다. - 흐름: **claim → markExecutionStarted → action 실행 → complete(또는 markFailed)**. - `COMPLETED` record 는 저장된 응답을 codec 으로 재생한다. - 같은 scope 에 다른 fingerprint → `IdempotencyRequestMismatchException` → 422. - 다른 owner 가 진행 중 → 기다리지 않고 바로 `IdempotencyInFlightException` → 409. - store 응답이 유실(`INDETERMINATE`)되면 `inspect` 로 실제 상태를 읽어 이어가거나 멈춘다. - 모든 상태 전이는 owner 핸들(owner token + attempt + operation ID + state revision)을 compare-and-set 으로 검증한다. 전이가 성공하면 revision 이 올라간 새 핸들을 다음 호출에 쓴다. - action 결과는 `IdempotentAction.Outcome` 으로 분류한다. `RetryableNoEffect` 만 재시도 가능한 실패로 기록하고, `EffectUnknown` 이나 그냥 던진 예외는 "효과 불명"(`ABANDONED`)으로 남긴다. 한 번 실행됐을지 모르는 작업을 재시도로 두 번 돌리지 않기 위해서다. - processing lease 와 replay TTL 은 따로 간다. 넘겨받을 수 있는 것은 만료된 `CLAIMED` 와 재시도 가능한 실패뿐이고, 다음 claim 이 누구든 넘겨받는다 — 같은 attempt 를 다시 보낸 caller 도 새 attempt 번호로 넘겨받는다(라운드6 RR6-02-01: 전에는 같은 attempt 가 이 기록을 재생받아 시작을 다시 거절당했다). 넘겨받기 전 핸들은 같은 attempt 가 들고 있어도 낡은 핸들이라 시작이 확인되지 않는다. 이미 적용된 전이(start·renew· complete·markFailed·release)를 "이미 처리됨"으로 확인받는 것은 그 전이를 적용한 핸들뿐이다. 넘겨받은 뒤에 일어난 complete·markFailed 를 넘겨받기 전 핸들로 다시 보내면 `NOT_OWNER` 다(2026-11-06 소유자 결정). renew 를 적용한 핸들로 start 해도 `NOT_OWNER` 다 — 기록은 그 핸들보다 revision 이 하나 높지만 거기로 옮긴 것은 start 가 아니라 renew 다. markFailed 를 적용한 핸들이 다른 disposition 으로 다시 보내면 `OPERATION_CONFLICT`(기록된 실패는 그대로), retention 만 다르면 "이미 처리됨"이다. retention 은 complete 의 replay TTL 처럼 비교하지 않는다(2026-11-07 소유자 결정). 한 attempt 를 두 호출이 동시에 쓰는 것은 가려내지 못하므로 재시도는 앞 호출이 돌아온 뒤에 한다. 만료된 `EXECUTING` 은 다른 caller 에게 `RECOVERY_REQUIRED` 로 답하되 기록은 그대로 둔다. 주인이 늦게 보고한 결과·실패는 기록된다 — 먼저 온 보고 하나만 남고 뒤의 보고는 거절된다(2026-11-04 소유자 결정, 재리뷰 RR5-01-03). lease 가 이미 끝났으면 주인도 시작(`markExecutionStarted`)과 `renew` 를 할 수 없고 `LEASE_EXPIRED` 를 받는다. 이 값은 `NOT_OWNER`(기록이 남에게 넘어감)와 다르다: 시작 전이면 아무것도 돌지 않았고 다음 claim 이 넘겨받으며, executor 는 503 `IDEMPOTENCY_UNAVAILABLE`(실행 전 거부)로 답한다. 실행 중이면 주인은 여전히 `complete`·`markFailed` 할 수 있다(RR5-01-02). - 생성은 app-bootstrap `IdempotencyProviderSelectionConfig` 가 한 번 한다(`IdempotencySettings`: processing lease 30s, replay TTL 24h(최대 72h), failure retention 24h(replay TTL 이상), codec id `json-v2`, policy revision 2). 유스케이스나 서비스 설정이 직접 만들지 않는다. - 이 계약은 요청 재생(replay) 근거를 남길 뿐이다. store 와 비즈니스 DB 사이의 exactly-once 를 보장하지 않는다. ### IdempotencyStorePort - provider 중립 owner-safe 상태 기계 포트. 메서드: `newClaimAttempt`, `claim`, `markExecutionStarted`, `renew`, `complete`, `markFailed`, `releaseBeforeExecution`, `inspect`. - 상태: `CLAIMED` / `EXECUTING` / `COMPLETED` / `FAILED_RETRYABLE` / `ABANDONED`(`IdempotencyState`). - 구현은 provider 하나만 붙는다: `redis`(`adapter:outbound:cache-redis` `RedisIdempotencyStoreAdapter`) 또는 `postgresql`(`adapter:outbound:persistence-jpa` `PostgreSqlIdempotencyStore`). `app.capabilities.idempotency.provider` 로 고르고 기본값은 `disabled` 다. store 가 정확히 하나가 아니면 기동을 거부한다. - **in-memory 프로덕션 구현 금지**. 테스트용 `InMemoryIdempotencyStore` 는 testFixtures 에만 있다. ### IdempotencyScopeDigest - 멱등 요청의 정체성. principal·클라이언트 key·operation code 를 **caller 가 먼저 versioned HMAC-SHA-256 으로 digest** 한 값이다(`digest`, `keyDigestVersion`, `operationCode`). - raw 클라이언트 key 와 principal 은 executor·store·로그·메트릭 어디에도 닿지 않는다. 예외 메시지의 진단 문자열도 이 digest 로만 만든다. - digest 를 만드는 쪽(키 링, 버전 교체)은 adapter 나 유스케이스 소유다. ### RequestFingerprint - 요청 body 의 SHA-256 지문(D8). 같은 scope 인데 body 가 다르면(지문이 다르면) 클라이언트 버그로 보고 executor 가 422 로 거부한다. null/빈 body 는 zero-length payload 지문으로 취급해 빈 replay 의 일관성을 지킨다. - **SHA-256 선택(표준이 강제한 값 아님 — 스켈레톤 기본 선택)**: MD5/SHA-1 대비 충돌 저항성 때문에 SHA-256 을 골랐다 — 인용 가능한 표준이 강제한 것도, 측정된 성능 근거가 있는 것도 아니다. body **정규화**(JSON 키 순서·공백·인코딩)는 의도적으로 적용하지 않는다 — 전송된 raw 바이트를 그대로 해시한다. 정규 동등성이 필요한 caller 는 `ofSha256` 호출 전에 직접 정규화해야 한다. 안 하면 키 순서만 바뀐 의미상 동일 replay 가 false mismatch 가 된다(부하와 실제 요청 형태로 검증 필요). - `NoSuchAlgorithmException` catch 는 도달 불가다(SHA-256 은 모든 JDK 에 필수). 그래서 `IllegalStateException` 으로 감싼다. ### 멱등성 값/계약 타입 (StoredResponse · Codec · Action) - `StoredResponse` — 완료된 응답의 불투명 직렬화 표현으로, 중복 caller 에게 그대로 재생된다(§B). 어디에 어떻게 저장되는지는 provider 관심사다. PostgreSQL store 는 8 KiB 이하 응답만 행에 inline 으로 저장하고, 넘으면 거부한다(별도 object store 경로는 없다). - `IdempotentResponseCodec` — 유스케이스 결과를 `StoredResponse` payload 로 직렬화/역직렬화. application 은 wire-format 중립이다 — 구체 JSON 인코딩은 `R` 의 응답 모양을 아는 adapter 가 소유하고(예: web-advanced `JsonIdempotentResponseCodec`), executor 는 그 문자열을 store 로 왕복시키기만 한다. - `IdempotentAction` — 실행할 작업. 결과를 `Outcome.Success` / `RetryableNoEffect` / `EffectUnknown` 으로 돌려준다. - complete/fail/release 재호출은 operation ID 와 result digest 가 같을 때만 이전 결과로 재생한다. ### 멱등성 예외 (공통 패턴) - `IdempotencyRequestMismatchException`(422 `IDEMPOTENT_REQUEST_MISMATCH`), `IdempotencyInFlightException`(409 `IDEMPOTENT_IN_FLIGHT`), `IdempotencyUnavailableException`(실행 전 거부: store 에 닿지 못함, 또는 claim 의 lease 가 시작 전에 끝남), `IdempotencyRecoveryRequiredException`(첫 시도가 효과를 냈는지 증명하지 못함). - 모두 **프레임워크-free, application 소유**(`AuthorizationDeniedException` 선례). web adapter 가 경계에서 HTTP 코드로 매핑한다. 진단 메시지는 scope digest 만 **로그용으로** 담고, 클라이언트에는 핸들러가 고정 client-safe 메시지로 대체한다(fingerprint 자체는 노출 안 함). - retryable: mismatch 는 `false`(body 를 고쳐야 한다). in-flight 는 `true`: 결과 불명. 같은 `Idempotency-Key`로 `Retry-After` 뒤 재전송. 새 키 금지(`docs/web/http-contract.md` §2). recovery-required 는 재생도 재실행도 안전하지 않다 — 비즈니스 데이터로만 판단할 수 있다. --- ## 트랜잭셔널 아웃박스 릴레이 (outbox) 핵심 패턴: 비즈니스 쓰기와 같은 트랜잭션에 이벤트를 append → 별도 relay 가 짧은 트랜잭션으로 claim → 트랜잭션 밖에서 발행 → at-least-once 보장. ### OutboxAppendPort - 트랜잭셔널 아웃박스에 새 이벤트를 append 하는 outbound 포트. - **dual-write 금지(D2)**: 반드시 이벤트를 만든 비즈니스 연산과 **같은 DB 트랜잭션 안에서** 호출해야 한다(그 트랜잭션은 caller 가 `TransactionPort.inWrite` 로 연다). 트랜잭션 밖에서, 또는 비즈니스 연산과 다른 트랜잭션에서 호출하면 dual-write 금지 위반이다 — 비즈니스는 커밋됐는데 outbox append 가 안 되거나(또는 그 반대) 이벤트가 silent 손실/허위 방출된다. 따라서 구현은 내부에서 새 트랜잭션을 열면 안 되고, 바깥 트랜잭션에 참여해야 한다. ### OutboxStorePort - relay 측에서 outbox store 에 접근하는 포트. 모든 mutating 연산 (`claimBatch`/`markPublished`/`markFailed`/`markDeferred`/`releaseLease`/`markDead`)은 relay 유스케이스가 소유한 `TransactionPort.inWrite` 경계 안에서 호출하며, 구현은 자체 트랜잭션을 열지 않는다. - **claim 의미(I4 / I6)** — `claimBatch` 가 적격 행을 atomic 하게 `IN_FLIGHT` 로 전이시킨다: - 적격 행: `PENDING`, `next_attempt_at <= now` 인 `FAILED`, `next_attempt_at <= now` 인 `IN_FLIGHT`(고아 in-flight — I6 timeout 재사용). - **FIFO 게이트(I4)**: 같은 `aggregate_id` 의 더 이른 `occurred_at` 행이 아직 `PUBLISHED` 가 아니면 그 aggregate 의 뒤 행들은 skip 한다. `DEAD` 행도 그 aggregate 큐를 막는다(strict FIFO — 해제하려면 runbook 개입 필요). - claim 후: `status = IN_FLIGHT`, `attempt_count += 1`, `next_attempt_at = now + inFlightTimeout`, `lease_owner = owner`, `lease_token += 1`. claim 결과는 행마다 `OutboxLease(event, owner, token)`이다. - 순서: adapter 는 claim 쿼리에 `ORDER BY occurred_at ASC` 를 쓰는 게 좋고, relay 도 받은 배치를 방어적으로 재정렬한다. - **in-flight timeout 재사용(I6)**: `next_attempt_at` 컬럼을 in-flight 고아 timeout 으로 재사용한다. relay 인스턴스가 죽어 `IN_FLIGHT` 로 남은 행이 `next_attempt_at` 을 지나면 다음 폴링에서 다시 claim 가능해진다. 별도 `claimed_at` 컬럼 없이 at-least-once 전달을 보장하는 트릭. - **lease fencing**: in-flight timeout 뒤 다른 relay 가 행을 다시 claim 할 수 있으므로 완료 (`markPublished`/`markFailed`/`markDead`)는 lease 를 받아, 행이 아직 `IN_FLIGHT` 이고 owner·token 이 같을 때만 적용된다. 결과는 `OutboxCompletion.APPLIED`/`STALE` 이고 `STALE` 이면 아무것도 쓰지 않는다. 그래서 timeout 을 넘겨 멈췄던 relay 가 행을 넘겨받은 relay 의 결과를 덮지 못한다. relay 는 `STALE` 을 `Outcome.STALE` 로 남기고 `reportStaleCompletion` 으로 알린 뒤 넘어간다. owner 는 relay 인스턴스마다 한 번 만든 UUID 다. fake 는 testFixtures `InMemoryOutboxStore`, 계약은 `OutboxLeaseFencingContract`(fake 와 PostgreSQL adapter 가 같은 계약을 통과). - `countByStatus` / `oldestUnpublishedAgeSecondsByEventType` 는 메트릭 게이지 (`outbox.pending.size`, `outbox.publisher.lag`)의 데이터 소스다. 트랜잭션 밖 read-only (metric-scrape 경로)로 호출된다. ### OutboxMessagePublishPort - claim 된 outbox 이벤트를 메시지 브로커에 발행하는 outbound 포트. - **fail-closed 계약(I8)**: 발행 실패는 반드시 `RuntimeException` 으로 표면화해야 한다. 구현은 예외를 삼키거나 실패 시 log-and-return 하면 안 된다. 일반적인 fail-open 메시징 publisher(잡고 로그 후 정상 반환)와의 **의도적·문서화된 차이** 다 — relay 의 Failure condition 이 발행 실패를 예외로 관측해야 FAILED/DEAD 전이 + typed failure report를 구동할 수 있기 때문. 삼킨 실패 (예외 없음·전이 없음·report 없음)가 금지 조건이다 — 행이 영원히 `IN_FLIGHT` 로 남고, aggregate FIFO 큐가 조용히 막히며, 메트릭엔 이상이 안 보인다. - **호출 위치**: relay 유스케이스가 **트랜잭션 밖에서** 호출한다. 짧은 `inWrite` 로 배치 claim → 트랜잭션 해제 → 발행 → 결과별로 다시 짧은 `inWrite` 로 상태 갱신. 브로커 호출이 진행되는 동안 트랜잭션 보유 시간을 최소화한다. ### PublishPendingOutboxEventsUseCase (릴레이 본체) - pending outbox 이벤트를 claim 해 브로커에 발행하는 relay 유스케이스. - **알고리즘(claim short, publish outside tx)**: 1. 짧은 write 트랜잭션 안에서 배치를 claim 한다. 2. `occurred_at` 오름차순으로 방어적 정렬(claim 쿼리도 정렬하지만, adapter 가 안 해도 relay 가 FIFO 를 강제한다). 3. 각 이벤트를 **트랜잭션 밖에서** 발행하고 결과로 상태 머신을 구동한다: - 발행 성공(`CONFIRMED`) → `inWrite { markPublished }` → `PUBLISHED`. - 확정 거부(`REJECTED_BEFORE_SEND`·`REJECTED_AFTER_BROKER`) → 시도 예산과 무관하게 바로 `markDead`. - 일시적 실패(`AMBIGUOUS`·`REJECTED_RETRYABLE`, 즉 `OutboxPublishOutcome.retryable()`) → 시도 예산을 쓰지 않고 항상 `markDeferred(nextAttemptAt, failureCode)`(FAILED 전이 + 미룬 시도로 기록). broker 정지·종료 중·permit 부족· credential 교체는 모든 행을 같은 방식으로 실패시키고 저절로 끝나므로, 예산을 쓰게 하면 몇 분 장애가 aggregate 머리마다 DEAD 행을 남긴다(2026-11-01 리뷰 06-01·06-03). 대가로 끝이 없다 — 저절로 풀리지 않는 원인(진짜 credential 오류, Kafka adapter가 이름을 모르는 broker 거부)이면 영원히 재시도된다. 그래서 모든 실패 전이는 원인 코드를 함께 적는다(`OutboxPublishAttempt.failureCode`: publisher가 붙인 코드, 없으면 결과 이름, 던진 예외면 그 타입 이름 → 행 `last_failure_code`, 보고 `failureCode`). 오래 미룬 행은 `OutboxStorePort.longRetries`로 세고, 운영자는 그 행을 `PARKED`로 보류할 수 있다(재리뷰 2026-11-03 RR-05-03, publish-failed runbook §4.1). - 발행 예외(`RuntimeException`, adapter가 분류하지 못한 실패): `budgetedAttemptCount() >= maxAttempts` 면 `markDead`, 아니면 `markFailed(nextAttemptAt)`. 예산은 이 경우에만 쓴다 — payload 자체 결함일 수 있는 실패가 aggregate를 영원히 막지 않게 하는 장치다. `budgetedAttemptCount() = attemptCount - deferredAttemptCount`: 미룬(일시적 실패) claim은 빼고, 결과를 남기지 못하고 죽은 claim(lease 만료)은 센다. 그래서 장애를 오래 기다린 행도 그 뒤 예산을 온전히 받는다(예전 한계: `attemptCount`가 일시 실패 claim까지 세어 첫 발행 예외에서 바로 DEAD). 재시도 지연은 계속 전체 `attemptCount`로 늘어나 긴 장애에서도 최대 5분 간격을 유지한다. - 멈춤 요청(`PublishPendingOutboxEventsCommand.stopRequested`, 종료 중인 scheduler가 건다): 지금 발행을 끝낸 뒤 남은 claim은 발행하지 않고 `releaseLease(now)`로 놓는다 → `PENDING`, 시도 수에서 그 claim을 빼고 바로 claim 가능. 결과는 `RELEASED`. - 전이를 먼저 성공시킨 뒤 해당 typed failure report를 보낸다. - `nextAttemptAt` 의 기준 시각은 **그 행이 실패한 시각**(`clock.instant()`)이다. 회차 시작 시각을 쓰면 broker가 멈춘 동안 publish 하나가 deadline(약 5초)을 다 쓰므로 배치 뒤쪽 행은 표시되는 순간 이미 재시도 시각이 지나 있어 지연이 사라진다. - **발행 실패는 절대 삼키지 않는다**: relay 는 각 발행 예외를 잡아 FAILED/DEAD 상태 머신을 구동하고, 성공한 전이만 `OutboxRelayFailureReportPort`로 보고한 뒤 rethrow 하지 않는다 (스케줄러 루프가 다음 이벤트로 계속 가야 하므로). 상태 전이가 실패하면 예외가 전파되고 report는 없다. reporter가 `RuntimeException`을 던져도 persisted outcome을 바꾸거나 다음 이벤트를 막지 못한다. - **안전한 allowlist report**: `OutboxRelayFailureReport`는 `code/eventId/eventType/aggregateId/correlationId/attemptCount/nextAttemptAt/cause`만 가진다. payload, envelope bytes, whole `ClaimedOutboxEvent`, severity/template, arbitrary map은 타입 수준에서 전달할 수 없다. retry factory는 `OUTBOX_PUBLISH_FAILED`와 필수 `nextAttemptAt`, dead factory는 `OUTBOX_DEAD_LETTER`와 null retry time을 고정한다. - **상태 갱신 실패는 시끄럽게 전파한다**: 발행 성공 후의 `markPublished` 실패는 store/인프라 에러지 발행 실패가 아니다. 따라서 FAILED/DEAD 머신을 구동하면 안 된다(이미 전달된 이벤트를 dead-letter 하는 꼴). 대신 스케줄러 catch 블록으로 전파되고, 행은 `IN_FLIGHT` 로 남아 고아 visibility-timeout 재claim 경로로 복구된다 → 재발행 → consumer dedupe 가 중복을 흡수(at-least-once). 배치 중간의 상태 갱신 실패가 그 tick 의 남은 배치를 중단시키는 것은 허용된다 — DB 가 실패 중이면 뒤따르는 갱신도 실패할 테고, 다음 tick 이 모든 `IN_FLIGHT` 고아를 재시도하기 때문. - **수동 와이어링(@Service 아님, context 빈 아님)**: outbox-relay composition이 직접 생성한다 (`batchSize`·`inFlightTimeout` 같은 설정값이 필요해서 자동 등록이 안 된다). `UseCaseCapability` 는 빈 등록 방식과 무관하게 필수다(ArchUnit 강제). 그리고 **Spring 빈으로 등록하면 안 된다**: relay를 부르는 것은 스케줄러뿐이고, 스케줄러 스레드에는 `Authentication`이 없다. 빈으로 노출하면 전송 계층이 권한 검사 없이 닿을 수 있다. - **권한 선언 없음 — `@SystemInvoked`**: relay는 엔드유저가 아니라 시스템이 부르는 유스케이스라 `@RequiresPermission`을 달지 않고 `@SystemInvoked(reason = ...)`로 그 사실을 적는다. 예전의 `@RequiresPermission("outbox:relay")`는 D4 규칙을 통과시키려고 붙인 장식이었다(빈이 아니라 한 번도 검사되지 않았고, 빈이었다면 매 tick 거부됐다). ArchUnit D4는 `@SystemInvoked`를 권한 선언 대신 받고, `SYSTEM_INVOKED_USE_CASES_DECLARE_NO_PERMISSION`이 둘을 함께 다는 것을 막는다. 면제의 전제(사용자 요청이 닿지 않는다)도 코드가 지킨다: `@SystemInvoked` 빈은 `PermissionEnforcementGuard`가 기동을 실패시키고, `@SystemCaller`가 아닌 inbound adapter가 그 클래스에 의존하면 `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`가 빌드를 실패시킨다(review 2026-11-03 RR-01-02, RR-01-12). 메시지 소비자는 `@SystemCaller` handler가 use case를 직접 만든다(매뉴얼 09장 「소비」 4단계). 시스템 호출자 세 가지(조립 모듈의 스케줄러, `@SystemCaller` 메시지 handler, `@SystemCaller` 예약 작업)와 각각 두는 곳은 매뉴얼 07장 「시스템이 부르는 쓰기」가 정본이다. ### OutboxBackoffPolicy - relay 재시도 스케줄링 정책(I10). 이름과 달리 "full jitter" 가 아니다 — full jitter 는 0 을 고를 수 있고, relay 재시도가 실패한 그 순간에 다시 due 가 되면 안 된다. - 공식: `base = 30s`, `maxDelay = 5m`, `maxAttempts = 3`, `delay = ceiling(attemptCount) + U[0, base]`, `nextAttemptAt = failedAt + delay`. `ceiling` 은 shared-contract `Backoff` 의 `base × 2^(attemptCount-1)` 이고 `maxDelay`(5분)에서 멈춘다. `attemptCount` 는 방금 실패한 시도의 1-based 번호다. 예산 안(1·2회차)의 값은 30s·60s 그대로라 registry·runbook 숫자가 유지된다. - `maxAttempts` 는 발행 예외(분류되지 않은 실패)에만 적용된다. 일시적 결과(`retryable()`)는 예산 없이 `maxDelay` 간격까지 늘어나며 계속 재시도된다. 그래서 broker가 돌아오면 늦어도 약 5분 30초 안에 적체가 저절로 빠진다. - 버린 대안: `MAX_ATTEMPTS` 만 늘리기(장애 길이에 비례해 계속 키워야 하고 진짜 poison 행이 늦게 격리된다), 예산을 설정 키로 외부화(I10 — registry·runbook과 어긋난다; 일시적 실패가 예산을 쓰지 않으므로 장애 길이에 맞춰 예산을 조정할 이유도 사라졌다), 일시적 실패 시 `attempt_count` 되돌리기 (지수 간격을 키울 근거가 사라진다 — 그래서 별도 열 `deferred_attempt_count`(V20)로 센다). - 더하는 spread 는 한 base 짜리 full jitter(`Backoff#fullJitter`, `[0, base]` 균등)이며 주입된 `RandomGenerator` 로 뽑는다. 0 을 반환하는 generator 를 주면 테스트가 결정적이 된다(I10). - **상수는 고정이다(I10)**: `BASE_DELAY`·`MAX_ATTEMPTS`·jitter 범위는 설정 프로퍼티가 아니다. 외부화하면 registry alert 임계치(`error-codes.yaml` 의 `retry_after_seconds=30`)와 `outbox-publish-failed` runbook 이 실제 런타임 값과 어긋난다. 이 상수는 registry·runbook 업데이트와 **함께만** 바꾼다. - 지수 계산의 overflow 는 `Backoff` 가 포화 연산으로 막는다. ### outbox 값/상태 타입 (Status · ClaimedOutboxEvent · RelayResult · Command) - `OutboxEventStatus` — 행 상태 머신(D5). `PENDING → IN_FLIGHT → {PUBLISHED | FAILED | DEAD}`, `FAILED → IN_FLIGHT`(재claim), `IN_FLIGHT 고아 → IN_FLIGHT`(I6). `DEAD` 는 FIFO 형제를 막는다 — 같은 aggregate 의 뒤 행 claim 을 차단하므로 runbook 개입이 필요하다. `PARKED` 는 운영자만 만든다 (`FAILED → PARKED`, runbook SQL): claim 되지 않고 DEAD 처럼 FIFO 형제를 막는다. 재개는 `PARKED → FAILED`, 버리기는 `PARKED → PUBLISHED`. relay 의 어떤 전이도 `PARKED` 로 가거나 나오지 않는다. - append 는 `OutboxAppendPort.append(ValidatedIntegrationEvent)` 하나다(2026-09-28, 소유자 결정 7). use case 가 `IntegrationEventDraft` 를 만들고 `IntegrationEventEncoderPort` 로 encode 한 뒤 같은 write 트랜잭션 안에서 append 한다. consumer 의 중복 제거 키는 event id 다. - `ClaimedOutboxEvent` — `claimBatch` 가 반환하는 claim-result 읽기 모델. append 된 validated event (저장된 exact envelope bytes 에서 복원) + 현재 `status` + `attemptCount`. relay 가 `attemptCount` 로 다음 실패 시 dead-letter 여부를 결정한다. 옛 `OutboxEvent`/`NewOutboxEvent`/`LegacyOutboxAppendPort` (free-text payload 모델)는 삭제됐다. - `OutboxRelayResult` — relay 한 사이클의 결과. `claimedCount` + per-event outcome 목록. 내부 `Outcome` enum 이 `OutboxEventStatus` 를 재사용하지 않고 5값(PUBLISHED/FAILED/DEAD/STALE/RELEASED — STALE 은 lease 를 잃어 결과를 쓰지 못한 경우, RELEASED 는 멈추는 relay 가 쓰지 않은 claim 을 놓은 경우)을 따로 두는 이유: relay 관점은 "이번 실행에서 무슨 일이 있었나" 이지 "행의 현재 영속 상태" 가 아니다(후자는 store 가 `OutboxEventStatus` 로 추적). 이 5값이 `outbox.publisher.published.total` 의 `outcome` label 이다(`docs/registries/metrics.yaml`, 계약 테스트가 비교). - `PublishPendingOutboxEventsCommand` — relay 커맨드 마커. 스케줄러 구동이라 caller 파라미터가 없고, 모든 운영 파라미터는 생성 시점에 주입된다(IdempotencyExecutor 선례). 호출마다 새 인스턴스를 만들 필요가 없게 `INSTANCE` 싱글톤을 제공한다. - `OutboxRelayFailureReportPort` / `OutboxRelayFailureReport` — confirmed FAILED/DEAD 상태를 adapter에 전달하는 framework-free outbound contract. 구조화 ERROR 필드와 runbook 렌더링은 messaging adapter가 소유한다. ### outbox V2 (삭제됨) `outbox.v2`(immutable storage + polling delivery 포트·유스케이스)는 어떤 composition 도 조립하지 않은 세대라 2026-09-25 에 삭제했다(`docs/capability-status.md` "제거된 코드"). 그 설계에서 가져온 owner/token CAS 는 위 `OutboxStorePort` 의 lease fencing 이다. --- ## 분산 락 (lock) application 계층은 락 획득/해제 계약만 알고, 실제 구현은 adapter 가 소유한다. ### DistributedLockPort - 분산 락 획득 outbound 포트. - **왜 이 포트가 있나(D2)**: 유스케이스는 락 클라이언트·Spring `LockRegistry`·advisory-lock SQL 을 직접 import 하면 안 된다. 이 포트가 application-core 안에서 협조적 상호배제를 위해 허용된 유일한 의존이다. adapter 구현(`JdbcLockRegistry` 멀티 인스턴스, `DefaultLockRegistry` 단일 인스턴스)은 `adapter-persistence` 에 있고 컴파일 타임엔 application 계층에 안 보인다. - **try-lock + 유한 waitTime + 필수 leaseTtl(D5)**: `tryAcquire` 는 try-lock 이다 — 최대 `waitTime` 만 블로킹하고 held 핸들을 반환하거나 `LockAcquisitionTimeoutException` 을 던진다. 무한 블로킹은 금지(항상 유한 `waitTime` 공급). `leaseTtl` 은 JVM 이 `close()` 전에 죽어도 adapter 가 락을 유지하는 최대 시간으로, 죽은 보유자가 시스템을 무한 데드락 시키는 것을 막는다. `JdbcLockRegistry` 는 registry 기본 TTL 과 호출별 lock TTL 을 강제하고, in-process `DefaultLockRegistry` 는 advisory(강제 없음)다. - **트랜잭션 커밋 순서 불변식(D4)**: 반환된 핸들은 보호 작업의 DB 트랜잭션이 **커밋된 후에만** 해제해야 한다. 트랜잭션 안(커밋 전)에서 해제하면 lost-update 경합이 생긴다 — 두 번째 스레드가 락을 얻어, 첫 트랜잭션의 쓰기가 DB 에 보이기 전에 자신의 read-modify-write 를 시작한다. - 올바른 패턴: `tryAcquire` → `try { txPort.inWrite(...) } finally { lock.close() }`(커밋 후 해제). - 금지된 역순: `inWrite` 콜백 안에서 `lock.close()`(커밋 전 해제 → 다른 스레드가 stale 상태를 본다). - **효율 락이지 정합성 락이 아니다(D6)**: 이 락은 경합·불필요한 재시도를 줄이는 *효율* 장치다. 정합성(중복·충돌 쓰기 방지)은 여전히 DB 제약(유니크 인덱스·낙관적 동시성)이 강제한다. 이 락 하나만 정합성 가드로 의존하면 안 된다. - **lease 만료 시 해제(SI-LOCK-C5)**: TTL 기반 provider(`JdbcLockRegistry`)에서 보유자가 `close()` 하기 전에 lease 가 만료되면, 락 행은 이미 다른 인스턴스가 회수했을 수 있다. metered `distributedLockProvider` 가 이를 로그 + 카운트 이벤트(`lock.lease.expired`)로 표면화하고 `close()` 는 정상 반환한다 — 만료가 caller 의 `finally` 를 터뜨리거나 보호 작업 자신의 예외를 가리지 않게 하기 위함. - `leaseTtl` 이 provider 설정 TTL 을 초과하면 `IllegalArgumentException`. shipped 와이어링은 provider 설정과 같은 `LockSettings.leaseTtl()` 로 바인딩하므로 런타임엔 안 터지고, mis-wired caller/test 를 잡는 가드다. ### DistributedLock (핸들) - 획득한 분산 락 핸들(`AutoCloseable`). `close()` 가 해제이고 `finally` 에서 한 번 호출하기에 안전하며, 구현은 idempotent 해야 한다(여러 번 close 해도 throw 금지). - D4 커밋 순서 불변식은 `DistributedLockPort` 와 동일하다 — 커밋 후에만 `close`. - `close()` 가 `AutoCloseable` 의 `throws Exception` 을 제거하도록 override 한 이유: 구현이 해제 시 checked exception 을 던지지 못하게 해서, caller 가 checked-exception 의식 없이 `finally` 에 둘 수 있게 하기 위함. ### LockAcquisitionTimeoutException - `waitTime` 안에 락을 얻지 못하면 `tryAcquire` 가 던진다(D5). - `OperationalError.LOCK_ACQUISITION_TIMEOUT`(CONFLICT, 409, retryable=true)을 운반한다. 락 경합은 일시적이다 — 현재 보유자가 임계 구역을 떠나거나 lease TTL 이 만료되면 재시도가 획득한다(D6 효율 락). - `ApiErrorCarrier` 를 구현한다. 그래서 전송이 따로 처리기를 두지 않아도 web 은 409 + `Retry-After: 1`(레지스트리 값), GraphQL·gRPC 는 같은 코드로 답하고, 4xx 라 서버 로그를 남기지 않는다. 전에는 carrier 가 아니어서 모든 전송이 500 `INTERNAL_ERROR`(재시도 불가)와 "unhandled" ERROR 로 답했다(재리뷰 RR7-01-04). `getMessage()`(key·waitTime 포함)는 클라이언트에 보내지 않고, 로그에도 남지 않는다. 4xx carrier 라 어느 전송도 남기지 않고, 락 adapter 도 timeout 을 남기지 않는다. 어느 락이 막혔는지 기록이 필요하면 호출자가 `key()` 를 직접 남긴다(엔티티 id 는 빼고). 운영 절차는 `docs/runbooks/lock-acquisition-timeout.md` (`lock.acquisition` metric, `INT_LOCK` 보유자 조회)다(재리뷰 RR8-01-02). --- ## 알림 타입은 이 leaf에 없다 (application-notification) `NotificationPort`·`Notification`·`NotificationChannel`과 알림 플랫폼(`..notification.platform..`, NOTIF-ADR-005)은 leaf `application-notification`(`src/application-notification`)이 소유한다. 패키지 이름이 `dev.caskeleton.application.notification`이라 이 leaf의 것처럼 보일 뿐이다. 설명과 규칙은 그 leaf의 코드 Javadoc과 `docs/notification/`이 정본이다. R1 오케스트레이션 타입은 2026-09-25에 삭제했다. --- ## 로그 가명화 포트 (observability) ### CorrelationIdPort - 현재 application invocation의 correlation id를 `Optional`으로 읽는 framework-free 경계다. application use case는 MDC나 SLF4J를 직접 알지 않는다. - inbound web adapter가 sanitized `correlation_id` MDC 슬롯을 구현 세부로 읽는다. - 값이 없거나 blank이면 event publisher는 생성한 event id를 correlation id로 재사용해 기존 self-correlation 동작을 유지한다. ### UserPrincipalPseudonymizerPort - raw 보안 principal id 를, 값이 로그/MDC 에 쓰이기 전에 안정적 가명 토큰으로 바꾸는 outbound 포트. - **null/blank 의미**: `rawPrincipal` 이 null/blank 면 null 을 반환한다. 가명화할 게 없으니, 이 경우 caller 는 `user_principal` MDC 키에 아무 값도 넣으면 안 된다. - **안정 토큰 계약**: non-blank 입력에 대해 (1) 같은 입력 + 같은 salt 는 같은 salt epoch 안에서 항상 같은 출력을 낸다(안정), (2) raw principal 의 trivial 복원이 불가능하다(일방향 derivation 이지 인코딩·가역 변환이 아니다), (3) `user_principal` MDC 와 로그 라인에 안전하다. - **알고리즘 SSOT**: 구체 알고리즘(90일 회전 salt 로 keyed 한 HMAC-SHA-256)은 이 영역의 책임다. 이 포트는 "보안 principal 을 가명 형태로 기록한다" 는 계약만 소유한다. 구현은 `adapter-identifier` 에 있고 `app-bootstrap` 이 와이어링한다. - **계층**: 순수 Java 인터페이스다. 구현은 application-core/domain-core 에서 참조하면 안 된다. consumer(`adapter-web` 의 `RequestLoggingFilter`)가 이 포트를 주입받아 `AuthenticatedPrincipal.idpUserId()` 를 가명화한 뒤 `MDC.put("user_principal", ...)` 한다. ### OutboxAggregateSequencePort (2026-11-01 리뷰 06-07) - aggregate의 다음 순서 번호(`AggregateOrder.sequence`)를 append와 같은 caller 쓰기 트랜잭션에서 준다. claim gate와 소비자가 이 번호로 "어느 변경이 나중인가"를 판단하므로 번호는 커밋 순서를 따라야 한다. 벽시계(예전 샘플의 epoch 마이크로초)는 인스턴스 사이 시계 차이·NTP 되돌림·같은 마이크로초 두 건에서 커밋 순서와 달라진다. - 계약(`OutboxAggregateSequenceContract`, fake `InMemoryOutboxAggregateSequences`와 JPA 구현이 공유): aggregate마다 첫 번호부터 하나씩 커지고, 첫 쓰기 두 개가 겹쳐도 둘 다 성공하며, aggregate끼리 독립이다. 첫 번호는 구현마다 다르다(fake는 1). JPA 구현(`JpaOutboxStore`, V21 `outbox_aggregate_sequence`)은 counter row lock으로 같은 aggregate 쓰기를 직렬화하고, 남은 outbox row의 최대 번호와 V21이 기록한 floor(적용 시각의 epoch 마이크로초) 중 큰 값 다음에서 시작한다. 그래서 reaper가 지웠거나 identity가 바뀐 aggregate도 옛 벽시계 번호보다 뒤에서 시작한다. 같은 `(tenant_scope, aggregate_type, aggregate_id, aggregate_sequence, event_index)` 두 번째 append는 V21 유일 인덱스가 append 시점에 거부한다. - aggregate가 자체 version 열(낙관적 락)을 가지면 그 값을 써도 된다. 이 포트는 counter가 없는 aggregate를 위한 것이다. --- ## 비밀 값 해석 (secret) - `SecretSourcePort`와 `SecretReference`(`secret:///` 한 가지 표기)를 둔다. 예전에는 `CallBudget`과 함께 `outbound` 패키지에 묶여 있었다. 세 타입은 서로 관계가 없고 `outbound`는 내용이 아니라 방향을 말하는 이름이라, 2026-11-01 리뷰 01-10에서 내용별로 흩었다. - `CallBudget`은 쓰는 곳이 object storage 계약(요청 record와 content 콜백 context)뿐이라 `application-objectstorage`의 `objectstorage.content`로, 항상 함께 다니는 `CancellationView` 옆에 옮겼다. 다른 전송(HTTP client·gRPC·GraphQL)은 각자의 deadline 타입을 쓴다. - 포트 계약 `secret.testkit.SecretSourceContract`, fake `InMemorySecretSource`(testFixtures).