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,103 @@
+---
+kind: CASE
+slug: the-same-rotation-defect-closed-once-and-reproduced
+title: 같은 자격 증명 회전 결함이 한 가족에서 닫히고 다른 가족에서 재현됐다
+topic: learning-transfer-between-families
+project: clean-architecture-backend-template
+status: 게시 전
+sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
+rootTreeNode: case:the-same-rotation-defect-closed-once-and-reproduced
+evidenceCapturedOn: 2026-09-01
+body: case-the-same-rotation-defect-closed-once-and-reproduced.body.md
+assets:
+  - key: the-same-rotation-defect-closed-once-and-reproduced
+    file: ../../../final/evidence/rendered/the-same-rotation-defect-closed-once-and-reproduced.svg
+evidence:
+  - ../../../final/evidence/raw/the-same-rotation-defect-closed-once-and-reproduced.txt
+  - ../../../final/evidence/raw/tl-rotation-defect-reproduced.txt
+source:
+  - 원본 분석 절은 final/document.md#5-5 · analysis/19 §5.4 · analysis/20 §7.4 이다.
+---
+
+# 같은 자격 증명 회전 결함이 한 가족에서 닫히고 다른 가족에서 재현됐다
+
+messaging 가족이 동기화 없는 읽기-갱신 회전 결함을 닫고 그 이력을 계약 테스트에 남겼다. gRPC 가족의 회전 매니저는 AtomicReference 를 평범한 홀더로 쓰며 같은 형태를 반복하고, 그 javadoc 은 경합의 존재를 이미 알고 있다.
+
+## 관계
+
+- **Atomic 타입의 존재는 원자성의 증거가 아니다**
+  이 사례가 그 규칙의 대표 형태다.
+- **레지스트리로 표현된 규칙은 전이되고 CI로 표현된 규칙은 전이되지 않는다**
+  같은 저장소 안에서 학습이 전이되지 않은 사례다.
+- **두 번째 플랫폼이 첫 번째의 bridge 부재는 막고 게이트 배선은 옮기지 않았다**
+  같은 두 가족 사이의 전이 패턴을 다룬다.
+
+## 문제
+
+messaging 가족의 자격 증명 런타임 레지스트리는 예전에 동기화 없이 읽고 가져오고 넣고 지웠다.
+
+그 결함을 계약 테스트의 javadoc 이 사후 기록으로 남긴다. 같은 자격 증명을 회전시키는 두 호출자가 둘 다 같은 옛 런타임을 읽고 둘 다 교체본을 가져왔다. 하나의 교체본이 한 번도 정리되지 않은 채 맵에서 버려졌다. 아무도 소유하지 않는 비밀이 메모리에 남은 것이다. 그리고 진 쪽이 이긴 쪽이 아직 쓰고 있는 자료를 지울 수 있었다.
+
+결함은 닫혔고 이력은 남았다.
+
+## 결론
+
+gRPC 가족의 회전 매니저가 같은 형태를 반복한다.
+
+그 클래스는 AtomicReference 를 필드로 갖는다. 그러나 원자적 갱신 연산을 한 번도 쓰지 않는다.
+
+get 으로 읽고 set 으로 쓴다
+compareAndSet 사용 0
+updateAndGet 사용 0
+synchronized 사용 0
+
+읽은 값으로 다음 상태를 만들어 쓰는 지점이 여럿이다. 상태를 관측하고 그 관측값으로 새 상태를 구성해 설정하는 형태다. 두 회전자가 동시에 들어오면 나중 쓰기가 앞선 쓰기를 덮는다.
+
+그리고 같은 파일의 javadoc 이 그 경합을 이미 이름으로 부른다. 회전자가 둘 겹치는 것이 그 상황의 통상적인 이유라고 적혀 있다.
+
+정책 리프의 테스트 열여섯 개 중 동시성을 다루는 것이 없다.
+
+두 가족이 같은 저장소 안에 있고, 앞선 결함의 이력이 코드 주석으로 남아 있는데도 전이되지 않았다.
+
+## 검증 환경
+
+OpenJDK : 21.0.12
+확인 방식 : 두 구현의 코드 비교와 연산 계수
+소스 수정 : x
+
+## 재현 조건
+
+원문은 final/evidence/raw/tl-rotation-defect-reproduced.txt 에 있다.
+
+1. messaging 자격 증명 계약 테스트의 javadoc 에서 닫힌 결함의 서술을 읽는다.
+2. gRPC 회전 매니저에서 AtomicReference 의 사용 지점을 열거한다.
+3. 같은 파일에서 compareAndSet 과 updateAndGet 과 synchronized 를 센다. 셋 다 0 이다.
+4. 그 파일의 javadoc 에서 경합을 언급하는 문장을 찾는다.
+5. 정책 리프의 테스트 중 동시성을 다루는 것을 센다.
+
+## 본문
+
+<!-- body:start -->
+
+messaging이 get → fetch → put → clear를 동기화 없이 하던 결함을 닫고 이력을 계약 테스트 javadoc에 남겼다 — "one replacement was dropped from the map without ever being cleared — a secret left in memory that nothing owns."
+
+## messaging 이 닫고 남긴 이력
+
+:::evidence key="the-same-rotation-defect-closed-once-and-reproduced" alt="분석 문서 final/document.md 에서 이 기록의 근거 절을 그대로 잘라낸 18줄. 코드베이스를 측정한 것이 아니라 원본 판정이 무엇을 적었는지를 보여 준다." caption="final/document.md 발췌 — 18줄" zoom="true"
+:::
+
+## gRPC 쪽은 CAS 를 한 번도 쓰지 않는다
+
+회전 매니저는 `AtomicReference`를 쓰면서 `compareAndSet`을 한 번도 쓰지 않고 `get()`→`set()`으로만 다룬다(`synchronized`도 0). javadoc이 그 경합의 존재를 이미 알고 있다 — "the usual reason for one is two rotators racing".
+
+## 테스트 열여섯 중 동시성을 다루는 것이 없다
+
+`grpc-policy` 쪽이다.
+
+## 확인하지 못한 것
+
+경합을 재현하는 동시성 테스트를 작성하지 않았다. 이 기록은 코드 형태와 앞선 사례의 대조에 근거한다.
+
+gRPC 블록은 어떤 배포에도 포함되지 않으므로 이 경합이 프로덕션에서 일어날 수 있는 상태는 아니다.
+
+<!-- body:end -->
@@ -0,0 +1,100 @@
+---
+kind: CASE
+slug: the-second-platform-carried-the-design-not-the-wiring
+title: 두 번째 플랫폼이 첫 번째의 bridge 부재는 막고 게이트 배선은 옮기지 않았다
+topic: learning-transfer-between-families
+project: clean-architecture-backend-template
+status: 게시 전
+sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
+rootTreeNode: case:the-second-platform-carried-the-design-not-the-wiring
+evidenceCapturedOn: 2026-09-01
+assets:
+  - key: the-second-platform-carried-the-design-not-the-wiring
+    file: ../../../final/evidence/rendered/the-second-platform-carried-the-design-not-the-wiring.svg
+evidence:
+  - ../../../final/evidence/raw/the-second-platform-carried-the-design-not-the-wiring.txt
+  - ../../../final/evidence/raw/tl-platform-suite-results.txt
+  - ../../../final/evidence/raw/tl-grpc-evidence-lanes.txt
+source:
+  - 원본 분석 절은 final/document.md#7-6 · analysis/20 §2, §3 · analysis/99-cross-scope.md §2, §4 이다.
+---
+
+# 두 번째 플랫폼이 첫 번째의 bridge 부재는 막고 게이트 배선은 옮기지 않았다
+
+gRPC 가족은 messaging 을 명시적으로 참조하며 만들어졌다. 옮겨진 것 셋은 전부 레지스트리와 빌드 파일로 표현되는 규칙이고, 옮겨지지 않은 것 셋은 전부 Gradle 태스크와 CI 설정으로 표현되는 규칙이다.
+
+## 관계
+
+- **레지스트리로 표현된 규칙은 전이되고 CI로 표현된 규칙은 전이되지 않는다**
+  이 사례에서 끌어낸 규칙이다.
+- **릴리스 게이트가 읽는 증거를 아무도 생산하지 않는다**
+  옮겨지지 않은 것 중 하나의 구체적 결과다.
+- **gRPC 플랫폼은 build-only로 두고 애플리케이션 도달 경로를 먼저 정한다**
+  옮겨진 것 중 가장 무거운 판단이다.
+- **같은 자격 증명 회전 결함이 한 가족에서 닫히고 다른 가족에서 재현됐다**
+  같은 두 가족 사이에서 전이되지 않은 다른 사례다.
+
+## 문제
+
+messaging 가족은 스타터를 컴포지션 루트의 의존으로 넣으면서 25개 리프가 출하 아티팩트에 실렸다. 그 결과 배선되지 않은 코드가 배포에 포함되는 문제가 실재하게 됐다.
+
+gRPC 가족은 그 이후에 만들어졌고 messaging 을 명시적으로 참조한다. 목표도 문서에 적혀 있다.
+
+그렇다면 무엇이 옮겨졌고 무엇이 옮겨지지 않았는가.
+
+## 결론
+
+옮겨진 것 셋은 전부 레지스트리와 빌드 파일로 표현된다.
+
+다리를 먼저 정하기로 한 것. 18개 리프 전부의 런타임 멤버십이 비어 있고, 인바운드 어댑터의 허용 의존에 이 가족이 없다. 레지스트리가 그것을 강제한다.
+프레임워크 없는 계약 리프를 두는 것. 빌드 파일의 테스트 클래스패스 조건이 그것을 검증 가능하게 만든다.
+속성 기반 전송 선택. 클래스패스 조건이 아니라 닫힌 레지스트리에서 이름으로 고른다.
+
+옮겨지지 않은 것 셋은 전부 Gradle 태스크와 CI 설정으로 표현된다.
+
+증거에서 파생되는 등급. gRPC 쪽에는 증거를 생산하는 태스크가 없다.
+CI 가 돌리는 게이트. 28개 워크플로 중 gRPC 를 이름에 담은 것이 0 이다.
+조립에 연결된 시작 검증기. 검증기는 있고 자동설정이 부르지 않는다.
+
+분류가 깨끗하다. 옮겨진 셋은 전부 다음 사람이 편집하게 되는 파일에 있고, 옮겨지지 않은 셋은 전부 그렇지 않은 파일에 있다.
+
+운영 문서는 그 상태를 정확히 공시한다. 출시되지 않았고 빌드 전용이라고 적는다. 이 점에서 messaging 의 지원 매트릭스와 대비된다.
+
+## 검증 환경
+
+OpenJDK : 21.0.12
+Gradle : 9.0.0
+확인 방식 : 레지스트리 항목 계수, Gradle 태스크와 CI 워크플로 계수, 문서 대조
+소스 수정 : x
+
+## 재현 조건
+
+원문은 final/evidence/raw 아래 tl-platform-suite-results.txt 와 266-grpc-family-claims-verification.txt 와 250-messaging-certification-gate-chain.txt 에 있다.
+
+1. 레지스트리에서 gRPC 리프들의 런타임 멤버십을 확인한다. 전부 비어 있다.
+2. 인바운드 gRPC 어댑터의 허용 의존에 이 가족이 있는지 확인한다.
+3. src/grpc 아래 등록된 Gradle 태스크 수를 센다.
+4. CI 워크플로 중 gRPC 를 이름에 담은 것을 센다.
+5. messaging 쪽 같은 사슬을 세어 대조한다.
+6. 블록의 CLAUDE.md 와 호환성 문서의 상태 표기를 읽는다.
+
+## 본문
+
+<!-- body:start -->
+
+gRPC 가족이 messaging을 명시적으로 참조하며 만들어졌고 목표를 문서에 적었다.
+
+## gRPC 가족이 문서에 적은 목표
+
+:::evidence key="the-second-platform-carried-the-design-not-the-wiring" alt="분석 문서 final/document.md 에서 이 기록의 근거 절을 그대로 잘라낸 18줄. 코드베이스를 측정한 것이 아니라 원본 판정이 무엇을 적었는지를 보여 준다." caption="final/document.md 발췌 — 18줄" zoom="true"
+:::
+
+## 옮겨진 셋과 옮겨지지 않은 셋이 표현 형식으로 갈린다
+
+옮겨진 셋(bridge를 먼저 정함·framework-free 계약 leaf·속성 기반 전송 선택)은 전부 레지스트리와 `build.gradle`로 표현되는 규칙이고, 옮겨지지 않은 셋(증거 파생 등급·CI가 돌리는 게이트·조립에 연결된 시작 검증기)은 전부 Gradle 태스크와 CI YAML로 표현되는 규칙이다.
+
+## 확인하지 못한 것
+
+이 분류가 인과인지 상관인지 확인할 수 없다. 작성자가 왜 후자를 옮기지 않았는지에 대한 기록이 없다. 표본도 두 가족뿐이다.
+
+<!-- body:end -->
@@ -0,0 +1,65 @@
+---
+kind: PROJECT_DECISION
+slug: grpc-stays-build-only-until-the-bridge-is-decided
+title: gRPC 플랫폼은 build-only로 두고 애플리케이션 도달 경로를 먼저 정한다
+topic: learning-transfer-between-families
+project: clean-architecture-backend-template
+status: 게시 전
+sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
+rootTreeNode: decision:grpc-stays-build-only-until-the-bridge-is-decided
+decisionStatus: ADOPTED
+decidedOn: 2026-08-30
+source:
+  - docs/adr/ADR-GRPC-001-platform-family-and-registry-shape.md
+  - src/config/architecture/modules.json
+  - src/grpc/CLAUDE.md
+  - docs/compatibility/grpc-support-matrix.md
+  - analysis/20-grpc-platform.md
+---
+
+# gRPC 플랫폼은 build-only로 두고 애플리케이션 도달 경로를 먼저 정한다
+
+## 결정문
+
+gRPC 가족의 18개 리프는 어떤 런타임 컴포지션에도 넣지 않고, 배선하려면 레지스트리를 먼저 바꾸고 게이트를 통과시켜야 한다.
+
+## 판단 이유
+
+messaging 가족은 스타터를 컴포지션 루트의 의존으로 넣었고, 그 결과 25개 리프가 출하 아티팩트에 실렸다. 배선되지 않은 코드가 배포에 포함되는 문제가 그때부터 실재하게 됐다.
+
+gRPC 가족은 그 선을 넘지 않기로 했다. 그리고 그 결정을 규약이 아니라 레지스트리로 표현했다.
+
+18개 리프 전부의 런타임 멤버십이 비어 있다
+인바운드 gRPC 어댑터의 허용 의존 목록에 이 가족이 없다
+
+배선하려면 멤버십을 먼저 바꾸고 런타임 모듈 멤버십 검증을 통과시켜야 한다. 즉 배선이 실수로 일어날 수 없다.
+
+그리고 그 상태를 문서가 공시한다. 호환성 문서가 출시되지 않았고 빌드 전용이라고 적고, 블록의 안내 문서가 같은 상태를 서술한다. 이 점이 messaging 의 지원 매트릭스와 대비된다.
+
+## 영향
+
+감수하는 것
+
+가족 전체가 어떤 배포에도 없다. 18개 리프의 코드는 컴파일되고 테스트되지만 실행되지 않는다.
+
+그 상태에서 발견되는 결함의 심각도를 판정하기 어렵다. 프로덕션 영향이 0 이므로 전부 낮아 보이지만, 배선되는 날 한꺼번에 나타난다.
+
+릴리스 게이트와 시작 검증기가 배선되지 않은 채로 남았다. 배선하는 날 그것들도 함께 연결해야 한다.
+
+얻는 것
+
+배선되지 않은 코드가 출하 아티팩트에 실리지 않는다.
+
+상태가 레지스트리에 있으므로 실수로 넘어갈 수 없고, 넘어가려면 게이트가 막는다.
+
+운영 문서가 실제 상태와 일치한다.
+
+## 근거
+
+- **두 번째 플랫폼이 첫 번째의 bridge 부재는 막고 게이트 배선은 옮기지 않았다**
+  이 결정이 무엇을 막았고 무엇을 남겼는지 보여 주는 사례다.
+- **레지스트리로 표현된 규칙은 전이되고 CI로 표현된 규칙은 전이되지 않는다**
+  이 결정이 레지스트리로 표현된 이유를 설명한다.
+- **릴리스 게이트가 읽는 증거를 아무도 생산하지 않는다**
+  배선하는 날 함께 해결해야 할 항목이다.
+
@@ -0,0 +1,60 @@
+---
+kind: REFERENCE
+slug: registry-rules-transfer-ci-rules-do-not
+title: 레지스트리로 표현된 규칙은 전이되고 CI로 표현된 규칙은 전이되지 않는다
+topic: learning-transfer-between-families
+project: clean-architecture-backend-template
+status: 게시 전
+sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
+rootTreeNode: reference:registry-rules-transfer-ci-rules-do-not
+verifiedOn:            # 이 기록은 이번 회차에 실행 확인을 하지 않았다
+---
+
+# 레지스트리로 표현된 규칙은 전이되고 CI로 표현된 규칙은 전이되지 않는다
+
+## 목적
+
+구조를 복제할 때 검증 배선이 함께 오지 않는 것을, 복제 시점에 알아채도록 한다.
+
+## 규칙
+
+1. 규칙이 어디에 적혀 있는지가 전이 여부를 정한다
+   다음 사람이 같은 파일을 편집하면서 마주치는 규칙은 따라 하게 된다. 마주치지 않는 규칙은 그렇지 않다.
+
+2. 마주치는 자리는 레지스트리와 빌드 파일과 타입 시그니처다
+   새 모듈을 만들려면 그 파일들을 반드시 연다.
+
+3. 마주치지 않는 자리는 Gradle 태스크와 CI 설정이다
+   새 모듈을 만들면서 워크플로 파일을 열 이유가 없다.
+
+4. CI 로만 표현된 규칙은 복제 시 명시적으로 옮긴다
+   전이되지 않는다고 단정하기보다, 복제 체크리스트에 그 항목을 두는 것이 안전한 형태다.
+
+5. 이력이 남은 자리도 같은 기준으로 본다
+   앞선 결함의 기록이 다른 가족의 테스트 파일에만 있으면 그 기록은 전이되지 않는다.
+
+## 적용 조건
+
+플랫폼 가족과 모듈 템플릿과 그 밖의 복제되는 구조
+
+앞선 사례에서 배운 규칙을 다음 구조에 옮길 때
+
+## 예외
+
+표본이 작으면 인과로 단정할 수 없다. 이 규칙의 근거는 두 가족의 관측이며, 안전한 사용법은 예측이 아니라 체크리스트다.
+
+## 예시
+
+두 번째 플랫폼이 옮겨온 셋은 전부 레지스트리와 빌드 파일 표현이고, 옮기지 않은 셋은 전부 Gradle 태스크와 CI 설정 표현이다.
+
+앞선 가족이 닫은 회전 경합의 이력은 그 가족의 계약 테스트 javadoc 에 있고, 다음 가족의 회전 매니저에서 같은 형태가 반복됐다.
+
+## 관계
+
+- **두 번째 플랫폼이 첫 번째의 bridge 부재는 막고 게이트 배선은 옮기지 않았다**
+  이 규칙을 끌어낸 사례다.
+- **같은 자격 증명 회전 결함이 한 가족에서 닫히고 다른 가족에서 재현됐다**
+  다섯 번째 규칙의 사례다.
+- **릴리스 게이트가 읽는 증거를 아무도 생산하지 않는다**
+  옮겨지지 않은 규칙의 결과다.
+