document-haness/docs/clean-architecture-backend-template/tech-log-studio/state-machines-and-ownership/case/case-a05-f020-inspect-claim.md

kind, slug, title, topic, project, status, sourceRevision, rootTreeNode, evidenceCapturedOn, assets, evidence, source

kind	slug	title	topic	project	status	sourceRevision	rootTreeNode	evidenceCapturedOn	assets	evidence	source
CASE	a05-f020-inspect-claim	만료를 보는 청구와 시각을 읽지 않는 조회가 같은 행을 다르게 답한다	state-machines-and-ownership	clean-architecture-backend-template	게시 전	21234e38cdb9a926cbc92bb97a2aee2e4a7d2916	case:a05-f020-inspect-claim	2026-09-02	key file a05-f020-inspect-claim ../../../final/evidence/rendered/a05-f020-inspect-claim.svg key file a05-f020-inspect-claim-postgres ../../../final/evidence/rendered/a05-f020-inspect-claim-postgres.svg	../../../final/evidence/raw/a05-f020-inspect-claim.txt ../../../final/evidence/raw/a05-f020-inspect-claim-postgres.txt	원본 분석 절은 `final/document.md#a05` §59.1 이다. 두 경로가 만료된 완료 행을 다르게 해석한다는 판정과 그 실행 탐침 값이 그 절에 있다. 같은 §59 의 나머지 한 군데는 §59.2 이고 별도 사례가 담당한다. 소비자 세 자리의 분기별 동작과 시험 범위, 레디스 구현과의 대조는 이 기록에서 확인했다.

만료를 보는 청구와 시각을 읽지 않는 조회가 같은 행을 다르게 답한다

멱등성 저장소의 청구 경로는 행을 잠근 뒤 데이터베이스 시각을 읽어 재생 유효 기간이 지난 완료 행을 인계로 보낸다. 조회 경로는 그 시각을 한 번도 읽지 않고 완료 상태에 응답이 있으면 재생으로 답한다. 실제 PostgreSQL 에서 만료 뒤 같은 행에 두 답이 나온다.

관계

• 만료된 claim과 만료된 실행은 다르게 다뤄야 한다 같은 상태 기계의 만료 처리 규칙이다.
• 시간은 DB에서, 그리고 행을 잠근 다음에 읽는다 두 경로가 같은 시각 기준을 써야 하는 이유다.
• 전이 다섯 중 넷은 공용 판정을 쓰고 완료만 손으로 비교한다 같은 분석 절이 짚은 나머지 한 군데 재생 경계다.

문제

멱등성 저장소에는 두 진입 경로가 있다. 조회는 이 연산이 이미 처리됐는지 묻고, 청구는 지금 처리해도 되는지 묻는다.

같은 행에 대한 두 답이 갈리면 어느 쪽을 믿을지 정하는 규칙이 코드에 없다.

결론

청구가 데이터베이스 시각을 읽는 것은 행을 잠근 다음이고 한 번뿐이다. 그 시각으로 완료 상태이면서 재생 유효 기간이 지난 행을 먼저 걸러 인계로 보내고, 그 검사가 재생 응답 분기보다 앞에 있다.

조회 쪽에는 그 호출이 없다. replayUntil 은 응답에 실려 나갈 뿐 어디에서도 읽히지 않는다. 만료를 비교하는 헬퍼가 하나 있고, 그것을 부르는 것은 청구뿐이다. 조회가 쓰는 조회 SQL 에도 시간 술어가 없다.

실제 PostgreSQL 16 에 이 리프의 마이그레이션을 적용하고 재생 유효 기간 2초로 완료했다. 만료 시각 전 조회는 재생으로 답하고, 만료 뒤 조회도 같은 답과 같은 옛 응답을 준다. 같은 행을 다시 청구하면 인계가 돌아온다.

멱등성 실행기는 조회의 재생 결과를 세 곳에서 받고, 셋 다 청구나 시작이나 완료가 불확정으로 끝난 뒤의 복구 경로다. 그중 둘은 저장된 응답을 그대로 돌려주고 행동을 실행하지 않는다. 그 둘에서 만료가 소비자에게 번진다.

