docs(copilot): add documentation for @ccusage/copilot - #1

…e comments

External PR ccusage#1209 code review identified the single recommended
maintainer gate before merge: strip references to ephemeral, private
development artifacts ("plan finding #N", "GPT-5.5 R12/R14",
"Piece B/C", "round-1/2 finding", "plan round-3 finding",
"seq-7 round-1B") from shipped code. These were meaningful to the
author during the iterative development + multi-model review process,
but read as noise (or confusion) to a future maintainer six months out.

Preserve the substance of every comment — what the code does and why
— while dropping the development-internal identifiers:
- `plan finding ccusage#10` → "Aggregate-only credits path:"
- `plan finding from PR ccusage#957 + GPT-5.5 R12` → "Skip rule for per-model
  metrics rows:" (PR ccusage#957 citation kept — external + persistent)
- `plan finding ccusage#7` → "in real session-state data"
- `plan finding #2` → (dropped — comment is self-explanatory)
- `plan finding for GPT-5.5 R14` → "Dedup key selection:"
- `plan finding ccusage#3 / Piece C carry-over from PR ccusage#957` →
  "carried over from PR ccusage#957's TypeScript implementation"
- `round-1/2 finding` → "documented invariant"
- `// ----- Piece B (credits) -----` → "AI Credits tests (totalNanoAiu)"
- `plan finding #1` → (dropped)
- `plan finding ccusage#8` → (dropped — paraphrased into the comment)
- `plan round-3 finding` → (dropped — paraphrased into the comment)
- `mirrors the seq-7 round-1B parser fixture fix` → (dropped — the
  preceding sentences already explain the genuinely-absent-vs-Some(0)
  reasoning standalone)

PR ccusage#957 references stay (external, persistent, useful for context).
External symbol/test/file references all resolve. No behavioral change.

Co-authored-by: Copilot <[email protected]>

…parity with nano_aiu deserializer

External PR ccusage#1209 code review (9th pass, prioritized #1) flagged that
`requests.cost` was deserialized via serde's default `Option<f64>`
while `totalNanoAiu` had a defensive custom deserializer
(`deserialize_nano_aiu`) rejecting NaN / ±Infinity / negative
values. The asymmetry meant a future Copilot CLI emitting a negative
`cost` would silently propagate `-1.5 × $0.04 = -$0.06` into the
billing total, making the summary appear smaller than reality —
strictly worse than dropping the single malformed row.

Add `deserialize_premium_request_cost`, structurally identical to
`deserialize_nano_aiu`: accepts int and float JSON forms, rejects
non-finite (NaN, ±Infinity) and negative values via serde errors. On
rejection the whole event drops via the existing
tolerate-malformed-line path — preferable to coercing through into
the billing total.

Regression test `rejects_negative_premium_request_cost` verified to
FAIL against the pre-fix default deserializer (which accepts -1.5
and propagates) and PASS against the new guard.

NOTE on NaN testing: standard JSON doesn't allow `NaN` / `Infinity`
literal tokens — `serde_json` rejects them at parse time before our
deserializer runs. A NaN regression test would therefore be
tautological (line-skip via JSON parse failure, not via our guard).
The `is_finite()` check is kept as defense-in-depth against any
future caller constructing the struct from a non-JSON source. The
comment in the deserializer documents this.

Total tests: 355 pass (was 354, +1 negative-cost regression).

Co-authored-by: Copilot <[email protected]>

…e comments

External PR ccusage#1209 code review identified the single recommended
maintainer gate before merge: strip references to ephemeral, private
development artifacts ("plan finding #N", "GPT-5.5 R12/R14",
"Piece B/C", "round-1/2 finding", "plan round-3 finding",
"seq-7 round-1B") from shipped code. These were meaningful to the
author during the iterative development + multi-model review process,
but read as noise (or confusion) to a future maintainer six months out.

Preserve the substance of every comment — what the code does and why
— while dropping the development-internal identifiers:
- `plan finding ccusage#10` → "Aggregate-only credits path:"
- `plan finding from PR ccusage#957 + GPT-5.5 R12` → "Skip rule for per-model
  metrics rows:" (PR ccusage#957 citation kept — external + persistent)
- `plan finding ccusage#7` → "in real session-state data"
- `plan finding #2` → (dropped — comment is self-explanatory)
- `plan finding for GPT-5.5 R14` → "Dedup key selection:"
- `plan finding ccusage#3 / Piece C carry-over from PR ccusage#957` →
  "carried over from PR ccusage#957's TypeScript implementation"
