fix(error-codes)!: 레지스트리에서 log_level 칸을 지운다

문제: docs/registries/error-codes.yaml의 log_level 칸은 읽는 코드가 없다.
로그 레벨은 오류 코드가 아니라 실패의 종류와 경로가 정한다
(ServerFailureLog, AuthErrorResponseWriter). 그래서 그 코드를 내는 곳이 있는
47행 중 33행이 실제 레벨과 달랐고, 런북 2곳이 틀린 레벨을 증상으로 적었다.

고른 방법: 칸을 지우고, 머리말이 레벨을 정하는 코드를 가리킨다(설계 메모 안
A, 소유자 결정 2026-11-06). 칸이 다시 생기지 않게
OperationalErrorRegistryContractTest에 단언을 둔다. client_safe_message를
코드에 고정한 테스트가 있는 자리다. 모든 레지스트리의 공통 스키마를 보는
ContractRegistrySchemaGovernanceTest는 한 레지스트리의 칸 뜻을 다루지 않아
고르지 않았다. 런북은 실제 로그 줄을 증상으로 적는다. 결정 색인 2.3절과
설계 메모 10절에 결정을 남겼다.
버린 대안: 칸을 코드에 맞추고 테스트로 고정(B) — 규칙의 손 사본이 생기고,
템플릿이 내지 않는 13행은 고정할 값이 없다. 칸을 규범으로 만들어 코드가
읽기(C) — 4xx를 남기지 않는 설계를 뒤집고 로그 양이 는다.

위험·한계: 자기 error-codes.yaml 행에 log_level을 둔 파생 서비스는 merge
뒤 mainCheck(documentContractTest)가 실패한다. upgrade 안내 「반드시 할 일」
17과 B-44에 적었다. repo 밖에서 이 칸을 읽는 도구는 없는 것으로 본다(소유자
결정 4).

검증(desktop, 공유 잠금, 로그는 desktop ~/t3-loglevel-logs/):
- RED: 기준 yaml로 OperationalErrorRegistryContractTest 3건 중
  noRegistryRowCarriesALogLevel 1건 실패(log_level이 있는 행 목록 출력).
  rc=1, red-registry.log
- GREEN: :app-bootstrap:documentContractTest rc=0, 66건 실패 0
  (RunbookCoverageContractTest 포함). green-doc-contract.log
- :app-bootstrap:testQualityCheck :app-bootstrap:spotlessCheck rc=0.
  green-quality.log
- python3 scripts/check-work-docs.py rc=0, --links docs 깨진 링크 0

BREAKING CHANGE: error-codes.yaml 행에 log_level이 있으면
OperationalErrorRegistryContractTest가 실패한다. 파생 서비스는 자기 행에서
log_level: 줄을 지운다. 레벨을 바꾸려면 그 실패를 로그로 남기는 코드를 고친다.
This commit is contained in:
DongHyeonka
2026-11-06 22:17:13 +09:00
parent 7ce83b73d9
commit e0beeca214
7 changed files with 53 additions and 67 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
@@ -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
@@ -1,6 +1,6 @@
# `error-codes.yaml`의 `log_level` 칸 — 설계 메모
- 상태: **소유자 결정 대기** (2026-11-06). 결정할 것은 7절이다.
- 상태: **확정** (2026-11-06, 소유자 답 "권하는 안대로"). 결정은 10절이다. 아래 1~9절은 결정 전에 쓴 그대로 둔다.
- 기준 커밋: `06f520e6` (`refactor/maturity-review-2026-11`)
- 크기: 중간(brief). 이 메모가 고르는 안을 실제로 적용하는 일은 **큼**이다. 오류 코드 레지스트리는 공개 계약이라
파일 하나여도 큼이다(`docs/work/README.md` 2절). 그래서 이 메모는 대안 비교까지 하고 멈춘다. 코드와 yaml은
@@ -229,3 +229,17 @@
- `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절 「오류 코드 로그 레벨」.
+2
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
+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 멱등성
@@ -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));