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>
5.3 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 | doc-contract-test-boundary-predicted-the-drift | 문서 계약 테스트의 단언 경계 밖에 발견된 드리프트 세 건이 전부 있었다 | what-a-gate-does-not-prove | clean-architecture-backend-template | 게시 전 | 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916 | case:doc-contract-test-boundary-predicted-the-drift | 2026-09-01 |
|
|
|
문서 계약 테스트의 단언 경계 밖에 발견된 드리프트 세 건이 전부 있었다
지원 문서가 코드와 어긋나는 것을 잡는 테스트가 있고 잘 작동한다. 이 분석이 찾은 문서 드리프트 세 건은 그 테스트의 단언 여덟 개가 닿지 않는 곳에만 있었다.
관계
- 문서와 상수가 서로 일치하는 것으로는 아무것도 증명되지 않는다 이 사례와 짝을 이루는 규칙이다.
- 빠뜨림이 통과가 되는 게이트는 게이트가 아니다 같은 계열의 상위 규칙이다.
문제
MessagingDocumentationContractTest 가 존재하고, 클래스 javadoc 이 목적을 정확히 적는다.
문서는 조용히 썩는다. 어댑터를 Stable 이라고 적은 지원 매트릭스는 누군가 그것을 강등한 날보다 오래 살아남고, 아무것도 실패하지 않는다. 테스트는 통과하고 빌드는 초록이며 유일한 신호는 몇 달 전에 사실이 아니게 된 페이지를 보고 결정을 내리는 운영자다.
단언은 의도적으로 좁다. 읽는 사람이 행동의 근거로 삼을 주장만 검사하고 산문은 검사하지 않는다. 표현을 단언하면 모든 편집이 테스트 실패가 되고 그 검사는 삭제될 것이기 때문이다.
의도도 이유도 명확하다. 문제는 그 경계가 어디인지를 아무 데도 적어 두지 않았다는 점이다.
결론
단언 여덟 개는 이렇다.
지원 매트릭스가 약속하는 문서 아홉 개의 존재 STABLE 어댑터 이름의 정확한 일치 EXPERIMENTAL 어댑터가 Stable 로 적히지 않음 문서화된 Kafka 버전 문자열의 일치 존재하지 않는 상수 두 개가 미지원 목록에 여전히 있음 그 두 상수가 코드에 실제로 없음 실험 정책 문서가 기본값 꺼짐을 명시하는지 각 문서가 500자를 넘는지
앞의 여섯은 정확하고 강하다. 뒤의 둘은 문자열 포함과 길이 검사라서 약하다.
경계 밖에 있는 것은 셋이다.
능력 표. 어댑터 다섯 곱하기 플래그 열둘로 60칸이다 런타임 멤버십 문장 브로커 등급 표의 제한 칸
이 분석이 찾은 문서 드리프트 세 건이 정확히 그 셋 안에 하나씩 있었다. 우연이 아니다. 테스트가 붙드는 항목인 등급 이름과 버전 문자열과 존재하지 않는 상수는 전부 옳았고, 붙들지 않는 항목만 틀렸다.
이것이 이 테스트를 결함으로 만들지는 않는다. 좁게 만든 것은 의도이고 그 이유도 타당하다.
결함은 그 경계가 어디인지가 문서에도 테스트에도 적혀 있지 않다는 것이다. 이 테스트를 통과한 문서는 코드와 일치하도록 검증됐다고 읽힌다. 실제로 검증된 것은 여덟 항목뿐이다.
검증 환경
OpenJDK : 21.0.12 Gradle : 9.0.0 확인 방식 : 테스트 메서드 열거와 문서 대조 소스 수정 : x
재현 조건
원문은 final/evidence/raw/261-messaging-documentation-contract-test-coverage.txt 와 255-messaging-capability-doc-vs-code-drift.txt 에 있다.
- MessagingDocumentationContractTest 의 테스트 메서드를 열거한다. 여덟 개다.
- 각 메서드가 무엇을 단언하는지 확인한다.
- 지원 문서에서 그 여덟 개가 닿지 않는 영역을 식별한다.
- 그 영역을 코드와 대조한다.
본문
doc rot를 막기 위해 존재하는 계약 테스트의 단언 여덟 개가 붙드는 것은 전부 정확하다 — 등급 이름·Kafka 버전 문자열·존재하지 않는 두 enum 상수.
계약 테스트의 단언 여덟 개
:::evidence key="doc-contract-test-boundary-predicted-the-drift" alt="분석 문서 final/document.md 에서 이 기록의 근거 절을 그대로 잘라낸 18줄. 코드베이스를 측정한 것이 아니라 원본 판정이 무엇을 적었는지를 보여 준다." caption="final/document.md 발췌 — 18줄" zoom="true" :::
붙들지 않는 것에 드리프트 세 건이 전부 있다
capability 표 60칸·runtime membership 문장·브로커 등급표의 "제한" 칸이다. 테스트 javadoc은 좁은 단언을 고른 이유까지 옳게 적는다.
결함은 경계가 적혀 있지 않다는 점이다
좁게 고른 것이 결함이 아니다.
확인하지 못한 것
세 건의 드리프트 각각에 대해 그것을 잡는 단언을 실제로 추가해 보지 않았다. 능력 표 60칸을 코드와 대조하는 단언이 유지 가능한 형태인지는 별도 판단이 필요하다.
없음 — 단언 목록과 문서를 전수 대조했다