fix: 3차 확인 리뷰의 Minor 19건을 고친다

문제: 3차 수정의 확인 리뷰가 새 Important 없이 Minor 19건을 남겼다.
동작에 닿는 것이 셋이다. JDK read-idle watchdog이 공용 ForkJoinPool에서
돌아 그 풀이 바쁘면 300ms timeout이 6초 가까이 늦었다. 붙여 쓴
-x<task>를 verifyStrictLaneStages가 읽지 않아 lane을 뺀 workflow가
통과했다. 사용자 전송이 중간 클래스를 거쳐 @SystemCaller bean을 부르면
ArchUnit 규칙을 지났다. 잠금 대기 검사기는 FK·trigger·REINDEX와
lock_timeout = 0을 못 봤고, 쿼터 보정 SQL은 코드와 다른 모양의 행을
넣었다.

방법: 영역별 4묶음이 맡은 Minor만 test-driven-development 절차로
고쳤다(재리뷰 README 12절).
- watchdog은 전용 데몬 스레드 하나에서 돌고 스트림을 닫으면 작업을
  취소한다. read당 비용은 그대로다(21–24ns).
- 사용자 전송 → @SystemCaller는 직접·간접 의존 모두 거부한다. 리뷰가
  권한 직접 의존 검사는 중간 클래스 하나로 다시 열려서 버렸다.
- 검사기를 보강하면서 새로 걸린 이미 배포된 마이그레이션 5개는 내용을
  바꾸지 않고 동결 목록에 더했다(main과 blob이 같다).
- 비밀 목록 bean은 규칙보다 먼저 만들어 실제 클래스로 검사한다.

위험·한계: 회복 필요 예외 메시지 끝에 scope digest가 붙고 기동 실패
문구가 바뀌어, 문구 전체에 맞추던 로그 매처는 고쳐야 한다. 코드가 든
Redis 계정 참조의 fixture- 검사는 문서로만 막았다(코드로 막으려면 새
의존 edge가 필요하다). failure-retention ≥ replay-ttl 기동 검사는 넣지
않았다. -mx 같은 짧은 플래그 묶음과 graphql 전송 fixture는 남았다.
spotbugsTestFixtures(게이트 밖)의 정규식 경고가 15건으로 늘었다.

검증: ci, 두 빌드의 verifyStrictLaneStages --dry-run, mainCheck,
:integrationCheck, -p optional-platforms ci integrationCheck
performanceCheck, :performanceCheck, :releaseCheck(-PgitRevision),
verify-compose-profile-contracts(18 lane) 첫 실행 통과. watchdog은
공용 풀을 채운 상태에서 300ms 설정이 300ms에 끝나는 것을 쟀다.

