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

Merge two usage maps, taking the max of numeric fields (to handle cumulative streaming usage) and recomputing derived totals.

@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

@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.