Design: feature-operational-error-observability-foundation 보강 + template 구조 정합

날짜: 2026-06-01
대상 문서: raw/branch-notes/feature-operational-error-observability-foundation.md
부모 SSOT: raw/project-notes/ca-skeleton-operational-contract.md
목적: (1) branch-note 를 templates/branch-note-template.md 표준 구조로 정합, (2) 다관점 브레인스토밍으로 식별한 사각(F1~F8) 반영, (3) 보강 근거를 공식 문서 raw 로 캡처 후 Supporting Claim 연결. 4개 선행 계약(skeleton-package-blueprint / architecture-enforcement / boundary-validation-mapping / resource-identifier) 의 결정과 충돌 금지.

0. 충돌 안전성 원칙 (최상위 제약)

본 작업의 모든 편집은 다음 계약의 결정을 흔들지 않는다:

feature-skeleton-package-blueprint-contract — module/package blueprint, shared-contract operational-only.
feature-architecture-enforcement-rules — ArchUnit/Gradle 경계 강제.
feature-boundary-validation-mapping-contract — envelope custom 채택, MAPPING_FAILED/BATCH_PARTIAL_FAILURE 를 §6 VALIDATION 으로 등록.
feature-resource-identifier-contract — ULID, MDC snake_case 정합, never-reuse 패턴.

검증: §6 재정합은 boundary 가 consume 하는 VALIDATION/MAPPING_FAILED/BATCH_PARTIAL_FAILURE 를 보존. 신규 사각은 모두 additive 이거나 sibling/owner branch 로 위임(cross-cite).

1. 식별된 사각 (브레인스토밍 결과)

ID	사각	분류	근거
F1	부모 §6 error category 13-목록이 stale — branch/§21/§25 의 10-enum 과 불일치, orphan code 미재태그	P0 SSOT 정합	§21 L810/L814, §25 L1065
F2	snake(MDC)↔camel(envelope)↔kebab(header) 매핑이 branch-note 에 미명시	P1 과소기술	§21 L829/L839, §25 L1087
F3	retryable→`Retry-After`/`X-RateLimit-*` surfacing 계약 부재	P1 과소기술	RFC9110-C21/C6, headers.yaml
F4	inbound 헤더 유래 MDC 값 log injection/CRLF sanitization 결정 부재	P2 진짜 사각	CWE-117, OWASP Logging
F5	client 제공 traceparent/X-Request-Id 의 trust boundary 결정 부재	P2 진짜 사각	W3C-TC-C2/C5
F6	operational error 의 trace span 기록 규약(OTel exception/status) 부재	P2 진짜 사각	OTel Exceptions semconv
F7	error code lifecycle(stability/never-reuse/deprecation) 정책 부재	P2 진짜 사각	STRIPE-C2, GOOG-ERR-C4, resource-id D15 대칭
F8	AUTH→401 에 WWW-Authenticate MUST 미명시	P2 minor	RFC 9110 §11.6.1 (owner=security-baseline)

2. Template 구조 정합 (section-by-section)

표준 순서: Parent → 목표/WHY → 범위 → Sources → TODO → 진행 중 메모 → 결정 사항 → Decision Evidence Map → 구현 가이드 → Claims To Verify → 마주친 문제 → Cluster → Daily notes → Closure.

조치:

frontmatter parent_branch: (빈 값) 추가.
Parent §에 형제 branch cross-cite 추가(boundary / resource-identifier / api-contract-baseline / log-management / security-operational-baseline / metrics-alerting / distributed-tracing / rate-limit-idempotency).
맨 앞 ## Cluster → 문서 끝으로 이동 + Sub-branches/Errors/Interview prep/Lectures/Blog topics subsection 정비.
Sources → 범위 다음으로 이동.
독립 섹션 error.category Enum·MDC Key Standard·error.details JSON shape → ## 구현 가이드 / Implementation Specification 의 sub-section 으로 흡수 + 각 sub-section 에 Trace(Decision ID + Claim ID) / UNSUPPORTED_IMPL_DECISION 3-rule 헤더 부착.
## Work Item Contract (generic boilerplate) → 제거 (Decision Evidence Map + 구현 가이드 등가 대체).
판정 기준·테스트 계약·SSOT Ownership·외부 근거/대안 조사 → 유지(보조), template 흐름에 맞춰 위치 정렬. 테스트 계약=실패 조건 카탈로그 / Claims To Verify=검증 미완 주장으로 역할 분담.
## 관련 일일 노트 추가(현재 없음 표기).

