Merge remote-tracking branch 'origin/claude/t3-error-codes-loglevel-fcf427' into claude/integration-r7

This commit is contained in:
DongHyeonka
2026-11-06 22:56:39 +09:00
12 changed files with 391 additions and 75 deletions
+8 -62
View File
@@ -1,7 +1,7 @@
# Registry: Error Codes
# Schema owner: feature-contract-registry-governance
# Category enum owner: feature-operational-error-observability-foundation
# Last updated: 2026-09-28
# Last updated: 2026-11-06
# Scope: skeleton-wide OperationalError SSOT. Product/fork ApiErrorCode enums own local registries/contracts.
#
# Schema (per row):
@@ -15,7 +15,6 @@
# owner_layer: presentation | application | domain | infrastructure | crosscut
# client_safe_message: = shared-contract ClientErrorMessages.of(category) — category별 한국어 문구 표
# 하나(소유자 결정 11). no token / no principal raw / no internal path / no stack trace
# log_level: ERROR | WARN | INFO
# runbook_link: runbook://area/scenario OR null (client-error만 null 허용)
# compatibility_impact: none | additive | behavior-change | breaking
# required_test: owning contract test identifier
@@ -25,6 +24,13 @@
# TRANSIENT_DEPENDENCY, PERMANENT_DEPENDENCY} ⇒ runbook_link 필수.
# VALIDATION/NOT_FOUND/CONFLICT/DATA_INTEGRITY는 client-error로 runbook 면제 가능.
# retryable=true 인 모든 row는 runbook_link 필수.
#
# 로그 레벨은 행의 칸이 아니다. 레벨은 오류 코드가 아니라 실패의 종류와 경로가 정한다.
# shared-contract ServerFailureLog — 모든 전송이 쓴다. 영속성·의존성 carrier와 5xx carrier는 ERROR,
# 4xx carrier는 남기지 않는다. IllegalArgumentException(BAD_PARAMETER)은 WARN.
# web AuthErrorResponseWriter — 보안 필터. 5xx는 ERROR, 4xx는 WARN.
# 행에 log_level을 두면 OperationalErrorRegistryContractTest가 실패한다.
# 결정: docs/superpowers/specs/2026-11-06-error-code-log-level-design.md 7·10절.
errors:
@@ -41,7 +47,6 @@ errors:
owner_branch: feature-security-operational-baseline
owner_layer: presentation
client_safe_message: "인증이 필요합니다."
log_level: WARN
runbook_link: "runbook://auth/token-missing"
compatibility_impact: none
required_test: contract-verification:auth-category
@@ -55,7 +60,6 @@ errors:
owner_branch: feature-security-operational-baseline
owner_layer: presentation
client_safe_message: "인증이 필요합니다."
log_level: WARN
runbook_link: "runbook://auth/token-malformed"
compatibility_impact: none
required_test: contract-verification:auth-category
@@ -69,7 +73,6 @@ errors:
owner_branch: feature-security-operational-baseline
owner_layer: presentation
client_safe_message: "인증이 필요합니다."
log_level: WARN
runbook_link: "runbook://auth/token-expired"
compatibility_impact: none
required_test: contract-verification:auth-category
@@ -83,7 +86,6 @@ errors:
owner_branch: feature-security-operational-baseline
owner_layer: presentation
client_safe_message: "인증이 필요합니다."
log_level: ERROR
runbook_link: "runbook://auth/token-invalid-signature"
compatibility_impact: none
required_test: contract-verification:auth-category
@@ -97,7 +99,6 @@ errors:
owner_branch: feature-security-operational-baseline
owner_layer: presentation
client_safe_message: "인증이 필요합니다."
log_level: ERROR
runbook_link: "runbook://auth/issuer-mismatch"
compatibility_impact: none
required_test: contract-verification:auth-category
@@ -111,7 +112,6 @@ errors:
owner_branch: feature-security-operational-baseline
owner_layer: presentation
client_safe_message: "인증이 필요합니다."
log_level: ERROR
runbook_link: "runbook://auth/audience-mismatch"
compatibility_impact: none
required_test: contract-verification:auth-category
@@ -126,7 +126,6 @@ errors:
owner_branch: feature-security-operational-baseline
owner_layer: presentation
client_safe_message: "인증이 필요합니다."
log_level: WARN
runbook_link: "runbook://auth/kid-unknown"
compatibility_impact: none
required_test: contract-verification:auth-category
@@ -140,7 +139,6 @@ errors:
owner_branch: feature-security-operational-baseline
owner_layer: infrastructure
client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요."
log_level: ERROR
runbook_link: "runbook://auth/jwks-unavailable"
compatibility_impact: none
required_test: contract-verification:auth-category
@@ -154,7 +152,6 @@ errors:
owner_branch: feature-security-operational-baseline
owner_layer: presentation
client_safe_message: "인증이 필요합니다."
log_level: ERROR
runbook_link: "runbook://auth/claim-mapping-failed"
compatibility_impact: none
required_test: contract-verification:auth-category
@@ -172,7 +169,6 @@ errors:
owner_branch: feature-security-operational-baseline
owner_layer: presentation
client_safe_message: "이 작업을 수행할 권한이 없습니다."
log_level: WARN
runbook_link: "runbook://authz/insufficient-permission"
compatibility_impact: none
required_test: contract-verification:authz-category
@@ -186,7 +182,6 @@ errors:
owner_branch: feature-security-operational-baseline
owner_layer: presentation
client_safe_message: "이 작업을 수행할 권한이 없습니다."
log_level: ERROR
runbook_link: "runbook://authz/tenant-mismatch"
compatibility_impact: none
required_test: contract-verification:authz-category
@@ -204,7 +199,6 @@ errors:
owner_branch: feature-security-operational-baseline
owner_layer: crosscut
client_safe_message: "요청을 처리할 수 없습니다."
log_level: ERROR
runbook_link: "runbook://auth/public-path-misconfiguration"
compatibility_impact: none
required_test: contract-verification:auth-category
@@ -218,7 +212,6 @@ errors:
owner_branch: feature-container-runtime-contract
owner_layer: infrastructure
client_safe_message: "요청을 처리할 수 없습니다."
log_level: ERROR
runbook_link: "runbook://runtime/jvm-oom"
compatibility_impact: none
required_test: contract-verification:container-runtime-oom
@@ -236,7 +229,6 @@ errors:
owner_branch: feature-persistence-failure-baseline
owner_layer: infrastructure
client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요."
log_level: ERROR
runbook_link: "runbook://db/unavailable"
compatibility_impact: none
required_test: contract-verification:persistence-mapping
@@ -250,7 +242,6 @@ errors:
owner_branch: feature-persistence-failure-baseline
owner_layer: infrastructure
client_safe_message: "현재 상태에서는 요청을 처리할 수 없습니다."
log_level: WARN
runbook_link: "runbook://db/serialization-failure"
compatibility_impact: none
required_test: contract-verification:persistence-mapping
@@ -264,7 +255,6 @@ errors:
owner_branch: feature-persistence-failure-baseline
owner_layer: infrastructure
client_safe_message: "현재 상태에서는 요청을 처리할 수 없습니다."
log_level: WARN
runbook_link: "runbook://db/deadlock"
compatibility_impact: none
required_test: contract-verification:persistence-mapping
@@ -278,7 +268,6 @@ errors:
owner_branch: feature-persistence-failure-baseline
owner_layer: infrastructure
client_safe_message: "요청을 처리할 수 없습니다."
log_level: WARN
runbook_link: null
compatibility_impact: none
required_test: contract-verification:persistence-mapping
@@ -292,7 +281,6 @@ errors:
owner_branch: feature-persistence-failure-baseline
owner_layer: infrastructure
client_safe_message: "요청을 처리할 수 없습니다."
log_level: WARN
runbook_link: null
compatibility_impact: none
required_test: contract-verification:persistence-mapping
@@ -306,7 +294,6 @@ errors:
owner_branch: feature-persistence-failure-baseline
owner_layer: infrastructure
client_safe_message: "현재 상태에서는 요청을 처리할 수 없습니다."
log_level: WARN
runbook_link: null
compatibility_impact: none
required_test: contract-verification:persistence-mapping
@@ -320,7 +307,6 @@ errors:
owner_branch: feature-persistence-failure-baseline
owner_layer: infrastructure
client_safe_message: "요청을 처리할 수 없습니다."
log_level: WARN
runbook_link: null
compatibility_impact: none
required_test: contract-verification:persistence-mapping
@@ -334,7 +320,6 @@ errors:
owner_branch: feature-persistence-failure-baseline
owner_layer: infrastructure
client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요."
log_level: ERROR
runbook_link: "runbook://db/idle-in-tx-timeout"
compatibility_impact: none
required_test: contract-verification:persistence-mapping
@@ -348,7 +333,6 @@ errors:
owner_branch: feature-persistence-failure-baseline
owner_layer: infrastructure
client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요."
log_level: WARN
runbook_link: "runbook://db/query-canceled"
compatibility_impact: none
required_test: contract-verification:persistence-mapping
@@ -362,7 +346,6 @@ errors:
owner_branch: feature-persistence-failure-baseline
owner_layer: infrastructure
client_safe_message: "현재 상태에서는 요청을 처리할 수 없습니다."
log_level: WARN
runbook_link: null
compatibility_impact: additive
required_test: persistence-jpa:JpaPersistenceExceptionCodeTest
@@ -376,7 +359,6 @@ errors:
owner_branch: feature-persistence-failure-baseline
owner_layer: infrastructure
client_safe_message: "요청을 처리할 수 없습니다."
log_level: ERROR
runbook_link: null
compatibility_impact: additive
required_test: persistence-jpa:JpaPersistenceExceptionCodeTest
@@ -394,7 +376,6 @@ errors:
owner_branch: feature-rate-limit-idempotency-contract
owner_layer: presentation
client_safe_message: "요청이 너무 잦습니다. 잠시 후 다시 시도해 주세요."
log_level: WARN
runbook_link: "runbook://rate-limit/exceeded"
compatibility_impact: none
required_test: contract-verification:rate-limit
@@ -412,7 +393,6 @@ errors:
owner_branch: feature-rate-limit-idempotency-contract
owner_layer: application
client_safe_message: "현재 상태에서는 요청을 처리할 수 없습니다."
log_level: INFO
runbook_link: null
compatibility_impact: behavior-change
required_test: contract-verification:idempotency
@@ -426,7 +406,6 @@ errors:
owner_branch: feature-rate-limit-idempotency-contract
owner_layer: application
client_safe_message: "요청 값이 올바르지 않습니다."
log_level: WARN
runbook_link: null
compatibility_impact: none
required_test: contract-verification:idempotency
@@ -440,7 +419,6 @@ errors:
owner_branch: feature-rate-limit-idempotency-contract
owner_layer: application
client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요."
log_level: WARN
runbook_link: "runbook://idempotency/unavailable"
compatibility_impact: additive
required_test: contract-verification:idempotency
@@ -456,7 +434,6 @@ errors:
owner_branch: feature-rate-limit-idempotency-contract
owner_layer: application
client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요."
log_level: ERROR
runbook_link: "runbook://idempotency/unavailable"
compatibility_impact: additive
required_test: contract-verification:idempotency
@@ -470,7 +447,6 @@ errors:
owner_branch: feature-rate-limit-idempotency-contract
owner_layer: application
client_safe_message: "요청을 처리할 수 없습니다."
log_level: ERROR
runbook_link: "runbook://idempotency/unavailable"
compatibility_impact: additive
required_test: contract-verification:idempotency
@@ -498,7 +474,6 @@ errors:
owner_branch: feature-api-contract-baseline
owner_layer: presentation
client_safe_message: "요청 값이 올바르지 않습니다."
log_level: INFO
runbook_link: null
compatibility_impact: none
required_test: contract-verification:api-contract-status-mapping
@@ -512,7 +487,6 @@ errors:
owner_branch: feature-api-contract-baseline
owner_layer: presentation
client_safe_message: "요청 값이 올바르지 않습니다."
log_level: INFO
runbook_link: null
compatibility_impact: none
required_test: contract-verification:api-contract-status-mapping
@@ -526,7 +500,6 @@ errors:
owner_branch: feature-api-contract-baseline
owner_layer: presentation
client_safe_message: "현재 상태에서는 요청을 처리할 수 없습니다."
log_level: INFO
runbook_link: null
compatibility_impact: none
required_test: contract-verification:api-contract-status-mapping
@@ -540,7 +513,6 @@ errors:
owner_branch: feature-api-contract-baseline
owner_layer: presentation
client_safe_message: "요청 값이 올바르지 않습니다."
log_level: WARN
runbook_link: null
compatibility_impact: none
required_test: contract-verification:api-contract-status-mapping
@@ -557,7 +529,6 @@ errors:
owner_branch: feature-api-contract-baseline
owner_layer: presentation
client_safe_message: "요청 값이 올바르지 않습니다."
log_level: WARN
runbook_link: null
compatibility_impact: none
required_test: contract-verification:api-contract-status-mapping
@@ -571,7 +542,6 @@ errors:
owner_branch: feature-api-contract-baseline
owner_layer: presentation
client_safe_message: "요청 값이 올바르지 않습니다."
log_level: INFO
runbook_link: null
compatibility_impact: none
required_test: contract-verification:api-contract-status-mapping
@@ -609,7 +579,6 @@ errors:
owner_branch: feature-outbound-http-client-baseline
owner_layer: infrastructure
client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요."
log_level: ERROR
runbook_link: "runbook://dependency/timeout"
compatibility_impact: none
required_test: contract-verification:outbound-http
@@ -623,7 +592,6 @@ errors:
owner_branch: feature-outbound-http-client-baseline
owner_layer: infrastructure
client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요."
log_level: ERROR
runbook_link: "runbook://dependency/connect-failed"
compatibility_impact: none
required_test: contract-verification:outbound-http
@@ -637,7 +605,6 @@ errors:
owner_branch: feature-outbound-http-client-baseline
owner_layer: infrastructure
client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요."
log_level: ERROR
runbook_link: "runbook://dependency/dns-failed"
compatibility_impact: none
required_test: contract-verification:outbound-http
@@ -651,7 +618,6 @@ errors:
owner_branch: feature-outbound-http-client-baseline
owner_layer: infrastructure
client_safe_message: "요청을 처리할 수 없습니다."
log_level: ERROR
runbook_link: "runbook://dependency/4xx-client"
compatibility_impact: none
required_test: contract-verification:outbound-http
@@ -665,7 +631,6 @@ errors:
owner_branch: feature-outbound-http-client-baseline
owner_layer: infrastructure
client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요."
log_level: ERROR
runbook_link: "runbook://dependency/5xx-server"
compatibility_impact: none
required_test: contract-verification:outbound-http
@@ -679,7 +644,6 @@ errors:
owner_branch: feature-outbound-http-client-baseline
owner_layer: infrastructure
client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요."
log_level: WARN
runbook_link: "runbook://dependency/circuit-open"
compatibility_impact: none
required_test: contract-verification:outbound-http
@@ -697,7 +661,6 @@ errors:
owner_branch: feature-domain-event-outbox-contract
owner_layer: infrastructure
client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요."
log_level: ERROR
runbook_link: "runbook://outbox/publish-failed"
compatibility_impact: none
required_test: contract-verification:outbox-publish
@@ -711,7 +674,6 @@ errors:
owner_branch: feature-domain-event-outbox-contract
owner_layer: infrastructure
client_safe_message: "요청을 처리할 수 없습니다."
log_level: ERROR
runbook_link: "runbook://outbox/dead-letter"
compatibility_impact: none
required_test: contract-verification:outbox-dlq
@@ -729,7 +691,6 @@ errors:
owner_branch: feature-background-job-async-contract
owner_layer: infrastructure
client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요."
log_level: ERROR
runbook_link: "runbook://job/executor-rejected"
compatibility_impact: none
required_test: contract-verification:async-saturation
@@ -743,7 +704,6 @@ errors:
owner_branch: feature-background-job-async-contract
owner_layer: infrastructure
client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요."
log_level: ERROR
runbook_link: "runbook://job/timeout"
compatibility_impact: none
required_test: contract-verification:async-timeout
@@ -757,7 +717,6 @@ errors:
owner_branch: feature-background-job-async-contract
owner_layer: infrastructure
client_safe_message: "요청을 처리할 수 없습니다."
log_level: ERROR
runbook_link: "runbook://job/dead-letter"
compatibility_impact: none
required_test: contract-verification:async-dlq
@@ -782,7 +741,6 @@ errors:
owner_branch: feature-distributed-lock-contract
owner_layer: infrastructure
client_safe_message: "현재 상태에서는 요청을 처리할 수 없습니다."
log_level: WARN
runbook_link: "runbook://lock/acquisition-timeout"
compatibility_impact: none
required_test: contract-verification:lock-acquisition-timeout
@@ -800,7 +758,6 @@ errors:
owner_branch: feature-integration-adapter-templates
owner_layer: infrastructure
client_safe_message: "요청을 처리할 수 없습니다."
log_level: ERROR
runbook_link: "runbook://adapter/adapter-disabled"
compatibility_impact: none
required_test: adapter-contract:adapter-disabled-runtime-call
@@ -819,7 +776,6 @@ errors:
owner_branch: feature-management-actuator-security-contract
owner_layer: presentation
client_safe_message: "이 작업을 수행할 권한이 없습니다."
log_level: WARN
runbook_link: "runbook://management/actuator-forbidden"
compatibility_impact: none
required_test: contract-verification:management-actuator
@@ -838,7 +794,6 @@ errors:
owner_branch: 2026-09-21-core-web-review-remediation
owner_layer: application
client_safe_message: "요청 값이 올바르지 않습니다."
log_level: INFO
runbook_link: null
compatibility_impact: additive
required_test: contract-verification:operational-error-registry
@@ -851,7 +806,6 @@ errors:
owner_branch: 2026-09-21-core-web-review-remediation
owner_layer: presentation
client_safe_message: "요청 값이 올바르지 않습니다."
log_level: INFO
runbook_link: null
compatibility_impact: additive
required_test: contract-verification:operational-error-registry
@@ -864,7 +818,6 @@ errors:
owner_branch: 2026-09-21-core-web-review-remediation
owner_layer: presentation
client_safe_message: "요청 값이 올바르지 않습니다."
log_level: INFO
runbook_link: null
compatibility_impact: additive
required_test: contract-verification:operational-error-registry
@@ -877,7 +830,6 @@ errors:
owner_branch: 2026-09-21-core-web-review-remediation
owner_layer: application
client_safe_message: "요청 값이 올바르지 않습니다."
log_level: WARN
runbook_link: null
compatibility_impact: additive
required_test: contract-verification:operational-error-registry
@@ -890,7 +842,6 @@ errors:
owner_branch: 2026-09-21-core-web-review-remediation
owner_layer: crosscut
client_safe_message: "요청을 처리할 수 없습니다."
log_level: ERROR
runbook_link: "runbook://internal/error-spike"
compatibility_impact: additive
required_test: contract-verification:operational-error-registry
@@ -903,7 +854,6 @@ errors:
owner_branch: 2026-09-21-core-web-review-remediation
owner_layer: presentation
client_safe_message: "인증이 필요합니다."
log_level: WARN
runbook_link: "runbook://auth/token-missing"
compatibility_impact: additive
required_test: contract-verification:operational-error-registry
@@ -916,7 +866,6 @@ errors:
owner_branch: 2026-09-21-core-web-review-remediation
owner_layer: presentation
client_safe_message: "인증이 필요합니다."
log_level: WARN
runbook_link: "runbook://auth/token-malformed"
compatibility_impact: additive
required_test: contract-verification:operational-error-registry
@@ -929,7 +878,6 @@ errors:
owner_branch: 2026-09-21-core-web-review-remediation
owner_layer: presentation
client_safe_message: "이 작업을 수행할 권한이 없습니다."
log_level: WARN
runbook_link: "runbook://authz/insufficient-permission"
compatibility_impact: additive
required_test: contract-verification:operational-error-registry
@@ -942,7 +890,6 @@ errors:
owner_branch: 2026-09-21-core-web-review-remediation
owner_layer: presentation
client_safe_message: "요청한 리소스를 찾을 수 없습니다."
log_level: INFO
runbook_link: null
compatibility_impact: additive
required_test: contract-verification:operational-error-registry
@@ -955,7 +902,6 @@ errors:
owner_branch: 2026-09-21-core-web-review-remediation
owner_layer: infrastructure
client_safe_message: "현재 상태에서는 요청을 처리할 수 없습니다."
log_level: WARN
runbook_link: null
compatibility_impact: additive
required_test: contract-verification:operational-error-registry
+3 -1
View File
@@ -4,7 +4,7 @@ category: TRANSIENT_DEPENDENCY
error_codes: [AUTH_JWKS_UNAVAILABLE]
severity: P1
owner: oncall
last_updated: 2026-06-15
last_updated: 2026-11-06
status: stub
---
@@ -13,6 +13,8 @@ status: stub
## Symptoms
- HTTP 503 with `error.code=AUTH_JWKS_UNAVAILABLE`
- ERROR log line `security failure: code=AUTH_JWKS_UNAVAILABLE category=TRANSIENT_DEPENDENCY method=… path=…`
(logger `AuthErrorResponseWriter`)
- All authentication failing; JWKS refresh attempts failing
## Diagnosis
@@ -4,7 +4,7 @@ category: INTERNAL
error_codes: [INTERNAL_AUTH_MISCONFIGURATION]
severity: P1
owner: oncall
last_updated: 2026-06-15
last_updated: 2026-11-06
status: stub
---
@@ -13,6 +13,8 @@ status: stub
## Symptoms
- HTTP 500 with `error.code=INTERNAL_AUTH_MISCONFIGURATION`
- ERROR log line `security failure: code=INTERNAL_AUTH_MISCONFIGURATION category=INTERNAL method=… path=…`
(logger `AuthErrorResponseWriter`)
- Security filter misconfiguration detected at runtime
## Diagnosis
@@ -4,7 +4,7 @@ category: AUTH
error_codes: [AUTH_TOKEN_INVALID_SIGNATURE]
severity: P1
owner: oncall
last_updated: 2026-06-15
last_updated: 2026-11-06
status: stub
---
@@ -13,7 +13,9 @@ status: stub
## Symptoms
- HTTP 401 with `error.code=AUTH_TOKEN_INVALID_SIGNATURE`
- `log_level=ERROR` — may indicate forged tokens or wrong signing key
- WARN log line `security failure: code=AUTH_TOKEN_INVALID_SIGNATURE category=AUTH method=… path=…`
(logger `AuthErrorResponseWriter`). It is a WARN because the caller sent the token; search by
`code=`, not by level. A burst of these may indicate forged tokens or a wrong signing key
## Diagnosis
+4 -2
View File
@@ -4,7 +4,7 @@ category: AUTHZ
error_codes: [AUTHZ_TENANT_MISMATCH]
severity: P1
owner: oncall
last_updated: 2026-06-15
last_updated: 2026-11-06
status: stub
---
@@ -13,7 +13,9 @@ status: stub
## Symptoms
- HTTP 403 with `error.code=AUTHZ_TENANT_MISMATCH`
- `log_level=ERROR` — cross-tenant access attempt detected
- The template does not emit this code; the service that decides cross-tenant access does. A 403
carrier is answered without a log line (`ServerFailureLog`), so that service logs
`code=AUTHZ_TENANT_MISMATCH` where it decides, if this runbook is to find the attempt
## Diagnosis
@@ -0,0 +1,245 @@
# `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 <CODE> 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차, <https://jboss-logging.github.io/jboss-logging-tools/> | 메시지 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절 「오류 코드 로그 레벨」.
+3
View File
@@ -37,6 +37,7 @@
| 14 | 자기 테스트 코드에 `./gradlew testQualityCheck`를 돌려 보고, 발견을 고치거나 이유를 단 Match로 뺀다(B-40) | `mainCheck`가 실패 | 테스트 코드가 있는 모든 서비스 |
| 15 | staging·prod 배포 마이그레이션 도구에 `flyway.postgresql.transactional.lock=false`(환경 변수 `FLYWAY_POSTGRESQL_TRANSACTIONAL_LOCK=false`)를 넣는다. 자기 Flyway stream은 `Flyway.configure()` 대신 `FlywaySchemaPolicy.configure()`로 만든다(5절 「Flyway 잠금」) | `CREATE INDEX CONCURRENTLY`·`REINDEX … CONCURRENTLY` 마이그레이션에서 배포가 오류 없이 멈춘다. 자기 stream이 `Flyway.configure()`를 부르면 `:app-bootstrap:architectureTest` 실패 | persistence-jpa 선택 + 배포 도구로 마이그레이션하거나 자기 stream을 둔 서비스 |
| 16 | 자기 성능 lane(`performance()`)에서 `performance.assertions.enabled`를 `false`로 두는 `systemProperty` 줄을 지우고, 그 속성을 읽어 상한 단언을 건너뛰던 테스트는 항상 단언하게 고친다. 성능 lane의 `@Disabled`·assumption skip을 없앤다(B-43) | `performanceCheck`가 테스트 전에 실패(`its test JVM would get performance.assertions.enabled=false`)하거나 skip 때문에 실패(`forbids skipped tests`) | 자기 성능 lane이 있는 서비스 |
| 17 | 자기 `docs/registries/error-codes.yaml` 행에서 `log_level:` 줄을 지운다(B-44) | `mainCheck`의 `:app-bootstrap:documentContractTest`가 실패(`docs/registries/error-codes.yaml rows with a log_level; the code decides the level, not the registry`) | `error-codes.yaml`에 자기 행을 더한 서비스 |
### 되돌릴 수 없는 것
@@ -111,6 +112,7 @@
| B-40 | 테스트 코드 정적 분석 `testQualityCheck`: SpotBugs·FindSecBugs를 main 밖 모든 source set(test, testFixtures, integrationTest, systemTest 등)에 돌린다. 테스트용 제외 목록은 `config/spotbugs/exclude-test.xml`(보안 범주·내부 상태 노출·생성자 예외·반환값 null 역참조·아키텍처 위반 fixture). 분석 classpath가 그 source set의 runtime classpath로 넓어졌고, 분석이 불완전하면(빠진 클래스) 실패한다. main 빌드는 `mainCheck`(`qualificationCheck`), optional 빌드는 `ci` | 자기 테스트 코드의 SpotBugs 발견(예: `CountDownLatch.await` 반환값 무시, 공유 변수 비원자 쓰기, 닫지 않은 `Statement`)이 main 단계를 막는다. 테스트 classpath에 없는 타입을 참조하면 `SpotBugs analysis incomplete` | 고치거나, 클래스·메서드로 좁힌 Match를 이유와 함께 `exclude-test.xml`에 더한다. 빠진 타입은 그 테스트 suite 의존성에 넣는다 | `2678955c` · `src/build-logic/.../quality/QualityConventionsPlugin.java`, `src/config/spotbugs/exclude-test.xml`, `src/build.gradle` |
| B-42 | shared-contract 패키지 규칙 `SHARED_CONTRACT_CONTAINS_ONLY_OPERATIONAL_CONTRACT_PACKAGES`가 실제로 검사한다. 대상은 `dev.caskeleton.shared..`뿐이고, 허용은 목록의 패키지(`concurrency digest error metrics observability ratelimit request response retry runtime security tracing`)와 그 아래, 뿌리 패키지에는 `package-info`만이다. 전에는 뿌리를 허용 목록에 넣고 접두어로 비교해서 모듈 안은 아무것도 잡지 못했고, 다른 leaf의 `..shared..` 패키지를 잡았다 | `dev.caskeleton.shared`에 목록에 없는 패키지나 뿌리 클래스를 둔 파생 서비스는 architectureTest 실패. 다른 leaf의 `shared` 패키지는 더는 걸리지 않는다 | 업무 개념이면 그것을 소유하는 모듈로 옮긴다. 운영 계약이면 `ForbiddenApiArchitectureTest.SHARED_CONTRACT_PACKAGES`와 shared-contract CLAUDE.md 「Responsibility」에 함께 더한다 | r10 · `src/app-bootstrap/src/architectureTest/.../ForbiddenApiArchitectureTest.java`, `SharedContractPackageRuleTest.java` |
| B-43 | 성능 lane 단언 상시화: `performance()` lane은 convention이 테스트 JVM에 `performance.assertions.enabled=true`를 넣는다. 빌드가 `-P`·`GRADLE_OPTS`(`-Dorg.gradle.project.…`)로 `true` 아닌 값을 주거나, lane `systemProperty`·`jvmArgs`(`-D…`)·task 설정이 테스트 JVM 값을 `true` 아닌 값으로 덮으면 테스트 전에 실패한다. 성능 lane은 `rejectSkipped` 없이도 skip된 테스트가 있으면 실패한다. httpclient·Mongo leaf의 속성 선언과 `integration-main.yml` `performance-check`·`release.yml` `httpclient-release-gate`의 `GRADLE_OPTS` 줄을 지웠다. 측정만 하는 모드는 만들지 않았다(JMH가 그 용도) | `performanceCheck`·`:<leaf>:performanceTestLaneCheck`가 `is a performance lane, and this build sets performance.assertions.enabled=false`, `its test JVM would get performance.assertions.enabled=false`, `forbids skipped tests … a skipped test is a bound nobody measured` 중 하나로 실패 | `-Pperformance.assertions.enabled=false`를 지운다. 자기 lane의 그 `systemProperty`·`jvmArgs` 줄을 지우고, 그 속성을 읽던 테스트는 항상 단언하게 고친다. 성능 lane의 skip은 없애거나 그 테스트를 다른 lane으로 옮긴다. `GRADLE_OPTS=-Dorg.gradle.project.performance.assertions.enabled=true`·`-P…=true`는 받아 주므로 그대로 둬도 된다 | B4(2026-11-06) · `src/build-logic/.../strictlane/StrictTestLanePlugin.java`, `.../strictlane/StrictTestLaneConventionTest.java`(test), `docs/testing/TESTING_STRATEGY.md` 6절 |
| B-44 | `docs/registries/error-codes.yaml`에서 `log_level` 칸을 지웠다. 행에 `log_level`이 있으면 `OperationalErrorRegistryContractTest.noRegistryRowCarriesALogLevel`(태그 `document-contract`, `mainCheck`)이 실패한다. 칸을 읽는 코드는 없었고 값 대부분이 실제 로그 레벨과 달랐다. 레벨은 실패 종류·경로가 정한다(`ServerFailureLog`, 보안 필터 `AuthErrorResponseWriter`) | 자기 행에 `log_level`이 남은 서비스는 `mainCheck` 실패(`… rows with a log_level; the code decides the level, not the registry`와 그 행의 code 목록) | 자기 행에서 `log_level:` 줄을 지운다. 레벨을 바꾸려면 그 실패를 로그로 남기는 코드를 고친다. 자기 설계서가 "행마다 `log_level`을 채운다"고 적었으면 그 문장도 지운다 | 설계 메모 2026-11-06 7절 결정 1·1-b · `docs/registries/error-codes.yaml` 머리말, `src/app-bootstrap/src/test/.../contract/OperationalErrorRegistryContractTest.java` |
### 3.5 모듈 registry·새 leaf
@@ -243,6 +245,7 @@ V21 실패의 분류는 `docs/runbooks/migration-failed.md` "Classify the failur
| sample-portfolio | 익명 쓰기 401, 포스터 제목 대소문자 무시 유일(409 `POSTER_ALREADY_EXISTS`), 관리자도 남의 work log 수정 불가, 샘플 이벤트 tenant `global` | sample을 남긴 서비스만 | `34565130`, `1400dc15` |
| Flyway 잠금 | Flyway의 PostgreSQL 마이그레이션 잠금을 트랜잭션 대신 세션에 둔다. Spring Boot의 Flyway는 module-defaults `spring.flyway.postgresql.transactional-lock: false`, 템플릿이 직접 만드는 Flyway(멱등성·알림·sample stream, schema-per-tenant, testkit `MigrationContractRunner`)는 `FlywaySchemaPolicy.configure()`, messaging inbox stream은 같은 값을 직접 넣는다. 운영 코드의 `Flyway.configure()` 직접 호출은 `JpaProductionArchitectureTest`가 거부한다 | Flyway 기본값에서는 동시 인덱스 마이그레이션이 Flyway 자신의 열린 트랜잭션을 기다려 끝나지 않았다. 이제 끝난다. 마이그레이션은 잠금을 잡은 연결 하나로 돈다. transaction 모드 PgBouncer 뒤에서는 잠금 해제가 다른 서버 연결로 가 다음 배포가 기다릴 수 있으니 마이그레이션은 직접 연결이나 session 모드 pool로 돌린다. 배포 도구는 이 repo 밖이라 2절 15번으로 맞춘다 | 재리뷰 round6 RR6-03-01 · `persistence-jpa.yml`, `.../migration/FlywaySchemaPolicy.java`, `docs/jpa/migration-guide.md` "Who may change the schema"·"Concurrent index builds" |
| 성능 lane(HTTP client·Mongo) | httpclient `LargeBodyResourceTest`의 힙 상한(32 MiB 스트리밍 중 힙 증가 16 MiB 미만)을 매번 단언한다. 전에는 `-Pperformance.assertions.enabled=true`일 때만 단언하고 아니면 건너뛴다는 줄만 찍었다. Mongo `MongoResourceBudgetLaneTest`는 표준 gate 전체(p99 500ms, pool 대기 250ms, 힙 512 MiB, examined/returned 10, spill 금지)를 Gradle 밖 실행에서도 단언한다(B-43) | 손으로 돌린 `performanceCheck`가 상한을 실제로 재므로, 전에는 통과하던 느린 기계에서 실패할 수 있다 | B4(2026-11-06) · `LargeBodyResourceTest`, `MongoResourceBudgetLaneTest` |
| 보안 필터 로그 레벨 | 보안 필터(`AuthErrorResponseWriter`)의 `security failure` 줄을 5xx(`AUTH_JWKS_UNAVAILABLE` 503, `INTERNAL_AUTH_MISCONFIGURATION` 500)면 ERROR, 4xx면 WARN으로 남긴다. 전에는 모두 WARN이었다. 다른 경로가 5xx를 ERROR로 남기는 규칙(`ServerFailureLog`)과 같아졌다 | ERROR로 거르는 로그 경보·대시보드에 JWKS 장애와 인증 설정 오류가 새로 잡힌다. 401·403은 그대로 WARN | 설계 메모 2026-11-06 7절 결정 2 · `src/adapter/inbound/web/.../auth/AuthErrorResponseWriter.java`, `docs/superpowers/specs/2026-11-06-error-code-log-level-design.md` |
## 6. 따라오는 순서
+1
View File
@@ -81,6 +81,7 @@
| GraphQL DataLoader 키 실패 | 등록된 `ApiErrorCode`만 노출 | 소유자 | 결정 25 |
| Draft-12 offset 불일치 | problem 문서는 프로토콜 예외로 유지 | 소유자 | 결정 12 |
| 알림 category 생략 | 거부(400), 판정은 유스케이스 | 소유자 | 결정 13 |
| 오류 코드 로그 레벨 | `error-codes.yaml`에 `log_level` 칸을 두지 않는다. 레벨은 실패 종류·경로가 정한다(`ServerFailureLog`, 보안 필터 `AuthErrorResponseWriter`). 칸이 다시 생기면 `OperationalErrorRegistryContractTest`가 실패한다. 보안 필터는 5xx(`AUTH_JWKS_UNAVAILABLE`·`INTERNAL_AUTH_MISCONFIGURATION`)를 ERROR, 4xx를 WARN으로 남긴다. 401 서명·issuer·audience 불일치는 WARN | 소유자 | 2026-11-06, `docs/superpowers/specs/2026-11-06-error-code-log-level-design.md` 10절 |
### 2.4 멱등성
+4
View File
@@ -115,6 +115,10 @@ commit-aware response wrapper 계약을 구현한다. 또한 이 모듈은 HTML
코드의 일반 `client_safe_message` 만 담고, 원시 예외 텍스트·`Authorization` 헤더·issuer·audience 는
절대 포함하지 않는다. 로그 라인엔 code/category/요청 path 만 기록하고 bearer token 은 절대 로깅하지
않는다(leak 테스트가 강제하는 계약). 전체 로그 마스킹 필터는 별도 log-management 영역에서 다룬다.
- **로그 레벨.** 4xx(토큰 누락·만료·서명·issuer·audience·kid 실패, 권한 부족)는 호출자 쪽 실패라 WARN이다.
5xx(`AUTH_JWKS_UNAVAILABLE` 503, `INTERNAL_AUTH_MISCONFIGURATION` 500)는 서버 쪽 고장이라 ERROR다. 다른
경로가 5xx를 ERROR로 남기는 규칙(shared-contract `ServerFailureLog`)과 같다. 레벨은 오류 코드 레지스트리의
칸이 아니라 이 코드가 정한다(설계 메모 `docs/superpowers/specs/2026-11-06-error-code-log-level-design.md`).
- **WWW-Authenticate(RFC 9110 §15.5.2).** 401 응답은 반드시 WWW-Authenticate 헤더를 갖되, `error_description`
으로 issuer/token 세부가 새지 않도록 최소한으로 유지한다.
@@ -8,6 +8,7 @@ import jakarta.servlet.http.HttpServletResponse;
import java.io.IOException;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.slf4j.event.Level;
import org.springframework.http.HttpHeaders;
import tools.jackson.databind.ObjectMapper;
@@ -28,13 +29,16 @@ class AuthErrorResponseWriter {
void write(HttpServletRequest request, HttpServletResponse response, OperationalError code)
throws IOException {
// Log only safe metadata — never the token or the raw failure message.
log.warn(
"security failure: code={} category={} method={} path={}",
code.code(),
code.category(),
request.getMethod(),
request.getRequestURI());
// Log only safe metadata — never the token or the raw failure message. A 5xx is the server's
// own failure (the key service is down, the decoder is misconfigured) and is an ERROR, as a 5xx
// is on every other path (ServerFailureLog); a 4xx is the caller's and stays a WARN.
log.atLevel(code.httpStatus() >= 500 ? Level.ERROR : Level.WARN)
.log(
"security failure: code={} category={} method={} path={}",
code.code(),
code.category(),
request.getMethod(),
request.getRequestURI());
// A 401 response carries a minimal WWW-Authenticate header (no issuer / token detail).
if (code.httpStatus() == 401) {
@@ -2,17 +2,23 @@ package dev.caskeleton.adapter.inbound.web.auth;
import static org.assertj.core.api.Assertions.assertThat;
import ch.qos.logback.classic.Logger;
import ch.qos.logback.classic.spi.ILoggingEvent;
import ch.qos.logback.core.read.ListAppender;
import dev.caskeleton.shared.error.Category;
import dev.caskeleton.shared.error.ClientErrorMessages;
import java.io.IOException;
import java.util.List;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.slf4j.LoggerFactory;
import org.springframework.boot.test.system.CapturedOutput;
import org.springframework.boot.test.system.OutputCaptureExtension;
import org.springframework.http.HttpHeaders;
import org.springframework.mock.web.MockHttpServletRequest;
import org.springframework.mock.web.MockHttpServletResponse;
import org.springframework.security.authentication.InsufficientAuthenticationException;
import org.springframework.security.core.AuthenticationException;
import org.springframework.security.oauth2.core.OAuth2Error;
import org.springframework.security.oauth2.core.OAuth2ErrorCodes;
import org.springframework.security.oauth2.jwt.BadJwtException;
@@ -106,6 +112,86 @@ class EnvelopeAuthenticationEntryPointTest {
.isEqualTo("AUTH_JWKS_UNAVAILABLE");
}
@Test
void aKeyServiceOutageIsLoggedAtError() throws Exception {
// given
AuthenticationException outage =
new InvalidBearerTokenException(
"invalid",
new JwtDecoderConfig.AuthenticationKeyServiceUnavailableException(
new IOException("connect timed out")));
// when
List<ILoggingEvent> lines = writerLinesFor(outage);
// then
assertThat(lines)
.singleElement()
.extracting(event -> event.getLevel().toString(), ILoggingEvent::getFormattedMessage)
.containsExactly(
"ERROR",
"security failure: code=AUTH_JWKS_UNAVAILABLE category=TRANSIENT_DEPENDENCY"
+ " method=GET path=/v1/things");
}
@Test
void aDecoderMisconfigurationIsLoggedAtError() throws Exception {
// given
AuthenticationException misconfiguration =
new InvalidBearerTokenException(
"invalid",
new JwtDecoderConfig.AuthenticationDecoderMisconfigurationException(
new IllegalStateException("issuer metadata does not match")));
// when
List<ILoggingEvent> lines = writerLinesFor(misconfiguration);
// then
assertThat(lines)
.singleElement()
.extracting(event -> event.getLevel().toString(), ILoggingEvent::getFormattedMessage)
.containsExactly(
"ERROR",
"security failure: code=INTERNAL_AUTH_MISCONFIGURATION category=INTERNAL"
+ " method=GET path=/v1/things");
}
@Test
void aRejectedSignatureStaysAtWarn() throws Exception {
// given
AuthenticationException rejected =
new InvalidBearerTokenException(
"invalid", new BadJwtException("Signed JWT rejected: Invalid signature"));
// when
List<ILoggingEvent> lines = writerLinesFor(rejected);
// then
assertThat(lines)
.singleElement()
.extracting(event -> event.getLevel().toString(), ILoggingEvent::getFormattedMessage)
.containsExactly(
"WARN",
"security failure: code=AUTH_TOKEN_INVALID_SIGNATURE category=AUTH"
+ " method=GET path=/v1/things");
}
/** The lines the security writer logs while the entry point answers {@code failure}. */
private List<ILoggingEvent> writerLinesFor(AuthenticationException failure) throws Exception {
Logger logger = (Logger) LoggerFactory.getLogger(AuthErrorResponseWriter.class);
ListAppender<ILoggingEvent> appender = new ListAppender<>();
appender.start();
logger.addAppender(appender);
try {
entryPoint.commence(
new MockHttpServletRequest("GET", "/v1/things"), new MockHttpServletResponse(), failure);
} finally {
logger.detachAppender(appender);
appender.stop();
}
return appender.list;
}
@Test
void tokenValueNeverLeaksIntoResponseBodyOrLogs(CapturedOutput output) throws Exception {
// §테스트 계약: a JWT value must never appear in the response or the log output.
@@ -98,6 +98,25 @@ class OperationalErrorRegistryContractTest {
assertThat(actual).isNotEmpty().isEqualTo(expected);
}
/**
* The log level is not a registry column. The failure's kind and path decide it — {@code
* ServerFailureLog} on every transport, {@code AuthErrorResponseWriter} in the security filter —
* not the code, so a per-row value can only drift from what is logged, as the column that was
* removed did (docs/superpowers/specs/2026-11-06-error-code-log-level-design.md).
*/
@Test
void noRegistryRowCarriesALogLevel() {
List<String> rowsWithALogLevel =
registryRows().stream()
.filter(row -> row.containsKey("log_level"))
.map(row -> String.valueOf(row.get("code")))
.toList();
assertThat(rowsWithALogLevel)
.as("%s rows with a log_level; the code decides the level, not the registry", REGISTRY)
.isEmpty();
}
@SuppressWarnings("unchecked")
private static List<Map<String, Object>> registryRows() {
Object loaded = new Yaml(new SafeConstructor(new LoaderOptions())).load(read(REGISTRY));