Files
clean-architecture-backend-…/src/application-core

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-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/<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).

  1. 새 version 추가: v<N+1>.schema.json, 새 payload record, 새 IntegrationEventContractContribution. 옛 version의 contribution은 그대로 둔다. encoder catalog는 (contractId, payloadVersion)마다 하나라 두 version이 함께 등록된다.
  2. 소비자 배포: 모든 소비자가 v과 v<N+1>을 둘 다 읽게 한다. outbox에 이미 쌓인 v 행은 저장된 바이트 그대로 나가므로, 생산자를 바꾼 뒤에도 한동안 두 version이 함께 도착한다.
  3. 생산자 전환: draft를 v<N+1> contract로 만든다. 이 커밋에서 manifest에 v<N+1> 줄을 더한다.
  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 강제).
  • 제네릭 입출력 타입(<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 가 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<T> 제약과 동일하다. 그래서 호출자는 도메인 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<String>으로 읽는 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://<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, fake InMemorySecretSource(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-bootstrap src/test에 있어서 architecture suite와 document-contract lane이 모두 본다). TemplatePackageOwnershipDocumentTest(document-contract lane, mainCheck)는 표와 그 클래스의 패키지 이름이나 소유 leaf가 다르거나, 표에 적힌 패키지가 표가 말한 leaf에 없으면 실패한다. TemplatePackageOwnershipRuleTest(architectureTest)는 적힌 이름이 운영 클래스 어디에도 없으면 실패한다. 새 템플릿 패키지는 같은 변경에서 둘 모두에 들어간다.
  • 못 잡는 것: 아무도 적지 않은 새 템플릿 패키지. 기능은 같은 leaf에 생성되므로 (scripts/new-feature.sh) 적히지 않은 패키지는 기능과 구별되지 않는다. 적는 것까지가 패키지를 더하는 일이다.
  • 버린 대안: 적힌 최상위 패키지만 허용하기(파생 기능마다 템플릿 목록을 고쳐야 한다 — 기능마다 병합 충돌이 난다), 플랫폼 패키지용 application-platform leaf를 따로 두기(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, 재생 TTL APP_IDEMPOTENCY_TTL 24h ≤72h이고 lease보다 짧지 않다, 실패 보존 24h이고 재생 TTL보다 짧지 않다). 유스케이스나 서비스 자신의 설정에서 만들지 않는다.
  • action은 IdempotentAction.Outcome(Success / RetryableNoEffect / EffectUnknown)을 돌려준다. 던진 예외는 효과를 모름(effect-unknown)으로 센다. 처리 중이면 409 IDEMPOTENT_IN_FLIGHT, fingerprint(SHA-256)가 다르면 422 IDEMPOTENT_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는 이 브랜치가 병합될 때 지웠다.