- `round-1/2 finding` → "documented invariant"
- `// ----- Piece B (credits) -----` → "AI Credits tests (totalNanoAiu)"
- `plan finding #1` → (dropped)
- `plan finding ccusage#8` → (dropped — paraphrased into the comment)
- `plan round-3 finding` → (dropped — paraphrased into the comment)
- `mirrors the seq-7 round-1B parser fixture fix` → (dropped — the
  preceding sentences already explain the genuinely-absent-vs-Some(0)
  reasoning standalone)

PR ccusage#957 references stay (external, persistent, useful for context).
External symbol/test/file references all resolve. No behavioral change.

Co-authored-by: Copilot <[email protected]>

…parity with nano_aiu deserializer

External PR ccusage#1209 code review (9th pass, prioritized #1) flagged that
`requests.cost` was deserialized via serde's default `Option<f64>`
while `totalNanoAiu` had a defensive custom deserializer
(`deserialize_nano_aiu`) rejecting NaN / ±Infinity / negative
values. The asymmetry meant a future Copilot CLI emitting a negative
`cost` would silently propagate `-1.5 × $0.04 = -$0.06` into the
billing total, making the summary appear smaller than reality —
strictly worse than dropping the single malformed row.

Add `deserialize_premium_request_cost`, structurally identical to
`deserialize_nano_aiu`: accepts int and float JSON forms, rejects
non-finite (NaN, ±Infinity) and negative values via serde errors. On
rejection the whole event drops via the existing
tolerate-malformed-line path — preferable to coercing through into
the billing total.

Regression test `rejects_negative_premium_request_cost` verified to
FAIL against the pre-fix default deserializer (which accepts -1.5
and propagates) and PASS against the new guard.

NOTE on NaN testing: standard JSON doesn't allow `NaN` / `Infinity`
literal tokens — `serde_json` rejects them at parse time before our
deserializer runs. A NaN regression test would therefore be
tautological (line-skip via JSON parse failure, not via our guard).
The `is_finite()` check is kept as defense-in-depth against any
future caller constructing the struct from a non-JSON source. The
comment in the deserializer documents this.

Total tests: 355 pass (was 354, +1 negative-cost regression).

Co-authored-by: Copilot <[email protected]>

…e comments

External PR ccusage#1209 code review identified the single recommended
maintainer gate before merge: strip references to ephemeral, private
development artifacts ("plan finding #N", "GPT-5.5 R12/R14",
"Piece B/C", "round-1/2 finding", "plan round-3 finding",
"seq-7 round-1B") from shipped code. These were meaningful to the
author during the iterative development + multi-model review process,
but read as noise (or confusion) to a future maintainer six months out.

Preserve the substance of every comment — what the code does and why
— while dropping the development-internal identifiers:
- `plan finding ccusage#10` → "Aggregate-only credits path:"
- `plan finding from PR ccusage#957 + GPT-5.5 R12` → "Skip rule for per-model
  metrics rows:" (PR ccusage#957 citation kept — external + persistent)
- `plan finding ccusage#7` → "in real session-state data"
- `plan finding #2` → (dropped — comment is self-explanatory)
- `plan finding for GPT-5.5 R14` → "Dedup key selection:"
- `plan finding ccusage#3 / Piece C carry-over from PR ccusage#957` →
  "carried over from PR ccusage#957's TypeScript implementation"
- `round-1/2 finding` → "documented invariant"
- `// ----- Piece B (credits) -----` → "AI Credits tests (totalNanoAiu)"
- `plan finding #1` → (dropped)
- `plan finding ccusage#8` → (dropped — paraphrased into the comment)
- `plan round-3 finding` → (dropped — paraphrased into the comment)
- `mirrors the seq-7 round-1B parser fixture fix` → (dropped — the
  preceding sentences already explain the genuinely-absent-vs-Some(0)
  reasoning standalone)

PR ccusage#957 references stay (external, persistent, useful for context).
External symbol/test/file references all resolve. No behavioral change.

Co-authored-by: Copilot <[email protected]>

…parity with nano_aiu deserializer

External PR ccusage#1209 code review (9th pass, prioritized #1) flagged that
`requests.cost` was deserialized via serde's default `Option<f64>`
while `totalNanoAiu` had a defensive custom deserializer
(`deserialize_nano_aiu`) rejecting NaN / ±Infinity / negative
values. The asymmetry meant a future Copilot CLI emitting a negative
`cost` would silently propagate `-1.5 × $0.04 = -$0.06` into the
billing total, making the summary appear smaller than reality —
strictly worse than dropping the single malformed row.

