타입 안전 gRPC 실행 플랫폼 — 실행 계획과 실행 결과

설계 SSOT: docs/superpowers/specs/2026-08-30-grpc-platform-adaptation-design.md

원본:

docs/2026-08-13-grpc-type-safe-rpc-platform-implementation-plan.md (Stable, Task 1–53)
docs/2026-08-13-grpc-advanced-capabilities-expansion-plan.md (Advanced, Task 1–18)

이 문서는 실행 전 계획이자 실행 결과 기록이다. 각 phase는 leaf 단위로 닫혔고, 닫힘 조건은 ./gradlew <gradle-path>:check 통과다 — 즉 test + spotless + checkstyle + SpotBugs(HIGH) + Error Prone/-Werror + 저장소 전역 게이트 전이 실행이다.

Phase 0 — 레지스트리와 스캐폴딩

src/config/architecture/modules.json에 18개 leaf 등록 (grpc:* 12, grpc-advanced:* 6)
leaf별 build.gradle 18개. io.grpc를 쓰는 leaf는 grpc-bom을 module scope로 import
src/build.gradle: :grpc: / :grpc-advanced: 를 plain JUnit+AssertJ 테스트 분기에 추가 (messaging:*와 같은 이유 — core-api가 Spring도 io.grpc도 이름 부르지 않는다는 주장을 검증 가능하게 만든다)
./gradlew --write-locks ...resolveAndLockAll 로 lockfile 18개 생성
verifyCleanArchitectureDependencies 통과

Phase 1 — Foundation (`grpc-core-api`, Stable Task 1–7 + ledger port)

Task 1 GrpcStableModuleCatalog / GrpcStableBuildInvariant
Task 2 GrpcMethodName / GrpcServiceName / GrpcChannelProfileName / RpcType / GrpcStatusCode
Task 3 RpcIdempotencyProfile / WaitForReadyPolicy / GrpcMethodPolicy / GrpcMethodPolicyCatalog
Task 4 GrpcTransportEvidence / GrpcBusinessEvidence / GrpcStreamEvidence / GrpcExecutionEvidence
Task 5 GrpcFailureCategory / GrpcCompletionOutcome / GrpcFailureContext / GrpcPlatformException
Task 6 GrpcDeadlineProfile / GrpcDeadlineBudget / GrpcCancellationToken / GrpcDeadlineExceededException
Task 7 GrpcRequestContext / GrpcMetadataKey / GrpcMetadataBudget / GrpcClientIdentity
추가: dev.caskeleton.grpc.ledger port (GrpcOperationLedger 외 3) — 정책 계층이 DB에 의존하지 않고 durable idempotency를 요구할 수 있게 하기 위해 core-api에 둔다

Phase 2 — Contract governance (`grpc-proto-contract`, `grpc-codegen`, Task 8–11)

Task 8 .proto 2개 + buf.yaml + GrpcProtoStyleManifest / GrpcProtoRuleViolation / GrpcProtoContractValidator
Task 9 GrpcBufPolicy / GrpcBreakingCategory / GrpcSchemaBaseline
Task 10 GrpcCodegenManifest / GrpcGeneratedPackagePolicy / GrpcCodegenOutput
Task 11 GrpcDescriptorArtifact / GrpcConsumerFixture / GrpcSchemaArtifactPublisher
편차: protoc·Buf CLI 미실행. 근거는 ADR-GRPC-002

Phase 3 — Policy (`grpc-policy`, Task 12·16·17·20·28–31·33·34·37–43)

Task 12 validation, Task 16 context propagation, Task 17 status/rich error, Task 20 TLS/credential rotation
Task 28 deadline calculator, Task 29 cancellation coordinator
Task 30 service config/retry owner, Task 31 retry eligibility/budget/coordinator, Task 42 wait-for-ready
Task 33 idempotency interceptor, Task 34 completion reconciliation
Task 37–41 stream envelope·writer·flow control·resume token·lifetime
Task 43 message size / compression / payload boundary

Phase 4 — Server boundary (`grpc-server`, Task 13–15·18–19)

Task 13 boundary rules + raw API import rule, Task 14 typed service adapter SPI
Task 15 interceptor 순서 계약, Task 18 Netty profile/executor/admission, Task 19 shaded parity

