# 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. 실행 순서

1. 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 만).