fix: normalize cache token usage semantics

[KorenKrita]

Summary

• define a self-describing usage marker for producers whose input totals include cache reads and writes
• normalize historical and current usage into one inclusive-input contract before storing derived usage events
• handle cumulative snapshot resets consistently and preserve primary input/output usage when cache partitions are malformed
• rebuild derived usage indexes through the v21 migration

Historical compatibility

• Claude assistant usage is normalized from cache-exclusive input
• Codex and Kimi cumulative/provider totals retain inclusive input semantics
• Pi imports and current generic ACP producers use explicit markers
• dashboard-era generic ACP messages with their own model property remain inclusive
• older unmarked generic ACP messages are conservatively normalized from cache-exclusive input

Validation

• bun run typecheck
• Hub usage and migration tests
• Codex, Kimi, Pi, and generic producer tests
• full Hub test suite
• independent adversarial review of cumulative resets, malformed cache partitions, migration behavior, and mixed old/new events

Closes #1389

[github-actions]

Findings

• No actionable findings.

Summary
Review mode: initial

No correctness, security, regression, data-loss, performance, or maintainability issues were found in the modified lines. Residual risk: schema v21 reindexes historical usage using producer-shape heuristics, so a provider payload variant absent from the fixtures could still be misclassified.

Testing

• Not run (automation; PR content was not executed). GitHub test check passed for head 3fa9cae7.

HAPI Bot

[github-actions]

Findings

• No actionable findings.

Summary
Review mode: follow-up after new commits

No correctness, security, regression, data-loss, performance, or maintainability issues were found in the modified lines. Residual risk: cumulative reset handling and legacy input-semantics reconstruction still depend on provider-shaped historical fixtures; the current CI test check has not completed yet.

Testing

• Not run (automation; PR content was not executed). GitHub test check is in progress for head cb29000d.

HAPI Bot