Add `deserialize_premium_request_cost`, structurally identical to
`deserialize_nano_aiu`: accepts int and float JSON forms, rejects
non-finite (NaN, ±Infinity) and negative values via serde errors. On
rejection the whole event drops via the existing
tolerate-malformed-line path — preferable to coercing through into
the billing total.

Regression test `rejects_negative_premium_request_cost` verified to
FAIL against the pre-fix default deserializer (which accepts -1.5
and propagates) and PASS against the new guard.

NOTE on NaN testing: standard JSON doesn't allow `NaN` / `Infinity`
literal tokens — `serde_json` rejects them at parse time before our
deserializer runs. A NaN regression test would therefore be
tautological (line-skip via JSON parse failure, not via our guard).
The `is_finite()` check is kept as defense-in-depth against any
future caller constructing the struct from a non-JSON source. The
comment in the deserializer documents this.

Total tests: 355 pass (was 354, +1 negative-cost regression).

Co-authored-by: Copilot <[email protected]>

…e comments

External PR ccusage#1209 code review identified the single recommended
maintainer gate before merge: strip references to ephemeral, private
development artifacts ("plan finding #N", "GPT-5.5 R12/R14",
"Piece B/C", "round-1/2 finding", "plan round-3 finding",
"seq-7 round-1B") from shipped code. These were meaningful to the
author during the iterative development + multi-model review process,
but read as noise (or confusion) to a future maintainer six months out.

Preserve the substance of every comment — what the code does and why
— while dropping the development-internal identifiers:
- `plan finding ccusage#10` → "Aggregate-only credits path:"
- `plan finding from PR ccusage#957 + GPT-5.5 R12` → "Skip rule for per-model
  metrics rows:" (PR ccusage#957 citation kept — external + persistent)
- `plan finding ccusage#7` → "in real session-state data"
- `plan finding #2` → (dropped — comment is self-explanatory)
- `plan finding for GPT-5.5 R14` → "Dedup key selection:"
- `plan finding ccusage#3 / Piece C carry-over from PR ccusage#957` →
  "carried over from PR ccusage#957's TypeScript implementation"
- `round-1/2 finding` → "documented invariant"
- `// ----- Piece B (credits) -----` → "AI Credits tests (totalNanoAiu)"
- `plan finding #1` → (dropped)
- `plan finding ccusage#8` → (dropped — paraphrased into the comment)
- `plan round-3 finding` → (dropped — paraphrased into the comment)
- `mirrors the seq-7 round-1B parser fixture fix` → (dropped — the
  preceding sentences already explain the genuinely-absent-vs-Some(0)
  reasoning standalone)

PR ccusage#957 references stay (external, persistent, useful for context).
External symbol/test/file references all resolve. No behavioral change.

Co-authored-by: Copilot <[email protected]>

…parity with nano_aiu deserializer

External PR ccusage#1209 code review (9th pass, prioritized #1) flagged that
`requests.cost` was deserialized via serde's default `Option<f64>`
while `totalNanoAiu` had a defensive custom deserializer
(`deserialize_nano_aiu`) rejecting NaN / ±Infinity / negative
values. The asymmetry meant a future Copilot CLI emitting a negative
`cost` would silently propagate `-1.5 × $0.04 = -$0.06` into the
billing total, making the summary appear smaller than reality —
strictly worse than dropping the single malformed row.

Add `deserialize_premium_request_cost`, structurally identical to
`deserialize_nano_aiu`: accepts int and float JSON forms, rejects
non-finite (NaN, ±Infinity) and negative values via serde errors. On
rejection the whole event drops via the existing
tolerate-malformed-line path — preferable to coercing through into
the billing total.

Regression test `rejects_negative_premium_request_cost` verified to
FAIL against the pre-fix default deserializer (which accepts -1.5
and propagates) and PASS against the new guard.

NOTE on NaN testing: standard JSON doesn't allow `NaN` / `Infinity`
literal tokens — `serde_json` rejects them at parse time before our
deserializer runs. A NaN regression test would therefore be
tautological (line-skip via JSON parse failure, not via our guard).
The `is_finite()` check is kept as defense-in-depth against any
future caller constructing the struct from a non-JSON source. The
comment in the deserializer documents this.

Total tests: 355 pass (was 354, +1 negative-cost regression).

Co-authored-by: Copilot <[email protected]>