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,57 @@
+---
+kind: PROJECT_DECISION
+slug: in-root-write-fails-fast
+title: inRootWrite는 suspend하지 않고 fail-fast한다
+topic: transaction-deadline-and-pool
+project: clean-architecture-backend-template
+status: 게시 전
+sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
+rootTreeNode: decision:in-root-write-fails-fast
+decisionStatus: ADOPTED
+decidedOn: 2026-08-30
+source:
+  - src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/transaction/SpringTransactionPort.java
+  - analysis/05-adapter-outbound-persistence-jpa.md
+---
+
+# inRootWrite는 suspend하지 않고 fail-fast한다
+
+## 결정문
+
+루트 쓰기 연산은 이미 트랜잭션이 열려 있으면 바깥을 일시 중단하지 않고 예외를 던진다.
+
+## 판단 이유
+
+이 연산의 이름이 약속하는 것은 루트 트랜잭션이다. 호출자가 그렇게 부르는 이유는 자기 작업이 다른 트랜잭션에 참여하지 않기를 바라기 때문이다.
+
+이미 트랜잭션이 열려 있는데 일시 중단하고 새로 시작하면 두 가지가 일어난다. 바깥 커넥션이 핀되고, 호출자는 자기가 루트라고 믿는데 실제로는 중첩 안에 있다.
+
+첫 번째는 풀 비용이다. 두 번째는 더 나쁘다. 커밋 순서와 롤백 범위에 대한 호출자의 가정이 틀린 채로 진행된다.
+
+그래서 일시 중단하지 않고 던진다. 중첩된 루트 트랜잭션이 거절되었다는 전용 예외 타입이다.
+
+이 선택은 호출자에게 부담을 넘긴다. 루트를 요구하는 코드가 어디서 불리는지 알아야 하기 때문이다. 그것이 의도다. 그 사실을 아는 것이 이 연산을 쓰는 조건이다.
+
+## 영향
+
+감수하는 것
+
+이 연산을 호출하는 경로가 트랜잭션 안에 들어가면 런타임에 실패한다. 정적으로는 막히지 않는다.
+
+기존 코드에서 이 연산을 쓰려면 호출 경로를 먼저 정리해야 한다.
+
+얻는 것
+
+루트라고 부른 것이 실제로 루트다.
+
+중첩 깊이가 예상 밖으로 늘어나 풀 하한을 깨는 경로 하나가 사라진다.
+
+## 근거
+
+- **REQUIRES_NEW의 커넥션 비용과 풀 사이징 제약**
+  일시 중단이 커넥션을 놓지 않는다는 사실이 이 결정의 근거 중 하나다.
+- **트랜잭션 템플릿은 모드별로 미리 만들어 둔다**
+  같은 포트의 다른 모드 결정이다.
+- **트랜잭션 결과 대수 — 다섯 변형이 각각 답하는 질문**
+  참여와 루트를 구별하는 결과 타입이다.
+
@@ -0,0 +1,53 @@
+---
+kind: PROJECT_DECISION
+slug: templates-are-built-once-per-mode
+title: 트랜잭션 템플릿은 모드별로 미리 만들어 둔다
+topic: transaction-deadline-and-pool
+project: clean-architecture-backend-template
+status: 게시 전
+sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
+rootTreeNode: decision:templates-are-built-once-per-mode
+decisionStatus: ADOPTED
+decidedOn: 2026-08-30
+source:
+  - src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/transaction/SpringTransactionPort.java
+  - analysis/05-adapter-outbound-persistence-jpa.md
+---
+
+# 트랜잭션 템플릿은 모드별로 미리 만들어 둔다
+
+## 결정문
+
+트랜잭션 템플릿을 모드마다 하나씩 미리 만들어 두고, 호출마다 템플릿의 속성을 바꾸지 않는다.
+
+## 판단 이유
+
+템플릿은 가변 객체다. 하나를 공유하면서 호출마다 전파 방식이나 타임아웃을 바꾸면 두 스레드가 서로의 설정을 본다.
+
+그 경합은 재현이 어렵다. 대부분의 호출은 같은 값을 쓰므로 증상이 드물게 나타나고, 나타났을 때는 트랜잭션이 잘못된 전파 방식으로 실행된 결과만 남는다.
+
+그래서 모드마다 별도 템플릿을 두고 전부 같은 격리 수준에 고정한다. 쓰기와 읽기와 새 트랜잭션 셋이다.
+
+데드라인처럼 호출마다 달라지는 값은 템플릿의 필드가 아니라 실행 시점에 계산해 전달한다.
+
+## 영향
+
+감수하는 것
+
+모드가 늘면 템플릿도 늘어난다. 조합이 많아지면 이 방식이 부담이 된다.
+
+호출마다 달라져야 하는 값은 별도 경로로 전달해야 한다. 템플릿에 넣을 수 없다.
+
+얻는 것
+
+템플릿 경합이 구조적으로 사라진다.
+
+각 모드가 무엇으로 설정되어 있는지 한 자리에서 보인다.
+
+## 근거
+
+- **호출 예산에서 DB 로컬 타임아웃까지의 데드라인 전파**
+  호출마다 달라지는 값이 어떻게 전달되는지 설명한다.
+- **Atomic 타입의 존재는 원자성의 증거가 아니다**
+  가변 공유 상태를 다루는 같은 계열의 규칙이다.
+