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
@@ -1,93 +0,0 @@
package dev.caskeleton.grpc.release;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
/**
* Which combinations a release is certified against, and which are only watched.
*
* <p>The distinction is what keeps a support claim honest. "Works with Spring Boot" is not a
* statement anyone can act on; "certified on the managed Boot platform, compatibility-checked
* against an upstream gRPC override, and not run at all on Edition 2024" is.
*/
public record GrpcCompatibilityMatrix(Map<String, Lane> lanes) {
/** How much a combination has actually been exercised. */
public enum Lane {
/** Run on every release. A failure blocks. */
CERTIFIED(true),
/** Run, but a failure is reported rather than blocking. */
COMPATIBILITY(false),
/** Recorded and not run. */
WATCH(false);
private final boolean blocking;
Lane(boolean blocking) {
this.blocking = blocking;
}
/** Whether a failure in this lane blocks a release. */
public boolean blocking() {
return blocking;
}
}
/** Copies the lane map. */
public GrpcCompatibilityMatrix {
if (lanes == null || lanes.isEmpty()) {
throw new IllegalArgumentException("a compatibility matrix names at least one lane");
}
lanes = Map.copyOf(lanes);
if (lanes.values().stream().noneMatch(Lane::blocking)) {
throw new IllegalArgumentException(
"a matrix with no certified lane certifies nothing; every combination is optional");
}
}
/** This repository's matrix. */
public static GrpcCompatibilityMatrix caSkeleton() {
return new GrpcCompatibilityMatrix(
Map.of(
"boot-managed-platform", Lane.CERTIFIED,
"proto3-explicit-optional", Lane.CERTIFIED,
"netty-shaded", Lane.CERTIFIED,
"netty-unshaded", Lane.COMPATIBILITY,
"upstream-grpc-java-override", Lane.COMPATIBILITY,
"protobuf-edition-2024", Lane.WATCH,
"protobuf-edition-2026", Lane.WATCH));
}
/** The lanes whose failure blocks a release. */
public List<String> blockingLanes() {
return lanes.entrySet().stream()
.filter(entry -> entry.getValue().blocking())
.map(Map.Entry::getKey)
.sorted()
.toList();
}
/**
* Every blocking lane that has no result.
*
* @return an empty list when every certified lane ran
*/
public List<String> missingResults(Map<String, Boolean> laneResults) {
if (laneResults == null) {
throw new IllegalArgumentException("a lane result map is required");
}
List<String> missing = new ArrayList<>();
blockingLanes()
.forEach(
lane -> {
Boolean passed = laneResults.get(lane);
if (passed == null) {
missing.add("certified lane '" + lane + "' produced no result");
} else if (!passed) {
missing.add("certified lane '" + lane + "' failed");
}
});
return List.copyOf(missing);
}
}
@@ -1,42 +0,0 @@
package dev.caskeleton.grpc.release;
import java.util.List;
/**
* Whether a Stable release may go out.
*
* <p>Blockers are a list rather than a boolean because a release conversation is about what is
* missing. "The gate failed" starts a search; "the fault lane did not run and the runbook is
* absent" starts the work.
*/
public record GrpcReleaseDecision(boolean approved, List<String> blockers) {
/** Requires blockers exactly when refused. */
public GrpcReleaseDecision {
if (blockers == null) {
throw new IllegalArgumentException("a release decision lists its blockers, even when empty");
}
blockers = List.copyOf(blockers);
if (approved && !blockers.isEmpty()) {
throw new IllegalArgumentException("an approved release has no blockers");
}
if (!approved && blockers.isEmpty()) {
throw new IllegalArgumentException("a refused release says why");
}
}
/**
* An approved release.
*
* <p>Named {@code approve} rather than {@code approved}, which the record already uses for its
* accessor.
*/
public static GrpcReleaseDecision approve() {
return new GrpcReleaseDecision(true, List.of());
}
/** A refused release. */
public static GrpcReleaseDecision refuse(List<String> blockers) {
return new GrpcReleaseDecision(false, blockers);
}
}
@@ -1,63 +0,0 @@
package dev.caskeleton.grpc.release;
import dev.caskeleton.grpc.testkit.GrpcEvidenceGrade;
import java.util.EnumSet;
import java.util.LinkedHashSet;
import java.util.Set;
/**
* What a release actually has evidence for.
*
* <p>Graded, so a release cannot cite an in-process run as transport evidence. That substitution is
* the easiest one to make under time pressure and the hardest to spot afterwards: the suite name
* says "contract", the report says the platform is certified, and nothing in between records that
* no socket was opened.
*/
public record GrpcReleaseEvidence(
Set<GrpcEvidenceGrade> gradesRun,
Set<String> certifiedCapabilities,
boolean runbookPresent,
boolean architectureDecisionRecordsPresent,
boolean supportMatrixPresent) {
/** The grades a Stable release must have run. */
private static final Set<GrpcEvidenceGrade> REQUIRED_GRADES =
EnumSet.of(
GrpcEvidenceGrade.CONTRACT,
GrpcEvidenceGrade.TRANSPORT,
GrpcEvidenceGrade.FAULT,
GrpcEvidenceGrade.PERFORMANCE);
/** Copies both sets. */
public GrpcReleaseEvidence {
if (gradesRun == null || certifiedCapabilities == null) {
throw new IllegalArgumentException("release evidence states what ran and what it certified");
}
gradesRun = Set.copyOf(gradesRun);
certifiedCapabilities = Set.copyOf(certifiedCapabilities);
}
/** The grades a Stable release requires. */
public static Set<GrpcEvidenceGrade> requiredGrades() {
return Set.copyOf(REQUIRED_GRADES);
}
/** The grades that were not run. */
public Set<GrpcEvidenceGrade> missingGrades() {
Set<GrpcEvidenceGrade> missing = new LinkedHashSet<>(REQUIRED_GRADES);
missing.removeAll(gradesRun);
return Set.copyOf(missing);
}
/**
* Whether {@code capability} is backed by a grade that can establish it.
*
* <p>The check the whole type exists for: a TLS claim needs a run that opened a socket.
*/
public boolean supports(String capability) {
if (!certifiedCapabilities.contains(capability)) {
return false;
}
return gradesRun.stream().anyMatch(grade -> grade.certifies().contains(capability));
}
}
@@ -1,94 +0,0 @@
package dev.caskeleton.grpc.release;
import dev.caskeleton.grpc.testkit.GrpcEvidenceGrade;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
/**
* The last check before a Stable release: every lane ran, every grade is present, and the
* operational documents exist.
*
* <p>Documents are a blocker rather than a follow-up. A platform whose failure modes are {@code
* COMPLETION_UNKNOWN} and a stream that needs a full resync is a platform whose on-call has to be
* told what to do about them; shipping the behaviour and writing the runbook afterwards means the
* first person to meet it is the one who has to work it out at three in the morning.
*/
public final class GrpcStableReleaseGate {
private final GrpcCompatibilityMatrix matrix;
/** Binds the gate to its compatibility matrix. */
public GrpcStableReleaseGate(GrpcCompatibilityMatrix matrix) {
if (matrix == null) {
throw new IllegalArgumentException("a release gate needs a compatibility matrix");
}
this.matrix = matrix;
}
/**
* The release decision.
*
* @param schemaBreakages what {@code buf breaking} reported against the released schema (the CI
* job {@code grpc-proto-buf}); empty when the schema is compatible
*/
public GrpcReleaseDecision evaluate(
GrpcReleaseEvidence evidence,
Map<String, Boolean> laneResults,
List<String> schemaBreakages) {
if (evidence == null || laneResults == null || schemaBreakages == null) {
throw new IllegalArgumentException(
"a release decision needs evidence, lanes and the schema verdict");
}
List<String> blockers = new ArrayList<>(matrix.missingResults(laneResults));
evidence.missingGrades().stream()
.sorted()
.forEach(
grade ->
blockers.add(
grade
+ " evidence was not produced; without it the release cannot claim "
+ grade.certifies().stream().sorted().toList()));
schemaBreakages.forEach(breakage -> blockers.add("schema: " + breakage));
if (!evidence.runbookPresent()) {
blockers.add(
"the operations runbook is missing; COMPLETION_UNKNOWN and FULL_RESYNC_REQUIRED are "
+ "states an on-call has to be told what to do about");
}
if (!evidence.architectureDecisionRecordsPresent()) {
blockers.add("the architecture decision records are missing");
}
if (!evidence.supportMatrixPresent()) {
blockers.add("the support matrix is missing, so no combination has a stated support level");
}
return blockers.isEmpty()
? GrpcReleaseDecision.approve()
: GrpcReleaseDecision.refuse(blockers);
}
/**
* Whether a capability may be advertised as supported.
*
* @throws IllegalStateException when the evidence behind it is of the wrong grade
*/
public static void requireCertified(GrpcReleaseEvidence evidence, String capability) {
if (evidence == null) {
throw new IllegalArgumentException("release evidence is required");
}
if (!evidence.supports(capability)) {
throw new IllegalStateException(
"capability '"
+ capability
+ "' is not certified by the evidence this release produced ("
+ evidence.gradesRun().stream().map(GrpcEvidenceGrade::name).sorted().toList()
+ ")");
}
}
/** The matrix in force. */
public GrpcCompatibilityMatrix matrix() {
return matrix;
}
}
@@ -1,151 +0,0 @@
package dev.caskeleton.grpc.release;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.grpc.testkit.GrpcEvidenceGrade;
import java.util.EnumSet;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Set;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
class GrpcStableReleaseGateTest {
private final GrpcStableReleaseGate gate =
new GrpcStableReleaseGate(GrpcCompatibilityMatrix.caSkeleton());
private static Map<String, Boolean> allLanesPassing() {
Map<String, Boolean> lanes = new LinkedHashMap<>();
GrpcCompatibilityMatrix.caSkeleton().blockingLanes().forEach(lane -> lanes.put(lane, true));
return lanes;
}
private static GrpcReleaseEvidence completeEvidence() {
return new GrpcReleaseEvidence(
GrpcReleaseEvidence.requiredGrades(),
Set.of("tls", "http2", "interceptor-order", "completion-unknown", "latency"),
true,
true,
true);
}
private static List<String> schemaAllowed() {
return List.of();
}
@Test
@DisplayName("a release with every lane, grade and document approved goes out")
void aCompleteReleaseIsApproved() {
GrpcReleaseDecision decision =
gate.evaluate(completeEvidence(), allLanesPassing(), schemaAllowed());
assertThat(decision.approved()).isTrue();
assertThat(decision.blockers()).isEmpty();
}
@Test
@DisplayName("a certified lane that did not run blocks the release")
void aMissingCertifiedLaneBlocks() {
Map<String, Boolean> missing = allLanesPassing();
missing.remove("netty-shaded");
assertThat(gate.evaluate(completeEvidence(), missing, schemaAllowed()).blockers())
.anySatisfy(blocker -> assertThat(blocker).contains("netty-shaded"));
}
@Test
@DisplayName("a certified lane that failed blocks the release")
void aFailedCertifiedLaneBlocks() {
Map<String, Boolean> failed = allLanesPassing();
failed.put("boot-managed-platform", false);
assertThat(gate.evaluate(completeEvidence(), failed, schemaAllowed()).blockers())
.anySatisfy(blocker -> assertThat(blocker).contains("boot-managed-platform"));
}
@Test
@DisplayName("a watch lane's absence does not block")
void watchLanesDoNotBlock() {
assertThat(GrpcCompatibilityMatrix.caSkeleton().blockingLanes())
.doesNotContain("protobuf-edition-2024", "protobuf-edition-2026");
assertThat(GrpcCompatibilityMatrix.Lane.WATCH.blocking()).isFalse();
assertThat(GrpcCompatibilityMatrix.Lane.COMPATIBILITY.blocking()).isFalse();
assertThat(GrpcCompatibilityMatrix.Lane.CERTIFIED.blocking()).isTrue();
}
@Test
@DisplayName("a missing evidence grade blocks and says what it would have certified")
void aMissingGradeBlocks() {
GrpcReleaseEvidence noFaultLane =
new GrpcReleaseEvidence(
EnumSet.of(
GrpcEvidenceGrade.CONTRACT,
GrpcEvidenceGrade.TRANSPORT,
GrpcEvidenceGrade.PERFORMANCE),
Set.of("tls"),
true,
true,
true);
assertThat(gate.evaluate(noFaultLane, allLanesPassing(), schemaAllowed()).blockers())
.anySatisfy(
blocker -> assertThat(blocker).contains("FAULT").contains("completion-unknown"));
}
@Test
@DisplayName("the operational documents are blockers, not follow-ups")
void missingDocumentsBlock() {
GrpcReleaseEvidence undocumented =
new GrpcReleaseEvidence(
GrpcReleaseEvidence.requiredGrades(), Set.of("tls"), false, false, false);
assertThat(gate.evaluate(undocumented, allLanesPassing(), schemaAllowed()).blockers())
.anySatisfy(blocker -> assertThat(blocker).contains("runbook"))
.anySatisfy(blocker -> assertThat(blocker).contains("architecture decision records"))
.anySatisfy(blocker -> assertThat(blocker).contains("support matrix"));
}
@Test
@DisplayName("a schema that breaks a consumer blocks the release")
void aBrokenConsumerBlocks() {
List<String> refused =
List.of(
"caskeleton/grpc/common/v1/stream.proto: Field \"3\" on message \"StreamEnvelope\" deleted.");
assertThat(gate.evaluate(completeEvidence(), allLanesPassing(), refused).blockers())
.anySatisfy(blocker -> assertThat(blocker).startsWith("schema:"));
}
@Test
@DisplayName("a capability may not be advertised on evidence of the wrong grade")
void aCapabilityNeedsEvidenceOfTheRightGrade() {
GrpcReleaseEvidence contractOnly =
new GrpcReleaseEvidence(
EnumSet.of(GrpcEvidenceGrade.CONTRACT),
Set.of("tls", "interceptor-order"),
true,
true,
true);
assertThat(contractOnly.supports("interceptor-order")).isTrue();
assertThat(contractOnly.supports("tls")).isFalse();
GrpcStableReleaseGate.requireCertified(contractOnly, "interceptor-order");
assertThatThrownBy(() -> GrpcStableReleaseGate.requireCertified(contractOnly, "tls"))
.isInstanceOf(IllegalStateException.class)
.hasMessageContaining("not certified by the evidence");
}
@Test
@DisplayName("a matrix with no certified lane certifies nothing and is refused")
void aMatrixWithNoCertifiedLaneIsRefused() {
assertThatThrownBy(
() ->
new GrpcCompatibilityMatrix(
Map.of("everything", GrpcCompatibilityMatrix.Lane.WATCH)))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("certifies nothing");
}
}