나머지 하나는 저장된 응답을 호출자가 방금 만든 결과와 비교하고 다르면 던진다. 그 경로는 호출자가 이미 실행한 뒤에만 닿고 돌려주는 값도 자기 결과이므로 이 문제가 번지지 않는다.

재생 창 만료를 짚는 시험은 없다. 통합 시험에 이름이 만료인 시험이 둘 있지만 둘 다 처리 임차를 25밀리초로 몰아 만든 것이고, 그 파일의 요청 헬퍼는 재생 유효 기간을 언제나 24시간으로 고정한다.

같은 계약의 레디스 구현에는 이 비교가 없다. 완료가 키에 재생 유효 기간을 그대로 만료로 걸어서, 창이 끝나면 해시가 사라지고 조회는 부재로 답한다.

검증 환경

OpenJDK : 21.0.12 데이터베이스 : PostgreSQL 16.15, 실제 실행 확인 방식 : 두 경로의 시각 참조 계수, 실제 PostgreSQL 에 마이그레이션 적용 후 만료 전후 호출, 소비자 세 자리 추적 소스 수정 : x

재현 조건

1. 청구 경로에서 데이터베이스 시각을 읽는 줄과 만료 판정 헬퍼를 찾고, 그것이 재생 응답 분기보다 앞인지 본다.
2. 조회 경로 전문에서 데이터베이스 시각 호출을 세고, replayUntil 이 어디에 쓰이는지 본다.
3. 조회가 쓰는 조회 SQL 에 시간 술어가 있는지 본다.
4. 실제 PostgreSQL 에 이 리프의 마이그레이션을 적용하고, 짧은 재생 유효 기간으로 완료한 뒤 만료 전후로 조회와 청구를 부른다.
5. 조회의 재생 결과를 받는 세 자리가 각각 무엇을 하는지 읽는다.
6. 통합 시험의 만료 시험이 무엇을 만료시키는지, 요청 헬퍼의 재생 유효 기간이 무엇인지 본다.

본문

청구는 행을 잠근 뒤 데이터베이스 시각을 한 번 읽는다. 조회는 그 호출이 0 이다.

청구는 만료를 먼저 본다

:::evidence key="a05-f020-inspect-claim" alt="청구 경로가 데이터베이스 시각을 읽고 만료된 완료 행을 먼저 걸러 내는 구간과 그 판정 헬퍼, 청구 본문의 시각 참조 수, 조회 경로 전문과 그 본문의 시각 참조 수와 replayUntil 이 쓰이는 자리, 만료 비교 헬퍼를 부르는 곳, 조회가 쓰는 조회 SQL, 조회 결과를 받는 세 자리, 그리고 출하 통합 시험의 만료 시험이 무엇을 만료시키는지와 요청 헬퍼의 재생 유효 기간을 출력한 터미널 기록." caption="청구는 databaseNow 1회와 만료 선분기 · 조회는 시각 0회, replayUntil 은 생성자 인자로만 · 만료 비교 헬퍼는 청구만 호출 · 조회 SQL 에 시간 술어 없음 · 만료 시험 둘은 처리 임차, 재생 창은 늘 24시간 — 95줄 · exit 0" zoom="true" :::

Instant dbNow = rows.databaseNow();
...
if (isExpiredCompleted(row, dbNow)) {
  return resetClaim(request, row);
}
...
if (row.state() == IdempotencyState.COMPLETED && row.replayUntil() != null) {
  return new IdempotencyClaimOutcome.CompletedReplay(
      new StoredResponse(row.responsePayload()), row.replayUntil());
}

만료 판정이 재생 응답 분기보다 앞에 있다.

조회는 만료된 완료 행도 재생으로 답한다

if (row.state() == IdempotencyState.COMPLETED && row.responsePayload() != null) {
  return new IdempotencyInspection(
      IdempotencyInspectionOutcome.COMPLETED_REPLAY,
      ...
      Optional.ofNullable(row.replayUntil()));
}

replayUntil 은 응답 생성자에 한 번 실려 나갈 뿐 비교되지 않는다. 만료 비교를 하는 헬퍼는 이 파일에 하나뿐이고 청구만 부른다. 조회가 쓰는 조회 SQL 도 범위 해시와 레코드 버전만 술어로 쓴다.

