[ADR] TokenUsage와 Money 불변식 및 정밀도 정책 정의

[HuitaePark]

목적

#22와 PR #23에서 구현한 TokenUsage 의미를 문서 계약으로 고정하고, #26 이후의 pricing/budget/accounting 구현이 따라야 할 Money 계약을 확정한다.

산출물

TokenUsage ADR — 구현 완료 계약

• TokenUsage 총량·세부량 및 provider 정규화
• 상태: Accepted / PR #23에서 구현 완료
• inputTokens, outputTokens는 포괄 총량이다.
• cache read/create는 input의 일부이고 reasoning은 output의 일부다.
• 세부량의 null은 provider 미보고, 0은 보고된 0이다.
• provider별 raw usage 차이는 Adapter가 Core 계약으로 정규화한다.
• cache/reasoning을 total에 다시 더하지 않는 이유와 정상·경계·실패 fixture를 포함한다.

Money ADR — 구현 기준 계약

• Money 정밀도·통화·반올림 및 가격 미등록 정책
• 상태: Accepted / 구현은 [Core/Budget] Money 정밀도·통화 불변식과 최종 반올림 교정 #26, [Pricing] missing pricing·explicit zero와 pricing snapshot 정책 구현 #28, [Budget] atomic reservation store와 idempotency 구현 #36, #37에서 진행
• canonical Money/Cost는 amount와 currency를 필수로 가진다.
• 내부 계산과 누적은 BigDecimal 정밀도를 보존하고 요청마다 반올림하지 않는다.
• 외부 표시·내보내기·청구 경계에서 scale 6, HALF_UP을 한 번만 적용한다.
• budget admission과 내부 비교에는 반올림 전 값을 사용한다.
• 서로 다른 통화의 산술·비교·reserve·commit은 상태 변경 없이 거부한다.
• missing pricing과 명시적 0원 rate를 구분한다.
• usage cost, cost bound, reservation, budget limit과 liability는 음수를 거부한다.
• 환율 변환과 refund/credit은 MVP 범위 밖이다.

확정 불변식

TokenUsage.total = inputTokens + outputTokens
cacheRead + cacheCreation <= inputTokens
reasoning <= outputTokens

Money.amount >= 0
Money.currency != null
same currency for arithmetic and comparison
internal amount is not rounded per request
missing pricing != explicit zero price

영향받는 후속 이슈

• [Core/Budget] Money 정밀도·통화 불변식과 최종 반올림 교정 #26: Cost와 Budget API를 currency-aware exact money로 이관
• [Pricing] missing pricing·explicit zero와 pricing snapshot 정책 구현 #28: missing plan/rate와 explicit zero를 typed resolution으로 구분
• [Core] versioned ModelRegistry와 최소 모델 정책 등록 #32: model과 pricing policy/version 연결
• [Core] 보수적 PreflightCostBound 계산 계약과 구현 #45: conservative preflight cost bound에 currency와 pricing snapshot 보존
• [Budget] atomic reservation store와 idempotency 구현 #36, [Budget] commit/release lifecycle와 actual reconciliation 구현 #37: reservation, committed cost와 unresolved liability에 동일 Money 계약 적용
• [ADR] 단일 accounting writer와 unresolved liability·event 실패 정책 정의 #46: accounting 상태·event 순서
• [Spring AI] Request/Usage Adapter와 Advisor E2E 연결 #39: Adapter는 Core 계약만 소비

Acceptance criteria

• TokenUsage ADR이 PR #23의 최종 모델과 일치한다.
• 전체량과 세부량의 포함 관계가 수식과 예제로 설명된다.
• null과 보고된 0이 구분된다.
• provider normalization이 Adapter 책임으로 고정된다.
• Money ADR이 내부 정밀도와 최종 rounding 경계를 명시한다.
• scale 6, HALF_UP과 음수 금액 정책이 결정된다.
• 다른 통화 합산 거부와 상태 무변경 원칙이 결정된다.
• missing pricing과 explicit zero가 구분된다.
• 정상·경계·실패 예시와 선택하지 않은 대안이 기록된다.
• 후속 구현 이슈가 ADR을 링크할 수 있다.

저장 위치

팀이 요청한 문서 허브 Notion 데이터베이스를 현재 canonical ADR 위치로 사용한다. 오픈소스 배포 전 repository에 공개 ADR mirror가 필요하면 #43 문서화 단계에서 동일 내용을 옮기고 링크 무결성을 검증한다.

Source

• 30일 MVP

[HuitaePark]

TokenUsage ADR과 Money ADR을 문서 허브에 작성하고 후속 구현 이슈에 계약을 연결했습니다. TokenUsage는 PR #23 구현 완료 상태, Money는 #26/#28/#36/#37의 구현 기준으로 분리했습니다.