fix(responses): record the canonical spend pool for request usage

docs-site/src/content/docs/ja/reference/configuration/server.md

@@ -200,6 +200,65 @@ Claude Code **2.1.257 or newer** is required for FORCE. Plugin and built-in agen
 
 The dashboard warns about old or unknown CLI versions, unavailable targets, and either variable already present in `settings.json` → `env` (which overrides launch env). Detection is read-only and server-local: it cannot inspect another launch shell, another machine, or project-local settings. An unknown result is not proof of force support.
 
+## 過去のプール使用量の継承
+
+プロバイダープールの上限にはルーティング先の正規プロバイダーを使い、リクエストログにはアカウント別の
+表示ラベルを残します。古いジャーナルでは、その表示ラベルに使用量が計上されている場合があります。
+ジャーナルに保存されるのはソルト付きのエイリアスであり、元のプロバイダー名やアカウント名ではありません。
+そのため、OpenCodex は現在のアカウント一覧、ラベルの接頭辞、短縮されたアカウント ID から対応関係を推測しません。
+
+`spend.pool.maxTokens` が設定され、正の過去残高の所有先が不明な場合、元のスコープに残したまま、
+各残高を候補となるすべてのプロバイダープールに一度ずつ加算し、そのプロバイダーの確認済みグループと合算します。
+この合計と予約分が上限に収まる場合だけリクエストを許可します。そのため、未使用のプールも一時的に制限されることがあります。
+ローカル拒否では、エイリアスやジャーナル内容を公開せず、この保守的な加算を説明します。
+ルートが判明する前は、不明な履歴だけを理由に HTTP admission を拒否しません。
+ルーティング後の事前確認では、保守的に合算した使用量がすでに上限に達している正規プールを拒否します。
+予約によってすでに許可されたリカバリー送信やコンボ送信では、その予約を自分自身に対して再度計上しません。
+それ以外の予約はすべて計上されます。この確認により、送信後に使用量を報告するパススルー送信が
+アトミックな予約に変わるわけではありません。上限をまたぐ送信、同時に許可されるリクエスト、
+事後報告される再試行には、従来の制約が残ります。監視のみの構成は引き続き監視のみです。
+ルートと ID の上限もそれぞれ独立して適用されます。
+
+解決するには、運用者自身が保持している証拠を使い、過去の各ソルト付きプールエイリアスが
+どの正規プロバイダーに属するかを確認する必要があります。`config.json` のトップレベルに
+`spendPoolAliases` オブジェクトを追加してください。各キーには、その同じインストールのジャーナルにある
+32 文字の小文字 16 進数のプールエイリアスを正確に指定し、各値には確認済みの正規プロバイダー ID を指定します。
+古いエイリアスがすでに正規プロバイダーを表していても、ID メタデータがなければ明示的なエントリが必要です。
+正の使用量を持ち、識別できないエイリアスは、すべての候補プールに保守的に加算されます。
+似た名前、アカウントの削除、現在のプロバイダー名やハッシュ、短縮ラベルの衝突から対応関係を推測しないでください。
+ジャーナルやソルトを公開しないでください。
+
+`spendPoolAliases` は `spend` の外に置いてください。古いバージョンは `spend` 内の未知のキーを拒否し、
+セクション全体を無効にする場合があります。無効なトップレベルのマッピングは設定の書き込み時に拒否されます。
+手動編集で `spendPoolAliases` が不正になった場合、既存の上限を維持したままプールへのリクエスト受け入れを拒否します。
+通常の設定手順でマッピングを修正し、再起動してください。マッピングを空にしたり削除したりしても、
+すでに永続的に記録された対応関係は消えません。一度リダイレクトされたエイリアスを別のグループへ再割り当てすることはできません。
+確認済みの正規プロバイダー名の変更では、既存の使用量を分割せずにグループを統合できます。
+マッピング全体をまとめて検証するため、有効なグループ統合はエイリアスキーの順序に依存しません。
+
+元の使用量はそれぞれ一度だけ計上されます。確定済みの使用量、処理中の予約、未解決の使用量はすべて計上し、
+不明な使用量を払い戻しとして扱うことはありません。元の予約先は保持されます。
+新しいリクエストでは引き続き正規プロバイダーのプールを記録し、チェックポイントには生のアカウント名や
+プロバイダー名を追加せず、ソルト付きの ID 識別情報を保持します。識別できない正の使用履歴と、稼働中または
+上限に達したグループはクリーンアップから保護されます。休眠中で上限未満の項目には従来の保持ルールが引き続き適用されます。
+ID 識別情報の保存容量には上限があり、容量を使い切った場合は情報を忘れるのではなくプールへの受け入れを停止します。
+検証できない履歴を復元する自動ツールはありません。
+
+### 安全なロールバックの要件
+
+サポートされるロールバックでは、リクエストを正規プロバイダーに帰属させる処理と、プール間の継承に対応した
+台帳の読み書き処理の両方を維持するかバックポートし、同じジャーナル、ソルト、確認済みマッピングを使う必要があります。
+最新のジャーナルを保持してください。アップグレード前のコピーを復元すると、それ以降の使用量が欠落します。
+ダウングレードを互換性があるように見せるために、記録の削除、ソルトの変更、上限の引き上げ、制限の無効化をしないでください。
+
+変更を加えていない古いバイナリへの切り戻しは、**サポート対象のロールバックではありません**。
+古いバイナリは v1 の生の計上値を読めても、エイリアスをまたぐプロバイダー合計に上限を適用せず、
+新たなアカウントラベルのプールを作成したり、圧縮時に任意の ID メタデータを破棄したりする場合があります。
+ダウングレードを自動的に防ぐ仕組みはありません。そのような古い書き込み処理が実行された場合、新しい読み取り処理は、
+運用者が残っているマッピングを確認するまで、識別できない正の使用履歴を各候補プールに保守的に加算します。
+ストレージやジャーナルの整合性による拒否はエイリアスの問題とは別で、`workflow_spend_undurable` のままです。
+安全でないファイルや所有権の問題は、代わりにストレージエラーとして伝播する場合がありますが、リクエストは許可されません。
+
 ## トークン予約と上限
 
