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,48 @@
+---
+kind: REFERENCE
+slug: messaging-kafka-share-experimental-f06
+title: 에러 메시지가 지시하는 설정은 그 설정을 읽는 코드와 함께 존재해야 한다
+topic: transport-and-provider-semantics
+project: clean-architecture-backend-template
+status: 게시 전
+sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
+rootTreeNode: reference:messaging-kafka-share-experimental-f06
+verifiedOn:            # 이 기록은 이번 회차에 실행 확인을 하지 않았다
+source:
+  - analysis/messaging/messaging-kafka-share-experimental.md#L512
+---
+
+# 에러 메시지가 지시하는 설정은 그 설정을 읽는 코드와 함께 존재해야 한다
+
+## 관계
+
+- **"등록"이 아무것도 등록하지 않고 성공을 반환한다**
+  이 규칙의 근거는 같은 분석 리프의 판정이 소유한다.
+
+## 목적
+
+운영자는 에러 메시지가 시키는 대로 프로퍼티를 설정하고, 아무 일도 일어나지 않는 것을 본다. 그때 의심할 대상이 자기 오타인지 코드인지 판단할 근거가 없다.
+
+## 규칙
+
+1. 에러 메시지에 등장하는 프로퍼티 키를 저장소에서 검색한다
+   KAFKA_SHARE_DISABLED 메시지가 backend.messaging.experimental.kafka-share=true 를 지시한다. git grep -n 'kafka-share' -- src 는 이 leaf 의 문자열 하나만 돌려준다.
+
+2. 그 키를 읽는 바인딩이 있는지 확인한다
+   enabled 는 KafkaShareProfile 생성자 인자이고, 그 profile 을 만드는 production 코드가 없다.
+
+3. 바인딩이 없으면 메시지에서 키를 빼거나 바인딩을 함께 만든다
+   지시가 실행 가능해야 지시다.
+
+## 적용 조건
+
+실패 메시지가 복구 방법을 문장으로 제시하는 모든 자리.
+
+## 예외
+
+SSOT 가 이 규칙의 반례를 적지 않았다. 배선 계획이 확정된 키를 미리 안내하는 경우가 있다면 그 사실이 메시지 자체에 있어야 한다.
+
+## 예시
+
+git grep -n 'kafka-share' -- src 의 결과가 문자열 하나라는 것과, KafkaShareProfile 을 만드는 production 코드가 없다는 것.
+
@@ -0,0 +1,52 @@
+---
+kind: REFERENCE
+slug: messaging-runtime-core-f04
+title: 안정 코드는 운영자의 행동이 갈리는 지점마다 나눈다
+topic: transport-and-provider-semantics
+project: clean-architecture-backend-template
+status: 게시 전
+sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
+rootTreeNode: reference:messaging-runtime-core-f04
+verifiedOn:            # 이 기록은 이번 회차에 실행 확인을 하지 않았다
+source:
+  - analysis/messaging/messaging-runtime-core.md#L736
+---
+
+# 안정 코드는 운영자의 행동이 갈리는 지점마다 나눈다
+
+## 관계
+
+- **관측이 구현·호출부·주입 자리를 모두 갖추고도 출하에서 no-op이다**
+  이 규칙의 근거는 같은 분석 리프의 판정이 소유한다.
+- **소비 오케스트레이터가 조립되지 않는다**
+  이 규칙의 근거는 같은 분석 리프의 판정이 소유한다.
+- **선언된 content type과 실제 인코딩이 조용히 갈라질 수 있다**
+  이 규칙의 근거는 같은 분석 리프의 판정이 소유한다.
+
+## 목적
+
+PUBLISH_DEADLINE_EXCEEDED 하나가 두 completion 에 붙는데, 두 경우의 운영자 행동은 정반대다. 전송 전이면 버려도 안전하고, 전송 후면 같은 messageId 로만 재발행해야 한다. 대시보드가 코드로 집계하는 순간 그 구분이 사라진다.
+
+## 규칙
+
+1. 코드 하나가 몇 개의 completion 에 붙는지 센다
+   전송 전이면 REJECTED(:16-21), 전송 후면 AMBIGUOUS(:42-47) 다.
+
+2. 각 completion 에서 운영자가 할 일이 같은지 묻는다
+   다르면 코드가 갈라져야 한다.
+
+3. FailureDescriptor.code 의 계약을 기준으로 판정한다
+   그 필드는 "stable, machine-readable code" 이고, completion 을 함께 읽어야만 뜻이 정해지는 코드는 그 계약을 지키지 못한다.
+
+## 적용 조건
+
+실패를 안정 코드로 분류하고 그 코드가 대시보드·알람의 집계 키가 되는 모든 자리.
+
+## 예외
+
+SSOT 가 이 규칙의 반례를 적지 않았다. 코드를 합치고 completion 을 항상 함께 노출하는 설계가 있다면 그 규약이 어딘가에 선언돼야 한다.
+
+## 예시
+
+PUBLISH_DEADLINE_EXCEEDED 가 붙는 두 위치. 확인 방법은 git grep -n 'PUBLISH_DEADLINE_EXCEEDED' -- src/messaging/messaging-runtime-core 다.
+
@@ -0,0 +1,48 @@
+---
+kind: REFERENCE
+slug: messaging-schema-json-f02
+title: 실패 코드는 운영자의 다음 행동이 갈리는 지점마다 나눈다
+topic: transport-and-provider-semantics
+project: clean-architecture-backend-template
+status: 게시 전
+sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
+rootTreeNode: reference:messaging-schema-json-f02
+verifiedOn:            # 이 기록은 이번 회차에 실행 확인을 하지 않았다
+source:
+  - analysis/messaging/messaging-schema-json.md#L472
+---
+
+# 실패 코드는 운영자의 다음 행동이 갈리는 지점마다 나눈다
+
+## 관계
+
+- **포맷 중립 payload 정책이, 자기 상수를 두고 JSON codec의 상수를 참조한다**
+  이 규칙의 근거는 같은 분석 리프의 판정이 소유한다.
+
+## 목적
+
+여섯 갈래 중 셋(중복 키 · trailing token · 깊이 초과)은 적대적 입력의 신호이고 나머지 셋은 계약 불일치다. 하나의 코드로 접히면 DLQ 를 보는 운영자가 그 둘을 구분할 수 없다. FailureDescriptor.exceptionType 마저 비어 있어 원인 클래스도 남지 않는다.
+
+## 규칙
+
+1. 한 catch 로 모이는 실패의 종류를 센다
+   decode 의 catch (JacksonException) 단일 분기가 깊이 초과 · 중복 키 · trailing token · 미지 필드 · 문서 길이 · 토큰 길이를 전부 JSON_DECODE_FAILED 로 만든다.
+
+2. 각각에 대해 운영자가 할 일이 같은지 묻는다
+   공격 신호는 차단으로, 계약 불일치는 스키마 수정으로 이어진다.
+
+3. 코드를 나누거나 최소한 원인 타입을 채운다
+   JacksonException 하위 타입별로 코드를 나누거나, exceptionType 에 원인 클래스 단순명을 넣는다.
+
+## 적용 조건
+
+라이브러리 예외 하나를 잡아 자체 실패 코드로 옮기는 모든 디코더·파서 경계.
+
+## 예외
+
+SSOT 가 이 규칙의 반례를 적지 않았다. 여섯 갈래의 대응이 실제로 동일하다면 하나의 코드가 맞지만, 여기서는 셋이 보안 신호다.
+
+## 예시
+
+JacksonMessageCodec.java:155-158 의 단일 catch. 확인 방법은 JacksonMessageCodecTest 의 네 케이스가 전부 같은 예외 타입을 기대한다는 것이다.
+
@@ -0,0 +1,48 @@
+---
+kind: REFERENCE
+slug: messaging-transport-spi-f02
+title: 멱등 종료를 보장하는 컴포넌트는 종료 이후의 등록도 정의한다
+topic: transport-and-provider-semantics
+project: clean-architecture-backend-template
+status: 게시 전
+sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
+rootTreeNode: reference:messaging-transport-spi-f02
+verifiedOn:            # 이 기록은 이번 회차에 실행 확인을 하지 않았다
+source:
+  - analysis/messaging/messaging-transport-spi.md#L668
+---
+
+# 멱등 종료를 보장하는 컴포넌트는 종료 이후의 등록도 정의한다
+
+## 관계
+
+- **드레인 마감 30초가 세 곳에서 독립적으로 결정된다**
+  이 규칙의 근거는 같은 분석 리프의 판정이 소유한다.
+
+## 목적
+
+이 클래스의 다른 모든 경로가 "정확히 한 번 close" 를 CAS 로 보장한다. 이 한 창만 그 보장 밖이고, 남는 것은 닫히지 않은 브로커 연결이다 — §13 의 세 번째 결함과 같은 결과다.
+
+## 규칙
+
+1. 종료 메서드가 상태를 비우는 순서를 본다
+   close() 가 draining 은 synchronized 로 비우고, current 는 List.copyOf(current.keySet()) 후 개별 remove 한다.
+
+2. 그 사이에 등록이 들어올 수 있는지 본다
+   install 이 새 세대를 넣으면 그 세대는 닫히지 않는다.
+
+3. 종료 이후의 등록 동작을 정의한다
+   close() 에 종료 플래그를 두고, 그 이후의 install 은 즉시 runtime.close() 하게 한다.
+
+## 적용 조건
+
+세대 교체나 참조 계수로 자원 종료를 보장하면서 등록 API 를 함께 노출하는 registry.
+
+## 예외
+
+종료 중 등록이 타입으로 불가능하면 대상이 아니다. 여기서는 install 이 종료 여부를 보지 않는다.
+
+## 예시
+
+DefaultMessagingRuntimeRegistry.java:141-156. 확인 방법은 코드 검토이고, 테스트로 재현하려면 close() 중 install 을 끼워 넣어야 한다.
+
@@ -0,0 +1,48 @@
+---
+kind: REFERENCE
+slug: messaging-transport-spi-f03
+title: 같은 개념의 sentinel은 계층을 넘어 하나로 정한다
+topic: transport-and-provider-semantics
+project: clean-architecture-backend-template
+status: 게시 전
+sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
+rootTreeNode: reference:messaging-transport-spi-f03
+verifiedOn:            # 이 기록은 이번 회차에 실행 확인을 하지 않았다
+source:
+  - analysis/messaging/messaging-transport-spi.md#L677
+---
+
+# 같은 개념의 sentinel은 계층을 넘어 하나로 정한다
+
+## 관계
+
+- **드레인 마감 30초가 세 곳에서 독립적으로 결정된다**
+  이 규칙의 근거는 같은 분석 리프의 판정이 소유한다.
+
+## 목적
+
+PauseResumeController 가 소비자 0 이라 오늘 충돌하지 않는다. 그것을 배선하는 사람이 변환을 넣어야 하고, 빠뜨리면 "" 가 이름이 "" 인 파티션을 가리킨다 — 실패하지 않고 아무것도 일시정지하지 않는다.
+
+## 규칙
+
+1. 같은 개념의 전체 지정자가 계층마다 무엇인지 모은다
+   TransportConsumerRegistration.pause 는 빈 문자열이 전체, PauseResumeController.pause 는 "*" 가 전체다.
+
+2. 변환 지점이 코드에 있는지 확인한다
+   지금은 두 계층을 잇는 코드 자체가 없다.
+
+3. sentinel 을 통일하거나 타입으로 바꾼다
+   Optional<String> 이면 sentinel 자체가 사라진다.
+
+## 적용 조건
+
+"전체" · "없음" · "기본" 같은 특수 의미를 문자열 값에 실어 계층을 넘기는 모든 API.
+
+## 예외
+
+두 계층이 절대 만나지 않는다면 대상이 아니다. 이 둘은 만나도록 설계된 상하 계층이다.
+
+## 예시
+
+두 javadoc 의 sentinel 정의. 확인 방법은 그 둘을 대조하는 것이다.
+