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>
6.2 KiB
kind, slug, title, topic, project, status, sourceRevision, rootTreeNode, evidenceCapturedOn, assets, evidence, source
| kind | slug | title | topic | project | status | sourceRevision | rootTreeNode | evidenceCapturedOn | assets | evidence | source | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| CASE | two-files-name-a-build-gate-that-no-build-runs | 두 파일이 같은 검증기를 "빌드를 실패시키는 것"이라 적고, 어떤 빌드도 그것을 부르지 않는다 | what-a-gate-does-not-prove | clean-architecture-backend-template | 게시 전 | 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916 | case:two-files-name-a-build-gate-that-no-build-runs | 2026-09-01 |
|
|
|
두 파일이 같은 검증기를 "빌드를 실패시키는 것"이라 적고, 어떤 빌드도 그것을 부르지 않는다
스키마 규칙 엔진과 스키마 거버넌스 정책이 서로를 가리키며 상대가 이 저장소의 빌드 게이트라고 적는다. 두 쪽 다 어떤 빌드 스크립트나 CI 정의에도 나오지 않는다.
관계
- 산문이 선언한 게이트는 빌드에 있는 게이트가 아니다 이 사례가 그 규칙을 만들었다.
- 아무도 돌리지 않는 레인의 게이트는 마지막으로 돌린 사람이 본 것을 보고한다 그 규칙의 앞 단계에 해당한다. 여기서는 레인이 도는지가 아니라 게이트가 존재한다는 문장의 근거를 묻는다.
- 릴리스 게이트가 읽는 증거를 아무도 생산하지 않는다 같은 가족의 다른 층위에서 나타난 형태다.
- build gate라 불리는 catalog drift 검사가 어디에서도 실행되지 않는다 다른 어댑터에서 같은 형태가 나타난 사례다.
문제
이 저장소는 스키마 도구 체인의 CLI 를 싣지 않기로 했다. 그 결정의 근거가 두 곳에 적혀 있고 논증이 같다. 바이너리가 없을 때 조용히 통과하는 게이트는 없는 것보다 나쁘므로, 커밋된 스키마에서 같은 판정을 계산하는 자바 규칙 엔진을 대신 둔다는 것이다.
그 논증의 결론이 문장으로 남아 있다. 스키마 모듈 설정 파일의 머리 주석은 규칙 엔진이 이 저장소의 빌드를 실패시킨다고 적는다. 코드 생성 거버넌스 정책의 javadoc 도 같은 문장을 갖는다.
같은 정책이 네 개의 수명주기 태스크 이름을 상수로 들고 있고, 그 javadoc 은 이름을 정책에 두는 이유를 적는다. 단계가 사라지면 아무도 모르게 사라지는 대신 테스트가 실패하게 만들기 위해서라는 것이다.
결론
규칙 엔진을 부르는 빌드 코드가 없다.
Gradle 태스크도, 검증 훅도, 다른 모듈의 호출도 없다. 규칙 아홉 개를 실제로 실행하는 것은 그 리프의 단위 테스트 하나이고, 그 테스트가 판정하는 대상은 하드코딩된 두 파일 목록이다. 세 번째 스키마 파일을 같은 디렉터리에 추가하면 그 목록을 함께 고치기 전까지 판정되지 않는다.
네 태스크 이름도 마찬가지다. 그 이름들은 어떤 빌드 파일에도 없다. 그것을 확인한다는 테스트는 목록을 리터럴과 비교하고, 다시 목록을 자기 자신과 비교한다. 어느 단언도 빌드가 그 단계를 등록했는지 묻지 않는다.
두 문장이 서로를 가리킨다. 설정 파일은 CLI 가 없으니 자바 검증기가 게이트라고 하고, 정책은 태스크 이름이 CI 의 계약이고 자바 검증기가 실제 게이트라고 한다. 두 쪽 다 상대가 게이트라고 말하고 어느 쪽도 실행되지 않는다.
CLI 가 없다는 사실 자체는 이미 밝혀져 있으므로 태스크가 없는 것은 놀랍지 않다. 어긋난 것은 그 자리를 무엇이 대신하는지에 대한 문장이다.
검증 환경
OpenJDK : 21.0.12 Gradle : 9.0.0 확인 방식 : 빌드 스크립트와 CI 정의에 대한 타입 이름 및 태스크 이름 전수 검색, 그리고 테스트 단언 목록 확인 소스 수정 : x
재현 조건
- 스키마 모듈 설정 파일의 머리 주석에서 게이트를 지목하는 문장을 확인한다.
- 코드 생성 거버넌스 정책의 javadoc 에서 같은 문장을 확인한다.
- 그 규칙 엔진의 타입 이름으로 빌드 스크립트와 CI 정의를 검색한다.
- 네 수명주기 태스크 이름으로 같은 대상을 검색한다.
- 규칙 엔진을 실행하는 테스트가 어떤 파일 목록을 쓰는지 확인한다.
본문
두 파일이 같은 논증을 편다 — Buf CLI 가 이 툴체인에 없으므로 자바로 구현한 규칙 엔진이 그 자리를 대신하고, "그것이 실제로 이 저장소의 빌드를 실패시킨다". buf.yaml 주석과 GrpcBufPolicy javadoc 이 각각 그 문장을 갖는다.
GrpcBufPolicy 참조 위치
:::evidence key="two-files-name-a-build-gate-that-no-build-runs" alt="코드베이스에서 GrpcBufPolicy 를 검색한 출력 4줄. 이 기록이 세는 참조가 그 출력에 그대로 보인다." caption="GrpcBufPolicy 코드베이스 검색 — 4줄 · exit 0" zoom="true" :::
아홉 규칙을 실행하는 것은 단위 테스트 하나다
GrpcProtoContractValidator 를 부르는 Gradle 태스크도, 검증 훅도, 다른 모듈의 호출도 없다. 그 테스트가 판정하는 대상은 하드코딩된 두 파일이다.
반대 방향으로도 같다
GrpcBufPolicy 가 계약이라고 든 네 태스크 이름(bufFormatCheck·bufLint·bufBuild·bufBreaking)이 어떤 빌드 파일에도 없다. 그 javadoc 은 "a missing stage is a test failure rather than a stage nobody noticed was gone" 라고 적는데 테스트는 그 목록을 리터럴 및 자기 자신과 비교한다. 두 쪽이 서로를 게이트라고 가리키고 어느 쪽도 실행되지 않는다.
확인하지 못한 것
리플렉션이나 서비스 로더처럼 이름이 문자열로만 등장하는 호출 형태는 배제하지 못했다. 이 기록은 타입 이름과 태스크 이름에 대한 검색 결과에 근거한다.