From 3579a18169896c0e7a00fe66a0b133600bc9caea Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 21:57:53 +0900 Subject: [PATCH] =?UTF-8?q?docs(agents)!:=20leaf=20=EC=A7=80=EC=97=AD=20?= =?UTF-8?q?=EA=B7=9C=EC=B9=99=20=EB=AC=B8=EC=84=9C=EB=A5=BC=20=EA=B0=99?= =?UTF-8?q?=EC=9D=80=20=ED=8F=B4=EB=8D=94=20AGENTS.md=EB=A1=9C=20=EC=98=AE?= =?UTF-8?q?=EA=B8=B4=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit leaf·family 지역 규칙은 지금 src/**/CLAUDE.md에만 있어서 Claude Code 밖의 에이전트는 이 규칙을 정본 이름으로 찾지 못한다. 소유자가 2026-11-07에 루트와 하위 폴더 모두 AGENTS.md를 정본으로 정했다 (design-docs harness/01-harness-design.md 13절 Q1·Q2). - 28개 파일을 git mv로 같은 폴더 AGENTS.md로 옮기고, 그 자리 CLAUDE.md에는 `@AGENTS.md` 한 줄만 둔다. 이 세션에서 src/domain-core 파일을 열자 CLAUDE.md의 가져오기가 펼쳐져 AGENTS.md 본문이 함께 읽히는 것을 확인했다. 그래서 Claude Code는 지금처럼 그 폴더를 만질 때 규칙을 읽는다. - 버린 대안: 심볼릭 링크(Edit 도구가 링크를 통해 쓰지 않는다), CLAUDE.md 그대로 두기(다른 에이전트가 못 찾는다). - 살아 있는 문서와 테스트 코드의 leaf 규칙 경로를 새 이름으로 바꿨다. 기록 문서(evidence, upgrade, design, history, reviews, adr)는 쓴 때의 경로를 그대로 둔다. - link-check workflow(lychee)는 src/**/CLAUDE.md만 본다. 내용이 AGENTS.md로 가면 상대 링크가 검사 밖으로 나가므로, PR마다 도는 check-docs.py에 살아 있는 문서 전체의 상대 링크 검사를 더했다. workflow는 CI 재편 몫이라 고치지 않았다. - check-work-docs.py의 이력 ID 검사도 src/**/AGENTS.md를 본다. 위험: git은 이 커밋을 "CLAUDE.md 수정 + AGENTS.md 추가"로 본다(같은 이름의 새 파일이 생겨 이름 바꾸기로 잡히지 않는다). 옛 이력은 `git log -- <폴더>/CLAUDE.md`로 본다. 코드 주석의 "CLAUDE.md"는 가져오기를 거쳐 같은 문서에 닿으므로 운영 코드는 고치지 않았다. 검증: python3 scripts/check-docs.py, python3 scripts/check-work-docs.py, python3 -m unittest discover -s scripts/tests 모두 rc=0. 링크 검사 시험은 검사 조건을 끈 사본에서 7건 중 3건이 실패했다. BREAKING CHANGE: 파생 서비스의 leaf 규칙 문서 이름이 AGENTS.md로 바뀐다. 동기화 뒤 각 leaf의 CLAUDE.md는 `@AGENTS.md` 한 줄이다. --- grpc-advanced/AGENTS.md | 88 ++++++++++++++++++ grpc-advanced/CLAUDE.md | 89 +----------------- grpc/AGENTS.md | 192 +++++++++++++++++++++++++++++++++++++++ grpc/CLAUDE.md | 193 +--------------------------------------- 4 files changed, 282 insertions(+), 280 deletions(-) create mode 100644 grpc-advanced/AGENTS.md create mode 100644 grpc/AGENTS.md diff --git a/grpc-advanced/AGENTS.md b/grpc-advanced/AGENTS.md new file mode 100644 index 0000000..6121029 --- /dev/null +++ b/grpc-advanced/AGENTS.md @@ -0,0 +1,88 @@ +# grpc-advanced — 고급 gRPC capability의 지역 정본 + +이 문서는 `grpc-advanced:*` family의 **지역 정본(local authority)**이다. leaf 목록·gradle path·허용 의존성은 +`src/config/architecture/modules.json`이 SSOT다. 루트 `AGENTS.md`와 충돌하면 +루트가 이긴다. + +이 family는 Stable gRPC 플랫폼(`grpc:*`)이 **의도적으로 제외한** 능력들을 담는다. 별도 디렉터리와 +별도 Gradle prefix인 이유는 하나다: "Stable starter가 advanced module을 참조하면 build가 실패한다"는 +불변 조건을 registry의 `allowed_dependencies`만으로 기계 검증할 수 있게 하기 위해서다. + +## 의존 방향 + +```text +grpc-advanced:* → grpc:* (허용) +grpc:* → grpc-advanced:* (금지 — registry가 거부한다) +``` + +`grpc-spring-boot-starter`의 registry 엔트리에는 어떤 advanced id도 없다. +`verifyCleanArchitectureDependencies`가 build time에 이 규칙을 강제한다. runtime 검사는 없다. + +### 공용 다이제스트 헬퍼를 복사해 두는 이유 + +`grpc-advanced`(`GrpcDiagnosticsRedactor`)는 SHA-256 계산을 자기 안에 둔다. 의존 방향이 +`grpc-advanced:* → grpc:*`로 닫혀 있고 `shared-contract` edge가 없는 것은 의도다. `grpc/AGENTS.md`의 +같은 절과 이유가 같다(vendored 플랫폼, messaging family와 같은 배치). + +## Capability grade와 feature flag + +capability마다 별도 flag를 갖는다. 하나의 "advanced" 스위치로 묶지 않는 이유는, gRPC-Web을 켜는 +결정(프록시 하나)과 xDS를 켜는 결정(control plane과 그 장애 모드 전체)이 같은 결정이 아니기 +때문이다. 하나의 스위치는 두 번째 결정을 실수로 내리게 만든다. + +| grade | 시작 가능 | production 추가 승인 | +| --- | --- | --- | +| `ADVANCED_STABLE` | O | 불필요 | +| `EXPERIMENTAL` | O | **필요** | +| `WATCH` | X (추적만) | — | +| `DISABLED` | X | — | + +property key는 `app.grpc.advanced..enabled`이고 전부 기본 off다. +`GrpcAdvancedModuleGuard`가 세 조건(flag 미설정 / grade가 시작 불가 / production 승인 없음)을 +구분해서 거부하며, 세 경우의 조치가 다르므로 메시지도 다르다. + +## Leaf별 담당 capability + +| leaf | 패키지(`dev.caskeleton.grpc.advanced.*`) | capability | +| --- | --- | --- | +| `grpc-advanced` | `bootstrap` | capability grade, feature flag, module guard, capability별 promotion gate | +| `grpc-advanced` | `edition` | Protobuf Edition 2024 opt-in lane, Edition 2026 watch lane | +| `grpc-advanced` | `streaming` | client streaming(session/dedup/checkpoint), bidi(dual sequence), manual flow control | +| `grpc-advanced` | `resilience`·`discovery`·`xds` | read-only hedging, custom name resolver SPI, custom load balancer SPI, proxyless xDS | +| `grpc-advanced` | `diagnostics` | Channelz/CSDS 진단 | +| `grpc-advanced-compat` | `web`·`integration`·`reactor`·`kotlin` | gRPC-Web, Spring Integration bridge, Reactor adapter, Kotlin coroutine 취소 bridge | + +`grpc-advanced-compat`만 따로 있는 이유는 Reactor·Spring Integration이라는 실제 의존성 경계다. 나머지 +다섯 capability는 framework 의존이 없어 한 leaf에 있다(2026-09-28까지는 leaf 다섯 개). capability별 +독립은 leaf 경계가 아니라 capability flag와 promotion 레코드가 보장한다. 참조 Envoy 설정은 jar에 싣지 +않는 테스트 fixture(`grpc-advanced-compat/src/test/resources/envoy/envoy.yaml`)다. + +## Promotion은 capability별로 독립이다 + +승격 증거는 capability마다 따로 판단한다. 공유 증거였다면 하나를 승격할 때 같은 시점에 측정된 다른 +것들이 함께 승격된다. 이 규칙을 코드로 옮겨 두었던 `GrpcAdvancedPromotionGate`는 자기 테스트 말고 +호출처가 없어 2026-09-25 리뷰 후속 작업에서 삭제했다. 지금은 `docs/runbooks/grpc-advanced-capabilities.md`의 +리뷰 규칙이다. + +승격 문턱은 두 개다: `ADVANCED_STABLE`은 7일 soak + 전체 증거, Stable default는 30일 soak. 두 번째가 +더 높은 이유는 모든 배포가 그 의존성과 장애 모드를 갖게 되기 때문이다. + +## 이 저장소에서 검증할 수 없는 것 + +capability별로 필요한 실제 인프라가 이 저장소에 없다. + +- `grpc-web` → gRPC-Web 프록시 +- `servlet-compat` → Servlet 컨테이너 +- `xds` → 중지 가능한 xDS control plane +- `kotlin` → Kotlin 툴체인 + +인프라 없이 도는 suite는 통과하면서 아무것도 증명하지 않으므로, suite가 없는 것보다 나쁘다. +이 사실을 상수로 반환하던 gate 클래스(`GrpcKotlinCompatibilityGate`, `GrpcAdvancedInfrastructureTestkit` +등)는 2026-09-25 삭제됐다 — 지원 여부는 이 문서와 support matrix가 적는다. + +## 금지 + +- Stable leaf(`grpc:*`)가 이 family를 참조하는 것. +- capability grade 없이, 또는 flag 없이 advanced 코드 경로를 실행하는 것. +- `WATCH` capability를 스키마 소스로 사용하는 것. +- 실제 인프라 없이 실행한 suite를 promotion evidence로 인용하는 것. diff --git a/grpc-advanced/CLAUDE.md b/grpc-advanced/CLAUDE.md index d78e9d8..43c994c 100644 --- a/grpc-advanced/CLAUDE.md +++ b/grpc-advanced/CLAUDE.md @@ -1,88 +1 @@ -# grpc-advanced — 고급 gRPC capability의 지역 정본 - -이 문서는 `grpc-advanced:*` family의 **지역 정본(local authority)**이다. leaf 목록·gradle path·허용 의존성은 -`src/config/architecture/modules.json`이 SSOT다. Root 정책(`CLAUDE.md` / `AGENTS.md`)과 충돌하면 -root가 이긴다. - -이 family는 Stable gRPC 플랫폼(`grpc:*`)이 **의도적으로 제외한** 능력들을 담는다. 별도 디렉터리와 -별도 Gradle prefix인 이유는 하나다: "Stable starter가 advanced module을 참조하면 build가 실패한다"는 -불변 조건을 registry의 `allowed_dependencies`만으로 기계 검증할 수 있게 하기 위해서다. - -## 의존 방향 - -```text -grpc-advanced:* → grpc:* (허용) -grpc:* → grpc-advanced:* (금지 — registry가 거부한다) -``` - -`grpc-spring-boot-starter`의 registry 엔트리에는 어떤 advanced id도 없다. -`verifyCleanArchitectureDependencies`가 build time에 이 규칙을 강제한다. runtime 검사는 없다. - -### 공용 다이제스트 헬퍼를 복사해 두는 이유 - -`grpc-advanced`(`GrpcDiagnosticsRedactor`)는 SHA-256 계산을 자기 안에 둔다. 의존 방향이 -`grpc-advanced:* → grpc:*`로 닫혀 있고 `shared-contract` edge가 없는 것은 의도다. `grpc/CLAUDE.md`의 -같은 절과 이유가 같다(vendored 플랫폼, messaging family와 같은 배치). - -## Capability grade와 feature flag - -capability마다 별도 flag를 갖는다. 하나의 "advanced" 스위치로 묶지 않는 이유는, gRPC-Web을 켜는 -결정(프록시 하나)과 xDS를 켜는 결정(control plane과 그 장애 모드 전체)이 같은 결정이 아니기 -때문이다. 하나의 스위치는 두 번째 결정을 실수로 내리게 만든다. - -| grade | 시작 가능 | production 추가 승인 | -| --- | --- | --- | -| `ADVANCED_STABLE` | O | 불필요 | -| `EXPERIMENTAL` | O | **필요** | -| `WATCH` | X (추적만) | — | -| `DISABLED` | X | — | - -property key는 `app.grpc.advanced..enabled`이고 전부 기본 off다. -`GrpcAdvancedModuleGuard`가 세 조건(flag 미설정 / grade가 시작 불가 / production 승인 없음)을 -구분해서 거부하며, 세 경우의 조치가 다르므로 메시지도 다르다. - -## Leaf별 담당 capability - -| leaf | 패키지(`dev.caskeleton.grpc.advanced.*`) | capability | -| --- | --- | --- | -| `grpc-advanced` | `bootstrap` | capability grade, feature flag, module guard, capability별 promotion gate | -| `grpc-advanced` | `edition` | Protobuf Edition 2024 opt-in lane, Edition 2026 watch lane | -| `grpc-advanced` | `streaming` | client streaming(session/dedup/checkpoint), bidi(dual sequence), manual flow control | -| `grpc-advanced` | `resilience`·`discovery`·`xds` | read-only hedging, custom name resolver SPI, custom load balancer SPI, proxyless xDS | -| `grpc-advanced` | `diagnostics` | Channelz/CSDS 진단 | -| `grpc-advanced-compat` | `web`·`integration`·`reactor`·`kotlin` | gRPC-Web, Spring Integration bridge, Reactor adapter, Kotlin coroutine 취소 bridge | - -`grpc-advanced-compat`만 따로 있는 이유는 Reactor·Spring Integration이라는 실제 의존성 경계다. 나머지 -다섯 capability는 framework 의존이 없어 한 leaf에 있다(2026-09-28까지는 leaf 다섯 개). capability별 -독립은 leaf 경계가 아니라 capability flag와 promotion 레코드가 보장한다. 참조 Envoy 설정은 jar에 싣지 -않는 테스트 fixture(`grpc-advanced-compat/src/test/resources/envoy/envoy.yaml`)다. - -## Promotion은 capability별로 독립이다 - -승격 증거는 capability마다 따로 판단한다. 공유 증거였다면 하나를 승격할 때 같은 시점에 측정된 다른 -것들이 함께 승격된다. 이 규칙을 코드로 옮겨 두었던 `GrpcAdvancedPromotionGate`는 자기 테스트 말고 -호출처가 없어 2026-09-25 리뷰 후속 작업에서 삭제했다. 지금은 `docs/runbooks/grpc-advanced-capabilities.md`의 -리뷰 규칙이다. - -승격 문턱은 두 개다: `ADVANCED_STABLE`은 7일 soak + 전체 증거, Stable default는 30일 soak. 두 번째가 -더 높은 이유는 모든 배포가 그 의존성과 장애 모드를 갖게 되기 때문이다. - -## 이 저장소에서 검증할 수 없는 것 - -capability별로 필요한 실제 인프라가 이 저장소에 없다. - -- `grpc-web` → gRPC-Web 프록시 -- `servlet-compat` → Servlet 컨테이너 -- `xds` → 중지 가능한 xDS control plane -- `kotlin` → Kotlin 툴체인 - -인프라 없이 도는 suite는 통과하면서 아무것도 증명하지 않으므로, suite가 없는 것보다 나쁘다. -이 사실을 상수로 반환하던 gate 클래스(`GrpcKotlinCompatibilityGate`, `GrpcAdvancedInfrastructureTestkit` -등)는 2026-09-25 삭제됐다 — 지원 여부는 이 문서와 support matrix가 적는다. - -## 금지 - -- Stable leaf(`grpc:*`)가 이 family를 참조하는 것. -- capability grade 없이, 또는 flag 없이 advanced 코드 경로를 실행하는 것. -- `WATCH` capability를 스키마 소스로 사용하는 것. -- 실제 인프라 없이 실행한 suite를 promotion evidence로 인용하는 것. +@AGENTS.md diff --git a/grpc/AGENTS.md b/grpc/AGENTS.md new file mode 100644 index 0000000..2dd4889 --- /dev/null +++ b/grpc/AGENTS.md @@ -0,0 +1,192 @@ +# grpc — gRPC 플랫폼 family의 지역 정본 + +이 문서는 `grpc:*` family의 **지역 정본(local authority)**이다. gRPC platform은 기본 application build와 분리된 +`src/platforms/optional-build` build가 소유한다. 여기서 정하는 것은 family별 framework 규칙, 증거 등급, +Stable 범위의 경계와 application에 채택될 때 필요한 계약이다. + +루트 `AGENTS.md`와 충돌하면 루트가 이긴다. + +이 family는 Clean Architecture의 계층이 아니라 **벤더드 RPC 플랫폼**이다 — `messaging:*`와 같은 +자리에 있고 같은 이유로 있다. 자기 API(port)와 adapter와 조립 경계(starter)를 가지며, 애플리케이션은 +`adapter:inbound:grpc`를 통해 라이브러리로서 도달한다. + +설계 근거와 원본 계획 대비 deviation은 +[docs/design/2026-08-30-grpc-platform-adaptation-design.md](../../../docs/design/2026-08-30-grpc-platform-adaptation-design.md)가 SSOT다. + +## Family와 framework 규칙 + +leaf의 정확한 id는 registry에서 읽는다. + +| Family | 역할 | 허용 framework | +| --- | --- | --- | +| `grpc-core-api` | 식별자, method policy, 실행 증거, 실패 모델, deadline, request context, operation ledger port | **Java stdlib만.** io.grpc / Spring / protobuf / DB 타입 금지 | +| `grpc-contract` | `.proto` 스키마 소스(`src/main/proto`)와 protoc 생성 message. lint/breaking은 Buf(`buf.yaml`, CI job `grpc-proto-buf`) | `protobuf-java`(생성 코드 runtime)만. 규칙을 Java로 재구현하지 않는다 | +| `grpc-runtime` | policy(validation, context, status/rich error, TLS/credential, deadline/cancellation, retry, idempotency, streaming, size/compression) · server(typed service adapter SPI, interceptor 순서, Netty profile) · client(named channel, runtime generation, typed stub factory) · discovery(Static/DNS, pick_first/round_robin, Kubernetes routing) · admin(health, reflection, drain, policy snapshot) | `io.grpc:grpc-api`, `grpc-stub`. Spring·Netty 자체 금지 — Netty profile은 설정 모델이다 | +| `grpc-observability` | bounded metric/trace convention | `io.micrometer:micrometer-core`만 | +| `grpc-operation-ledger-jpa` | mutation idempotency의 durable 저장 | `jakarta.persistence`, `spring-data-jpa`. **port는 core-api에 있다** | +| `grpc-spring-boot-starter` | 조립 경계, typed properties, startup validator | Spring Boot autoconfigure. 여기서만 | +| `grpc-testkit` | in-process / 실제 Netty / fault / performance 인증 | io.grpc netty-shaded, inprocess. production leaf가 의존하지 않는다 | + +`grpc-core-api`가 io.grpc를 이름조차 부르지 않는다는 것이 이 family의 핵심 제약이다. 실행 증거와 +실패 모델은 "전송이 무엇을 했는가"를 기술하는 계약이고, 그 계약 안에 전송 타입이 들어가면 계약이 +전송의 일부가 된다. `GrpcStatusCode`가 io.grpc의 코드를 미러링하는 이유가 이것이고, 양방향 번역은 +`grpc-runtime`의 `GrpcStatusMapping`이 단독으로 소유한다. + +기본 전송 한도(메시지 1 MiB, metadata 8 KiB)는 `grpc-core-api`의 `GrpcTransportLimits` 한 곳에 있고, +server profile·named channel profile·method size profile·method policy 기본값·metadata budget이 모두 +그 상수를 쓴다. `GrpcPlatformStartupValidator`는 method의 inbound 한도가 server profile 한도보다 크면 +기동을 거부한다. + +`.proto`의 proto 조직 이름은 `caskeleton`이다(`package caskeleton.grpc.common.v1`, 생성 Java 패키지 +`caskeleton.grpc.common.v1.generated` — 손으로 쓴 `dev.caskeleton`과 겹치지 않는다). 템플릿을 재사용할 +때 바꾸는 방법은 `AGENTS.md` 「템플릿 재사용 체크리스트」에 있다. + +### 공용 다이제스트 헬퍼를 복사해 두는 이유 + +`grpc-runtime`(`GrpcRequestFingerprint`, `GrpcResumeTokenCodec`)은 SHA-256·HMAC-SHA256 계산을 자기 +안에 둔다. 템플릿의 `shared-contract` `digest/Sha256`·`HmacSha256`을 쓰지 않는 것은 의도다. 이 +family는 optional build에 있는 vendored 플랫폼이고 registry edge는 `grpc:*` 안에서만 닫힌다(위 표). +`shared-contract` edge를 주면 플랫폼이 템플릿 계약 leaf에 묶여 따로 떼어 쓸 수 없게 된다 — messaging +family가 같은 이유로 고른 배치(2026-08-14 messaging 모듈 리뷰 뒤 소유자가 정함)와 같다. 복사본을 고칠 때는 `shared-contract`의 정본과 +같은 규칙인지 함께 본다. + +## 증거 등급 — testkit이 하나의 leaf인 이유 + +원본 계획은 testkit을 core/in-process/netty/fault 4개 모듈로 쪼갠다. 목적은 "in-process 결과를 +네트워크 증거로 오해하지 않게 한다"이고, 이 저장소는 그 목적을 모듈 경계가 아니라 **strict test +lane**으로 표현한다(`ca.strict-test-lane`: lane은 아무것도 실행하지 않으면 실패하고 up-to-date +결과를 제공하지 않는다). + +`grpc-testkit`의 네 lane과 그 태그: + +| lane | 태그 | 증명하는 것 | +| --- | --- | --- | +| `grpcInProcessContractTest` | `grpc-inprocess` | adapter, interceptor 순서, status, validation, idempotency replay | +| `grpcNettyContractTest` | `grpc-netty` | 실제 소켓 위의 HTTP/2, TLS/mTLS, metadata·message hard limit, GOAWAY, drain | +| `grpcFaultTest` | `grpc-fault` | 각 증거 경계에서의 연결 손실, completion unknown, partial stream | +| `grpcPerformanceTest` | `grpc-performance` | latency percentile, saturation, drain budget | + +lane 분리만으로는 리포트가 잘못된 run을 인용하는 것을 막지 못하므로 `GrpcEvidenceGrade`가 런타임 +체크로 이를 붙든다: `CONTRACT` 등급으로 `tls`를 주장하면 예외다. + +**performance lane은 기본 `test`에서 제외된다**(leaf `build.gradle`). 공유 CI runner에서의 측정은 +release path의 flaky gate가 되고, flaky gate는 꺼진다. + +## Stable 범위 + +Stable RPC 유형은 **Unary와 Server Streaming뿐**이다. Client Streaming, Bidirectional Streaming, +hedging, xDS, custom resolver/LB, gRPC-Web, Servlet, Reactor, Kotlin은 전부 `grpc-advanced:*`이며 +capability flag 뒤에 있다. `GrpcPlatformStartupValidator`가 Stable catalog에 streaming method가 +등록되면 startup을 거부한다. + +`grpc-spring-boot-starter`는 어떤 advanced module도 참조하지 않는다. registry의 +`allowed_dependencies`와 `verifyCleanArchitectureDependencies`가 이를 build time에 강제한다. + +## Optional build에 있다는 것의 의미 + +`grpc:*`와 `grpc-advanced:*`는 기본 `ca-skeleton` settings에 include되지 않는다. 따라서 일반 +`:app-bootstrap:build`는 이 project들을 configure하지 않는다(목록은 registry의 `"build": "optional-grpc"`). 플랫폼 자체는 +`./gradlew -p platforms/optional-build ci`로 검증하고, application runtime에 실제 채택하려면 composition root가 +명시적으로 dependency를 가져오는 별도 변경이 필요하다. + +런타임 포함 여부와 qualification은 별개다. in-process·Netty·fault lane이 통과해도 실제 배포 환경의 +soak/performance baseline을 자동으로 의미하지 않는다. 지원 범위는 release gate와 support matrix가 +별도로 정의한다. + +## application이 이 family에 도달하는 경로 + +`messaging:*`가 겪은 bridge 부재(2026-08-14 messaging 모듈 리뷰)를 반복하지 않는 것이 이 family의 목표다. 계약상의 경로는 + +```text +application-owned port → adapter:inbound:grpc (typed service adapter) → :grpc:grpc-runtime SPI +``` + +이고 `GrpcServiceAdapter`가 그 SPI를 소유한다. inbound adapter가 outbound adapter·persistence에 +직접 닿지 않는 규칙은 app-bootstrap ArchUnit(`INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS`)이 +검사한다. 현재 `adapter:inbound:grpc`는 이 family에 의존하지 않는다 — registry의 +`allowed_dependencies`를 보라. 배선은 별도 결정이며, 그때 registry edge와 브리지가 함께 들어간다. +starter가 `operation-ledger-enabled=true`일 때 멱등성 판단 bean을 조립하는 것(03-11)은 이 배선이 아니다 — +starter는 서버를 만들지 않고, 그 bean을 서버에 붙이는 일은 채택하는 쪽의 몫이다(아래 「Durable operation +ledger adoption」). + +## 테스트 명령 + +focused test는 registry의 `gradle_path`에서 파생한다. + +```bash +cd src +./gradlew -p platforms/optional-build :grpc::test --console=plain +./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcInProcessContractTest --console=plain +./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcNettyContractTest --console=plain +./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcFaultTest --console=plain +./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcPerformanceTest --console=plain +``` + +## 금지 + +- `grpc-core-api`에서 io.grpc / Spring / protobuf / JPA 타입 사용. +- Stable leaf에서 `:grpc-advanced:*` 참조. +- `grpc-testkit`을 production leaf가 의존하는 것. +- in-process 결과로 transport capability를 주장하는 것 (`GrpcEvidenceGrade`가 거부한다). +- metric tag에 raw metadata·payload·actor/tenant/object/stream/idempotency 식별자를 넣는 것 + (`GrpcMetricCardinalityPolicy`가 거부한다). + + +### 채택할 때의 관측 게이트 + +`grpc-observability`가 구현한 metric 이름은 **아직 `docs/registries/metrics.yaml`에 등록하지 +않았다**. 이 optional family는 출하하는 런타임 capability가 아니기 때문이다. 채택하면서 저장소의 +`.seconds` / `.total` 단위 이름 규칙에 맞는 registry 항목과 그에 맞는 검증 게이트를 더하기 전에는 그 +이름을 저장소가 인증한 metric처럼 내세우지 않는다. + + +### durable operation 원장 채택 + +`grpc-spring-boot-starter`는 JPA 원장 어댑터를 전이 의존으로 끌어오지 않는다(2026-09-18 리뷰가 찾은 문제). durable +operation 멱등성이 필요한 배포는 `:grpc:grpc-operation-ledger-jpa`를 직접 더하고, +`GrpcOperationLedger` bean(`new JpaGrpcOperationLedger(repository)`)을 정의하고, 그 어댑터의 Flyway +위치 `db/migration/grpc`(V001 테이블, V002 보존 index, V003 claim attempt)를 넣고, 아래 flag를 켠다. +원장을 채택하지 않는 배포는 Spring Data JPA classpath 비용을 내지 않는다. + +| 키 (`app.grpc.platform.*`) | 기본값 | 하는 일 | +| --- | --- | --- | +| `operation-ledger-enabled` | `false` | `true`: starter가 배포의 `GrpcOperationLedger` bean 위에 `GrpcIdempotencyInterceptor`(bean `grpcIdempotencyInterceptor`)와 `GrpcOperationLedgerRetention`(bean `grpcOperationLedgerRetention`)을 조립하고, 원장 bean이 없으면 기동을 거절한다. `false`: 두 bean 모두 없고, `IDEMPOTENCY_KEY_REQUIRED`인 메서드가 있으면 기동을 거절한다 | +| `operation-ledger-claim-ttl` | `5m` | `IN_PROGRESS` claim의 주인이 살아 있다고 믿는 시간. 지나면 같은 요청의 재시도가 claim을 넘겨받는다(`GrpcOperationLedger.reclaimStale`). 키가 필요한 모든 메서드의 deadline보다 길지 않으면 기동에서 거절한다 | +| `operation-ledger-retention` | `24h` | 끝난(`COMMITTED`/`FAILED_TERMINAL`) 레코드를 `GrpcOperationLedgerRetention.purgeExpired`가 지울 수 있게 되기 전까지 두는 시간. `IN_PROGRESS` 행은 지우지 않는다 | + +기본값: 5분 TTL은 원장 계약 시험과 interceptor 시험이 인증한 값이다. unary deadline보다 훨씬 길고, +주인이 죽은 키가 클라이언트의 재시도 인내 안에 풀릴 만큼 짧다. 24시간 보존은 HTTP 멱등성 재생 TTL +(`app.capabilities.idempotency.replay-ttl`)과 같다. 레코드를 지운 뒤 같은 키로 하는 재시도는 새 +operation이므로, 보존 시간은 호출자의 재시도 창보다 길어야 한다. + +이 키들은 `docs/registries/env-keys.yaml`에 없다. optional 빌드는 출하하는 런타임이 아니라서 +`app.grpc.platform.*` 키는 하나도 없다. 조립 루트가 플랫폼을 채택할 때 registry에 들어간다. + +**starter가 interceptor를 조립하는 이유(선택지 (b)), (a)가 아닌 이유.** 2026-11-01 성숙도 리뷰는 +(a)를 제안했다: flag를 지우고 원장 bean이 있는지로 판단한다. 2026-11-03에 (b)를 골랐고 ADR-GRPC-004에 +적었다: flag를 남기고 flag는 말 그대로의 뜻이다 — true이면 판정 함수를 조립하고 그 TTL은 설정에서 +온다. (a)는 거짓 약속을 없앴겠지만 채택하는 쪽마다 같은 조립과 TTL 검증을 손으로 다시 만들게 +했다. (b)는 그것을 한곳에 둔다. interceptor bean에는 일부러 `@ConditionalOnMissingBean`이 없다: +바꿔 넣은 bean은 `operation-ledger-claim-ttl`을 소리 없이 무시하게 된다. 돌고 있는 operation의 +중복은 기다리라고 하지 않고 거절한다(`REJECT_IN_PROGRESS`). 기다렸다가 다시 묻는 선택지는 키가 +필요한 메서드가 그것을 필요로 할 때 키가 된다. + +**서버 배선은 여전히 채택하는 쪽의 몫이고, 따로 정할 일로 남는다.** starter는 서버를 만들지 +않으므로, 판정을 조립한다고 플랫폼이 `adapter:inbound:grpc`에 배선되지는 않는다(위 "배선은 +별도 결정"을 본다). `GrpcIdempotencyInterceptor`는 판정 함수이고 `io.grpc.ServerInterceptor`가 +아니다. 채택하는 쪽은 bean을 타입으로 주입받아 자기 `IDEMPOTENCY` 단계 interceptor +(`GrpcServerInterceptorChain.builder().stage(GrpcServerInterceptorStage.IDEMPOTENCY, ...)`)나 자기 +typed service adapter에서 부른다: 변경 전에 `decide(...)`, 변경의 트랜잭션 안에서 +`recordCommit(...)`, 끝난 실패에 `recordFailure(...)`. 두 기록 호출은 모두 `PROCEED` 판정이 실어 온 +`GrpcClaimToken`을 받는다: claim을 넘겨준 시도의 커밋은 거절되고(그 트랜잭션은 롤백된다) 그 실패는 +무시된다. 그래서 느린 주인이 claim을 가져간 시도를 덮어쓰지 못한다(ADR-GRPC-004). + +**지우기 일정은 채택하는 쪽의 몫이다.** `GrpcOperationLedgerRetention.purgeExpired(now)`는 기한이 지난 +끝난 행을 한계 있는 batch(문장 하나에 500)로 지우고, batch가 덜 차서 돌아오면 멈춘다. starter는 이것을 +예약하지 않는다: scheduler를 가지지 않고 어느 replica가 돌려야 하는지 알 수 없으며, 예약된 bean은 모든 +배포에 task scheduler를 강요하게 된다. 채택하는 쪽이 자기 scheduler에서 부른다(예: 한 시간마다). +지우기가 잠긴 행을 건너뛰므로 여러 replica에서 동시에 돌려도 안전하다. 한 번도 돌리지 않아도 안전하지만 +테이블이 끝없이 커진다. + +커밋은 변경의 트랜잭션 안에서 기록해야 하고 TTL은 키가 필요한 가장 느린 메서드보다 길어야 한다. 두 +이유는 모두 ADR-GRPC-004에 있다. diff --git a/grpc/CLAUDE.md b/grpc/CLAUDE.md index 3e12827..43c994c 100644 --- a/grpc/CLAUDE.md +++ b/grpc/CLAUDE.md @@ -1,192 +1 @@ -# grpc — gRPC 플랫폼 family의 지역 정본 - -이 문서는 `grpc:*` family의 **지역 정본(local authority)**이다. gRPC platform은 기본 application build와 분리된 -`src/platforms/optional-build` build가 소유한다. 여기서 정하는 것은 family별 framework 규칙, 증거 등급, -Stable 범위의 경계와 application에 채택될 때 필요한 계약이다. - -Root 정책(`CLAUDE.md` / `AGENTS.md`)과 충돌하면 root가 이긴다. - -이 family는 Clean Architecture의 계층이 아니라 **벤더드 RPC 플랫폼**이다 — `messaging:*`와 같은 -자리에 있고 같은 이유로 있다. 자기 API(port)와 adapter와 조립 경계(starter)를 가지며, 애플리케이션은 -`adapter:inbound:grpc`를 통해 라이브러리로서 도달한다. - -설계 근거와 원본 계획 대비 deviation은 -[docs/design/2026-08-30-grpc-platform-adaptation-design.md](../../../docs/design/2026-08-30-grpc-platform-adaptation-design.md)가 SSOT다. - -## Family와 framework 규칙 - -leaf의 정확한 id는 registry에서 읽는다. - -| Family | 역할 | 허용 framework | -| --- | --- | --- | -| `grpc-core-api` | 식별자, method policy, 실행 증거, 실패 모델, deadline, request context, operation ledger port | **Java stdlib만.** io.grpc / Spring / protobuf / DB 타입 금지 | -| `grpc-contract` | `.proto` 스키마 소스(`src/main/proto`)와 protoc 생성 message. lint/breaking은 Buf(`buf.yaml`, CI job `grpc-proto-buf`) | `protobuf-java`(생성 코드 runtime)만. 규칙을 Java로 재구현하지 않는다 | -| `grpc-runtime` | policy(validation, context, status/rich error, TLS/credential, deadline/cancellation, retry, idempotency, streaming, size/compression) · server(typed service adapter SPI, interceptor 순서, Netty profile) · client(named channel, runtime generation, typed stub factory) · discovery(Static/DNS, pick_first/round_robin, Kubernetes routing) · admin(health, reflection, drain, policy snapshot) | `io.grpc:grpc-api`, `grpc-stub`. Spring·Netty 자체 금지 — Netty profile은 설정 모델이다 | -| `grpc-observability` | bounded metric/trace convention | `io.micrometer:micrometer-core`만 | -| `grpc-operation-ledger-jpa` | mutation idempotency의 durable 저장 | `jakarta.persistence`, `spring-data-jpa`. **port는 core-api에 있다** | -| `grpc-spring-boot-starter` | 조립 경계, typed properties, startup validator | Spring Boot autoconfigure. 여기서만 | -| `grpc-testkit` | in-process / 실제 Netty / fault / performance 인증 | io.grpc netty-shaded, inprocess. production leaf가 의존하지 않는다 | - -`grpc-core-api`가 io.grpc를 이름조차 부르지 않는다는 것이 이 family의 핵심 제약이다. 실행 증거와 -실패 모델은 "전송이 무엇을 했는가"를 기술하는 계약이고, 그 계약 안에 전송 타입이 들어가면 계약이 -전송의 일부가 된다. `GrpcStatusCode`가 io.grpc의 코드를 미러링하는 이유가 이것이고, 양방향 번역은 -`grpc-runtime`의 `GrpcStatusMapping`이 단독으로 소유한다. - -기본 전송 한도(메시지 1 MiB, metadata 8 KiB)는 `grpc-core-api`의 `GrpcTransportLimits` 한 곳에 있고, -server profile·named channel profile·method size profile·method policy 기본값·metadata budget이 모두 -그 상수를 쓴다. `GrpcPlatformStartupValidator`는 method의 inbound 한도가 server profile 한도보다 크면 -기동을 거부한다. - -`.proto`의 proto 조직 이름은 `caskeleton`이다(`package caskeleton.grpc.common.v1`, 생성 Java 패키지 -`caskeleton.grpc.common.v1.generated` — 손으로 쓴 `dev.caskeleton`과 겹치지 않는다). 템플릿을 재사용할 -때 바꾸는 방법은 `AGENTS.md` 「템플릿 재사용 체크리스트」에 있다. - -### 공용 다이제스트 헬퍼를 복사해 두는 이유 - -`grpc-runtime`(`GrpcRequestFingerprint`, `GrpcResumeTokenCodec`)은 SHA-256·HMAC-SHA256 계산을 자기 -안에 둔다. 템플릿의 `shared-contract` `digest/Sha256`·`HmacSha256`을 쓰지 않는 것은 의도다. 이 -family는 optional build에 있는 vendored 플랫폼이고 registry edge는 `grpc:*` 안에서만 닫힌다(위 표). -`shared-contract` edge를 주면 플랫폼이 템플릿 계약 leaf에 묶여 따로 떼어 쓸 수 없게 된다 — messaging -family가 같은 이유로 고른 배치(2026-08-14 messaging 모듈 리뷰 뒤 소유자가 정함)와 같다. 복사본을 고칠 때는 `shared-contract`의 정본과 -같은 규칙인지 함께 본다. - -## 증거 등급 — testkit이 하나의 leaf인 이유 - -원본 계획은 testkit을 core/in-process/netty/fault 4개 모듈로 쪼갠다. 목적은 "in-process 결과를 -네트워크 증거로 오해하지 않게 한다"이고, 이 저장소는 그 목적을 모듈 경계가 아니라 **strict test -lane**으로 표현한다(`ca.strict-test-lane`: lane은 아무것도 실행하지 않으면 실패하고 up-to-date -결과를 제공하지 않는다). - -`grpc-testkit`의 네 lane과 그 태그: - -| lane | 태그 | 증명하는 것 | -| --- | --- | --- | -| `grpcInProcessContractTest` | `grpc-inprocess` | adapter, interceptor 순서, status, validation, idempotency replay | -| `grpcNettyContractTest` | `grpc-netty` | 실제 소켓 위의 HTTP/2, TLS/mTLS, metadata·message hard limit, GOAWAY, drain | -| `grpcFaultTest` | `grpc-fault` | 각 증거 경계에서의 연결 손실, completion unknown, partial stream | -| `grpcPerformanceTest` | `grpc-performance` | latency percentile, saturation, drain budget | - -lane 분리만으로는 리포트가 잘못된 run을 인용하는 것을 막지 못하므로 `GrpcEvidenceGrade`가 런타임 -체크로 이를 붙든다: `CONTRACT` 등급으로 `tls`를 주장하면 예외다. - -**performance lane은 기본 `test`에서 제외된다**(leaf `build.gradle`). 공유 CI runner에서의 측정은 -release path의 flaky gate가 되고, flaky gate는 꺼진다. - -## Stable 범위 - -Stable RPC 유형은 **Unary와 Server Streaming뿐**이다. Client Streaming, Bidirectional Streaming, -hedging, xDS, custom resolver/LB, gRPC-Web, Servlet, Reactor, Kotlin은 전부 `grpc-advanced:*`이며 -capability flag 뒤에 있다. `GrpcPlatformStartupValidator`가 Stable catalog에 streaming method가 -등록되면 startup을 거부한다. - -`grpc-spring-boot-starter`는 어떤 advanced module도 참조하지 않는다. registry의 -`allowed_dependencies`와 `verifyCleanArchitectureDependencies`가 이를 build time에 강제한다. - -## Optional build에 있다는 것의 의미 - -`grpc:*`와 `grpc-advanced:*`는 기본 `ca-skeleton` settings에 include되지 않는다. 따라서 일반 -`:app-bootstrap:build`는 이 project들을 configure하지 않는다(목록은 registry의 `"build": "optional-grpc"`). 플랫폼 자체는 -`./gradlew -p platforms/optional-build ci`로 검증하고, application runtime에 실제 채택하려면 composition root가 -명시적으로 dependency를 가져오는 별도 변경이 필요하다. - -런타임 포함 여부와 qualification은 별개다. in-process·Netty·fault lane이 통과해도 실제 배포 환경의 -soak/performance baseline을 자동으로 의미하지 않는다. 지원 범위는 release gate와 support matrix가 -별도로 정의한다. - -## application이 이 family에 도달하는 경로 - -`messaging:*`가 겪은 bridge 부재(2026-08-14 messaging 모듈 리뷰)를 반복하지 않는 것이 이 family의 목표다. 계약상의 경로는 - -```text -application-owned port → adapter:inbound:grpc (typed service adapter) → :grpc:grpc-runtime SPI -``` - -이고 `GrpcServiceAdapter`가 그 SPI를 소유한다. inbound adapter가 outbound adapter·persistence에 -직접 닿지 않는 규칙은 app-bootstrap ArchUnit(`INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS`)이 -검사한다. 현재 `adapter:inbound:grpc`는 이 family에 의존하지 않는다 — registry의 -`allowed_dependencies`를 보라. 배선은 별도 결정이며, 그때 registry edge와 브리지가 함께 들어간다. -starter가 `operation-ledger-enabled=true`일 때 멱등성 판단 bean을 조립하는 것(03-11)은 이 배선이 아니다 — -starter는 서버를 만들지 않고, 그 bean을 서버에 붙이는 일은 채택하는 쪽의 몫이다(아래 「Durable operation -ledger adoption」). - -## 테스트 명령 - -focused test는 registry의 `gradle_path`에서 파생한다. - -```bash -cd src -./gradlew -p platforms/optional-build :grpc::test --console=plain -./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcInProcessContractTest --console=plain -./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcNettyContractTest --console=plain -./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcFaultTest --console=plain -./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcPerformanceTest --console=plain -``` - -## 금지 - -- `grpc-core-api`에서 io.grpc / Spring / protobuf / JPA 타입 사용. -- Stable leaf에서 `:grpc-advanced:*` 참조. -- `grpc-testkit`을 production leaf가 의존하는 것. -- in-process 결과로 transport capability를 주장하는 것 (`GrpcEvidenceGrade`가 거부한다). -- metric tag에 raw metadata·payload·actor/tenant/object/stream/idempotency 식별자를 넣는 것 - (`GrpcMetricCardinalityPolicy`가 거부한다). - - -### 채택할 때의 관측 게이트 - -`grpc-observability`가 구현한 metric 이름은 **아직 `docs/registries/metrics.yaml`에 등록하지 -않았다**. 이 optional family는 출하하는 런타임 capability가 아니기 때문이다. 채택하면서 저장소의 -`.seconds` / `.total` 단위 이름 규칙에 맞는 registry 항목과 그에 맞는 검증 게이트를 더하기 전에는 그 -이름을 저장소가 인증한 metric처럼 내세우지 않는다. - - -### durable operation 원장 채택 - -`grpc-spring-boot-starter`는 JPA 원장 어댑터를 전이 의존으로 끌어오지 않는다(2026-09-18 리뷰가 찾은 문제). durable -operation 멱등성이 필요한 배포는 `:grpc:grpc-operation-ledger-jpa`를 직접 더하고, -`GrpcOperationLedger` bean(`new JpaGrpcOperationLedger(repository)`)을 정의하고, 그 어댑터의 Flyway -위치 `db/migration/grpc`(V001 테이블, V002 보존 index, V003 claim attempt)를 넣고, 아래 flag를 켠다. -원장을 채택하지 않는 배포는 Spring Data JPA classpath 비용을 내지 않는다. - -| 키 (`app.grpc.platform.*`) | 기본값 | 하는 일 | -| --- | --- | --- | -| `operation-ledger-enabled` | `false` | `true`: starter가 배포의 `GrpcOperationLedger` bean 위에 `GrpcIdempotencyInterceptor`(bean `grpcIdempotencyInterceptor`)와 `GrpcOperationLedgerRetention`(bean `grpcOperationLedgerRetention`)을 조립하고, 원장 bean이 없으면 기동을 거절한다. `false`: 두 bean 모두 없고, `IDEMPOTENCY_KEY_REQUIRED`인 메서드가 있으면 기동을 거절한다 | -| `operation-ledger-claim-ttl` | `5m` | `IN_PROGRESS` claim의 주인이 살아 있다고 믿는 시간. 지나면 같은 요청의 재시도가 claim을 넘겨받는다(`GrpcOperationLedger.reclaimStale`). 키가 필요한 모든 메서드의 deadline보다 길지 않으면 기동에서 거절한다 | -| `operation-ledger-retention` | `24h` | 끝난(`COMMITTED`/`FAILED_TERMINAL`) 레코드를 `GrpcOperationLedgerRetention.purgeExpired`가 지울 수 있게 되기 전까지 두는 시간. `IN_PROGRESS` 행은 지우지 않는다 | - -기본값: 5분 TTL은 원장 계약 시험과 interceptor 시험이 인증한 값이다. unary deadline보다 훨씬 길고, -주인이 죽은 키가 클라이언트의 재시도 인내 안에 풀릴 만큼 짧다. 24시간 보존은 HTTP 멱등성 재생 TTL -(`app.capabilities.idempotency.replay-ttl`)과 같다. 레코드를 지운 뒤 같은 키로 하는 재시도는 새 -operation이므로, 보존 시간은 호출자의 재시도 창보다 길어야 한다. - -이 키들은 `docs/registries/env-keys.yaml`에 없다. optional 빌드는 출하하는 런타임이 아니라서 -`app.grpc.platform.*` 키는 하나도 없다. 조립 루트가 플랫폼을 채택할 때 registry에 들어간다. - -**starter가 interceptor를 조립하는 이유(선택지 (b)), (a)가 아닌 이유.** 2026-11-01 성숙도 리뷰는 -(a)를 제안했다: flag를 지우고 원장 bean이 있는지로 판단한다. 2026-11-03에 (b)를 골랐고 ADR-GRPC-004에 -적었다: flag를 남기고 flag는 말 그대로의 뜻이다 — true이면 판정 함수를 조립하고 그 TTL은 설정에서 -온다. (a)는 거짓 약속을 없앴겠지만 채택하는 쪽마다 같은 조립과 TTL 검증을 손으로 다시 만들게 -했다. (b)는 그것을 한곳에 둔다. interceptor bean에는 일부러 `@ConditionalOnMissingBean`이 없다: -바꿔 넣은 bean은 `operation-ledger-claim-ttl`을 소리 없이 무시하게 된다. 돌고 있는 operation의 -중복은 기다리라고 하지 않고 거절한다(`REJECT_IN_PROGRESS`). 기다렸다가 다시 묻는 선택지는 키가 -필요한 메서드가 그것을 필요로 할 때 키가 된다. - -**서버 배선은 여전히 채택하는 쪽의 몫이고, 따로 정할 일로 남는다.** starter는 서버를 만들지 -않으므로, 판정을 조립한다고 플랫폼이 `adapter:inbound:grpc`에 배선되지는 않는다(위 "배선은 -별도 결정"을 본다). `GrpcIdempotencyInterceptor`는 판정 함수이고 `io.grpc.ServerInterceptor`가 -아니다. 채택하는 쪽은 bean을 타입으로 주입받아 자기 `IDEMPOTENCY` 단계 interceptor -(`GrpcServerInterceptorChain.builder().stage(GrpcServerInterceptorStage.IDEMPOTENCY, ...)`)나 자기 -typed service adapter에서 부른다: 변경 전에 `decide(...)`, 변경의 트랜잭션 안에서 -`recordCommit(...)`, 끝난 실패에 `recordFailure(...)`. 두 기록 호출은 모두 `PROCEED` 판정이 실어 온 -`GrpcClaimToken`을 받는다: claim을 넘겨준 시도의 커밋은 거절되고(그 트랜잭션은 롤백된다) 그 실패는 -무시된다. 그래서 느린 주인이 claim을 가져간 시도를 덮어쓰지 못한다(ADR-GRPC-004). - -**지우기 일정은 채택하는 쪽의 몫이다.** `GrpcOperationLedgerRetention.purgeExpired(now)`는 기한이 지난 -끝난 행을 한계 있는 batch(문장 하나에 500)로 지우고, batch가 덜 차서 돌아오면 멈춘다. starter는 이것을 -예약하지 않는다: scheduler를 가지지 않고 어느 replica가 돌려야 하는지 알 수 없으며, 예약된 bean은 모든 -배포에 task scheduler를 강요하게 된다. 채택하는 쪽이 자기 scheduler에서 부른다(예: 한 시간마다). -지우기가 잠긴 행을 건너뛰므로 여러 replica에서 동시에 돌려도 안전하다. 한 번도 돌리지 않아도 안전하지만 -테이블이 끝없이 커진다. - -커밋은 변경의 트랜잭션 안에서 기록해야 하고 TTL은 키가 필요한 가장 느린 메서드보다 길어야 한다. 두 -이유는 모두 ADR-GRPC-004에 있다. +@AGENTS.md