Skip to content

Commit f80c972

Browse files
jay-tauCopilot
andcommitted
docs(adapter/copilot): reconcile per-process-snapshot summing vs credit-content-dedup designs
External PR ccusage#1209 code review (10th pass, only actionable item) flagged that token-bearing rows and credit-only rows encode opposite beliefs about duplicate shutdowns: token rows trust event ids (distinct events = distinct charges, sum them), while credit-only rows distrust event ids (distinct events with same naiu = same snapshot, collapse them). Reviewer asked for a doc reconciliation explaining why the asymmetry is deliberate. Replace the brief 'Resumed sessions' section with a longer 'Resumed sessions and dedup-key design' section that: - Names the two key shapes explicitly (`shutdown:{session_id}:{event_id}:{model}` vs `credit-shutdown:{session_id}:{model}:{naiu}`). - Documents WHY token rows trust event ids: per-process snapshots commonly produce near-identical counts when a user resumes a similar workload; event-id keying prevents silent under-count. - Documents WHY credit-only rows distrust event ids: real-data ships them in paired snapshots with distinct event ids but identical naiu (1135875b-… / 76dc438a-… pattern; ~$2.65 of credits would be double-billed in the local corpus by event-id keying). - Names the matching pinning tests for both paths so a future reader has the contracts at hand. - Calls out the residual risk: if a future Copilot CLI ships GENUINE non-coincidental duplicate event ids on credit-only rows, the over-suppression would surface as a visible under-bill in `credits` JSON output (the soft signal) rather than silently doubling the bill. Also explains the synthetic aggregate-credit key (`credit-aggregate:{session_id}:{nano_aiu}`) mirrors the same content-based 'paired snapshot' semantics for consistency. No code change — pure design-rationale documentation. Co-authored-by: Copilot <[email protected]>
1 parent c5f7afd commit f80c972

1 file changed

Lines changed: 45 additions & 1 deletion

File tree

  • rust/crates/ccusage/src/adapter/copilot

‎rust/crates/ccusage/src/adapter/copilot/README.md‎

Lines changed: 45 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -78,14 +78,58 @@ skip rule ignores it to avoid surfacing all-zero phantom rows. See
7878
`skips_non_gemini_row_with_only_reasoning_tokens` for the matching
7979
regressions.
8080

81-
### Resumed sessions
81+
### Resumed sessions and dedup-key design
8282

8383
A single `events.jsonl` may contain multiple `session.shutdown` events (the user
8484
re-opened the same session UUID multiple times). Each shutdown is a
8585
**per-process snapshot** — token counts are NOT cumulative across resumes. The
8686
parser emits one entry per `(session_id, event.id, model)` triple so the
8787
resumed-session totals are summed correctly at report time.
8888

89+
The dedup-key selector chooses between two key shapes for each surviving row,
90+
and the two shapes deliberately encode **opposite beliefs about what a duplicate
91+
shutdown means** — because real-data shapes differ between the two paths:
92+
93+
- **Token-bearing / priced rows** key on `shutdown:{session_id}:{event_id}:{model}`.
94+
Two shutdowns with distinct event ids are treated as distinct charges (sum at
95+
report time), even if their token counts happen to coincide. This is correct
96+
because per-process snapshots commonly produce near-identical counts when a
97+
user resumes a similar workload, and treating them as duplicates would
98+
silently under-count usage. Pinned by
99+
`token_bearing_rows_keep_event_id_dedup_key_not_content_based` and
100+
`treats_resumed_session_shutdowns_as_distinct_entries`.
101+
- **Credit-only zero-token rows** key on
102+
`credit-shutdown:{session_id}:{model}:{naiu}` — **deliberately omitting
103+
`event_id`**. Real session-state data ships credit-only rows in
104+
duplicate pairs with distinct event ids but identical `totalNanoAiu`
105+
values (observed pattern in `1135875b-…` and `76dc438a-…`; the local
106+
200-file corpus shows roughly $2.65 of credits would be double-counted
107+
by event-id-based keying). Two such rows are treated as duplicates of
108+
the same snapshot, not distinct charges. Pinned by
109+
`auto_mode_dedupes_duplicate_credit_only_rows_within_same_session` and
110+
`credit_only_rows_with_identical_naiu_but_distinct_event_ids_are_treated_as_duplicates`.
111+
112+
**The asymmetry is intentional.** Token rows trust event ids because their
113+
data shape (per-process snapshots) makes coincidence-collision a far more
114+
likely failure mode than missed-duplicate. Credit-only rows distrust event
115+
ids because their data shape (paired snapshots) makes the opposite true.
116+
Both choices accept a small known under/over-count risk in the unlikely
117+
forward-compat case (token counts coincidentally identical across resumes;
118+
or distinct genuine credit charges that happen to share the same naiu) in
119+
exchange for correctness on the observed real-data shape.
120+
121+
The aggregate-credit synthetic entry (emitted only when no per-model row
122+
carries a priced billing signal — see `parse_session_state_file`'s
123+
suppression guard) uses the same content-based key family
124+
(`credit-aggregate:{session_id}:{nano_aiu}`) to mirror the credit-only
125+
"paired snapshot" semantics.
126+
127+
If a future Copilot CLI ships genuine non-coincidental duplicate event ids
128+
on credit-only rows, the over-suppression would surface as a visible
129+
under-bill in `credits` JSON output (which is always populated regardless
130+
of mode) — a soft signal that surfaces the schema change rather than
131+
silently doubling the bill.
132+
89133
## Model normalization
90134

91135
The adapter ships `normalize_copilot_model()` for pricing-lookup callers. The

0 commit comments

Comments
 (0)