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,58 @@
+---
+kind: PROJECT_DECISION
+slug: retry-safety-is-decided-by-evidence
+title: 재시도 안전성은 증거에 기반해 판정한다
+topic: http-failure-classification
+project: clean-architecture-backend-template
+status: 게시 전
+sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
+rootTreeNode: decision:retry-safety-is-decided-by-evidence
+decisionStatus: ADOPTED
+decidedOn: 2026-08-30
+source:
+  - src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/transport/TransportFailure.java
+  - src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/api/operation/ExecutionEvidence.java
+  - src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/resilience/DefaultRetryEligibilityEngine.java
+  - docs/adr/ADR-GRPC-003-three-axis-execution-evidence.md
+  - analysis/11-adapter-outbound-httpclient.md
+---
+
+# 재시도 안전성은 증거에 기반해 판정한다
+
+## 결정문
+
+재시도 여부는 무엇이 실패했는지가 아니라 무엇이 관측됐는지로 판정한다.
+
+## 판단 이유
+
+같은 예외라도 요청이 서버에 닿았는지에 따라 재시도의 의미가 완전히 달라진다. 닿지 않았으면 재시도는 첫 시도이고, 닿았을지도 모르면 재시도는 중복이다. 예외 타입은 그 구분을 담지 않으므로, 관측된 진행 정도를 별도의 값으로 기록하고 그것을 판정 입력으로 삼는다.
+
+이 판정을 보수적으로 유지하는 것이 핵심이다. 전송되지 않았다는 판정은 단계 실패가 그것을 증명할 때만 쓰고, 일반적인 엔진 입출력 실패는 결코 그 판정으로 승격되지 않는다. 모호한 것을 전송되지 않음으로 추측하는 것이 타임아웃을 중복 결제로 바꾸는 경로다.
+
+같은 원칙이 이 저장소의 gRPC 쪽에도 별도 ADR 로 채택되어 있다. 거기서는 전송 증거와 업무 증거와 스트림 증거를 세 축으로 나누고 축 사이의 추론을 금지한다. HTTP 쪽의 이 결정은 그 셋 중 전송 축에 해당한다.
+
+## 영향
+
+감수하는 것
+
+재시도 가능한 실패를 재시도하지 않는 경우가 생긴다. 증거가 모호하면 안전한 쪽으로 판정하므로, 실제로는 전송되지 않았는데 재시도를 포기하는 호출이 있다.
+
+분류기마다 이 증거를 정확히 채워야 한다. 엔진별 분류기가 늘어날 때마다 같은 판정 품질을 유지해야 하는 비용이 붙는다.
+
+증거를 만드는 계층이 정보를 버리면 판정 전체가 틀린 입력 위에 선다. 이 취약점은 실제로 관측되었다. 다중 주소 호스트에서 연결 루프가 앞선 주소의 실패를 버리면, 영구 실패가 재시도 가능한 범주로 내려온다. 분류기 안에서는 고칠 수 없다.
+
+얻는 것
+
+같은 실패에 대해 Apache JDK Reactor Netty Jetty 가 동일한 재시도와 관측 동작을 낸다.
+
+재시도 정책이 HTTP 메서드 같은 간접 신호에 기대지 않는다.
+
+## 근거
+
+- **전송 실패를 단계와 범주 두 축으로 모델링한다**
+  이 결정이 만들어 내는 자료 구조다. TransportFailure 의 notSent 와 sentNoResponse 팩토리, 그리고 ExecutionEvidence 의 네 값이 결정의 구현체다.
+- **재시도 가능성은 멱등성과 실패 범주를 함께 봐야 정해진다**
+  이 결정을 재시도 결정표로 옮긴 규칙이다.
+- **붉은 테스트를 제품 결함으로 읽은 오진**
+  이 결정의 취약점이 실제로 드러난 사례다.
+