feat(payments): settle the metered actual at session close (ATXP up-to) — Phase 2

[badjer]

Phase 2 — ATXP up-to (settle the metered actual)

Second phase of the streaming-payment-sessions work (Phase 1: #177). Makes session close settle the accumulated actual (session.spent) instead of the credential's full cap — the "up-to" semantics: authorize a cap, meter locally, settle what was actually spent.

What changes

• ProtocolSettlement.settle(protocol, credential, context?, actualAmount?) — additive optional actualAmount. For ATXP it overrides the settle body's options[].amount, so auth /pay charges the actual (≤ the authorized cap) instead of the cap baked into the credential. x402 (settlementOverrides.amount) and mpp (voucher amount) get their mappings in their own phases.
• settlePaymentSession passes session.spent as actualAmount.

What does NOT change

• requirePayment({price}) and the resource-server API are identical. It charges the open session locally (zero network per charge); N calls now settle their sum at close.
• No accounts/auth changes. The cap already comes from the challenge amount (max(minimumPayment, price)), and /pay already permits a charge ≤ spend_limit.
• Backwards-compatible. For a single requirePayment(price), spent === price === cap, so the settled amount equals Phase 1's. No mode flag.

Verification

• @atxp/server: 210 tests green (new: settle passes actualAmount === spent; multi-charge sums under cap; single-charge unchanged; cap-exceed rejects).
• @atxp/express: 55 green (new integration test: real McpServer + transport, 3× requirePayment($0.001) → one /settle/atxp carrying the summed $0.003).
• Live E2E (Base mainnet): a tool charging 3 × $0.001 against a $0.01-cap ATXP credential settled $0.003 (the metered actual) in a single on-chain /pay at close — txHash 0x5507…, confirmed within the settle window, no settle_unconfirmed/failed markers. Phase 1 would have settled the $0.01 cap.

Design: docs/STREAMING_PAYMENT_SESSIONS.md (accounts), Phase 2.

🤖 Generated with Claude Code

[badjer]

Thanks for the review — addressed all three in 02f0444.

1. Exponential serialization (real bug) — fixed: actualAmount.toFixed() instead of .toString(), so sub-1e-6 totals never serialize as "3e-7". Regression test asserts 0.0000003 → "0.0000003" and contains no e.

2. Inaccurate spent === price === cap invariant — corrected. The comment now states spent is the sum of prices (≤ cap), and notes spent < cap even for a single charge when minimumPayment inflated the cap. Renamed the misleading one-shot test and added a new single-charge test with cap > price asserting actualAmount === price and < cap — the case that actually demonstrates up-to for a one-shot call and guards against regressing to cap-settling.

3. x402/mpp silent overcharge — added a greppable settle_actual_dropped protocol=… actual=… logger.warn in buildRequestBody whenever actualAmount is supplied for a non-ATXP protocol, so the interim overcharge is visible until those phases wire their up-to mappings. Test asserts the marker fires for x402.

Minors: left as-is per your assessment (the >6-decimal precision passthrough is pre-existing and shared with the challenge path; the array cast is practically unreachable).

Suites green: atxp-server 213, atxp-express 55, tsc clean. No re-E2E — for the tested $0.003, toFixed() yields the identical "0.003"; the fix only changes sub-1e-6 values.