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
@@ -44,6 +44,16 @@ slug를 비우면 제목에서 만든다. 한글 제목도 로마자로 옮겨
 **Project에 slug가 없으면 공개 화면에 프로젝트가 표시되지 않는다.** 공개 계약의
 `ProjectSummary`가 `slug`와 `path`를 요구하기 때문이다. `주제·프로젝트` 화면에서 확인한다.

+## frontmatter 의 `topic`
+
+**폴더 이름과 같은 slug 를 적는다.** 화면에 보이는 한글 주제 이름은 `topicName` 에 따로 둔다.
+`topic` 이 표시 이름이면 폴더와 대조할 수 없다.
+
+```yaml
+topic: oauth-oidc-auth-boundary
+topicName: OAuth/OIDC 인증 경계
+```
+
 ## 기록이 가리키는 로컬 파일

 기록은 `docs/<프로젝트>/tech-log-studio/<주제>/<종류>/` 에 있고, 그림과 증거는 같은 프로젝트의
@@ -69,6 +79,13 @@ evidence:
 본문(`bodyMarkdown`)을 뺀 모든 칸은 평문이다. 백틱·파이프·`#`는 글자 그대로 보이고 줄바꿈만
 살아난다. 그 줄바꿈이 유일한 서식이므로 아끼지 않는다.

+**무엇을 지우나.** 백틱·별표·코드펜스는 글자 그대로 보인다. 식별자는 남기고 표시 문자만 뺀다.
+`InboxCleanupJob:56` 은 InboxCleanupJob:56 으로, `**this is the parameter**` 는 그 문장만 남긴다.
+코드펜스 안이 `이름 : 값` 꼴이면 펜스 줄만 지우면 그대로 읽힌다. 줄바꿈이 유일한 서식이므로
+문단 사이 빈 줄은 지킨다.
+
+관계(`근거`) 절은 평문 칸이 아니다. 기록을 거는 목록이라 `- **제목**` 표기를 그대로 둔다.
+
 **나열은 `이름 : 값`으로 끊는다.** 쉼표로 이으면 읽는 사람이 항목을 세어야 한다.

 ```text
@@ -3,9 +3,12 @@
 칸 목록과 상한은 `record-kinds.md`, 문장 규칙은 `explaining.md`, 문서군의 리듬은 `ai-tells.md`에
 있다. 이 문서는 **그 칸을 무엇으로 채우는가**다.

-**이미 쓴 47건에서 뽑았다.** keycloak 23건(Case 4·Concept 6·Reference 7·Question 4·Decision 2),
-n+1liner 24건(Case 5·Reference 7·Question 5·Decision 7). 「대개 이렇게 쓴다」는 말은 그 47건이
-그렇게 돼 있다는 뜻이다.
+**Studio 에 실제로 올라간 47건에서 뽑았다.** keycloak 23건(Case 4·Concept 6·Reference 7·
+Question 4·Decision 2), n+1liner 24건(Case 5·Reference 7·Question 5·Decision 7).
+「대개 이렇게 쓴다」는 말은 그 47건이 그렇게 돼 있다는 뜻이다.
+
+`clean-architecture-backend-template` 의 949건은 다른 절 이름으로 쓰여 있었고 이 기준에 맞춰
+고쳤다. 올라간 적 없는 초안이 아니라 **올라간 것**이 기준이다.

 ## 파일 뼈대 — 다섯 종류가 같다

@@ -30,6 +33,18 @@ id · kind · slug · title · topic · project · status · studio

 frontmatter 는 메타데이터, `##` 는 Studio 의 칸, 제목 아래 첫 문단은 요약이다. 47건 모두 이 모양이다.

+**`## 요약` 이라는 절을 만들지 않는다.** 요약은 제목 바로 아래 문단이다. 절로 만들면 Studio 에
+그런 칸이 없어서 통째로 사라진다.
+
+**`## 출처` 도 칸이 아니다.** 원본 분석 문서나 파일 경로는 frontmatter 의 `source` 에 적는다.
+본문 마지막에 두면 게시된 글에 저장소 내부 경로가 그대로 실린다.
+
+```yaml
+source:
+  - analysis/05-adapter-outbound-persistence-jpa.md#L354
+module: adapter-inbound-graphql
+```
+
 **관계 항목은 굵은 제목 한 줄 + 이유 한 줄**이다.

 ```markdown
@@ -58,6 +73,8 @@ frontmatter 는 메타데이터, `##` 는 Studio 의 칸, 제목 아래 첫 문
  테스트로 확인한 범위」, 「Redirect URI와 CORS에서 아직 확인하지 않은 부분」), 2건이 「다음 선택」,
  나머지가 지표 읽는 법이나 남긴 이유다. **재지 않은 것을 적지 않고 닫는 Case 는 없다**

+그 마지막 절은 **본문 안**이다. 칸으로 빼면 Studio 에 그런 칸이 없어 사라진다.
+
 코드블록에는 무엇을 보라는 한 줄을 붙인다. 표 앞이나 뒤에 그 표를 어떻게 읽는지 적는다. 예시는
 한 규모로 고정한다 — 표가 전체 계열을 이미 보여 준다.

@@ -131,3 +148,35 @@ basisVersion: oauth2-proxy 7.15.2 · Nginx auth_request
 - 그림 안에는 이름만 넣는다. 문장은 `<desc>` 와 옆 문단에 둔다
 - 그림과 증거는 frontmatter 의 `assets` · `evidence` 로 잇는다. 같은 파일을 기록 옆에 복사하지 않는다
 - 본문은 `<!-- body:start -->` 와 `<!-- body:end -->` 사이다. 그 밖은 Studio 로 가지 않는다
+
+## 관계를 어디서 가져오나
+
+관계는 **다른 기록을 가리키는 링크**다. 지어내지 않는다. 분해 계약(`root-tree.md`)이 노드마다
+`relations` 를 적어 두면 그것을 그대로 옮긴다.
+
+계약이 관계를 적지 않은 노드는 한 가지 규칙만 쓸 수 있다 — **Reference 의 근거 사건은 같은
+`source` 리프의 판정이 소유한다.** 그래서 같은 분석 문서에서 나온 Reference 와 Case 는 서로
+걸 수 있다. 그 밖의 짝은 읽고 정해야 한다. 「같은 모듈이다」는 관계가 아니라 분류다.
+
+```markdown
+## 관계
+
+- **SQL 실패가 재시도 불가로 분류된다**
+  이 규칙의 근거는 같은 분석 리프의 판정이 소유한다.
+```
+
+Studio 는 Decision 만 관계를 1개 이상 요구한다. 나머지는 비어도 게시되지만, 관계 없는 기록은
+다른 기록에서 도달할 수 없다.
+
+## Studio 파서가 거절하는 세 가지
+
+`check_body.mjs` 가 잡는다. 셋 다 글자를 바꾸지 않고 고칠 수 있다.
+
+| 쓴 것 | 파서가 읽는 것 | 고치는 법 |
+|---|---|---|
+| `` `:11`~`:14` `` | `~…~` 를 취소선으로 | `` `:11`\~`:14` `` |
+| `afterPropertiesSet(:43)` | `:43` 을 인라인 디렉티브로 | `(\:43)` 또는 백틱으로 감싼다 |
+| `:::note` 안에 문단 둘 | 거절 | 문단 하나만 담거나 절 제목 아래 평문으로 푼다 |
+
+`## 확인하지 못한 것` 처럼 절 제목이 이미 무엇인지 말하는 자리에서는 `:::note` 로 다시 감싸지
+않는다. 제목과 콜아웃이 같은 말을 두 번 한다.