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: REFERENCE
+slug: a-fake-that-cannot-show-the-property-is-not-a-witness
+title: 그 속성을 보일 수 없는 대역 위에서 통과한 테스트는 증인이 아니다
+topic: retention-and-unbounded-growth
+project: clean-architecture-backend-template
+status: 게시 전
+sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
+rootTreeNode: reference:a-fake-that-cannot-show-the-property-is-not-a-witness
+verifiedOn:            # 이 기록은 이번 회차에 실행 확인을 하지 않았다
+---
+
+# 그 속성을 보일 수 없는 대역 위에서 통과한 테스트는 증인이 아니다
+
+## 목적
+
+테스트 대역이 실제 구현의 불변식을 재현하지 못하면 그 위에서 통과한 단언은 그 불변식에 대해 아무 말도 하지 않는다.
+
+## 규칙
+
+1. 단언하는 속성이 협력자의 상태 변화에 달려 있는지 본다
+   달려 있지 않으면 이 규칙은 해당하지 않는다.
+
+2. 대역이 결함 있는 구현과 올바른 구현을 구분할 수 있는지 묻는다
+   구분하지 못하면 그 테스트는 회귀를 잡지 못한다.
+
+3. 대역이 흉내 내는 불변식을 문장으로 쓴다
+   쓸 수 없으면 대역이 무엇을 재현하는지 저자도 모르는 상태다.
+
+4. 이름이 속성을 주장하면 대역을 먼저 읽는다
+   이름이 강할수록 그 공백이 눈에 띄지 않는다.
+
+## 적용 조건
+
+저장소, 브로커, 파일 시스템처럼 상태를 갖는 협력자의 인메모리 대역 전부.
+
+## 예외
+
+협력자의 존재만 필요한 테스트에는 해당하지 않는다. 호출이 일어났는지만 확인하는 경우가 그렇다.
+
+## 예시
+
+배치 제한 정리 대역이 무제한 결과와 제한값 중 작은 쪽을 돌려준다. 전부 지우고 숫자만 깎으므로 두 형태의 차이를 보일 수 없다.
+
+리드라이브 대역의 정착 메서드가 정착 목록에 추가만 하고 준비 목록을 줄이지 않는다. 실제 불변식은 정착된 것이 다음 조회에서 사라지는 것이고, 재개 지점 계산이 정확히 그 성질에 달려 있다.
+
+청구 대역의 저장 메서드가 삽입을 흉내 내서, 실제 구현이 갱신으로 동작한다는 차이를 가린다.
+
+## 관계
+
+- **cleanup 이 스스로 막겠다고 적은 장애를 일으키는 형태로 호출된다**
+  이 규칙이 회귀 테스트를 막는 사례다.
+- **재개된 리드라이브가 옮기지 못한 메시지를 건너뛰고 성공으로 닫힌다**
+  대역이 불변식을 재현하지 못해 결함이 오래 남은 사례다.
+- **배정 식별자 때문에 insert-first 청구가 UPSERT 가 되어 커밋된 결과를 덮었다**
+  같은 형태의 세 번째 사례다.
+
@@ -0,0 +1,55 @@
+---
+kind: REFERENCE
+slug: a-port-that-offers-both-forms-has-chosen-the-unsafe-one
+title: 두 형태를 나란히 내놓는 포트는 이미 안전하지 않은 쪽을 고른 것이다
+topic: retention-and-unbounded-growth
+project: clean-architecture-backend-template
+status: 게시 전
+sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
+rootTreeNode: reference:a-port-that-offers-both-forms-has-chosen-the-unsafe-one
+verifiedOn:            # 이 기록은 이번 회차에 실행 확인을 하지 않았다
+---
+
+# 두 형태를 나란히 내놓는 포트는 이미 안전하지 않은 쪽을 고른 것이다
+
+## 목적
+
+인터페이스가 만든 기본값을 호출자의 선택으로 오인하지 않는다. 안전하지 않은 형태가 컴파일되면 그것은 언젠가 호출된다.
+
+## 규칙
+
+1. 안전하지 않은 쪽을 부르는 것이 컴파일되는지 본다
+   컴파일되면 그 형태는 기본값이다.
+
+2. 두 형태를 가르는 표시가 있는지 본다
+   폐기 표시, 이름 차이, 가시성 차이 중 아무것도 없으면 호출자는 짧은 쪽을 고른다.
+
+3. 두 형태가 진짜로 다른 용도인지 묻는다
+   다르면 이름이 그 차이를 말해야 한다. 오버로드로 두는 것은 차이를 이름에서 지우는 선택이다.
+
+4. 같은 용도라면 하나를 지운다
+   지울 수 없으면 폐기 표시와 함께 부를 조건을 javadoc 에 적는다.
+
+## 적용 조건
+
+정리, 삭제, 조회처럼 결과 크기가 데이터 양에 비례하는 모든 연산. 그리고 같은 전이의 두 세대가 공존하는 인터페이스.
+
+## 예외
+
+두 형태가 서로 다른 호출자 집단을 위한 것이면 공존이 맞다. 그때 판정 기준은 이름이 그 구분을 담고 있는지다.
+
+## 예시
+
+inbox 와 outbox 포트가 정리 연산의 무제한 형태와 배치 제한 형태를 오버로드로 나란히 선언한다. 두 정리 잡이 무제한 쪽을 부르고, 배치 제한 쪽은 호출 지점이 0이다.
+
+같은 포트에 같은 전이의 두 세대 메서드가 있다. 안전하지 않은 쪽에 폐기 표시가 없다.
+
+## 관계
+
+- **bounded 와 unbounded 오버로드를 나란히 둔 포트**
+  이 규칙이 나온 구조다.
+- **cleanup 이 스스로 막겠다고 적은 장애를 일으키는 형태로 호출된다**
+  이 규칙을 어긴 결과다.
+- **같은 개념의 두 어휘가 공존하면 하나를 죽은 것으로 표시한다**
+  같은 계열의 규칙이고, 이쪽은 어휘가 아니라 시그니처에 대한 것이다.
+
@@ -0,0 +1,55 @@
+---
+kind: REFERENCE
+slug: one-formula-and-one-enforcement-point-per-safety-rule
+title: 같은 안전 규칙은 하나의 공식과 하나의 강제 시점을 갖는다
+topic: retention-and-unbounded-growth
+project: clean-architecture-backend-template
+status: 게시 전
+sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
+rootTreeNode: reference:one-formula-and-one-enforcement-point-per-safety-rule
+verifiedOn:            # 이 기록은 이번 회차에 실행 확인을 하지 않았다
+---
+
+# 같은 안전 규칙은 하나의 공식과 하나의 강제 시점을 갖는다
+
+## 목적
+
+같은 종류의 안전 여유가 여러 곳에서 독립적으로 정해지면 공식과 강제 시점이 갈린다. 값의 주인을 한 곳으로 정한다.
+
+## 규칙
+
+1. 이 값을 바꾸려면 몇 군데를 고쳐야 하는지 센다
+   하나가 아니면 나머지는 조용히 옛 값으로 남는다.
+
+2. 공식이 같은지 본다
+   같은 관계를 곱셈과 덧셈으로 다르게 표현하고 있으면 둘 중 하나는 근거가 없다.
+
+3. 강제 시점이 같은지 본다
+   한쪽은 항상 검증하고 다른 쪽은 특정 객체를 만들 때만 검증하면, 그 객체를 만들지 않는 배포는 검증을 받지 않는다.
+
+4. 값이 아니라 관계가 소유자를 가져야 하는 경우를 구분한다
+   층마다 다른 값이 정당하면 값이 아니라 그 관계를 한 곳에 두고 검증한다.
+
+## 적용 조건
+
+보존 기간, 마감, 재시도 상한, 배치 크기처럼 안전을 위해 고른 모든 수치.
+
+## 예외
+
+클라이언트 마감이 서버 마감보다 짧아야 하는 것처럼 층마다 다른 값이 필요한 경우. 그때는 값이 아니라 관계가 한 곳에 있어야 하고, 그 관계를 검증하는 코드가 있어야 한다.
+
+## 예시
+
+inbox 보존 여유가 한 곳에서는 곱셈으로, 다른 곳에서는 덧셈으로 표현된다. 한쪽은 정리 잡을 만들 때만 검증하고 다른 쪽은 항상 검증한다.
+
+드레인 마감 30초가 세 곳에서 각자 정해진다. 공개 상수 하나, 다른 클래스의 비공개 복사본 하나, 생성자 인자 하나. 테스트가 붙드는 것은 공개 상수뿐이고, 살아 있는 값은 비공개 복사본이다.
+
+## 관계
+
+- **재생 저장소에 제거 경로가 없고, 형제 맵의 상한은 세션 경계 하나다**
+  보존 경계가 아예 없는 쪽의 사례다.
+- **순서 계약을 구현하는 것이 없고, 그것을 검증한다는 테스트는 enum 선언 순서만 본다**
+  드레인 마감 세 곳이 그 사건의 일부다.
+- **문서의 수치는 세지 말고 파생하거나 게이트로 붙든다**
+  같은 규칙의 문서 판이다.
+