Phase 5 — Client / discovery / admin / observability / ledger

grpc-client Task 24–27
grpc-discovery Task 35–36
grpc-admin Task 21–23·45
grpc-observability Task 44
grpc-operation-ledger-jpa Task 32 (entity + repository + migration + port impl)

Phase 6 — Composition과 인증 (`grpc-spring-boot-starter`, `grpc-testkit`)

Task 52 properties / auto-configuration / startup validator
Task 46 in-process fixture, Task 47 실제 Netty + TLS/mTLS fixture
Task 48 fault point / scenario / evidence classifier
Task 49–50 unary·streaming contract suite, Task 51 performance budget/gate
Task 53 compatibility matrix / release evidence / release gate
strict test lane 4개 등록 및 실행: grpcInProcessContractTest, grpcNettyContractTest, grpcFaultTest, grpcPerformanceTest

Phase 7 — Advanced (`grpc-advanced:*`, Advanced Task 1–18)

A1·A18 grpc-advanced-bootstrap
A2·A3 grpc-advanced-edition
A4–A7 grpc-advanced-streaming
A8–A11 grpc-advanced-resilience
A12–A16 grpc-advanced-compat
A17 grpc-advanced-diagnostics

Phase 8 — 문서와 게이트

src/grpc/CLAUDE.md, src/grpc-advanced/CLAUDE.md
ADR-GRPC-001..005, ADR-GRPC-ADV-001
docs/runbooks/grpc-platform-operations.md, docs/runbooks/grpc-advanced-capabilities.md
docs/compatibility/grpc-support-matrix.md, docs/compatibility/grpc-advanced-support-matrix.md
verifyRunbookReferences, verifyDocumentedLeafCount 통과

Phase 9 — 2026-08-31 계획 대조 감사

사용자가 "빠짐없이 반영한게 맞나"를 물어 계획의 Files: 절 전체를 기계 대조했다. 결과와 조치는 설계 문서 §6이 SSOT다. 요약:

대조 스크립트 실행 → 초기 결과 present=316 / missing=38
실제 누락 6건 보완: GrpcKubernetesProfileValidator, ADR-GRPC-006(discovery/Kubernetes), xDS bootstrap.json, control-plane-snapshot.json, DocumentClientFixture, buf.gen.yaml+buf.lock
추가한 픽스처는 전부 실제 검사에 물렸다 — 장식이 되지 않도록: GrpcXdsStartupGuard.bootstrapMismatches(namespace 불일치·비TLS control plane), redactor가 실제 모양의 CSDS 데이터로 검증, GrpcConsumerFixture.fromJavaSource가 fixture 소스에서 요구사항을 역산
테스트 클래스 17건을 계획이 명시한 이름으로 분리
재대조 → present=341 / missing=13, 잔여 13건은 전부 §6.1–6.4의 기록된 편차 (ADR 파일명 6, codegen convention plugin 3, TLS 인증서 3, Kotlin .kt 1)

남은 작업 (이 계획 범위 밖, 별도 결정 필요)

런타임 투입. 신규 leaf 전부 runtime_memberships: []다. app-bootstrap에 배선하려면 registry membership 변경 + verifyRuntimeModuleMembership 통과가 선행이며, 그것은 별도 결정이다.
adapter:inbound:grpc 브리지. registry의 allowed_dependencies에 grpc-core-api·grpc-server를 추가하고 typed service adapter를 배선하는 작업. 플랫폼이 green이 된 지금이 시작점이다.
protoc / Buf CLI 활성화. ADR-GRPC-002가 조건과 비용을 기록한다.
performance baseline 기록. 현재 lane은 shape만 검증한다. 알려진 runner에서의 baseline이 regression gate를 만든다.

7.0 KiB Raw Blame History Unescape Escape

타입 안전 gRPC 실행 플랫폼 — 실행 계획과 실행 결과

Phase 0 — 레지스트리와 스캐폴딩

Phase 1 — Foundation (grpc-core-api, Stable Task 1–7 + ledger port)

Phase 2 — Contract governance (grpc-proto-contract, grpc-codegen, Task 8–11)

Phase 3 — Policy (grpc-policy, Task 12·16·17·20·28–31·33·34·37–43)

Phase 4 — Server boundary (grpc-server, Task 13–15·18–19)