템플릿 repo 안에 프로젝트 계층이 아닌 라이브러리가 있었다. gRPC 플랫폼 (src/platforms/grpc, grpc-advanced)과 그것만을 위한 두 번째 Gradle 빌드 (src/platforms/optional-build)는 템플릿 어느 leaf도 쓰지 않는데, registry 9행, workflow job 넷과 단계 하나, build-logic 플러그인 둘, 카탈로그·SpotBugs 항목, 문서 열두 개를 템플릿이 함께 지고 있었다. 소유자 결정(2026-11-07, design-docs repo-structure/README.md 3.5절, 05-library-repos.md Q1~Q17 승인)대로 라이브러리마다 별도 repo로 옮긴다. gRPC는 템플릿 소비자가 없어 먼저 옮기고, 템플릿은 지우기만 한다(Q13). 코드와 이력은 grpc-library repo에 filter-repo로 옮겼다(옮긴 폴더의 트리 해시가 이 기준 커밋 22df3525와 같다). 지운 것: - src/platforms/grpc, grpc-advanced, optional-build(343파일) - registry의 "build": "optional-grpc" 9행 - ci-quality-gates.yml job optional-platforms·grpc-proto-buf와 그 needs, integration-main.yml optional 성능 단계와 job grpc-optional-platform-integration, release.yml job grpc-stable-release-gate와 이미지 job의 needs 한 줄 - build-logic ca.grpc-platform-module·ca.optional-architecture-registry, MainBuild(두 번째 빌드에서 주 빌드를 찾던 것)와 ArchitecturePlugin의 optional 분기. 도구 설정·이미지 목록·registry는 Gradle 루트에서 찾는다 - 카탈로그 protobufPlugin·protobuf-java-grpc·protoc·plugin protobuf(Q14: 채택 전이라 grpc-library 좌표도 넣지 않는다), SpotBugs 제외의 gRPC 줄 - 옮긴 문서: ADR-GRPC 7개, docs/compatibility/(폴더째), gRPC runbook 둘, gRPC 설계서. 리뷰·기록 본문은 고치지 않았다(Q15). 기록 하나의 머리 블록 「현재 정본」만 새 자리를 말하게 했다 - DeveloperExperienceContractTest의 optional 빌드 lane 계약 시험, adopter API 표면 검사의 optional-build 제외 경로 남긴 것: adapter:inbound:grpc(io.grpc를 직접 쓰고 플랫폼을 쓰지 않는다), src/platforms/messaging(다음 분리 작업), registry의 build 칸 지원 (ModuleRegistry, 일반 기능). 살아 있는 문서: README, docs 지도, capability-status, work/delegate· gates·decisions(새 행 「라이브러리 repo」)·defect-patterns· review-criteria(경계 밖 파일을 경로로 읽는 결합을 결함 후보로), manual 04, jpa migration-guide, build-logic AGENTS·README, testkit 주석. 새 docs/work/reference/related-repos.md가 라이브러리 repo 목록과 같이 고치는 법을 둔다. 파생 서비스 안내는 docs/upgrade 3.8절 B-55·B-56. 위험: 파생 서비스가 이 경로를 고쳤으면 수정 대 삭제 충돌이 난다 (tech-log-backend는 플랫폼을 받은 적이 없다, 설계 12절). 분리 직전 커밋 태그 pre-library-split(설계 12.2절)은 이 브랜치 권한 밖이라 달지 않았다. 검증: desktop 게이트 결과는 PR 본문(ci, mainCheck 계열, releaseCheck, compose smoke, 빠른 시작). 문서 검사 셋 rc=0. BREAKING CHANGE: src/platforms/grpc*·optional-build, :grpc:*·:grpc-advanced:* 프로젝트, ca.grpc-platform-module, 카탈로그 protoc·protobuf-java-grpc·plugin protobuf가 없다. 쓰던 서비스는 grpc-library 좌표 com.hyeonworks.grpc로 받는다(docs/upgrade/2026-11-maturity-review.md 3.8절). Refs: design-docs repo-structure/05-library-repos.md 13.1절 1·2단계
7.6 KiB
7.6 KiB
기록 · 계획서 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 끝남
- 작성일: 2026-08-30
- 요약: 타입 안전 gRPC 실행 플랫폼의 실행 계획과 실행 결과다.
- 현재 정본: 없음 — gRPC 플랫폼은 2026-11-08에 별도 repo grpc-library로 옮겼다. 지금 동작은 그 repo의 docs/compatibility/grpc-support-matrix.md다
타입 안전 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.gradle18개. 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.ledgerport (GrpcOperationLedger외 3) — 정책 계층이 DB에 의존하지 않고 durable idempotency를 요구할 수 있게 하기 위해 core-api에 둔다
Phase 2 — Contract governance (grpc-proto-contract, grpc-codegen, Task 8–11)
- Task 8
.proto2개 +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-clientTask 24–27grpc-discoveryTask 35–36grpc-adminTask 21–23·45grpc-observabilityTask 44grpc-operation-ledger-jpaTask 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.mddocs/compatibility/grpc-support-matrix.md,docs/compatibility/grpc-advanced-support-matrix.mdverifyRunbookReferences,verifyDocumentedLeafCount통과
Phase 9 — 2026-08-31 계획 대조 감사
사용자가 "빠짐없이 반영한게 맞나"를 물어 계획의 Files: 절 전체를 기계 대조했다. 결과와 조치는
설계 문서 §6이 SSOT다. 요약:
- 대조 스크립트 실행 → 초기 결과 present=316 / missing=38
- 실제 누락 6건 보완:
GrpcKubernetesProfileValidator,ADR-GRPC-006(discovery/Kubernetes), xDSbootstrap.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
.kt1)
남은 작업 (이 계획 범위 밖, 별도 결정 필요)
- 런타임 투입. 신규 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를 만든다.