실제 PostgreSQL 에서 두 답이 갈린다

:::evidence key="a05-f020-inspect-claim-postgres" alt="실제 PostgreSQL 컨테이너를 세우고 이 리프의 마이그레이션 세 스트림을 적용해 만들어진 테이블 목록, 그리고 재생 유효 기간 2초로 완료한 뒤 저장된 만료 시각과 만료 전 조회 결과, 만료 뒤 조회 결과와 그때 돌아온 응답, 같은 행에 대한 청구 결과를 출력한 터미널 기록." caption="PostgreSQL 16.15 에 마이그레이션 적용 · 재생 창 2초로 완료 · 만료 전 조회는 재생 · 만료 뒤 조회도 재생과 옛 응답 · 같은 행의 청구는 인계 — 12줄 · exit 0" zoom="true" :::

replay_until  : 2026-09-02 04:35:51.753222+00
지금          : 2026-09-02 04:35:49.768587+00
만료 전 조회  : COMPLETED_REPLAY
지금          : 2026-09-02 04:35:53.285753+00
만료 후 조회  : COMPLETED_REPLAY  응답={"v":"OLD-RESPONSE"}
만료 후 청구  : TakenOverClaimed

만료 시각을 지난 뒤에도 조회는 같은 답과 같은 옛 응답을 준다. 같은 행에 대한 청구는 인계를 돌려준다.

조회 결과를 그대로 돌려주는 두 자리

멱등성 실행기는 조회의 재생 결과를 세 곳에서 받는다. 모두 청구나 시작이나 완료가 불확정으로 끝난 뒤의 복구 경로다. 그중 둘은 저장된 응답을 그대로 돌려준다.

case COMPLETED_REPLAY -> codec.deserialize(requireResponse(inspection).payload());

두 경로 모두 행동을 실행하지 않는다. 그래서 재생 유효 기간이 지나 청구라면 인계했을 행에서도, 청구나 시작이 불확정으로 끝난 호출자는 만료된 이전 응답을 자기 답으로 받는다.

세 번째는 다르다.

StoredResponse stored = requireResponse(inspection);
if (stored.payload().equals(codec.serialize(result))) {
  yield result;
}
throw recovery("the completed response conflicts with the one this caller produced");

이 경로는 호출자가 이미 행동을 실행한 뒤에만 닿고, 돌려주는 값도 저장된 응답이 아니라 호출자 자신의 결과다. 만료가 번지는 자리는 앞의 둘이다.

재생 창 만료를 짚는 시험은 없다

통합 시험에 이름이 만료인 시험이 둘 있다. 만료된 청구를 인계하되 낡은 소유자는 시작하지 못한다는 것과, 만료된 실행 중 행은 조정을 요구한다는 것이다.

둘 다 처리 임차를 25밀리초로 몰아 만든 것이고, 그 파일의 요청 헬퍼는 재생 유효 기간을 언제나 24시간으로 고정한다. 만료 판정 헬퍼가 참이 되는 분기는 이 파일의 어느 시험도 밟지 않는다.

조회는 그 파일 전체에서 한 번 불리고, 포기 상태를 확인한다.

같은 계약의 레디스 구현에는 이 비교가 없다

완료가 키에 재생 유효 기간을 그대로 만료로 건다. JPA 쪽이 완료 SQL 에서 replay_until 로 적는 값과 같은 값이다. 창이 끝나면 해시가 사라지고 조회는 부재로 답한다.

시작과 갱신은 만료를 건드리지 않고, 실패 표시는 보존 기간을 건다.

고칠 방향

조회도 청구와 같은 데이터베이스 시각 기준을 써야 한다. 그리고 재생 유효 기간이 지난 뒤 조회가 무엇을 답하는지 고정하는 경계 시험이 있어야 한다.

확인하지 못한 것

두 답이 공존하는 창이 얼마나 지속되는지는 재지 않았다. 탐침에서 인계가 끝나면 조회는 다른 답으로 바뀌므로, 갈림은 먼저 도는 쪽이 상태를 바꿀 때까지다.