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>
99 lines
4.9 KiB
Markdown
99 lines
4.9 KiB
Markdown
---
|
|
kind: CASE
|
|
slug: support-matrix-said-the-opposite-of-the-code
|
|
title: 지원 매트릭스가 코드와 반대를 적었고, 그 오해가 소비자에게 자기 멱등성을 생략하게 한다
|
|
topic: drift-direction
|
|
project: clean-architecture-backend-template
|
|
status: 게시 전
|
|
sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
|
|
rootTreeNode: case:support-matrix-said-the-opposite-of-the-code
|
|
evidenceCapturedOn: 2026-09-01
|
|
body: case-support-matrix-said-the-opposite-of-the-code.body.md
|
|
assets:
|
|
- key: support-matrix-said-the-opposite-of-the-code
|
|
file: ../../../final/evidence/rendered/support-matrix-said-the-opposite-of-the-code.svg
|
|
evidence:
|
|
- ../../../final/evidence/raw/support-matrix-said-the-opposite-of-the-code.txt
|
|
- ../../../final/evidence/raw/tl-kafka-dedup-drift.txt
|
|
source:
|
|
- 원본 분석 절은 final/document.md#8-1 · analysis/19 §6.3 이다.
|
|
---
|
|
|
|
# 지원 매트릭스가 코드와 반대를 적었고, 그 오해가 소비자에게 자기 멱등성을 생략하게 한다
|
|
|
|
Kafka 어댑터의 능력 상수는 중복 제거 발행을 거짓으로 선언한다. 지원 매트릭스는 그것을 지원으로 적는다. 능력 표 60칸 중 유일한 불일치이고, 하필 실제 거부를 일으키는 유일한 플래그다.
|
|
|
|
## 관계
|
|
|
|
- **과대 진술 문서를 과소보다 먼저 고친다**
|
|
이 사례가 그 우선순위를 만든 형태다.
|
|
- **문서 계약 테스트의 단언 경계 밖에 발견된 드리프트 세 건이 전부 있었다**
|
|
이 드리프트가 왜 잡히지 않았는지 설명한다.
|
|
- **문서와 상수가 서로 일치하는 것으로는 아무것도 증명되지 않는다**
|
|
같은 계열의 규칙이다.
|
|
|
|
## 문제
|
|
|
|
메시징 어댑터는 자기 능력을 불리언 열둘로 선언한다. 열 번째가 중복 제거 발행이다.
|
|
|
|
Kafka 어댑터의 상수에서 열 번째 값은 거짓이다.
|
|
|
|
지원 매트릭스의 해당 행은 Kafka 열에 지원 표시를 적는다.
|
|
|
|
능력 표는 어댑터 다섯 곱하기 플래그 열둘로 60칸이다. 이 한 칸이 유일한 불일치다.
|
|
|
|
## 결론
|
|
|
|
하필 그 한 칸이 실제 거부를 일으키는 유일한 플래그다.
|
|
|
|
발행기는 열두 플래그 중 하나만 강제한다. 프로파일이 중복 제거 발행을 요구하는데 전송이 그 능력을 갖지 않으면 거부한다.
|
|
|
|
그래서 오해의 방향이 나쁜 쪽이다. 매트릭스를 읽고 Kafka 가 중복 제거를 해 준다고 믿은 소비자는 자기 멱등성 처리를 생략한다. 실제로는 브로커가 중복 제거를 하지 않으므로 중복이 그대로 소비자에게 도달한다.
|
|
|
|
그리고 그 소비자가 프로파일에 중복 제거를 요구하면 발행 자체가 거부된다. 두 결과 중 어느 쪽도 매트릭스를 읽은 사람이 예상한 것이 아니다.
|
|
|
|
문서 계약 테스트가 이 불일치를 잡지 못한 이유는 그 테스트의 단언 여덟 개가 등급 이름과 버전 문자열과 존재하지 않는 상수를 붙들고 능력 표 60칸은 붙들지 않기 때문이다.
|
|
|
|
## 검증 환경
|
|
|
|
OpenJDK : 21.0.12
|
|
Gradle : 9.0.0
|
|
확인 방식 : 코드 상수와 문서 표의 위치 대조
|
|
소스 수정 : x
|
|
|
|
## 재현 조건
|
|
|
|
원문은 final/evidence/raw/tl-kafka-dedup-drift.txt 와 255-messaging-capability-doc-vs-code-drift.txt 에 있다.
|
|
|
|
1. 능력 레코드의 컴포넌트 순서를 확인해 열 번째가 중복 제거 발행임을 확인한다.
|
|
2. Kafka 전송의 능력 상수에서 열 번째 값을 읽는다. 거짓이다.
|
|
3. 지원 매트릭스의 해당 행에서 Kafka 열을 읽는다. 지원으로 적혀 있다.
|
|
4. 발행기에서 능력 플래그를 강제하는 지점을 찾는다. 중복 제거 발행 하나뿐이다.
|
|
|
|
## 본문
|
|
|
|
<!-- body:start -->
|
|
|
|
capability 표 60칸을 코드 배열과 전수 대조한 결과 불일치가 정확히 한 칸이다 — Kafka `deduplicatedPublish`가 문서 `O`, 코드 `false`.
|
|
|
|
## 60칸을 전수 대조한 결과
|
|
|
|
:::evidence key="support-matrix-said-the-opposite-of-the-code" alt="분석 문서 final/document.md 에서 이 기록의 근거 절을 그대로 잘라낸 18줄. 코드베이스를 측정한 것이 아니라 원본 판정이 무엇을 적었는지를 보여 준다." caption="final/document.md 발췌 — 18줄" zoom="true"
|
|
:::
|
|
|
|
## 하필 그 플래그다
|
|
|
|
12개 중 유일하게 실제 거부를 발생시키는 것이고, 코드 javadoc이 `true`→`false` 변경 이력과 피해를 직접 이름 붙인다 — "the caller believes the broker is deduplicating and skips the idempotency it would otherwise build."
|
|
|
|
## 나머지 48칸은 일치한다
|
|
|
|
Pulsar의 `keyedOrdering`은 문서가 두 배열 차이까지 반영해 코드보다 정밀하다.
|
|
|
|
## 확인하지 못한 것
|
|
|
|
실제 브로커에 대고 중복 발행을 시도해 거부가 나는 것을 재현하지 않았다. 이 기록은 선언과 문서의 불일치, 그리고 그 플래그가 강제되는 유일한 것이라는 사실에 대한 것이다.
|
|
|
|
없음 — 60칸 전수 대조
|
|
|
|
<!-- body:end -->
|