{@link #APPLIED}만 새로운 회계 변경이 적용되었음을 뜻합니다. 나머지 결과는 기존 상태와 + * 금액을 바꾸지 않았음을 뜻하므로 호출자는 예외 메시지나 저장소 내부 구현에 의존하지 않고 + * 재시도, 충돌 처리, 입력 보정을 결정할 수 있습니다.
+ */ +public enum AccountingTransitionStatus { + /** 요청한 회계 변경이 새로 적용되었습니다. */ + APPLIED, + + /** 같은 회계 명령과 값이 이미 적용되어 기존 결과가 재사용되었습니다. */ + REUSED, + + /** 기존에 적용된 종료 명령 또는 값이 새 요청과 충돌합니다. */ + CONFLICT, + + /** 대상 예약을 찾을 수 없습니다. */ + NOT_FOUND, + + /** 명령 금액의 통화가 예약 통화와 다릅니다. */ + CURRENCY_MISMATCH, + + /** 명령 인자가 계약을 만족하지 않습니다. */ + INVALID_ARGUMENT, + + /** 현재 예약 상태에서는 요청한 전이가 허용되지 않습니다. */ + NOT_ALLOWED; + + /** 새로운 회계 변경이 적용되었는지 반환합니다. */ + public boolean isApplied() { + return this == APPLIED; + } +} diff --git a/token-pilot-budget/src/main/java/io/tokenpilot/budget/ActualUsageCommand.java b/token-pilot-budget/src/main/java/io/tokenpilot/budget/ActualUsageCommand.java new file mode 100644 index 0000000..1b4ca84 --- /dev/null +++ b/token-pilot-budget/src/main/java/io/tokenpilot/budget/ActualUsageCommand.java @@ -0,0 +1,38 @@ +package io.tokenpilot.budget; + +import io.tokenpilot.core.domain.TokenUsage; +import io.tokenpilot.core.domain.UsageSource; + +import java.util.Objects; + +/** + * provider가 보고한 actual usage를 하나의 예약에 정산하기 위한 명령입니다. + */ +public record ActualUsageCommand( + String requestId, + String attemptId, + ReservationId reservationId, + TokenUsage usage, + String responseModelId +) { + + public ActualUsageCommand { + requestId = requireText(requestId, "requestId"); + attemptId = requireText(attemptId, "attemptId"); + Objects.requireNonNull(reservationId, "reservationId must not be null"); + Objects.requireNonNull(usage, "usage must not be null"); + if (usage.source() == UsageSource.UNAVAILABLE) { + throw new IllegalArgumentException( + "usage must be available for actual reconciliation" + ); + } + responseModelId = requireText(responseModelId, "responseModelId"); + } + + private static String requireText(String value, String name) { + if (value == null || value.isBlank()) { + throw new IllegalArgumentException(name + " must not be blank"); + } + return value; + } +} diff --git a/token-pilot-budget/src/main/java/io/tokenpilot/budget/BudgetReservation.java b/token-pilot-budget/src/main/java/io/tokenpilot/budget/BudgetReservation.java index d848ffd..443660e 100644 --- a/token-pilot-budget/src/main/java/io/tokenpilot/budget/BudgetReservation.java +++ b/token-pilot-budget/src/main/java/io/tokenpilot/budget/BudgetReservation.java @@ -1,9 +1,11 @@ package io.tokenpilot.budget; import io.tokenpilot.core.domain.Cost; +import io.tokenpilot.core.domain.PricingSnapshot; import java.time.Instant; import java.util.Objects; +import java.util.Optional; /** * 예산 bucket에 생성된 immutable 예약 snapshot입니다. @@ -13,10 +15,13 @@ public record BudgetReservation( BudgetKey key, Cost limit, Cost amount, + String requestId, IdempotencyKey idempotencyKey, String modelId, String pricingPolicyId, String catalogVersion, + Optional새 provider admission 경계는 {@link #snapshot(BudgetKey, Cost)} 또는 - * {@link #checkAndReserve(BudgetKey, Cost, Cost, String)}를 사용해야 합니다.
+ * {@link #checkAndReserve(BudgetReservationRequest)}를 사용해야 합니다. */ Cost getAccumulatedCost(BudgetKey key, Cost limit); @@ -31,7 +31,9 @@ public interface BudgetStateStore { * @param safeUpperBoundCost 예약할 보수적 비용 상한 * @param idempotencyKey 중복 요청 식별자 * @return 생성·재사용·차단·충돌·통화 불일치 결과 + * @deprecated request ID와 idempotency key를 분리하는 overload 또는 요청 객체를 사용하세요. */ + @Deprecated(since = "0.1.0", forRemoval = false) default BudgetReservationResult checkAndReserve( BudgetKey key, Cost limit, @@ -48,7 +50,10 @@ default BudgetReservationResult checkAndReserve( /** * typed idempotency key를 사용하는 원자적 예약 overload입니다. + * + * @deprecated request ID와 idempotency key를 분리하는 overload 또는 요청 객체를 사용하세요. */ + @Deprecated(since = "0.1.0", forRemoval = false) default BudgetReservationResult checkAndReserve( BudgetKey key, Cost limit, @@ -66,6 +71,29 @@ default BudgetReservationResult checkAndReserve( )); } + /** + * 요청 상관관계와 중복 방지 식별자를 분리하는 원자적 예약 overload입니다. + */ + default BudgetReservationResult checkAndReserve( + BudgetKey key, + Cost limit, + Cost safeUpperBoundCost, + String requestId, + IdempotencyKey idempotencyKey + ) { + return checkAndReserve(new BudgetReservationRequest( + key, + limit, + safeUpperBoundCost, + requestId, + idempotencyKey, + null, + null, + null, + java.util.Optional.empty() + )); + } + /** * 모델·가격 snapshot metadata를 포함한 원자적 예약 요청입니다. */ diff --git a/token-pilot-budget/src/main/java/io/tokenpilot/budget/ReservationAccounting.java b/token-pilot-budget/src/main/java/io/tokenpilot/budget/ReservationAccounting.java new file mode 100644 index 0000000..962bb8e --- /dev/null +++ b/token-pilot-budget/src/main/java/io/tokenpilot/budget/ReservationAccounting.java @@ -0,0 +1,131 @@ +package io.tokenpilot.budget; + +/** + * 예약의 회계 상태와 금액을 변경하는 단일 진입점입니다. + * + *| 명령 | + *허용 상태 | + *결과 상태 | + *금액 이동 | + *
|---|---|---|---|
| {@link #markInFlight(ReservationId)} | + *{@link ReservationState#RESERVED} | + *{@link ReservationState#IN_FLIGHT} | + *없음 | + *
| {@code release(CANCELLED_BEFORE_DISPATCH)} | + *{@link ReservationState#RESERVED} | + *{@link ReservationState#RELEASED} | + *{@code activeReservedCost -= estimate} | + *
| {@code release(PROVIDER_CONFIRMED_UNBILLED)} | + *{@link ReservationState#IN_FLIGHT} | + *{@link ReservationState#RELEASED} | + *{@code activeReservedCost -= estimate} | + *
| {@link #commit(ActualUsageCommand)} | + *{@link ReservationState#IN_FLIGHT} | + *{@link ReservationState#COMMITTED} | + *{@code activeReservedCost -= estimate; committedCost += actual} | + *
| {@link #markReconciliationRequired(ReservationId, ReservationAccountingReason)} | + *{@link ReservationState#IN_FLIGHT} | + *{@link ReservationState#RECONCILIATION_REQUIRED} | + *{@code activeReservedCost -= estimate; pendingReconciliationLiability += estimate} | + *
| {@link #reconcileLateActual(ActualUsageCommand)} | + *{@link ReservationState#RECONCILIATION_REQUIRED} | + *{@link ReservationState#COMMITTED} | + *{@code pendingReconciliationLiability -= estimate; committedCost += actual} | + *
| {@link #writeOff(ReservationId, ReservationAccountingReason)} | + *{@link ReservationState#RECONCILIATION_REQUIRED} | + *{@link ReservationState#WRITTEN_OFF} | + *{@code pendingReconciliationLiability -= estimate} | + *
표의 전이가 새로 적용되면 {@link AccountingTransitionStatus#APPLIED}입니다. + * 동일한 종료 명령과 값 또는 정산 대기 명령의 재호출은 상태와 금액을 유지하고 + * {@link AccountingTransitionStatus#REUSED}, 다른 actual 또는 상충하는 종료 명령은 + * {@link AccountingTransitionStatus#CONFLICT}입니다. 아직 종료 명령이 적용되지 않았지만 + * 현재 상태가 표의 허용 상태가 아니면 {@link AccountingTransitionStatus#NOT_ALLOWED}입니다.
+ * + *존재하지 않는 예약과 명령에 허용되지 않은 reason은 상태를 변경하기 전에 + * {@link IllegalArgumentException}으로 거부합니다. 모든 상태와 금액 변경은 같은 budget + * bucket의 임계 구역 안에서 함께 적용됩니다.
+ */ +public interface ReservationAccounting { + + /** 예약을 사용한 provider 호출 시작을 기록합니다. */ + ReservationTransition markInFlight(ReservationId reservationId); + + /** provider 호출 전에 사용하지 않은 예약을 해제합니다. */ + default ReservationTransition releaseBeforeDispatch(ReservationId reservationId) { + return release( + reservationId, + ReservationAccountingReason.CANCELLED_BEFORE_DISPATCH + ); + } + + /** provider가 미과금을 확인한 진행 중 예약을 해제합니다. */ + default ReservationTransition releaseConfirmedUnbilled(ReservationId reservationId) { + return release( + reservationId, + ReservationAccountingReason.PROVIDER_CONFIRMED_UNBILLED + ); + } + + ReservationTransition release( + ReservationId reservationId, + ReservationAccountingReason reason + ); + + /** provider actual usage를 예약 시점 가격으로 계산하여 확정합니다. */ + ReservationReconciliation commit(ActualUsageCommand command); + + /** actual을 확보하지 못한 예약을 정산 대기로 전환합니다. */ + default ReservationTransition markReconciliationRequired( + ReservationId reservationId + ) { + return markReconciliationRequired( + reservationId, + ReservationAccountingReason.ACTUAL_USAGE_UNAVAILABLE + ); + } + + ReservationTransition markReconciliationRequired( + ReservationId reservationId, + ReservationAccountingReason reason + ); + + /** 늦게 도착한 provider actual usage를 예약 시점 가격으로 계산하여 확정합니다. */ + ReservationReconciliation reconcileLateActual(ActualUsageCommand command); + + /** 후속 정산할 수 없는 pending 예약을 명시적으로 상각합니다. */ + default ReservationTransition writeOff(ReservationId reservationId) { + return writeOff( + reservationId, + ReservationAccountingReason.MANUAL_WRITE_OFF + ); + } + + ReservationTransition writeOff( + ReservationId reservationId, + ReservationAccountingReason reason + ); +} diff --git a/token-pilot-budget/src/main/java/io/tokenpilot/budget/ReservationAccountingEvent.java b/token-pilot-budget/src/main/java/io/tokenpilot/budget/ReservationAccountingEvent.java new file mode 100644 index 0000000..00438d9 --- /dev/null +++ b/token-pilot-budget/src/main/java/io/tokenpilot/budget/ReservationAccountingEvent.java @@ -0,0 +1,16 @@ +package io.tokenpilot.budget; + +import java.util.Objects; + +/** 새롭게 적용된 예약 정산을 전달하는 회계 이벤트입니다. */ +public record ReservationAccountingEvent( + ReservationReconciliation reconciliation +) { + + public ReservationAccountingEvent { + Objects.requireNonNull( + reconciliation, + "reconciliation must not be null" + ); + } +} diff --git a/token-pilot-budget/src/main/java/io/tokenpilot/budget/ReservationAccountingListener.java b/token-pilot-budget/src/main/java/io/tokenpilot/budget/ReservationAccountingListener.java new file mode 100644 index 0000000..57d206b --- /dev/null +++ b/token-pilot-budget/src/main/java/io/tokenpilot/budget/ReservationAccountingListener.java @@ -0,0 +1,8 @@ +package io.tokenpilot.budget; + +/** 예약 정산 이벤트를 수신하는 framework-independent 계약입니다. */ +@FunctionalInterface +public interface ReservationAccountingListener { + + void onCommitted(ReservationAccountingEvent event); +} diff --git a/token-pilot-budget/src/main/java/io/tokenpilot/budget/ReservationAccountingReason.java b/token-pilot-budget/src/main/java/io/tokenpilot/budget/ReservationAccountingReason.java new file mode 100644 index 0000000..af50e02 --- /dev/null +++ b/token-pilot-budget/src/main/java/io/tokenpilot/budget/ReservationAccountingReason.java @@ -0,0 +1,13 @@ +package io.tokenpilot.budget; + +/** 회계 명령과 정산 결과에 사용하는 제한된 사유입니다. */ +public enum ReservationAccountingReason { + ACTUAL_USAGE_REPORTED, + LATE_ACTUAL_USAGE_REPORTED, + ACTUAL_USAGE_UNAVAILABLE, + CALLBACK_TIMED_OUT, + CANCELLED_BEFORE_DISPATCH, + PROVIDER_CONFIRMED_UNBILLED, + MANUAL_WRITE_OFF, + ACTUAL_USAGE_UNRECOVERABLE +} diff --git a/token-pilot-budget/src/main/java/io/tokenpilot/budget/ReservationActualTokens.java b/token-pilot-budget/src/main/java/io/tokenpilot/budget/ReservationActualTokens.java new file mode 100644 index 0000000..d5e377b --- /dev/null +++ b/token-pilot-budget/src/main/java/io/tokenpilot/budget/ReservationActualTokens.java @@ -0,0 +1,45 @@ +package io.tokenpilot.budget; + +import io.tokenpilot.core.domain.TokenUsage; +import io.tokenpilot.core.domain.TokenUsageDetails; +import io.tokenpilot.core.domain.UsageSource; + +import java.util.Map; +import java.util.Objects; + +/** Provider actual usage에서 무제한 metadata를 제외한 회계용 token 결과입니다. */ +public record ReservationActualTokens( + long inputTokens, + long outputTokens, + TokenUsageDetails details, + UsageSource source +) { + + public ReservationActualTokens { + if (inputTokens < 0 || outputTokens < 0) { + throw new IllegalArgumentException("actual tokens must be non-negative"); + } + Objects.requireNonNull(details, "details must not be null"); + Objects.requireNonNull(source, "source must not be null"); + if (source == UsageSource.UNAVAILABLE) { + throw new IllegalArgumentException( + "actual token source must be available" + ); + } + new TokenUsage(inputTokens, outputTokens, details, source, Map.of()); + } + + public static ReservationActualTokens from(TokenUsage usage) { + Objects.requireNonNull(usage, "usage must not be null"); + return new ReservationActualTokens( + usage.inputTokens(), + usage.outputTokens(), + usage.details(), + usage.source() + ); + } + + public long totalTokens() { + return Math.addExact(inputTokens, outputTokens); + } +} diff --git a/token-pilot-budget/src/main/java/io/tokenpilot/budget/ReservationReconciliation.java b/token-pilot-budget/src/main/java/io/tokenpilot/budget/ReservationReconciliation.java new file mode 100644 index 0000000..be34bea --- /dev/null +++ b/token-pilot-budget/src/main/java/io/tokenpilot/budget/ReservationReconciliation.java @@ -0,0 +1,107 @@ +package io.tokenpilot.budget; + +import io.tokenpilot.core.domain.Cost; +import io.tokenpilot.core.domain.PricingSnapshot; + +import java.math.BigDecimal; +import java.util.Currency; +import java.util.Objects; + +/** + * 한 예약의 estimate와 actual 비용을 연결한 회계 정산 결과입니다. + */ +public record ReservationReconciliation( + String requestId, + String attemptId, + ReservationId reservationId, + BudgetKey budgetKey, + String responseModelId, + PricingSnapshot pricingSnapshot, + ReservationTokenEstimate tokenEstimate, + ReservationActualTokens actualTokens, + Cost estimate, + Cost actual, + boolean overLimit, + ReservationTransition transition, + ReservationAccountingReason reason +) { + + public ReservationReconciliation { + requestId = requireText(requestId, "requestId"); + attemptId = requireText(attemptId, "attemptId"); + Objects.requireNonNull(reservationId, "reservationId must not be null"); + Objects.requireNonNull(budgetKey, "budgetKey must not be null"); + responseModelId = requireText(responseModelId, "responseModelId"); + Objects.requireNonNull(pricingSnapshot, "pricingSnapshot must not be null"); + Objects.requireNonNull(tokenEstimate, "tokenEstimate must not be null"); + Objects.requireNonNull(actualTokens, "actualTokens must not be null"); + Objects.requireNonNull(estimate, "estimate must not be null"); + Objects.requireNonNull(actual, "actual must not be null"); + Objects.requireNonNull(transition, "transition must not be null"); + Objects.requireNonNull(reason, "reason must not be null"); + if (!estimate.currency().equals(actual.currency())) { + throw new IllegalArgumentException( + "estimate and actual must use the same currency" + ); + } + if (!estimate.currency().equals(pricingSnapshot.currency())) { + throw new IllegalArgumentException( + "reconciliation costs must use the pricing snapshot currency" + ); + } + } + + /** 예약 시점 pricing snapshot의 request model입니다. */ + public String requestModelId() { + return pricingSnapshot.modelId(); + } + + /** 예약 시점 pricing policy 식별자입니다. */ + public String pricingPolicyId() { + return pricingSnapshot.pricingPolicyId(); + } + + /** 예약 시점 model catalog version입니다. */ + public String catalogVersion() { + return pricingSnapshot.catalogVersion(); + } + + /** actual에서 estimate를 뺀 signed 비용 차이입니다. */ + public BigDecimal delta() { + return actual.value().subtract(estimate.value()); + } + + public long inputTokenDelta() { + return Math.subtractExact( + actualTokens.inputTokens(), + tokenEstimate.inputEstimatedTokens() + ); + } + + public long outputTokenDelta() { + return Math.subtractExact( + actualTokens.outputTokens(), + tokenEstimate.reservedOutputTokens() + ); + } + + public long totalTokenDelta() { + long estimatedTotal = Math.addExact( + tokenEstimate.inputEstimatedTokens(), + tokenEstimate.reservedOutputTokens() + ); + return Math.subtractExact(actualTokens.totalTokens(), estimatedTotal); + } + + /** estimate와 actual이 사용하는 통화입니다. */ + public Currency currency() { + return actual.currency(); + } + + private static String requireText(String value, String name) { + if (value == null || value.isBlank()) { + throw new IllegalArgumentException(name + " must not be blank"); + } + return value; + } +} diff --git a/token-pilot-budget/src/main/java/io/tokenpilot/budget/ReservationState.java b/token-pilot-budget/src/main/java/io/tokenpilot/budget/ReservationState.java index 3a1a2cf..4a1cd07 100644 --- a/token-pilot-budget/src/main/java/io/tokenpilot/budget/ReservationState.java +++ b/token-pilot-budget/src/main/java/io/tokenpilot/budget/ReservationState.java @@ -2,9 +2,32 @@ /** * 예산 예약의 현재 회계 상태입니다. - * - *commit/release/reconciliation 상태 전이는 #37에서 확장합니다.
*/ public enum ReservationState { - RESERVED + /** 안전 상한액이 예약되었지만 공급자 호출은 시작되지 않은 상태입니다. */ + RESERVED, + + /** 예약을 사용해 공급자 호출이 진행 중인 상태입니다. */ + IN_FLIGHT, + + /** 실제 사용량을 알 수 없어 후속 정산이 필요한 상태입니다. */ + RECONCILIATION_REQUIRED, + + /** 실제 사용 금액이 확정된 종료 상태입니다. */ + COMMITTED, + + /** 사용되지 않은 예약 금액이 해제된 종료 상태입니다. */ + RELEASED, + + /** 실제 사용량을 끝내 확정할 수 없어 정책에 따라 상각된 종료 상태입니다. */ + WRITTEN_OFF; + + /** + * 더 이상 정상적인 회계 전이를 허용하지 않는 종료 상태인지 반환합니다. + * + *{@link #RECONCILIATION_REQUIRED}는 후속 정산을 기다리는 상태이므로 종료 상태가 아닙니다.
+ */ + public boolean isClosed() { + return this == COMMITTED || this == RELEASED || this == WRITTEN_OFF; + } } diff --git a/token-pilot-budget/src/main/java/io/tokenpilot/budget/ReservationStateMachine.java b/token-pilot-budget/src/main/java/io/tokenpilot/budget/ReservationStateMachine.java new file mode 100644 index 0000000..812b575 --- /dev/null +++ b/token-pilot-budget/src/main/java/io/tokenpilot/budget/ReservationStateMachine.java @@ -0,0 +1,94 @@ +package io.tokenpilot.budget; + +import java.util.Objects; + +/** + * 예약의 회계 상태 전이 가능 여부를 판단합니다. + */ +public final class ReservationStateMachine { + + private ReservationStateMachine() { + } + + /** 예약된 요청의 공급자 호출을 시작합니다. */ + public static ReservationTransition onDispatch(ReservationState currentState) { + return transitionFrom( + currentState, + ReservationState.RESERVED, + ReservationState.IN_FLIGHT + ); + } + + /** 공급자 호출 전에 예약을 해제합니다. */ + public static ReservationTransition release(ReservationState currentState) { + return transitionFrom( + currentState, + ReservationState.RESERVED, + ReservationState.RELEASED + ); + } + + /** 공급자가 미과금을 확인한 진행 중 예약을 해제합니다. */ + public static ReservationTransition releaseConfirmedUnbilled( + ReservationState currentState + ) { + return transitionFrom( + currentState, + ReservationState.IN_FLIGHT, + ReservationState.RELEASED + ); + } + + /** 전달받은 actual을 확정하기 위한 상태 전이를 판단합니다. */ + public static ReservationTransition commit(ReservationState currentState) { + return transitionFrom( + currentState, + ReservationState.IN_FLIGHT, + ReservationState.COMMITTED + ); + } + + /** actual을 전달받지 못한 예약을 정산 대기로 전환할 수 있는지 판단합니다. */ + public static ReservationTransition markReconciliationRequired(ReservationState currentState) { + return transitionFrom( + currentState, + ReservationState.IN_FLIGHT, + ReservationState.RECONCILIATION_REQUIRED + ); + } + + /** 정산 대기 중 전달받은 late actual을 확정할 수 있는지 판단합니다. */ + public static ReservationTransition reconcileLateActual(ReservationState currentState) { + return transitionFrom( + currentState, + ReservationState.RECONCILIATION_REQUIRED, + ReservationState.COMMITTED + ); + } + + /** 정산 대기 중인 예약을 명시적으로 상각합니다. */ + public static ReservationTransition writeOff(ReservationState currentState) { + return transitionFrom( + currentState, + ReservationState.RECONCILIATION_REQUIRED, + ReservationState.WRITTEN_OFF + ); + } + + private static ReservationTransition transitionFrom( + ReservationState currentState, + ReservationState requiredState, + ReservationState resultingState + ) { + Objects.requireNonNull(currentState, "currentState must not be null"); + + if (currentState == requiredState) { + return ReservationTransition.applied(currentState, resultingState); + } + + return ReservationTransition.unchanged( + currentState, + AccountingTransitionStatus.NOT_ALLOWED + ); + } +} diff --git a/token-pilot-budget/src/main/java/io/tokenpilot/budget/ReservationTokenEstimate.java b/token-pilot-budget/src/main/java/io/tokenpilot/budget/ReservationTokenEstimate.java new file mode 100644 index 0000000..3e59e05 --- /dev/null +++ b/token-pilot-budget/src/main/java/io/tokenpilot/budget/ReservationTokenEstimate.java @@ -0,0 +1,22 @@ +package io.tokenpilot.budget; + +/** 예약 비용의 근거가 된 호출 전 token estimate입니다. */ +public record ReservationTokenEstimate( + long inputEstimatedTokens, + long inputSafeUpperBoundTokens, + long reservedOutputTokens +) { + + public ReservationTokenEstimate { + if (inputEstimatedTokens < 0 + || inputSafeUpperBoundTokens < 0 + || reservedOutputTokens < 0) { + throw new IllegalArgumentException("estimated tokens must be non-negative"); + } + if (inputSafeUpperBoundTokens < inputEstimatedTokens) { + throw new IllegalArgumentException( + "inputSafeUpperBoundTokens must be greater than or equal to inputEstimatedTokens" + ); + } + } +} diff --git a/token-pilot-budget/src/main/java/io/tokenpilot/budget/ReservationTransition.java b/token-pilot-budget/src/main/java/io/tokenpilot/budget/ReservationTransition.java new file mode 100644 index 0000000..ed66bc0 --- /dev/null +++ b/token-pilot-budget/src/main/java/io/tokenpilot/budget/ReservationTransition.java @@ -0,0 +1,44 @@ +package io.tokenpilot.budget; + +import java.util.Objects; + +/** + * 예약의 상태 전이 판단입니다. + */ +public record ReservationTransition( + ReservationState previousState, + ReservationState resultingState, + AccountingTransitionStatus status +) { + + public ReservationTransition { + Objects.requireNonNull(previousState, "previousState must not be null"); + Objects.requireNonNull(resultingState, "resultingState must not be null"); + Objects.requireNonNull(status, "status must not be null"); + + boolean stateChanged = previousState != resultingState; + if (status.isApplied() != stateChanged) { + throw new IllegalArgumentException( + "APPLIED must change reservation state and all other statuses must preserve it" + ); + } + } + + public static ReservationTransition applied( + ReservationState previousState, + ReservationState resultingState + ) { + return new ReservationTransition( + previousState, + resultingState, + AccountingTransitionStatus.APPLIED + ); + } + + public static ReservationTransition unchanged( + ReservationState state, + AccountingTransitionStatus status + ) { + return new ReservationTransition(state, state, status); + } +} diff --git a/token-pilot-budget/src/main/java/io/tokenpilot/budget/internal/ActualUsageFingerprint.java b/token-pilot-budget/src/main/java/io/tokenpilot/budget/internal/ActualUsageFingerprint.java new file mode 100644 index 0000000..2f08d41 --- /dev/null +++ b/token-pilot-budget/src/main/java/io/tokenpilot/budget/internal/ActualUsageFingerprint.java @@ -0,0 +1,28 @@ +package io.tokenpilot.budget.internal; + +import io.tokenpilot.budget.ActualUsageCommand; +import io.tokenpilot.budget.ReservationActualTokens; +import io.tokenpilot.budget.ReservationId; + +/** 중복 actual callback을 민감하거나 무제한인 metadata 없이 식별합니다. */ +record ActualUsageFingerprint( + String requestId, + String attemptId, + ReservationId reservationId, + ReservationActualTokens actualTokens, + String responseModelId +) { + + static ActualUsageFingerprint from( + ActualUsageCommand command, + ReservationActualTokens actualTokens + ) { + return new ActualUsageFingerprint( + command.requestId(), + command.attemptId(), + command.reservationId(), + actualTokens, + command.responseModelId() + ); + } +} diff --git a/token-pilot-budget/src/main/java/io/tokenpilot/budget/internal/AppliedCommit.java b/token-pilot-budget/src/main/java/io/tokenpilot/budget/internal/AppliedCommit.java new file mode 100644 index 0000000..5e4c937 --- /dev/null +++ b/token-pilot-budget/src/main/java/io/tokenpilot/budget/internal/AppliedCommit.java @@ -0,0 +1,94 @@ +package io.tokenpilot.budget.internal; + +import io.tokenpilot.budget.AccountingTransitionStatus; +import io.tokenpilot.budget.ReservationState; +import io.tokenpilot.budget.ReservationTransition; +import io.tokenpilot.core.domain.Cost; + +import java.util.Objects; +import java.util.Optional; + +import static io.tokenpilot.budget.AccountingTransitionStatus.CONFLICT; +import static io.tokenpilot.budget.AccountingTransitionStatus.REUSED; + +/** + * 이미 적용된 commit의 종류, actual과 재호출 판단을 보관합니다. + */ +record AppliedCommit( + CommitType type, + Cost actualCost, + boolean overLimit, + Optionalbucket별 monitor가 조회·통화 검증·한도 검증·예약 갱신을 함께 보호하고, * 별도의 idempotency index가 같은 요청의 중복 예약을 차단합니다.
*/ -public class InMemoryBudgetStateStore implements BudgetStateStore { +public class InMemoryBudgetStateStore implements BudgetStateStore, ReservationAccounting { private final ConcurrentMap