DongHyeonkaandClaude Opus 5
b2963105a8
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>
95 lines
5.2 KiB
Markdown
95 lines
5.2 KiB
Markdown
---
|
|
kind: CASE
|
|
slug: analysis-finding-a06-f024
|
|
title: promotion 증거 어휘가 둘이고, gate는 하나만 검사한다
|
|
topic: multitenancy-isolation
|
|
project: clean-architecture-backend-template
|
|
status: 게시 전
|
|
sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
|
|
rootTreeNode: case:analysis-finding-a06-f024
|
|
evidenceCapturedOn: 2026-09-01
|
|
assets:
|
|
- key: analysis-finding-a06-f024
|
|
file: ../../../final/evidence/rendered/analysis-finding-a06-f024.svg
|
|
evidence:
|
|
- ../../../final/evidence/raw/analysis-finding-a06-f024.txt
|
|
source:
|
|
- 원본 분석 절은 analysis/06-adapter-outbound-persistence-mongo.md#L1305 이다.
|
|
---
|
|
|
|
# promotion 증거 어휘가 둘이고, gate는 하나만 검사한다
|
|
|
|
승격 증거의 필수 범주가 여섯이고 게이트가 그 여섯을 검사한다. 벡터 검색 벤치마크 게이트는 완전히 다른 다섯 범주를 요구하는데 그 집합을 읽는 프로덕션 코드가 없다.
|
|
|
|
## 관계
|
|
|
|
- **빠뜨림이 통과가 되는 게이트는 게이트가 아니다**
|
|
이 사례가 그 규칙의 형태다.
|
|
- **같은 개념의 두 어휘가 공존하면 하나를 죽은 것으로 표시한다**
|
|
증거 어휘가 둘인 구조다.
|
|
- **능력 등급은 코드가 아니라 실행된 증거에서 파생한다**
|
|
승격이 요구하는 증거의 성질이다.
|
|
|
|
## 문제
|
|
|
|
승격 증거의 필수 범주는 여섯이다. 안정 플랫폼과 실제 토폴로지와 보안과 마이그레이션과 실패와 런북이다.
|
|
|
|
승격 게이트가 그 여섯을 전부 검사한다.
|
|
|
|
그리고 그 파일에는 고쳐진 결함이 주석으로 남아 있다. 한 범주가 필수 목록에는 있고 게이트에는 없어서, 게이트가 선언한 여섯 중 다섯만 요구했다는 것이다. 주석은 그것을 실행한 것보다 많이 인증하는 게이트의 모양이라고 부른다.
|
|
|
|
## 결론
|
|
|
|
같은 모양이 모듈 경계를 건너 다시 나타난다.
|
|
|
|
벡터 검색 벤치마크 게이트는 완전히 다른 다섯 범주를 요구한다. 인덱스 준비도와 재현율과 지연과 메모리와 실제 토폴로지다.
|
|
|
|
겹치는 것은 실제 토폴로지 하나뿐이고, 이 집합을 읽는 프로덕션 코드가 없다. 승격 게이트는 이 집합을 모른다.
|
|
|
|
그래서 벡터 검색을 승격하는 경로는 승격 게이트를 통과할 수 있고, 그 통과는 재현율과 지연과 인덱스 메모리에 대해 아무것도 말하지 않는다.
|
|
|
|
벤치마크 게이트의 javadoc 이 정확히 그 위험을 적는데도 그렇다. 기능적 성공은 벡터 검색의 증거가 아니며, 근사 인덱스는 어떤 질의에 대해서도 결과를 돌려주고 그것이 옳은 결과인지는 재현율에 달렸다는 것이다.
|
|
|
|
방금 한 범주 누락으로 고쳤던 것과 같은 모양이 반복된다. 선언한 것보다 적게 검사하는 게이트다.
|
|
|
|
## 검증 환경
|
|
|
|
OpenJDK : 21.0.12
|
|
확인 방식 : 두 게이트의 요구 범주 대조와 참조 계수
|
|
소스 수정 : x
|
|
|
|
## 재현 조건
|
|
|
|
원문은 final/evidence/raw/137 계열에 있다.
|
|
|
|
1. 승격 증거의 필수 범주 목록을 확인한다.
|
|
2. 승격 게이트가 검사하는 범주를 확인한다.
|
|
3. 그 파일의 고쳐진 결함 주석을 읽는다.
|
|
4. 벤치마크 게이트가 요구하는 범주를 확인한다.
|
|
5. 그 집합을 읽는 프로덕션 코드를 센다.
|
|
|
|
## 본문
|
|
|
|
<!-- body:start -->
|
|
|
|
`MongoAdvancedPromotionEvidence.REQUIRED`는 여섯 범주다 — `stable-platform`, `actual-topology`, `security`, `migration`, `failure`, `runbook`. `MongoAdvancedPromotionGate.verify(...)`가 그 여섯을 전부 검사한다. 그 파일에는 고쳐진 결함이 주석으로 남아 있다 — "`migration` was in `MongoAdvancedPromotionEvidence.REQUIRED` and not here, so the gate demanded five of the six categories it declares… which is the shape MNG-008 names: a gate that certifies more than it ran."
|
|
|
|
## MongoAdvancedPromotionEvidence 참조 위치
|
|
|
|
:::evidence key="analysis-finding-a06-f024" alt="코드베이스에서 MongoAdvancedPromotionEvidence 를 검색한 출력 3줄. 이 기록이 세는 참조가 그 출력에 그대로 보인다." caption="MongoAdvancedPromotionEvidence 코드베이스 검색 — 3줄 · exit 0" zoom="true"
|
|
:::
|
|
|
|
## 다른 gate가 완전히 다른 다섯 범주를 반환한다
|
|
|
|
`MongoVectorSearchBenchmarkGate.requiredEvidence()`는 `index-readiness`, `recall`, `latency`, `memory`, `actual-topology`를 반환한다. 겹치는 것은 `actual-topology` 하나뿐이고, 이 집합을 읽는 production 코드는 없다(`137-...` §8.3). `MongoAdvancedPromotionGate`는 이 집합을 모른다.
|
|
|
|
## 통과가 아무것도 말하지 않는 구간
|
|
|
|
vector search를 promotion하는 경로는 `MongoAdvancedPromotionGate.verify`를 통과할 수 있고, 그 통과는 recall·latency·index memory에 대해 아무것도 말하지 않는다 — `MongoVectorSearchBenchmarkGate`의 javadoc이 정확히 그 위험을 적는데도: "Functional success is not evidence for vector search. An approximate index returns results for any query; whether they are the right results depends on recall." 방금 `migration` 누락으로 고쳤던 것과 같은 모양이 모듈 경계를 건너 다시 나타난다. P3.
|
|
|
|
## 확인하지 못한 것
|
|
|
|
벡터 검색 승격을 실제로 시도해 통과하는 것을 재현하지 않았다.
|
|
|
|
<!-- body:end -->
|