# `error-codes.yaml`의 `log_level` 칸 — 설계 메모 - 상태: **확정** (2026-11-06, 소유자 답 "권하는 안대로"). 결정은 10절이다. 아래 1~9절은 결정 전에 쓴 그대로 둔다. - 기준 커밋: `06f520e6` (`refactor/maturity-review-2026-11`) - 크기: 중간(brief). 이 메모가 고르는 안을 실제로 적용하는 일은 **큼**이다. 오류 코드 레지스트리는 공개 계약이라 파일 하나여도 큼이다(`docs/work/README.md` 2절). 그래서 이 메모는 대안 비교까지 하고 멈춘다. 코드와 yaml은 바꾸지 않았다. - 요청(총괄 brief 원문): "`docs/registries/error-codes.yaml`의 `log_level` 칸은 읽는 코드가 없고, 값이 코드와 다른 곳이 있다(`IDEMPOTENCY_UNAVAILABLE`: 문서 WARN, 코드 ERROR). 이 칸을 어떻게 할지 설계 메모를 쓰고 소유자 결정을 묻는다." - 처음 나온 곳: 재리뷰 round6이 "규범인지 판단하지 않았다"로 남긴 항목 (`docs/reviews/2026-11-03-rereview/round6/02-idempotency-outbound.md:217`). ## 1. 결론 권하는 안은 **A — 칸을 지운다**이다. 로그 레벨은 오류 코드 하나가 아니라 실패의 종류와 경로가 정하고, 그 규칙은 이미 코드 한 곳(`ServerFailureLog`)에 있다. 레지스트리 머리말은 그 규칙을 가리키기만 한다. 칸 값을 증상으로 적은 런북 2곳은 실제 로그 줄로 고친다. 칸과 별개로 동작 질문이 둘 남는다. 보안 필터가 5xx 두 코드를 WARN으로 남기는 것(결정 2), 문서가 ERROR로 의도한 401 세 코드(결정 3)다. ## 2. 지금 어떻게 되어 있나 ### 2.1 칸을 읽는 곳 - 스키마: `docs/registries/error-codes.yaml:18` `log_level: ERROR | WARN | INFO`. 60행 모두 값이 있다(ERROR 25, WARN 26, INFO 9). - 코드와 테스트: 읽는 곳이 없다. `src`·`scripts`의 java·py·gradle·sh에서 `log_level`·`logLevel` 검색 결과 0건이다. - 테스트가 읽는 칸: `category`·`http_status`·`retryable`·`client_safe_message`·`runbook_link`·`owner_branch`· `compatibility_impact`·`required_test`다(테스트 코드의 `get("<칸>")` 집계). `log_level`과 `owner_layer`만 아무도 읽지 않는다. - 스키마 검사(`ContractRegistrySchemaGovernanceTest`, `RegistryGovernanceCatalog.java:217, 247-253`)는 필수 칸만 본다. 모르는 칸을 막지 않는다. - 값의 이력: `git log -S log_level`의 네 커밋(`821fe00c`, `9da00eb7`, `c4a066df`, `bbe944bd`)은 행을 넣거나 뺐다. 있던 행의 레벨 값이 바뀐 적은 없다(커밋 사이 코드별 값 비교 결과 차이 0). - 런북: 두 곳이 칸 값을 증상으로 적는다. - `docs/runbooks/auth-token-invalid-signature.md:16`: "`log_level=ERROR` — may indicate forged tokens" - `docs/runbooks/authz-tenant-mismatch.md:16`: "`log_level=ERROR`" - 경보: `docs/registries/metrics.yaml`의 경보 기준은 모두 지표다(error_rate, p99 등). 로그 레벨을 세는 경보는 없다 (`logback_events`·`level=error` 검색 0건). - 파생 서비스 `tech-log-backend`(`a000f87`): 자기 `error-codes.yaml` 96행에 `log_level`을 채운다. 설계서가 새 행마다 이 칸을 채우라고 적는다(`docs/superpowers/specs/2026-08-18-techlog-studio-backend-design.md:382`). 그쪽에도 이 칸을 읽는 코드는 없다(`git grep log_level`, java·gradle·yaml·sh 0건). ### 2.2 코드가 로그 레벨을 정하는 방식 레벨은 오류 코드가 아니라 **실패의 종류와 경로**가 정한다. ```text 요청 실패 ─┬─ 보안 필터(401·403·JWKS·인증 설정) ─ AuthErrorResponseWriter ─────────── 늘 WARN ├─ IllegalArgumentException ─────────── ServerFailureLog.refusedArgument ─── WARN ├─ ApiErrorCarrier ─ ServerFailureLog.of ─┬─ PersistenceFailureException ── ERROR (상태 무관) │ ├─ DependencyFailureException ── ERROR (상태 무관) │ ├─ 그 밖의 5xx ───────────────── ERROR │ └─ 4xx ───────────────────────── 남기지 않음 ├─ Spring MVC 예외 ─ handleExceptionInternal ── 5xx면 ERROR, 4xx면 남기지 않음 └─ 그 밖의 예외 ─ handleUnknown ── INTERNAL_ERROR로 답하고 ERROR 배경 작업 ─ outbox 실패 보고, executor 거절 ── ERROR ``` 출처: - 규칙: `src/shared-contract/src/main/java/dev/caskeleton/shared/error/ServerFailureLog.java:54-79`. 4xx를 남기지 않는 이유는 같은 파일 25행 "A client-side carrier is not logged: it is an answer, not an incident"다. IAE WARN은 91-96행이다. - 네 전송이 같은 줄을 쓴다. - carrier ERROR: web `GlobalExceptionHandler.java:173-176`, gRPC `GrpcExceptionHandlingInterceptor.java:135-136`, GraphQL `GraphQlWireErrorMapper.java:134-135`, STOMP `StompHandlerFailureLog.java:35-36` - IAE WARN: web `GlobalExceptionHandler.java:96-97`, gRPC `:139-140`, GraphQL `:137-138`, STOMP `:40-41` - 보안 필터: `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/auth/AuthErrorResponseWriter.java:32` `log.warn("security failure: code={} …")`. 인증 진입점과 접근 거부 처리기가 둘 다 이 writer를 쓴다. - Spring MVC: `GlobalExceptionHandler.java:397-401`. 그 밖의 예외: 같은 파일 195-203행. - 배경 작업: `Slf4jOutboxRelayFailureReportAdapter.java`의 `atError()`, `LoggingAbortPolicy.java:35`. - 이 규칙은 리뷰를 거쳐 정한 설계다. 네 전송이 한 정책을 쓰게 했고(`ServerFailureLog` Javadoc 첫 문단), IAE를 네 전송에서 같은 WARN 한 줄로 남기게 했다(RR6-01-06, `docs/reviews/2026-11-03-rereview/README.md` 17절 r10-01). 그래서 레벨은 오류 코드 하나에 값 하나로 떨어지지 않는다. - 같은 `BAD_PARAMETER`라도 IAE에서 오면 WARN이다. 타입 변환 실패에서 오면 남기지 않는다 (`GlobalExceptionHandler.java:108-116`). - 같은 409라도 영속성 실패면 ERROR다. 멱등 in-flight면 남기지 않는다. ### 2.3 60행 대조 방법: 행마다 main 코드에서 그 코드를 내는 곳을 찾았다(`grep -rlw src --include='*.java'` 중 `/main/`). 그 경로에 2.2의 규칙을 대어 레벨을 정했다. 코드를 읽은 결과이고, 실행 탐침은 돌리지 않았다(이유는 6절 가정 4). | 결과 | 행 | 코드 | | --- | --- | --- | | 같다 | 14 | WARN: `AUTH_TOKEN_MISSING`, `AUTH_TOKEN_MALFORMED`, `AUTH_TOKEN_EXPIRED`, `AUTH_KID_UNKNOWN`. ERROR: `DB_UNAVAILABLE`, `DB_IDLE_IN_TX_TIMEOUT`, `DB_COMPLETION_UNKNOWN`, `IDEMPOTENCY_COMPLETION_UNKNOWN`, `IDEMPOTENCY_RECOVERY_REQUIRED`, `ADAPTER_DISABLED`, `INTERNAL_ERROR`, `OUTBOX_PUBLISH_FAILED`, `OUTBOX_DEAD_LETTER`, `JOB_EXECUTOR_REJECTED` | | 문서 ERROR, 코드 WARN | 5 | `AUTH_TOKEN_INVALID_SIGNATURE`, `AUTH_ISSUER_MISMATCH`, `AUTH_AUDIENCE_MISMATCH`(401), `AUTH_JWKS_UNAVAILABLE`(503), `INTERNAL_AUTH_MISCONFIGURATION`(500). 보안 필터가 모두 WARN으로 남긴다 | | 문서 WARN, 코드 ERROR | 10 | `IDEMPOTENCY_UNAVAILABLE`(503 carrier). 영속성 실패 9개: `DB_SERIALIZATION_FAILURE`, `DB_DEADLOCK`, `DB_NULL_VIOLATION`, `DB_FK_VIOLATION`, `DB_UNIQUE_VIOLATION`, `DB_CHECK_VIOLATION`, `DB_OPTIMISTIC_CONFLICT`, `DB_LOCK_TIMEOUT`(409), `DB_QUERY_CANCELED`(503). JPA 예외는 모두 `PersistenceFailureException`의 하위 타입이다(`JpaPersistenceException.java:22`) | | 문서는 레벨, 코드는 남기지 않음 | 15 | `IDEMPOTENT_IN_FLIGHT`, `IDEMPOTENT_REQUEST_MISMATCH`, `MAPPING_FAILED`, `VALIDATION_FAILED`, `PRECONDITION_FAILED`, `METHOD_NOT_ALLOWED`, `NOT_ACCEPTABLE`, `PAYLOAD_TOO_LARGE`, `URI_TOO_LONG`, `UNSUPPORTED_MEDIA_TYPE`, `ROUTE_NOT_FOUND`, `RATE_LIMIT_EXCEEDED`, `INVALID_TOKEN`, `FORBIDDEN`, `BATCH_PARTIAL_FAILURE` | | 경로마다 다름 | 3 | `BAD_PARAMETER`(문서 INFO; IAE면 WARN, 타입 변환이면 없음). `AUTHZ_INSUFFICIENT_PERMISSION`(문서 WARN; 필터면 WARN, controller method security면 `handleForbidden`이라 없음). `UNAUTHENTICATED`(문서 WARN; web은 없음, gRPC는 인증 정책이 예외를 던질 때만 WARN — `GrpcAuthenticationInterceptor.java:55`) | | 템플릿 main에 내는 곳 없음 | 13 | `AUTH_CLAIM_MAPPING_FAILED`, `AUTHZ_TENANT_MISMATCH`, `JVM_OOM`, `DEPENDENCY_TIMEOUT`, `DEPENDENCY_CONNECT_FAILED`, `DEPENDENCY_DNS_FAILED`, `DEPENDENCY_4XX_CLIENT`, `DEPENDENCY_5XX_SERVER`, `DEPENDENCY_CIRCUIT_OPEN`, `JOB_TIMEOUT`, `JOB_DEAD_LETTER`, `ACTUATOR_FORBIDDEN`, `LOCK_ACQUISITION_TIMEOUT` | - 내는 곳이 있는 47행 중 33행이 문서와 다르다. brief가 든 `IDEMPOTENCY_UNAVAILABLE`은 그중 하나다. - `DEPENDENCY_*`: 파생 서비스의 어댑터가 `DependencyFailureException`으로 던지면 ERROR가 된다. 그때는 문서가 WARN인 `DEPENDENCY_CIRCUIT_OPEN`도 어긋난다. - `LOCK_ACQUISITION_TIMEOUT`은 레벨과 별개의 문제가 있다(9절). ### 2.4 어긋남이 실제로 해를 끼치는 곳 - **런북 증상이 틀렸다.** `auth-token-invalid-signature.md`는 `log_level=ERROR`를 증상으로 적는다. 실제 줄은 WARN `security failure: code=AUTH_TOKEN_INVALID_SIGNATURE …`다. ERROR로 거르는 운영자는 이 사건을 못 본다. - **칸을 채우는 일이 헛수고다.** 새 코드를 만드는 사람이 칸을 채워도 동작이 바뀌지 않는다. 파생 서비스는 96행에 값을 골라 적었다. - 경보는 로그 레벨을 쓰지 않는다. 그래서 이 어긋남으로 경보가 빠지지는 않는다. ## 3. 선행 사례 | 출처 | 1차/2차 | 그들이 한 것 | 한계 | 가져올 것 | | --- | --- | --- | --- | --- | | 이 repo `client_safe_message` 칸 (`c4a066df`, 소유자 결정 11) | 1차 | 행마다 다르던 문구를 Category별 문구 표 하나(`ClientErrorMessages`)로 코드에 두었다. 칸은 그 값과 같아야 한다고 테스트로 고정했다(`OperationalErrorRegistryContractTest.everyRegistryClientMessageIsTheSharedCategoryMessage`) | 문구가 category만으로 정해져서 고정이 쉬웠다 | 코드가 원본이고 칸은 테스트가 고정한다. 레벨은 코드 하나로 정해지지 않는다는 점이 다르다(2.2) | | 이 repo `category`·`http_status`·`retryable` | 1차 | enum이 원본이다. yaml을 enum과 테스트로 대조한다(`theEnumAndTheRegistryAgree`) | — | 레지스트리 칸은 코드가 읽거나 테스트가 고정한다는 이 repo의 관행 | | 이 repo `env-keys.yaml`의 `required_when` (`0a6dd0e4`) | 1차 | 런타임이 강제한 적 없는 요구("app.redis.mode=sentinel")를 지우고 실제 동작에 맞췄다(`docs/registries/env-keys.yaml:2269-2273`) | — | 강제하지 않는 레지스트리 문장을 규범처럼 두지 않는다. 실제 동작으로 고친다 | | JBoss Logging Tools (Hibernate·WildFly가 씀) | 1차, | 메시지 id와 레벨을 코드의 annotation 한 곳에 둔다(`@Message(id = …)`, `@LogMessage(level = ERROR)`). 보고서(id, 해결 문서 링크, 메시지, 레벨)는 annotation에서 만든다(AsciiDoc·XML) | 메시지마다 레벨이 하나인 모델이다. 경로마다 레벨이 다른 우리 설계에는 그대로 맞지 않는다 | 레벨을 문서로 보이고 싶으면 손으로 쓴 칸이 아니라 코드에서 뽑는다 | | Spring Framework `AbstractHandlerExceptionResolver` | 1차, `spring-webmvc/src/main/java/org/springframework/web/servlet/handler/AbstractHandlerExceptionResolver.java`(main) | 예외 처리 로그는 처리기 코드가 정한다. 기본은 남기지 않고, `setWarnLogCategory`로 켜면 WARN 한 레벨로 남긴다 | 오류 코드별 레벨 표는 없다 | 처리된 클라이언트 오류는 기본으로 남기지 않는다. `ServerFailureLog`의 "4xx는 답이지 사건이 아니다"와 같은 판단이다 | ## 4. 대안 ### A. 칸을 지운다 - 머리말 스키마에서 `log_level` 줄을 뺀다. 대신 "로그 레벨은 오류 코드가 아니라 실패 종류와 경로가 정한다. 규칙은 `ServerFailureLog` Javadoc과 `AuthErrorResponseWriter`"라고 적는다. - 60행에서 `log_level:` 줄을 지운다. - 런북 2곳의 증상 줄을 실제 로그 줄로 고친다. - `docs/upgrade/`에 파생 서비스 안내를 한 줄 더한다. - 선택(결정 1-b): 칸이 다시 생기지 않게 "행에 `log_level`이 없다"는 단언을 레지스트리 테스트에 둔다. 두면 파생 서비스도 자기 행에서 칸을 지워야 merge 뒤 테스트가 통과한다. ### B. 칸을 남기고 코드에 맞춘 뒤 테스트로 고정한다 - 값 집합에 `NONE`(남기지 않음)과 `BY_PATH`(경로마다 다름)를 더한다. 60행을 2.3 표대로 고친다. - 테스트는 `ServerFailureLog` 규칙을 다시 구현한 표(코드 → 기대 레벨)와 yaml을 대조한다. - 문제: 레벨이 코드만으로 정해지지 않아서, 표가 규칙의 손 사본이 된다. 예외 종류(영속성·의존성 carrier)는 행에 없으므로, 테스트가 "`DB_*`면 ERROR"를 이름 접두어로 짐작해야 한다. 템플릿 main에 내는 곳이 없는 13행은 기대값을 정할 근거가 없다. ### C. 칸을 규범으로 만들고 코드가 읽는다 - `ApiErrorCode`에 `logLevel()`을 더한다. `OperationalError`는 값을 갖고, 파생 enum은 default 메서드로 지금 규칙을 쓴다. - 네 전송, 보안 필터, 배경 작업이 그 값으로 남긴다. yaml은 enum과 테스트로 대조한다. - 동작이 바뀐다. 2.3의 33행이 지금과 다른 레벨이 된다. - 문서가 INFO·WARN인 4xx 15행이 새로 로그를 남긴다. 404·400·429마다 한 줄씩이라, 스캐너·공격 트래픽이 로그 양을 정한다. - 409 영속성 실패는 ERROR에서 WARN으로 내려간다. - `ServerFailureLog`의 "4xx는 남기지 않는다"와 RR6-01-06 결정을 뒤집는다. 다시 열 조건(`docs/work/reference/decisions.md` 1절)에 맞는 새 근거가 없다. - `ApiErrorCode`는 shared-contract의 공개 인터페이스다. 파생 서비스의 enum이 영향을 받는다. ### 버린 기준선: 주석만 달기 칸에 "참고용"이라 적고 `IDEMPOTENCY_UNAVAILABLE` 한 행만 고치는 안이다. 틀린 33행 중 1행만 고쳐지고 런북은 여전히 틀린 증상을 적는다. 버린다. ### 비교 | 대안 | 효과 | 비용 | 되돌리기 | 파생 서비스 영향 | 기존 결정과 충돌 | | --- | --- | --- | --- | --- | --- | | A 지움 | 틀린 값 33행과 틀린 런북 증상 2곳이 사라진다. 레벨의 원본이 코드 하나로 준다 | yaml 머리말·60줄, 런북 2곳, upgrade 1줄. 코드 변경 0 (1-b면 테스트 단언 1개) | 쉽다(revert) | 1-b 없으면 할 일 없음. 1-b면 자기 96행에서 칸을 지운다 | 없다. `client_safe_message`·`env-keys` 선례와 같은 방향 | | B 맞추고 고정 | 칸이 맞는 값이 된다 | yaml 33행, 스키마, 새 테스트(규칙의 손 사본). 규칙을 바꿀 때마다 두 곳을 고친다 | 쉽다 | 같은 테스트가 파생 행도 읽으면 자기 행도 맞춰야 한다 | 없다. 다만 규칙 사본을 하나 더 만든다 | | C 규범화 | 소유자가 코드마다 레벨을 고를 수 있다 | shared-contract 인터페이스, 전송 넷, 보안 필터, 배경 작업, 테스트. 로그 양이 는다 | 어렵다(공개 인터페이스, 운영 로그 모양) | `ApiErrorCode` 구현 enum, 로그 수집 규칙 | `ServerFailureLog` 설계, RR6-01-06 | ## 5. 권하는 안: A - 이 칸이 담으려던 정보("이 코드가 얼마나 시끄러운가")는 코드가 이미 실패 종류로 정한다. 그 규칙은 리뷰를 거쳐 네 전송에 하나로 모였다. 코드별 칸은 그 규칙을 담을 모양이 아니다(2.2). - B는 그 규칙의 손 사본을 테스트에 하나 더 만든다. 사본은 고칠 곳만 늘린다. 내는 곳이 없는 13행에는 고정할 값도 없다. - C는 코드가 맞고 문서가 틀린 상황에서 코드를 문서에 맞춘다. 문서 값은 행을 처음 넣을 때 적은 뒤 한 번도 고친 적이 없다(2.1). 레벨을 따져 본 리뷰를 거친 쪽은 코드다. - 이 repo의 관행은 "칸은 코드가 읽거나 테스트가 고정한다"이다. 이 관행에 맞는 길은 A와 B인데, B는 고정할 값이 없다. 그래서 A다. ## 6. 반증할 수 있는 가정, 반론과 답 ### 가정 1. **템플릿과 파생 서비스 밖에서 이 칸을 읽는 도구가 없다.** 틀렸다면: 로그 파이프라인이나 대시보드가 이 yaml을 읽고 있다면 칸 삭제가 그것을 깨뜨린다. 확인한 범위는 두 repo의 추적 파일이다. repo 밖 운영 도구는 모른다(결정 4). 2. **레벨은 오류 코드 하나로 정해지지 않는다.** 틀렸다면 B의 비용이 크게 준다. 확인: `GlobalExceptionHandler.java:96-97`(IAE, WARN)과 `:108-116`(타입 변환, 로그 없음)가 같은 `BAD_PARAMETER`를 낸다. 3. **4xx를 남기지 않는 것은 의도다.** 틀렸다면, 즉 소유자가 4xx를 줄 단위로 추적하길 원하면 C가 맞다. 근거: `ServerFailureLog.java:25`의 문장. 4xx 양은 `http.server.requests`의 `status=4xx` 지표로 이미 보인다 (`metrics.yaml:18-40`). 4. **2.3 표는 코드 읽기로 충분하다.** 틀렸다면: 다른 경로가 같은 코드를 다른 레벨로 남기면 표 칸이 바뀐다. 결론 ("대부분 다르다")은 33행 중 몇 행이 바뀌어도 유지된다. 탐침을 돌리지 않은 이유는 둘이다. - 각 경로는 레벨을 바꾸는 분기가 없는 `log.error`/`log.warn` 한 줄이다. - 기존 테스트가 같은 레벨을 고정한다: `GrpcExceptionHandlingInterceptorTest`·`StompHandlerFailureLogTest`· `GraphQlWireErrorMapperTest`의 `Level.ERROR`/`Level.WARN` 단언, `GlobalExceptionHandlerTest.anIllegalArgumentIsLoggedAtWarnByItsTypeWithoutItsMessage`. ### 반론과 답 - **"레벨을 문서에서 한눈에 보는 가치가 있다."** 그 가치는 값이 맞을 때만 있다. 지금은 47행 중 33행이 틀렸다. 꼭 보이고 싶다면 JBoss Logging처럼 코드에서 뽑아야 한다. 그것은 레벨이 코드별 값이 된 뒤(C)에나 가능하다. - **"보안 쪽 ERROR(위조 토큰 의심)는 의도였다."** 의도는 런북 문장에 남아 있지만 구현된 적이 없다. 401 서명 실패를 ERROR로 남기면 공격자가 ERROR 양을 정하게 된다. 감지가 필요하면 결정 3에서 따로 고른다. - **"칸을 지우면 파생 서비스가 upstream merge 때 할 일이 생긴다."** 1-b를 두지 않으면 할 일이 없다. 1-b를 두면 지울 일이 생기지만, 같은 거짓 칸이 파생 서비스 96행에 남지 않는다. ## 7. 소유자가 정할 것 | # | 항목 | 선택지 | 권하는 안과 이유 | 정할 사람 | | --- | --- | --- | --- | --- | | 1 | `log_level` 칸 | A 지움 / B 코드 규칙에 맞추고 테스트로 고정 / C 규범화(코드가 읽음) | **A**. 5절 | 소유자 | | 1-b | A일 때 칸이 다시 생기는 것을 막는 단언 | 둔다(파생 서비스도 자기 행에서 지운다) / 두지 않는다 | **둔다**. 칸이 거짓인 것은 파생 서비스 행도 같다. upgrade 안내 "반드시 할 일"에 한 줄 | 소유자 | | 2 | 보안 필터가 5xx 두 코드(`AUTH_JWKS_UNAVAILABLE` 503, `INTERNAL_AUTH_MISCONFIGURATION` 500)를 WARN으로 남기는 것 | ERROR로 올림 / WARN 유지 | **ERROR로 올림**. 다른 모든 경로가 5xx를 ERROR로 남긴다. 둘 다 서버 쪽 고장(키 서버 장애, 설정 오류)이다. 1번과 관계없이 동작 변경이라 별도 개선 작업으로 한다 | 소유자 | | 3 | 401 서명·issuer·audience 불일치(문서가 ERROR로 의도) | WARN 유지, 런북은 WARN 줄의 code로 찾게 고침 / ERROR로 올림 / WARN 유지 + 코드별 인증 실패 지표를 새로 둠 | **WARN 유지**. 클라이언트가 만드는 실패라 ERROR로 올리면 공격 트래픽이 ERROR 양을 정한다. 경보가 필요하면 세 번째 안이다. 지금은 코드별 인증 실패 지표가 없다(`metrics.yaml`) | 소유자 | | 4 | repo 밖에서 이 칸을 읽는 도구 | 있음 / 없음 | **모름**. 두 repo의 추적 파일에는 없다. 있으면 A를 다시 본다 | 소유자 | ## 8. 결정 뒤 할 일 (이 메모에서는 하지 않았다) - A를 고르면: `docs/registries/error-codes.yaml` 머리말과 60행, 런북 2곳, `docs/upgrade/` 안내 한 줄, (1-b면) 레지스트리 테스트 단언. 공개 계약 변경이라 크기는 큼이고 `docs/work/improve.md`로 한다. 결정은 `docs/work/reference/decisions.md`에 기록한다. - 결정 2를 고르면: `AuthErrorResponseWriter`의 레벨 분기와 테스트(RED → GREEN). - B나 C를 고르면 이 메모의 4절을 계획서로 옮겨 다시 크기를 잡는다. ## 9. 이 조사 중 본 별개 문제 (범위 밖, 고치지 않았다) - `LockAcquisitionTimeoutException`은 `ApiErrorCarrier`를 구현하지 않는다 (`src/application-core/src/main/java/dev/caskeleton/application/lock/LockAcquisitionTimeoutException.java:13`). inbound 어디에도 이 예외의 처리기가 없다(`grep -rln LockAcquisitionTimeoutException src`: persistence-jpa와 테스트뿐). - Javadoc은 "The web adapter maps it to 409"라고 적는다. 하지만 web은 `handleUnknown`을 거쳐 `INTERNAL_ERROR` 500으로 답할 것으로 읽힌다(`GlobalExceptionHandler.java:195-203`). - `LockAcquisitionTimeoutClassificationContractTest`가 막으려는 "500 INTERNAL로 뭉개기"(D7)와 같은 모양이다. 그 테스트는 enum과 레지스트리만 보고 전송 경로는 보지 않는다. - 코드 읽기 결과이고 탐침은 돌리지 않았다. 결함 후보로 `docs/work/improve.md` 절차에 넘긴다. ## 10. 결정 (2026-11-06) 소유자 답은 "권하는 안대로"다(총괄 세션 전달, 2026-11-06). 7절 각 항목은 이렇게 정해졌다. | # | 결정 | 적용한 곳 | | --- | --- | --- | | 1 | A. `log_level` 칸을 지운다. 레지스트리 머리말이 레벨을 정하는 코드(`ServerFailureLog`, `AuthErrorResponseWriter`)를 가리킨다 | `docs/registries/error-codes.yaml` 머리말과 60행 | | 1-b | 칸이 다시 생기지 않게 단언을 둔다. 파생 서비스는 자기 행에서도 지운다 | `OperationalErrorRegistryContractTest.noRegistryRowCarriesALogLevel`(태그 `document-contract`), `docs/upgrade/2026-11-maturity-review.md` 「반드시 할 일」 17·B-44 | | 2 | 보안 필터는 5xx(`AUTH_JWKS_UNAVAILABLE` 503, `INTERNAL_AUTH_MISCONFIGURATION` 500)를 ERROR로 남긴다 | `AuthErrorResponseWriter`(5xx ERROR, 4xx WARN), `EnvelopeAuthenticationEntryPointTest`, web README, 런북 2곳, upgrade 5절 | | 3 | 401 서명·issuer·audience 불일치는 WARN으로 둔다. 런북은 WARN 줄의 `code=`로 찾게 고친다 | `docs/runbooks/auth-token-invalid-signature.md`, 서명 실패 WARN을 고정한 테스트 | | 4 | repo 밖에서 이 칸을 읽는 도구는 없는 것으로 본다 | — | 결정 색인: `docs/work/reference/decisions.md` 2.3절 「오류 코드 로그 레벨」.