diff --git a/docs/registries/error-codes.yaml b/docs/registries/error-codes.yaml index d569b16b..6b29101f 100644 --- a/docs/registries/error-codes.yaml +++ b/docs/registries/error-codes.yaml @@ -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 diff --git a/docs/runbooks/auth-jwks-unavailable.md b/docs/runbooks/auth-jwks-unavailable.md index 42bcc829..b7c529e4 100644 --- a/docs/runbooks/auth-jwks-unavailable.md +++ b/docs/runbooks/auth-jwks-unavailable.md @@ -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 diff --git a/docs/runbooks/auth-public-path-misconfiguration.md b/docs/runbooks/auth-public-path-misconfiguration.md index df069a67..019a1976 100644 --- a/docs/runbooks/auth-public-path-misconfiguration.md +++ b/docs/runbooks/auth-public-path-misconfiguration.md @@ -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 diff --git a/docs/runbooks/auth-token-invalid-signature.md b/docs/runbooks/auth-token-invalid-signature.md index ce057a1f..02051f53 100644 --- a/docs/runbooks/auth-token-invalid-signature.md +++ b/docs/runbooks/auth-token-invalid-signature.md @@ -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 diff --git a/docs/runbooks/authz-tenant-mismatch.md b/docs/runbooks/authz-tenant-mismatch.md index 1bd30beb..47747cd9 100644 --- a/docs/runbooks/authz-tenant-mismatch.md +++ b/docs/runbooks/authz-tenant-mismatch.md @@ -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 diff --git a/docs/superpowers/specs/2026-11-06-error-code-log-level-design.md b/docs/superpowers/specs/2026-11-06-error-code-log-level-design.md new file mode 100644 index 00000000..4392d283 --- /dev/null +++ b/docs/superpowers/specs/2026-11-06-error-code-log-level-design.md @@ -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 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절 「오류 코드 로그 레벨」. diff --git a/docs/upgrade/2026-11-maturity-review.md b/docs/upgrade/2026-11-maturity-review.md index ef50f035..8bc96132 100644 --- a/docs/upgrade/2026-11-maturity-review.md +++ b/docs/upgrade/2026-11-maturity-review.md @@ -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`·`::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. 따라오는 순서 diff --git a/docs/work/reference/decisions.md b/docs/work/reference/decisions.md index 227e493b..c5ec382a 100644 --- a/docs/work/reference/decisions.md +++ b/docs/work/reference/decisions.md @@ -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 멱등성 diff --git a/src/adapter/inbound/web/README.md b/src/adapter/inbound/web/README.md index 7b2336ca..6383ea21 100644 --- a/src/adapter/inbound/web/README.md +++ b/src/adapter/inbound/web/README.md @@ -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 세부가 새지 않도록 최소한으로 유지한다. diff --git a/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/auth/AuthErrorResponseWriter.java b/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/auth/AuthErrorResponseWriter.java index 79068f66..7893d1ba 100644 --- a/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/auth/AuthErrorResponseWriter.java +++ b/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/auth/AuthErrorResponseWriter.java @@ -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) { diff --git a/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/auth/EnvelopeAuthenticationEntryPointTest.java b/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/auth/EnvelopeAuthenticationEntryPointTest.java index 3ad25ca3..d580043b 100644 --- a/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/auth/EnvelopeAuthenticationEntryPointTest.java +++ b/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/auth/EnvelopeAuthenticationEntryPointTest.java @@ -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 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 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 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 writerLinesFor(AuthenticationException failure) throws Exception { + Logger logger = (Logger) LoggerFactory.getLogger(AuthErrorResponseWriter.class); + ListAppender 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. diff --git a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/OperationalErrorRegistryContractTest.java b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/OperationalErrorRegistryContractTest.java index 5f561936..2e043b83 100644 --- a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/OperationalErrorRegistryContractTest.java +++ b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/OperationalErrorRegistryContractTest.java @@ -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 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> registryRows() { Object loaded = new Yaml(new SafeConstructor(new LoaderOptions())).load(read(REGISTRY));