---
kind: CASE
slug: messaging-admin-runtime-f06
title: 저널의 itemsCompleted 단조성이 인터페이스 계약에 없다
topic: state-ownership-and-concurrency
project: clean-architecture-backend-template
status: 게시 전
sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
rootTreeNode: case:messaging-admin-runtime-f06
evidenceCapturedOn: 2026-09-01
assets:
  - key: messaging-admin-runtime-f06
    file: ../../../final/evidence/rendered/messaging-admin-runtime-f06.svg
evidence:
  - ../../../final/evidence/raw/messaging-admin-runtime-f06.txt
source:
  - 원본 분석 절은 analysis/messaging/messaging-admin-runtime.md#L936 이다.
module: messaging-admin-runtime
priority: P3
---

# 저널의 itemsCompleted 단조성이 인터페이스 계약에 없다

AdminOperationJournal javadoc 은 구현 의무 셋을 명시하면서 이것을 빠뜨렸고, fail 의 @param 은 오히려 문자 그대로 저장하라고 읽힌다. 유일한 호출자는 낡은 값을 넘긴다.

## 문제

AdminOperationJournal javadoc 은 구현 의무 셋을 명시하면서 이것을 빠뜨렸고, fail 의 @param 은 오히려 문자 그대로 저장하라고 읽힌다.

유일한 호출자는 낡은 값을 넘긴다.

## 결론

두 구현이 각각 clamp 해서 무사한 상태다(EVD-308).

두 가지 중 하나가 필요하다.

인터페이스 javadoc 에 "itemsCompleted 는 단조 증가해야 하며 구현은 기존 값보다 작은 값을 무시한다" 를 명시하거나, 호출자가 실제 체크포인트 값을 넘기도록 고친다.

후자가 더 정직하다 — 지금 journal.fail(lease, lease.resumeFrom(), …) 은 "이번 시도가 아무것도 못 했다" 고 주장하는 것이고, 그것은 대개 사실이 아니다.

## 검증 환경

OpenJDK : 21.0.12   java -version 으로 확인
Gradle : 9.0.0      src/gradle/wrapper/gradle-wrapper.properties 의 distributionUrl 로 확인
확인 방식 : AdminOperationJournal 참조 30건 검색과 javadoc 의 구현 의무 목록·유일한 호출자가 넘기는 값 확인
소스 수정 : x

## 재현 조건

원문은 analysis/messaging/messaging-admin-runtime.md#L936 에 있다.

## 본문

<!-- body:start -->

`AdminOperationJournal` javadoc 은 구현 의무 셋을 명시하면서 `itemsCompleted` 단조성을 빠뜨렸고, `fail` 의 `@param` 은 오히려 문자 그대로 저장하라고 읽힌다.

## AdminOperationJournal 참조 위치

:::evidence key="messaging-admin-runtime-f06" alt="코드베이스에서 AdminOperationJournal 를 검색한 출력 30줄. 이 기록이 세는 참조가 그 출력에 그대로 보인다." caption="AdminOperationJournal 코드베이스 검색 — 30줄 · exit 0" zoom="true"
:::

## 유일한 호출자가 낡은 값을 넘긴다

두 구현이 각각 clamp 해서 무사한 상태다(`EVD-308`).

## 두 가지 중 하나가 필요하다

인터페이스 javadoc 에 "`itemsCompleted` 는 단조 증가해야 하며 구현은 기존 값보다 작은 값을 무시한다" 를 명시하거나, 호출자가 실제 체크포인트 값을 넘기도록 고친다. 후자가 더 정직하다 — 지금 `journal.fail(lease, lease.resumeFrom(), …)` 은 "이번 시도가 아무것도 못 했다" 고 주장하는 것이고, 그것은 대개 사실이 아니다.

## 확인하지 못한 것

JdbcAdminOperationJournal 의 실제 동작을 확인하지 않았다. Postgres 컨테이너가 필요하고 미실행이다. SQL 문자열은 읽어 GREATEST 를 확인했다.

<!-- body:end -->