review-followup Wave 3 라운드 1(P16): 빌드 게이트 정리 — JPA evidence manifest 폐기, build-tools 제거, API surface를 leaf check로

- 결정 4: JPA evidence·qualification manifest 폐기 → persistence-jpa 테스트, build-tools included build 비움(verifyEnvKeys는
  app-bootstrap 태스크, 구현은 build-logic `ca.config-contract`), gRPC release gate 삭제
- 결정 20: API surface 검사를 leaf `check`로, JPA adopter 검사를 `ca.api-surface`로 합침(구현 하나)
- 레인 단계 정리(문서 대조 레인은 `mainStage()`), integrationCheck가 입력 없는 레인을 이름과 함께 제외 → 로컬 통과(NEW-16)
- release workflow 통합, releaseCheck는 tag 전용, build-logic 비핵심 플러그인 정리, sample을 ArchUnit 대상에
- 보류 4행(B3 변경 모듈만 실행, C 이미지 서명, messaging 카드 검증 이동 2행 — 결정 필요), 남음 2행(O3-5 나머지)
- 통합: P17이 옮긴 gRPC release gate 사본 삭제, `grpc-proto-buf`를 release-gate needs에(P17-new-3)

검증: ./gradlew ci verifyDependencyLocks --warning-mode=fail 통과(685 task), mainCheck 통과(268 task),
-p optional-platforms ci 통과, -p build-logic test 78건 통과(손상된 TestKit 캐시 삭제 후)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
donghyeon-ka
2026-09-28 16:44:17 +09:00
co-authored by Claude Opus 5.5
parent 3e2cbd54f1
commit ee4b243fe0
14 changed files with 16 additions and 881 deletions
+4 -3
View File
@@ -53,9 +53,10 @@ property key는 `ca-skeleton.grpc.advanced.<capability>.enabled`이고 전부
## Promotion은 capability별로 독립이다
`GrpcAdvancedPromotionEvidence`는 capability마다 별도 레코드다. 공유 레코드였다면 하나를 승격할 때
같은 시점에 측정된 다른 것들이 함께 승격된다. `GrpcAdvancedPromotionGate.capabilitiesDraggedAlong`이
항상 빈 리스트인 것은 주석이 아니라 테스트되는 속성이다.
승격 증거는 capability마다 따로 판단한다. 공유 증거였다면 하나를 승격할 때 같은 시점에 측정된 다른
것들이 함께 승격된다. 이 규칙을 코드로 옮겨 두었던 `GrpcAdvancedPromotionGate`는 자기 테스트 말고
호출처가 없어 삭제했다(리뷰 2026-09-24 S5-lead-4). 지금은 `docs/runbooks/grpc-advanced-capabilities.md`의
리뷰 규칙이다.
승격 문턱은 두 개다: `ADVANCED_STABLE`은 7일 soak + 전체 증거, Stable default는 30일 soak. 두 번째가
더 높은 이유는 모든 배포가 그 의존성과 장애 모드를 갖게 되기 때문이다.
@@ -1,50 +0,0 @@
package dev.caskeleton.grpc.advanced.release;
import dev.caskeleton.grpc.advanced.bootstrap.GrpcAdvancedCapability;
import dev.caskeleton.grpc.advanced.bootstrap.GrpcCapabilityGrade;
import java.util.List;
/**
* Whether one capability moves to a new grade.
*
* <p>Carries the grade it would move to as well as the blockers, so a refusal says what was being
* asked for. "Not promoted" is ambiguous between a failed promotion to Advanced Stable and a failed
* promotion to a Stable default, and the second is a much larger decision.
*/
public record GrpcAdvancedPromotionDecision(
GrpcAdvancedCapability capability,
GrpcCapabilityGrade from,
GrpcCapabilityGrade to,
boolean promoted,
List<String> blockers) {
/** Requires blockers exactly when refused. */
public GrpcAdvancedPromotionDecision {
if (capability == null || from == null || to == null || blockers == null) {
throw new IllegalArgumentException(
"a promotion decision names its capability and both grades");
}
blockers = List.copyOf(blockers);
if (promoted && !blockers.isEmpty()) {
throw new IllegalArgumentException("a granted promotion has no blockers");
}
if (!promoted && blockers.isEmpty()) {
throw new IllegalArgumentException("a refused promotion says why");
}
}
/** A granted promotion. */
public static GrpcAdvancedPromotionDecision grant(
GrpcAdvancedCapability capability, GrpcCapabilityGrade from, GrpcCapabilityGrade to) {
return new GrpcAdvancedPromotionDecision(capability, from, to, true, List.of());
}
/** A refused promotion. */
public static GrpcAdvancedPromotionDecision refuse(
GrpcAdvancedCapability capability,
GrpcCapabilityGrade from,
GrpcCapabilityGrade to,
List<String> blockers) {
return new GrpcAdvancedPromotionDecision(capability, from, to, false, blockers);
}
}
@@ -1,75 +0,0 @@
package dev.caskeleton.grpc.advanced.release;
import dev.caskeleton.grpc.advanced.bootstrap.GrpcAdvancedCapability;
import java.time.Duration;
import java.util.Set;
/**
* What one capability has behind it.
*
* <p>Per capability, never shared. The Stable plan's requirement that Edition, streaming, xDS,
* gRPC-Web, Servlet and the language adapters do not gate each other only means something if their
* evidence is separate: a shared record makes promoting one of them promote whichever others
* happened to be measured at the same time.
*/
public record GrpcAdvancedPromotionEvidence(
GrpcAdvancedCapability capability,
boolean compatibilityEvidence,
boolean securityReview,
boolean faultEvidence,
boolean performanceEvidence,
Duration soakDuration,
boolean architectureDecisionRecord,
boolean runbook,
boolean realEnvironmentTest) {
/** Requires a capability and a non-negative soak. */
public GrpcAdvancedPromotionEvidence {
if (capability == null) {
throw new IllegalArgumentException("promotion evidence names its capability");
}
if (soakDuration == null || soakDuration.isNegative()) {
throw new IllegalArgumentException("a soak duration must be present and non-negative");
}
}
/** No evidence at all, which is where a capability starts. */
public static GrpcAdvancedPromotionEvidence none(GrpcAdvancedCapability capability) {
return new GrpcAdvancedPromotionEvidence(
capability, false, false, false, false, Duration.ZERO, false, false, false);
}
/** Everything a promotion to Advanced Stable needs. */
public static GrpcAdvancedPromotionEvidence complete(
GrpcAdvancedCapability capability, Duration soakDuration) {
return new GrpcAdvancedPromotionEvidence(
capability, true, true, true, true, soakDuration, true, true, true);
}
/** Which required items are absent, as a set a report can print. */
public Set<String> missing() {
Set<String> missing = new java.util.LinkedHashSet<>();
if (!compatibilityEvidence) {
missing.add("compatibility evidence");
}
if (!securityReview) {
missing.add("security review");
}
if (!faultEvidence) {
missing.add("fault evidence");
}
if (!performanceEvidence) {
missing.add("performance evidence");
}
if (!architectureDecisionRecord) {
missing.add("architecture decision record");
}
if (!runbook) {
missing.add("runbook");
}
if (!realEnvironmentTest) {
missing.add("real environment test");
}
return Set.copyOf(missing);
}
}
@@ -1,85 +0,0 @@
package dev.caskeleton.grpc.advanced.release;
import dev.caskeleton.grpc.advanced.bootstrap.GrpcAdvancedCapability;
import dev.caskeleton.grpc.advanced.bootstrap.GrpcCapabilityGrade;
import java.time.Duration;
import java.util.ArrayList;
import java.util.List;
/**
* Decides one capability's promotion, on its own evidence.
*
* <p>Two thresholds rather than one. Reaching Advanced Stable means the capability works and is
* documented; becoming a Stable default means every deployment gets it, which additionally puts its
* dependencies on every classpath and its failure modes in every on-call rotation. The second needs
* the first plus a longer soak, because a capability that has run in one deployment for a week is
* not the same claim as one that ships to all of them.
*/
public final class GrpcAdvancedPromotionGate {
/** The soak a promotion to Advanced Stable requires. */
public static final Duration ADVANCED_STABLE_SOAK = Duration.ofDays(7);
/** The soak a promotion to a Stable default requires. */
public static final Duration STABLE_DEFAULT_SOAK = Duration.ofDays(30);
private GrpcAdvancedPromotionGate() {}
/**
* Whether {@code capability} may move from {@code from} to {@code to}.
*
* @throws IllegalArgumentException when the transition is not one this gate governs
*/
public static GrpcAdvancedPromotionDecision evaluate(
GrpcAdvancedPromotionEvidence evidence, GrpcCapabilityGrade from, GrpcCapabilityGrade to) {
if (evidence == null || from == null || to == null) {
throw new IllegalArgumentException("a promotion needs evidence and both grades");
}
if (from == to) {
throw new IllegalArgumentException("a promotion changes the grade");
}
GrpcAdvancedCapability capability = evidence.capability();
List<String> blockers = new ArrayList<>();
evidence.missing().stream()
.sorted()
.forEach(missing -> blockers.add(capability.flagName() + " has no " + missing));
Duration requiredSoak =
to == GrpcCapabilityGrade.ADVANCED_STABLE ? ADVANCED_STABLE_SOAK : STABLE_DEFAULT_SOAK;
if (evidence.soakDuration().compareTo(requiredSoak) < 0) {
blockers.add(
capability.flagName()
+ " soaked for "
+ evidence.soakDuration().toDays()
+ " day(s); promotion to "
+ to
+ " requires "
+ requiredSoak.toDays());
}
if (from == GrpcCapabilityGrade.WATCH && to != GrpcCapabilityGrade.EXPERIMENTAL) {
blockers.add(
capability.flagName()
+ " is WATCH, which is tracked rather than implemented; it becomes EXPERIMENTAL "
+ "before anything else");
}
return blockers.isEmpty()
? GrpcAdvancedPromotionDecision.grant(capability, from, to)
: GrpcAdvancedPromotionDecision.refuse(capability, from, to, blockers);
}
/**
* Whether promoting {@code promoted} would drag another capability with it.
*
* <p>Always empty, and the method exists so a test can assert that rather than a comment claiming
* it: each capability's evidence is its own record, so there is no path by which one promotion
* changes another's grade.
*/
public static List<GrpcAdvancedCapability> capabilitiesDraggedAlong(
GrpcAdvancedCapability promoted) {
if (promoted == null) {
throw new IllegalArgumentException("a capability is required");
}
return List.of();
}
}
@@ -1,66 +0,0 @@
package dev.caskeleton.grpc.advanced.release;
import dev.caskeleton.grpc.advanced.bootstrap.GrpcAdvancedCapability;
import dev.caskeleton.grpc.advanced.bootstrap.GrpcCapabilityGrade;
import java.util.EnumMap;
import java.util.Map;
/**
* Every advanced capability's current grade, in one place an adopter can read.
*
* <p>The published answer to "is this supported". Without it the answer is inferred from whether a
* class exists, which says only that somebody wrote it.
*/
public final class GrpcAdvancedSupportMatrix {
private final Map<GrpcAdvancedCapability, GrpcCapabilityGrade> grades =
new EnumMap<>(GrpcAdvancedCapability.class);
/** A matrix at each capability's default grade. */
public GrpcAdvancedSupportMatrix() {
for (GrpcAdvancedCapability capability : GrpcAdvancedCapability.values()) {
grades.put(capability, capability.defaultGrade());
}
}
/** The grade of one capability. */
public GrpcCapabilityGrade gradeOf(GrpcAdvancedCapability capability) {
if (capability == null) {
throw new IllegalArgumentException("a capability is required");
}
return grades.get(capability);
}
/**
* Applies a granted promotion.
*
* @throws IllegalArgumentException when the decision's starting grade is not the current one,
* which means two promotions raced or one was replayed
*/
public GrpcAdvancedSupportMatrix apply(GrpcAdvancedPromotionDecision decision) {
if (decision == null) {
throw new IllegalArgumentException("a decision is required");
}
if (!decision.promoted()) {
return this;
}
GrpcCapabilityGrade current = grades.get(decision.capability());
if (current != decision.from()) {
throw new IllegalArgumentException(
"capability '"
+ decision.capability().flagName()
+ "' is "
+ current
+ ", not "
+ decision.from()
+ "; this decision was made against a different matrix");
}
grades.put(decision.capability(), decision.to());
return this;
}
/** The whole matrix. */
public Map<GrpcAdvancedCapability, GrpcCapabilityGrade> snapshot() {
return Map.copyOf(grades);
}
}
@@ -1,150 +0,0 @@
package dev.caskeleton.grpc.advanced.release;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.grpc.advanced.bootstrap.GrpcAdvancedCapability;
import dev.caskeleton.grpc.advanced.bootstrap.GrpcCapabilityGrade;
import java.time.Duration;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
class GrpcAdvancedPromotionGateTest {
@Test
@DisplayName("a capability with complete evidence and a full soak is promoted")
void completeEvidencePromotes() {
GrpcAdvancedPromotionDecision decision =
GrpcAdvancedPromotionGate.evaluate(
GrpcAdvancedPromotionEvidence.complete(
GrpcAdvancedCapability.HEDGING, Duration.ofDays(7)),
GrpcCapabilityGrade.EXPERIMENTAL,
GrpcCapabilityGrade.ADVANCED_STABLE);
assertThat(decision.promoted()).isTrue();
assertThat(decision.blockers()).isEmpty();
}
@Test
@DisplayName("every missing piece of evidence is named")
void everyMissingPieceIsNamed() {
GrpcAdvancedPromotionDecision decision =
GrpcAdvancedPromotionGate.evaluate(
GrpcAdvancedPromotionEvidence.none(GrpcAdvancedCapability.XDS),
GrpcCapabilityGrade.EXPERIMENTAL,
GrpcCapabilityGrade.ADVANCED_STABLE);
assertThat(decision.blockers())
.anySatisfy(blocker -> assertThat(blocker).contains("compatibility evidence"))
.anySatisfy(blocker -> assertThat(blocker).contains("security review"))
.anySatisfy(blocker -> assertThat(blocker).contains("fault evidence"))
.anySatisfy(blocker -> assertThat(blocker).contains("runbook"))
.anySatisfy(blocker -> assertThat(blocker).contains("real environment test"))
.anySatisfy(blocker -> assertThat(blocker).contains("soaked for"));
}
@Test
@DisplayName("becoming a Stable default needs a longer soak than becoming Advanced Stable")
void theStableDefaultThresholdIsHigher() {
GrpcAdvancedPromotionEvidence weekLongSoak =
GrpcAdvancedPromotionEvidence.complete(GrpcAdvancedCapability.GRPC_WEB, Duration.ofDays(7));
assertThat(
GrpcAdvancedPromotionGate.evaluate(
weekLongSoak,
GrpcCapabilityGrade.EXPERIMENTAL,
GrpcCapabilityGrade.ADVANCED_STABLE)
.promoted())
.isTrue();
assertThat(
GrpcAdvancedPromotionGate.evaluate(
weekLongSoak, GrpcCapabilityGrade.ADVANCED_STABLE, GrpcCapabilityGrade.DISABLED)
.blockers())
.anySatisfy(blocker -> assertThat(blocker).contains("requires 30"));
}
@Test
@DisplayName("a WATCH capability becomes EXPERIMENTAL before anything else")
void watchPromotesOnlyToExperimental() {
assertThat(
GrpcAdvancedPromotionGate.evaluate(
GrpcAdvancedPromotionEvidence.complete(
GrpcAdvancedCapability.EDITION_2026, Duration.ofDays(60)),
GrpcCapabilityGrade.WATCH,
GrpcCapabilityGrade.ADVANCED_STABLE)
.blockers())
.anySatisfy(blocker -> assertThat(blocker).contains("becomes EXPERIMENTAL"));
assertThat(
GrpcAdvancedPromotionGate.evaluate(
GrpcAdvancedPromotionEvidence.complete(
GrpcAdvancedCapability.EDITION_2026, Duration.ofDays(60)),
GrpcCapabilityGrade.WATCH,
GrpcCapabilityGrade.EXPERIMENTAL)
.promoted())
.isTrue();
}
@Test
@DisplayName("promoting one capability drags none of the others with it")
void promotionsAreIndependent() {
GrpcAdvancedSupportMatrix matrix = new GrpcAdvancedSupportMatrix();
GrpcCapabilityGrade webBefore = matrix.gradeOf(GrpcAdvancedCapability.GRPC_WEB);
matrix.apply(
GrpcAdvancedPromotionGate.evaluate(
GrpcAdvancedPromotionEvidence.complete(
GrpcAdvancedCapability.HEDGING, Duration.ofDays(7)),
GrpcCapabilityGrade.EXPERIMENTAL,
GrpcCapabilityGrade.ADVANCED_STABLE));
assertThat(matrix.gradeOf(GrpcAdvancedCapability.HEDGING))
.isEqualTo(GrpcCapabilityGrade.ADVANCED_STABLE);
assertThat(matrix.gradeOf(GrpcAdvancedCapability.GRPC_WEB)).isEqualTo(webBefore);
assertThat(GrpcAdvancedPromotionGate.capabilitiesDraggedAlong(GrpcAdvancedCapability.HEDGING))
.isEmpty();
}
@Test
@DisplayName("a decision made against a different matrix state is refused")
void aStaleDecisionIsRefused() {
GrpcAdvancedSupportMatrix matrix = new GrpcAdvancedSupportMatrix();
assertThatThrownBy(
() ->
matrix.apply(
GrpcAdvancedPromotionGate.evaluate(
GrpcAdvancedPromotionEvidence.complete(
GrpcAdvancedCapability.GRPC_WEB, Duration.ofDays(7)),
GrpcCapabilityGrade.EXPERIMENTAL,
GrpcCapabilityGrade.ADVANCED_STABLE)))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("made against a different matrix");
}
@Test
@DisplayName("a refused promotion leaves the matrix alone")
void aRefusedPromotionChangesNothing() {
GrpcAdvancedSupportMatrix matrix = new GrpcAdvancedSupportMatrix();
matrix.apply(
GrpcAdvancedPromotionGate.evaluate(
GrpcAdvancedPromotionEvidence.none(GrpcAdvancedCapability.XDS),
GrpcCapabilityGrade.EXPERIMENTAL,
GrpcCapabilityGrade.ADVANCED_STABLE));
assertThat(matrix.gradeOf(GrpcAdvancedCapability.XDS))
.isEqualTo(GrpcCapabilityGrade.EXPERIMENTAL);
}
@Test
@DisplayName("a promotion that changes nothing is refused")
void aNoOpPromotionIsRefused() {
assertThatThrownBy(
() ->
GrpcAdvancedPromotionGate.evaluate(
GrpcAdvancedPromotionEvidence.none(GrpcAdvancedCapability.XDS),
GrpcCapabilityGrade.EXPERIMENTAL,
GrpcCapabilityGrade.EXPERIMENTAL))
.isInstanceOf(IllegalArgumentException.class);
}
}