@spec merge(map(), map()) :: map()

Merge two usage maps and take the maximum numeric value for each field.

Canonical token counters can be numbers or base-10 integer strings. Valid integer strings are normalized before cumulative values are compared. Malformed counters remain visible when no valid value exists, but they do not replace an earlier valid counter and are not used to recompute totals. Missing input or output counters keep the existing zero default.

@spec normalize(map() | any()) :: map()

Normalize usage into a canonical map.

Guarantees canonical token keys:

• :input_tokens
• :output_tokens
• :total_tokens

Also guarantees compatibility aliases:

• :input
• :output
• :cached_tokens for :cache_read_tokens
• :cache_creation_tokens for :cache_write_tokens

Prompt cache reads and writes are available as separate counters:

• :cache_read_tokens
• :cache_write_tokens

Canonical counters accept numbers and base-10 integer strings. Malformed component counters remain visible instead of becoming zero. A malformed explicit total is replaced only when valid input and output counters can produce a derived total.

@spec zero(map() | any()) :: map()

Zero out a usage map for application-layer cache hits.

Existing keys are preserved where possible, but numeric values are reset so callers can reliably distinguish response-cache hits from provider-native cache reads that still incur an API call.