feat: add tempo session hint reconciliation

[brendanjryan]

Summary

This keeps the session flow backward-compatible while making client channel maintenance simpler and more server-authoritative.

• add optional session hint fields in request.methodDetails: requiredCumulative, acceptedCumulative, spent, and deposit
• populate those hints on the server when request.channelId points at a reusable stored channel
• teach the Tempo session client to hydrate from those hints, prefer requiredCumulative when present, and reconcile runtime state from Payment-Receipt
• keep on-chain recovery as the fallback when only channelId is available
• keep verification behavior unchanged so legacy clients can continue sending any valid advancing voucher
• wire receipt reconciliation into normal fetch flows by letting client methods observe successful responses

Before

flowchart LR
    A[Client request without auth] --> B[Server returns 402 with optional channelId hint]
    B --> C[Client recovers channel from chain settled amount]
    C --> D[Client increments local cumulative counter]
    D --> E[Client signs voucher or open payload]
    E --> F[Server verifies credential]
    F --> G[200 plus Payment-Receipt]
    G --> H[Client updates mostly local spent state]

Loading

After

flowchart LR
    A[Client request without auth] --> B[Server returns 402 with channelId and optional accepted spent deposit required hints]
    B --> C[Client hydrates channel from server hints]
    C --> D[If hints unavailable fall back to on-chain recovery]
    D --> E[Client signs server requiredCumulative when present]
    E --> F[Server verifies credential with legacy rules unchanged]
    F --> G[200 plus Payment-Receipt with channelId acceptedCumulative spent]
    G --> H[Client overwrites local channel snapshot from receipt]

Loading

Notes

• no spec change is required; all new fields are optional and additive
• old clients ignore the new fields and still work
• new clients still fall back to the previous on-chain recovery path
• the server only emits reusable-channel hints when it already has matching stored channel state

Testing

• pnpm test src/tempo/Methods.test.ts src/tempo/client/Session.test.ts src/client/internal/Fetch.test.ts src/tempo/server/Session.test.ts
• pnpm check:types
• pnpm check

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/mppx@260

commit: 4d37baf