3. 사각 → 결정 배치

신규 결정(기존 D1~~D12 유지, D13~~D19 추가):

D13 (F3 Retry-After surfacing) — RFC9110-C21,RFC9110-C6; 429 specifics→rate-limit-idempotency cross-cite.
D14 (F4 log injection sanitization) — owasp-logging-cheat-sheet#OWASP-LOG-Cx + CWE-117.
D15 (F5 trace trust boundary) — W3C-TC-C2,W3C-TC-C5; trust/regenerate detail→distributed-tracing/security cross-cite (UNSUPPORTED_IMPL).
D16 (F6 OTel span exception 기록) — otel-exceptions-semconv#OTEL-EXC-Cx; span detail→distributed-tracing cross-cite.
D17 (F7 error code lifecycle never-reuse) — project-decision + STRIPE-C2 + GOOG-ERR-C4; resource-id D15 대칭; deprecation→api-compatibility cross-cite (UNSUPPORTED_DECISION).
D18 (F8 401 WWW-Authenticate) — security-baseline owner cross-cite (신규 claim 없음).
D19 (F2 ID 명명 3중 매핑) — project-ssot(§21 L829/L839, §25 L1087).

각 결정은 Decision Evidence Map 행 + 구현 가이드 sub-section + Claims To Verify 행으로 전개.

4. 공식 문서 raw 캡처

신규 2건 (wiki-source-summarizer):

raw/official-docs/owasp-logging-cheat-sheet.md (F4) — log injection/CRLF neutralization, 구조화 로깅.
raw/official-docs/otel-exceptions-semantic-conventions.md (F6) — exception.type/message/stacktrace, span status ERROR.

재사용 (기존 raw):

rfc9110-http-semantics.md (RFC9110-C21/C6) — F3.
tracing-w3c-trace-context-spec.md (W3C-TC-C2/C5) — F5.
stripe-resource-id-convention.md (STRIPE-C2) + google-api-error-format.md (GOOG-ERR-C4) + stripe-error-format.md — F7.

5. 부모 project-note §6/§8 정합 (F1)

§6: 13-목록 → 10-enum 통일(이미 §21 L814 결정), orphan code re-tag(DB_*→TRANSIENT_DEPENDENCY/INTERNAL, CACHE_UNAVAILABLE→TRANSIENT_DEPENDENCY, NOTIFICATION_SEND_FAILED→TRANSIENT_DEPENDENCY, MESSAGE_PUBLISH_FAILED→TRANSIENT_DEPENDENCY, DATA_INTEGRITY_VIOLATION→DATA_INTEGRITY 등 — 실제 매핑은 error-codes.yaml 와 cross-check). VALIDATION/MAPPING_FAILED/BATCH_PARTIAL_FAILURE 보존.
§8: log field 명명을 mdc-keys.yaml snake_case 와 정합 — snake(MDC)↔camel(envelope) seam 1줄 명시.

6. 실행 순서

spec (본 문서). 2. 공식문서 캡처 2건(병렬). 3. branch-note 구조 정합 + D13~D19 반영. 4. 부모 §6/§8 정합. 5. wiki-link-verifier 검증.

7. 비목표 (YAGNI)

tenant 모델 구현(→feature-tenant-context-policy).
실제 error-codes.yaml/mdc-keys.yaml row 편집(→registry-governance, ca-tmpl repo).
distributed-tracing/security/rate-limit branch 의 owner 결정 작성(cross-cite 만).

6.6 KiB Raw Permalink Blame History