application-core — 설계 결정 참조
애플리케이션 유스케이스 계층. 패키지 루트: dev.caskeleton.application.
허용/금지 의존, 유스케이스 형태, 트랜잭션 모드, 명명 규칙 같은 모듈 규칙은 AGENTS.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-neutralContractDescriptor만 기여한다. 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/<contract>/v<N>.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).
- 새 version 추가:
v<N+1>.schema.json, 새 payload record, 새IntegrationEventContractContribution. 옛 version의 contribution은 그대로 둔다. encoder catalog는(contractId, payloadVersion)마다 하나라 두 version이 함께 등록된다. - 소비자 배포: 모든 소비자가 v과 v<N+1>을 둘 다 읽게 한다. outbox에 이미 쌓인 v 행은 저장된 바이트 그대로 나가므로, 생산자를 바꾼 뒤에도 한동안 두 version이 함께 도착한다.
- 생산자 전환: draft를 v<N+1> contract로 만든다. 이 커밋에서 manifest에 v<N+1> 줄을 더한다.
- 옛 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 강제). - 제네릭 입출력 타입(
<I, O>)에는 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 가 SpringPlatformTransactionManager로 제공한다. 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 을 던질 수 없다. SpringTransactionCallback<T>제약과 동일하다. 그래서 호출자는 도메인 checked exception 을RuntimeException하위로 감싸야 한다(DomainException extends RuntimeException).IOException→UncheckedIOException,SQLException은 SpringDataAccessException계층이 자동 변환한다. 콜백 안에서 던진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/NEVERpropagation,READ_UNCOMMITTEDisolation, 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_PERMISSION403 으로 매핑한다(코드 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).
COMPLETEDrecord 는 저장된 응답을 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 는 503IDEMPOTENCY_UNAVAILABLE(실행 전 거부)로 답한다. 실행 중이면 주인은 여전히complete·markFailed할 수 있다(RR5-01-02). - 생성은 app-bootstrap
IdempotencyProviderSelectionConfig가 한 번 한다(IdempotencySettings: processing lease 30s, replay TTL 24h(최대 72h), failure retention 24h(replay TTL 이상), codec idjson-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-redisRedisIdempotencyStoreAdapter) 또는postgresql(adapter:outbound:persistence-jpaPostgreSqlIdempotencyStore).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 가 된다(부하와 실제 요청 형태로 검증 필요). NoSuchAlgorithmExceptioncatch 는 도달 불가다(SHA-256 은 모든 JDK 에 필수). 그래서IllegalStateException으로 감싼다.
멱등성 값/계약 타입 (StoredResponse · Codec · Action)
StoredResponse— 완료된 응답의 불투명 직렬화 표현으로, 중복 caller 에게 그대로 재생된다(§B). 어디에 어떻게 저장되는지는 provider 관심사다. PostgreSQL store 는 8 KiB 이하 응답만 행에 inline 으로 저장하고, 넘으면 거부한다(별도 object store 경로는 없다).IdempotentResponseCodec— 유스케이스 결과를StoredResponsepayload 로 직렬화/역직렬화. application 은 wire-format 중립이다 — 구체 JSON 인코딩은R의 응답 모양을 아는 adapter 가 소유하고(예: web-advancedJsonIdempotentResponseCodec), executor 는 그 문자열을 store 로 왕복시키기만 한다.IdempotentAction— 실행할 작업. 결과를Outcome.Success/RetryableNoEffect/EffectUnknown으로 돌려준다.- complete/fail/release 재호출은 operation ID 와 result digest 가 같을 때만 이전 결과로 재생한다.
멱등성 예외 (공통 패턴)
IdempotencyRequestMismatchException(422IDEMPOTENT_REQUEST_MISMATCH),IdempotencyInFlightException(409IDEMPOTENT_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 는 testFixturesInMemoryOutboxStore, 계약은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):
- 짧은 write 트랜잭션 안에서 배치를 claim 한다.
occurred_at오름차순으로 방어적 정렬(claim 쿼리도 정렬하지만, adapter 가 안 해도 relay 가 FIFO 를 강제한다).- 각 이벤트를 트랜잭션 밖에서 발행하고 결과로 상태 머신을 구동한다:
- 발행 성공(
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, wholeClaimedOutboxEvent, 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). 메시지 소비자는@SystemCallerhandler가 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-contractBackoff의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-failedrunbook 이 실제 런타임 값과 어긋난다. 이 상수는 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 목록. 내부Outcomeenum 이OutboxEventStatus를 재사용하지 않고 5값(PUBLISHED/FAILED/DEAD/STALE/RELEASED — STALE 은 lease 를 잃어 결과를 쓰지 못한 경우, RELEASED 는 멈추는 relay 가 쓰지 않은 claim 을 놓은 경우)을 따로 두는 이유: relay 관점은 "이번 실행에서 무슨 일이 있었나" 이지 "행의 현재 영속 상태" 가 아니다(후자는 store 가OutboxEventStatus로 추적). 이 5값이outbox.publisher.published.total의outcomelabel 이다(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-processDefaultLockRegistry는 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 가 만료되면, 락 행은 이미 다른 인스턴스가 회수했을 수 있다. metereddistributedLockProvider가 이를 로그 + 카운트 이벤트(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 가 아니어서 모든 전송이 500INTERNAL_ERROR(재시도 불가)와 "unhandled" ERROR 로 답했다(재리뷰 RR7-01-04).getMessage()(key·waitTime 포함)는 클라이언트에 보내지 않고, 로그에도 남지 않는다. 4xx carrier 라 어느 전송도 남기지 않고, 락 adapter 도 timeout 을 남기지 않는다. 어느 락이 막혔는지 기록이 필요하면 호출자가key()를 직접 남긴다(엔티티 id 는 빼고). 운영 절차는docs/runbooks/lock-acquisition-timeout.md(lock.acquisitionmetric,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<String>으로 읽는 framework-free 경계다. application use case는 MDC나 SLF4J를 직접 알지 않는다. - inbound web adapter가 sanitized
correlation_idMDC 슬롯을 구현 세부로 읽는다. - 값이 없거나 blank이면 event publisher는 생성한 event id를 correlation id로 재사용해 기존 self-correlation 동작을 유지한다.
UserPrincipalPseudonymizerPort
- raw 보안 principal id 를, 값이 로그/MDC 에 쓰이기 전에 안정적 가명 토큰으로 바꾸는 outbound 포트.
- null/blank 의미:
rawPrincipal이 null/blank 면 null 을 반환한다. 가명화할 게 없으니, 이 경우 caller 는user_principalMDC 키에 아무 값도 넣으면 안 된다. - 안정 토큰 계약: non-blank 입력에 대해 (1) 같은 입력 + 같은 salt 는 같은 salt epoch 안에서
항상 같은 출력을 낸다(안정), (2) raw principal 의 trivial 복원이 불가능하다(일방향 derivation
이지 인코딩·가역 변환이 아니다), (3)
user_principalMDC 와 로그 라인에 안전하다. - 알고리즘 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, fakeInMemoryOutboxAggregateSequences와 JPA 구현이 공유): aggregate마다 첫 번호부터 하나씩 커지고, 첫 쓰기 두 개가 겹쳐도 둘 다 성공하며, aggregate끼리 독립이다. 첫 번호는 구현마다 다르다(fake는 1). JPA 구현(JpaOutboxStore, V21outbox_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://<source>/<name>한 가지 표기)를 둔다. 예전에는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, fakeInMemorySecretSource(testFixtures).
지역 규칙에서 옮긴 표와 계약
이 절의 표와 계약은 지역 규칙 AGENTS.md에 있던 것을 2026-11-07에 옮겼다(지역 규칙은 200줄 이하). 규칙이 바뀌면 이 절과 AGENTS.md를 같은 변경에서 고친다.
계약 타입
| 타입 | 용도 |
|---|---|
usecase.UseCase<I, O> |
inbound 포트의 기반 타입. 구체 inbound 포트는 반드시 CommandUseCase나 QueryUseCase를 상속한다. |
usecase.CommandUseCase<C extends Command, R> |
쓰기 유스케이스의 inbound 포트. 구현은 반드시 @UseCaseCapability를 단다. |
usecase.QueryUseCase<Q extends Query, R> |
읽기 전용 유스케이스의 inbound 포트. 구현은 반드시 transactionMode = READ_ONLY와 repositoryAccess = READ_REPOSITORY를 선언한다. |
command.Command |
쓰기 의도의 표지. 도메인 값으로 만든 평범한 불변 타입이다. |
query.Query |
읽기 의도의 표지. 도메인 값으로 만든 평범한 불변 타입이다. |
transaction.TransactionPort |
합류할 수 있는 쓰기·읽기, 물리 루트에서만 하는 쓰기, 독립 쓰기 경계를 내놓는 outbound 포트. adapter:outbound:persistence-jpa의 SpringTransaction이 구현한다. |
secret.SecretSourcePort |
프레임워크 없는 outbound 비밀 해석 이음매. 배포가 app-bootstrap에서 backend를 고른다. 실제 환경 변수·클라우드·vault 리더는 outbound 어댑터 leaf에 둔다. |
transaction.NestedRootTransactionRejectedException |
inRootWrite가 실제로 열린 바깥 트랜잭션을 찾았을 때, action이나 provider 부작용 전에 바로 던지는 실패 신호. |
transaction.TransactionMode |
WRITE / READ_ONLY / REQUIRES_NEW. NESTED와 NEVER는 일부러 없다. |
transaction.Isolation |
READ_COMMITTED(고정 기본값) / REPEATABLE_READ / SERIALIZABLE. READ_UNCOMMITTED는 금지다(선언하지 않았다). vendor 기본값은 쓰지 않는다(엔진마다 기본값이 다르다 — PostgreSQL은 READ COMMITTED, MySQL InnoDB는 REPEATABLE READ). 더 엄격한 수준을 TransactionPort로 넘기는 일은 feature-application-port-usecase-contract와 함께 바꿀 planned 항목이다. 지금 호출 경로는 READ_COMMITTED로 고정한다. |
capability.UseCaseCapability |
모든 구체 유스케이스에 반드시 다는 애너테이션: transactionMode, idempotency, repositoryAccess, externalOutboundAllowed를 선언한다. |
capability.Idempotency |
IDEMPOTENT / KEYED / NOT_IDEMPOTENT. |
capability.RepositoryAccess |
NONE / READ_REPOSITORY / WRITE_REPOSITORY. |
messaging.contract.IntegrationEventContractContribution<P> |
닫힌 정확한 record payload 타입, 정해진 component 순서, 로컬 schema identity·hash, provider 중립 descriptor 기여. |
messaging.event.IntegrationEventDraft<P> |
로컬 인코딩 전의 타입 있는 semantic 이벤트. JSON·Kafka·영속 상태가 아니다. IntegrationEventDrafts로만 만든다(INTEGRATION_EVENT_DRAFTS_ARE_BUILT_BY_THE_SHARED_HELPER). |
messaging.event.IntegrationEventDrafts |
기능이 초안을 만드는 유일한 길: contract id·version·destination은 contract에서, correlation은 요청 값이 정규형이면 그 값(아니면 event id), 테넌트가 없는 기능은 SINGLE_TENANT_SCOPE. |
messaging.event.IntegrationIdentity |
event id, correlation·causation id, aggregate id의 유일한 문법과 길이 한계. 값은 isCanonical(value, bound)로 시험한다. 패턴을 복사하지 않는다. |
messaging.event.ValidatedIntegrationEvent |
안정된 semantic identity와 바뀌지 않는 정확한 인코딩 바이트·hash. 뒤의 durable append 경계로 넘길 준비가 된 값이다. |
messaging.event.IntegrationEventEncoderPort |
프레임워크 없는 로컬 경계(초안 → 검증된 이벤트). outbound 어댑터가 구현한다(템플릿은 adapter:outbound:support의 JsonIntegrationEventEncoder). |
outbox.OutboxAppendPort |
유일한 outbox append: ValidatedIntegrationEvent 하나를 호출자의 쓰기 트랜잭션 안에서 넣는다. |
tenant.TenantId |
테넌트 식별자와 그 유일한 문법([A-Za-z0-9][A-Za-z0-9_.-]{0,63}). web과 GraphQL 전송 문맥이 모두 이 값을 싣는다. 전송 계층이 검증된 인증 데이터로만 만든다. |
패키지 소유 (Package ownership)
이 절은 템플릿이 어떤 패키지를 가지는지와 업무 기능이 어디로 가는지의 정본이다.
docs/manual/03-placement.md가 이곳을 가리킨다.
- 업무 기능은
dev.caskeleton.application.<feature>다(그리고dev.caskeleton.domain.<feature>,...adapter.inbound.web.<feature>,...bootstrap.autoconfigure.<feature>). 루트마다 바로 아래에 기능 하나당 패키지 하나를 두고,command·usecase·port하위 패키지를 두지 않는다. <feature>는 아래 템플릿 패키지 이름 중 하나가 아니다. 같은 이름의 템플릿 패키지 옆에 둔 기능은 같은 패키지 트리에 들어가고, upstream 템플릿 갱신이 올 때마다 그 기능에 섞여 들어간다.- 템플릿 패키지는 기능 패키지를 import하지 않는다. 이름이 맞아도 업무 코드를 템플릿 패키지에 넣지 않는다.
- 두 루트 아래에서 여기 적히지 않은 것은 모두 기능이다. 파생 서비스는 이 목록을 고치지 않고 기능을 더한다. 템플릿은 자기 패키지를 더하거나, 이름을 바꾸거나, 지울 때 이 목록을 고친다.
패키지 (dev.caskeleton.application.*) |
소유 leaf | 담는 것 |
|---|---|---|
usecase, command, query |
application-core | inbound 포트 기반 타입과 command·query 표지 |
capability |
application-core | @UseCaseCapability와 그 enum |
transaction |
application-core | TransactionPort와 그 모드 |
security |
application-core | 인가 포트, @RequiresPermission, @SystemInvoked, @SystemCaller, ObjectAccessPolicy |
tenant |
application-core | TenantId |
observability |
application-core | CorrelationIdPort, UserPrincipalPseudonymizerPort |
secret |
application-core | SecretSourcePort, SecretReference |
messaging |
application-core | integration event semantic contract |
outbox |
application-core | 트랜잭션 outbox append와 relay |
idempotency |
application-core | 키 기반 멱등성 executor와 store 포트 |
operation |
application-core | durable(오래 걸리는) operation |
lease, lock |
application-core | 분산 lease·lock 포트 |
cache |
application-core | cache region 포트 |
realtime |
application-core | live event 재생 포트 |
notification |
application-notification | 알림 capability |
fileserver |
application-fileserver | 파일 서버 capability |
objectstorage |
application-objectstorage | 오브젝트 스토리지 capability(content.CallBudget은 그것이 싣는 호출 기한이다) |
패키지 (dev.caskeleton.domain.*) |
소유 leaf | 담는 것 |
|---|---|---|
identifier |
domain-core | ResourceId, IdFactory |
stereotype |
domain-core | @AggregateRoot, @DomainEvent, @ValueObject |
강제하는 곳:
scripts/new-feature.sh는 다섯 루트 중 어디든, 어느 leaf든 이미 패키지로 있는 기능 이름을 거절한다. 템플릿 패키지도 모두 여기 걸린다.NamingConventionTest.FEATURE_PACKAGES_DO_NOT_REUSE_TEMPLATE_PACKAGE_NAMES: 두 루트 아래의 기능 패키지는 이 표의 이름을 쓰지 않는다. 기능마다 domain 패키지가 있으므로operation이라는 기능은dev.caskeleton.domain.operation에서 걸린다.NamingConventionTest.TEMPLATE_PACKAGES_DO_NOT_DEPEND_ON_FEATURE_PACKAGES: 템플릿 패키지 안에 쓴 기능 클래스는 템플릿 이름을 지니지만 자기 도메인을 import한다. 실패하는 것은 그 import다.- 이 표가 정본이다. 규칙이 읽는 기계용 사본은
TemplatePackageOwnership이다(app-bootstrapsrc/test에 있어서 architecture suite와 document-contract lane이 모두 본다).TemplatePackageOwnershipDocumentTest(document-contract lane,mainCheck)는 표와 그 클래스의 패키지 이름이나 소유 leaf가 다르거나, 표에 적힌 패키지가 표가 말한 leaf에 없으면 실패한다.TemplatePackageOwnershipRuleTest(architectureTest)는 적힌 이름이 운영 클래스 어디에도 없으면 실패한다. 새 템플릿 패키지는 같은 변경에서 둘 모두에 들어간다. - 못 잡는 것: 아무도 적지 않은 새 템플릿 패키지. 기능은 같은 leaf에 생성되므로
(
scripts/new-feature.sh) 적히지 않은 패키지는 기능과 구별되지 않는다. 적는 것까지가 패키지를 더하는 일이다. - 버린 대안: 적힌 최상위 패키지만 허용하기(파생 기능마다 템플릿 목록을 고쳐야 한다 — 기능마다
병합 충돌이 난다), 플랫폼 패키지용
application-platformleaf를 따로 두기(2026-11-01 성숙도 리뷰에서 따졌다: 경계는 더 분명하지만, 이름 규칙에 필요한 것보다 registry edge가 많아진다).
정해진 유스케이스 모양 (Canonical use case shape)
@RequiresPermission("user:register")
@UseCaseCapability(
transactionMode = TransactionMode.WRITE,
idempotency = Idempotency.KEYED,
repositoryAccess = RepositoryAccess.WRITE_REPOSITORY)
public class RegisterUserUseCase implements CommandUseCase<RegisterUserCommand, User> {
private final UserRepository users;
private final TransactionPort tx;
public RegisterUserUseCase(UserRepository users, TransactionPort tx) {
this.users = users;
this.tx = tx;
}
@Override
public User handle(RegisterUserCommand cmd) {
return tx.inWrite(() -> {
// ... domain coordination
});
}
}
이 클래스는 평범한 Java다. 조립 루트가 포트와 설정 값을 넣어 만든다. application-core는 DI
프레임워크에 스스로 등록하지 않는다. 클래스는 final이 아니다: 상태를 바꾸는 유스케이스는
@RequiresPermission을 선언하고, web 어댑터는 CGLIB proxy로 그것을 강제하는데, CGLIB는 final
클래스를 상속하지 못한다(RequiresPermissionProxyabilityTest). 같은 이유로 bean으로 등록한다.
new로 만든 유스케이스는 검사를 받지 않는다. 시스템만 부르는 유스케이스(스케줄러, relay, 메시지
소비자)는 권한 대신 @SystemInvoked(reason = ...)를 달고 bean이 아니다. 권한 검사가 없는 쓰기라서
사용자 요청이 닿으면 안 되기 때문이다. 그 시스템 호출자가 유스케이스를 만든다: 스케줄러는 조립
모듈, 메시지 핸들러는 ..adapter.inbound.messaging.. 안의 @SystemCaller(reason = ...), 예약
작업은 서비스 자신의 ..adapter.inbound.scheduler.. 패키지 안의 @SystemCaller다. 이 셋과 각각의
위치는 docs/manual/07-authorization.md 「시스템이 부르는 쓰기」가 정본 목록이다. 모두 강제된다:
@SystemInvoked bean은 기동에 실패한다. @SystemCaller가 아닌 inbound 어댑터가 그 유스케이스에
의존하면 ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES가 실패한다.
SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS는 그 표지(그리고 표지가 붙은 클래스 안에 든
클래스)를 사용자 전송 계층에 두지 못하게 한다. USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS는 사용자
전송 계층이 시스템 호출자를 부르지 못하게 한다(그 클래스로든, 그것이 구현한 프로젝트 인터페이스로든).
SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES는 시스템 호출자가 Runnable이나 프로젝트 밖의 다른
타입이 되지 못하게 한다. 그런 타입은 어떤 의존 규칙도 따라가지 못한다. 타입 이름이 드러나지 않는
경로(이름으로 찾는 bean, 설정이 넘겨주는 함수)는 보지 못한다. 매뉴얼 07장이 그 경로와 그것을 막는
곳을 적는다. @RequiresPermission bean이 있는데 강제할 advisor가 없는 조립도 기동에 실패한다
(composition:service-runtime의 PermissionEnforcementGuard, 두 검사 모두).
멱등성 (KEYED) — feature-rate-limit-idempotency-contract
@UseCaseCapability(idempotency = Idempotency.KEYED)는 지원한다. KEYED 유스케이스는 자기 일을
dev.caskeleton.application.idempotency.IdempotencyExecutor로 감싼다. 소유자를 안전하게 지키는
유일한 세대다. V1 IdempotencyScope/tryBegin API는 없어졌다.
- 범위(scope): 호출자가
IdempotencyScopeDigest를 넘긴다. principal + client key + operation code의 버전 있는 HMAC이고, executor가 받기 전에 계산한다. 원본Idempotency-Key는 이 계층에도 store에도 닿지 않는다. - store:
IdempotencyStorePort.app.capabilities.idempotency.provider로 고른 provider 정확히 하나가 내놓는다(redis→cache-redis,postgresql→persistence-jpa, 기본값disabled). 운영에서 메모리 저장소는 금지다. - executor:
composition:idempotency의IdempotencyAutoConfiguration이IdempotencySettings로 한 번 만든다(처리 lease 30s, 재생 TTLAPP_IDEMPOTENCY_TTL24h ≤72h이고 lease보다 짧지 않다, 실패 보존 24h이고 재생 TTL보다 짧지 않다). 유스케이스나 서비스 자신의 설정에서 만들지 않는다. - action은
IdempotentAction.Outcome(Success/RetryableNoEffect/EffectUnknown)을 돌려준다. 던진 예외는 효과를 모름(effect-unknown)으로 센다. 처리 중이면 409IDEMPOTENT_IN_FLIGHT, fingerprint(SHA-256)가 다르면 422IDEMPOTENT_REQUEST_MISMATCH다.IdempotencyUnavailableException과IdempotencyRecoveryRequiredException은 store가 결과를 증명하지 못했다는 뜻이니 무턱대고 다시 시도하지 않는다. - 모든 store는 처리 lease가 끝난 실행에
RecoveryRequired로 답하고 그 실행을 넘겨받지 않는다. 넘겨받는 것은 시작하지 않은 claim이나 다시 시도할 수 있는 실패뿐이다. 이 답은 레코드를 가진 쪽에게 남긴다: 가진 쪽이 늦게 보낸 첫complete/markFailed는 기록한다. lease가 끝난 것은 갱신하지 않고, lease가 끝난 claim은 시작하지 않는다. 둘 다NOT_OWNER가 아니라LEASE_EXPIRED로 답하고, executor는 거절된 시작을 「적용 안 됨」으로 바꾼다(소유자 결정 2026-11-04). 레코드는 lease에 재생 TTL을 더한 만큼 산다.IdempotencyStoreContract가 Redis와 PostgreSQL을 실제 서버에서 둘 모두에 맞춘다. 메모리 fake는 시간을 모델링하지 않으니 계약 중 시간이 없는 경우만 돈다. - 모든 전이는 그 레코드를 claim한 operation을 이름으로 댄다(
IdempotencyOwner.claimOperationId()). 다른 operation이면 모든 store에서OPERATION_CONFLICT이고 아무것도 바꾸지 않는다. owner token을 다른 operation으로 가져온 조회도 같다(소유자 결정 2026-11-06). - 이미 적용된 전이는 그것을 적용한 handle에게만 「already …」로 확인해 준다. 그 handle은 그 전이로
옮겨 간, 한 revision 뒤의 레코드다. 다른 handle은 모두
NOT_OWNER다. 넘겨받기 전의 같은 시도의 handle도, 갱신을 적용한 handle로 하는 시작도 그렇다. 놓아준 handle로 하는 시작은 store가 놓아준 레코드를 남기느냐에 따라ABSENT나NOT_OWNER다(소유자 결정 2026-11-06,IdempotencyStoreContract). - 적용한 handle이 다른 disposition으로
markFailed를 다시 보내면OPERATION_CONFLICT이고 기록된 실패가 남는다. retention만 다르면ALREADY_MARKED_SAME_OPERATION이고 처음 retention이 남는다 — retention은 완료의 재생 TTL처럼 비교하지 않는다(소유자 결정 2026-11-07).
예전 ArchUnit 동결 규칙 inbound_port_implementations_do_not_declare_keyed_idempotency와 그 fixture는
이 브랜치가 병합될 때 지웠다.