Files
clean-architecture-backend-…/src/application-core/README.md
T
DongHyeonka ab5982e955 refactor(repo)!: 샘플 모듈과 그 참조를 지운다
문제: src/sample-portfolio(311파일)와 src/Dockerfile.sample이 빌드 8곳,
registry, PR job, spotbugs 제외, 매뉴얼·leaf 문서 수십 곳에 얽혀 있다.
매뉴얼과 생성 명령이 예시를 맡게 된 뒤로 샘플은 유지 비용만 남았고,
문서 일부는 이미 없는 태스크(sampleOffTest)와 ArchUnit 규칙을 가리킨다.

고른 방법: 소유자 결정(2026-11-07)대로 샘플을 폴더째 지우고 역할은
옮기지 않는다. 샘플을 가리키던 것도 같은 변경에서 지운다.
- 빌드: registry 행, 루트 build.gradle의 샘플 태스크·의존·단계
  (sampleWebContractCheck, :sample-portfolio:*, strict lane 단계),
  app-bootstrap architectureTestRuntimeOnly, spotbugs 제외 3곳
- CI: ci-quality-gates.yml의 sample-portfolio job과 release-gate 칸
- 테스트: SampleRuntimeDefaultsContractTest, Dockerfile.sample 비교 테스트,
  ArchUnit 규칙의 죽은 sample 패키지 제외. build-logic 테스트와
  application-core 테스트의 가짜 이름은 example-app으로 바꾼다
- 문서: 매뉴얼 예시를 실제 코드(durable operation, identifier,
  ErrorCodeRegistryMappingTest)로 바꾸고, 템플릿에 예가 없는 기법
  (유일 제약 → 같은 409)은 규칙과 확인 방법만 적는다. 결정 색인의
  샘플 전용 행은 "샘플과 함께 사라짐"으로 표시한다
버린 대안: 설계서 권장안(OpenAPI 스냅숏·웹 계약을 옮긴 뒤 삭제)은
소유자가 고르지 않았다.

위험·한계:
- 샘플 안에만 있던 검사(OpenAPI 스냅숏, Date 헤더, 가상 스레드 MDC
  전파, 요청당 SQL 수 단언)가 함께 사라진다. 소유자가 남기라 하면
  총괄이 따로 맡긴다.
- APP_CACHE_REDIS_ENABLED는 샘플이 읽지 않는 키라(설계서 가정과 다름)
  지우지 않고 src/README.md 문장만 고쳤다. 제거 기한 2026-11-30은 그대로.
- docs/capability-status.md 「제거된 코드」 표와 docs/work/evidence.md의
  샘플 경로는 이력이라 두었다.

검증(desktop, 트리 0525e14e, ~/t1-layout-logs/):
- ./gradlew :ci --warning-mode=fail rc=0 (502 executed, 83 from cache)
- :verifyStrictLaneStages --dry-run rc=0
- :app-bootstrap:documentContractTest rc=0
- -p build-logic check rc=0
- :verifyDependencyLocks rc=0
- python3 scripts/check-work-docs.py, 상대 링크 검사 rc=0

Refs: design-docs repo-structure/README.md 3.1, repo-structure/01-backend-layout.md 6.2
BREAKING CHANGE: src/sample-portfolio, src/Dockerfile.sample, 샘플 태스크와 job이 없어진다. 샘플을 고쳐 쓰던 파생 서비스는 병합 때 수정 대 삭제 충돌이 난다. docs/upgrade/2026-11-maturity-review.md B-49.
2026-11-07 12:21:03 +09:00

52 KiB
Raw Blame History

application-core — 설계 결정 참조

애플리케이션 유스케이스 계층. 패키지 루트: dev.caskeleton.application.

허용/금지 의존, 유스케이스 형태, 트랜잭션 모드, 명명 규칙 같은 모듈 규칙은 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/<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).