Idempotency and budget results

The charge ledger treats (runId, idempotencyKey) as the idempotency identity. Reusing that pair returns the stored charge with replayed: true.

The endpoint reads the key from idempotency-key; it also accepts body.idempotencyKey as a fallback. The SDK always sends the header.

Budget calculation

For a new charge, the backend:

1. Sums client_cost_usd for all existing ledger rows with the same runId.
2. Subtracts that total from the signed context’s maxTotalChargeUsd.
3. Divides the remaining budget by the active event’s unitPriceUsd.
4. Charges at most the requested positive integer count.

Zero-price events accept the full requested count.

Result fields

Field	Current implementation
requestedCount	Positive integer count requested by the provider.
chargedCount	Count accepted by the budget calculation.
chargeableWithinLimit	Accepted count calculated for this request.
eventChargeLimitReached	For a new charge, true for a partial result or when the remaining budget cannot fund one more unit. On replay, it only indicates a prior partial result.
replayed	True when the ledger already had the same (runId, idempotencyKey).

eventChargeLimitReached is not implemented consistently between the first response and a replay. Use chargedCount as the authoritative count for work execution.