-`spend.root.maxTokens`、`spend.identity.maxTokens`、`spend.pool.maxTokens` のいずれかがリクエストに適用される場合、追跡容量の不足などでトークン予約を記録できなければ送信を拒否します。適用される上限がないリクエストは観測のみを続けます。
+リクエストに `spend.root.maxTokens`、`spend.identity.maxTokens`、`spend.pool.maxTokens` のいずれかが適用され、追跡容量の不足や送信 ID の重複などで予約を記録できない場合、新しい送信はディスパッチ前に拒否されます。適用される上限がないリクエストは引き続き観測のみです。

docs-site/src/content/docs/ko/reference/configuration/server.md

@@ -257,6 +257,61 @@ Claude Code **2.1.257 or newer** is required for FORCE. Plugin and built-in agen
 
 The dashboard warns about old or unknown CLI versions, unavailable targets, and either variable already present in `settings.json` → `env` (which overrides launch env). Detection is read-only and server-local: it cannot inspect another launch shell, another machine, or project-local settings. An unknown result is not proof of force support.
 
-## 토큰 예약과 한도
-
-요청에 `spend.root.maxTokens`, `spend.identity.maxTokens`, `spend.pool.maxTokens` 중 하나가 적용되면 추적 용량 부족 등으로 토큰 예약을 기록할 수 없을 때 전송을 거부합니다. 적용되는 한도가 없는 요청은 계속 관측만 합니다.
+## 과거 풀 사용량의 연속성
+
+제공자 풀 상한은 라우팅된 정규 제공자를 기준으로 적용하고, 요청 로그에는 계정별 표시 레이블을 유지합니다.
+이전 저널에는 이 표시 레이블에 사용량이 기록되어 있을 수 있습니다. 저널은 원래 제공자·계정 이름이 아닌
+솔트가 적용된 별칭을 저장하므로, OpenCodex는 현재 계정 목록, 레이블 접두사, 축약된 계정 ID로 매핑을 추측하지 않습니다.
+
+`spend.pool.maxTokens`가 설정되어 있고 양수인 과거 잔액의 소유자를 알 수 없으면,
+각 잔액은 원래 스코프에 보존되며 후보 제공자 풀마다 한 번씩 더해져 확인된 그룹과 합산됩니다.
+합계와 예약량이 한도에 들어오는 경우에만 요청을 허용합니다. 이 방식은 사용하지 않는 풀도 일시적으로 제한할 수 있습니다.
+로컬 거부 메시지는 별칭이나 저널 내용을 공개하지 않고 이러한 보수적 계산을 설명합니다.
+라우트를 알기 전에는 불명확한 이력만으로 HTTP admission을 거부하지 않습니다.
+라우팅 후 사전 검사에서도 보수적으로 합산한 사용량이 이미 한도에 도달한 정규 풀을 거부합니다.
+예약을 통해 이미 허용된 복구 또는 콤보 전송에서는 그 예약을 자신에게 다시 계산하지 않습니다.
+다른 예약은 모두 계산합니다. 이 검사가 사용량을 사후 보고하는 패스스루 전송을 원자적 예약으로 바꾸지는 않습니다.
+한도를 넘기는 전송, 동시 요청 허용, 사후 보고되는 재시도에는 기존 제약이 그대로 남습니다.
+관찰 전용 구성은 계속 관찰 전용으로 동작합니다. 루트와 ID 상한도 각각 독립적으로 적용됩니다.
+
+해결하려면 운영자가 보관한 근거를 사용해 과거의 각 솔트 적용 풀 별칭이 어느 정규 제공자에 속하는지 확인해야 합니다.
+`config.json`의 최상위에 `spendPoolAliases` 객체를 추가하세요. 각 키는 동일 설치의 저널에 있는
+32자리 소문자 16진수 풀 별칭과 정확히 일치해야 하고, 각 값은 확인된 정규 제공자 ID여야 합니다.
+이전 별칭이 이미 정규 제공자를 나타내더라도 ID 메타데이터가 없으면 명시적 항목이 필요합니다.
+식별할 수 없는 양수 사용량의 별칭은 모든 후보 풀에 보수적으로 계산됩니다.
+비슷한 이름, 계정 삭제, 현재 제공자 이름이나 해시, 축약 레이블 충돌로 매핑을 추측하지 말고,
+저널이나 솔트를 공개하지 마세요.
+
+`spendPoolAliases`는 `spend` 밖에 두세요. 이전 버전은 `spend` 안의 알 수 없는 키를 거부하며
+섹션 전체를 비활성화할 수 있습니다. 잘못된 최상위 매핑은 설정 쓰기 시 거부됩니다.
+수동 편집으로 `spendPoolAliases`가 잘못된 형식이 되면 기존 상한을 유지한 채 풀 요청 허용을 차단합니다.
+일반적인 설정 절차로 매핑을 수정하고 재시작하세요. 매핑을 비우거나 삭제해도 이미 영구 기록된 연결은 지워지지 않습니다.
+이전에 다른 대상으로 연결한 별칭은 다른 그룹에 재할당할 수 없습니다. 확인된 정규 제공자 이름 변경은
+기존 사용량을 나누지 않고 그룹을 합칠 수 있습니다. 전체 매핑을 함께 검증하므로 유효한 그룹 병합은 별칭 키 순서에 의존하지 않습니다.
+
+각 원래 사용량은 한 번만 계산합니다. 확정된 사용량, 진행 중 예약, 미해결 사용량을 모두 계산하며,
+알 수 없는 사용량을 환급으로 취급하지 않습니다. 원래 예약 대상은 유지됩니다.
+새 요청은 계속 정규 제공자 풀을 기록하고, 체크포인트는 원래 계정·제공자 이름을 추가하지 않은 채
+솔트가 적용된 ID 식별 근거를 보존합니다. 알 수 없는 양수 사용 이력과 활성 상태 또는 한도에 도달한 그룹은
+정리 대상에서 보호됩니다. 휴면 상태이고 한도 미만인 항목에는 기존 보존 규칙이 계속 적용됩니다.
+ID 식별 근거의 저장 용량에는 한도가 있으며, 용량을 소진하면 근거를 잊는 대신 풀 요청 허용을 중단합니다.
+검증할 수 없는 이력을 복원하는 자동 도구는 없습니다.
+
+### 안전한 롤백 요건
+
+지원되는 롤백은 요청을 정규 제공자에 귀속시키는 처리와 연속성을 인식하는 원장 읽기·쓰기 처리를 모두 유지하거나
+백포트해야 하며, 동일한 저널, 솔트, 검증된 매핑을 사용해야 합니다.
+최신 저널을 유지하세요. 업그레이드 전 사본을 복원하면 이후 사용량이 누락됩니다.
+다운그레이드가 호환되는 것처럼 보이게 하려고 기록을 삭제하거나, 솔트를 바꾸거나, 상한을 높이거나, 제한 적용을 끄지 마세요.
+
+수정하지 않은 이전 바이너리로 되돌리는 것은 **지원되는 롤백이 아닙니다**.
+이전 바이너리는 v1 원시 사용량을 읽을 수 있지만 별칭 간 제공자 합계에 상한을 적용하지 않으며,
+새 계정 레이블 풀을 만들거나 압축할 때 선택적 ID 메타데이터를 버릴 수 있습니다.
+다운그레이드를 자동으로 막는 장치는 없습니다. 이런 이전 쓰기 처리가 실행되었다면, 새 읽기 처리는
+운영자가 남은 매핑을 확인할 때까지 식별되지 않은 양수 사용 이력을 모든 후보 제공자 풀에 보수적으로 계산합니다.
+스토리지 또는 저널 무결성에 따른 거부는 별칭 문제와 별개이며 `workflow_spend_undurable`을 유지합니다.
+안전하지 않은 파일이나 소유권 문제는 대신 스토리지 오류로 전파될 수 있으며, 이 경우에도 요청을 허용하지 않습니다.
+
+## 토큰 예약 및 한도
+
+요청에 `spend.root.maxTokens`, `spend.identity.maxTokens`, `spend.pool.maxTokens` 중 하나가 적용되고 추적 용량 부족이나 중복된 전송 ID 등으로 예약을 기록할 수 없으면 새 전송을 디스패치 전에 거부합니다. 적용되는 한도가 없는 요청은 계속 관측만 합니다.