feat(codex): retain raw quota observation history

[lidge-jun]

Summary

• Retain bounded raw quota observations for stored Codex pool accounts, using the publication identity introduced in feat(codex): establish quota-history publication identity #4375. Appends require the exact serving credential generation; ordinary refresh preserves history, while replacement/removal retires it.
• Record fresh WHAM and response headers before display carry/clamping, including replay, WebSocket, compact and warmup paths. Reject malformed/oversized history input. Native-main and pre-publication login observations are excluded from this durable pool history.
• Add cached-only GET /api/codex-auth/quota/history and ocx account history openai <pool-account-id>. Responses omit private UUID/generation. Capacity estimation remains the next dependent slice; [Feature]: retain quota history and make reset windows a scheduling input (capacity estimation, reset ordering, automatic activation) #3376 is not closed here.

Ordinary manual chain: #4375 (publication identity) → this PR (history) → capacity estimation (pending). Base is the open #4375 head branch; merge bottom-up only through the coordinator.

Verification

• Local suites of all sizes, builds, typecheck and install: NOT RUN, per explicit maintainer instruction. Regression sources are written for hosted final cumulative-tip validation.
• Source-only capability map generator updated the committed CLI reference. git diff --check and staged whitespace check passed; these are not product test evidence.
• Independent plan/source review identified a missing final compact-response observation; implementation and ordinary/alternate fixtures now cover it. Final source/security review passed at 0d98205fcd1985607d8ae257ebacc4df86ac6e63; runtime hosted acceptance remains pending.
• Added bounded-history, identity, raw/carry, persistence, management authentication, CLI and compact attribution regression coverage.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[lidge-jun]

리뷰 · 우선순위 57 / 80

설명

이 PR은 Codex 풀 계정에 대해 "방금 본 쿼터"만이 아니라, 시간순으로 쌓인 원본 관측 기록을 남기는 두 번째 칸입니다. 부모는 아직 열린 draft #4375(codex/260912-60plus-accounts-history-identity)이고, 이 브랜치 codex/260912-60plus-accounts-history는 그 tip보다 3커밋 앞서 있습니다. 체인 순서는 문서대로 publication identity(#4375) → 이 history 슬라이스 → 아직 없는 capacity 추정입니다. #3376(쿼터 이력·리셋 창을 스케줄 입력으로)을 닫지 않는다고 명시한 점도 맞습니다.

현재 dev HEAD는 2526715fb이고 방금 합쳐진 것은 #4360 experimental Codex context history/notes relay입니다. 이름에 history가 들어가지만 #4360은 src/codex/context-owner.ts / src/server/context-history.ts 쪽 대화 컨텍스트 릴레이이고, 이 PR의 src/codex/quota-history.ts와는 축이 다릅니다. dev에 이미 있는 쿼터 회피 트레인(#4368+#4396+#4397+#4398)은 process-local quotaAvoidUntil이고, 이 PR은 디스크에 남는 publication UUID에 묶인 시계열입니다. 둘을 한 PR에 섞지 않은 선택이 맞습니다.

핵심 잎은 src/codex/quota-history.ts의 CodexQuotaHistory입니다. 계정당 200샘플, 계정 64개, 전체 4096샘플, 약 2MiB, 30일 나이를 닫힌 한도로 두고, hydrate 때 한도를 넘는 envelope는 잘라 넣지 않고 통째로 거절합니다. append는 PoolQuotaWriter의 accountId·historyIdentity·credentialGeneration이 맞을 때만 들어가고, identity가 바뀌면 그 계정 bucket을 비웁니다. 읽기 DTO에서는 private UUID와 credentialGeneration을 빼고, GET /api/codex-auth/quota/history와 ocx account history openai <pool-account-id>는 업스트림을 치지 않는 캐시 전용입니다.

생산 경로는 WHAM(auth-api의 commit/fetch/401-replay), 응답 헤더(HTTP/WS/compact/warmup), compact 최종 serving 계정까지 writer를 실어 보냅니다. 클램프 전에 잘못된 percent면 관측 전체를 버리고 표시용 latest 스냅샷 동작은 그대로 둡니다. 네이티브 메인, 로그인 직전 staged 샘플, legacy updateAccountQuota는 의도적으로 빠집니다. 쿼터 캐시 읽기는 readQuotaCacheBounded로 4MiB+1을 넘기면 miss 처리하고, POSIX에서는 O_NOFOLLOW를 켭니다.

draft이고 base가 dev가 아니라 #4375 head입니다. 로컬 suite/build/typecheck는 standing restriction으로 NOT RUN이라 hosted cumulative tip 검증이 게이트입니다. structure/*에 짧게 찍힌 문서 스탬프가 여러 파일이지만, 제품 동작은 quota/auth/CLI/responses 쪽입니다. types.ts/config.ts 대분할 캠페인에 직접 걸리는 파일은 아닙니다.

라인 - (PR, clearAccountQuota) - accountId가 있을 때 hydrateAccountQuotasFromDisk를 두 번 호출합니다. diskHydrated 가드 때문에 두 번째는 no-op이라 버그는 아니지만, 첫 hydrate → history clear → 둘째 hydrate 순서가 읽기 어렵습니다. clear 앞의 한 번만 남겨도 됩니다.
경로 src/server/responses/compact.ts / 최종 outcomeCtx 기록 - 거절된 첫 계정과 최종 serving 계정을 각각 한 번씩 남기도록 고친 부분은 계획(HIST-IMPL-01)과 맞습니다. 같은 응답에서 두 계정이 나가면 샘플이 둘 생기는 것이 의도입니다. failover 테스트가 그 경계를 고정하는지만 hosted에서 한 번 더 확인하면 좋습니다.
경로 applyAccountQuotaFromUpstreamHeaders / validHistory - 헤더 경로 검증은 primary·secondary·tertiary 세 칸만 보고, Spark custom window 헤더 이상은 같은 가드에 안 넣습니다. WHAM 쪽 isValidWhamHistoryObservation은 additional_rate_limits까지 봅니다. 헤더·WHAM 가드 범위가 조금 다릅니다.
경로 structure/* 다수 파일 - 제품 코드와 무관한 2줄짜리 스탬프가 많습니다. 체인 tip 머지 전에 스탬프만 따로 정리할지, 그대로 둘지 취향 문제입니다.
경로 base #4375 - 이 PR만 dev에 얹을 수 없습니다. identity writer API(capturePoolQuotaWriter, isPoolQuotaWriterLive, poolQuotaHistoryIdentity)가 부모에 있습니다.

메인테이너의 판단이 필요한 지점

• feat(codex): establish quota-history publication identity #4375 충돌/초안 상태를 먼저 풀고 bottom-up으로 올릴지, identity+history를 한 tip으로 묶을지
• capacity child가 오기 전에 history API를 dev에 넣을 가치가 있는지 (지금은 읽기만 있고 스케줄 입력은 없음)
• hosted cumulative tip 검증 전에 draft를 ready로 올릴지
• structure 스탬프 노이즈를 허용할지

너의 추천
draft 유지하고 #4375가 안정된 뒤에만 이어서 검토하세요. 설계(펜스·한도·클램프 전 거절·메인 제외)는 #3376 두 번째 칸으로 설득력 있습니다. 지금 dev(2.52.0, #4360/#4365와 쿼터 회피 트레인)의 급한 착지 후보는 아닙니다. 로컬 테스트는 돌리지 않았고, CI 게이트 체크는 draft라 cancel된 상태입니다.

이 댓글은 grok-bot이 작성했습니다