chore: initialize from backend template 0a6dd0e

src/shared-contract/README.md

@@ -0,0 +1,522 @@
+# shared-contract — 설계 결정 참조
+
+스켈레톤 전역 운영 계약(operational contract) 모듈. 패키지 루트: `dev.caskeleton.shared`.
+
+모듈 책임·허용/금지 의존(Java 표준 라이브러리 only)·테스트 명령 같은 **모듈 규칙**은
+[CLAUDE.md](CLAUDE.md) 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를
+모아둔 참조용 기록이다 — 코드를 읽다 "왜 이렇게 했나"가 궁금할 때 본다. 아래 설명은 별도
+추적 ID를 몰라도 읽히도록 결정의 배경과 트레이드오프를 문장으로 풀어 둔다.
+
+이 모듈은 한 가지 규칙을 끝까지 지킨다: **Java 표준 라이브러리만 쓴다.** Spring·Jackson·JPA·
+Micrometer·OTel 같은 프레임워크 타입을 import 하지 않는다. 그래서 모든 계층(application·web·
+persistence·outbound)이 프레임워크 충돌 없이 이 타입들을 공유할 수 있고, HTTP status 같은
+전송 개념도 프레임워크 타입이 아니라 평범한 `int` 로 표현한다(매핑은 web 어댑터가 한다).
+
+`health/RedisHealthSnapshotProvider`도 같은 원칙을 따른다. Redis adapter는 native client나
+예외를 노출하지 않고 bounded role/capability 상태만 제공하며, bootstrap이 이를 Actuator
+health로 변환한다.
+
+---
+
+## ratelimit — edge enforcement 계약
+
+`EdgeRateLimitPort`는 inbound와 Redis adapter 사이의 provider-neutral edge enforcement
+경계다. Business quota나 entitlement policy를 담는 application use case가 아니며, 이미
+pseudonymized된 subject digest와 bounded policy ID/cost/deadline만 받는다.
+
+`RateLimitPolicy`는 fixed window, sliding-window counter, token bucket 중 하나의 exact parameter
+subtype을 고정하고 Lua의 `2^53-1` 안전 정수, 1일 window/refill/cleanup, 1시간 clock regression,
+`FAIL_CLOSED`만 허용한다. 결과는 evaluated, known pre-send unavailable, post-dispatch
+indeterminate, schema/program/reply incompatible로 분리하므로 adapter가 장애를 allow나 평범한
+deny로 숨길 수 없다. 이 패키지는 Java 표준 라이브러리만 사용하며 Redis key, command, Lua,
+Spring/Lettuce 타입을 노출하지 않는다.
+
+---
+
+## messaging — generic envelope schema resource
+
+- `contracts/messaging/envelope/v1.schema.json` 은 비즈니스 필드를 모르는 공통 envelope v1의
+  저장소 소유 Draft 2020-12 리소스다. root와 aggregate metadata는 닫혀 있고, `payload`는 object
+  크기만 제한한다. 실제 payload 필드와 닫힘 정책은 feature owner의 별도 schema가 소유한다.
+- `.schema.sha256`은 schema 파일의 exact bytes SHA-256이다. 같은 version의 schema bytes를 바꾸면
+  digest도 의도적으로 갱신하고 compatibility 검토를 다시 해야 한다.
+- 이 단계의 테스트는 UTF-8, 정본 구조, digest, remote `$ref` 금지만 JDK로 검사한다. Task 6의
+  실제 Draft 2020-12 validator가 붙기 전까지 validator compatibility가 증명된 것은 아니다.
+- classpath resource가 존재한다는 사실은 runtime discovery나 자동 등록을 의미하지 않는다.
+  contract catalog와 encoder가 명시적으로 조립되기 전에는 어떤 publisher도 이 리소스를 읽지 않는다.
+
+---
+
+## error — 에러 코드 계약
+
+### ApiErrorCode (인터페이스)
+- **클라이언트에 노출되는, 안정적이고 기계가 읽을 수 있는 에러 코드 계약.** 스켈레톤 공통 코드는
+  `OperationalError` 에 있고, 포크한 프로젝트는 이 인터페이스를 구현해(보통 enum) 자기 도메인 코드를
+  더한다.
+- **`httpStatus()` 가 프레임워크 타입이 아니라 평범한 `int` 인 이유:** 이 모듈을 프레임워크 중립으로
+  유지하기 위해서다(stdlib-only 규칙). 실제 전송 status 타입으로의 매핑은 web 어댑터가 한다.
+- **`retryable` 의 의미:** `true` 면 같은 입력이 나중에 성공할 수 있다는 뜻(일시적 인프라 장애 /
+  rate limit). `false` 면 입력 자체를 바꿔야 한다.
+
+### Category (enum)
+- **운영 에러 분류 10-value SSOT enum.** 응답에 `error.category` 로 노출되어, 클라이언트가 모든
+  코드를 일일이 열거하지 않고도 굵직하게 분기할 수 있게 해 준다.
+- **분류(identity)만 담는다.** 코드별 HTTP status·`retryable` 은 `ApiErrorCode` 구현과
+  `error-codes.yaml` 에 있지 여기 있지 않다 — `retryable` 은 **코드별** 값이며 category 에서
+  계산하지 않는다.
+
+### OperationalError (enum)
+스켈레톤 공통 운영/전송/보안 에러 코드의 집합이다. `USER_NOT_FOUND` 같은 **도메인 전용 코드는
+여기 두지 않고** 그 코드를 쓰는 모듈에 둔다.
+
+- **출처/SSOT:** 모든 코드의 status/category/`retryable` 값은 레지스트리
+  `docs/registries/error-codes.yaml` 를 그대로 미러링한다. 코드 추가/변경은 레지스트리가 먼저다.
+
+**전송 형태(transport-shape) 코드의 분류 — 프로젝트 선택**
+- `METHOD_NOT_ALLOWED`(405), `UNSUPPORTED_MEDIA_TYPE`(415), `NOT_ACCEPTABLE`(406),
+  `PAYLOAD_TOO_LARGE`(413), `URI_TOO_LONG`(414) 는 "요청 형태가 잘못됐다" 류의 전송 계층 에러다.
+  10-value enum 에는 이들을 위한 전용 category 가 없어, 가장 가까운 "클라이언트 요청 형태" 버킷인
+  `VALIDATION` 에 넣었다. 이를 강제하는 외부 표준은 없다(프로젝트 결정).
+- `PRECONDITION_FAILED`(412) 는 `If-Match` 검증 실패, 즉 낙관적 동시성 충돌의 HTTP 표현이다.
+  그래서 persistence 계층의 `DB_SERIALIZATION_FAILURE`/`DB_DEADLOCK` 와 같은 식구인 `CONFLICT`
+  로 분류한다.
+
+**보안 코드 — 굵은(coarse) 폴백 vs 세분화(fine-grained)**
+- `UNAUTHENTICATED`/`INVALID_TOKEN`/`FORBIDDEN` 은 굵은 폴백 코드다. 시큐리티 필터를 거치지 않는
+  경로(예: 컨트롤러에서 직접 던진 `AccessDeniedException`)를 위해 남겨 둔다.
+- `AUTH_*` 세분화 코드는 보안 운영 베이스라인의 AuthN/AuthZ 결정 매트릭스 구현이다. 굵은 3-way
+  매핑 대신 레지스트리가 선언한 세분화 코드를 쓰도록 정리한 것으로, 런타임에 리소스 서버의
+  AuthenticationEntryPoint / AccessDeniedHandler 가 방출한다.
+- `AUTH_KID_UNKNOWN` 은 `retryable=true`: 키 회전(key rotation) 중 알 수 없는 JWKS `kid` 는 키
+  세트가 새로고침되면 저절로 풀린다(레지스트리에서 `false→true` 로 바뀐 이력 있음, Retry-After 5s).
+- `AUTH_JWKS_UNAVAILABLE` 은 JWKS 엔드포인트 장애 = 일시적 의존성 실패 → 503, retryable.
+- `INTERNAL_AUTH_MISCONFIGURATION` 은 `retryable=false`: 보호돼야 할 엔드포인트가 public 으로
+  새어 나가는 것은 **배포 시점 설정 버그**이지 일시적 장애가 아니다. 같은 요청을 다시 보내도 (재배포
+  전까지) 절대 풀리지 않으므로, "INTERNAL 은 retryable" 이라는 일반 휴리스틱에서 의도적으로 벗어나
+  false 로 둔다.
+
+**rate-limit / idempotency**
+- `RATE_LIMIT_EXCEEDED` 는 `retryable=true` 이며 Retry-After 헤더와 짝을 이룬다.
+- `IDEMPOTENT_IN_FLIGHT`/`IDEMPOTENT_REQUEST_MISMATCH` 는 결정적인 클라이언트 결과(다시
+  poll 하거나 본문을 고쳐야 함)라 `retryable=false`.
+
+**ADAPTER_DISABLED — 어댑터 런타임 fail-fast**
+- 비활성(`app.<domain>.<adapter>.enabled=false`, 기본값) 상태인 선택적 어댑터(Kafka/Redis/Slack/
+  Google Email)의 use-case 경로가 호출됐을 때 던지는 런타임 fail-fast 코드다(`AdapterDisabledException`
+  매핑 결과).
+- 기동 시점의 `REQUIRED_ADAPTER_DISABLED`(owner: 마이그레이션/기동 계약, exit code 72)와 **의도적으로
+  다른 코드**다. 런타임 호출과 기동 검증은 서로 다른 lifecycle 이라, 코드를 재사용하면 두 의미가
+  뭉개진다. `INTERNAL_AUTH_MISCONFIGURATION` 과 마찬가지로 결정적 설정/프로그래밍 버그이지 일시적
+  장애가 아니므로 `retryable=false` — 여전히 비활성인 어댑터를 다시 호출해도 풀리지 않는다.
+
+**persistence — SQLState → 코드 분류**
+- `DB_*` 코드는 adapter-persistence 의 `PersistenceExceptionTranslator` 가 raw Spring
+  `DataAccessException`/SQLState 를 벗겨 낸 뒤 방출하는 프레임워크 중립 코드다. JPA 예외 자체는 web
+  계층까지 절대 도달하지 않는다.
+- **`PERSISTENCE` 라는 category 는 없다.** 10-value Category 가 SSOT 이므로 DB 실패도 기존 분류에
+  녹여 넣는다: 연결 끊김/타임아웃 → `TRANSIENT_DEPENDENCY`, 직렬화/데드락/유니크 → `CONFLICT`,
+  null/FK/check → `DATA_INTEGRITY`.
+
+| 코드 | SQLState | category | HTTP | retryable | 메모 |
+|---|---|---|---|---|---|
+| `DB_UNAVAILABLE` | 08* | TRANSIENT_DEPENDENCY | 503 | ✅ | 연결 실패 |
+| `DB_SERIALIZATION_FAILURE` | 40001 | CONFLICT | 409 | ✅ | |
+| `DB_DEADLOCK` | 40P01 | CONFLICT | 409 | ✅ | backoff 후 재시도 |
+| `DB_NULL_VIOLATION` | 23502 | DATA_INTEGRITY | 409 | ❌ | |
+| `DB_FK_VIOLATION` | 23503 | DATA_INTEGRITY | 409 | ❌ | |
+| `DB_UNIQUE_VIOLATION` | 23505 | CONFLICT | 409 | ❌ | 비즈니스 매핑 |
+| `DB_CHECK_VIOLATION` | 23514 | DATA_INTEGRITY | 409 | ❌ | |
+| `DB_IDLE_IN_TX_TIMEOUT` | 25P03 | TRANSIENT_DEPENDENCY | 503 | ✅ | |
+| `DB_QUERY_CANCELED` | 57014 | TRANSIENT_DEPENDENCY | 503 | ❌ | |
+
+**outbound HTTP — upstream 실패 분류**
+- `DEPENDENCY_*` 코드는 adapter-outbound 의 `OutboundHttpErrorMapper` 가 upstream HTTP/네트워크
+  실패를 분류한 뒤 방출한다. raw upstream 응답은 web 계층까지 도달하지 않는다.
+- **알려진 미해결 엣지:** 408(Request Timeout)·429(Too Many Requests)는 의미상 재시도 가능하지만,
+  레지스트리 SSOT 는 **모든 upstream 4xx 를 `PERMANENT_DEPENDENCY`(`retryable=false`)로 분류**한다.
+  이는 의도적 결정이며, 바꾸려면 레지스트리 갱신과 어댑터 변경을 함께 해야 한다.
+
+| 코드 | category | HTTP | retryable | 트리거 |
+|---|---|---|---|---|
+| `DEPENDENCY_TIMEOUT` | TRANSIENT_DEPENDENCY | 504 | ✅ | upstream read/global-call timeout |
+| `DEPENDENCY_CONNECT_FAILED` | TRANSIENT_DEPENDENCY | 503 | ✅ | TCP connect 거부/타임아웃 |
+| `DEPENDENCY_DNS_FAILED` | TRANSIENT_DEPENDENCY | 503 | ✅ | 이름 해석 실패 |
+| `DEPENDENCY_4XX_CLIENT` | PERMANENT_DEPENDENCY | 502 | ❌ | upstream 이 요청 거부(4xx) |
+| `DEPENDENCY_5XX_SERVER` | TRANSIENT_DEPENDENCY | 502 | ✅ | upstream 서버 에러(5xx) |
+| `DEPENDENCY_CIRCUIT_OPEN` | TRANSIENT_DEPENDENCY | 503 | ✅ | 서킷 브레이커 open / shutdown 거부 fail-fast |
+
+**transactional outbox**
+- outbox 상태 머신: `PENDING → IN_FLIGHT → PUBLISHED | FAILED | DEAD`.
+- `OUTBOX_PUBLISH_FAILED`: 일시적 발행 실패 → row 가 FAILED 로 가고 backoff 재시도. 메시지
+  브로커/relay 가 일시적 의존성이라 `TRANSIENT_DEPENDENCY`, `retryable=true`(retry_after 30s).
+- `OUTBOX_DEAD_LETTER`: 최대 재시도 소진 → row 가 DEAD(DLQ)로. 수동 개입이 필요하고 같은 발행을
+  다시 해도 풀리지 않으므로 `retryable=false`(`INTERNAL_AUTH_MISCONFIGURATION`/`ADAPTER_DISABLED`
+  와 같은 논리: 결정적 종료 상태이지 일시적 장애가 아님).
+
+**background job / async executor**
+- 이 계약이 소유하는 재시도/DLQ 어휘이며 outbox/outbound 계약이 가져다 쓴다.
+- `JOB_EXECUTOR_REJECTED`: bounded executor 포화(AbortPolicy 거부). 스레드 풀+큐가 다 차서 생긴
+  일시적 용량 부족으로, 부하가 빠지면 풀린다 → `TRANSIENT_DEPENDENCY`/503, retryable(Retry-After 5s).
+- `JOB_TIMEOUT`: 실행 중 job 이 예산(19s graceful-shutdown interrupt 포함)을 초과 → 일시적,
+  다음 cycle 에 재시도 → `TRANSIENT_DEPENDENCY`/500, retryable.
+- `JOB_DEAD_LETTER`: 재시도 소진 → DLQ 종료 상태. 수동 개입 필요, 같은 job 을 다시 해도 풀리지
+  않음 → `INTERNAL`/500, `retryable=false`(`OUTBOX_DEAD_LETTER` 와 같은 논리).
+
+**distributed lock**
+- `LOCK_ACQUISITION_TIMEOUT`: 분산 락 provider(`JdbcLockRegistry`/in-process `LockRegistry`)가
+  제한된 `waitTime` 안에 락을 얻지 못했을 때 방출(무한 블로킹 없이 try-lock + 유한 waitTime, D5).
+- 일반 500 이 아니라 `CONFLICT`+`retryable=true` 인 이유: 락 경합은 일시적이다 — 보유자가
+  임계 구역을 떠나거나 lease TTL 이 만료되면 같은 요청이 락을 얻는다. `DB_DEADLOCK`/
+  `DB_SERIALIZATION_FAILURE` 와 같은 재시도 가능 `CONFLICT`(409) 식구다. 이건 효율용 락 타임아웃
+  (D6)이며, 정합성 자체는 이 코드가 아니라 DB 제약이 지킨다.
+
+**기타 운영 코드**
+- `JVM_OOM`: JVM OutOfMemoryError 분류. JVM 이 죽는
+  종료성 장애(`ExitOnOutOfMemoryError`, exit 137)라 재시도해도 안 풀림 → `retryable=false`
+  (`INTERNAL`/500). 로그의 `error.code=JVM_OOM` 유무로 kubelet OOMKill 과 구별한다.
+- `ACTUATOR_FORBIDDEN`: 운영 환경에서 위험한
+  actuator 엔드포인트(env/configprops/heapdump/threaddump/shutdown) 접근 → 403(`AUTHZ`/403/false,
+  로그 WARN).
+
+### MappingException
+- **경계 mapper 의 sentinel.** request→command/query 변환, response shaping, outbound ACL 등 어떤
+  경계 mapper 에서든 payload 가 구조적으로는 멀쩡한데 의미상 매핑이 불가능할 때 던진다.
+- web 어댑터의 기본 `GlobalExceptionHandler` 가 이 타입을 잡아 `MAPPING_FAILED`(400)로 보낸다 —
+  `INTERNAL_ERROR` 로 새어 나가지 않게 하려는 것.
+- **`shared.error` 에 사는 이유:** 어떤 모듈(web/persistence/outbound ACL mapper)이든 cross-adapter
+  의존 없이 던질 수 있게 하기 위해서다.
+
+### AdapterDisabledException
+- **integration-adapter-templates Layer 3 의 런타임 fail-fast sentinel.** 비활성 상태인 선택적
+  어댑터(Kafka/Redis/Slack/Google Email)의 use-case 경로가 호출되면 던진다.
+- **정상 경로에선 도달할 수 없다:** Layer 1(`@ConditionalOnProperty` bean-gating)이 비활성일 때 실제
+  어댑터 bean 을 아예 등록하지 않으므로 호출될 수 없다. 이 예외는 Layer 1/Layer 2 를 우회한 호출에
+  대한 **최후의 방어선**이다 — 조용한 no-op 이나 타임아웃 대기 없이 즉시 실패해서, 비활성 의존성이
+  상태를 오염시키거나 멈추게 두지 않고 바로 표면화한다.
+- web 어댑터가 이 타입을 `ADAPTER_DISABLED`(500, retryable=false)로 매핑한다 — 기동 시점의
+  `REQUIRED_ADAPTER_DISABLED` 와는 절대 섞지 않는 별개 런타임 코드. `shared.error` 거주 이유는
+  `MappingException` 과 동일하다.
+
+### DependencyFailureException
+- **분류된 outbound HTTP(의존성) 실패의 프레임워크 중립 운반체**. adapter-outbound 의 `OutboundHttpErrorMapper` 가 raw 네트워크/HTTP 예외를 잡아 upstream
+  실패 매트릭스로 분류한 뒤, 안정적 `ApiErrorCode`(`DEPENDENCY_*`)와 upstream 의존성 이름을 담아
+  이 타입으로 감싸 다시 던진다.
+- **`diagnosticMessage` 는 서버 로그 전용이며 upstream raw 응답 본문을 절대 담아선 안 된다.** 테스트
+  계약: "upstream raw error body 가 response/log 에 노출되면 실패". web 어댑터는 `errorCode()` +
+  고정된 client-safe 메시지로 매핑하므로 upstream status/body/header/raw 예외 클래스가 API
+  클라이언트에 닿지 않는다.
+- **stdlib-only 유지:** `ApiErrorCode` 는 프레임워크 중립이고 cause 는 평범한 `Throwable` 이라
+  no-Spring 규칙을 지킨다. `adapter-outbound` 가 던지고 `adapter-web` 이 잡되 금지된 cross-adapter
+  의존을 만들지 않도록 `shared.error` 에 둔다.
+
+### PersistenceFailureException
+- **분류된 persistence 실패의 프레임워크 중립 운반체**.
+  adapter-persistence 의 `PersistenceExceptionTranslator` 가 raw Spring `DataAccessException` 을
+  잡아 SQLState 를 9행 매트릭스로 분류한 뒤, 안정적 `ApiErrorCode`(`DB_*`)만 담아 이 타입으로
+  감싸 다시 던진다.
+- raw `DataAccessException` 은 **서버 로그용 cause 로만** 보존한다. web 어댑터가 `errorCode()` +
+  고정 client-safe 메시지로 매핑하므로 SQLState·제약/인덱스 이름·SQL 조각·JPA/Spring 예외 클래스가
+  클라이언트에 닿지 않는다(D1, business-rule-validation C7/D9).
+- `shared.error` 거주·stdlib-only 이유는 `DependencyFailureException` 과 동일하다.
+
+---
+
+## response — 응답 envelope 계약
+
+### Envelope
+- **스켈레톤 공통 단일 아이템 응답 envelope.** 성공과 실패가 한 모양을 공유한다: 최상위 `success`
+  플래그, `data`(성공) 또는 `error`(실패) 필드, 그리고 request/trace/correlation id 를 담는 `meta`.
+  `data`/`error` 중 정확히 하나만 non-null 이다.
+- **RFC 7807 ProblemDetail 을 대체한다**(boundary D5/D6). `meta` 객체는 예전의 평평한 `traceId`
+  필드를 대체하며, success/error 대칭은 유지하면서 요청 진단 정보를 더 풍부하게 담는다.
+
+### ApiError
+- **`success=false` 일 때 Envelope 안에 들어가는 에러 payload.**
+- D5 가 RFC 7807 ProblemDetail 을 거부하고, D10 이 `category`(10-value Category enum)를 **1급
+  필드**로 추가했다 — 클라이언트가 모든 코드를 열거하지 않고도 굵게 분기할 수 있게.
+- 필드 의미: `code`(기계가독 식별자, 클라이언트는 `message` 가 아니라 이걸로 분기), `category`(굵은
+  운영 버킷), `message`(client-facing 사유 — stack trace·내부 ID 금지), `retryable`(운영 메타를
+  1급으로 끌어올림), `details`(코드별 polymorphic — VALIDATION 이면 field error, BATCH_PARTIAL_FAILURE
+  면 per-item 결과, 아니면 null).
+
+### ResponseMeta
+- **envelope `meta` 객체로 노출되는 per-response correlation 메타**(D19/G2). camelCase JSON 이
+  wire form 이고, 로그/MDC form 은 snake_case(`request_id`/`trace_id`/`correlation_id`)이며, 그
+  변환(projection)은 adapter-web 에서 한다(이 모듈은 프레임워크 중립).
+- **D7: 실제 응답에서 `traceId` 는 절대 null 이 아니다** — tracing 이 꺼져 있으면 어댑터가 생성한
+  opaque id 를 채운다. `span_id` 는 로그 전용이라 여기 의도적으로 노출하지 않는다
+  (`mdc-keys.yaml` 에서 `envelope_field: null`).
+- `page`는 collection 응답에 pagination 메타를 싣고 단일 아이템
+  응답에선 null 이다. 3-arg 생성자는 단일 아이템 호출부를 그대로 두고, list 컨트롤러는 `withPage()`
+  로 pagination 을 붙인다.
+
+### PageMeta
+- **envelope `meta.page` 로 노출되는 pagination 메타**(D7/D18). collection 응답에만 있고 단일 아이템
+  엔 null.
+- 필드: `number`(0-indexed 페이지 번호, Spring `Pageable` 과 동일, `0`=첫 페이지), `size`(1..100 cap
+  적용 후 실제 page size), `total`(전체 element 수 — 빈 collection 은 `0`, 이때 `data` 는 `[]` 이지
+  null 이 아님), `sort`(Spring native 형식 `"field,direction"`, 미정렬이면 null).
+- 프레임워크 중립: JSON 필드명은 camelCase(envelope wire SSOT), Jackson import 없음.
+
+### BulkEnvelope
+- **bulk 엔드포인트 응답 envelope**(B8). `ApiError`/`ResponseMeta` 를 재사용하되 `data`(단일 값)를
+  `results`(리스트)로 바꾼다.
+- `success=true` 는 **모든** 아이템이 성공했을 때만이다. 하나라도 실패하면 → `success=false` +
+  `error.code=BATCH_PARTIAL_FAILURE` + per-item `details`. `results` 는 전부 성공일 때만 non-null.
+
+### BulkItemResult
+- **bulk 엔드포인트의 `error.details[]` 안에 들어가는 per-item 결과.**
+- 성공: `status="ok"` + `id`. 실패: `status="error"` + `code` + `message`.
+- 디버그 payload 를 두지 않아 envelope 를 로그/전송해도 안전하다(B8 + D3 마스킹).
+
+---
+
+## operation — 장기 실행 작업(LRO) 계약
+
+### Operation
+- **장기 실행 작업(long-running-operation) 폴링 본문**.
+  `GET /v1/operations/{id}` 가 `Envelope` 의 `data` 로 반환한다.
+- 필드: `operationId`(opaque server id, 202 응답 `Location` 헤더의 마지막 segment 이기도 함,
+  never null), `status`(`OperationStatus`, terminal 까지 클라이언트가 polling), `statusUrl`(self
+  link), `result`(`SUCCEEDED` 일 때만, AIP151-C3), `error`(`FAILED` 일 때만, AIP151-C5, 스켈레톤
+  `ApiError` 모양 재사용).
+- 프레임워크 중립. id 발급과 202/Location 배선은 web 어댑터가 한다.
+
+### OperationStatus
+- **LRO lifecycle status**(D17).
+- **프로젝트 선택:** 이 5-value 어휘는 Google AIP-151 의 `done`/`response`/`error`
+  이진 모델(AIP151-C4/C3/C5)을 프로젝트 내부용으로 투영한 것이다 — AIP-151 자체에는 enum 이 없다.
+  매핑: `PENDING`=접수됐으나 미시작, `RUNNING`=`done=false` 진행 중, `SUCCEEDED`=`done=true`+
+  `response`, `FAILED`=`done=true`+`error`, `CANCELLED`=`done=true`+취소.
+
+---
+
+## request — 요청 값 계약
+
+### Patch
+- **PATCH 커맨드 필드용 스켈레톤 공통 3-state 값**(B2). 한 필드에 대한 호출자의 의도를 표현한다:
+  `absent()`=필드 생략(변경 없음), `ofNull()`=명시적 `null`(값 비우기), `of(value)`=값으로 교체.
+- web 어댑터가 JSON `JsonNullable<T>`(Jackson 을 아는, openapi-generator 산출물)를 이 Jackson-free
+  타입으로 매핑한 뒤 use case 를 호출한다 → `application-core` 는 wire 표현을 절대 보지 않는다.
+
+---
+
+## security — 권한 계약
+
+### Permission
+- **`resource:action` 으로 이름 붙인 권한 집행 단위**.
+- **문법:** 2-segment, 소문자, colon 으로 구분(예: `worklog:close`). AWS IAM 의 `service:Action`
+  관례(IAM-NAMING-C1)와 Curity 의 `resource:action` 산업 관행(CURITY-SCOPE-C2)을 따른다.
+- **점(dot) 형태 `service.resource.verb`(Google IAM)를 거부하는 이유:** Java 패키지명과 시각적으로
+  헷갈리고, 이 단일 서비스 스켈레톤엔 필요 없는 service prefix 를 중복시키기 때문이다. 멀티 서비스용
+  `service:resource:action` 문법은 의도적인 향후 확장이라, 3-segment 값을 오늘 조용히 받아들이지 않고
+  명시적으로 거부한다.
+- `AuthorizationPort` 계약이 소비하는 as-built 값 객체다. `shared-contract`(Java-only, 프레임워크
+  자유)에 두어, application 계층은 Spring Security 타입 없이 계약을 표현하고 web 어댑터는 같은
+  타입으로 role→permission 을 해석한다.
+
+---
+
+## metrics — 메트릭/알림 계약
+
+> 이 패키지의 구체 수치(cardinality 상한, P1/P2/P3 임계치 등)는 대부분
+> **프로젝트 선택** — 외부 표준에서 유도한 게 아니라 이 스켈레톤이 합의한 운영 가정이며,
+> 트래픽 패턴/SLO 데이터에 따라 개정 대상인 "문서화된 기본값"이다. 모든 클래스는 stdlib-only(Spring/
+> Jackson/Micrometer 의존 없음).
+
+### MetricNaming
+- **Micrometer dot.case 메트릭 이름의 작명/단위 접미사 규칙**(D2/D3 + §3).
+- **이름 규칙(D2):** 소문자 영문+숫자만, 단일 점으로 segment 구분, 각 segment 는 영문자로 시작
+  (예: `http.server.requests`). 정확한 규칙은 `VALID_NAME_PATTERN` 정규식에 있다.
+- **단위 접미사(D2):** 이름의 마지막 segment 로 `seconds`/`bytes`/`total` 중 하나를 붙인다
+  (timer=seconds, byte 게이지=bytes, counter=total). 이 집합 밖의 접미사는 금지.
+- **Prometheus base-name 변환(§3):** dot.case 이름의 `.` 을 `_` 로 바꾼다
+  (`http.server.requests` → `http_server_requests`).
+- **INFERENCE / 운영 메모:** Spring Boot 3 Prometheus exporter 는 런타임에 추가 접미사
+  (`_seconds_bucket`/`_count`/`_sum` 등)를 더 붙인다 — 그건 exporter 의 소관이고 이 base-name 변환의
+  범위 밖이다. 실제 방출되는 이름은 `/actuator/prometheus` 로 검증할 것.
+
+### CardinalityBounds
+- **스켈레톤에 등록되는 메트릭의 tag 별 cardinality 상한**(§Cardinality Bounds 표의 Java mirror).
+  `limitFor(key)` 로 magic number 하드코딩 없이 상한을 조회한다(MeterFilter 설정, cardinality
+  계약 테스트).
+- 상수값(프로젝트 선택): `STATUS_CODE`=7(1xx~5xx + ok/other), `URI_TEMPLATE`=200
+  (라우트는 `/users/{id}` 처럼 템플릿 정규화 필수, raw path 는 `ForbiddenMetricTags` 로 금지),
+  `DEPENDENCY_NAME`=50, `ERROR_CODE`=100, `TENANT_ID`=1000, `RESILIENCE4J_OUTCOME`=5
+  (SUCCESS/FAILURE/CIRCUIT_OPEN/TIMEOUT/REJECTED).
+- **`ERROR_CODE`=100 은 `error-codes.yaml` 의 행 수 상한과 동기화한다.** 레지스트리가 100행을 넘으면
+  이 상수와 레지스트리 메모를 함께 갱신해야 한다.
+- **`TENANT_ID`=1000:** 메트릭 라벨은 bounded mapping-table ID 나 cohort bucket 을 써야 한다 —
+  raw UUID tenant 식별자는 라벨로 금지. 1001번째 tenant 부터는 bucket folding 이 자동 적용된다.
+- **tag-key 매핑 quirk 2가지**(`limitFor` 에서 명시 처리): (1) HTTP 메트릭 레지스트리 행의 tag 이름은
+  `status_code` 가 아니라 `status` 다 — 혼동을 막으려 `status`/`status_code` 둘 다 `STATUS_CODE`(7)로
+  매핑. (2) Resilience4j bound 는 `outcome` tag(5값)에 적용 — 상수명은 명료성을 위해
+  `RESILIENCE4J_OUTCOME` 이지만 lookup 키는 레지스트리 tag 이름인 `outcome` 다. 다른 메트릭의
+  `outcome` tag 는 실제 cardinality 가 다를 수 있으나(db 3, outbox 4), lookup 은 보수적 출발점으로
+  Resilience4j bound 를 돌려준다.
+
+### ForbiddenMetricTags
+- **스켈레톤 전역에서 금지된 high-cardinality 메트릭 tag 키**(D8): `user_id`, `request_id`,
+  `raw_url`, `raw_query`, `raw_header_value`, `ip_address`.
+- **왜 금지하나(D8):** label key-value 조합 하나마다 Prometheus 에 새 time series 가 생긴다. user
+  식별자·raw URL·IP 처럼 **무한히 늘어나는(unbounded)** 값을 tag 로 쓰면 time series 가 수백만 개로
+  폭증해 애플리케이션과 Prometheus 서버 메모리를 잡아먹는다. 근거: Prometheus 공식 best practice
+  (PROM-CARD-C1/C2 — "모든 unique label 조합 = 새 time series"; user ID/email/unbounded set 을 명시),
+  Micrometer `HighCardinalityTagsDetector`(MM-HCARD-C1/C2 — `userId`/`requestId`/`traceId` 가 대표 예시).
+- **`request_id` 가 여기선 금지인데 baggage 엔 허용인 이유(의도적 비대칭):** `request_id` 는
+  `BaggageAllowlist.ALLOWED` 에 있다 — 분산 추적 correlation 을 위한 정당한 W3C baggage 키이기
+  때문이다. 하지만 **메트릭 라벨**로 쓰면 요청당 time series 1개씩, 수백만 개가 된다. 요청별 correlation
+  은 메트릭 tag 가 아니라 분산 추적(trace ID/exemplar)으로 해야 한다. 나중에 읽는 사람이 이걸
+  "고친다"며 forbidden 목록에서 `request_id` 를 빼지 말 것 — 비대칭은 의도적이다.
+- **프로젝트 선택:** 명백한 user/request ID 예시(PROM-CARD-C2, MM-HCARD-C2) 외의
+  멤버(`raw_url`/`raw_query`/`raw_header_value`/`ip_address`)는 "unbounded set" 원칙을 HTTP 특유의
+  출처에 적용한 운영 가정이다. 이를 명시적으로 열거하는 외부 표준은 없다.
+
+### AlertSeverity
+- **메트릭 계약의 알림 심각도 분류**(D7 / §P1/P2/P3). `key()` 가 돌려주는 소문자 형태(`p1`/`p2`/`p3`)가
+  레지스트리 `alert_severity_thresholds` 키와 일치하며, `fromKey()` 의 정규 입력이다(대소문자 무시).
+- **임계치 수치는 provisional, 프로젝트 선택** — 이 스켈레톤이 합의한 운영 가정이지
+  외부 표준이 아니다. 정식 SLO 채택 시 재검토할 것(D5 burn-rate migration path).
+  - **P1**(릴리스 차단): error rate >5% 5분 OR >10% 1분; p99 latency >5s 5분; 필수 의존성 unavailable >2분.
+  - **P2**(on-call 즉시 대응): error rate >1% 10분; p99 latency >1s 10분; 선택 의존성 degraded >5분.
+  - **P3**(업무 시간 대응): error rate >0.1% 1시간; p99 latency >500ms 30분; 평소의 10× spike.
+
+---
+
+## tracing — 분산 추적 계약
+
+> tracing 패키지는 **OTel/Micrometer 런타임이 포크에서 활성화되는 seam**이라는 전제로 설계됐다
+>. 그래서 계약 타입 자체는 stdlib-only(Spring/OTel/
+> Micrometer 의존 없음)로 두어, adapter-web·adapter-outbound 가 tracer 라이브러리에 컴파일타임으로
+> 묶이지 않고도 헤더 모양/기록 seam 에 의존할 수 있게 한다.
+
+### TraceParent
+- **W3C `traceparent` 헤더의 불변(immutable) 값 타입**(D5/D7). 형식:
+  `00-<32자리 소문자 hex>-<16자리 소문자 hex>-<2자리 소문자 hex>`.
+- **strict W3C 검증**(`parse`/`of` 가 적용): version=`00`, 정확히 4개의 dash 구분 필드, trace-id 는
+  32자리 소문자 hex 이며 all-zero 금지, parent-id(span-id)는 16자리 소문자 hex 이며 all-zero 금지,
+  trace-flags 는 2자리 소문자 hex(값 자유, `sampled` = 최하위 비트).
+- **실패 처리 정책:** `parse` 는 위반 시 `Optional.empty()` 를 돌려줄 뿐 예외를 던지지 않는다.
+  `of` 는 invalid 입력이면 예외를 던진다. silent normalization 은 하지 않으므로 호출자가 소문자로
+  넣어야 한다.
+
+### BaggageAllowlist
+- **스켈레톤의 W3C/OTel baggage allowlist**(D2/D8).
+- **D8:** W3C `baggage` 헤더에는 `tenant_id` 와 `request_id` 만 허용한다. 그 밖의 모든 키는 downstream
+  으로 전파하기 전에 제거한다 — W3C Baggage spec §4.1 의 trust-boundary 규칙과 OTel Baggage API 의
+  "untrusted process" 제거 의무(D2)에 따른 것.
+
+### SpanErrorRecorder
+- **tracer 라이브러리에 결합하지 않고 span error 를 기록하기 위한 D12 seam.** adapter-web
+  (`GlobalExceptionHandler`)·adapter-outbound 가 컴파일타임 tracer 의존 없이 span error 를 일관되게
+  기록할 수 있게 한다.
+- **`NOOP` 기본값:** tracer 가 classpath 에 없는 스켈레톤 기본 상태를 위한 no-op 구현. Micrometer
+  Tracing 을 활성화하는 포크는 `app-bootstrap` composition root 에서 이 bean 을 교체한다.
+- **D12 구현 계약 (실제 tracer 를 배선하는 포크가 지켜야 할 것):**
+  1. `Observation.error(throwable)` 또는 동등한 OTel `span.recordException(throwable)` 을 호출해 error
+     lifecycle event 를 내보내고 예외를 현재 span 에 붙인다.
+  2. span status 를 별도 호출 `span.setStatus(StatusCode.ERROR)` 로 ERROR 로 만든다 — OTel Trace
+     API 명세(OTEL-TAPI-C4)상 `recordException` 은 AddEvent 만 하지 status 를 바꾸지 않는다.
+  3. `error.code` span attribute 를 전달받은 `errorCode` 문자열로 붙인다. 주의: `error.code` 는
+     ca-tmpl 레지스트리 attribute 이름이지, OTel semantic-convention 의 `exception.type`/
+     `exception.message`/`exception.stacktrace` 가 아니다.
+  4. 전체 stack trace 는 현재 span 이 sampled 일 때만 붙인다. unsampled span 에는 `error.code`
+     attribute 만 붙이고 stack trace 부착은 금지 — cardinality/데이터 볼륨 오버헤드를 피하기 위한
+     ca-tmpl 운영 결정(D12 프로젝트 선택, 외부 spec 근거 없음).
+
+---
+
+## concurrency — 런타임 컨텍스트 전파 계약
+
+도메인/비즈니스 컨텍스트(예: 비즈니스 식별자)를
+virtual-thread 와 `StructuredTaskScope.fork()` 경계 너머로 전파하는 계약이다.
+
+### 설계 골격 — "Default + 교체 가능한 추상화" (rate-limit 패턴)
+동작하는 기본 구현을 제공하되 strategy seam 뒤에 두어, 호출부를 건드리지 않고 교체/대체할 수 있게 한다.
+`RateLimiter` / `RateLimitAlgorithm` / `RateLimiterFactory` 와 정확히 같은 구조다:
+
+- **`DomainContextPropagator`** — port(인터페이스).
+- **`ThreadLocalDomainContextPropagator`** — 기본 구현(plain `ThreadLocal`, 명시적 capture/restore,
+  virtual-thread 안전, `InheritableThreadLocal` 미사용).
+- **`DomainContextStrategy`** — 선택 가능한 strategy enum(기본 `THREAD_LOCAL`; `MICROMETER`/
+  `SCOPED_VALUE` 는 주석으로만 남긴 향후 strategy).
+- **`DomainContextPropagatorFactory`** — 유일한 확장점(단일 `switch`).
+- **`DomainContextKey`** — 도메인이 공급하는 per-value 확장점(키), `RateLimitKeyResolver` 와 유사.
+
+Spring 배선(`DomainContextSettings` + `DomainContextConfig`, `ca-skeleton.domain-context.strategy`
+바인딩)은 `app-bootstrap` 에 있고, 설정이 없으면 strategy 는 `THREAD_LOCAL` 로 기본 동작한다.
+
+### 무엇을 일부러 ship 하지 않았나 (그리고 왜)
+- **도메인 키:** 스켈레톤엔 도메인이 없으므로 `DomainContextKey` 상수를 ship 하지 않고, 기본적으로
+  흐르는 값도 없다. 도메인은 필요해질 때 자기 키를 선언한다(그 전까지 seam 은 관측 가능한 동작이
+  없다 — route 가 없는 `RateLimitKeyResolver` 와 같다).
+- **`ScopedValue`/`StructuredTaskScope` strategy:** Java 21 preview API 이고 빌드에 `--enable-preview`
+  가 없어(빌드 사실 C1) 운영에서 컴파일되지 않는다. `domain_context_propagation_primitives_stay_unshipped`
+  ArchUnit 규칙(app-bootstrap `CleanArchitectureTest`)이, strategy seam 을 통해 활성화되기 전까지
+  이를 운영 코드에서 배제한다.
+
+### 경계 → 메커니즘 위임 맵 (S1, 참고용)
+각 경계의 전파는 형제 계약이 소유한다. 이 계약은 **도메인 컨텍스트** 핸드오프와 통합 view 만 소유한다:
+
+| 경계 | 메커니즘 | 소유자 |
+|---|---|---|
+| inbound HTTP 필터 | `request_id`/`correlation_id`/`trace_id` MDC(SLF4J 2.0+) | B6(boundary-validation) |
+| outbound HTTP/메시지 | W3C `traceparent`/`tracestate` + baggage | distributed-tracing D5/D7/D8 |
+| `@Async` `ThreadPoolTaskExecutor` | `TaskDecorator` 의 MDC 4-key 복사(planned) | background-job D5/D6 |
+| virtual-thread carrier | 진단용 MDC, `InheritableThreadLocal` 금지 | B6 |
+| `StructuredTaskScope.fork()`/스레드 핸드오프 | 이 패키지 propagator 통한 **도메인 컨텍스트** | 여기서 소유(S2/S3) |
+
+> `@Async` 경계는 background-job 이 executor 배선을 소유하되, 그 `TaskDecorator` 가
+> `DomainContextPropagator.wrap(Runnable)` 도 호출해 MDC 복사와 함께 도메인 컨텍스트도 운반해야 한다.
+> 이 계약은 seam 만 제공한다.
+
+### DomainContextPropagator (port)
+- 도메인/비즈니스 컨텍스트를 스레드·`fork()` 경계 너머 전파하는 **strategy seam**(S2/S3). 애플리케이션
+  코드는 이 인터페이스만 의존하고, Factory 가 설정에서 구체 strategy 를 고른다. strategy 추가 = "새 impl
+  + enum 값 1개 + factory case 1개", 호출부 변경 없음.
+- **진단(diagnostic) 컨텍스트는 여기 두지 않는다.** `request_id`/`trace_id`/`correlation_id` 는 MDC 에
+  살고 inbound 필터가 virtual thread 에서 전파한다(B6 + D11). 이 propagator 는 **도메인 채널** — 별개의
+  관심사다.
+- **명시적 핸드오프(S3):** 구현은 스레드 간 암묵적 상속에 의존해선 안 된다(`InheritableThreadLocal` 은
+  `no_inheritable_thread_local` ArchUnit 규칙으로 금지). 스레드/`fork()` 경계를 넘는 코드는
+  `wrap()` 또는 `capture()`+`restore()` 로 컨텍스트를 명시적으로 재확립한다.
+
+### DomainContextStrategy (enum)
+- `THREAD_LOCAL` 이 기본이자 현재 ship 된 유일한 값이다. 값을 추가하려면 enum 값 + `DomainContextPropagator`
+  구현 + Factory case 를 함께 더한다(`RateLimitAlgorithm` 패턴).
+- **`THREAD_LOCAL`:** plain `ThreadLocal` + 명시적 capture/restore. virtual-thread 안전(VT 마다 자기
+  copy), `no_inheritable_thread_local` 금지 준수(`InheritableThreadLocal` 아님), 추가 의존성 0.
+- **향후 strategy(주석으로만 존재):**
+  - `MICROMETER` — `io.micrometer:context-propagation` 의 `ContextSnapshot`/`ContextRegistry`. 안정적
+    API 이고 MDC/tracing 과 같은 채널에 통합된다. 다중 키나 Reactor bridge 가 필요할 때 고른다
+    (C7: 활성화 전에 virtual-thread 동작을 확인할 것).
+  - `SCOPED_VALUE` — Java 21 `ScopedValue`. 불변이며 `StructuredTaskScope` 안에서 자동 상속된다.
+    PREVIEW: `--enable-preview` 가 필요한데 현재 빌드는 켜지 않는다(C1) →
+    `domain_context_propagation_primitives_stay_unshipped` ArchUnit 규칙으로 guard 된다.
+
+### DomainContextPropagatorFactory
+- 설정된 strategy 를 만들어 주는 곳(S2). 내부의 단일 `switch` 가 유일한 확장점이다 — strategy 추가 =
+  enum 값 + 구현 + case, 호출부는 그대로. `RateLimiterFactory` 와 같은 모양.
+
+### ThreadLocalDomainContextPropagator (기본 구현)
+- plain `ThreadLocal` 이 현재 스레드의 도메인 컨텍스트 맵을 들고, 스레드 경계는 명시적 capture/restore
+  로 넘긴다(D4/D6).
+- **왜 plain `ThreadLocal` 인가:** `InheritableThreadLocal` 이 아니라서 pooled carrier 스레드 너머로
+  조용히 새지 않고 `no_inheritable_thread_local` ArchUnit 규칙(B6)을 지킨다. virtual thread 는 각자
+  자기 copy 를 갖는다(Oracle Java 21 docs, TL-VT-C1) → 같은 스레드 read 는 동작하지만 fork 시 상속은
+  없다 — 그래서 핸드오프가 `wrap()`/`capture()` 로 **명시적**이어야 하는 것이다.
+- multi-key 고빈도 변경이나 Reactor bridging 용이 아니다 — 그건 `MICROMETER` strategy 의 일이다. 이
+  기본 구현은 흔한 경우(작은 비즈니스 식별자 집합을 명시적 async 핸드오프 너머 운반)를 노린다.
+
+### DomainContextKey
+- 단일 도메인/비즈니스 컨텍스트 값에 대한 typed·named 키(S2). **확장점**이다: 비즈니스 식별자를
+  async/fork 경계 너머 운반해야 하는 도메인이 `DomainContextKey` 상수 하나를 선언하고 `Propagator` 를
+  통해 read/write 한다 — 프로젝트가 `RateLimitKeyResolver` 를 공급하는 것과 비슷하다. 스켈레톤은
+  메커니즘을 ship 하고, 도메인은 키를 공급한다.
+- identity 는 `name` 뿐이다 → 같은 이름의 두 키는 같은 slot 을 가리킨다(`type` 은 read 시 구분용).
+  키는 `static final` 상수로 두라는 의도이며, 요청마다 새로 만들지 않는다.
+
+### DomainContextSnapshot
+- 스레드/`fork()` 경계 너머 명시적 핸드오프를 위한, 한 스레드 도메인 컨텍스트의 불변 capture(S3).
+  Micrometer Context Propagation 의 `ContextSnapshot` capture/restore 모양을 본떴다.
+- `restore()` 는 반드시 try-with-resources 와 함께 써서 worker 스레드가 오염된 채 남지 않게 한다.