Merge branch 'claude/d2b-src-adr-d46d23' — 모듈 문서와 ADR 번역

충돌: scripts/check-docs-exceptions.txt. 두 쪽 모두 줄을 지우기만 했다(D2a 11줄, D2b 81줄, 겹침 0).
기준의 줄 중 두 쪽이 모두 남긴 줄만 남겼다(220 → 128줄).
This commit is contained in:
DongHyeonka
2026-11-07 18:07:04 +09:00
78 changed files with 3394 additions and 4077 deletions
@@ -7,122 +7,110 @@
- 현재 정본: `src/build-logic/README.md`
<!-- 머리 블록 끝 -->
# ADR-BUILD-001: `java-test-fixtures` is the standard for shared test code
# ADR-BUILD-001: 공유 시험 코드의 표준은 `java-test-fixtures`다
- Status: Accepted
- Date: 2026-09-07
- Scope: every leaf that publishes or consumes shared test code
- Source: `docs/reviews/2026-09-07-app-bootstrap-module-code-review.md` BOOT-015
- 상태: 채택
- 날짜: 2026-09-07
- 범위: 공유 시험 코드를 내놓거나 쓰는 모든 leaf
- 출처: `docs/reviews/2026-09-07-app-bootstrap-module-code-review.md` BOOT-015
## Context
## 배경
Two conventions do the same job in this repository.
이 저장소에서 같은 일을 하는 규약이 둘 있다.
`ca.testkit-publisher` — a convention plugin — gives a leaf a `testkit` source set, wires its output
onto the lanes that leaf names, and optionally publishes it as a consumable configuration. Five
leaves use it: `persistence-jpa` (published as `jpaTestkit`), `web` (`webTestkit`), `websocket`
(`websocketTestkit`), `persistence-mongo` and `httpclient` (both unpublished).
`ca.testkit-publisher` — 규약 플러그인 — 는 leaf에 `testkit` source set을 주고, 그 출력을 leaf가 이름을 댄 lane에
배선하고, 원하면 쓸 수 있는 configuration으로 내놓는다. 다섯 leaf가 쓴다: `persistence-jpa`(`jpaTestkit`으로 내놓음),
`web`(`webTestkit`), `websocket`(`websocketTestkit`), `persistence-mongo`와 `httpclient`(둘 다 내놓지 않음).
`java-test-fixtures` — Gradle's own plugin — gives a leaf a `testFixtures` source set, puts it on
`test`'s classpath automatically, and always publishes it as a variant consumers reach with
`testFixtures(project(':x'))`. One leaf uses it: `graphql`, which additionally fails its build when a
fixture is written outside `src/testFixtures/java`.
`java-test-fixtures` — Gradle 자신의 플러그인 — 는 leaf에 `testFixtures` source set을 주고, 그것을 `test`의
classpath에 자동으로 올리고, 쓰는 쪽이 `testFixtures(project(':x'))`로 닿는 variant로 언제나 내놓는다. 한 leaf가
쓴다: `graphql`. 이 leaf는 fixture를 `src/testFixtures/java` 밖에 쓰면 빌드를 실패시키기도 한다.
Two conventions for one purpose is the defect. A contributor adding shared test code has to know
which leaf they are in before they know where the file goes, and the two answers are not
interchangeable: a consumer of the first writes `project(path: ':x', configuration: 'jpaTestkit')`
and has to know the configuration's name, while a consumer of the second writes
`testFixtures(project(':x'))` and does not.
한 목적에 규약 둘이 있는 것이 결함이다. 공유 시험 코드를 더하는 사람은 파일을 어디 둘지 알기 전에 자기가 어느
leaf에 있는지 알아야 하고, 두 답은 서로 바꿔 쓸 수 없다: 첫째를 쓰는 쪽은
`project(path: ':x', configuration: 'jpaTestkit')`를 쓰고 configuration 이름을 알아야 하지만, 둘째를 쓰는 쪽은
`testFixtures(project(':x'))`를 쓰고 그럴 필요가 없다.
## Decision
## 결정
**`java-test-fixtures` is the standard.** New shared test code goes in `src/testFixtures/java`, and a
consumer depends on it with `testFixtures(project(':x'))`.
**`java-test-fixtures`가 표준이다.** 새 공유 시험 코드는 `src/testFixtures/java`에 두고, 쓰는 쪽은
`testFixtures(project(':x'))`로 의존한다.
Three reasons, in order of weight:
이유 셋, 무게 순으로:
1. **The consumer side describes itself.** `testFixtures(project(':adapter:inbound:web'))` says what
it is. `project(path: ':adapter:inbound:web', configuration: 'webTestkit')` says where to look,
and only after the reader has learned that `webTestkit` is a testkit rather than a lane.
2. **The enforcement already exists and is copyable.** `graphql`'s build fails when a fixture is
declared in the wrong place. The same guard applies unchanged to any leaf that adopts the plugin.
3. **It is one fewer local concept.** A convention plugin that reimplements a Gradle plugin has to be
maintained against it.
1. **쓰는 쪽이 스스로를 설명한다.** `testFixtures(project(':adapter:inbound:web'))`는 그것이 무엇인지 말한다.
`project(path: ':adapter:inbound:web', configuration: 'webTestkit')`는 어디를 볼지 말하고, 읽는 사람이
`webTestkit`이 lane이 아니라 testkit임을 배운 뒤에야 뜻이 통한다.
2. **강제 장치가 이미 있고 복사할 수 있다.** `graphql`의 빌드는 fixture를 엉뚱한 곳에 선언하면 실패한다. 같은
guard를 플러그인을 쓰는 어느 leaf에든 바꾸지 않고 적용한다.
3. **지역 개념이 하나 준다.** Gradle 플러그인을 다시 구현한 규약 플러그인은 그 플러그인에 맞춰 계속 관리해야 한다.
## What the local plugin does better, and how it is replaced
## 지역 플러그인이 더 잘하는 것과 그것을 대신하는 방법
This is worth writing down, because the review that prompted this ADR recommended the migration
before reading `ca.testkit-publisher`, and the plugin turns out to encode two deliberate decisions
rather than being an oversight.
이것은 적어 둘 만하다. 이 ADR을 낳은 리뷰는 `ca.testkit-publisher`를 읽기 전에 옮기기를 권했고, 읽어 보니 그
플러그인은 빠뜨린 것이 아니라 일부러 정한 결정 둘을 담고 있었다.
**Publishing is opt-in.** `persistence-mongo` and `httpclient` have a testkit and publish nothing;
`persistence-jpa` publishes. The plugin's own comment names this as "a real difference in what each
leaf offers rather than an oversight to normalise away". `java-test-fixtures` always creates the
variant, so the distinction is lost — a leaf that never meant to offer its fixtures will offer them.
**내놓기는 고를 때만 한다.** `persistence-mongo`와 `httpclient`는 testkit이 있지만 아무것도 내놓지 않는다.
`persistence-jpa`는 내놓는다. 플러그인 자신의 주석이 이것을 "a real difference in what each leaf offers rather than
an oversight to normalise away"(각 leaf가 주는 것의 실제 차이이지, 맞춰 없앨 빠뜨림이 아니다)라고 부른다.
`java-test-fixtures`는 언제나 variant를 만드니 이 구별이 사라진다 — fixture를 줄 생각이 없던 leaf도 주게 된다.
> Replacement: none at the build level. The distinction moves to review: the fixtures of a leaf that
> nobody consumes are simply unconsumed. This is a real, accepted loss.
> 대신하는 것: 빌드 수준에서는 없다. 구별은 리뷰로 옮긴다: 아무도 쓰지 않는 leaf의 fixture는 그냥 쓰이지 않는다.
> 실제 손실이고, 받아들인 손실이다.
**Lane consumption is declared.** `persistence-jpa` says `consumedBy 'test', 'postgresqlIntegrationTest'`.
`java-test-fixtures` puts fixtures on `test` only, so every other lane needs the output added
explicitly.
**lane이 쓰는 것을 선언한다.** `persistence-jpa`는 `consumedBy 'test', 'postgresqlIntegrationTest'`라고 말한다.
`java-test-fixtures`는 fixture를 `test`에만 올리니, 다른 모든 lane에는 출력을 명시해서 더해야 한다.
> Replacement: `strictTestLanes`' existing `compilesAgainst` expresses this unchanged — a lane
> declares `compilesAgainst 'main', 'testFixtures'`. The first draft of this ADR assumed the DSL
> would need a change, because `sourceSet(name)` creates what it is given and `testFixtures` already
> exists. The `persistence-mongo` migration showed otherwise: `compilesAgainst` only *looks a source
> set up*, so naming a plugin-created one works as-is. What the leaf drops is the
> `sourceSet('testkit')` declaration, not the lane's.
> 대신하는 것: `strictTestLanes`의 기존 `compilesAgainst`가 바꾸지 않고 이것을 나타낸다 — lane이
> `compilesAgainst 'main', 'testFixtures'`를 선언한다. 이 ADR의 첫 초안은 DSL을 바꿔야 한다고 가정했다.
> `sourceSet(name)`은 받은 것을 만들고 `testFixtures`는 이미 있기 때문이다. `persistence-mongo`를 옮겨 보니 아니었다:
> `compilesAgainst`는 source set을 *찾기만* 하므로, 플러그인이 만든 것의 이름을 대도 그대로 된다. leaf가 버리는 것은
> lane의 선언이 아니라 `sourceSet('testkit')` 선언이다.
## Migration: done, and what it cost
## 옮기기: 끝났고, 든 비용
Five leaves, eleven lanes, two published testkits, all migrated leaf by leaf with the suite run
between each. `ca.testkit-publisher` is deleted.
leaf 다섯, lane 열하나, 내놓은 testkit 둘을 leaf 하나씩, 그 사이마다 suite를 돌리며 모두 옮겼다.
`ca.testkit-publisher`는 지웠다.
The order was chosen so a mistake would be cheap: unpublished leaves first, published ones last with
their consumer in the same step.
순서는 실수가 싸게 끝나도록 골랐다: 내놓지 않는 leaf를 먼저, 내놓는 leaf를 마지막에 그 쓰는 쪽과 같은 단계에서.
1. `persistence-mongo` — one leaf, two lanes, no cross-module consumer; the proof the path works.
What it took, per leaf:
- `apply plugin: 'java-test-fixtures'` at the top of the leaf build file;
1. `persistence-mongo` — leaf 하나, lane 둘, 다른 모듈의 쓰는 쪽 없음. 길이 되는지 보는 증명이다.
leaf마다 든 일:
- leaf 빌드 파일 맨 위에 `apply plugin: 'java-test-fixtures'`;
- `git mv src/testkit src/testFixtures`;
- drop `sourceSet('testkit')` and the whole `testkitPublisher` block; keep every other lane's
`compilesAgainst`, renaming `'testkit'` to `'testFixtures'`;
- rename `testkitImplementation` to `testFixturesImplementation`, **and add what the old source
set was inheriting silently**. This is the one non-mechanical step: `testkit*` extended
`testImplementation`, so the fixtures saw every test library the leaf declared. Mongo's needed
four more lines (AssertJ, BSON, Spring Data commons, Toxiproxy) — none of which the leaf had
ever stated the fixtures depended on;
- regenerate the leaf's lock state.
2. `httpclient`, then `websocket` — unpublished as well, more lanes.
3. `web` and `persistence-jpa` with `app-bootstrap`'s two consumer declarations, which became
`testImplementation(testFixtures(project(':…')))`.
4. `ca.testkit-publisher` deleted, along with its `plugins {}` entry and its application in the root
build.
- `sourceSet('testkit')`와 `testkitPublisher` 블록 전체를 버린다. 다른 모든 lane의 `compilesAgainst`는 두고
`'testkit'`을 `'testFixtures'`로 이름을 바꾼다;
- `testkitImplementation`을 `testFixturesImplementation`으로 이름을 바꾸고, **옛 source set이 소리 없이
물려받던 것을 더한다**. 기계적이지 않은 단계는 이것 하나다: `testkit*`는 `testImplementation`을 상속해서,
fixture가 leaf가 선언한 모든 시험 라이브러리를 봤다. Mongo는 네 줄(AssertJ, BSON, Spring Data commons,
Toxiproxy)이 더 필요했다 — leaf가 fixture의 의존으로 적은 적이 한 번도 없는 것들이다;
- leaf의 잠금 상태를 다시 만든다.
2. `httpclient`, 그다음 `websocket` — 역시 내놓지 않고, lane이 더 많다.
3. `web`과 `persistence-jpa`, 그리고 `app-bootstrap`의 쓰는 쪽 선언 둘. 그 선언은
`testImplementation(testFixtures(project(':…')))`가 됐다.
4. `ca.testkit-publisher`를 지웠다. 그 `plugins {}` 항목과 루트 빌드의 적용도 함께.
### Two things the migration broke, and what they taught
### 옮기기가 깨뜨린 것 둘과 그것이 가르친 것
Both were caught by tests that exist to catch exactly this, which is the argument for having them.
둘 다 바로 이것을 잡으려고 있는 시험이 잡았다. 그런 시험을 둘 이유가 그것이다.
**ArchUnit corpora went wrong in opposite directions.** `httpclient`'s boundary rules *excluded*
`build/classes/java/testkit`; after the move the fixtures arrived as a `…-test-fixtures.jar` on the
same classpath, so the exclusion missed them and 258 fixture-to-fixture calls were reported as
production depending on the testkit. `persistence-jpa`'s rules *included* only
`build/classes/java/main`; applying `java-test-fixtures` makes the module's own test classpath carry
the module as a **jar** rather than as a class directory, so its corpus became empty. The second is
the dangerous one — an empty corpus makes every `noClasses()` rule pass — and it surfaced only
because that suite asserts its corpus is non-empty before asserting anything about it.
**ArchUnit 대상 묶음이 반대 방향으로 틀어졌다.** `httpclient`의 경계 규칙은 `build/classes/java/testkit`을
*뺐다*. 옮긴 뒤 fixture는 같은 classpath에 `…-test-fixtures.jar`로 들어왔고, 그래서 빼기가 그것을 놓쳤으며
fixture 사이 호출 258개가 운영 코드가 testkit에 의존한다고 보고됐다. `persistence-jpa`의 규칙은
`build/classes/java/main`만 *넣었다*. `java-test-fixtures`를 적용하면 모듈 자신의 시험 classpath가 모듈을 class
디렉터리가 아니라 **jar**로 싣는다. 그래서 대상 묶음이 비었다. 위험한 쪽은 둘째다 — 빈 묶음이면 모든
`noClasses()` 규칙이 통과한다 — 그리고 그 suite가 무엇이든 단언하기 전에 묶음이 비어 있지 않음을 단언했기
때문에만 드러났다.
**Fixtures had invisible dependencies.** `testkit*` configurations extended `testImplementation`, so
the fixtures compiled against every test library their leaf declared without ever naming one. Making
them explicit took roughly thirty `testFixturesImplementation` lines across the five leaves —
Micrometer, Spring Web, Netty, logback, Jackson, JUnit, AssertJ, Spring Data. None of them were
wrong; none of them were stated.
**fixture에 보이지 않는 의존이 있었다.** `testkit*` configuration은 `testImplementation`을 상속해서, fixture는 이름
한 번 대지 않고 leaf가 선언한 모든 시험 라이브러리에 대고 컴파일됐다. 그것을 명시하는 데 다섯 leaf에 걸쳐
`testFixturesImplementation` 줄이 대략 서른 개 들었다 — Micrometer, Spring Web, Netty, logback, Jackson, JUnit, AssertJ,
Spring Data. 틀린 것은 없었다. 적힌 것도 없었다.
## Consequences
## 결과
- `docs/testing/TESTING_STRATEGY.md` §5 records the standard; this ADR records why and at what cost.
- Until step 5, two conventions remain visible. The strategy document says so explicitly, so a
contributor reading it is not left to infer which one is current.
- The opt-in-publishing distinction is given up. If it later proves load-bearing — a leaf whose
fixtures genuinely must not be reachable — the answer is a separate module, not a third convention.
- `docs/testing/TESTING_STRATEGY.md` §5가 표준을 적는다. 이 ADR은 왜, 어떤 비용으로인지를 적는다.
- 5단계까지는 규약 둘이 보이는 채로 남는다. 전략 문서가 그것을 분명히 말하므로, 읽는 사람이 어느 것이 지금
것인지 짐작하게 두지 않는다.
- 고를 때만 내놓는 구별은 포기한다. 나중에 그것이 꼭 필요한 것으로 드러나면 — fixture에 정말 닿으면 안 되는
leaf — 답은 세 번째 규약이 아니라 따로 둔 모듈이다.
@@ -7,73 +7,63 @@
- 현재 정본: `src/adapter/inbound/graphql/README.md`
<!-- 머리 블록 끝 -->
# ADR-GQL-001 — GraphQL context stays inbound; object authorization moves to application-core; the persisted-operation store stays an inbound SPI
# ADR-GQL-001 — GraphQL 문맥은 inbound에 머물고, 객체 인가는 application-core로 옮기며, persisted operation 저장소는 inbound SPI로 남는다
- Status: Accepted
- Date: 2026-08-24
- Review: `docs/reviews/2026-08-14-graphql-module-code-review.md` GQL-026
- 상태: 채택
- 날짜: 2026-08-24
- 리뷰: `docs/reviews/2026-08-14-graphql-module-code-review.md` GQL-026
## Context
## 배경
The GraphQL leaf's own documentation described three things crossing its boundary: a
`GraphQlRequestContext` with a deadline propagated into application, JPA, Mongo and the HTTP client;
object authorization decided inside the transport; and a persisted-operation registry implemented by
an external durable store.
GraphQL leaf 자신의 문서는 경계를 넘는 것 셋을 적었다: application, JPA, Mongo, HTTP client로 deadline을 전파하는
`GraphQlRequestContext`, 전송 계층 안에서 정하는 객체 인가, 외부 durable 저장소가 구현하는 persisted operation
registry.
Two of those invert the dependency direction. If `application-core` or an outbound adapter
implements a type that lives in `adapter:inbound:graphql`, the registry edge that says inbound
depends on application is satisfied while the real compile-time dependency runs the other way.
그중 둘은 의존 방향을 뒤집는다. `application-core`나 outbound 어댑터가 `adapter:inbound:graphql`에 있는 타입을
구현하면, inbound가 application에 의존한다는 registry edge는 만족되지만 실제 컴파일 의존은 반대로 간다.
The third is a business rule in the wrong layer: whether an actor may see an object is a decision
about the domain, and GraphQL is one of four transports this skeleton ships.
셋째는 엉뚱한 계층의 업무 규칙이다: actor가 객체를 볼 수 있는지는 도메인에 대한 판단이고, GraphQL은 이 골격이
싣는 전송 계층 넷 중 하나다.
## Decision
## 결정
Three different answers, because the three problems are not the same problem.
세 문제가 같은 문제가 아니므로 답도 셋이다.
**GraphQL context stays inbound-local.** It is mapped explicitly onto application command fields —
actor, tenant, deadline — rather than travelling as a type. Nothing outside the leaf references
`GraphQlRequestContext`, and the boundary test is that grep returns nothing outside it.
**GraphQL 문맥은 inbound 안에 머문다.** 타입으로 실려 다니지 않고 application command 필드 — actor, tenant,
deadline — 로 명시해 대응시킨다. leaf 밖의 어떤 것도 `GraphQlRequestContext`를 참조하지 않고, 경계 시험은 leaf
밖에서 grep이 아무것도 돌려주지 않는 것이다.
**Object authorization moves to `application-core`.** `ObjectAccessPolicy`, `ObjectAccessRequest`
and `ObjectAccessDecision` are transport-neutral and live with the other application policies;
`ApplicationObjectAuthorization` in the GraphQL leaf is the bridge that calls them. This is the one
of the three that was a real layering defect, and it is fixed rather than documented.
**객체 인가는 `application-core`로 옮긴다.** `ObjectAccessPolicy`, `ObjectAccessRequest`, `ObjectAccessDecision`은
전송 중립이고 다른 애플리케이션 정책과 함께 있다. GraphQL leaf의 `ApplicationObjectAuthorization`이 그것을 부르는
다리다. 셋 중 이것이 실제 계층 결함이었고, 적어 두지 않고 고친다.
**The persisted-operation store stays an inbound-owned SPI.** `GraphQlPersistedOperationRegistry`
remains in `advanced/persisted`, and no leaf outside GraphQL implements it.
**persisted operation 저장소는 inbound가 가진 SPI로 남는다.** `GraphQlPersistedOperationRegistry`는
`advanced/persisted`에 남고, GraphQL 밖의 어떤 leaf도 그것을 구현하지 않는다.
## Consequences
## 결과
The third decision is the one that needs defending, because it leaves the reported risk in place
rather than removing it.
변호가 필요한 것은 셋째 결정이다. 보고된 위험을 없애지 않고 그 자리에 두기 때문이다.
The risk is conditional: the direction inverts only when something outside the leaf implements the
interface. Nothing does. The template ships an in-memory registry and no durable one, because it
ships no persisted-operation store at all.
위험은 조건부다: leaf 밖의 무엇이 그 인터페이스를 구현할 때만 방향이 뒤집힌다. 그런 것은 없다. 템플릿은 메모리
registry를 싣고 durable registry는 싣지 않는다. persisted operation 저장소를 아예 싣지 않기 때문이다.
The alternative was to introduce a generic operational key-value store port owned by a neutral
contract holder, with the GraphQL adapter owning only the key and value mapping. That port would
have exactly one interface, zero implementations and one speculative consumer — a new abstraction
whose shape is guessed from a requirement nobody has stated. This repository has spent a full
remediation pass deleting controls that existed and were reached by nothing, and inventing a port
for a store that does not exist is how the next one of those gets written.
대안은 중립 계약 보유자가 가진 범용 운영 key-value 저장소 포트를 들이고, GraphQL 어댑터는 키와 값 대응만 가지는
것이었다. 그 포트는 인터페이스 정확히 하나, 구현 0개, 짐작으로 정한 쓰는 쪽 하나를 가졌을 것이다 — 아무도 말하지
않은 요구에서 모양을 짐작한 새 추상이다. 이 저장소는 있었지만 아무것도 닿지 않던 통제를 지우는 데 수정 한 바퀴를
통째로 썼다. 없는 저장소를 위해 포트를 지어내는 것이 그런 것을 다음에 또 쓰는 길이다.
So the decision is to leave the SPI where it is and to move it when a durable store is actually
built. Moving it then is a rename across one leaf and one new adapter, which is cheaper than
carrying a wrong abstraction until then. What must not happen in the meantime is an outbound leaf
implementing the inbound interface, because that is the moment the direction actually inverts, and
it would happen in a commit whose diff looks like an implementation rather than a layering change.
그래서 결정은 SPI를 있는 곳에 두고, durable 저장소를 실제로 만들 때 옮기는 것이다. 그때 옮기는 일은 leaf 하나와
새 어댑터 하나에 걸친 이름 바꾸기이고, 그때까지 틀린 추상을 끌고 다니는 것보다 싸다. 그동안 일어나면 안 되는 것은
outbound leaf가 inbound 인터페이스를 구현하는 것이다. 그때가 방향이 실제로 뒤집히는 순간이고, 그것은 계층 변경이
아니라 구현처럼 보이는 diff의 커밋에서 일어날 것이다.
The composition root wires these and owns no business or storage policy of its own.
조립 루트가 이것들을 배선하고, 자기 업무·저장 정책은 가지지 않는다.
## Enforcement
## 강제
`verifyCleanArchitectureDependencies` and `modules.json` hold the leaf's edges to
`domain-core`, `application-core` and `shared-contract`. `ObjectAccessPolicyTest` covers the
application-side policy and `ApplicationObjectAuthorizationTest` the bridge.
`verifyCleanArchitectureDependencies`와 `modules.json`이 leaf의 `domain-core`, `application-core`, `shared-contract`
edge를 지킨다. `ObjectAccessPolicyTest`가 application 쪽 정책을, `ApplicationObjectAuthorizationTest`가 다리를 덮는다.
The condition this ADR turns on — that nothing outside the GraphQL leaf implements the
persisted-operation SPI — is a claim about the whole repository, so it is checked at the
composition root rather than inside the leaf, next to the other GraphQL boundary rules in
`app-bootstrap`'s architecture suite.
이 ADR이 기대는 조건 — GraphQL leaf 밖의 어떤 것도 persisted operation SPI를 구현하지 않는다 — 은 저장소 전체에
대한 주장이다. 그래서 leaf 안이 아니라 조립 루트에서, `app-bootstrap` architecture suite의 다른 GraphQL 경계 규칙
옆에서 검사한다.
@@ -7,58 +7,51 @@
- 현재 정본: `docs/compatibility/grpc-support-matrix.md`
<!-- 머리 블록 끝 -->
# ADR-GRPC-001: The gRPC platform ships as a registered family, not as one adapter leaf
# ADR-GRPC-001: gRPC 플랫폼은 adapter leaf 하나가 아니라 등록된 family로 싣는다
- Status: accepted
- Date: 2026-08-30
- Scope: `:grpc:*`, `:grpc-advanced:*`, `src/config/architecture/modules.json`
- 상태: 채택
- 날짜: 2026-08-30
- 범위: `:grpc:*`, `:grpc-advanced:*`, `src/config/architecture/modules.json`
## Context
## 배경
The two source plans describe a type-safe gRPC execution platform with its own API, SPI, adapters and
composition root: fifteen Stable modules under `modules/grpc` and sixteen Advanced ones under
`modules/grpc-advanced`, on Gradle Kotlin DSL, in package `io.backend.skeleton.grpc`, against
Spring Boot 4.1.
두 원본 계획은 자기 API, SPI, 어댑터, 조립 루트를 가진 타입 안전 gRPC 실행 플랫폼을 설명한다: `modules/grpc` 아래
Stable 모듈 열다섯과 `modules/grpc-advanced` 아래 Advanced 모듈 열여섯, Gradle Kotlin DSL, 패키지
`io.backend.skeleton.grpc`, Spring Boot 4.1 기준.
None of that layout exists here. This repository uses Groovy DSL, a fail-closed module registry that
owns the leaf list, package root `dev.caskeleton`, and Spring Boot 4.0.8. The plans anticipate this:
their last Global Constraint says that when the repository structure differs, file paths are remapped
and the public contracts, invariants and test meanings are not changed.
그 배치는 여기 하나도 없다. 이 저장소는 Groovy DSL, leaf 목록을 가진 실패하면 닫히는 모듈 registry, 패키지 루트
`dev.caskeleton`, Spring Boot 4.0.8을 쓴다. 계획은 이것을 예상한다: 마지막 Global Constraint가, 저장소 구조가 다르면
파일 경로를 다시 대응시키고 공개 계약·불변식·시험의 뜻은 바꾸지 않는다고 말한다.
Two shapes were available. Fold the platform into the existing `:adapter:inbound:grpc` leaf as
packages — which is what the JPA, GraphQL, WebSocket and HTTP platforms did here — or register it as
a family the way `messaging:*` is registered.
고를 수 있는 모양은 둘이었다. 플랫폼을 기존 `:adapter:inbound:grpc` leaf에 패키지로 접어 넣기 — JPA, GraphQL,
WebSocket, HTTP 플랫폼이 여기서 그렇게 했다 — 또는 `messaging:*`를 등록한 방식대로 family로 등록하기.
## Decision
## 결정
Register it as a family: twelve Stable leaves under `src/grpc/` and six Advanced ones under
`src/grpc-advanced/`.
family로 등록한다: `src/grpc/` 아래 Stable leaf 열둘과 `src/grpc-advanced/` 아래 Advanced leaf 여섯.
The deciding property is that this is not a layer of this application. Root `CLAUDE.md` already
describes `messaging:*` as "a vendored messaging platform: a product with its own API, SPI, adapters
and composition boundary, not a layer of this application", and the gRPC platform is the same shape
for the same reason — the application is meant to reach it the way it reaches a library, through an
application-owned port. The four platforms that became packages are all layers of this application;
this one is not.
결정을 가른 성질은 이것이 이 애플리케이션의 계층이 아니라는 점이다. 루트 `CLAUDE.md`는 이미 `messaging:*`를 "a
vendored messaging platform: a product with its own API, SPI, adapters and composition boundary, not a layer of this
application"(들여온 메시징 플랫폼: 자기 API, SPI, 어댑터, 조립 경계를 가진 제품이고 이 애플리케이션의 계층이
아니다)이라고 설명하고, gRPC 플랫폼은 같은 이유로 같은 모양이다 — 애플리케이션은 라이브러리에 닿듯, 애플리케이션이
가진 포트를 거쳐 그것에 닿아야 한다. 패키지가 된 네 플랫폼은 모두 이 애플리케이션의 계층이다. 이것은 아니다.
The split between `src/grpc/` and `src/grpc-advanced/` is not organisational. The Stable plan
requires that the Stable starter's build fail if it reaches an Advanced module, and separate Gradle
path prefixes make that a `verifyCleanArchitectureDependencies` failure rather than a review note:
`grpc-spring-boot-starter`'s registry entry names no advanced id, and it cannot acquire one silently.
`src/grpc/`와 `src/grpc-advanced/`의 분리는 정리용이 아니다. Stable 계획은 Stable starter의 빌드가 Advanced 모듈에
닿으면 실패해야 한다고 요구하고, Gradle 경로 접두어를 따로 두면 그것이 리뷰 메모가 아니라
`verifyCleanArchitectureDependencies` 실패가 된다: `grpc-spring-boot-starter`의 registry 항목은 advanced id를 하나도
대지 않고, 소리 없이 얻을 수도 없다.
## Consequences
## 결과
**The registry grew from 44 leaves to 62.** That is a large registry change, made deliberately and in
one place. Every new leaf is `runtime_memberships: []`, so nothing ships until a second, explicit
decision moves it.
**registry가 leaf 44개에서 62개로 늘었다.** 큰 registry 변경이고, 일부러 한곳에서 했다. 새 leaf는 모두
`runtime_memberships: []`라서, 두 번째로 명시한 결정이 옮기기 전까지 아무것도 실리지 않는다.
**The advanced boundary is checked twice.** Once by the registry at build time, and once by
`GrpcStableBuildInvariant` at runtime, because a fat jar or a shaded artifact is assembled by
something the registry never sees.
**advanced 경계는 두 번 검사한다.** 빌드 때 registry가 한 번, 런타임에 `GrpcStableBuildInvariant`가 한 번. fat jar나
shaded artifact는 registry가 보지 못하는 무언가가 조립하기 때문이다.
**Four testkit modules became four test lanes.** The plan's split exists so in-process results cannot
be mistaken for network results; this repository expresses that with `ca.strict-test-lane`, whose
lanes fail when they discover nothing and never serve an up-to-date result. `GrpcEvidenceGrade` keeps
the same rule inside the code, so a report cannot cite a contract run as transport evidence.
**testkit 모듈 넷은 시험 lane 넷이 됐다.** 계획이 나눈 이유는 프로세스 안 결과를 네트워크 결과로 착각하지 못하게
하려는 것이다. 이 저장소는 그것을 `ca.strict-test-lane`으로 나타낸다. 그 lane은 아무것도 찾지 못하면 실패하고,
up-to-date 결과를 내주지 않는다. `GrpcEvidenceGrade`가 코드 안에서 같은 규칙을 지키므로, 보고서가 계약 실행을 전송
증거로 인용할 수 없다.
**Codegen is not wired.** See ADR-GRPC-002.
**codegen은 배선하지 않았다.** ADR-GRPC-002를 본다.
@@ -8,74 +8,65 @@
- 대체됨: `docs/capability-status.md`
<!-- 머리 블록 끝 -->
# ADR-GRPC-002: Schema governance runs without protoc and without the Buf CLI
# ADR-GRPC-002: schema 관리는 protoc 없이, Buf CLI 없이 돈다
- Status: **superseded (2026-09-28)** by owner decision 18 of the 2026-09-25 review follow-up
- Date: 2026-08-30
- Scope: `:grpc:grpc-proto-contract`, `:grpc:grpc-codegen` (both removed)
- 상태: **대체됨(2026-09-28)** — 2026-09-25 리뷰 후속의 소유자 결정 18
- 날짜: 2026-08-30
- 범위: `:grpc:grpc-proto-contract`, `:grpc:grpc-codegen`(둘 다 지움)
> **Superseded.** The regex `.proto` validator and the Java re-implementation of Buf's rules were
> deleted. The schema now lives in `:grpc:grpc-contract` (`src/grpc/grpc-contract/src/main/proto`),
> compiled by the Gradle protobuf plugin (`com.google.protobuf`, version pinned in
> `src/gradle/libs.versions.toml`; protoc and the protobuf-java runtime are both `protobufGrpc`).
> Generated sources are excluded from Spotless, Checkstyle and Error Prone in that leaf only.
> `buf lint` and `buf breaking` (`src/grpc/grpc-contract/buf.yaml`, STANDARD lint, FILE breaking)
> run in CI, job `grpc-proto-buf` in `.github/workflows/ci-quality-gates.yml`. The proto organization
> is `caskeleton` (was `hyeonworks`). The text below is kept as the record of the original decision.
> **대체됨.** 정규식 `.proto` 검증기와 Buf 규칙의 Java 재구현은 지웠다. schema는 이제 `:grpc:grpc-contract`
> (`src/grpc/grpc-contract/src/main/proto`)에 있고 Gradle protobuf 플러그인(`com.google.protobuf`, 버전은
> `src/gradle/libs.versions.toml`에 고정. protoc와 protobuf-java runtime은 둘 다 `protobufGrpc`)이 컴파일한다. 생성된
> 소스는 그 leaf에서만 Spotless, Checkstyle, Error Prone에서 뺀다. `buf lint`와 `buf breaking`
> (`src/grpc/grpc-contract/buf.yaml`, STANDARD lint, FILE breaking)은 CI의 `.github/workflows/ci-quality-gates.yml`
> job `grpc-proto-buf`에서 돈다. proto organization은 `caskeleton`이다(예전에는 `hyeonworks`). 아래 글은 원래 결정의
> 기록으로 남긴다.
## Context
## 배경
Stable Tasks 8 through 11 require proto style rules, Buf format/lint/breaking governance, a single
Java codegen owner, and a descriptor artifact whose consumer-compile result gates a release.
Stable Task 8부터 11은 proto 문체 규칙, Buf format·lint·breaking 관리, Java codegen 소유자 하나, 그리고 쓰는 쪽
컴파일 결과가 릴리스를 막는 descriptor artifact를 요구한다.
Two of the tools those tasks name are absent from this toolchain. The Buf CLI is not installed. And
`protoc` is available through the Gradle protobuf plugin, but every leaf in this repository passes
spotless with google-java-format, checkstyle, SpotBugs at HIGH confidence, Error Prone and `-Werror`
— and generated protobuf sources pass none of them. Turning codegen on means excluding a source set
from five quality gates.
그 Task가 이름을 대는 도구 중 둘이 이 toolchain에 없다. Buf CLI는 설치돼 있지 않다. 그리고 `protoc`는 Gradle
protobuf 플러그인으로 쓸 수 있지만, 이 저장소의 모든 leaf는 google-java-format을 쓴 spotless, checkstyle, HIGH
confidence의 SpotBugs, Error Prone, `-Werror`를 통과하는데 — 생성된 protobuf 소스는 그중 어느 것도 통과하지 못한다.
codegen을 켜면 source set 하나를 품질 게이트 다섯에서 빼야 한다.
There is precedent for such an exclusion: the `jmh` source set has `spotbugsJmh` and `checkstyleJmh`
disabled and Error Prone off. So the carve-out is available. It is also a decision about the quality
baseline of a leaf, taken for one task, and outside what this work was asked to change.
그런 예외에는 선례가 있다: `jmh` source set은 `spotbugsJmh`와 `checkstyleJmh`를 끄고 Error Prone도 끈다. 그러니 빼는
길은 있다. 하지만 그것은 Task 하나를 위해 leaf의 품질 기준선에 대해 내리는 결정이고, 이 일이 바꾸라고 받은 범위
밖이다.
`adapter:inbound:grpc` also carries a recorded decision in the opposite direction: its `CLAUDE.md`
forbids the protobuf plugin and `.proto` in that leaf, on the grounds that a consuming feature module
should own its schema.
`adapter:inbound:grpc`에도 반대 방향으로 기록된 결정이 있다: 그 `CLAUDE.md`는 쓰는 기능 모듈이 자기 schema를 가져야
한다는 이유로 그 leaf에서 protobuf 플러그인과 `.proto`를 금지한다.
## Decision
## 결정
Commit the `.proto` sources and implement every rule the tasks require as executable Java, with no
protoc run and no Buf CLI invocation.
`.proto` 소스를 커밋하고, Task가 요구하는 모든 규칙을 protoc 실행도 Buf CLI 호출도 없이 실행되는 Java로 구현한다.
`GrpcProtoContractValidator` reads `.proto` text and enforces proto3 syntax, the
`{organization}.{domain}.v{major}` package rule, `java_multiple_files`, a generated Java package
disjoint from the hand-written one, `_UNSPECIFIED` enum zero values, `reserved` declarations checked
against a supplied removal history, a well-known-type allowlist and a map-field allowlist. It runs
against the committed schema in its own test, so the shipped `.proto` files are live rather than
decorative.
`GrpcProtoContractValidator`는 `.proto` 글을 읽고 다음을 강제한다: proto3 문법, `{organization}.{domain}.v{major}`
패키지 규칙, `java_multiple_files`, 손으로 쓴 것과 겹치지 않는 생성 Java 패키지, `_UNSPECIFIED` enum 0값, 받은 삭제
이력과 대조한 `reserved` 선언, well-known type 허용 목록, map 필드 허용 목록. 자기 시험에서 커밋한 schema에 대고
돌므로, 출하하는 `.proto` 파일은 장식이 아니라 살아 있다.
`GrpcBufPolicy` fixes the breaking gate at Buf's `FILE` category and names the four lifecycle stages
a compliant pipeline registers. `GrpcCodegenManifest` fixes one codegen owner and refuses a literal
generator version. `GrpcDescriptorArtifact`, `GrpcConsumerFixture` and `GrpcSchemaArtifactPublisher`
carry the schema hash, the descriptor digest and the per-consumer source-break report, and refuse a
publish that breaks a consumer or republishes a released version with different bytes.
`GrpcBufPolicy`는 breaking gate를 Buf의 `FILE` category로 고정하고, 규칙을 따르는 pipeline이 등록하는 lifecycle 단계
넷을 이름으로 댄다. `GrpcCodegenManifest`는 codegen 소유자를 하나로 고정하고 리터럴 생성기 버전을 거절한다.
`GrpcDescriptorArtifact`, `GrpcConsumerFixture`, `GrpcSchemaArtifactPublisher`는 schema hash, descriptor digest, 쓰는
쪽별 소스 깨짐 보고를 싣고, 쓰는 쪽을 깨뜨리는 게시나 이미 릴리스한 버전을 다른 바이트로 다시 게시하는 것을
거절한다.
The committed `buf.yaml` states the same rules, so running the CLI in an environment that has it
reaches the same verdict.
커밋한 `buf.yaml`도 같은 규칙을 적으므로, CLI가 있는 환경에서 돌리면 같은 판정에 닿는다.
## Consequences
## 결과
**The invariants are enforced; the process is not run.** Everything Tasks 8 to 11 are about — which
schema changes are refused, which consumer breaks block a release, who owns generation — is a
build-checkable rule here. What is missing is the protoc invocation and the Buf binary.
**불변식은 강제하고, 과정은 돌리지 않는다.** Task 8부터 11이 다루는 모든 것 — 어떤 schema 변경을 거절하는지, 어떤
쓰는 쪽 깨짐이 릴리스를 막는지, 생성을 누가 가지는지 — 이 여기서는 빌드로 검사하는 규칙이다. 빠진 것은 protoc
호출과 Buf 바이너리다.
**Turning codegen on is a bounded change.** `GrpcCodegenManifest.caSkeleton()` already names the
owner, the managed version source, the build-directory output paths and the disjoint package policy
that a real plugin configuration has to satisfy. The work is a source-set carve-out and a plugin
block, not a redesign.
**codegen을 켜는 것은 한계 있는 변경이다.** `GrpcCodegenManifest.caSkeleton()`이 이미 실제 플러그인 설정이 만족해야
할 소유자, 관리되는 버전 출처, 빌드 디렉터리 출력 경로, 겹치지 않는 패키지 정책을 이름으로 댄다. 할 일은 source set
예외와 플러그인 블록이지 재설계가 아니다.
**The fixtures use a text codec.** `GrpcTextCodec` gives the testkit a UTF-8 marshaller so the
in-process and Netty lanes can exercise interceptors, status mapping, metadata limits and stream
sequencing without generated stubs. Those contracts are properties of the platform and the transport,
not of any message shape, so the substitution costs nothing — and the lanes run today rather than
after codegen lands.
**fixture는 텍스트 codec을 쓴다.** `GrpcTextCodec`이 testkit에 UTF-8 marshaller를 줘서, 프로세스 안 lane과 Netty
lane이 생성된 stub 없이 interceptor, status 대응, metadata 한계, stream 순서를 시험할 수 있다. 그 계약은 메시지
모양이 아니라 플랫폼과 전송의 성질이므로 바꿔 넣어도 잃는 것이 없다 — 그리고 lane이 codegen이 들어온 뒤가 아니라
오늘 돈다.
@@ -7,53 +7,48 @@
- 현재 정본: `docs/compatibility/grpc-support-matrix.md`
<!-- 머리 블록 끝 -->
# ADR-GRPC-003: Transport, business and stream evidence are three axes, and none implies another
# ADR-GRPC-003: 전송·업무·stream 증거는 세 축이고, 어느 것도 다른 것을 뜻하지 않는다
- Status: accepted
- Date: 2026-08-30
- Scope: `:grpc:grpc-core-api`, `:grpc:grpc-runtime` (was `grpc-policy`), `:grpc:grpc-testkit`
- 상태: 채택
- 날짜: 2026-08-30
- 범위: `:grpc:grpc-core-api`, `:grpc:grpc-runtime`(예전 `grpc-policy`), `:grpc:grpc-testkit`
## Context
## 배경
A failed RPC produces a status code, and a status code is not an answer to the question the caller
actually has. `DEADLINE_EXCEEDED` on a mutation does not say whether the mutation happened;
`UNAVAILABLE` after the request was sent does not say the server never saw it; response headers
arriving does not say a transaction committed.
실패한 RPC는 status code를 낸다. 그리고 status code는 호출자가 실제로 가진 질문의 답이 아니다. 변경 요청의
`DEADLINE_EXCEEDED`는 변경이 일어났는지 말하지 않는다. 요청을 보낸 뒤의 `UNAVAILABLE`은 서버가 그것을 한 번도 보지
않았다고 말하지 않는다. 응답 header가 도착했다고 트랜잭션이 커밋된 것은 아니다.
Every one of those is a place where a plausible inference produces a duplicate write or a lost one,
and none of them is visible in a test that only exercises the happy path.
그 하나하나가 그럴듯한 추론이 중복 쓰기나 잃은 쓰기를 낳는 자리이고, 성공 경로만 시험하는 시험에서는 하나도 보이지
않는다.
## Decision
## 결정
Model what happened as three independent axes, and refuse the inferences between them.
일어난 일을 서로 독립인 세 축으로 모델링하고, 축 사이의 추론을 거절한다.
`GrpcTransportEvidence` records what the client observed on the wire, and distinguishes `NOT_SENT` —
the client watched its own send fail — from `UNOBSERVED`, which is every other case where nothing is
known. `GrpcBusinessEvidence` records what the application confirmed, with `COMMIT_UNKNOWN` as a real
state rather than a placeholder. `GrpcStreamEvidence` is a sealed hierarchy whose non-empty cases all
carry a position, because "partial" without a last sequence can be neither resumed nor reconciled.
`GrpcTransportEvidence`는 client가 wire에서 본 것을 기록하고, `NOT_SENT` — client가 자기 보내기가 실패하는 것을 봤다
— 와, 아무것도 모르는 다른 모든 경우인 `UNOBSERVED`를 구별한다. `GrpcBusinessEvidence`는 애플리케이션이 확인한 것을
기록하고, `COMMIT_UNKNOWN`은 자리표시가 아니라 실제 상태다. `GrpcStreamEvidence`는 sealed 계층이고, 비어 있지 않은
경우는 모두 위치를 싣는다. 마지막 순번 없는 「부분」은 이어 가지도 맞춰 보지도 못하기 때문이다.
`GrpcExecutionEvidence` holds all three and rejects combinations nobody could have observed: a unary
call with stream evidence, or a request the client watched fail to send that nonetheless carries
business evidence. Promoting response headers to a confirmed commit is possible only by editing
`withResponseHeadersSeen`, which is one method rather than a plausible line in an interceptor.
`GrpcExecutionEvidence`는 셋을 모두 가지고, 아무도 볼 수 없었을 조합을 거절한다: stream 증거가 있는 unary 호출, 또는
client가 보내기 실패를 봤는데도 업무 증거를 실은 요청. 응답 header를 확인된 커밋으로 올리는 것은
`withResponseHeadersSeen`을 고쳐야만 할 수 있다. 그것은 interceptor 안의 그럴듯한 한 줄이 아니라 메서드 하나다.
`GrpcCompletionOutcome.forMutation` derives what a caller may conclude, and defaults
`DEADLINE_EXCEEDED` and post-send `UNAVAILABLE` on a mutation to `COMPLETION_UNKNOWN`.
`GrpcCompletionOutcome.forMutation`이 호출자가 결론 내릴 수 있는 것을 끌어내고, 변경 요청의 `DEADLINE_EXCEEDED`와
보낸 뒤의 `UNAVAILABLE`을 기본으로 `COMPLETION_UNKNOWN`으로 둔다.
The same types are used by the failure model and by the observation convention, so an incident has
one account of a call rather than two.
실패 모델과 관측 규약이 같은 타입을 쓰므로, 사고 때 호출 하나에 대한 설명이 둘이 아니라 하나다.
## Consequences
## 결과
**A whole class of retry bug becomes unrepresentable.** `GrpcRetryEligibility` reads all three axes
plus the idempotency profile; a caller cannot reach "retry" from a status alone because the status
alone is not an input.
**재시도 결함의 한 종류를 아예 나타낼 수 없게 된다.** `GrpcRetryEligibility`는 세 축 모두와 멱등성 profile을 읽는다.
status만으로는 입력이 아니므로, 호출자는 status만 보고 「재시도」에 닿을 수 없다.
**The fault lane has something to check.** `GrpcTransportEvidenceClassifier` turns a client's
observations into evidence and refuses to infer `NOT_SENT` from an unobserved state — and the lane
exercises it against a real connection dropped mid-call, not against a mock.
**장애 lane에 검사할 것이 생긴다.** `GrpcTransportEvidenceClassifier`가 client의 관찰을 증거로 바꾸고, 관찰하지 않은
상태에서 `NOT_SENT`를 추론하기를 거절한다 — 그리고 lane은 mock이 아니라 호출 중간에 끊은 실제 연결에 대고 그것을
시험한다.
**Callers must handle a third outcome.** `COMPLETION_UNKNOWN` is not a failure and not a success, and
a caller that treats it as either is wrong. `GrpcOperationStatusQuery` and `GrpcCompletionReconciler`
exist so that resolving it is a supported path rather than an exercise for the caller.
**호출자는 세 번째 결과를 다뤄야 한다.** `COMPLETION_UNKNOWN`은 실패도 성공도 아니고, 둘 중 하나로 다루는 호출자는
틀렸다. `GrpcOperationStatusQuery`와 `GrpcCompletionReconciler`는 그것을 푸는 일이 호출자에게 맡긴 숙제가 아니라
지원하는 경로가 되게 하려고 있다.
@@ -7,129 +7,106 @@
- 현재 정본: `docs/compatibility/grpc-support-matrix.md`
<!-- 머리 블록 끝 -->
# ADR-GRPC-004: One retry owner, and keyed mutations need a durable ledger
# ADR-GRPC-004: 재시도 소유자는 하나이고, 키가 있는 변경에는 durable 원장이 필요하다
- Status: accepted
- Date: 2026-08-30
- Scope: `:grpc:grpc-runtime` (was `grpc-policy`), `:grpc:grpc-operation-ledger-jpa`, `:grpc:grpc-core-api`
- 상태: 채택
- 날짜: 2026-08-30
- 범위: `:grpc:grpc-runtime`(예전 `grpc-policy`), `:grpc:grpc-operation-ledger-jpa`, `:grpc:grpc-core-api`
## Context
## 배경
Three layers can retry a gRPC call: the application, the channel's service config, and a service
mesh. Their effects multiply. Three attempts at each layer is twenty-seven requests for one call, and
the load arrives exactly when the dependency is already failing.
gRPC 호출을 재시도할 수 있는 계층이 셋 있다: 애플리케이션, channel의 service config, service mesh. 그 효과는 곱해진다.
계층마다 세 번 시도하면 호출 하나에 요청 스물일곱 개이고, 그 부하는 의존 대상이 이미 실패하고 있을 바로 그때 온다.
Separately, a mutation that is safe to repeat needs somewhere to record that it ran. Without one, a
retry after a lost response either duplicates the effect or drops it, and nothing distinguishes the
two afterwards.
따로, 되풀이해도 안전한 변경에는 그것이 돌았다는 기록을 둘 곳이 필요하다. 없으면 응답을 잃은 뒤의 재시도는 효과를
겹치게 하거나 버리게 되고, 나중에 둘을 구별할 것이 없다.
## Decision
## 결정
**Exactly one retry owner per channel.** `GrpcRetryOwner` has four values including `NONE`, which is a
decision rather than an omission. `GrpcServiceConfigPolicy` refuses an in-process retry entry when the
owner is the mesh or nobody, and `GrpcRetryOwnershipValidator` compares the service config's method
names against the policy catalog — a renamed method leaves its retry entry matching nothing, silently,
and the method then runs with channel defaults.
**channel마다 재시도 소유자는 정확히 하나다.** `GrpcRetryOwner`에는 `NONE`을 포함해 값이 넷 있고, `NONE`은 빠뜨림이
아니라 결정이다. `GrpcServiceConfigPolicy`는 소유자가 mesh이거나 아무도 아닐 때 프로세스 안 재시도 항목을 거절하고,
`GrpcRetryOwnershipValidator`는 service config의 메서드 이름을 정책 catalog와 대조한다 — 이름이 바뀐 메서드는 그 재시도
항목이 소리 없이 아무것과도 맞지 않게 되고, 그 메서드는 channel 기본값으로 돈다.
**Retry eligibility reads the method, the evidence and the status together.**
`GrpcRetryEligibility` refuses a non-idempotent method outright, refuses any call whose stream
delivered a prefix, and turns a `DEADLINE_EXCEEDED` or post-send `UNAVAILABLE` mutation into
"resolve the completion first" rather than a retry.
**재시도 자격은 메서드, 증거, status를 함께 읽는다.** `GrpcRetryEligibility`는 멱등이 아닌 메서드를 바로 거절하고,
stream이 앞부분을 전달한 호출을 모두 거절하며, 변경 요청의 `DEADLINE_EXCEEDED`나 보낸 뒤의 `UNAVAILABLE`을 재시도가
아니라 「먼저 완료를 풀어라」로 바꾼다.
**A keyed mutation is retryable only with both a caller key and a durable ledger.**
`GrpcOperationLedger` is a port in `grpc-core-api`, so the policy layer can require durable
idempotency without depending on a database. Its `claim` contract is a single atomic insert-or-read
against a unique constraint: `JpaGrpcOperationLedger` inserts first and reads on constraint violation,
because a read-then-insert implementation has a window exactly as wide as the race it closes and
passes every test that does not run two attempts concurrently.
**키가 있는 변경은 호출자 키와 durable 원장이 둘 다 있을 때만 재시도할 수 있다.** `GrpcOperationLedger`는
`grpc-core-api`의 포트라서, 정책 계층이 데이터베이스에 의존하지 않고 durable 멱등성을 요구할 수 있다. 그 `claim` 계약은
unique 제약에 대한 원자적 insert-or-read 하나다: `JpaGrpcOperationLedger`는 먼저 insert하고 제약 위반이면 읽는다.
read-then-insert 구현에는 그것이 닫으려는 경쟁만큼 넓은 창이 있고, 두 시도를 동시에 돌리지 않는 모든 시험을
통과하기 때문이다.
The identity is caller fingerprint plus full method plus hashed key. All three are load-bearing:
without the caller, one tenant's key suppresses another's write; without the method, a key reused
across operations makes the second a replay of the first.
identity는 호출자 fingerprint + 전체 메서드 + hash한 키다. 셋 모두 꼭 필요하다: 호출자가 없으면 한 테넌트의 키가 다른
테넌트의 쓰기를 막는다. 메서드가 없으면 operation 사이에서 다시 쓴 키 때문에 둘째가 첫째의 재생이 된다.
## Consequences
## 결과
**A budget bounds retries as a fraction of traffic.** `GrpcRetryBudget` degrades to roughly no
retries when everything is failing, which is the behaviour that lets a dependency recover.
**예산이 재시도를 traffic의 비율로 묶는다.** `GrpcRetryBudget`은 모든 것이 실패할 때 재시도가 거의 없는 쪽으로
떨어진다. 그것이 의존 대상이 회복하게 하는 동작이다.
**The ledger and the mutation should commit together.** `JpaGrpcOperationLedger` carries no
transaction annotations, deliberately: a `REQUIRES_NEW` would put the claim in its own transaction and
reintroduce the window where the write is durable and the claim is not.
**원장과 변경은 함께 커밋해야 한다.** `JpaGrpcOperationLedger`는 일부러 트랜잭션 애너테이션을 달지 않는다:
`REQUIRES_NEW`는 claim을 자기 트랜잭션에 넣어서, 쓰기는 durable한데 claim은 아닌 창을 다시 들인다.
**A claim expires instead of blocking its key forever** (review 2026-11-01, 03-10). A claim still
`IN_PROGRESS` after the claim TTL is presumed abandoned by a dead owner, and the next retry of the same
request takes it over with `GrpcOperationLedger.reclaimStale` — one conditional
`UPDATE … WHERE state = 'IN_PROGRESS' AND claimed_at < :cutoff`, so of two concurrent takeovers exactly
one wins, the same shape as `reclaimFailed`. The TTL is the `claimTtl` argument of
`GrpcIdempotencyInterceptor`, refused at construction when it is not longer than every keyed method's
deadline. Since the 03-11 follow-up the starter assembles the interceptor when
`app.grpc.platform.operation-ledger-enabled=true` and takes the TTL from
`app.grpc.platform.operation-ledger-claim-ttl` (default 5m); a TTL the constructor refuses fails startup
naming that key, and an enabled flag without a `GrpcOperationLedger` bean fails startup too.
**claim은 키를 영원히 막지 않고 만료된다**(review 2026-11-01, 03-10). claim TTL이 지난 뒤에도 `IN_PROGRESS`인 claim은
죽은 주인이 버린 것으로 보고, 같은 요청의 다음 재시도가 `GrpcOperationLedger.reclaimStale`로 넘겨받는다 — 조건부
`UPDATE … WHERE state = 'IN_PROGRESS' AND claimed_at < :cutoff` 하나라서, 동시에 넘겨받기 둘이 오면 정확히 하나가 이긴다.
`reclaimFailed`와 같은 모양이다. TTL은 `GrpcIdempotencyInterceptor`의 `claimTtl` 인자이고, 키가 있는 모든 메서드의
deadline보다 길지 않으면 만들 때 거절한다. 03-11 후속부터 starter는 `app.grpc.platform.operation-ledger-enabled=true`이면
interceptor를 조립하고 TTL을 `app.grpc.platform.operation-ledger-claim-ttl`(기본 5m)에서 가져온다. 생성자가 거절하는
TTL은 그 키 이름을 대며 기동을 실패시키고, `GrpcOperationLedger` bean 없이 flag를 켜도 기동이 실패한다.
The takeover is safe only because the commit is recorded in the mutation's own transaction: then a
claim still `IN_PROGRESS` means the mutation never committed. An adopter that commits them separately
turns an abandoned claim into an unknown outcome, and a takeover can run the mutation twice. A takeover
of an owner that is merely slow does the same, which is why the TTL must exceed the slowest keyed
method and not just its deadline.
넘겨받기가 안전한 것은 커밋을 변경 자신의 트랜잭션 안에서 기록하기 때문뿐이다: 그러면 아직 `IN_PROGRESS`인 claim은
변경이 한 번도 커밋되지 않았다는 뜻이다. 둘을 따로 커밋하는 채택자는 버려진 claim을 모르는 결과로 만들고, 넘겨받기가
변경을 두 번 돌릴 수 있다. 그저 느린 주인을 넘겨받아도 같은 일이 생긴다. 그래서 TTL은 deadline만이 아니라 키가 있는
가장 느린 메서드보다 길어야 한다.
Rejected: an owner token with a heartbeat lease (the outbox lease model) — needed only when a keyed
method can run longer than any fixed TTL; revisit when one exists. A sweeper job that deletes stale
rows — it needs a scheduler this family does not have, and deleting a claim makes the next retry a
fresh claim with no record that an attempt was abandoned.
버린 것: heartbeat lease를 단 owner token(outbox lease 모델) — 키가 있는 메서드가 어떤 고정 TTL보다 오래 돌 수 있을 때만
필요하다. 그런 메서드가 생기면 다시 본다. 낡은 행을 지우는 sweeper job — 이 family에 없는 scheduler가 필요하고,
claim을 지우면 다음 재시도가 시도를 버렸다는 기록 없는 새 claim이 된다.
**A taken-over owner is fenced by a claim token** (re-review 2026-11-03, RR-02-04). The owner a
takeover presumes dead may only be slow. Without knowing which attempt held the claim, its late
`markFailed` turned the new attempt's claim `FAILED_TERMINAL`, the next retry re-claimed it, and two
attempts ran the mutation at once; its late `markCommitted` committed beside the new attempt. Every
claim now carries a `GrpcClaimToken` (`claim_attempt`, migration V003): 1 for the first claim, one more
for each `reclaimFailed` or `reclaimStale`. `decide` returns it on `PROCEED`, and `recordCommit` /
`recordFailure` hand it back. A commit or a failure is one conditional
`UPDATE … WHERE state = 'IN_PROGRESS' AND claim_attempt = :attempt`: a commit by an attempt that lost
the claim is refused with an exception, so its business transaction rolls back; a failure by one is
ignored (`markFailed` returns false). The same conditional update closes the JPA commit race —
load-check-save let two commits that both read `IN_PROGRESS` both write; now exactly one matches.
A claim whose conflicting row is purged between insert and read retries the insert once instead of
failing the call.
**넘겨받긴 주인은 claim token으로 막는다**(re-review 2026-11-03, RR-02-04). 넘겨받기가 죽었다고 보는 주인은 그저 느릴
수 있다. 어느 시도가 claim을 쥐었는지 모르면, 그 주인의 늦은 `markFailed`가 새 시도의 claim을 `FAILED_TERMINAL`로
만들었고, 다음 재시도가 그것을 다시 claim해서 두 시도가 동시에 변경을 돌렸다. 늦은 `markCommitted`는 새 시도 옆에서
커밋했다. 이제 모든 claim은 `GrpcClaimToken`(`claim_attempt`, migration V003)을 싣는다: 첫 claim은 1이고,
`reclaimFailed`나 `reclaimStale`마다 하나씩 늘어난다. `decide`는 `PROCEED`에서 그것을 돌려주고, `recordCommit` /
`recordFailure`가 그것을 되돌려 준다. 커밋이나 실패는 조건부
`UPDATE … WHERE state = 'IN_PROGRESS' AND claim_attempt = :attempt` 하나다: claim을 잃은 시도의 커밋은 예외로 거절해서
그 업무 트랜잭션이 롤백되고, 그런 시도의 실패는 무시한다(`markFailed`가 false를 돌려준다). 같은 조건부 update가 JPA
커밋 경쟁도 닫는다 — load-check-save에서는 둘 다 `IN_PROGRESS`를 읽은 커밋 둘이 둘 다 썼다. 이제 정확히 하나만 맞는다.
insert와 read 사이에 충돌 행이 지워진 claim은 호출을 실패시키지 않고 insert를 한 번 다시 시도한다.
`release(identity, claimToken)` is fenced the same way (re-review 2026-11-03 round 2, RR-01-15): it is a
conditional `DELETE … WHERE state = 'IN_PROGRESS' AND claim_attempt = :attempt` and returns whether it
deleted. It used to delete by key alone, so any caller could erase the claim of the attempt that held
it, or a finished record a retry replays. The counter lives in the row, so a deleted row's key starts
again at attempt 1: the token separates the attempts of one row, not attempts across a delete. Both
deletions are limited accordingly — release only for a claim whose owner is known to be gone, purge
only for rows finished longer ago than any retry. Rejected: dropping `release` from the port
(`markFailed` then `reclaimFailed` keeps the counter, but a deployment that must free a key for a
different request has no other path), and a tombstone row that keeps the counter (a second state to
purge, for a window the two limits already close).
`release(identity, claimToken)`도 같은 방식으로 막는다(re-review 2026-11-03 round 2, RR-01-15): 조건부
`DELETE … WHERE state = 'IN_PROGRESS' AND claim_attempt = :attempt`이고 지웠는지를 돌려준다. 예전에는 키만으로 지웠기
때문에, 아무 호출자나 그것을 쥔 시도의 claim이나 재시도가 재생하는 끝난 레코드를 지울 수 있었다. counter는 행 안에
있으므로 지운 행의 키는 다시 attempt 1에서 시작한다: token은 행 하나의 시도들을 가르지, 삭제를 넘는 시도들을 가르지
않는다. 그래서 두 삭제를 모두 제한한다 — release는 주인이 사라졌다고 아는 claim에만, purge는 어떤 재시도보다 오래 전에
끝난 행에만. 버린 것: 포트에서 `release`를 빼기(`markFailed` 뒤 `reclaimFailed`는 counter를 지키지만, 다른 요청을 위해
키를 풀어야 하는 배포에는 다른 길이 없다), counter를 지키는 tombstone 행(지울 두 번째 상태가 생기는데, 그 창은 두 제한이
이미 닫는다).
Chosen over the claim moment as the token (`WHERE claimed_at = :claimedAt`), which needs no column:
PostgreSQL stores microseconds while `Instant` carries nanoseconds, so the token a caller holds and
the one stored can differ by rounding, and two processes' clocks can give two attempts the same
moment. The counter has neither problem. The heartbeat lease above stays rejected for the same reason
as before; the token fences without one.
token으로 claim 시각(`WHERE claimed_at = :claimedAt`)을 쓰는 안보다 이것을 골랐다. 시각은 열이 따로 필요 없지만,
PostgreSQL은 마이크로초를 저장하고 `Instant`는 나노초를 싣는다. 그래서 호출자가 쥔 token과 저장된 것이 반올림만큼
다를 수 있고, 두 프로세스의 시계가 두 시도에 같은 시각을 줄 수 있다. counter에는 두 문제가 다 없다. 위 heartbeat lease는
앞과 같은 이유로 계속 버린다. token은 그것 없이 막는다.
**What `operation-ledger-enabled=true` promises (03-11 (b), recorded 2026-11-03, RR-02-07).** The
2026-11-01 review offered (a) delete the flag and judge by whether a ledger bean exists, or (b) keep the
flag and have the starter assemble the decision function from it. (b) is kept: the assembly and the
TTL validation live in one place instead of in every adopter. (a) was rejected because it removes the
false promise only by removing the assembly with it. The limit stays and is stated where an operator
meets it: the starter builds no server, so the flag assembles the decision function only, and keys are
honoured once the adopter's `IDEMPOTENCY` stage interceptor or service adapter calls `decide` and
`recordCommit`. `GrpcPlatformStartupValidator`'s refusal for a keyed method says exactly that; a running
process cannot see whether the stage exists, so the validator does not claim to check it.
**`operation-ledger-enabled=true`가 약속하는 것(03-11 (b), 2026-11-03 기록, RR-02-07).** 2026-11-01 리뷰는 (a) flag를
지우고 원장 bean이 있는지로 판단하기와 (b) flag를 두고 starter가 그것으로 판정 함수를 조립하기를 내놓았다. (b)를
지킨다: 조립과 TTL 검증이 채택자마다가 아니라 한곳에 있다. (a)는 거짓 약속을 없애되 조립까지 함께 없애기 때문에
버렸다. 한계는 남고, 운영자가 그것을 만나는 곳에 적는다: starter는 서버를 만들지 않으므로 flag는 판정 함수만
조립하고, 채택자의 `IDEMPOTENCY` 단계 interceptor나 service adapter가 `decide`와 `recordCommit`을 부를 때 비로소 키가
지켜진다. 키가 있는 메서드에 대한 `GrpcPlatformStartupValidator`의 거절이 바로 그것을 말한다. 돌고 있는 프로세스는 그
단계가 있는지 볼 수 없으니, validator는 그것을 검사한다고 주장하지 않는다.
**Finished rows are purged after a retention; in-progress rows never are** (03-10 follow-up).
`GrpcOperationLedger.purgeCompletedBefore(cutoff, limit)` deletes at most `limit` `COMMITTED` or
`FAILED_TERMINAL` rows that completed before the cutoff, oldest first — on PostgreSQL one bounded
`DELETE … WHERE storage_key IN (SELECT … LIMIT … FOR UPDATE SKIP LOCKED)` served by the partial index
of migration V002. `GrpcOperationLedgerRetention.purgeExpired(now)` applies
`app.grpc.platform.operation-ledger-retention` (default 24h, the HTTP idempotency replay TTL) in
batches. A retry after its record was purged is a fresh claim and runs again, so the retention must
exceed the callers' retry window. The adopter schedules the purge; the starter assembles the policy
only, because a scheduled bean would force a scheduler onto every deployment and the starter cannot
know which replica should run it.
**끝난 행은 보존 기간 뒤에 지우고, 진행 중인 행은 절대 지우지 않는다**(03-10 후속).
`GrpcOperationLedger.purgeCompletedBefore(cutoff, limit)`는 cutoff 전에 끝난 `COMMITTED`나 `FAILED_TERMINAL` 행을 오래된
것부터 많아야 `limit`개 지운다 — PostgreSQL에서는 migration V002의 부분 index가 받쳐 주는 한계 있는
`DELETE … WHERE storage_key IN (SELECT … LIMIT … FOR UPDATE SKIP LOCKED)` 하나다.
`GrpcOperationLedgerRetention.purgeExpired(now)`가 `app.grpc.platform.operation-ledger-retention`(기본 24h, HTTP 멱등성
재생 TTL)을 batch로 적용한다. 레코드가 지워진 뒤의 재시도는 새 claim이고 다시 돈다. 그래서 보존 시간은 호출자의 재시도
창보다 길어야 한다. 지우기 일정은 채택자가 잡는다. starter는 정책만 조립한다. 예약된 bean은 모든 배포에 scheduler를
강요하고, starter는 어느 replica가 돌려야 하는지 알 수 없기 때문이다.
**A key reused for a different request is a caller error, not a duplicate.** The stored request
fingerprint turns that into `FAILED_PRECONDITION` rather than silently returning the first request's
answer.
**다른 요청에 다시 쓴 키는 중복이 아니라 호출자 오류다.** 저장된 요청 fingerprint가 그것을 소리 없이 첫 요청의 답을
돌려주는 대신 `FAILED_PRECONDITION`으로 바꾼다.
@@ -7,53 +7,46 @@
- 현재 정본: `docs/compatibility/grpc-support-matrix.md`
<!-- 머리 블록 끝 -->
# ADR-GRPC-005: One writer per stream, a bounded queue, and resume that refuses to guess
# ADR-GRPC-005: stream마다 쓰는 쪽 하나, 한계 있는 queue, 짐작하기를 거절하는 resume
- Status: accepted
- Date: 2026-08-30
- Scope: `:grpc:grpc-runtime` (was `grpc-policy`)
- 상태: 채택
- 날짜: 2026-08-30
- 범위: `:grpc:grpc-runtime`(예전 `grpc-policy`)
## Context
## 배경
`StreamObserver` is not thread-safe, and the failure when two producers call `onNext` concurrently is
not an exception — it is interleaved bytes, which a client decodes as a corrupt message or, worse, as
a valid one it should never have received.
`StreamObserver`는 thread-safe가 아니다. 두 producer가 동시에 `onNext`를 부를 때의 실패는 예외가 아니다 — 섞인 바이트이고,
client는 그것을 깨진 메시지로, 더 나쁘게는 받지 말았어야 할 유효한 메시지로 decode한다.
Two further properties of server streams are easy to get wrong in ways that look healthy. A consumer
that falls behind either terminates the stream or silently loses messages, and the second leaves a
client with a stream that appears fine and is missing changes. And a reconnect either continues from
a position the server can still replay, or skips whatever is no longer there.
server stream에는 건강해 보이는 방식으로 틀리기 쉬운 성질이 둘 더 있다. 뒤처진 소비자는 stream을 끝내거나 메시지를 소리
없이 잃는데, 둘째는 client에게 멀쩡해 보이지만 변경이 빠진 stream을 남긴다. 그리고 재연결은 서버가 아직 재생할 수 있는
위치에서 이어 가거나, 더는 없는 것을 건너뛴다.
## Decision
## 결정
**A bounded queue drained by one writer.** `GrpcSerializedStreamWriter` accepts messages from any
thread and hands them to the transport only from `flush`, which is synchronized. `write` returning
`ACCEPTED` means queued, and the name is deliberately not `sent`: the transport call returns as soon
as bytes are handed over, so no method here can honestly report delivery.
**쓰는 쪽 하나가 비우는 한계 있는 queue.** `GrpcSerializedStreamWriter`는 어느 스레드에서든 메시지를 받고, synchronized인
`flush`에서만 전송에 넘긴다. `write`가 `ACCEPTED`를 돌려주는 것은 줄 세웠다는 뜻이고, 이름을 일부러 `sent`로 하지
않았다: 전송 호출은 바이트를 넘기자마자 돌아오므로, 여기 어떤 메서드도 전달을 정직하게 알릴 수 없다.
**Both a message bound and a byte bound.** Either alone is unbounded in the other dimension.
`GrpcFlowControlPolicy` also takes the transport's own readiness signal, because a writer that relies
only on its queue bound produces as fast as it can allocate.
**메시지 한계와 바이트 한계를 둘 다.** 하나만 두면 다른 차원으로는 한계가 없다. `GrpcFlowControlPolicy`는 전송 자신의
readiness 신호도 받는다. queue 한계에만 기대는 쓰는 쪽은 메모리를 할당할 수 있는 만큼 빨리 만들어 내기 때문이다.
**Termination is the default for a slow consumer.** `GrpcSlowConsumerPolicy.DROP_OLDEST` exists for
feeds whose business meaning tolerates loss, and is not the default, because a client cannot detect
dropped messages: the sequence numbers it sees are the ones it was sent.
**느린 소비자에게는 끝내기가 기본이다.** `GrpcSlowConsumerPolicy.DROP_OLDEST`는 업무 뜻이 손실을 견디는 feed를 위해
있고 기본값이 아니다. client는 버려진 메시지를 알아챌 수 없기 때문이다: client가 보는 순번은 보내진 것의 순번이다.
**Resume is refused rather than faked.** `GrpcStreamGapDetector` requires a signed, unexpired token
whose caller and filter fingerprints match the current request, refuses one whose snapshot version
moved, and returns `FULL_RESYNC_REQUIRED` when the cursor predates retained history. `GrpcResumeToken`
carries a key id so the signing key can rotate without invalidating every outstanding token.
**resume은 꾸며 내지 않고 거절한다.** `GrpcStreamGapDetector`는 서명됐고 만료되지 않았으며 호출자·필터 fingerprint가
지금 요청과 맞는 token을 요구하고, snapshot version이 움직인 token을 거절하며, cursor가 보존한 이력보다 앞서면
`FULL_RESYNC_REQUIRED`를 돌려준다. `GrpcResumeToken`은 key id를 싣는다. 그래서 서명 키를 바꿔도 아직 쓰이는 모든 token이
무효가 되지 않는다.
## Consequences
## 결과
**A stream carries an envelope, not a bare payload.** `GrpcStreamEnvelope` holds the stream id,
generation, sequence, snapshot version and resume token, because resume, gap detection and drain all
need a position and a generation.
**stream은 맨 payload가 아니라 envelope을 싣는다.** `GrpcStreamEnvelope`은 stream id, generation, 순번, snapshot version,
resume token을 가진다. resume, 빈틈 찾기, 비우기가 모두 위치와 generation을 필요로 하기 때문이다.
**Four clocks, not one.** `GrpcStreamLifetimePolicy` separates setup deadline, idle timeout, max
duration and heartbeat interval, and refuses combinations where one can never fire. Merging any pair
produces a familiar bug: an idle timeout used as a max duration kills healthy busy streams.
**시계는 하나가 아니라 넷이다.** `GrpcStreamLifetimePolicy`는 준비 deadline, idle timeout, 최대 지속 시간, heartbeat
간격을 나누고, 하나가 절대 울릴 수 없는 조합을 거절한다. 어느 둘을 합치든 익숙한 결함이 나온다: 최대 지속 시간으로 쓴
idle timeout은 건강하게 바쁜 stream을 죽인다.
**A heartbeat is a liveness signal and nothing else.** It is not an application acknowledgement and
not an ordering guarantee; `GrpcStreamHeartbeat` says so in the place somebody would otherwise reuse
it.
**heartbeat는 살아 있다는 신호이고 그 밖의 무엇도 아니다.** 애플리케이션 확인 응답도 순서 보장도 아니다.
`GrpcStreamHeartbeat`가 누가 그것을 다르게 다시 쓸 법한 자리에서 그렇게 말한다.
@@ -7,71 +7,61 @@
- 현재 정본: `docs/compatibility/grpc-support-matrix.md`
<!-- 머리 블록 끝 -->
# ADR-GRPC-006: Stable discovery is DNS and static, and a Kubernetes profile names who balances
# ADR-GRPC-006: Stable discovery는 DNS와 static이고, Kubernetes profile은 누가 분산하는지 이름으로 댄다
- Status: accepted
- Date: 2026-08-31
- Scope: `:grpc:grpc-runtime` (was `grpc-discovery`, `grpc-client`)
- 상태: 채택
- 날짜: 2026-08-31
- 범위: `:grpc:grpc-runtime`(예전 `grpc-discovery`, `grpc-client`)
## Context
## 배경
A gRPC channel's discovery configuration has a failure mode with no runtime symptom: it works, and
it does not do what the dashboard says it does.
gRPC channel의 discovery 설정에는 런타임 증상이 없는 실패 방식이 있다: 동작은 하는데, 대시보드가 말하는 일을 하지 않는다.
The specific case is `round_robin` over a Kubernetes Service ClusterIP. The Service is one virtual
address, so the resolver returns one endpoint and the client-side balancer has nothing to rotate
across; kube-proxy picks a pod at connect time, and an HTTP/2 connection is long-lived, so every
request from that client goes to the same pod for the life of the connection. Nothing fails. The
configuration says `round_robin`, the metrics show requests spread across clients rather than pods,
and the conclusion "we have client-side load balancing" is wrong in a way nobody is prompted to
check.
구체적인 경우는 Kubernetes Service ClusterIP 위의 `round_robin`이다. Service는 가상 주소 하나라서 resolver가 endpoint 하나를
돌려주고 client 쪽 분산기는 돌려 가며 보낼 대상이 없다. kube-proxy는 연결할 때 pod를 고르고, HTTP/2 연결은 오래 살기
때문에, 그 client의 모든 요청이 연결이 사는 동안 같은 pod로 간다. 실패하는 것은 없다. 설정은 `round_robin`이라고 말하고,
metric은 요청이 pod가 아니라 client 사이에 퍼진 것을 보여 주며, 「client 쪽 부하 분산을 한다」는 결론은 아무도 확인할
계기가 없는 방식으로 틀렸다.
The mirror-image mistake is `pick_first` over a headless record, which pins a client to one pod out
of many.
거울상 실수는 headless record 위의 `pick_first`다. 많은 pod 중 하나에 client를 묶는다.
Separately, a service mesh changes who owns retries, and a deployment that adds mesh routing without
removing its own retry policy has two retriers whose effects multiply.
따로, service mesh는 재시도를 누가 가지는지 바꾸고, mesh 라우팅을 더하면서 자기 재시도 정책을 빼지 않은 배포는 효과가
곱해지는 재시도자 둘을 가진다.
## Decision
## 결정
**Stable resolvers are Static, DNS and Unix domain socket; Stable load balancing is `pick_first` and
`round_robin`.** `GrpcDiscoveryPolicyValidator.requireStableScheme` refuses `xds`, `consul`, `etcd`
and `eureka` by name, with a message saying they are Advanced capabilities with their own control
plane and promotion gate rather than unknown schemes.
**Stable resolver는 Static, DNS, Unix domain socket이고, Stable 부하 분산은 `pick_first`와 `round_robin`이다.**
`GrpcDiscoveryPolicyValidator.requireStableScheme`은 `xds`, `consul`, `etcd`, `eureka`를 이름으로 거절하고, 그것이 모르는
scheme이 아니라 자기 control plane과 승격 gate를 가진 Advanced capability라고 메시지로 말한다.
**The pairing is checked against the resolved address count, not against intent.**
`GrpcResolverProfile` carries `expectedAddressCount`, and `GrpcStableLoadBalancer.effective` answers
whether the policy distributes anything over that many endpoints. A `round_robin` profile over one
address is a reported violation whose message says it describes spreading that is not happening.
**짝 맞춤은 의도가 아니라 해석된 주소 수와 대조한다.** `GrpcResolverProfile`은 `expectedAddressCount`를 싣고,
`GrpcStableLoadBalancer.effective`가 그 수의 endpoint 위에서 정책이 무언가를 분산하는지 답한다. 주소 하나 위의
`round_robin` profile은 보고되는 위반이고, 그 메시지는 그것이 일어나지 않는 퍼뜨리기를 설명한다고 말한다.
**A Kubernetes deployment names its routing mode**, and the mode implies both the balancer and the
retry owner. `GrpcKubernetesRoutingMode` has three values — `K8S_VIP`, `K8S_HEADLESS`, `MESH` — and
`GrpcKubernetesProfile` refuses a mesh profile whose retry owner retries in-process.
**Kubernetes 배포는 자기 라우팅 모드를 이름으로 대고**, 그 모드가 분산기와 재시도 소유자를 둘 다 정한다.
`GrpcKubernetesRoutingMode`에는 값이 셋 있다 — `K8S_VIP`, `K8S_HEADLESS`, `MESH` — 그리고 `GrpcKubernetesProfile`은 재시도
소유자가 프로세스 안에서 재시도하는 mesh profile을 거절한다.
**A profile that carries long-lived streams must state a reconnect budget and a readiness drain
grace.** A stream pins a client to one pod for its whole life, so every rollout, eviction and
scale-down ends it. `GrpcKubernetesProfileValidator` additionally reports a VIP profile carrying
long streams, and a drain grace shorter than the reconnect budget — the second means the pod stops
serving before its clients have finished reconnecting elsewhere.
**오래 사는 stream을 싣는 profile은 재연결 예산과 readiness 비우기 유예를 밝혀야 한다.** stream은 사는 내내 client를 pod
하나에 묶으므로, 모든 rollout, eviction, scale-down이 그것을 끝낸다. `GrpcKubernetesProfileValidator`는 긴 stream을 싣는
VIP profile과, 재연결 예산보다 짧은 비우기 유예도 알린다 — 후자는 client가 다른 곳으로 재연결을 마치기 전에 pod가 응답을
멈춘다는 뜻이다.
**A DNS profile must refresh.** `GrpcResolverProfile` refuses a zero refresh interval on DNS,
because a channel that resolved once at startup keeps sending to addresses that stopped existing an
hour ago, and the resulting `UNAVAILABLE` looks like an unhealthy deployment long after the rollout
finished.
**DNS profile은 새로 고쳐야 한다.** `GrpcResolverProfile`은 DNS에서 새로 고침 간격 0을 거절한다. 기동 때 한 번 해석한
channel은 한 시간 전에 없어진 주소로 계속 보내고, 그 결과인 `UNAVAILABLE`은 rollout이 끝난 지 한참 뒤에도 건강하지 않은
배포처럼 보인다.
## Consequences
## 결과
**Two validators, not one.** `GrpcDiscoveryPolicyValidator` asks whether a balancer does anything
over the addresses it will see; `GrpcKubernetesProfileValidator` asks whether the deployment shape,
the retry owner and the stream obligations agree. A deployment can have a coherent resolver profile
and still have put retries in two places, so merging them would let one answer hide the other.
**validator는 하나가 아니라 둘이다.** `GrpcDiscoveryPolicyValidator`는 분산기가 자기가 볼 주소 위에서 무언가를 하는지
묻는다. `GrpcKubernetesProfileValidator`는 배포 모양, 재시도 소유자, stream 의무가 맞는지 묻는다. 배포는 resolver profile이
앞뒤가 맞으면서도 재시도를 두 곳에 둘 수 있다. 그래서 둘을 합치면 한 답이 다른 답을 가린다.
**`expectedAddressCount` has to come from somewhere.** It is a declared number, and a declaration can
be wrong. It is still better than the alternative, which is not comparing anything: a wrong
declaration is a wrong statement somebody wrote down, and a missing one is a question nobody asked.
`GrpcChannelProfileValidator` takes resolved counts where they are known at startup and skips the
check where they are not, rather than guessing and failing on a name that cannot be resolved yet.
**`expectedAddressCount`는 어딘가에서 와야 한다.** 선언한 숫자이고, 선언은 틀릴 수 있다. 그래도 아무것도 비교하지 않는
대안보다 낫다: 틀린 선언은 누가 적어 둔 틀린 말이고, 빠진 선언은 아무도 묻지 않은 질문이다.
`GrpcChannelProfileValidator`는 기동 때 알 수 있는 곳에서는 해석된 수를 받고, 알 수 없는 곳에서는 짐작해서 아직 해석할 수
없는 이름에서 실패하는 대신 검사를 건너뛴다.
**xDS is reachable, and not by this route.** It lives in `grpc-advanced` (package `resilience`/`xds`) behind its
capability flag and its production approval, and `GrpcXdsStartupGuard.advertisableAsStableSupport()`
returns false so the Stable support statement cannot widen quietly. See ADR-GRPC-ADV-001.
**xDS에는 닿을 수 있지만, 이 길로는 아니다.** xDS는 `grpc-advanced`(패키지 `resilience`/`xds`)에서 자기 capability flag와
운영 승인 뒤에 있고, `GrpcXdsStartupGuard.advertisableAsStableSupport()`가 false를 돌려주므로 Stable 지원 설명이 조용히
넓어질 수 없다. ADR-GRPC-ADV-001을 본다.
@@ -7,60 +7,51 @@
- 현재 정본: `docs/compatibility/grpc-advanced-support-matrix.md`
<!-- 머리 블록 끝 -->
# ADR-GRPC-ADV-001: Each advanced capability has its own flag, its own grade and its own promotion
# ADR-GRPC-ADV-001: advanced capability마다 자기 flag, 자기 등급, 자기 승격이 있다
- Status: accepted
- Date: 2026-08-30
- Scope: `:grpc-advanced:*`
- 상태: 채택
- 날짜: 2026-08-30
- 범위: `:grpc-advanced:*`
## Context
## 배경
The advanced plan covers sixteen capabilities that differ by orders of magnitude in what they bring
with them. gRPC-Web adds a proxy. Reactor adds a dependency. xDS adds a control plane, its outage
modes, its own security boundary and its own version skew. Hedging duplicates production traffic.
advanced 계획은 capability 열여섯을 다룬다. 그것들이 함께 가져오는 것은 몇 자릿수씩 다르다. gRPC-Web은 proxy를 더한다.
Reactor는 의존 하나를 더한다. xDS는 control plane, 그 장애 방식, 자기 보안 경계, 자기 버전 어긋남을 더한다. hedging은 운영
traffic을 겹친다.
Bundling them under one flag makes enabling the cheapest of those the same decision as enabling the
most consequential.
그것들을 flag 하나로 묶으면 가장 싼 것을 켜는 일이 가장 무거운 것을 켜는 일과 같은 결정이 된다.
## Decision
## 결정
**One flag per capability**, under `ca-skeleton.grpc.advanced.<capability>.enabled`, all off by
default.
**capability마다 flag 하나.** `ca-skeleton.grpc.advanced.<capability>.enabled` 아래에 있고, 기본은 모두 꺼짐이다.
**Four grades.** `ADVANCED_STABLE` starts on its flag; `EXPERIMENTAL` additionally needs a separate
production approval, because the flag says somebody wanted the feature and the approval says somebody
accepted that its failure modes are not fully characterised; `WATCH` cannot start at all; `DISABLED`
is withdrawn.
**등급 넷.** `ADVANCED_STABLE`은 flag로 시작한다. `EXPERIMENTAL`은 따로 운영 승인도 필요하다. flag는 누가 그 기능을 원했다는
뜻이고, 승인은 누가 그 장애 방식이 다 밝혀지지 않았음을 받아들였다는 뜻이기 때문이다. `WATCH`는 아예 시작할 수 없다.
`DISABLED`는 거둬들인 것이다.
`GrpcAdvancedModuleGuard` distinguishes the three refusals — flag unset, grade unstartable,
production unapproved — because the remedy differs in each case.
`GrpcAdvancedModuleGuard`는 세 거절 — flag 없음, 시작할 수 없는 등급, 운영 승인 없음 — 을 구별한다. 경우마다 고치는 법이
다르기 때문이다.
**Promotion evidence is per capability.** `GrpcAdvancedPromotionEvidence` is one record per
capability, so no promotion can drag another along;
`GrpcAdvancedPromotionGate.capabilitiesDraggedAlong` returns an empty list, and that is a tested
property rather than a claim. (2026-09-28: the gate classes were removed because nothing outside
their own tests called them — review 2026-09-24 S5-lead-4. The per-capability rule stands as a
review rule in `docs/runbooks/grpc-advanced-capabilities.md`.) Two thresholds: seven days of soak plus complete evidence for
`ADVANCED_STABLE`, thirty for a Stable default, because the second means every deployment gets the
capability's dependencies and its failure modes.
**승격 증거는 capability마다다.** `GrpcAdvancedPromotionEvidence`는 capability마다 record 하나라서, 어떤 승격도 다른 것을
끌고 가지 못한다. `GrpcAdvancedPromotionGate.capabilitiesDraggedAlong`은 빈 목록을 돌려주고, 그것은 주장이 아니라 시험한
성질이다. (2026-09-28: gate 클래스는 자기 시험 밖에서 부르는 것이 없어서 지웠다 — review 2026-09-24 S5-lead-4.
capability별 규칙은 `docs/runbooks/grpc-advanced-capabilities.md`의 리뷰 규칙으로 남는다.) 문턱은 둘이다:
`ADVANCED_STABLE`에는 7일 soak와 완전한 증거, Stable 기본값에는 30일. 후자는 모든 배포가 그 capability의 의존과 장애 방식을
받는다는 뜻이기 때문이다.
**Infrastructure is named per capability.** `GrpcAdvancedInfrastructureTestkit` records that
gRPC-Web needs a proxy, Servlet needs a container, xDS needs a stoppable control plane and Kotlin
needs a toolchain. A suite that runs without its infrastructure passes and establishes nothing, which
is worse than not having one.
**기반 시설은 capability마다 이름으로 댄다.** `GrpcAdvancedInfrastructureTestkit`은 gRPC-Web에는 proxy가, Servlet에는
container가, xDS에는 멈출 수 있는 control plane이, Kotlin에는 toolchain이 필요하다고 적는다. 기반 시설 없이 도는 suite는
통과하고 아무것도 세우지 않는다. 없는 것보다 나쁘다.
## Consequences
## 결과
**The Kotlin adapter fails closed here, and says why.** This repository has no Kotlin toolchain, so
`GrpcKotlinCompatibilityGate.supportableHere()` returns false. The four contract requirements — one
schema source, coroutine cancellation propagation, Flow backpressure inside the Stable bounds,
platform evidence types preserved — are checkable and are checked; only the compile lane is missing.
**Kotlin 어댑터는 여기서 실패하면 닫히고, 이유를 말한다.** 이 저장소에는 Kotlin toolchain이 없어서
`GrpcKotlinCompatibilityGate.supportableHere()`가 false를 돌려준다. 계약 요구 넷 — schema 출처 하나, coroutine 취소 전파,
Stable 한계 안의 Flow backpressure, 플랫폼 증거 타입 보존 — 은 검사할 수 있고 검사한다. 빠진 것은 compile lane뿐이다.
**Edition 2026 cannot be used however its watch report reads.** `GrpcEdition2026Guard` is not
conditional on the report, because letting a status record also authorise use means a schema moves
onto an edition the moment somebody marks four fields SUPPORTED, with no promotion decision, no
consumer migration and no ADR.
**Edition 2026은 그 watch 보고가 무어라 하든 쓸 수 없다.** `GrpcEdition2026Guard`는 보고에 따라 달라지지 않는다. 상태 기록이
사용까지 허락하게 두면, 누가 필드 넷을 SUPPORTED로 표시하는 순간 schema가 승격 결정도, 쓰는 쪽 옮기기도, ADR도 없이 그
edition으로 옮겨 가기 때문이다.
**xDS is not part of the Stable support statement.** It works, behind its flag and its approval;
`GrpcXdsStartupGuard.advertisableAsStableSupport()` returns false so a support matrix cannot widen
quietly.
**xDS는 Stable 지원 설명의 일부가 아니다.** flag와 승인 뒤에서 동작한다. `GrpcXdsStartupGuard.advertisableAsStableSupport()`가
false를 돌려주므로 support matrix가 조용히 넓어질 수 없다.
@@ -7,38 +7,34 @@
- 현재 정본: `docs/jpa/repository-adaptation.md`
<!-- 머리 블록 끝 -->
# ADR-JPA-001 — The domain owns the persistence model
# ADR-JPA-001 — 영속 모델은 도메인이 가진다
- Status: Accepted
- Date: 2026-08-11
- Design: §10.1, §23.3
- 상태: 채택
- 날짜: 2026-08-11
- 설계: §10.1, §23.3
## Context
## 배경
A persistence platform can either own the repository abstraction — a `GenericRepository<T, ID>`
every aggregate inherits — or provide only the pieces domains assemble themselves.
영속 플랫폼은 repository 추상 — 모든 aggregate가 상속하는 `GenericRepository<T, ID>` — 을 가질 수도 있고, 도메인이 스스로
조립할 조각만 줄 수도 있다.
## Decision
## 결정
The domain owns entities, embeddables, repositories, queries, index requirements, and lock,
soft-delete, and audit policy. The platform provides no generic CRUD repository and no base
repository. `JpaRepositoryFragmentSupport` exists, has no `save`, `findById`, `findAll`, or
`delete`, and is enforced not to acquire them.
엔티티, embeddable, repository, query, index 요구, lock·soft-delete·감사 정책은 도메인이 가진다. 플랫폼은 범용 CRUD
repository도 기반 repository도 주지 않는다. `JpaRepositoryFragmentSupport`는 있지만 `save`, `findById`, `findAll`, `delete`가
없고, 그것을 얻지 못하게 강제한다.
## Consequences
## 결과
A generic base repository has one property that looks like a benefit and is not: every aggregate
gets the same operations. That means each aggregate is offered operations that may be wrong for it —
a `delete` on an append-only ledger, a `findAll` on a table that will never be small — and, worse,
one aggregate's later requirement changes the shared base and therefore changes behaviour for
aggregates nobody reviewed.
범용 기반 repository에는 이득처럼 보이지만 이득이 아닌 성질이 하나 있다: 모든 aggregate가 같은 operation을 받는다. 그러면
aggregate마다 자기에게 틀릴 수 있는 operation을 받게 된다 — append-only 원장의 `delete`, 결코 작지 않을 테이블의 `findAll` —
그리고 더 나쁘게, 한 aggregate의 나중 요구가 공용 기반을 바꾸고 그래서 아무도 리뷰하지 않은 aggregate의 동작을 바꾼다.
Spring Data already implements CRUD. Re-implementing it adds a layer whose only function is to be
harder to opt out of.
Spring Data는 이미 CRUD를 구현한다. 그것을 다시 구현하면 빠져나가기 더 어렵게 만드는 것만이 하는 일인 계층이 더해진다.
The cost is a small amount of repetition: each domain declares the repository interface it needs.
That repetition is the thing that makes each aggregate's persistence surface reviewable.
비용은 약간의 되풀이다: 도메인마다 필요한 repository 인터페이스를 선언한다. 그 되풀이가 aggregate마다 영속 surface를 리뷰할
수 있게 만든다.
## Enforcement
## 강제
`JpaArchitectureRules.noGenericRepository()`; `JpaRepositoryFragmentSupportTest`.
`JpaArchitectureRules.noGenericRepository()`, `JpaRepositoryFragmentSupportTest`.
+25 -29
View File
@@ -8,43 +8,39 @@
- 대체됨: `docs/capability-status.md`
<!-- 머리 블록 끝 -->
# ADR-JPA-002 — Retry re-runs the whole use case
# ADR-JPA-002 — 재시도는 유스케이스 전체를 다시 돌린다
- Status: Superseded (2026-09-25) — the retry engine this ADR describes
(`FullTransactionRetryCoordinator`, `JpaTransactionExecutor`) was removed. `SpringTransactionPort`
retries nothing; a caller that retries still re-runs the whole use case, which is the part of this
decision that stands. The last commit is in `docs/capability-status.md`.
- Date: 2026-08-11
- Design: §19.2
- 상태: 대체됨(2026-09-25) — 이 ADR이 설명하는 재시도 엔진(`FullTransactionRetryCoordinator`, `JpaTransactionExecutor`)은
지웠다. `SpringTransactionPort`는 아무것도 재시도하지 않는다. 재시도하는 호출자는 여전히 유스케이스 전체를 다시 돌리고,
이 결정 중 그 부분이 남는다. 마지막 커밋은 `docs/capability-status.md`에 있다.
- 날짜: 2026-08-11
- 설계: §19.2
## Context
## 배경
Optimistic conflicts, deadlocks, and serialization failures are recoverable. The question is what
unit gets retried: the failed statement, the transaction, or the use case.
낙관적 충돌, 교착, serialization 실패는 회복할 수 있다. 질문은 무엇을 단위로 재시도하느냐다: 실패한 문장, 트랜잭션, 또는
유스케이스.
## Decision
## 결정
The whole use case, in a new transaction with a new Persistence Context.
`FullTransactionRetryCoordinator` re-enters `JpaTransactionExecutor` for every attempt, and the
retry advice is ordered outside Spring's transaction advice so each attempt begins a new
transaction.
유스케이스 전체를, 새 Persistence Context를 가진 새 트랜잭션에서. `FullTransactionRetryCoordinator`는 시도마다
`JpaTransactionExecutor`에 다시 들어가고, 재시도 advice는 Spring 트랜잭션 advice 바깥으로 순서를 잡아 시도마다 새
트랜잭션을 시작한다.
## Consequences
## 결과
Statement-level retry is wrong for exactly the failures being retried. An optimistic conflict means
the state the attempt computed against is no longer the committed state; re-issuing the same
statement computes the same wrong answer against a version that has moved on. The domain rules have
to run again over reloaded data, which means the whole use case.
문장 단위 재시도는 바로 재시도하려는 실패에 틀린 답이다. 낙관적 충돌은 시도가 계산의 바탕으로 삼은 상태가 더는 커밋된
상태가 아니라는 뜻이다. 같은 문장을 다시 내면 이미 움직인 version에 대고 같은 틀린 답을 계산한다. 도메인 규칙은 다시 읽은
데이터 위에서 다시 돌아야 하고, 그것은 유스케이스 전체라는 뜻이다.
Reusing the Persistence Context would be equally wrong: the second attempt would read the first
attempt's stale entities out of the first-level cache. And with the advice ordering inverted, the
retry loop would run inside one transaction that has already been marked rollback-only, so the
second attempt fails immediately without executing anything.
Persistence Context를 다시 쓰는 것도 똑같이 틀렸다: 두 번째 시도가 1차 cache에서 첫 시도의 낡은 엔티티를 읽게 된다. 그리고
advice 순서가 뒤집히면 재시도 반복문이 이미 rollback-only로 표시된 트랜잭션 하나 안에서 돌아서, 두 번째 시도가 아무것도
실행하지 않고 바로 실패한다.
The cost is that a retryable use case must be safe to run from scratch — no irreversible external
effect before the commit. `IrreversibleSideEffectContext` lets a use case declare when that does not
hold, and the policy then refuses to retry it whatever budget remains.
비용은 재시도할 수 있는 유스케이스가 처음부터 돌려도 안전해야 한다는 것이다 — 커밋 전에 되돌릴 수 없는 외부 효과가 없어야
한다. `IrreversibleSideEffectContext`로 유스케이스가 그렇지 않을 때를 선언할 수 있고, 그러면 정책은 남은 예산이 얼마든 그
재시도를 거절한다.
## Enforcement
## 강제
`FullTransactionRetryCoordinatorTest`; `RetryableJpaTransactionInterceptor.DEFAULT_ORDER`.
`FullTransactionRetryCoordinatorTest`, `RetryableJpaTransactionInterceptor.DEFAULT_ORDER`.
+32 -40
View File
@@ -7,57 +7,49 @@
- 현재 정본: `docs/jpa/transaction-guide.md`
<!-- 머리 블록 끝 -->
# ADR-JPA-003 — Completion unknown is never retried
# ADR-JPA-003 — 완료를 모름은 절대 재시도하지 않는다
- Status: Accepted; amended 2026-09-25 — `TransactionCompletionResolver`, `CommitFailureClassifier`
and the retry engine were removed. The invariant holds because `SpringTransactionPort`, the only
transaction engine, retries nothing; enforcement below is updated accordingly.
- Date: 2026-08-11
- Design: §17
- 상태: 채택. 2026-09-25 보완 — `TransactionCompletionResolver`, `CommitFailureClassifier`, 재시도 엔진을 지웠다. 유일한
트랜잭션 엔진인 `SpringTransactionPort`가 아무것도 재시도하지 않으므로 불변식이 지켜진다. 아래 강제 절도 그에 맞게
고쳤다.
- 날짜: 2026-08-11
- 설계: §17
## Context
## 배경
A connection can break while a commit is in flight. The server may have committed; the
acknowledgement may simply have been lost. The driver cannot tell the two apart.
커밋이 진행 중일 때 연결이 끊길 수 있다. 서버가 커밋했을 수도 있고, 확인 응답만 잃었을 수도 있다. driver는 둘을 구별하지
못한다.
## Decision
## 결정
`TransactionCompletionUnknownException` is never retried, automatically or otherwise. It is
produced only by a failure observed while the transaction phase is `COMMITTING`, and only for
SQLSTATE `40003`, a connection-class (`08*`) state, or a transport break. Recovery is
domain-specific reconciliation.
`TransactionCompletionUnknownException`은 자동이든 아니든 절대 재시도하지 않는다. 트랜잭션 단계가 `COMMITTING`인 동안 본
실패에서만, 그리고 SQLSTATE `40003`, 연결 class(`08*`) 상태, 전송 끊김에 대해서만 만든다. 회복은 도메인별 맞춰 보기다.
## Consequences
## 결과
Retrying a possibly-committed write is the most damaging thing this platform could do: a duplicate
payment, a duplicate order, a double decrement. There is no budget or backoff that makes it safe,
because the failure is epistemic rather than transient.
커밋됐을지 모르는 쓰기를 재시도하는 것이 이 플랫폼이 할 수 있는 가장 해로운 일이다: 중복 결제, 중복 주문, 두 번 깎기.
실패가 일시적인 것이 아니라 알 수 없는 것이라서, 그것을 안전하게 만드는 예산이나 backoff는 없다.
The invariant is enforced at the type level rather than by policy alone. `JpaFailureContext` refuses
to construct a retryable completion-unknown context, and the exception rebuilds its context through
the safe factory whatever it is handed. A future policy bug therefore cannot produce an unsafe
retry — the value it would need does not exist.
불변식은 정책만이 아니라 타입 수준에서 강제한다. `JpaFailureContext`는 재시도할 수 있는 completion-unknown 문맥을 만들기를
거절하고, 예외는 무엇을 받든 안전한 factory로 자기 문맥을 다시 만든다. 그래서 나중의 정책 결함이 안전하지 않은 재시도를 낳을
수 없다 — 그것에 필요한 값이 존재하지 않는다.
The rule is deliberately narrow in the other direction too. Classifying every connection failure as
completion-unknown would push ordinary pool exhaustion and server restarts into the reconciliation
queue, which trains operators to clear that queue without reading it — and then the one entry that
mattered gets cleared with the rest.
규칙은 반대 방향으로도 일부러 좁다. 모든 연결 실패를 completion-unknown으로 분류하면 보통의 pool 고갈과 서버 재시작이 맞춰
보기 queue로 밀려 들어가고, 그것은 운영자에게 그 queue를 읽지 않고 비우도록 길들인다 — 그러면 중요했던 항목 하나가 나머지와
함께 지워진다.
The cost is that the domain must supply the resolver. The platform cannot: only the domain knows
which idempotency record, business row, or outbox entry proves the write happened.
비용은 도메인이 resolver를 줘야 한다는 것이다. 플랫폼은 할 수 없다: 어떤 멱등성 레코드, 업무 행, outbox 항목이 쓰기가
일어났음을 증명하는지는 도메인만 안다.
## Enforcement
## 강제
Production path: `SpringTransaction` records when the action has returned in a write transaction it
began; a failure after that point goes through
`PersistenceExceptionTranslator#translateCommitFailure`, which builds this exception for `08*`,
`40003`, a vendor termination state (`SqlStateErrorMapping#commitOutcomeUnknownStates`, PostgreSQL
`57P01`/`57P02`) or a transport break. Hibernate's flush inside the commit is not separated from the
COMMIT itself, so a connection lost during that flush is also reported as unknown — the safe side.
Until review 04-01 (2026-11-01) nothing constructed the exception and a commit-phase `08*` reached
callers as the retryable `DB_UNAVAILABLE`.
운영 경로: `SpringTransaction`은 자기가 시작한 쓰기 트랜잭션에서 action이 돌아온 때를 기록한다. 그 뒤의 실패는
`PersistenceExceptionTranslator#translateCommitFailure`를 거치고, 그것이 `08*`, `40003`, vendor 종료 상태
(`SqlStateErrorMapping#commitOutcomeUnknownStates`, PostgreSQL `57P01`/`57P02`), 전송 끊김에 대해 이 예외를 만든다. 커밋 안의
Hibernate flush는 COMMIT 자체와 나뉘지 않으므로, 그 flush 중에 잃은 연결도 모름으로 알린다 — 안전한 쪽이다. review
04-01(2026-11-01) 전까지는 아무것도 이 예외를 만들지 않았고, 커밋 단계의 `08*`가 재시도할 수 있는 `DB_UNAVAILABLE`로 호출자에게
닿았다.
`JpaFailureContextTest`; `SpringTransactionTest`; `PersistenceExceptionTranslatorTest`;
`JpaFailureContextTest`, `SpringTransactionTest`, `PersistenceExceptionTranslatorTest`,
`PostgreSqlTransactionIntegrationTest#connectionLossDuringCommitSurfacesAsCompletionUnknownAndIsNeverRetried`
(asserts `DB_COMPLETION_UNKNOWN`; also the `jpa-failure` lane, i.e. release gate
`completion-unknown-no-retry`).
(`DB_COMPLETION_UNKNOWN`을 단언한다. `jpa-failure` lane, 곧 릴리스 gate `completion-unknown-no-retry`이기도 하다).
@@ -7,41 +7,37 @@
- 현재 정본: `docs/jpa/migration-guide.md`
<!-- 머리 블록 끝 -->
# ADR-JPA-004 — Flyway is the schema source of truth
# ADR-JPA-004 — schema의 정본은 Flyway다
- Status: Accepted
- Date: 2026-08-11
- Design: §31
- 상태: 채택
- 날짜: 2026-08-11
- 설계: §31
## Context
## 배경
Hibernate can create and alter schema from the entity mapping. Flyway can apply versioned scripts.
Both cannot own the schema.
Hibernate는 엔티티 대응에서 schema를 만들고 바꿀 수 있다. Flyway는 버전 있는 script를 적용할 수 있다. 둘이 함께 schema를 가질
수는 없다.
## Decision
## 결정
Flyway owns every schema change. Hibernate validates and never mutates: `ddl-auto` is `validate` or
`none`, enforced at startup. The runtime database credential holds no DDL privilege, so the rule is
enforced by the server as well as by configuration.
모든 schema 변경은 Flyway가 가진다. Hibernate는 검증만 하고 절대 바꾸지 않는다: `ddl-auto`는 `validate`나 `none`이고, 기동 때
강제한다. 런타임 데이터베이스 credential에는 DDL 권한이 없으므로, 규칙을 설정만이 아니라 서버도 강제한다.
## Consequences
## 결과
`ddl-auto=update` fails in a specific and expensive way: it adds but never drops or narrows, so the
result is a schema that is neither the previous one nor the one the mappings describe — produced
silently, by whichever instance started first, with no record of what it did.
`ddl-auto=update`는 구체적이고 비싸게 실패한다: 더하기만 하고 지우거나 좁히지 않아서, 결과는 이전 것도 대응이 설명하는 것도
아닌 schema다 — 먼저 시작한 인스턴스가 무엇을 했는지 기록도 없이 소리 없이 만든다.
Two credentials rather than one is what makes this more than a convention. A configuration rule can
be overridden by a property; a role without `CREATE` cannot be overridden by anything the
application does.
credential을 하나가 아니라 둘 두는 것이 이것을 관례 이상으로 만든다. 설정 규칙은 속성 하나로 덮을 수 있다. `CREATE`가 없는
role은 애플리케이션이 무엇을 하든 덮을 수 없다.
Validation fails closed and never repairs. `repair` rewrites the schema history to match the scripts
on disk, which resolves a checksum mismatch by deleting the evidence of which change is missing.
검증은 실패하면 닫히고 절대 고치지 않는다. `repair`는 schema 이력을 디스크의 script에 맞게 다시 쓰는데, 그것은 어떤 변경이
빠졌는지의 증거를 지워서 checksum 불일치를 푸는 것이다.
The cost is that a schema change requires a migration script and a deployment step. That is the
intended cost: it makes schema change reviewable and reversible.
비용은 schema 변경에 migration script와 배포 단계가 필요하다는 것이다. 그것이 의도한 비용이다: schema 변경을 리뷰할 수 있고
되돌릴 수 있게 만든다.
## Enforcement
## 강제
`JpaDangerousConfigurationGuard`; `FlywaySchemaPolicy`; `FlywayValidationGate` (testkit, used by the
migration contract tests); `PostgreSqlRuntimeRoleVerifier`; release gates `flyway-validate` and
`runtime-role-no-ddl`.
`JpaDangerousConfigurationGuard`, `FlywaySchemaPolicy`, `FlywayValidationGate`(testkit, migration 계약 시험이 쓴다),
`PostgreSqlRuntimeRoleVerifier`, 릴리스 gate `flyway-validate`와 `runtime-role-no-ddl`.
@@ -7,41 +7,36 @@
- 현재 정본: `docs/jpa/support-matrix.md`
<!-- 머리 블록 끝 -->
# ADR-JPA-005 — Contracts run against real PostgreSQL
# ADR-JPA-005 — 계약은 실제 PostgreSQL에 대고 돈다
- Status: Accepted
- Date: 2026-08-11
- Design: §40
- 상태: 채택
- 날짜: 2026-08-11
- 설계: §40
## Context
## 배경
An in-memory database makes tests fast and hermetic. A container makes them slow and requires
Docker.
메모리 데이터베이스는 시험을 빠르고 밀폐되게 만든다. container는 느리게 만들고 Docker를 요구한다.
## Decision
## 결정
Every persistence contract runs against real PostgreSQL 16, 17, and 18 in containers. H2 remains a
local-development convenience and never satisfies a contract. The lanes fail closed when Docker is
absent rather than skipping.
모든 영속 계약은 container 안의 실제 PostgreSQL 16, 17, 18에 대고 돈다. H2는 로컬 개발 편의로 남고 어떤 계약도 만족시키지
않는다. Docker가 없으면 lane은 건너뛰지 않고 실패하면 닫힌다.
## Consequences
## 결과
The behaviours these contracts verify either do not exist in H2 or differ there: SQLSTATE values for
the same violation, `FOR UPDATE SKIP LOCKED` semantics, JSONB operators, range types, concurrent
index builds, `search_path` privileges, and the generated SQL for a paged collection fetch. A green
H2 run is evidence that the code compiles and runs — not that any of the above holds.
이 계약이 검증하는 동작은 H2에 없거나 다르다: 같은 위반의 SQLSTATE 값, `FOR UPDATE SKIP LOCKED`의 뜻, JSONB 연산자, 범위 타입,
concurrent index 만들기, `search_path` 권한, page를 나눈 컬렉션 fetch의 생성 SQL. H2 실행이 초록이면 코드가 컴파일되고 돈다는
증거이지 — 위 어느 것이 지켜진다는 증거가 아니다.
Three versions rather than one because the platform claims three. A contract suite that ran only on
16 would make "Stable on 17 and 18" an assumption.
버전을 하나가 아니라 셋 두는 것은 플랫폼이 셋을 주장하기 때문이다. 16에서만 도는 계약 suite는 「17과 18에서 Stable」을 가정으로
만든다.
Skipping on missing Docker is the failure mode this decision most wants to avoid: a skipped contract
reports success, and CI eventually inherits that silence. `PostgreSqlContainerFactory.assertDockerAvailable()`
throws instead.
Docker가 없을 때 건너뛰는 것이 이 결정이 가장 피하려는 실패 방식이다: 건너뛴 계약은 성공을 알리고, CI는 결국 그 침묵을
물려받는다. `PostgreSqlContainerFactory.assertDockerAvailable()`은 대신 던진다.
The cost is that the contract lanes need Docker and take minutes. The unit lane stays hermetic and
fast, and is where most tests live; the container lanes verify the things only a real server can
answer.
비용은 계약 lane에 Docker가 필요하고 몇 분이 걸린다는 것이다. 단위 lane은 밀폐되고 빠른 채로 남고 대부분의 시험이 거기 있다.
container lane은 실제 서버만 답할 수 있는 것을 검증한다.
## Enforcement
## 강제
`PostgreSqlVersion.stable()`; `PostgreSqlContainerFactory`; release gate `postgresql-contract`.
`PostgreSqlVersion.stable()`, `PostgreSqlContainerFactory`, 릴리스 gate `postgresql-contract`.
@@ -7,68 +7,58 @@
- 현재 정본: `docs/jpa/repository-adaptation.md`
<!-- 머리 블록 끝 -->
# ADR-JPA-006 — `audit` is the sole technical audit model
# ADR-JPA-006 — 기술 감사 모델은 `audit` 하나뿐이다
- Status: Accepted
- Date: 2026-08-24
- Review: `docs/reviews/2026-08-14-jpa-module-code-review.md` JPA-022
- 상태: 채택
- 날짜: 2026-08-24
- 리뷰: `docs/reviews/2026-08-14-jpa-module-code-review.md` JPA-022
## Context
## 배경
Two complete technical-audit mechanisms live in this leaf and they disagree about the schema.
이 leaf에 완전한 기술 감사 장치가 둘 있고, 둘은 schema에 대해 의견이 다르다.
`audit/AuditableEntity` stamps `created_at`/`created_by`/`updated_at`/`updated_by` with an actor
column of length 256, captured through explicit `initializeAudit`/`applyModification` calls and an
`AuditContextPort`. `auditing/AuditMetadata` is a Spring Data embeddable that stamps
`created_*`/`modified_*` with an actor column of length 64, captured by `@CreatedDate` and friends
through an `AuditorAware`.
`audit/AuditableEntity`는 길이 256의 actor 열과 함께 `created_at`/`created_by`/`updated_at`/`updated_by`를 넣고, 명시적인
`initializeAudit`/`applyModification` 호출과 `AuditContextPort`로 값을 잡는다. `auditing/AuditMetadata`는 길이 64의 actor 열과
함께 `created_*`/`modified_*`를 넣는 Spring Data embeddable이고, `AuditorAware`를 거쳐 `@CreatedDate` 같은 것으로 값을 잡는다.
Only the first is real: it is what the sample entities extend and what the migrations were written
for. `JpaAuditingConfiguration` is not a Spring `@Configuration`, and nothing in production
constructs any of the three `auditing` types.
실제로 쓰이는 것은 첫째뿐이다: 샘플 엔티티가 상속하는 것이고 migration도 그것을 위해 썼다. `JpaAuditingConfiguration`은 Spring
`@Configuration`이 아니고, 운영 코드의 어떤 것도 `auditing` 타입 셋 중 하나를 만들지 않는다.
The review asked for one canonical model with a migration or activation decision. The failure mode
it was protecting against is specific: an author of a new entity picks whichever package they find
first, and column names, actor lengths and capture lifecycles then diverge per table.
리뷰는 migration이나 켜기 결정이 붙은 정해진 모델 하나를 요구했다. 막으려던 실패 방식은 구체적이다: 새 엔티티를 쓰는 사람이
먼저 찾은 패키지를 고르고, 그러면 열 이름, actor 길이, 값 잡는 lifecycle이 테이블마다 갈라진다.
## Decision
## 결정
`audit/AuditableEntity` is canonical and the unused `auditing/*` implementation is removed.
`audit/AuditableEntity`가 정본이고, 쓰지 않는 `auditing/*` 구현은 지운다.
Keeping a complete, incompatible implementation as a dormant candidate created exactly the
ambiguity the review warned about: a new entity could choose a package by autocomplete and silently
change column names, actor bounds and capture lifecycle. A future move to Spring Data auditing is a
migration of the canonical model, not activation of a second model that has drifted beside it.
완전하고 호환되지 않는 구현을 잠든 후보로 두는 것이 바로 리뷰가 경고한 모호함을 만들었다: 새 엔티티가 자동 완성으로 패키지를
고르고 열 이름, actor 한계, 값 잡는 lifecycle을 소리 없이 바꿀 수 있었다. 나중에 Spring Data auditing으로 옮기는 것은 정본
모델의 migration이지, 옆에서 어긋나 온 두 번째 모델을 켜는 것이 아니다.
That future migration must preserve `created_*`/`updated_*`, the 256-character actor contract,
`AuditContextPort`, and the shared `Clock`; listener wiring and entity conversion land atomically.
그 나중의 migration은 `created_*`/`updated_*`, 256자 actor 계약, `AuditContextPort`, 공용 `Clock`을 지켜야 한다. listener 배선과
엔티티 변환은 한 번에 들어온다.
## Consequences
## 결과
Two audit mechanisms remain readable in one leaf, and a reader has to be told which one is live.
That cost is paid in this document, in the package javadoc and in a test whose name says so.
감사 장치 둘이 한 leaf 안에 읽을 수 있게 남고, 읽는 사람에게 어느 것이 살아 있는지 알려야 한다. 그 비용은 이 문서, 패키지
javadoc, 그리고 이름이 그것을 말하는 시험이 낸다.
Two failure modes stay silent unless they are asserted, so both are:
단언하지 않으면 소리 없이 남는 실패 방식이 둘 있으므로, 둘 다 단언한다:
- The candidate acquires a stereotype and starts stamping in every deployment that has this module
on the classpath, including the ones whose tables have no `modified_*` columns — where the result
is a failed startup rather than a feature.
- Somebody "harmonises" the two by editing one side's column names, at which point the schema a
deployed table was migrated for and the schema its entity expects diverge with no migration
between them.
- 후보가 stereotype을 얻어 이 모듈이 classpath에 있는 모든 배포에서 값을 넣기 시작한다. 테이블에 `modified_*` 열이 없는 배포도
포함된다 — 거기서 결과는 기능이 아니라 기동 실패다.
- 누가 한쪽 열 이름을 고쳐 둘을 「맞춘다」. 그러면 배포된 테이블이 migration된 schema와 그 엔티티가 기대하는 schema가 둘 사이
migration 없이 갈라진다.
If the candidate is ever promoted, it is promoted atomically: forward migration, sample conversion,
`AuditContextPort → AuditorAware` and `Clock → DateTimeProvider` bridges land together, and this
ADR is superseded rather than amended.
후보를 언젠가 승격하면 한 번에 승격한다: 앞으로 가는 migration, 샘플 변환, `AuditContextPort → AuditorAware`와
`Clock → DateTimeProvider` 다리가 함께 들어오고, 이 ADR은 보완이 아니라 대체된다.
Bulk and native updates stamp nothing under either mechanism. That is a property of JPA, not of the
choice made here, so it is enforced separately rather than assumed away.
bulk·native update는 어느 장치에서든 아무것도 넣지 않는다. 그것은 여기서 고른 것의 성질이 아니라 JPA의 성질이므로, 없다고
치지 않고 따로 강제한다.
## Enforcement
## 강제
`JpaAuditMechanismRule.entitiesUseExactlyOneAuditMechanism` and
`bulkUpdatesOfAuditedEntitiesStampAudit`, run against the real production graph by
`JpaProductionArchitectureTest` at the composition root — not against fixtures, which is how the
earlier version of this rule pack passed while applying to nothing. `AuditingCandidateStatusTest`
asserts the candidate carries no composing stereotype and that the two column sets stay distinct.
`JpaAuditMechanismRuleTest` exercises the rules' own negative cases.
`JpaAuditMechanismRule.entitiesUseExactlyOneAuditMechanism`과 `bulkUpdatesOfAuditedEntitiesStampAudit`를 조립 루트의
`JpaProductionArchitectureTest`가 실제 운영 그래프에 대고 돌린다 — fixture가 아니다. 이 규칙 묶음의 앞 버전은 fixture에 대고
돌아서 아무것에도 적용되지 않은 채 통과했다. `AuditingCandidateStatusTest`가 후보에 조립하는 stereotype이 없고 두 열 집합이
따로 남는다고 단언한다. `JpaAuditMechanismRuleTest`가 규칙 자신의 부정 경우를 시험한다.
+39 -46
View File
@@ -7,66 +7,59 @@
- 현재 정본: `docs/mongodb/repository-adaptation.md`
<!-- 머리 블록 끝 -->
# ADR-MONGO-001 — MongoDB platform boundary
# ADR-MONGO-001 — MongoDB 플랫폼 경계
- **Status:** Accepted
- **Date:** 2026-08-13
- **Design source:** `docs/superpowers/specs/2026-08-11-mongodb-document-persistence-platform-design.md` §1, §2 (D-01, D-04, D-05), §5, §6
- **상태:** 채택
- **날짜:** 2026-08-13
- **설계 출처:** `docs/superpowers/specs/2026-08-11-mongodb-document-persistence-platform-design.md` §1, §2 (D-01, D-04, D-05), §5, §6
## Context
## 배경
Two failure modes are common when a team wraps MongoDB.
팀이 MongoDB를 감쌀 때 흔한 실패 방식이 둘 있다.
The first is flattening: a shared `CommonMongoRepository<T, ID>` and a generic CRUD facade, which
forces every collection to share an id strategy, a consistency profile and a query surface. MongoDB's
single-document atomicity, aggregation model and change streams stop being reachable, and the first
collection that needs something different gets a cast or a leaky generic.
첫째는 납작하게 만들기다: 공용 `CommonMongoRepository<T, ID>`와 범용 CRUD 창구. 모든 collection이 id 전략, 일관성 profile,
query surface를 같이 쓰게 강요한다. MongoDB의 단일 문서 원자성, aggregation 모델, change stream에 더는 닿을 수 없고, 다른 것이
필요한 첫 collection은 cast나 새는 제네릭을 받는다.
The second is unrestricted exposure: the driver and `runCommand` available everywhere. Then any
service can drop a collection, run an unbounded pipeline, or issue an admin command from a request
thread, and no review catches it because there is nothing structural to catch.
둘째는 제한 없는 노출이다: driver와 `runCommand`를 어디서나 쓸 수 있다. 그러면 어느 서비스든 요청 스레드에서 collection을
지우거나, 한계 없는 pipeline을 돌리거나, admin 명령을 낼 수 있고, 구조로 잡을 것이 없으니 어떤 리뷰도 잡지 못한다.
## Decision
## 결정
The domain owns its documents; the platform owns the cross-cutting decisions. Four exposure planes:
도메인이 자기 문서를 가지고, 플랫폼이 가로지르는 결정을 가진다. 노출 plane 넷:
| Plane | Contents | Client |
| plane | 내용 | client |
|---|---|---|
| D1 Standard document persistence | Spring Data repositories, typed queries, mapping manifest, atomic update primitives, optimistic revision | Stable API V1, `apiStrict=true` |
| D2 Advanced document operations | `MongoTemplate`, transactions/sessions, bulk, aggregation, keyset cursors, change streams | Stable API V1, `apiStrict=true` |
| D3 Explicit Mongo capability | Native BSON, time series, search/vector, CSFLE/QE, shard-aware operations | Separate capability client |
| D4 Admin plane | Collection, validator, index, migration, shard, repair | Separate admin client and credential |
| D1 표준 문서 영속 | Spring Data repository, 타입 있는 query, 대응 manifest, 원자 update 기본 장치, 낙관적 revision | Stable API V1, `apiStrict=true` |
| D2 고급 문서 연산 | `MongoTemplate`, 트랜잭션·세션, bulk, aggregation, keyset cursor, change stream | Stable API V1, `apiStrict=true` |
| D3 명시적 Mongo capability | native BSON, time series, search·vector, CSFLE·QE, shard를 아는 연산 | 따로 둔 capability client |
| D4 admin plane | collection, validator, index, migration, shard, repair | 따로 둔 admin client와 credential |
Specifically:
구체적으로:
1. **No `CommonMongoRepository<T, ID>`.** Each aggregate declares its own repository.
2. **D1/D2 run on Stable API V1 with `apiStrict=true`,** so a command outside the versioned API fails
at development time instead of on the next server upgrade.
3. **D3 is not a raw-client escape.** Every call passes a fixed admission order: capability registered
→ database profile → collection allowlist → operation name → timeout → consistency profile →
result limit → trace → redaction → command category → admin-command refusal → execute.
4. **D4 is a separate client with a separate credential.** No application-plane path reaches it;
`PolicyAwareMongoNativeGateway` refuses admin-category commands regardless of capability.
5. **Advanced and Experimental capabilities are opt-in modules**, never transitive dependencies of the
Stable surface.
1. **`CommonMongoRepository<T, ID>`가 없다.** aggregate마다 자기 repository를 선언한다.
2. **D1·D2는 `apiStrict=true`인 Stable API V1에서 돈다.** 그래서 버전 있는 API 밖의 명령은 다음 서버 업그레이드 때가 아니라
개발 때 실패한다.
3. **D3는 raw client로 빠져나가는 길이 아니다.** 모든 호출이 정해진 허가 순서를 지난다: capability 등록 → 데이터베이스
profile → collection 허용 목록 → operation 이름 → timeout → 일관성 profile → 결과 한계 → trace → 가리기 → 명령 category →
admin 명령 거절 → 실행.
4. **D4는 따로 둔 credential을 가진 따로 둔 client다.** 애플리케이션 plane 경로는 그것에 닿지 않는다.
`PolicyAwareMongoNativeGateway`는 capability와 관계없이 admin category 명령을 거절한다.
5. **Advanced와 Experimental capability는 골라 쓰는 모듈이고**, Stable surface의 전이 의존이 되지 않는다.
## Consequences
## 결과
**Positive.** MongoDB's semantics stay reachable. Misuse is refused structurally rather than reviewed
for. A server upgrade cannot silently change D1/D2 behaviour. Admin operations have their own audit
trail and credential.
**좋은 점.** MongoDB의 뜻에 계속 닿을 수 있다. 잘못된 사용은 리뷰로 찾지 않고 구조로 거절한다. 서버 업그레이드가 D1·D2
동작을 소리 없이 바꿀 수 없다. admin 연산은 자기 감사 흔적과 credential을 가진다.
**Negative.** Every operation needs a registered name and profile, so a new query is a small amount of
configuration rather than zero. A genuinely new capability requires a registration before it can be
used. Both are deliberate: the cost is paid once per operation, at review time.
**나쁜 점.** 모든 operation에 등록된 이름과 profile이 필요해서, 새 query에는 0이 아니라 약간의 설정이 든다. 정말 새 capability는
쓰기 전에 등록이 필요하다. 둘 다 일부러다: 비용은 operation마다 한 번, 리뷰 때 낸다.
**Rejected alternative — "expose the driver, rely on code review."** Review does not scale to every
query in every service, and the operations that matter (unbounded pipeline, `dropCollection`,
unanchored regex on user input) look unremarkable in a diff.
**버린 대안 — 「driver를 내놓고 코드 리뷰에 기댄다」.** 리뷰는 모든 서비스의 모든 query로 늘어나지 못하고, 중요한 연산
(한계 없는 pipeline, `dropCollection`, 사용자 입력에 대한 anchor 없는 정규식)은 diff에서 눈에 띄지 않는다.
## Repository adaptation
## 저장소에 맞추기
The design assumes 19 Gradle modules under `modules/mongodb/`. This repository's fail-closed registry
declares exactly 19 leaf identities, so the modules became package boundaries inside
`:adapter:outbound:persistence-mongo`, enforced by ArchUnit. See
[docs/mongodb/repository-adaptation.md](../mongodb/repository-adaptation.md).
설계는 `modules/mongodb/` 아래 Gradle 모듈 19개를 가정한다. 이 저장소의 실패하면 닫히는 registry는 정확히 19개의 leaf identity를
선언하므로, 그 모듈들은 `:adapter:outbound:persistence-mongo` 안의 패키지 경계가 됐고 ArchUnit이 강제한다.
[docs/mongodb/repository-adaptation.md](../mongodb/repository-adaptation.md)를 본다.
+36 -44
View File
@@ -7,61 +7,53 @@
- 현재 정본: `docs/mongodb/bson-mapping-guide.md`
<!-- 머리 블록 끝 -->
# ADR-MONGO-002 — BSON representation is a pinned manifest
# ADR-MONGO-002 — BSON 표현은 고정한 manifest다
- **Status:** Accepted
- **Date:** 2026-08-13
- **Design source:** design §10, decision D-06
- **상태:** 채택
- **날짜:** 2026-08-13
- **설계 출처:** 설계 §10, 결정 D-06
## Context
## 배경
How a Java value is represented in BSON is a data contract, but nothing in the default toolchain
treats it as one. Spring Data and the MongoDB driver both have defaults, and those defaults have
changed across versions. A `BigDecimal` can land as a `Double`, a `String` or a `Decimal128`; a `UUID`
can land as `Binary` subtype 3 or subtype 4; an `Instant` can land as a `Date` or a `String`.
Java 값을 BSON으로 어떻게 나타내는지는 데이터 계약인데, 기본 toolchain의 어떤 것도 그것을 계약으로 다루지 않는다. Spring Data와
MongoDB driver에는 둘 다 기본값이 있고, 그 기본값은 버전마다 바뀌어 왔다. `BigDecimal`은 `Double`, `String`, `Decimal128` 중
무엇으로든 들어갈 수 있다. `UUID`는 `Binary` subtype 3이나 subtype 4로 들어갈 수 있다. `Instant`는 `Date`나 `String`으로 들어갈
수 있다.
The consequences are asymmetric. A representation change is invisible in a value-equality test —
`12.30` looks like `12.30` whether it is a double or a `Decimal128` — but once a collection holds
production data, changing it is a full migration. And the UUID case is worse than a migration: legacy
Java representation byte-swaps two halves of the UUID, so a document written under one representation
and read under the other yields a *different, valid-looking* UUID. Nothing errors. You get the wrong
record.
결과는 비대칭이다. 표현이 바뀌어도 값 동등 시험에는 보이지 않는다 — `12.30`은 double이든 `Decimal128`이든 `12.30`처럼 보인다 —
하지만 collection에 운영 데이터가 들면 그것을 바꾸는 것은 전체 migration이다. 그리고 UUID 경우는 migration보다 나쁘다: 옛 Java
표현은 UUID의 두 절반을 byte-swap하므로, 한 표현으로 쓰고 다른 표현으로 읽은 문서는 *다르지만 유효해 보이는* UUID를 낸다.
오류는 없다. 엉뚱한 레코드를 받는다.
## Decision
## 결정
`MongoTypeRepresentationManifest` pins the representation for every type the platform maps, and
`MongoMappingConfiguration` builds the Spring Data converters from it. Nothing relies on a library
default.
`MongoTypeRepresentationManifest`가 플랫폼이 대응시키는 모든 타입의 표현을 고정하고, `MongoMappingConfiguration`이 그것으로
Spring Data converter를 만든다. 라이브러리 기본값에 기대는 것은 없다.
| Java | BSON | Rationale |
| Java | BSON | 근거 |
|---|---|---|
| `UUID` | `Binary` subtype 4 (`STANDARD`) | Subtype 3 byte-swaps; cross-representation reads are silently wrong. |
| `BigDecimal` | `Decimal128` | A double cannot represent `12.30`; money compared as a double is eventually wrong by a cent. |
| `BigInteger` | `Decimal128`, or declared `String` when out of range | 34 significant digits; out of range fails on write instead of rounding. |
| `Instant` / `OffsetDateTime` / `ZonedDateTime` | UTC `Date` | One instant, one representation. |
| `LocalDate` | declared per field | A calendar day is not an instant. |
| `LocalDateTime` | **refused** | No offset: the stored value depends on the writing JVM's default zone. |
| `enum` | `String` name | Ordinals renumber when someone inserts a constant. |
| `UUID` | `Binary` subtype 4(`STANDARD`) | subtype 3은 byte-swap한다. 표현을 넘나드는 읽기는 소리 없이 틀린다. |
| `BigDecimal` | `Decimal128` | double은 `12.30`을 나타내지 못한다. double로 비교한 돈은 결국 1원씩 틀린다. |
| `BigInteger` | `Decimal128`, 범위를 넘으면 선언한 `String` | 유효 숫자 34자리. 범위를 넘으면 반올림하지 않고 쓰기에서 실패한다. |
| `Instant` / `OffsetDateTime` / `ZonedDateTime` | UTC `Date` | 시각 하나, 표현 하나. |
| `LocalDate` | 필드마다 선언 | 달력의 날은 시각이 아니다. |
| `LocalDateTime` | **거절** | offset이 없다: 저장 값이 쓰는 JVM의 기본 시간대에 따라 달라진다. |
| `enum` | `String` 이름 | 누가 상수를 끼워 넣으면 ordinal이 다시 매겨진다. |
Type metadata follows `MongoTypeMetadataPolicy` — `NONE`, `ALIAS` or `CLASS_NAME`. A
`@LongLivedMongoDocument` type may not use `CLASS_NAME`: writing a FQCN into a million documents makes
a package rename a data migration.
타입 metadata는 `MongoTypeMetadataPolicy` — `NONE`, `ALIAS`, `CLASS_NAME` — 를 따른다. `@LongLivedMongoDocument` 타입은
`CLASS_NAME`을 쓰면 안 된다: 문서 백만 개에 FQCN을 쓰면 패키지 이름 바꾸기가 데이터 migration이 된다.
The manifest is enforced by a golden gate. `MongoBsonSnapshot` canonicalises a stored document,
preserving BSON types and keeping missing distinct from null, and
`MongoBsonSnapshotAssert.hasTypeSignature(...)` fails on any representation change. The registry
pins `UuidCodec(STANDARD)` explicitly rather than inheriting a default, since inheriting the default
is the exact drift the gate exists to catch.
manifest는 golden gate가 강제한다. `MongoBsonSnapshot`이 저장된 문서를 정규화하면서 BSON 타입을 지키고 없음과 null을 구별해
두며, `MongoBsonSnapshotAssert.hasTypeSignature(...)`가 표현이 바뀌면 실패한다. registry는 기본값을 물려받지 않고
`UuidCodec(STANDARD)`를 명시해 고정한다. 기본값을 물려받는 것이 바로 gate가 잡으려는 어긋남이기 때문이다.
## Consequences
## 결과
**Positive.** A library upgrade cannot move a representation without failing a test. Money is exact.
UUIDs read back as themselves. Class moves stay refactors.
**좋은 점.** 라이브러리 업그레이드가 시험을 실패시키지 않고 표현을 옮길 수 없다. 돈이 정확하다. UUID가 자기 자신으로 다시
읽힌다. 클래스 옮기기는 리팩터링으로 남는다.
**Negative.** Every representation-affecting change requires updating a snapshot *and* writing a
migration. A new mapped type needs a manifest entry before it can be used. This is the intended
friction: the alternative is discovering the change in production.
**나쁜 점.** 표현에 영향을 주는 모든 변경에 snapshot 갱신 *그리고* migration 작성이 필요하다. 새로 대응시키는 타입은 쓰기 전에
manifest 항목이 필요하다. 의도한 마찰이다: 대안은 운영에서 변경을 발견하는 것이다.
**Rejected alternative — "snapshot the JSON."** JSON destroys exactly the distinctions the gate
protects: `Decimal128` and `String` both render as text, `Binary` UUID and `ObjectId` both render as
hex, and missing and null both disappear.
**버린 대안 — 「JSON을 snapshot한다」.** JSON은 gate가 지키는 바로 그 구별을 없앤다: `Decimal128`과 `String`은 둘 다 글로
나오고, `Binary` UUID와 `ObjectId`는 둘 다 hex로 나오며, 없음과 null은 둘 다 사라진다.
+35 -43
View File
@@ -7,33 +7,29 @@
- 현재 정본: `docs/mongodb/consistency-transaction-guide.md`
<!-- 머리 블록 끝 -->
# ADR-MONGO-003 — Transaction body retry and commit retry are separate loops
# ADR-MONGO-003 — 트랜잭션 본문 재시도와 커밋 재시도는 따로 도는 반복문이다
- **Status:** Accepted
- **Date:** 2026-08-13
- **Design source:** design §14–§16, decisions D-07 through D-10
- **상태:** 채택
- **날짜:** 2026-08-13
- **설계 출처:** 설계 §14–§16, 결정 D-07부터 D-10
## Context
## 배경
MongoDB reports two transaction failures that look similar and must be handled in opposite ways.
MongoDB는 비슷해 보이지만 정반대로 다뤄야 하는 트랜잭션 실패 둘을 알린다.
`TransientTransactionError` means the transaction definitively did not commit. The correct response is
to run the whole thing again.
`TransientTransactionError`는 트랜잭션이 분명히 커밋되지 않았다는 뜻이다. 맞는 대응은 전체를 다시 돌리는 것이다.
`UnknownTransactionCommitResult` means the commit **may already have applied** — typically because the
primary changed while the commit was in flight. The correct response is to retry *the commit*, which
is a no-op if it already succeeded.
`UnknownTransactionCommitResult`는 커밋이 **이미 적용됐을 수 있다**는 뜻이다 — 보통 커밋이 진행 중일 때 primary가 바뀌었기
때문이다. 맞는 대응은 *커밋*을 재시도하는 것이고, 이미 성공했다면 그것은 아무 일도 하지 않는다.
The common implementation wraps everything in one retry loop. That loop replays the body after an
unknown commit, and if the commit did apply, the body applies twice. In a payment or notification path
that is a duplicate charge or a duplicate message, produced by the error handler.
흔한 구현은 모든 것을 재시도 반복문 하나로 감싼다. 그 반복문은 모르는 커밋 뒤에 본문을 다시 돌리고, 커밋이 적용됐었다면 본문이
두 번 적용된다. 결제나 알림 경로에서 그것은 오류 handler가 만든 중복 청구나 중복 메시지다.
The related trap is session reuse: retrying on the same session after an abort carries the aborted
transaction's state into the retry.
관련된 함정은 세션 다시 쓰기다: abort 뒤에 같은 세션으로 재시도하면 abort된 트랜잭션의 상태가 재시도로 넘어간다.
## Decision
## 결정
`MongoTransactionRetryCoordinator` implements two loops with different scopes.
`MongoTransactionRetryCoordinator`가 범위가 다른 반복문 둘을 구현한다.
```
for each body attempt within the budget:
@@ -44,34 +40,30 @@ for each body attempt within the budget:
UnknownTransactionCommitResult -> retry the COMMIT ONLY, same session
```
Rules that follow, all of them load-bearing:
따라 나오는 규칙. 모두 꼭 필요하다:
1. **A new session per body attempt.** No aborted state leaks into a retry.
2. **The body is never replayed after a commit ambiguity.** `MongoRetryScope.COMMIT_ONLY` is a
distinct value from `BODY` precisely so this cannot be collapsed by accident.
3. **One budget bounds both loops.** `MongoRetryBudget` limits attempts *and* elapsed time, with
jittered backoff, so a struggling primary is not retried into the ground by every instance at once.
4. **An exhausted commit retry surfaces `TRANSACTION_COMMIT_UNKNOWN`,** never a generic failure. An
ambiguous outcome reported as a failure invites the caller to retry — the one thing that must not
happen. See [docs/mongodb/runbooks/unknown-commit.md](../mongodb/runbooks/unknown-commit.md).
5. **Transaction bodies write a deterministic marker** so `MongoCommitReconciler` can establish what
actually happened. A transaction that cannot be reconciled has no recovery path.
6. **Classification reads labels before codes.** Server error labels are the authoritative statement
about retryability; error codes vary by version.
1. **본문 시도마다 새 세션.** abort된 상태가 재시도로 새지 않는다.
2. **커밋이 모호해진 뒤에는 본문을 절대 다시 돌리지 않는다.** `MongoRetryScope.COMMIT_ONLY`가 `BODY`와 다른 값인 것은 바로
이것이 실수로 뭉개지지 않게 하려는 것이다.
3. **예산 하나가 두 반복문을 묶는다.** `MongoRetryBudget`이 시도 수 *그리고* 흐른 시간을 jitter 있는 backoff와 함께 제한한다.
그래서 힘든 primary를 모든 인스턴스가 한꺼번에 재시도로 짓밟지 않는다.
4. **바닥난 커밋 재시도는 일반 실패가 아니라 `TRANSACTION_COMMIT_UNKNOWN`으로 드러난다.** 실패로 알린 모호한 결과는 호출자에게
재시도를 부른다 — 일어나면 안 되는 바로 그 일이다.
[docs/mongodb/runbooks/unknown-commit.md](../mongodb/runbooks/unknown-commit.md)를 본다.
5. **트랜잭션 본문은 결정적인 표지를 쓴다.** 그래서 `MongoCommitReconciler`가 실제로 무엇이 일어났는지 세울 수 있다. 맞춰 볼 수
없는 트랜잭션에는 회복 길이 없다.
6. **분류는 코드보다 label을 먼저 읽는다.** 서버 오류 label이 재시도 가능성에 대한 정본 진술이고, 오류 코드는 버전마다 다르다.
Surrounding decisions that reduce how often this path is reached at all: single-document atomic
operations are preferred over transactions (D-09), partial changes use update operators rather than
`save()` (D-07), and whole-document replacement requires an optimistic revision (D-08).
이 경로에 닿는 횟수 자체를 줄이는 주변 결정: 트랜잭션보다 단일 문서 원자 연산을 고른다(D-09), 부분 변경은 `save()`가 아니라
update 연산자를 쓴다(D-07), 문서 전체 바꾸기에는 낙관적 revision이 필요하다(D-08).
## Consequences
## 결과
**Positive.** A commit ambiguity cannot become a duplicate effect. The ambiguity reaches the caller as
an ambiguity. The retry budget is bounded in both attempts and time.
**좋은 점.** 커밋 모호함이 중복 효과가 될 수 없다. 모호함이 모호함으로 호출자에게 닿는다. 재시도 예산이 시도 수와 시간 둘 다에서
한계를 가진다.
**Negative.** Callers must handle a third outcome beyond success and failure. Transaction bodies must
write a marker they would not otherwise need. Both costs are small compared with reconciling
duplicated financial effects after the fact.
**나쁜 점.** 호출자는 성공과 실패 밖의 세 번째 결과를 다뤄야 한다. 트랜잭션 본문은 그렇지 않으면 필요 없을 표지를 써야 한다. 두
비용 모두 중복된 금전 효과를 나중에 맞춰 보는 것에 비하면 작다.
**Rejected alternative — "one retry loop, at-least-once everywhere."** It requires every transaction
body to be fully idempotent, which is a much stronger and much less checkable property than writing
one marker, and it is silently violated the first time someone adds a non-idempotent step.
**버린 대안 — 「재시도 반복문 하나, 어디서나 at-least-once」.** 모든 트랜잭션 본문이 완전히 멱등이어야 한다. 표지 하나를 쓰는
것보다 훨씬 강하고 훨씬 검사하기 어려운 성질이고, 누가 멱등이 아닌 단계를 처음 더하는 순간 소리 없이 깨진다.
@@ -7,65 +7,55 @@
- 현재 정본: `docs/mongodb/schema-index-migration-guide.md`
<!-- 머리 블록 끝 -->
# ADR-MONGO-004 — Index and schema changes belong to the admin plane
# ADR-MONGO-004 — index와 schema 변경은 admin plane의 것이다
- **Status:** Accepted
- **Date:** 2026-08-13
- **Design source:** design §21–§25, decisions D-11, D-13
- **상태:** 채택
- **날짜:** 2026-08-13
- **설계 출처:** 설계 §21–§25, 결정 D-11, D-13
## Context
## 배경
Spring Data can create indexes automatically from annotations. On a laptop this is convenient. On a
collection with a hundred million documents, an index build is a capacity event: it consumes CPU, IO
and memory on the primary for minutes to hours, and it starts because a pod restarted.
Spring Data는 애너테이션에서 index를 자동으로 만들 수 있다. 노트북에서는 편하다. 문서 1억 개가 든 collection에서 index 만들기는
용량 사건이다: primary의 CPU, IO, 메모리를 몇 분에서 몇 시간 동안 쓰고, pod 하나가 재시작했다는 이유로 시작된다.
Worse, it starts N times when N pods restart, and there is no approval step, no ordering relative to
the code that needs the index, and no record afterwards of what was created.
더 나쁘게, pod N개가 재시작하면 N번 시작하고, 승인 단계도, 그 index가 필요한 코드와의 순서도, 나중에 무엇을 만들었는지의 기록도
없다.
Schema validators have the same shape with a sharper edge: tightening a validator on a collection with
existing data rejects writes to documents that were legal when they were written.
schema validator도 같은 모양인데 날이 더 서 있다: 데이터가 있는 collection에서 validator를 조이면, 쓸 때는 적법했던 문서에 대한
쓰기를 거절한다.
TTL has a third shape. It looks like a scheduler and is not one: the TTL monitor runs about once a
minute and deletes in batches, so an expired document routinely remains readable for minutes or hours.
TTL은 세 번째 모양이다. scheduler처럼 보이지만 아니다: TTL monitor는 대략 1분에 한 번 돌고 batch로 지우므로, 만료된 문서가 몇
분에서 몇 시간 동안 읽히는 것이 예사다.
## Decision
## 결정
**Indexes and validators are declared in a manifest and applied by the admin plane (D4).** Automatic
index creation in production is disabled.
**index와 validator는 manifest에 선언하고 admin plane(D4)이 적용한다.** 운영에서 자동 index 만들기는 끈다.
1. `MongoManifestRegistry` holds the declared indexes (`MongoIndexManifest`) and validator
(`MongoSchemaManifest`) per collection. The manifest is the source of truth, reviewed in a pull
request.
2. `MongoIndexDiffEngine` compares manifest against observed state and reports missing, extra and
*changed* indexes. Changed ones are reported rather than re-issued: MongoDB will not silently
rebuild an index whose definition moved.
3. `MongoIndexApplyPolicy` sets what an environment may do — `APPLY` (local), `APPLY_WITH_DIFF`
(staging), `DIFF_WITH_APPROVED_APPLY` (production), `REPORT_ONLY` (audit).
4. **Ownership gates every drop.** `MongoMetadataOwnership` distinguishes `APPLICATION_MANAGED` from
`SEARCH_MANAGED`, `ENCRYPTION_MANAGED` and `EXTERNAL`. Only application-managed objects are
droppable on drift. A diff engine without ownership eventually proposes dropping
`enxcol_.customers.esc`, and "the drift tool cleaned it up" is a very bad incident summary.
5. **Retirement is staged.** `MongoIndexRetirementState` moves an index declared → hidden →
observed-unused → droppable, one deployment per transition. Hiding is instantly reversible;
dropping is a rebuild.
6. **Stable validation actions are `error` and `warn` only.** `errorAndLog` is not part of the Stable
contract on 7.0 or 8.0 and is refused. Tightening goes `warn`+`MODERATE` → confirm zero warnings →
`error`+`STRICT`, in two deployments.
7. **TTL is physical cleanup only** (D-13). `MongoExpirationAccessPolicy` states the rule: a
document's presence is not authorization and its absence is not a deadline. Access control checks
the expiry field; scheduling uses a scheduler.
8. **Migrations are checksummed, locked, precondition-checked and resumable.**
`MongoMigrationRunner` fails hard when an applied id's checksum changed — two environments running
different code under one id is worse than a failed deploy.
1. `MongoManifestRegistry`가 collection마다 선언한 index(`MongoIndexManifest`)와 validator(`MongoSchemaManifest`)를 가진다.
manifest가 정본이고 pull request에서 리뷰한다.
2. `MongoIndexDiffEngine`이 manifest를 관찰한 상태와 비교해 빠진 index, 남는 index, *바뀐* index를 알린다. 바뀐 것은 다시 내지
않고 알린다: MongoDB는 정의가 움직인 index를 소리 없이 다시 만들지 않는다.
3. `MongoIndexApplyPolicy`가 환경이 할 수 있는 것을 정한다 — `APPLY`(로컬), `APPLY_WITH_DIFF`(staging),
`DIFF_WITH_APPROVED_APPLY`(운영), `REPORT_ONLY`(감사).
4. **모든 drop은 소유권이 막는다.** `MongoMetadataOwnership`이 `APPLICATION_MANAGED`를 `SEARCH_MANAGED`, `ENCRYPTION_MANAGED`,
`EXTERNAL`과 구별한다. 어긋났을 때 지울 수 있는 것은 애플리케이션이 관리하는 객체뿐이다. 소유권 없는 diff 엔진은 결국
`enxcol_.customers.esc`를 지우자고 제안하고, 「drift 도구가 치웠다」는 아주 나쁜 사고 요약이다.
5. **은퇴는 단계를 밟는다.** `MongoIndexRetirementState`가 index를 선언됨 → 숨김 → 안 쓰는 것 확인 → 지울 수 있음으로 옮기고,
전이마다 배포 한 번이다. 숨기기는 바로 되돌릴 수 있다. 지우기는 다시 만들기다.
6. **Stable validation action은 `error`와 `warn`뿐이다.** `errorAndLog`는 7.0이나 8.0에서 Stable 계약에 속하지 않아 거절한다.
조이기는 `warn`+`MODERATE` → 경고 0 확인 → `error`+`STRICT`로, 배포 두 번에 걸쳐 간다.
7. **TTL은 물리적 치우기일 뿐이다**(D-13). `MongoExpirationAccessPolicy`가 규칙을 말한다: 문서가 있다고 인가가 아니고, 없다고
기한이 아니다. 접근 통제는 만료 필드를 검사하고, 일정은 scheduler를 쓴다.
8. **migration은 checksum을 두고, 잠그고, 전제 조건을 검사하고, 이어서 할 수 있다.** `MongoMigrationRunner`는 적용한 id의
checksum이 바뀌면 단단히 실패한다 — 두 환경이 id 하나 아래 다른 코드를 돌리는 것은 실패한 배포보다 나쁘다.
## Consequences
## 결과
**Positive.** Index builds are scheduled by people who know the capacity. Rollback is possible at
every step. Drift is visible without being dangerous. Nothing drops what it does not own.
**좋은 점.** index 만들기 일정은 용량을 아는 사람이 잡는다. 모든 단계에서 되돌릴 수 있다. drift는 위험하지 않게 보인다. 아무것도
자기가 가지지 않은 것을 지우지 않는다.
**Negative.** Adding an index is a manifest change plus an apply, not an annotation. Local development
uses `APPLY` so the friction is confined to environments where it is warranted.
**나쁜 점.** index 더하기는 애너테이션이 아니라 manifest 변경 + 적용이다. 로컬 개발은 `APPLY`를 쓰므로 마찰은 그것이 정당한
환경에만 머문다.
**Rejected alternative — "auto-create with a feature flag."** The flag is either on in production,
which is the problem, or off, in which case the manifest is the real mechanism and the annotation is a
second, divergent source of truth.
**버린 대안 — 「feature flag와 함께 자동으로 만들기」.** flag가 운영에서 켜져 있으면 그것이 문제이고, 꺼져 있으면 manifest가
실제 장치이고 애너테이션은 두 번째의 갈라진 정본이다.
@@ -7,90 +7,78 @@
- 현재 정본: `docs/mongodb/support-matrix.md`
<!-- 머리 블록 끝 -->
# ADR-MONGO-ADV-001 — Advanced capability promotion
# ADR-MONGO-ADV-001 — Advanced capability 승격
- **Status:** Accepted
- **Date:** 2026-08-13
- **Design source:** design §2 (D-15), §3.2–§3.3; Advanced expansion plan Task 15
- **Amended 2026-09-25:** the `ca-skeleton.persistence-mongo.advanced.*.enabled` binding
(`MongoAdvancedConfiguration`/`MongoAdvancedSettings`) was imported by nothing, so no deployment
property ever reached the flags; it was removed together with `propertyFor`. The flags are now
built in code by the adapter that constructs an entry point. `MongoAdvancedPromotionGate`,
`MongoAdvancedPromotionEvidence`, `MongoVectorSearchBenchmarkGate` and the search, vector, time
series and GridFS packages (interfaces with no implementation) were removed. The evidence
categories below remain a review obligation; no class checks them.
- **상태:** 채택
- **날짜:** 2026-08-13
- **설계 출처:** 설계 §2 (D-15), §3.2–§3.3. Advanced 확장 계획 Task 15
- **2026-09-25 보완:** `ca-skeleton.persistence-mongo.advanced.*.enabled` 바인딩(`MongoAdvancedConfiguration`/
`MongoAdvancedSettings`)은 아무것도 import하지 않아서 어떤 배포 속성도 flag에 닿지 않았다. `propertyFor`와 함께 지웠다. flag는
이제 entry point를 만드는 어댑터가 코드로 만든다. `MongoAdvancedPromotionGate`, `MongoAdvancedPromotionEvidence`,
`MongoVectorSearchBenchmarkGate`, 그리고 search, vector, time series, GridFS 패키지(구현 없는 인터페이스)를 지웠다. 아래 증거
category는 리뷰 의무로 남는다. 그것을 검사하는 클래스는 없다.
## Context
## 배경
Sharding, time series, CSFLE, Queryable Encryption, search, vector search and multi-tenancy each work
in a demo within an afternoon. What they do not do is behave the same way in production, and the
differences are not discovered by functional tests:
sharding, time series, CSFLE, Queryable Encryption, search, vector search, multi-tenancy는 하나같이 오후 한나절이면 demo에서
동작한다. 하지 않는 것은 운영에서 같은 방식으로 동작하는 것이고, 그 차이는 기능 시험으로 찾지 못한다:
- Sharding changes which queries are efficient. A query that misses the shard key becomes
scatter-gather, which passes every test on a one-shard cluster.
- Encryption's failure modes are KMS failure modes — wrong key, revoked permission, mid-rotation —
none of which occur against a local key provider.
- Search and vector search can be functionally correct and useless: the index returns results, and
the results are not relevant. Recall is not visible in a pass/fail assertion.
- Database-per-tenant works until the tenant count crosses what the connection and file-handle
budget supports, which is an operational property, not a code property.
- sharding은 어떤 query가 효율적인지 바꾼다. shard key를 놓친 query는 scatter-gather가 되는데, shard 하나짜리 cluster에서는
모든 시험을 통과한다.
- 암호화의 실패 방식은 KMS의 실패 방식이다 — 틀린 키, 거둬들인 권한, 교체 중 — 로컬 키 provider에 대고는 하나도 일어나지 않는다.
- search와 vector search는 기능상 맞으면서 쓸모없을 수 있다: index는 결과를 돌려주는데 결과가 관련이 없다. recall은 통과·실패
단언에 보이지 않는다.
- 테넌트마다 데이터베이스는 테넌트 수가 연결·파일 handle 예산이 받쳐 주는 수를 넘을 때까지 동작한다. 그것은 코드가 아니라 운영의
성질이다.
The failure mode this ADR prevents is a capability marked "done" on the strength of a green test that
never touched the environment where it will run.
이 ADR이 막는 실패 방식은 그것이 돌 환경을 한 번도 건드리지 않은 초록 시험을 근거로 capability를 「끝남」으로 표시하는 것이다.
## Decision
## 결정
Every Advanced and Experimental capability is an **opt-in module behind its own flag**, and promotion
requires evidence, not confidence.
모든 Advanced·Experimental capability는 **자기 flag 뒤의 골라 쓰는 모듈**이고, 승격에는 자신감이 아니라 증거가 필요하다.
### Enablement
### 켜기
`MongoAdvancedCapabilityFlags` gates construction of every Advanced entry point. A disabled capability
does not produce a runtime warning — the type refuses to be constructed, naming the property that
enables it (`MongoAdvancedCapabilityFlags.propertyFor(capability)`). Being on the classpath is not
being enabled, and `stableNeverDependsOnAdvanced` (ArchUnit) keeps the Stable surface free of them.
`MongoAdvancedCapabilityFlags`가 모든 Advanced entry point의 생성을 막는다. 꺼진 capability는 런타임 경고를 내지 않는다 — 타입이
그것을 켜는 속성 이름을 대며 만들어지기를 거절한다(`MongoAdvancedCapabilityFlags.propertyFor(capability)`). classpath에 있다고
켜진 것이 아니고, `stableNeverDependsOnAdvanced`(ArchUnit)가 Stable surface에서 그것을 떼어 둔다.
### Promotion evidence
### 승격 증거
`MongoAdvancedPromotionGate.verify(evidence)` requires every category:
`MongoAdvancedPromotionGate.verify(evidence)`는 모든 category를 요구한다:
| Category | Means |
| category | 뜻 |
|---|---|
| `stable-platform` | The Stable release gate passed on the same revision. |
| `actual-topology` | The capability ran on the real topology — a real sharded cluster, the real KMS, the actual target deployment. Atlas Local is a pull-request convenience and explicitly not release evidence (`MongoAtlasCapabilityContractSuite.Environment.ATLAS_LOCAL`). |
| `security` | Privileges reviewed; the capability's admin role is separate from the application role. |
| `migration` | A documented path in and, where the capability is irreversible, an explicit statement that there is no path back. |
| `failure` | Negative cases fail closed: wrong key, missing permission, rotation, non-ready index, unrouted query. |
| `runbook` | A runbook exists for the capability's characteristic incident. |
| `stable-platform` | 같은 revision에서 Stable 릴리스 gate가 통과했다. |
| `actual-topology` | capability가 실제 topology에서 돌았다 — 실제 sharded cluster, 실제 KMS, 실제 대상 배포. Atlas Local은 pull request용 편의이고 릴리스 증거가 아님을 명시한다(`MongoAtlasCapabilityContractSuite.Environment.ATLAS_LOCAL`). |
| `security` | 권한을 리뷰했다. capability의 admin role은 애플리케이션 role과 따로다. |
| `migration` | 들어가는 길을 적었고, capability가 되돌릴 수 없으면 돌아오는 길이 없다고 명시했다. |
| `failure` | 부정 경우가 실패하면 닫힌다: 틀린 키, 빠진 권한, 교체, 준비되지 않은 index, 라우팅되지 않은 query. |
| `runbook` | capability의 대표 사고를 위한 runbook이 있다. |
### Additional per-capability requirements
### capability별 추가 요구
- **Search / vector search:** relevance and performance evidence, not functional success alone.
`MongoVectorSearchBenchmarkGate` requires recall alongside latency and index size; a gate that
measures only latency certifies a fast wrong answer.
- **Database-per-tenant and reshard orchestration remain Experimental** until operational scale
evidence exists. Both are correct in the small and unbounded in the large.
- **Reshard requires an explicit `ReshardApproval`** — a named approver and a stated window. It
rewrites the collection.
- **search / vector search:** 기능 성공만이 아니라 관련성과 성능 증거. `MongoVectorSearchBenchmarkGate`는 지연 시간·index 크기와
함께 recall을 요구한다. 지연 시간만 재는 gate는 빠른 틀린 답을 인증한다.
- **테넌트마다 데이터베이스와 reshard 조율은 운영 규모 증거가 생길 때까지 Experimental로 남는다.** 둘 다 작게는 맞고 크게는
한계가 없다.
- **reshard에는 명시한 `ReshardApproval`이 필요하다** — 이름 있는 승인자와 밝힌 시간 창. reshard는 collection을 다시 쓴다.
### Promotion does not change the dependency boundary
### 승격은 의존 경계를 바꾸지 않는다
A capability promoted to Stable **remains an opt-in module** unless a later starter ADR changes the
dependency boundary. Promotion is a statement about evidence, not an invitation to add a transitive
dependency to every service.
Stable로 승격한 capability도 나중의 starter ADR이 의존 경계를 바꾸지 않는 한 **골라 쓰는 모듈로 남는다**. 승격은 증거에 대한
진술이지, 모든 서비스에 전이 의존을 더하라는 초대가 아니다.
## Consequences
## 결과
**Positive.** No capability reaches production on the strength of a container-only test. The evidence
list is the same for every capability, so promotion is reviewable rather than negotiated.
**좋은 점.** container 전용 시험을 근거로 운영에 닿는 capability는 없다. 증거 목록이 모든 capability에 같으므로, 승격은 흥정이
아니라 리뷰할 수 있는 것이 된다.
**Negative.** Promotion requires access to real infrastructure — a sharded cluster, a real KMS, the
target deployment. That is the cost of the guarantee: the alternative is finding out in production,
where encryption and sharding are both expensive to reverse.
**나쁜 점.** 승격에는 실제 기반 시설 — sharded cluster, 실제 KMS, 대상 배포 — 에 대한 접근이 필요하다. 그것이 보장의 비용이다:
대안은 운영에서 알게 되는 것이고, 거기서는 암호화와 sharding 둘 다 되돌리기 비싸다.
## Verification
## 검증
`scripts/verify-mongodb-advanced.sh` enforced this ADR until it was removed on 2026-08-15. The
promotion evidence categories this ADR requires are therefore no longer checked by any automated
gate; they are a review obligation until one is rebuilt. See `docs/mongodb/repository-adaptation.md`
§5 for the Gradle lanes the script wrapped.
`scripts/verify-mongodb-advanced.sh`가 2026-08-15에 지워질 때까지 이 ADR을 강제했다. 그래서 이 ADR이 요구하는 승격 증거
category는 이제 어떤 자동 gate도 검사하지 않는다. 다시 만들 때까지 리뷰 의무다. 그 script가 감싸던 Gradle lane은
`docs/mongodb/repository-adaptation.md` §5를 본다.
@@ -7,73 +7,62 @@
- 현재 정본: `docs/web/streaming-contract.md`
<!-- 머리 블록 끝 -->
# ADR-WEB-ADV-001: Streaming is live delivery, and the web module stores no history
# ADR-WEB-ADV-001: streaming은 실시간 전달이고, web 모듈은 이력을 저장하지 않는다
- Status: Accepted
- Date: 2026-08-25
- Scope: `adapter:inbound:web` — `advanced.stream.**`
- 상태: 채택
- 날짜: 2026-08-25
- 범위: `adapter:inbound:web` — `advanced.stream.**`
## Context
## 배경
Advanced Tasks 6–13 add SSE, NDJSON and JSON text sequences, with a `Last-Event-ID` resume path.
Advanced Task 6–13은 `Last-Event-ID` resume 경로와 함께 SSE, NDJSON, JSON text sequence를 더한다.
One fact drives every decision here: **after the first byte, the HTTP status is 200 and cannot
change.** A stream that ends because a dependency failed and one that ends because it finished are
identical at the transport layer — both are a closed connection after a 200. So is a stream that was
cut off mid-flight.
여기의 모든 결정을 이끄는 사실은 하나다: **첫 바이트 뒤에 HTTP status는 200이고 바꿀 수 없다.** 의존 대상이 실패해서 끝난
stream과 다 마쳐서 끝난 stream은 전송 계층에서 똑같다 — 둘 다 200 뒤에 닫힌 연결이다. 도중에 잘린 stream도 그렇다.
The second fact is that a resume path invites the web module to remember things. It must not: the
messaging platform already owns durable event history, and a second copy would have its own
retention, its own eviction and its own opinion about ordering.
둘째 사실은 resume 경로가 web 모듈에게 무언가를 기억하라고 꾄다는 것이다. 그러면 안 된다: durable 이벤트 이력은 이미 메시징
플랫폼이 가지고, 두 번째 사본은 자기 보존 기간, 자기 eviction, 순서에 대한 자기 의견을 가질 것이다.
## Decision
## 결정
**Three outcomes, expressed in the stream rather than in the status.** The wire record (for NDJSON,
`NdjsonRecord`) is an item, a failure or a completion. A client that sees neither terminal record
has been cut off, and that third case is recorded as `ABRUPT_CLOSE` rather than counted as a
completion — which is where a rising rate of mid-stream failures would otherwise hide.
**결과는 셋이고, status가 아니라 stream 안에서 나타낸다.** wire record(NDJSON이면 `NdjsonRecord`)는 항목, 실패, 완료 중 하나다.
끝 record를 하나도 보지 못한 client는 잘린 것이고, 그 셋째 경우는 완료로 세지 않고 `ABRUPT_CLOSE`로 기록한다 — 그렇지 않으면
도중 실패 비율이 오르는 것이 거기 숨는다.
**Nothing writes an error body onto a committed response.** Before commit, a failure is an ordinary
HTTP error (the `Envelope`) with a real status; after, a terminal record. Attempting both produces a
body that is half stream and half JSON, which no client parses and every proxy caches as a success.
(The mapper that encoded this, `WebStreamTerminationMapper`, was removed on 2026-09-25 with the
problem-document vocabulary it returned; the rule stands.)
**커밋된 응답 위에 오류 body를 쓰는 것은 없다.** 커밋 전의 실패는 실제 status를 가진 보통 HTTP 오류(`Envelope`)이고, 커밋 뒤에는
끝 record다. 둘 다 하려 하면 반은 stream이고 반은 JSON인 body가 나오는데, 어떤 client도 그것을 파싱하지 못하고 모든 proxy가
성공으로 cache한다. (이것을 인코딩하던 mapper `WebStreamTerminationMapper`는 그것이 돌려주던 problem document 어휘와 함께
2026-09-25에 지웠다. 규칙은 남는다.)
**Positions are monotonic, and it is enforced.** `WebStreamEvidence.recordDelivered` refuses a
repeated or regressing position. A client deduplicating on position would silently drop the second
item.
**위치는 단조 증가하고, 그것을 강제한다.** `WebStreamEvidence.recordDelivered`는 되풀이되거나 뒤로 가는 위치를 거절한다. 위치로
중복을 거르는 client는 두 번째 항목을 소리 없이 버리게 된다.
**A slow consumer is disconnected, not buffered.** `WebStreamPolicy.maxBufferedItems` is a hard
bound. Backpressure protects the reactive pipeline; it does not protect the server's heap from a
consumer that reads slowly for an hour.
**느린 소비자는 buffer에 담지 않고 연결을 끊는다.** `WebStreamPolicy.maxBufferedItems`는 단단한 한계다. backpressure는 reactive
pipeline을 지키지만, 한 시간 동안 천천히 읽는 소비자로부터 서버 heap을 지키지는 않는다.
**Every stream is in a registry, and shutdown drains it.** A node with a hundred open streams and no
other traffic looks idle by request rate. `WebStreamDrainCoordinator` stops accepting first, asks
clients to reconnect, and only then forces the remainder — because a client whose socket is cut
retries immediately, and if every socket is cut at once, every client retries at once.
**모든 stream은 registry에 있고, 종료가 그것을 비운다.** 열린 stream 백 개 말고 다른 traffic이 없는 노드는 요청 비율로 보면 놀고
있는 것처럼 보인다. `WebStreamDrainCoordinator`는 먼저 받기를 멈추고, client에게 다시 연결하라고 요청하고, 그다음에야 나머지를
강제로 끊는다 — socket이 끊긴 client는 바로 다시 시도하고, 모든 socket을 한꺼번에 끊으면 모든 client가 한꺼번에 다시 시도하기
때문이다.
**The web module stores no durable history.** `WebStreamReplaySource` is an interface this module
implements nowhere. An expired cursor raises `ReplayCursorExpiredException` rather than resuming from
the oldest retained position, because that delivers a stream with a hole the client cannot see.
**web 모듈은 durable 이력을 저장하지 않는다.** `WebStreamReplaySource`는 이 모듈이 어디에서도 구현하지 않는 인터페이스다. 만료된
cursor는 보존한 가장 오래된 위치에서 이어 가지 않고 `ReplayCursorExpiredException`을 올린다. 그렇게 하면 client가 볼 수 없는
구멍이 있는 stream을 전달하기 때문이다.
**The replay-to-live seam is watched.** `GapAndDuplicateGuard` detects both directions. Neither is
visible in either half on its own.
**재생에서 실시간으로 넘어가는 이음매를 지켜본다.** `GapAndDuplicateGuard`가 두 방향을 모두 찾는다. 어느 쪽도 한 절반만 보면
보이지 않는다.
## Consequences
## 결과
- Clients must handle three outcomes. A client that treats a closed connection as completion will be
wrong, and no server change can fix that for it.
- An expired `Last-Event-ID` costs the client a full re-read. That is the honest answer.
- JSON-seq is preferred over NDJSON where truncation matters: its separator comes first, so a parser
resynchronises at the next record. NDJSON's delimiter is the thing that gets truncated away.
- client는 결과 셋을 다뤄야 한다. 닫힌 연결을 완료로 다루는 client는 틀리고, 서버가 무엇을 바꿔도 그것을 대신 고칠 수 없다.
- 만료된 `Last-Event-ID`는 client에게 전체 다시 읽기를 치르게 한다. 그것이 정직한 답이다.
- 잘림이 중요한 곳에서는 NDJSON보다 JSON-seq를 고른다: 구분자가 앞에 오므로 parser가 다음 record에서 다시 맞춘다. NDJSON의
구분자는 잘려 나가는 바로 그것이다.
## Alternatives considered
## 따져 본 대안
- **Emit a problem document when a stream fails after commit.** Rejected: the body becomes
unparseable and the 200 is cached.
- **Resume from the oldest retained position when the cursor expires.** Rejected: positions are
contiguous from where the replay started, so nothing in the data says events are missing.
- **Store replay history in the web module.** Rejected: a second source of truth that drifts
invisibly.
- **Unbounded buffering for slow consumers.** Rejected: it moves the client's slowness into the
server's heap.
- **커밋 뒤에 stream이 실패하면 problem document를 낸다.** 버렸다: body가 파싱할 수 없게 되고 200이 cache된다.
- **cursor가 만료되면 보존한 가장 오래된 위치에서 이어 간다.** 버렸다: 위치는 재생이 시작된 곳부터 이어지므로, 데이터 안의 어떤
것도 이벤트가 빠졌다고 말하지 않는다.
- **재생 이력을 web 모듈에 저장한다.** 버렸다: 보이지 않게 어긋나는 두 번째 정본이다.
- **느린 소비자를 위한 한계 없는 buffer.** 버렸다: client의 느림을 서버 heap으로 옮긴다.
@@ -7,73 +7,60 @@
- 현재 정본: `docs/web/virtual-thread-profile.md`
<!-- 머리 블록 끝 -->
# ADR-WEB-ADV-002: Virtual threads change scheduling, not the concurrency budget
# ADR-WEB-ADV-002: virtual thread는 스케줄링을 바꾸지 동시성 예산을 바꾸지 않는다
- Status: Accepted
- Date: 2026-08-25
- Scope: `adapter:inbound:web` — `advanced.virtualthread`, `advanced.blockingbridge`
- 상태: 채택
- 날짜: 2026-08-25
- 범위: `adapter:inbound:web` — `advanced.virtualthread`, `advanced.blockingbridge`
## Context
## 배경
Advanced Task 2 offers a virtual-thread executor for MVC; Task 3 offered a bounded blocking bridge
for WebFlux. (The WebFlux adapter for it was removed on 2026-09-25 — the template is servlet only;
`advanced.blockingbridge` remains as library code.)
Advanced Task 2는 MVC용 virtual thread executor를 준다. Task 3은 WebFlux용 한계 있는 blocking bridge를 줬다. (그 WebFlux 어댑터는
2026-09-25에 지웠다 — 템플릿은 servlet만이다. `advanced.blockingbridge`는 라이브러리 코드로 남는다.)
A platform-thread MVC deployment has an implicit concurrency limit — the thread pool — and that
limit is usually what has been protecting the database pool, the outbound HTTP bulkhead and every
downstream service from the full arrival rate. Nobody wrote it down as an admission policy; it was a
side effect of the pool size.
platform thread MVC 배포에는 숨은 동시성 한계 — thread pool — 가 있고, 보통 그 한계가 데이터베이스 pool, outbound HTTP
bulkhead, 모든 하류 서비스를 전체 도착 비율로부터 지켜 왔다. 아무도 그것을 admission 정책으로 적지 않았다. pool 크기의
부작용이었다.
Switching to virtual threads deletes that limit without deleting anything that depended on it.
virtual thread로 바꾸면 그 한계가 지워지는데, 그것에 기대던 것은 하나도 지워지지 않는다.
## Decision
## 결정
**An explicit admission limit is required when virtual threads are enabled.**
`VirtualThreadProfile` refuses construction without one. Without it the deployment accepts every
arrival, queues all of them on the downstream budgets, and times out work that would have succeeded
had it been refused. The load that used to be shed at the front door is shed at the back, after the
cost of accepting it.
**virtual thread를 켜면 명시적 admission 한계가 필요하다.** `VirtualThreadProfile`은 그것 없이는 만들어지기를 거절한다. 없으면
배포는 모든 도착을 받고, 그것을 모두 하류 예산 위에 줄 세우며, 거절됐으면 성공했을 일을 timeout으로 끝낸다. 예전에 정문에서
덜어 내던 부하를, 받아들이는 비용을 치른 뒤 뒷문에서 덜어 낸다.
**The limit bounds concurrent use cases, not threads.** `VirtualThreadAdmissionGuard` is a fair
semaphore, not a pool. Bounding threads would put the waiting back and throw away what virtual
threads bought. Ten thousand virtual threads may exist while a hundred hold permits.
**한계는 스레드가 아니라 동시 유스케이스를 묶는다.** `VirtualThreadAdmissionGuard`는 pool이 아니라 공정한 semaphore다. 스레드를
묶으면 기다림을 되돌려 놓고 virtual thread가 산 것을 버린다. virtual thread 만 개가 있어도 허가를 쥔 것은 백 개일 수 있다.
**The downstream budgets are carried in the profile and stated as unchanged.** The whole point is
that they did not grow. `admissionFitsDownstreamBudgets()` reports when the admission limit exceeds
them, without refusing — a deployment can legitimately admit more than its pool when the work is not
all database-bound, and that should be a choice rather than an accident.
**하류 예산은 profile에 싣고 바뀌지 않았다고 밝힌다.** 요점은 그것이 늘지 않았다는 것이다. `admissionFitsDownstreamBudgets()`는
admission 한계가 그것을 넘으면 거절하지 않고 알린다 — 일이 모두 데이터베이스에 묶인 것이 아니면 배포가 pool보다 많이 받는
것이 정당할 수 있고, 그것은 사고가 아니라 선택이어야 한다.
**Blocking offloads are registered, bounded and timed out.** `boundedElastic()` is available from
anywhere and unbounded in practice, so a controller that calls it has silently opted the whole
application into an unbounded pool. `BlockingBridgeProfile` names the operations permitted to
offload; `BlockingBridgeBudget` bounds the concurrency and refuses a caller that cannot get a slot
in time, because otherwise a slow dependency's callers accumulate until the heap does and the fast
dependencies starve behind them.
**blocking offload는 등록하고, 한계를 두고, timeout을 둔다.** `boundedElastic()`은 어디서나 쓸 수 있고 실제로는 한계가 없어서,
그것을 부르는 controller는 애플리케이션 전체를 소리 없이 한계 없는 pool에 들여놓는다. `BlockingBridgeProfile`이 offload해도 되는
operation을 이름으로 대고, `BlockingBridgeBudget`이 동시성을 묶으며 제때 자리를 얻지 못한 호출자를 거절한다. 그렇지 않으면 느린
의존 대상의 호출자가 heap이 찰 때까지 쌓이고 빠른 의존 대상이 그 뒤에서 굶는다.
> 2026-09-25: `advanced.blockingbridge` was removed. Its WebFlux adapter went with the WebFlux twin
> (D4), and a budget for a bridge that no longer exists bounded nothing.
> 2026-09-25: `advanced.blockingbridge`를 지웠다. 그 WebFlux 어댑터는 WebFlux 쌍둥이와 함께 갔고(D4), 더는 없는 bridge의 예산은
> 아무것도 묶지 않았다.
**Pinning is observed, not assumed away.** `VirtualThreadProfile.requiredObservations()` lists what
has to be watched — `jdk.VirtualThreadPinned` above all. A synchronized block held across a blocking
call pins the carrier thread, the carrier pool is bounded by CPU count, and enough pinned carriers is
a deadlock a thread dump does not obviously show.
**pinning은 없다고 치지 않고 관찰한다.** `VirtualThreadProfile.requiredObservations()`가 지켜봐야 할 것 — 무엇보다
`jdk.VirtualThreadPinned` — 을 적는다. blocking 호출을 가로질러 쥔 synchronized 블록은 carrier thread를 고정하고, carrier pool은
CPU 수로 묶여 있으며, 고정된 carrier가 충분히 많으면 thread dump로도 잘 드러나지 않는 교착이 된다.
## Consequences
## 결과
- Enabling virtual threads is a two-part change: the executor and the admission limit. The profile
will not let it be one.
- Refusals rise under load, and that is correct. A request refused in a millisecond is better for
the client than the same request accepted and timed out thirty seconds later behind a full pool.
An operator seeing 503s climb should read them as the limit working.
- `VirtualThreadAdmissionGuard.peakActive()` exists so a load test can assert the limit was applied.
It is invisible from throughput, which is why a load test that only measures throughput would pass
with the guard removed.
- virtual thread 켜기는 두 부분짜리 변경이다: executor와 admission 한계. profile은 그것이 한 부분이 되게 두지 않는다.
- 부하 아래에서 거절이 오르고, 그것이 맞다. 1밀리초 안에 거절된 요청이, 꽉 찬 pool 뒤에서 받아들여졌다가 30초 뒤 timeout된 같은
요청보다 client에게 낫다. 503이 오르는 것을 본 운영자는 그것을 한계가 동작하는 것으로 읽어야 한다.
- `VirtualThreadAdmissionGuard.peakActive()`는 부하 시험이 한계가 적용됐음을 단언할 수 있게 하려고 있다. 처리량에서는 보이지
않는다. 그래서 처리량만 재는 부하 시험은 guard를 빼도 통과한다.
## Alternatives considered
## 따져 본 대안
- **Enable virtual threads and raise the downstream budgets to match.** Rejected: the budgets are
sized to what the dependencies can serve, not to what the web tier can accept.
- **Bound the virtual threads themselves with a fixed-size executor.** Rejected: that is a platform
thread pool with extra steps.
- **Let controllers call `boundedElastic()` directly.** Rejected: every such call site is invisible
until the pool is the thing consuming the heap.
- **virtual thread를 켜고 하류 예산을 거기 맞춰 올린다.** 버렸다: 예산은 web 계층이 받을 수 있는 양이 아니라 의존 대상이 감당할
수 있는 양에 맞춘 것이다.
- **고정 크기 executor로 virtual thread 자체를 묶는다.** 버렸다: 단계만 더 많은 platform thread pool이다.
- **controller가 `boundedElastic()`을 직접 부르게 둔다.** 버렸다: 그런 호출 자리는 pool이 heap을 먹는 범인이 될 때까지 하나도
보이지 않는다.
@@ -7,62 +7,51 @@
- 현재 정본: `docs/web/openapi-32-compatibility.md`
<!-- 머리 블록 끝 -->
# ADR-WEB-ADV-003: OpenAPI 3.2 is generated in parallel and stays experimental
# ADR-WEB-ADV-003: OpenAPI 3.2는 나란히 생성하고 실험용으로 남는다
- Status: Accepted
- Date: 2026-08-25
- Scope: `adapter:inbound:web` — `advanced.openapi`
- 상태: 채택
- 날짜: 2026-08-25
- 범위: `adapter:inbound:web` — `advanced.openapi`
## Context
## 배경
Advanced Task 17 adds an OpenAPI 3.2 generation lane beside the Stable 3.1.2 snapshot.
Advanced Task 17은 Stable 3.1.2 snapshot 옆에 OpenAPI 3.2 생성 lane을 더한다.
Generating 3.2 is cheap. Adopting it is not, and the two get conflated because the generated
document looks fine. The value of an API description is entirely in what consumes it, and a document
in a version a client generator does not fully understand produces a client that compiles and is
wrong — which is worse than no document at all.
3.2 생성은 싸다. 채택은 싸지 않고, 생성된 문서가 멀쩡해 보여서 둘이 뒤섞인다. API 설명의 가치는 전부 그것을 쓰는 쪽에 있고,
client 생성기가 다 이해하지 못하는 버전의 문서는 컴파일되지만 틀린 client를 낳는다 — 문서가 아예 없는 것보다 나쁘다.
## Decision
## 결정
**3.1.2 remains the release artifact.** `OpenApiVersionLane.STABLE_3_1.releaseArtifact()` is true and
`EXPERIMENTAL_3_2`'s is false. This is a property of the type, not a configuration setting.
**3.1.2가 릴리스 artifact로 남는다.** `OpenApiVersionLane.STABLE_3_1.releaseArtifact()`는 true이고 `EXPERIMENTAL_3_2`의 것은
false다. 이것은 설정이 아니라 타입의 성질이다.
**Generating 3.2 must not change the 3.1 snapshot.** Both are produced from the same model, so a
contributor that mutates it on the way to 3.2 changes the artifact that is actually shipped —
silently, and only when the experimental lane runs. `OpenApi32CompatibilityReport` compares the
snapshot hash before and after and makes a difference a promotion blocker.
**3.2를 생성해도 3.1 snapshot이 바뀌면 안 된다.** 둘은 같은 모델에서 만들어지므로, 3.2로 가는 길에 모델을 바꾸는 기여자는 실제로
출하하는 artifact를 바꾼다 — 소리 없이, 실험 lane이 돌 때만. `OpenApi32CompatibilityReport`가 전후의 snapshot hash를 비교하고,
차이를 승격을 막는 것으로 만든다.
> 2026-09-25: `OpenApi32CompatibilityReport` and `OpenApiToolchainMatrix` were removed — promotion
> checks kept in production code, called only by their own tests. `WebOpenApi32Generator` remains
> as library code in `adapter:inbound:web-advanced`; the decision below is unchanged.
> 2026-09-25: `OpenApi32CompatibilityReport`와 `OpenApiToolchainMatrix`를 지웠다 — 운영 코드에 둔 승격 검사인데 자기 시험만
> 불렀다. `WebOpenApi32Generator`는 `adapter:inbound:web-advanced`에 라이브러리 코드로 남는다. 아래 결정은 바뀌지 않았다.
**Four kinds of tool are checked separately.** A parser reports structural errors; a linter applies
style rules and accepts documents a parser rejects; a generator produces client code, and this is
where an unsupported construct surfaces — not as an error but as a method with the wrong signature;
a compile of that generated code is the only step that catches it. "OpenAPI 3.2 works" is not a
statement anybody can make. "This document is read correctly by these four tools at these versions"
is.
**도구 네 종류를 따로 검사한다.** parser는 구조 오류를 알린다. linter는 문체 규칙을 적용하고 parser가 거절하는 문서도 받는다.
생성기는 client 코드를 만들고, 지원되지 않는 구문이 드러나는 곳이 여기다 — 오류가 아니라 시그니처가 틀린 메서드로. 그 생성 코드를
컴파일하는 것이 그것을 잡는 유일한 단계다. 「OpenAPI 3.2가 된다」는 누구도 할 수 있는 말이 아니다. 「이 문서를 이 버전의 이 네
도구가 맞게 읽는다」는 할 수 있다.
**Promotion requires an accepted ADR regardless of how green the matrix is.**
`promotionBlockers(false)` always contains that blocker. A machine-checkable matrix cannot decide
whether the consumer population is ready.
**표가 얼마나 초록이든 승격에는 채택된 ADR이 필요하다.** `promotionBlockers(false)`는 언제나 그 막음을 담는다. 기계로 검사하는
표는 쓰는 쪽 집단이 준비됐는지 정할 수 없다.
**Streaming description differences are reported separately.** They are the substantive difference
between the two versions for this application, and folding them into a pass/fail hides what
changed.
**streaming 설명의 차이는 따로 알린다.** 이 애플리케이션에서 두 버전의 실질적 차이가 그것이고, 통과·실패 하나로 접으면 무엇이
바뀌었는지 가려진다.
## Consequences
## 결과
- The 3.2 document is published as an artifact of the experimental workflow, never of the release
workflow.
- A client generator that only understands 3.1 is unaffected, which is the point.
- Adopting 3.2 later is a documented decision with a named consumer matrix behind it.
- 3.2 문서는 릴리스 workflow가 아니라 실험 workflow의 artifact로만 게시한다.
- 3.1만 이해하는 client 생성기는 영향을 받지 않는다. 그것이 요점이다.
- 나중에 3.2를 채택하는 것은 이름 있는 쓰는 쪽 표를 뒤에 둔, 문서로 남긴 결정이다.
## Alternatives considered
## 따져 본 대안
- **Switch to 3.2 and keep a 3.1 downgrade.** Rejected: the downgrade is lossy in exactly the
constructs 3.2 was wanted for, so it would ship a description that is wrong for both audiences.
- **Generate only 3.2 and let consumers cope.** Rejected: the failure mode is a generated client
that compiles and misbehaves.
- **Skip the client-compile step in the matrix.** Rejected: it is the only one that catches the
failure the others miss.
- **3.2로 바꾸고 3.1로 낮춘 것을 둔다.** 버렸다: 낮추기는 바로 3.2를 원한 이유인 구문에서 손실이 있어서, 두 독자 모두에게 틀린
설명을 출하하게 된다.
- **3.2만 생성하고 쓰는 쪽이 알아서 하게 둔다.** 버렸다: 실패 방식은 컴파일되고 잘못 동작하는 생성 client다.
- **표에서 client 컴파일 단계를 건너뛴다.** 버렸다: 다른 단계가 놓치는 실패를 잡는 유일한 단계다.
@@ -8,62 +8,51 @@
- 대체됨: `docs/capability-status.md`
<!-- 머리 블록 끝 -->
# ADR-WS-001: The WebSocket platform ships as packages in one leaf, with machine-checked boundaries
# ADR-WS-001: WebSocket 플랫폼은 leaf 하나 안의 패키지로 싣고, 경계는 기계로 검사한다
- Status: Superseded 2026-09-25 — the eighteen-package platform was cut to the parts a Spring
configuration or a real-container lane reaches: the `stomp` channel and the servlet handler
library (`servlet`, `outbound`, `budget`). The Advanced packages, the reactive runtime and the
`WebSocketArchitectureRules` pack went with the rest (see `docs/capability-status.md`).
- Date: 2026-08-25
- Scope: `:adapter:inbound:websocket`
- 상태: 대체됨 2026-09-25 — 패키지 열여덟 개짜리 플랫폼을 Spring 설정이나 실제 container lane이 닿는 부분으로 잘랐다: `stomp`
채널과 servlet handler 라이브러리(`servlet`, `outbound`, `budget`). Advanced 패키지, reactive runtime, `WebSocketArchitectureRules`
묶음은 나머지와 함께 갔다(`docs/capability-status.md`를 본다).
- 날짜: 2026-08-25
- 범위: `:adapter:inbound:websocket`
## Context
## 배경
The realtime connection platform design models itself as eighteen Gradle modules under
`modules/websocket`, each with a declared purity grade and a declared set of allowed dependencies.
This repository's `src/config/architecture/modules.json` is a fail-closed registry that owns the
leaf list; adding eighteen leaves is a registry change of a size that needs its own decision, and
HARD-STOP #5 forbids doing it implicitly.
실시간 연결 플랫폼 설계는 스스로를 `modules/websocket` 아래 Gradle 모듈 열여덟 개로 모델링하고, 모듈마다 순수성 등급과 허용 의존
집합을 선언한다. 이 저장소의 `src/config/architecture/modules.json`은 leaf 목록을 가진 실패하면 닫히는 registry다. leaf 열여덟 개를
더하는 것은 자기 결정이 필요한 크기의 registry 변경이고, HARD-STOP #5가 그것을 은근슬쩍 하는 것을 금지한다.
Three earlier platforms in this repository — JPA, GraphQL, and the HTTP platform — met the same
situation and resolved it the same way.
이 저장소의 앞선 플랫폼 셋 — JPA, GraphQL, HTTP 플랫폼 — 이 같은 상황을 만났고 같은 방식으로 풀었다.
## Decision
## 결정
The eighteen design modules ship as packages inside the single registered leaf. `WebSocketStableModule`
declares each one's package, purity grade and exact allowed edges, and `WebSocketModuleBoundaryTest`
scans the production tree and fails when the declaration and the tree disagree in either direction.
설계 모듈 열여덟 개를 등록된 leaf 하나 안의 패키지로 싣는다. `WebSocketStableModule`이 모듈마다 패키지, 순수성 등급, 정확한 허용
edge를 선언하고, `WebSocketModuleBoundaryTest`가 운영 트리를 scan해 선언과 트리가 어느 방향으로든 다르면 실패한다.
Three deviations from the design's module map were forced by the check and are recorded in
`docs/websocket/repository-adaptation.md`: `WebSocketSubprotocolName` moved to `core` and the codec
moved to its own FRAMEWORK_BOUND module, both to avoid cycles the design's placement created here;
and the `budget -> core` edge was inverted because `budget` imports nothing from `core`.
검사가 강요한, 설계 모듈 지도와 다른 점 셋은 `docs/websocket/repository-adaptation.md`에 적었다: `WebSocketSubprotocolName`을
`core`로 옮겼고 codec을 자기 FRAMEWORK_BOUND 모듈로 옮겼다. 둘 다 설계의 배치가 여기서 만든 순환을 피하려는 것이다. 그리고
`budget`이 `core`에서 아무것도 import하지 않으므로 `budget -> core` edge를 뒤집었다.
## Consequences
## 결과
**The boundary is enforced, not documented.** Six violations were caught during implementation that
a document would not have: two would-be cycles, a duplicate module declaration where two ids claimed
one package, and three undeclared edges. The duplicate is the instructive one — with two ids on one
package, ownership depends on iteration order and one module's rules silently apply to nothing. A
guard against it is now part of the boundary test.
**경계를 문서로 두지 않고 강제한다.** 구현 중에 문서라면 잡지 못했을 위반 여섯 개를 잡았다: 순환이 될 뻔한 것 둘, id 둘이 패키지
하나를 주장한 중복 모듈 선언, 선언하지 않은 edge 셋. 배울 것이 있는 쪽은 중복이다 — 패키지 하나에 id가 둘이면 소유가 반복 순서에
달리고 한 모듈의 규칙이 소리 없이 아무것에도 적용되지 않는다. 그것을 막는 guard가 이제 경계 시험의 일부다.
**The detector had a hole.** Its framework-import list named `com.fasterxml` (Jackson 2) and not
`tools.jackson` (Jackson 3), which is what Spring 7 actually uses — so a CORE module could have
imported a mapper unnoticed. Fixed here and in the HTTP platform, which shared the list.
**찾는 장치에 구멍이 있었다.** 그 프레임워크 import 목록은 `com.fasterxml`(Jackson 2)를 대고 Spring 7이 실제로 쓰는
`tools.jackson`(Jackson 3)을 대지 않았다 — 그래서 CORE 모듈이 mapper를 import해도 들키지 않을 수 있었다. 여기와, 그 목록을 같이 쓰던
HTTP 플랫폼에서 고쳤다.
**Promotion stays cheap.** Each enum constant is already shaped like a leaf specification, so
splitting one out later is a registry edit rather than an archaeology exercise.
**승격은 싸게 남는다.** enum 상수 하나하나가 이미 leaf 명세 모양이라서, 나중에 하나를 떼어 내는 것은 고고학이 아니라 registry
수정이다.
**The design's own rules were kept where they cost something.** `core` names no framework, so the
same decisions serve both runtimes and are testable without a server; no Java class name reaches the
wire; the payload is an encoded string rather than a map; and handlers are given no way to write,
which is what makes ordering and backpressure guarantees rather than conventions.
**비용이 드는 곳에서도 설계 자신의 규칙을 지켰다.** `core`는 어떤 프레임워크도 이름으로 대지 않으므로 같은 결정이 두 runtime에
쓰이고 서버 없이 시험할 수 있다. Java 클래스 이름이 wire에 닿지 않는다. payload는 map이 아니라 인코딩한 문자열이다. 그리고
handler에게는 쓸 길을 주지 않는다. 그것이 순서와 backpressure를 관례가 아니라 보장으로 만든다.
## Alternatives considered
## 따져 본 대안
**Register eighteen leaves.** Faithful to the design and a large change to a fail-closed registry
for a platform that ships as one artifact either way. Rejected as disproportionate; the boundary
test provides the property the modules were for.
**leaf 열여덟 개를 등록한다.** 설계에 충실하지만, 어느 쪽이든 artifact 하나로 싣는 플랫폼을 위해 실패하면 닫히는 registry를 크게
바꾼다. 지나치다고 보고 버렸다. 경계 시험이 모듈이 주려던 성질을 준다.
**Ship the modules as packages with no enforcement.** Cheapest, and it makes the boundary a claim.
The six violations found during implementation are the argument against it.
**모듈을 강제 없는 패키지로 싣는다.** 가장 싸지만 경계를 주장으로 만든다. 구현 중에 찾은 위반 여섯 개가 그것에 반대하는 근거다.
+39 -47
View File
@@ -8,64 +8,56 @@
- 대체됨: `docs/capability-status.md`
<!-- 머리 블록 끝 -->
# ADR-WS-002: Resume and cluster state are caches, and are treated as caches
# ADR-WS-002: resume와 cluster 상태는 cache이고, cache로 다룬다
- Status: Superseded 2026-09-25 — `advanced.resume`, `advanced.cluster` and `advanced.presence`
were removed: nothing assembled them (see `docs/capability-status.md`).
- Date: 2026-08-25
- Scope: `adapter:inbound:websocket` — `advanced.resume`, `advanced.cluster`, `advanced.presence`
- 상태: 대체됨 2026-09-25 — `advanced.resume`, `advanced.cluster`, `advanced.presence`를 지웠다: 아무것도 그것을 조립하지
않았다(`docs/capability-status.md`를 본다).
- 날짜: 2026-08-25
- 범위: `adapter:inbound:websocket` — `advanced.resume`, `advanced.cluster`, `advanced.presence`
## Context
## 배경
Advanced Tasks 2–8 add three things that all look like state and are not: a resume token that says
where a client got to, a cluster index that says which node holds a session, and a presence summary
derived from that index.
Advanced Task 2–8은 모두 상태처럼 보이지만 상태가 아닌 것 셋을 더한다: client가 어디까지 왔는지 말하는 resume token, 어느 노드가
세션을 가졌는지 말하는 cluster index, 그 index에서 끌어낸 presence 요약.
Each is a statement about the past. The resume token was minted before the disconnect; the index
entry was written by a node that may since have died; presence is a read of the index and inherits
everything wrong with it. The failure this ADR exists to prevent is treating any of them as current
fact, because each reads as one at the call site.
하나하나가 과거에 대한 진술이다. resume token은 연결이 끊기기 전에 만들어졌다. index 항목은 그 뒤에 죽었을 수 있는 노드가 썼다.
presence는 index를 읽은 것이고 그것의 틀린 점을 모두 물려받는다. 이 ADR이 막으려는 실패는 그중 어느 것이든 지금의 사실로 다루는
것이다. 부르는 자리에서는 하나같이 사실처럼 읽히기 때문이다.
## Decision
## 결정
**Resume is bounded by what the replay store actually holds, not by what the token claims.**
`ResumeCoordinator` consults `ReplayAvailability` before honouring a position. A token that names a
position the store has evicted produces a resynchronise, not a gap-filled stream. The alternative —
trusting the token — silently delivers a stream with a hole in it, which is worse than an explicit
resynchronise because the client believes it is complete.
**resume은 token이 주장하는 것이 아니라 replay 저장소가 실제로 가진 것으로 묶는다.** `ResumeCoordinator`는 위치를 받아 주기 전에
`ReplayAvailability`를 묻는다. 저장소가 이미 버린 위치를 대는 token은 빈틈을 메운 stream이 아니라 다시 맞추기를 낸다. 대안 — token을
믿기 — 은 구멍 난 stream을 소리 없이 전달하고, client가 그것이 완전하다고 믿으므로 명시적 다시 맞추기보다 나쁘다.
**Cluster index entries carry an observation time and are checked against it on every read.**
`ExternalSessionSummary.staleAt` exists so that "the index says edge-2" cannot be used without also
answering "as of when". An entry whose node stopped reporting is not evidence that the node holds
the session.
**cluster index 항목은 관찰 시각을 싣고, 읽을 때마다 그것과 대조한다.** `ExternalSessionSummary.staleAt`은 「index가 edge-2라고
한다」를 「언제 기준으로」에 답하지 않고는 쓸 수 없게 하려고 있다. 보고를 멈춘 노드의 항목은 그 노드가 세션을 가졌다는 증거가
아니다.
**Durable fan-out is deduplicated by stream position, not by message id.** At-least-once is the
contract, so redelivery is normal operation: a redeploy, a slow consumer or a broker rebalance all
produce it. `FanoutDeduplicator` keys on `(stream, position)` and advances a high-water mark under
`compute`, so two consumer threads cannot both deliver the same position.
**durable fan-out의 중복은 message id가 아니라 stream 위치로 거른다.** 계약이 at-least-once이므로 재전달은 보통 동작이다: 재배포,
느린 소비자, broker rebalance가 모두 그것을 낳는다. `FanoutDeduplicator`는 `(stream, position)`을 키로 쓰고 `compute` 아래에서
high-water mark를 올리므로, 소비자 스레드 둘이 같은 위치를 둘 다 전달할 수 없다.
**Presence has four states, not two.** `OFFLINE` is a reported fact; `STALE` is the absence of one.
Collapsing them reports every user as disconnected during a Redis partition, when what happened is
that the index went dark and the connections are fine.
**presence에는 상태가 둘이 아니라 넷이다.** `OFFLINE`은 보고된 사실이고, `STALE`은 사실이 없는 것이다. 둘을 합치면 Redis partition
동안 모든 사용자를 연결 끊김으로 알리는데, 실제로 일어난 일은 index가 어두워졌고 연결은 멀쩡한 것이다.
**Nothing security-relevant may depend on presence.** An attacker who can make a node stop reporting
can move the platform's belief about who is present. Presence answers "show a green dot".
**보안에 관련된 어떤 것도 presence에 기대면 안 된다.** 노드가 보고를 멈추게 할 수 있는 공격자는 누가 있는지에 대한 플랫폼의 믿음을
움직일 수 있다. presence는 「초록 점을 보여 줄까」에 답한다.
## Consequences
## 결과
- A resume that cannot be honoured is visible to the client as a resynchronise. Clients must
implement one; there is no mode in which the platform silently pretends.
- Every read of the cluster index needs a clock. This is deliberate friction.
- `PresenceSummary.classify` refuses an idle window at or past the stale window, because otherwise
`IDLE` is unreachable and the caller believes it has a four-state model when it has three.
- Fan-out envelopes carry a bounded reference and the catalog-encoded document, never a business
object. A rolling deploy has two versions of the code reading the same envelope.
- 받아 줄 수 없는 resume은 client에게 다시 맞추기로 보인다. client는 그것을 구현해야 한다. 플랫폼이 소리 없이 시늉하는 모드는 없다.
- cluster index를 읽을 때마다 시계가 필요하다. 일부러 둔 마찰이다.
- `PresenceSummary.classify`는 stale 창 이상인 idle 창을 거절한다. 그렇지 않으면 `IDLE`에 닿을 수 없고, 호출자는 상태 셋짜리를
가지고 넷짜리 모델이라고 믿는다.
- fan-out envelope은 한계 있는 참조와 catalog로 인코딩한 문서를 싣고, 업무 객체는 싣지 않는다. rolling deploy에서는 코드 두 버전이
같은 envelope을 읽는다.
## Alternatives considered
## 따져 본 대안
- **Trust the resume token.** Rejected: it makes a gap indistinguishable from a complete stream.
- **Deduplicate by message id.** Rejected: a broker that redelivers may re-mint ids, and a producer
that retries certainly does. Position is the property the ordering actually has.
- **A single `online` boolean.** Rejected for the partition case above.
- **Write presence separately from the session index.** Rejected: two sources of truth for "who is
connected" drift, and the drift is invisible — both look plausible and nothing reconciles them.
- **resume token을 믿는다.** 버렸다: 빈틈을 완전한 stream과 구별할 수 없게 만든다.
- **message id로 중복을 거른다.** 버렸다: 재전달하는 broker는 id를 다시 만들 수 있고, 재시도하는 producer는 반드시 그렇게 한다.
위치가 순서가 실제로 가진 성질이다.
- **`online` boolean 하나.** 위 partition 경우 때문에 버렸다.
- **presence를 세션 index와 따로 쓴다.** 버렸다: 「누가 연결돼 있나」의 정본이 둘이면 어긋나고, 그 어긋남은 보이지 않는다 — 둘 다
그럴듯해 보이고 아무것도 둘을 맞추지 않는다.
+45 -57
View File
@@ -8,78 +8,66 @@
- 대체됨: `docs/capability-status.md`
<!-- 머리 블록 끝 -->
# ADR-WS-003: STOMP is an Advanced adapter with a declared destination catalog
# ADR-WS-003: STOMP는 destination catalog를 선언한 Advanced 어댑터다
- Status: Superseded 2026-09-25 — `advanced.stomp` and `advanced.stomp.rabbit` were removed; the
`stomp` package is the only STOMP channel (see `docs/capability-status.md`).
- Date: 2026-08-25
- Scope: `adapter:inbound:websocket` — `advanced.stomp`, `advanced.stomp.rabbit`
- 상태: 대체됨 2026-09-25 — `advanced.stomp`와 `advanced.stomp.rabbit`을 지웠다. `stomp` 패키지가 유일한 STOMP 채널이다
(`docs/capability-status.md`를 본다).
- 날짜: 2026-08-25
- 범위: `adapter:inbound:websocket` — `advanced.stomp`, `advanced.stomp.rabbit`
## Context
## 배경
Advanced Tasks 9–13 add STOMP 1.2 alongside the platform's own protocol, plus a RabbitMQ broker
relay and cross-node user destinations.
Advanced Task 9–13은 플랫폼 자신의 프로토콜 옆에 STOMP 1.2를 더하고, RabbitMQ broker relay와 노드를 가로지르는 user destination도
더한다.
This leaf already ships an older STOMP-over-SockJS channel (`stomp`, gated on
`app.websocket.enabled`). Two `@EnableWebSocketMessageBroker` configurations in one context
do not conflict loudly — both contribute a configurer, both call `configureMessageBroker`, and the
broker that results is whichever ran last. Nothing errors and nothing logs.
이 leaf는 이미 더 오래된 STOMP-over-SockJS 채널(`stomp`, `app.websocket.enabled`로 막는다)을 싣는다. 한 context 안의
`@EnableWebSocketMessageBroker` 설정 둘은 시끄럽게 충돌하지 않는다 — 둘 다 configurer를 기여하고, 둘 다
`configureMessageBroker`를 부르며, 결과 broker는 마지막에 돈 쪽의 것이다. 오류도 로그도 없다.
STOMP also brings a destination model that is a free string from the client. Without a catalog, the
set of reachable destinations is whatever the broker accepts, which for the simple broker is every
string.
STOMP는 client에게서 오는 자유 문자열인 destination 모델도 가져온다. catalog가 없으면 닿을 수 있는 destination 집합은 broker가 받는
모든 것이고, simple broker에게 그것은 모든 문자열이다.
## Decision
## 결정
**The Advanced adapter is its own module (`advanced-stomp`), separate from `advanced`.** It is the
one Advanced capability that cannot be pure — STOMP here *is* the Spring Messaging types — and
folding it into `advanced` would relax that module's purity for every capability in it.
**Advanced 어댑터는 `advanced`와 따로 둔 자기 모듈(`advanced-stomp`)이다.** 순수할 수 없는 유일한 Advanced capability다 — 여기서
STOMP는 곧 Spring Messaging 타입이다 — 그리고 `advanced`에 접어 넣으면 그 모듈의 모든 capability에 대해 순수성을 느슨하게 만든다.
**The relay is a further module (`advanced-stomp-rabbit`).** The adapter parses a protocol; the
relay opens a TCP connection to somebody else's broker and makes every delivery depend on it.
Different blast radius, different decision, different module.
**relay는 그다음 모듈(`advanced-stomp-rabbit`)이다.** 어댑터는 프로토콜을 파싱한다. relay는 남의 broker에 TCP 연결을 열고 모든
전달을 그것에 기대게 만든다. 피해 범위가 다르고, 결정이 다르고, 모듈이 다르다.
**Destinations are declared, per operation.** `StompDestinationCatalog` maps `(operation,
destination)` to a required permission. Undeclared is refused. `SUBSCRIBE` and `SEND` are separate
declarations, because reading a feed and publishing into it are different rights.
**destination은 operation마다 선언한다.** `StompDestinationCatalog`는 `(operation, destination)`을 필요한 권한에 대응시킨다. 선언하지
않은 것은 거절한다. `SUBSCRIBE`와 `SEND`는 따로 선언한다. feed를 읽는 것과 거기에 게시하는 것은 다른 권리이기 때문이다.
**The authorization decision is a value, not an interceptor method.** `StompAuthorizationPolicy`
returns a `StompAuthorizationDecision`; `StompSecurityInterceptor` only extracts and enforces. A rule
reachable only through a `MessageChannel` gets tested for the cases somebody built a channel for.
**인가 판정은 interceptor 메서드가 아니라 값이다.** `StompAuthorizationPolicy`가 `StompAuthorizationDecision`을 돌려주고,
`StompSecurityInterceptor`는 꺼내서 강제하기만 한다. `MessageChannel`을 거쳐서만 닿는 규칙은 누가 channel을 만들어 둔 경우만
시험된다.
**Only one STOMP runtime may run.** `StompBrokerExclusivity` fails the context when both channels
are enabled, when both brokers are, or when the adapter is enabled with no broker behind it.
**STOMP runtime은 하나만 돌 수 있다.** `StompBrokerExclusivity`는 두 채널이 모두 켜졌을 때, 두 broker가 모두 켜졌을 때, 또는 뒤에
broker 없이 어댑터가 켜졌을 때 context를 실패시킨다.
**A `RECEIPT` is never promoted to a commit.** `StompEvidence` has six stages and
`StompAckPolicy.evidenceForReceipt()` is fixed at `PROTOCOL_RECEIPT`. The receipt is written by the
protocol layer, which knows nothing about whether the work succeeded.
**`RECEIPT`는 절대 커밋으로 올리지 않는다.** `StompEvidence`에는 단계가 여섯 있고 `StompAckPolicy.evidenceForReceipt()`는
`PROTOCOL_RECEIPT`로 고정이다. receipt는 프로토콜 계층이 쓰고, 그 계층은 일이 성공했는지 아무것도 모른다.
**The simple broker declares what it cannot do.** `SimpleBrokerProfile` cannot be constructed
claiming cluster support or durable acks, and refuses activation outside local/test — in a
multi-node deployment it does not error, it delivers to whichever fraction of users is on the
publishing node.
**simple broker는 할 수 없는 것을 선언한다.** `SimpleBrokerProfile`은 cluster 지원이나 durable ack를 주장하며 만들 수 없고,
local·test 밖에서 켜기를 거절한다 — 여러 노드 배포에서 그것은 오류를 내지 않고, 게시한 노드에 있는 사용자 일부에게만 전달한다.
**Unresolved user destinations are broadcast once and then dead-lettered.**
`MultiNodeUserDestination` distinguishes a message that arrived *via* the broadcast from one that did
not. Without that, every node rebroadcasts every unresolvable message on receipt.
**풀리지 않은 user destination은 한 번 broadcast한 뒤 dead-letter로 보낸다.** `MultiNodeUserDestination`은 broadcast를 *거쳐* 온
메시지와 그렇지 않은 메시지를 구별한다. 그렇지 않으면 모든 노드가 풀 수 없는 메시지를 받을 때마다 다시 broadcast한다.
## Consequences
## 결과
- Enabling Advanced STOMP requires disabling the legacy channel. There is no migration path that
runs both; the exclusivity check makes that explicit at startup rather than at 3am.
- A deployment must write its own catalog. There is deliberately no default: an empty one refuses
every frame and reads as a broken adapter, and a non-empty one publishes destinations nobody chose.
- The relay's cost is one broker connection per authenticated session plus one system connection.
`brokerConnectionsFor` exists so this is computed before the first outage.
- User-destination metrics are tagged with `UserDestinationAction`, never the destination — a user
destination contains a user identifier by construction.
- Advanced STOMP를 켜려면 옛 채널을 꺼야 한다. 둘을 함께 돌리는 옮기기 길은 없다. 배타성 검사가 그것을 새벽 3시가 아니라 기동
때 분명히 한다.
- 배포는 자기 catalog를 써야 한다. 일부러 기본값이 없다: 빈 catalog는 모든 frame을 거절해서 고장 난 어댑터처럼 읽히고, 비어 있지
않은 기본 catalog는 아무도 고르지 않은 destination을 게시한다.
- relay의 비용은 인증된 세션마다 broker 연결 하나 + 시스템 연결 하나다. `brokerConnectionsFor`는 첫 장애 전에 그것을 계산하려고
있다.
- user destination metric은 destination이 아니라 `UserDestinationAction`으로 tag를 단다 — user destination은 구조상 사용자 식별자를
담는다.
## Alternatives considered
## 따져 본 대안
- **Extend the existing `stomp` package.** Rejected: it is Stable, and WS-ARCH-6 forbids a Stable
module naming an Advanced one. Making the legacy channel profile-driven would have required that
edge.
- **One `advanced-stomp` module including the relay.** Rejected: the relay is a separate operational
decision and deserves to be refusable on its own.
- **Allow undeclared destinations with a wildcard permission.** Rejected: the wildcard becomes the
default and the catalog becomes documentation.
- **기존 `stomp` 패키지를 넓힌다.** 버렸다: 그것은 Stable이고, WS-ARCH-6은 Stable 모듈이 Advanced 모듈 이름을 대는 것을 금지한다.
옛 채널을 profile로 움직이게 하려면 그 edge가 필요했다.
- **relay를 포함한 `advanced-stomp` 모듈 하나.** 버렸다: relay는 따로 정할 운영 결정이고, 그것만 따로 거절할 수 있어야 한다.
- **wildcard 권한으로 선언하지 않은 destination을 허용한다.** 버렸다: wildcard가 기본이 되고 catalog는 문서가 된다.
@@ -7,30 +7,28 @@
- 현재 정본: `docs/notification/support-matrix.md`
<!-- 머리 블록 끝 -->
# NOTIF-ADR-001 — `submit()` means durable acceptance
# NOTIF-ADR-001 — `submit()`은 durable 접수를 뜻한다
## Status
## 상태
Accepted.
채택.
## Context
## 배경
The obvious API for a notification platform is `send()` returning success or failure. Every channel
this platform supports makes that return value a lie:
알림 플랫폼의 뻔한 API는 성공이나 실패를 돌려주는 `send()`다. 이 플랫폼이 지원하는 모든 채널이 그 반환값을 거짓말로 만든다:
- SES accepts a request, returns a `MessageId`, and can still decline to send.
- Twilio separates `accepted`, `sent` and `delivered` into distinct, later events.
- APNs accepts a notification and may then deliver, store or discard it.
- Web Push separates push-service acceptance from user-agent acknowledgement at the protocol level.
- SES는 요청을 받고 `MessageId`를 돌려준 뒤에도 보내기를 거절할 수 있다.
- Twilio는 `accepted`, `sent`, `delivered`를 따로따로, 나중에 오는 이벤트로 나눈다.
- APNs는 알림을 받은 뒤 전달하거나, 저장하거나, 버릴 수 있다.
- Web Push는 프로토콜 수준에서 push service의 접수와 user agent의 확인 응답을 나눈다.
## Decision
## 결정
`submit()` and `schedule()` return once the logical request and its recipient jobs are committed to
the database. The receipt carries `notificationId`, `RequestStatus` and `acceptedAt`, and has no
`delivered`, `sent` or `read` component. No provider is contacted while the transaction is open.
`submit()`과 `schedule()`은 논리 요청과 그 수신자 job이 데이터베이스에 커밋되면 돌아온다. 접수증은 `notificationId`,
`RequestStatus`, `acceptedAt`을 싣고, `delivered`·`sent`·`read` 요소가 없다. 트랜잭션이 열려 있는 동안에는 어떤 provider에도
연락하지 않는다.
## Consequences
## 결과
Callers cannot mistake acceptance for delivery, because the type does not offer that reading.
Delivery state is a separate query against the projection built from the provider event ledger. The
cost is that "did it arrive?" is a second question — which is the honest number of questions.
타입이 그렇게 읽을 길을 주지 않으므로, 호출자는 접수를 전달로 착각할 수 없다. 전달 상태는 provider 이벤트 원장에서 만든
projection에 대한 따로 둔 query다. 비용은 「도착했나?」가 두 번째 질문이라는 것이다 — 그것이 정직한 질문 수다.
@@ -7,28 +7,25 @@
- 현재 정본: `docs/notification/support-matrix.md`
<!-- 머리 블록 끝 -->
# NOTIF-ADR-002 — append-only event ledger with channel projectors
# NOTIF-ADR-002 — 채널 projector를 둔 append-only 이벤트 원장
## Status
## 상태
Accepted.
채택.
## Context
## 배경
A single linear delivery status has to be updated in place, which forces a rule for deciding whether
a new event outranks the stored one. The natural rule — compare ordinals — is wrong for real provider
traffic. Twilio does not guarantee callback ordering, so `sent` arrives after `delivered`. Email
generates complaints after deliveries. Both cases lose information under an ordinal rule.
선형 전달 상태 하나는 제자리에서 고쳐야 하고, 그러면 새 이벤트가 저장된 것보다 앞서는지 정할 규칙이 필요하다. 자연스러운 규칙 —
ordinal 비교 — 은 실제 provider traffic에서 틀린다. Twilio는 callback 순서를 보장하지 않아서 `sent`가 `delivered` 뒤에 온다. email은
전달 뒤에 불만 신고를 낸다. 두 경우 모두 ordinal 규칙 아래에서 정보를 잃는다.
## Decision
## 결정
Provider events are appended to an immutable ledger before any projection runs. Channel-specific
projectors merge events into `SubmissionOutcome`, `DeliveryOutcome`, `EvidenceLevel`,
`EngagementFacts` and `SuppressionFacts` using explicit transition tables. Projection is idempotent
and can be replayed from the ledger.
provider 이벤트는 어떤 projection이 돌기 전에 바뀌지 않는 원장에 덧붙인다. 채널별 projector가 명시한 전이 표로 이벤트를
`SubmissionOutcome`, `DeliveryOutcome`, `EvidenceLevel`, `EngagementFacts`, `SuppressionFacts`로 합친다. projection은 멱등이고 원장에서
다시 돌릴 수 있다.
## Consequences
## 결과
Duplicate, out-of-order and late events are normal inputs rather than defects. A projector bug is
recoverable, because the events it mis-projected are still stored. Projector versions can be migrated
by replay. The cost is a second write per event and a projection that can lag its ledger.
중복, 순서가 뒤바뀐, 늦은 이벤트는 결함이 아니라 보통 입력이다. 잘못 project한 이벤트가 아직 저장돼 있으므로 projector 결함은
회복할 수 있다. projector 버전은 다시 돌려서 옮길 수 있다. 비용은 이벤트마다 두 번째 쓰기와, 원장보다 늦을 수 있는 projection이다.
@@ -7,40 +7,36 @@
- 현재 정본: `docs/notification/support-matrix.md`
<!-- 머리 블록 끝 -->
# NOTIF-ADR-003 — ambiguous submission is a first-class state
# NOTIF-ADR-003 — 모호한 제출은 정식 상태다
## Status
## 상태
Accepted.
채택.
## Context
## 배경
The most common serious failure is not a rejection. It is a request whose body reached the provider
and whose response never came back. The platform has no provider request id, and the user may or may
not have received the notification.
가장 흔한 심각한 실패는 거절이 아니다. body는 provider에 닿았는데 응답이 돌아오지 않은 요청이다. 플랫폼에는 provider 요청 id가 없고,
사용자는 알림을 받았을 수도 안 받았을 수도 있다.
Treating that as a failure produces duplicates: a retry sends a second message, and a cross-channel
fallback sends the SMS next to the push that already arrived. Treating it as a success loses real
failures.
그것을 실패로 다루면 중복이 생긴다: 재시도가 두 번째 메시지를 보내고, 채널을 넘는 대체가 이미 도착한 push 옆에 SMS를 보낸다. 성공으로
다루면 실제 실패를 잃는다.
## Decision
## 결정
`AMBIGUOUS` is a stored `SubmissionOutcome` and `AttemptConfirmation`. Attempts record
`requestStarted`, `requestBodyCommitted` and `providerResponseReceived`, each with an
`EvidenceCertainty` of `PROVEN`, `INFERRED` or `UNKNOWN`, so an adapter that does not know is not
forced to answer `false`.
`AMBIGUOUS`는 저장되는 `SubmissionOutcome`이자 `AttemptConfirmation`이다. 시도는 `requestStarted`, `requestBodyCommitted`,
`providerResponseReceived`를 기록하고, 각각 `PROVEN`, `INFERRED`, `UNKNOWN` 중 하나의 `EvidenceCertainty`를 가진다. 그래서 모르는
어댑터가 `false`로 답하도록 강요받지 않는다.
While an ambiguous attempt exists on a recipient delivery:
수신자 전달에 모호한 시도가 있는 동안에는:
- automatic retry is blocked unless the provider proves per-request idempotency
- automatic cross-channel fallback is blocked unconditionally
- reconciliation runs where the provider supports a status query
- otherwise the delivery stops and waits for an operator
- provider가 요청별 멱등성을 증명하지 않으면 자동 재시도를 막는다
- 채널을 넘는 자동 대체는 조건 없이 막는다
- provider가 상태 query를 지원하면 맞춰 보기를 돌린다
- 그렇지 않으면 전달을 멈추고 운영자를 기다린다
Operator redrive of an ambiguous attempt requires explicit duplicate-risk approval.
모호한 시도를 운영자가 다시 보내려면 중복 위험을 명시해 승인해야 한다.
## Consequences
## 결과
Some notifications stop in a state that needs a human or a reconciliation pass. That is the intended
trade: an unresolved unknown is cheaper than a guaranteed duplicate, and the state is visible rather
than silently resolved in either direction.
어떤 알림은 사람이나 맞춰 보기 한 바퀴가 필요한 상태에서 멈춘다. 그것이 의도한 거래다: 풀리지 않은 모름이 보장된 중복보다 싸고,
상태는 어느 쪽으로든 소리 없이 풀리지 않고 보인다.
@@ -7,30 +7,27 @@
- 현재 정본: `docs/notification/provider-runbooks.md`
<!-- 머리 블록 끝 -->
# NOTIF-ADR-004 — FCM installation id is the primary target
# NOTIF-ADR-004 — FCM installation id가 주 대상이다
## Status
## 상태
Accepted.
채택.
## Context
## 배경
Firebase now recommends the installation id (FID) and treats registration-token multicast paths as
legacy. A contact point model built on a single `token` string would encode the older model as the
only one, and a later migration would be a runtime interpretation problem: the same string field
would mean different things for different rows.
Firebase는 이제 installation id(FID)를 권하고 registration token multicast 경로를 옛것으로 다룬다. `token` 문자열 하나 위에 세운
contact point 모델은 옛 모델을 유일한 것으로 담게 되고, 나중의 옮기기는 런타임 해석 문제가 된다: 같은 문자열 필드가 행마다 다른
뜻이 된다.
## Decision
## 결정
`MobilePushTarget` is a sealed hierarchy of `FcmInstallationId`, `LegacyFcmRegistrationToken` and
`ApnsDeviceToken`. The kinds are separate types, never a discriminator on one string field, and each
carries its own `ContactPointType` so the uniqueness scope and the encryption associated data differ.
`MobilePushTarget`은 `FcmInstallationId`, `LegacyFcmRegistrationToken`, `ApnsDeviceToken`으로 된 sealed 계층이다. 종류는 문자열 필드
하나의 구분자가 아니라 따로 둔 타입이고, 각각 자기 `ContactPointType`을 싣는다. 그래서 유일성 범위와 암호화 associated data가 다르다.
APNs tokens additionally carry their environment, because sandbox and production are separate
namespaces rather than a flag.
APNs token은 환경도 싣는다. sandbox와 production은 flag가 아니라 따로 둔 namespace이기 때문이다.
## Consequences
## 결과
Migrating a target kind is a compile-time change with an exhaustive `switch`, not a runtime guess.
The adapter maps each kind to its own wire representation, so a provider changing one path cannot
silently change the other. The cost is one more type than a string field would need.
대상 종류를 옮기는 것은 런타임 짐작이 아니라 빠짐없는 `switch`를 쓴 컴파일 시점 변경이다. 어댑터가 종류마다 자기 wire 표현으로
대응시키므로, provider가 한 경로를 바꿔도 다른 경로가 소리 없이 바뀌지 않는다. 비용은 문자열 필드보다 타입이 하나 더 필요하다는
것이다.
@@ -11,7 +11,7 @@
## 상태
Accepted (2026-08-15). NTF-018 대응.
채택(2026-08-15). NTF-018 대응.
**갱신 (2026-09-25):** R1 type은 삭제됐다. production consumer가 끝까지 0건이었고 fake로만 증명된
계약이라, 새 consumer를 막는 ArchUnit 규칙을 유지할 이유가 없어졌다. 남은 것은 adapter core의
@@ -47,9 +47,10 @@ bridge도 import도 없다.
reconciliation을 실제 PostgreSQL 레인으로 증명한다(NOTIF-ADR-001~003). R1은 fake로 증명된 R1 계약이며
스스로 그렇게 선언한다 — `application-core/CLAUDE.md`가 "R1 application contract proven with fakes.
It does not claim PostgreSQL schema/locking, provider protocol, cryptographic verifier, or runtime
wiring qualification"이라고 적어 둔 그대로다.
wiring qualification"(fake로 증명한 R1 애플리케이션 계약이다. PostgreSQL schema·locking, provider 프로토콜, 암호
검증기, 런타임 배선 검증은 주장하지 않는다)이라고 적어 둔 그대로다.
## Disposition
## 처분
R1 public type 100개의 처분은 네 가지 중 하나다.