Design multi-account usage snapshot model

[cbusillo]

Objective

Design the core account, provider, usage-limit, snapshot, and refresh-health model for multiple logins per provider.

Finish Line

ContextPanelCore exposes tested domain types that can represent multiple accounts per provider, one or more model/limit buckets per account, reset timing, stale data, unknown limits, and provider refresh errors.

Current Status

State: Partially complete. Core UsageLimit, percent units, Codex/Gemini/Claude parser types, and forecast tests now exist on PR #14, but the model still needs a production connector/store vocabulary.
Next action: Use #15 connector runtime and #16 snapshot storage to finish the account, refresh health, history, and widget-safe cache shapes.
Blocked by: None; provider research is sufficient for MVP.
Last verified: 2026-05-06.

Scope

• Account identity and display naming.
• Provider enum and adapter-facing identifiers.
• Limit buckets for model, message, token, spend, or request quotas.
• Reset windows and refresh timestamps.
• Unknown, stale, limited, and error states.
• Tests for limit math and state aggregation.

Acceptance Criteria

• Domain model supports multiple accounts per provider without UI-specific assumptions.
• Tests cover aggregate status, reset timing, stale snapshots, and exhausted limits.
• README or architecture docs reflect the implemented vocabulary.

Relationships

• Sub-issue of Build Context Panel v1 native app and widget #2.
• Blocks Build provider connector runtime #15 provider connector runtime where model gaps appear.
• Blocks Build local snapshot storage and history #16 snapshot storage and history.
• Informed by Research provider usage access for OpenAI, Anthropic, and Google #3 provider research and PR Add OpenAI limit probe prototype #14 probes.

Validation

• scripts/commit-gate.sh.

Decisions

Open Questions

• How should unavailable provider limits differ from exhausted limits in the UI model?