Refs: docs/reviews/2026-11-03-rereview/README.md 11·12절, round3/
This commit is contained in:
DongHyeonka
2026-11-04 03:00:21 +09:00
parent 339cf8fdbf
commit f40c03c6d3
77 changed files with 1876 additions and 410 deletions
+12 -8
View File
@@ -202,12 +202,15 @@ subclass a final class (`RequiresPermissionProxyabilityTest`). It is registered
same reason — a use case built with `new` is never checked. A use case only the system calls (a
scheduler, a relay, a message consumer) carries `@SystemInvoked(reason = ...)` instead of a
permission and is not a bean: it is a write with no permission check, so no user request may reach
it. Its system caller constructs it — a composition module for a scheduler, or a
`@SystemCaller(reason = ...)` message handler in `..adapter.inbound.messaging..` (manual 09
「소비」 step 4). Both halves are enforced — a `@SystemInvoked` bean fails startup, and an inbound
adapter that depends on one without being a `@SystemCaller` fails
`ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES` (`SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`
keeps the mark off user transports). A composition with `@RequiresPermission`
it. Its system caller constructs it — a composition module for a scheduler, a
`@SystemCaller(reason = ...)` message handler in `..adapter.inbound.messaging..`, or a
`@SystemCaller` scheduled job in the service's own `..adapter.inbound.scheduler..` package. Manual
07 「시스템이 부르는 쓰기」 is the canonical list of the three and where each lives. All of it is
enforced — a `@SystemInvoked` bean fails startup, an inbound adapter that depends on one without
being a `@SystemCaller` fails `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`,
`SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS` keeps the mark (and classes nested in a marked
one) off user transports, and `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS` keeps a user transport
from calling a system caller. A composition with `@RequiresPermission`
beans but no enforcing advisor fails startup too (`composition:service-runtime`
`PermissionEnforcementGuard`, both checks).
@@ -268,8 +271,9 @@ generation; the V1 `IdempotencyScope`/`tryBegin` API is gone.
could not prove the outcome, so do not blindly retry.
- Every store answers an execution whose processing lease ran out with `RecoveryRequired` and never
takes it over; only a claim that never started or a retryable failure is taken over. A record lives
for the lease plus the replay TTL. `IdempotencyStoreContract` holds the fake, Redis and PostgreSQL
to both on real servers (re-review 2026-11-04 RR-01-11, RR-03-11).
for the lease plus the replay TTL. `IdempotencyStoreContract` holds Redis and PostgreSQL to both on
real servers; the in-memory fake models no time, so it runs only the contract's time-free cases
(re-review 2026-11-04 RR-01-11, RR-03-11, RR3-03-04).
The former ArchUnit freeze rule `inbound_port_implementations_do_not_declare_keyed_idempotency`
and its fixture were removed when this branch merged.
+2 -1
View File
@@ -458,7 +458,8 @@ claim → 트랜잭션 밖에서 발행 → at-least-once 보장.
`PermissionEnforcementGuard`가 기동을 실패시키고, `@SystemCaller`가 아닌 inbound adapter가 그 클래스에
의존하면 `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`가 빌드를 실패시킨다(review 2026-11-03
RR-01-02, RR-01-12). 메시지 소비자는 `@SystemCaller` handler가 use case를 직접 만든다(매뉴얼 09장
「소비」 4단계).
「소비」 4단계). 시스템 호출자 세 가지(조립 모듈의 스케줄러, `@SystemCaller` 메시지 handler,
`@SystemCaller` 예약 작업)와 각각 두는 곳은 매뉴얼 07장 「시스템이 부르는 쓰기」가 정본이다.
### OutboxBackoffPolicy
@@ -121,9 +121,9 @@ public final class IdempotencyExecutor {
case IdempotencyClaimOutcome.InProgress ignored ->
throw IdempotencyInFlightException.forScopeDigest(diagnostic(scope));
case IdempotencyClaimOutcome.RecoveryRequired ignored ->
throw recovery("claim requires reconciliation");
throw recovery(scope, "claim requires reconciliation");
case IdempotencyClaimOutcome.OwnerOperationConflict ignored ->
throw recovery("claim requires reconciliation");
throw recovery(scope, "claim requires reconciliation");
case IdempotencyClaimOutcome.Unavailable ignored ->
throw new IdempotencyUnavailableException();
// The response was lost, not the attempt. The retained attempt is what makes the record
@@ -148,9 +148,11 @@ public final class IdempotencyExecutor {
IdempotencyInspection inspection = inspect(request);
return switch (inspection.outcome()) {
case CLAIMED_SAME_OPERATION ->
startAndRun(request, requireOwner(inspection), action, codec, false);
case EXECUTING_SAME_OPERATION -> runStarted(request, requireOwner(inspection), action, codec);
case COMPLETED_REPLAY -> codec.deserialize(requireResponse(inspection).payload());
startAndRun(request, requireOwner(request.scope(), inspection), action, codec, false);
case EXECUTING_SAME_OPERATION ->
runStarted(request, requireOwner(request.scope(), inspection), action, codec);
case COMPLETED_REPLAY ->
codec.deserialize(requireResponse(request.scope(), inspection).payload());
case FINGERPRINT_MISMATCH ->
throw IdempotencyRequestMismatchException.forScopeDigest(diagnostic(request.scope()));
case IN_PROGRESS_OTHER ->
@@ -159,7 +161,8 @@ public final class IdempotencyExecutor {
// ABSENT, FAILED_RETRYABLE, ABANDONED and OPERATION_CONFLICT all mean the same thing here:
// this caller cannot prove what happened to its own attempt, and guessing is the one thing an
// owner-safe store exists to prevent.
default -> throw recovery("an indeterminate claim could not be resumed safely");
default ->
throw recovery(request.scope(), "an indeterminate claim could not be resumed safely");
};
}
@@ -179,11 +182,14 @@ public final class IdempotencyExecutor {
case UNAVAILABLE -> throw new IdempotencyUnavailableException();
case INDETERMINATE -> {
if (alreadyRetried) {
throw recovery("execution start stayed indeterminate after reconciliation");
throw recovery(
request.scope(), "execution start stayed indeterminate after reconciliation");
}
yield resumeAfterIndeterminateStart(request, action, codec);
}
default -> throw recovery("execution start was not confirmed for this exact operation");
default ->
throw recovery(
request.scope(), "execution start was not confirmed for this exact operation");
};
}
@@ -194,11 +200,13 @@ public final class IdempotencyExecutor {
IdempotencyInspection inspection = inspect(request);
return switch (inspection.outcome()) {
case CLAIMED_SAME_OPERATION ->
startAndRun(request, requireOwner(inspection), action, codec, true);
case EXECUTING_SAME_OPERATION -> runStarted(request, requireOwner(inspection), action, codec);
case COMPLETED_REPLAY -> codec.deserialize(requireResponse(inspection).payload());
startAndRun(request, requireOwner(request.scope(), inspection), action, codec, true);
case EXECUTING_SAME_OPERATION ->
runStarted(request, requireOwner(request.scope(), inspection), action, codec);
case COMPLETED_REPLAY ->
codec.deserialize(requireResponse(request.scope(), inspection).payload());
case UNAVAILABLE -> throw new IdempotencyUnavailableException();
default -> throw recovery("execution start is indeterminate");
default -> throw recovery(request.scope(), "execution start is indeterminate");
};
}
@@ -253,7 +261,7 @@ public final class IdempotencyExecutor {
// The action has run. Reporting "unavailable" here would tell the client it did not.
case UNAVAILABLE -> throw new IdempotencyCompletionUnknownException();
case INDETERMINATE -> reconcileCompletion(request, result, codec, alreadyRetried);
default -> throw recovery("completion was not confirmed");
default -> throw recovery(request.scope(), "completion was not confirmed");
};
}
@@ -272,22 +280,25 @@ public final class IdempotencyExecutor {
IdempotencyInspection inspection = inspect(request);
return switch (inspection.outcome()) {
case COMPLETED_REPLAY -> {
StoredResponse stored = requireResponse(inspection);
StoredResponse stored = requireResponse(request.scope(), inspection);
if (stored.payload().equals(codec.serialize(result))) {
yield result;
}
// The stored response is somebody else's answer to this scope. Returning either one would
// be asserting a fact this caller cannot establish.
throw recovery("the completed response conflicts with the one this caller produced");
throw recovery(
request.scope(), "the completed response conflicts with the one this caller produced");
}
case EXECUTING_SAME_OPERATION -> {
if (alreadyRetried) {
throw recovery("completion stayed indeterminate after reconciliation");
throw recovery(request.scope(), "completion stayed indeterminate after reconciliation");
}
yield complete(request, requireOwner(inspection), result, codec, true);
yield complete(request, requireOwner(request.scope(), inspection), result, codec, true);
}
case UNAVAILABLE -> throw new IdempotencyCompletionUnknownException();
default -> throw recovery("the completion response is indeterminate and was not reconciled");
default ->
throw recovery(
request.scope(), "the completion response is indeterminate and was not reconciled");
};
}
@@ -320,20 +331,24 @@ public final class IdempotencyExecutor {
return transition.owner().orElse(fallback);
}
private static IdempotencyOwner requireOwner(IdempotencyInspection inspection) {
private static IdempotencyOwner requireOwner(
IdempotencyScopeDigest scope, IdempotencyInspection inspection) {
Optional<IdempotencyOwner> owner = inspection.owner();
return owner.orElseThrow(
() ->
recovery(
scope,
"the store reported "
+ inspection.outcome()
+ " without the owner handle it needs"));
}
private static StoredResponse requireResponse(IdempotencyInspection inspection) {
private static StoredResponse requireResponse(
IdempotencyScopeDigest scope, IdempotencyInspection inspection) {
return inspection
.response()
.orElseThrow(() -> recovery("the store reported a completed replay with no response"));
.orElseThrow(
() -> recovery(scope, "the store reported a completed replay with no response"));
}
/**
@@ -345,7 +360,13 @@ public final class IdempotencyExecutor {
return scope.operationCode() + "::v" + scope.keyDigestVersion() + "::" + scope.digest();
}
private static IdempotencyRecoveryRequiredException recovery(String message) {
return new IdempotencyRecoveryRequiredException(message);
/**
* A recovery-required failure that names its scope, as the in-flight and mismatch failures do:
* the runbook's first step is to find this record, and the scope digest is the only identity this
* lifecycle holds (re-review 2026-11-04 RR3-03-03).
*/
private static IdempotencyRecoveryRequiredException recovery(
IdempotencyScopeDigest scope, String message) {
return new IdempotencyRecoveryRequiredException(message + ": " + diagnostic(scope));
}
}
@@ -4,7 +4,11 @@ import dev.caskeleton.shared.error.ApiErrorCarrier;
import dev.caskeleton.shared.error.ApiErrorCode;
import dev.caskeleton.shared.error.OperationalError;
/** Raised when request replay cannot safely decide whether an external effect already occurred. */
/**
* Raised when request replay cannot safely decide whether an external effect already occurred. The
* executor's message ends with the opaque scope digest, for logs only — the record an operator
* looks up (re-review 2026-11-04 RR3-03-03); transports answer with the code's fixed message.
*/
public final class IdempotencyRecoveryRequiredException extends RuntimeException
implements ApiErrorCarrier {
@@ -15,14 +15,18 @@ import java.lang.annotation.Target;
* system reaches it through a delivery or a tick. This marker is how an inbound adapter of the
* second kind says so, in code, next to the reason. Without it an inbound adapter that depends on a
* {@code @SystemInvoked} use case fails {@code ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES};
* with it, {@code SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS} checks the claim: the class
* lives in a system-driven inbound package ({@code ..adapter.inbound.messaging..}, {@code
* ..adapter.inbound.scheduler..}) and depends on no user-transport type. A controller cannot carry
* it.
* with it, {@code SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS} checks the claim on the class
* and on every class nested in it: they live in a system-driven inbound package ({@code
* ..adapter.inbound.messaging..}, {@code ..adapter.inbound.scheduler..}) and depend on no
* user-transport type. A controller cannot carry it.
*
* <p>The marked adapter constructs the use case it calls with {@code new} from the ports it is
* given and keeps it to itself: the use case is never a bean ({@code PermissionEnforcementGuard}
* refuses one), so nothing but this adapter holds it. Review 2026-11-03 RR-01-12, decision 9.1.
* refuses one), and no user transport depends on the adapter, directly or through other classes
* ({@code USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS}). The rules read class dependencies; a bean
* looked up at run time ({@code getBean}, {@code ObjectProvider}) is not seen. The three system
* callers and where each lives are listed in manual 07 「시스템이 부르는 쓰기」. Review 2026-11-03 RR-01-12,
* decision 9.1; review 2026-11-04 RR3-01-01.
*/
@Documented
@Retention(RetentionPolicy.RUNTIME)
@@ -19,13 +19,15 @@ import java.lang.annotation.Target;
* <p>A use case marked this way is a write with no permission check, so no user request may reach
* it. Its system caller constructs it directly and keeps it: a composition module hands it to a
* scheduler (the outbox relay), or a {@link SystemCaller} inbound adapter — a message handler, a
* scheduled job — constructs it from the ports its bean method receives (manual 09 「소비」 step 4).
* Both ways a user could reach it are refused: a bean of it fails startup ({@code
* composition:service-runtime} {@code PermissionEnforcementGuard}), and an inbound adapter that
* depends on it without being a {@link SystemCaller} fails the architecture rule {@code
* ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES} (review 2026-11-03 RR-01-02, RR-01-12). It is
* not a way to silence the rule that a mutating use case declares a permission: a write a user
* triggers declares one, and a write both a user and the system trigger is two use cases.
* scheduled job — constructs it from the ports its bean method receives (manual 07 「시스템이 부르는 쓰기」
* lists the three). The ways a user could reach it are refused: a bean of it fails startup ({@code
* composition:service-runtime} {@code PermissionEnforcementGuard}), an inbound adapter that depends
* on it without being a {@link SystemCaller} fails the architecture rule {@code
* ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES}, and a user transport that depends on the
* system caller fails {@code USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS} (review 2026-11-03
* RR-01-02, RR-01-12; review 2026-11-04 RR3-01-01). It is not a way to silence the rule that a
* mutating use case declares a permission: a write a user triggers declares one, and a write both a
* user and the system trigger is two use cases.
*/
@Documented
@Retention(RetentionPolicy.RUNTIME)
@@ -185,6 +185,56 @@ class IdempotencyExecutorTest {
assertThat(ran).isFalse();
}
/**
* The runbook's first step for a recovery-required answer is to find the record, and the scope
* digest is the only identity the lifecycle holds; the ERROR line of a 5xx carrier prints the
* message (re-review 2026-11-04 RR3-03-03).
*/
@ParameterizedTest(name = "{0}")
@MethodSource("recoveryRequiredStores")
@DisplayName("회복 필요로 끝나면 운영자가 기록을 찾도록 예외 메시지에 scope digest를 남긴다")
void aRecoveryRequiredFailureNamesTheScopeDigest(String path, FakeStore store) {
// when
Throwable thrown =
catchThrowable(
() ->
executor(store)
.execute(
SCOPE,
FINGERPRINT,
ATTEMPT,
() -> new IdempotentAction.Outcome.Success<>("created"),
codec()));
// then
assertThat(thrown)
.isInstanceOf(IdempotencyRecoveryRequiredException.class)
.hasMessageContaining(SCOPE.operationCode())
.hasMessageContaining(SCOPE.digest());
}
static Stream<Arguments> recoveryRequiredStores() {
FakeStore expiredExecution = new FakeStore();
expiredExecution.claim = new IdempotencyClaimOutcome.RecoveryRequired(1);
FakeStore abandonedAfterLostClaim = new FakeStore();
abandonedAfterLostClaim.claim = new IdempotencyClaimOutcome.Indeterminate(OPERATION);
abandonedAfterLostClaim.inspection =
IdempotencyInspection.outcome(IdempotencyInspectionOutcome.ABANDONED);
FakeStore conflictingReplay = startedStore();
conflictingReplay.complete = IdempotencyCompleteOutcome.INDETERMINATE;
conflictingReplay.inspectionAfterComplete =
new IdempotencyInspection(
IdempotencyInspectionOutcome.COMPLETED_REPLAY,
Optional.empty(),
Optional.empty(),
Optional.of(new StoredResponse("somebody-elses-answer")),
Optional.of(Instant.parse("2026-07-29T13:00:00Z")));
return Stream.of(
Arguments.of("claim answered recovery required", expiredExecution),
Arguments.of("lost claim found abandoned", abandonedAfterLostClaim),
Arguments.of("lost completion found someone else's", conflictingReplay));
}
/**
* The action already ran when completion fails, so "refused before the action" would be false.
* Effects in the action's own transaction roll back with the exception; anything else it did has
@@ -9,6 +9,7 @@ import dev.caskeleton.application.idempotency.IdempotencyCompleteOutcome;
import dev.caskeleton.application.idempotency.IdempotencyFailOutcome;
import dev.caskeleton.application.idempotency.IdempotencyFailureDisposition;
import dev.caskeleton.application.idempotency.IdempotencyInspection;
import dev.caskeleton.application.idempotency.IdempotencyInspectionOutcome;
import dev.caskeleton.application.idempotency.IdempotencyInspectionRequest;
import dev.caskeleton.application.idempotency.IdempotencyMutationResult;
import dev.caskeleton.application.idempotency.IdempotencyOwner;
@@ -378,6 +379,28 @@ public abstract class IdempotencyStoreContract {
.isGreaterThan(claimed.stateRevision());
}
@Test
@DisplayName("실행 중인 자기 기록을 inspect하면 기록 수명이 아니라 claim이 받은 처리 lease 만료 시각이 나온다")
void inspectingAnOwnExecutionReportsItsProcessingLeaseNotTheRecordLifetime() {
// given
// A record now outlives its lease by the replay TTL, so a store that reports when the record
// goes away reports a lease hours past the real one (re-review 2026-11-04 RR3-03-05).
IdempotencyStorePort store = subject();
IdempotencyClaimAttempt attempt = store.newClaimAttempt(OPERATION);
IdempotencyClaimOutcome.Acquired acquired =
(IdempotencyClaimOutcome.Acquired) store.claim(claim(attempt, FINGERPRINT));
store.markExecutionStarted(acquired.owner(), OPERATION);
// when
IdempotencyInspection inspection =
store.inspect(new IdempotencyInspectionRequest(SCOPE, FINGERPRINT, attempt));
// then
assertThat(inspection.outcome())
.isEqualTo(IdempotencyInspectionOutcome.EXECUTING_SAME_OPERATION);
assertThat(inspection.processingLeaseUntil()).contains(acquired.processingLeaseUntil());
}
@Test
@DisplayName("renew한 처리 lease는 처음 만료 시각이 지나도 다른 요청에 넘어가지 않는다")
void aRenewedLeaseOutlivesItsFirstExpiry() {