docs(keycloak-session-store): import the session-storage lab as a new project

The keycloak project ended with four open questions that design could not settle. A two-VM lab was built to answer them by measurement, and this is that material: 26 experiments, 125 raw command outputs, 22 browser captures. Follows the import procedure in README.md. source/ the originating repository verbatim — 78 documents, 28 SVGs, 8 manifests, plus .source-revision recording the commit final/ the SSOT document.md 729 lines written from the 29 experiment documents, not concatenated: what was predicted, what was measured, and where the measurement itself was wrong evidence/raw 125 outputs, flattened to <experiment>__<file> because the originals collided (01-baseline.txt appeared three times) and the audit only globs the top level evidence/meta one per raw file; command and exitCode are null and the README says why rather than inventing them evidence/browser 22 captures assets/ three diagrams through techviz .techviz/ their VizSpecs A separate project rather than an addition to keycloak: the B-layer answers that project's four questions, but the A, C and D layers are about cluster failure, SSO and operations, and one document.md should hold one subject. The four question records there can point here through 관계. Recorded rather than papered over: only three of the 28 diagrams were remade. The repository forbids hand-drawn SVG and forbids titles inside the canvas; all 28 originals carry both, so converting them is redrawing, not reformatting. They stay in source/ and the gap is written into the document. verify-pipeline.py passes. audit-records.py reports no issues. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-04 22:51:59 +09:00
parent 43bccd08a8
commit b2963105a8
5017 changed files with 372751 additions and 4943 deletions
@@ -0,0 +1,46 @@
+---
+kind: CONCEPT
+slug: adapter-inbound-web-c15
+title: 상관 식별자를 만드는 필터가 세 벌이다
+topic: observability-models
+project: clean-architecture-backend-template
+status: 게시 전
+sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
+rootTreeNode: concept:adapter-inbound-web-c15
+evidenceCapturedOn: 2026-09-01
+assets:
+  - key: adapter-inbound-web-c15
+    file: ../../../final/evidence/rendered/adapter-inbound-web-c15.svg
+evidence:
+  - ../../../final/evidence/raw/adapter-inbound-web-c15.txt
+source:
+  - 원본 분석 절은 analysis/14-adapter-inbound-web.md#L1108 이다.
+module: adapter-inbound-web
+---
+
+# 상관 식별자를 만드는 필터가 세 벌이다
+
+`WebMvcRequestIdFilter`·`RequestLoggingFilter`·`WebFluxRequestContextFilter` 셋이 상관 식별자를 각각 만든다. 세 번째는 전송이 달라 공존이 정상이고, 앞의 둘은 같은 서블릿 체인에서 같은 헤더를 두 번 처리한다.
+
+## 본문
+
+<!-- body:start -->
+
+상관 식별자를 만드는 메커니즘이 셋이다.
+
+| 메커니즘 | 헤더 | 저장 위치 |
+|---|---|---|
+| `WebMvcRequestIdFilter` | `X-Request-Id`, `traceparent` | 요청 속성(`WebRequestId`/`WebTraceId`) |
+| `RequestLoggingFilter` | `X-Request-Id`, `X-Correlation-Id`, `traceparent` | MDC |
+| `WebFluxRequestContextFilter` | `X-Request-Id`, `traceparent` | Reactor context |
+
+## RequestLoggingFilter 참조 위치
+
+:::evidence key="adapter-inbound-web-c15" alt="코드베이스에서 RequestLoggingFilter 를 검색한 출력 22줄. 이 기록이 세는 참조가 그 출력에 그대로 보인다." caption="RequestLoggingFilter 코드베이스 검색 — 22줄 · exit 0" zoom="true"
+:::
+
+## 서블릿 체인에서 같은 헤더가 두 번 처리된다
+
+세 번째는 전송이 달라 공존이 정상이다. 앞의 둘은 같은 서블릿 체인에서 같은 헤더를 두 번 처리한다. `traceparent`도 마찬가지로 두 번 파싱되며, `RequestLoggingFilter`는 응답에도 `traceparent`를 쓰고(`:68`) `WebMvcRequestIdFilter`는 쓰지 않는다.
+
+<!-- body:end -->
@@ -0,0 +1,40 @@
+---
+kind: CONCEPT
+slug: adapter-outbound-persistence-jpa-c44
+title: manual audit 경로만 조립되고 Spring Data auditing은 dormant다
+topic: observability-models
+project: clean-architecture-backend-template
+status: 게시 전
+sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
+rootTreeNode: concept:adapter-outbound-persistence-jpa-c44
+evidenceCapturedOn: 2026-09-01
+assets:
+  - key: adapter-outbound-persistence-jpa-c44
+    file: ../../../final/evidence/rendered/adapter-outbound-persistence-jpa-c44.svg
+evidence:
+  - ../../../final/evidence/raw/adapter-outbound-persistence-jpa-c44.txt
+source:
+  - 원본 분석 절은 analysis/05-adapter-outbound-persistence-jpa.md#L3123 이다.
+module: adapter-outbound-persistence-jpa
+---
+
+# manual audit 경로만 조립되고 Spring Data auditing은 dormant다
+
+manual `AuditableEntity`/`AuditContextPort` 경로와 Spring Data `AuditMetadata`/`JpaAuditingConfiguration`이 함께 존재한다. tests/docs가 후자를 candidate/dormant로 명시하고 default composition도 canonical manual audit 경로만 사용한다.
+
+## 본문
+
+<!-- body:start -->
+
+manual `AuditableEntity`/`AuditContextPort` 경로와 Spring Data `AuditMetadata`/`JpaAuditingConfiguration`이 함께 존재한다.
+
+## 중복 활성화로 판정하지 않은 이유
+
+tests/docs가 후자를 candidate/dormant로 명시하고 default composition도 canonical manual audit 경로만 사용한다. 현재 중복 활성화 defect로 판정하지 않는다.
+
+## AuditableEntity 참조 위치
+
+:::evidence key="adapter-outbound-persistence-jpa-c44" alt="코드베이스에서 AuditableEntity 를 검색한 출력 27줄. 이 기록이 세는 참조가 그 출력에 그대로 보인다." caption="AuditableEntity 코드베이스 검색 — 27줄 · exit 0" zoom="true"
+:::
+
+<!-- body:end -->
@@ -0,0 +1,57 @@
+---
+kind: CONCEPT
+slug: adapter-outbound-support-c02
+title: FailOpenDependencyLogger는 실패 정책을 정하지 않는다
+topic: observability-models
+project: clean-architecture-backend-template
+status: 게시 전
+sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
+rootTreeNode: concept:adapter-outbound-support-c02
+evidenceCapturedOn: 2026-09-01
+assets:
+  - key: adapter-outbound-support-c02
+    file: ../../../final/evidence/rendered/adapter-outbound-support-c02.svg
+  - key: adapter-outbound-support-c02-diagram
+    file: ../../../final/assets/diagrams/adapter-outbound-support-c02.svg
+evidence:
+  - ../../../final/evidence/raw/adapter-outbound-support-c02.txt
+source:
+  - 원본 분석 절은 analysis/04-adapter-outbound-support.md#L119 이다.
+module: adapter-outbound-support
+---
+
+# FailOpenDependencyLogger는 실패 정책을 정하지 않는다
+
+이 logger는 retry, recovery, fallback을 수행하지 않는다. 실패 정책을 결정하는 주체가 아니라 이미 결정된 fail-open outcome을 관측하는 기술 seam이다.
+
+## 본문
+
+<!-- body:start -->
+
+`logSuccess(...)`는 DEBUG로 다음을 기록한다.
+
+- dependency_name
+- dependency_type
+- operation
+- outcome=`SUCCESS`
+- correlation_id
+
+`logFailure(...)`는 WARN으로 outcome=`FAILURE`와 error=`<exception simple class>: <cause.getMessage()>`를 추가한다. README와 javadoc은 WARN을 선택한 이유를 "optional fail-open dependency가 실패해도 core use case 자체는 성공했기 때문"이라고 설명한다.
+
+## 판정과 기록이 갈리는 자리
+
+:::evidence key="adapter-outbound-support-c02-diagram" alt="fail-open 판정에서 use case 결과와 로거로 각각 화살표가 나가고 로거에서 돌아오는 화살표는 없는 구조" caption="판정과 기록의 갈림" zoom="false"
+:::
+
+이 logger 자체는 retry, recovery, fallback을 수행하지 않는다. **실패 정책을 결정하는 주체가 아니라 이미 결정된 fail-open outcome을 관측하는 기술 seam**이다.
+
+## FailOpenDependencyLogger 참조 위치
+
+:::evidence key="adapter-outbound-support-c02" alt="코드베이스에서 FailOpenDependencyLogger 를 검색한 출력 34줄. 이 기록이 세는 참조가 그 출력에 그대로 보인다." caption="FailOpenDependencyLogger 코드베이스 검색 — 34줄 · exit 0" zoom="true"
+:::
+
+## 실제로 support를 import하는 네 파일
+
+repository-wide production reference scan에서 support package를 직접 import하는 current production files는 네 개뿐이었다 — `MessagingConfig`, `OutboundMessagePublisher`, `NotificationConfig`, `FailOpenNotificationProvider`. 반대로 support README가 "공유 consumer"로 설명하는 `cache-redis`, `httpclient`는 Gradle dependency는 유지하지만 support production type을 직접 참조하지 않는다. 이 차이는 §8에서 별도로 다룬다.
+
+<!-- body:end -->
@@ -0,0 +1,43 @@
+---
+kind: CONCEPT
+slug: adapter-outbound-support-c06
+title: 두 게이트가 증명하는 것과 증명하지 않는 것
+topic: observability-models
+project: clean-architecture-backend-template
+status: 게시 전
+sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
+rootTreeNode: concept:adapter-outbound-support-c06
+evidenceCapturedOn: 2026-09-01
+assets:
+  - key: adapter-outbound-support-c06
+    file: ../../../final/evidence/rendered/adapter-outbound-support-c06.svg
+evidence:
+  - ../../../final/evidence/raw/adapter-outbound-support-c06.txt
+source:
+  - 원본 분석 절은 analysis/04-adapter-outbound-support.md#L558 이다.
+module: adapter-outbound-support
+---
+
+# 두 게이트가 증명하는 것과 증명하지 않는 것
+
+`CleanArchitectureTest --rerun-tasks`와 `verifyCleanArchitectureDependencies`가 각각 BUILD SUCCESSFUL이다. 이 둘은 source/package/project dependency constraint를 증명하며 diagnostics runtime failure나 PII behavior를 증명하지 않는다.
+
+## 본문
+
+<!-- body:start -->
+
+두 게이트의 실행 결과다.
+
+- `CleanArchitectureTest --rerun-tasks`: BUILD SUCCESSFUL
+- `verifyCleanArchitectureDependencies`: BUILD SUCCESSFUL
+
+## 두 결과가 증명하지 않는 것
+
+이 둘은 source/package/project dependency constraint를 증명하며 diagnostics runtime failure나 PII behavior를 증명하지 않는다.
+
+## 분석 원문의 실행 기록
+
+:::evidence key="adapter-outbound-support-c06" alt="분석 문서 analysis/04-adapter-outbound-support.md 에서 이 기록의 근거 절을 그대로 잘라낸 15줄. 코드베이스를 측정한 것이 아니라 원본 판정이 무엇을 적었는지를 보여 준다." caption="analysis/04-adapter-outbound-support.md 발췌 — 15줄" zoom="true"
+:::
+
+<!-- body:end -->
@@ -0,0 +1,66 @@
+---
+kind: CONCEPT
+slug: grpc-observability-c03
+title: allowlist가 기본 거절이고 거절 목록은 메시지를 위한 것이다
+topic: observability-models
+project: clean-architecture-backend-template
+status: 게시 전
+sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
+rootTreeNode: concept:grpc-observability-c03
+evidenceCapturedOn: 2026-09-01
+assets:
+  - key: grpc-observability-c03
+    file: ../../../final/evidence/rendered/grpc-observability-c03.svg
+evidence:
+  - ../../../final/evidence/raw/grpc-observability-c03.txt
+source:
+  - 원본 분석 절은 analysis/grpc/grpc-observability.md#L74 이다.
+module: grpc-observability
+---
+
+# allowlist가 기본 거절이고 거절 목록은 메시지를 위한 것이다
+
+`violations(Map)` 의 판정 순서가 셋이고, 그중 `FORBIDDEN_TAGS` 분기는 판정을 바꾸지 않고 진단만 바꾼다. 두 번째 분기의 allowlist가 이미 그것들을 거절한다.
+
+## 본문
+
+<!-- body:start -->
+
+`violations(Map)` 의 판정 순서가 셋이다.
+
+```java
+if (FORBIDDEN_TAGS.contains(key))      → "its value space grows with traffic…"
+if (!ALLOWED_TAGS.contains(key))       → "not on the bounded allowlist [...]"
+if (UNBOUNDED_VALUE.matcher(value))    → "looks like an identifier or a credential"
+```
+
+클래스 javadoc 이 두 목록이 겹치는 이유를 적는다 — "Everything unlisted is refused anyway; naming the dangerous ones gives the refusal a message that says why rather than just that." 즉 `FORBIDDEN_TAGS` 는 판정을 바꾸지 않고 진단만 바꾼다. 두 번째 분기가 이미 그것들을 거절한다.
+
+## 허용 태그 여덟과 명시적 거절 열하나
+
+허용 태그: `grpc.service` · `grpc.method` · `grpc.rpc_type` · `grpc.status` · `grpc.channel_profile` · `grpc.completion_outcome` · `grpc.retry_bucket` · `grpc.stream_termination_reason`.
+
+명시적 거절: `actor_id` · `tenant_id` · `object_id` · `stream_id` · `idempotency_key` · `request` · `response` · `metadata` · `authorization` · `error_detail` · `trace_id`.
+
+## GrpcRpcObservation 참조 위치
+
+:::evidence key="grpc-observability-c03" alt="코드베이스에서 GrpcRpcObservation 를 검색한 출력 5줄. 이 기록이 세는 참조가 그 출력에 그대로 보인다." caption="GrpcRpcObservation 코드베이스 검색 — 5줄 · exit 0" zoom="true"
+:::
+
+## 값 검사가 잡지 못하는 것
+
+UUID · `sha256:` 접두 · `bearer ` 접두. 숫자 id, 이메일, 호스트명은 잡히지 않는다. 그리고 `.` 은 기본적으로 개행에 맞지 않으므로 값에 개행이 섞이면 `matches()` 가 거짓이 된다.
+
+## 시도 수를 값이 아니라 버킷으로 접는다
+
+`retryBucket(int)` 이 1-based 시도 수를 받아 `0`/`1`/`2`/`3+` 로 접는다. 0 이하는 던진다. javadoc 이 이유를 적는다 — "an attempt count is unbounded in principle and the distinction anyone acts on is first attempt, one retry, several."
+
+## 재시도 한 번이 호출 하나로 남는 이유
+
+`GrpcRpcObservation` javadoc 이 적는다.
+
+> "A retried call is one observation with a retry bucket, and three attempt events beneath it; recording three separate calls instead makes the success rate read as 33% when the caller in fact got its answer."
+
+그 분리가 `GrpcObservationConvention.record(GrpcRpcObservation)` 에서 실제로 그렇게 구현되어 있다 — `RPC_DURATION` 타이머는 1회, `RPC_ATTEMPTS` 카운터는 `attempts` 만큼 증가. 같은 태그 집합을 쓴다.
+
+<!-- body:end -->
@@ -0,0 +1,47 @@
+---
+kind: CONCEPT
+slug: messaging-admin-runtime-c05
+title: 실패 사유가 저널에도 감사 이벤트에도 남지 않는다
+topic: observability-models
+project: clean-architecture-backend-template
+status: 게시 전
+sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
+rootTreeNode: concept:messaging-admin-runtime-c05
+evidenceCapturedOn: 2026-09-01
+assets:
+  - key: messaging-admin-runtime-c05
+    file: ../../../final/evidence/rendered/messaging-admin-runtime-c05.svg
+evidence:
+  - ../../../final/evidence/raw/messaging-admin-runtime-c05.txt
+source:
+  - 원본 분석 절은 analysis/messaging/messaging-admin-runtime.md#L472 이다.
+module: messaging-admin-runtime
+---
+
+# 실패 사유가 저널에도 감사 이벤트에도 남지 않는다
+
+`attempt(...)` 가 모든 `RuntimeException` 을 삼키는 것은 근거가 있지만 대가도 있다. 감사 이벤트는 `failed` 개수만 담고, 어떤 메시지가 왜 실패했는지는 어디에도 기록되지 않는다.
+
+## 본문
+
+<!-- body:start -->
+
+토폴로지 불일치가 두 곳에서 각각 보고된다.
+
+| 상황 | 처리 | 위치 |
+|---|---|---|
+| 토폴로지 불일치 (A) | `MessagingConfigurationException("TOPOLOGY_MISMATCH")` | `TopologyValidationReport:78` |
+| 토폴로지 불일치 (B) | `MessageTopologyException("TOPOLOGY_MISMATCH")` | `TopologyValidationRuntime:54` |
+
+이 두 줄이 §12.3(a)의 요약이다 — 같은 코드 문자열, 다른 예외 타입, 다른 판정 규칙.
+
+## RuntimeException 을 삼키는 자리
+
+:::evidence key="messaging-admin-runtime-c05" alt="코드베이스에서 RuntimeException 를 검색한 출력 4줄. 이 기록이 세는 참조가 그 출력에 그대로 보인다." caption="RuntimeException 코드베이스 검색 — 4줄 · exit 0" zoom="true"
+:::
+
+## 삼킨 예외가 남기지 않는 것
+
+`attempt(...)` 가 모든 `RuntimeException` 을 삼키는 것은 근거가 있지만 대가도 있다: 실패 사유가 어디에도 남지 않는다. 감사 이벤트는 `failed` 개수만 담고(`:135`), 어떤 메시지가 왜 실패했는지는 기록되지 않는다.
+
+<!-- body:end -->
@@ -0,0 +1,52 @@
+---
+kind: CONCEPT
+slug: messaging-observability-c02
+title: 재료 둘만 bean으로 있고 그것을 조립하는 것이 없다
+topic: observability-models
+project: clean-architecture-backend-template
+status: 게시 전
+sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
+rootTreeNode: concept:messaging-observability-c02
+evidenceCapturedOn: 2026-09-01
+assets:
+  - key: messaging-observability-c02
+    file: ../../../final/evidence/rendered/messaging-observability-c02.svg
+evidence:
+  - ../../../final/evidence/raw/messaging-observability-c02.txt
+source:
+  - 원본 분석 절은 analysis/messaging/messaging-observability.md#L70 이다.
+module: messaging-observability
+---
+
+# 재료 둘만 bean으로 있고 그것을 조립하는 것이 없다
+
+출하 조립에서 bean으로 등록되는 것은 `MessagingRedactor`와 `CardinalityGuard` 둘이다. 둘 다 `MessagingMetrics`의 생성자 인자인데 `MessagingMetrics` bean이 없다.
+
+## 관계
+
+- **타입이 문서화한 불변식은 타입이 강제한다**
+  같은 분석 리프에서 끌어낸 규칙이다.
+
+## 본문
+
+<!-- body:start -->
+
+들어오는 것: `messaging-core-api`(api), `micrometer-core`(api). 나가는 것: `messaging-runtime-core`, `messaging-kafka`, `messaging-rabbit`, `messaging-admin-runtime`, `messaging-pulsar-experimental`, `messaging-nats-experimental`, `messaging-spring-boot-starter`.
+
+## 출하 조립이 등록하는 bean 둘
+
+| bean | 라인 | 소비 |
+|---|---:|---|
+| `MessagingRedactor` | `MessagingCoreAutoConfiguration:253` | **없음** |
+| `CardinalityGuard` | `:264` | **없음** |
+
+## MessagingMetrics 참조 위치
+
+:::evidence key="messaging-observability-c02" alt="코드베이스에서 MessagingMetrics 를 검색한 출력 16줄. 이 기록이 세는 참조가 그 출력에 그대로 보인다." caption="MessagingMetrics 코드베이스 검색 — 16줄 · exit 0" zoom="true"
+:::
+
+## 재료는 있는데 조립하는 bean이 없다
+
+두 클래스는 `MessagingMetrics`의 생성자 인자다. 그런데 `MessagingMetrics` bean이 없다(§12.1). `MessagingTracer`·`MessagingAuditSink`·`DefaultMessagingObservationConvention`은 bean도 없고 소비자도 없다.
+
+<!-- body:end -->