docs(rfc): preserve payment grants through 402 challenges

[aadopii]

A seller may authenticate an agent before returning a 402 Payment Required challenge. If that first check redeems a single-use payment grant, the paid retry is rejected even though the purchase has not started. This proposal clarifies the boundary between checking permission and consuming it.

Related to #179. This PR targets ack-id-core-rfc so the diff contains only the proposed v2 changes. It addresses an ambiguity in the draft, not a demonstrated defect in a shipped v2 SDK.

Proposed behavior

• A challenge-only request leaves its payment grant unused.
• The paid retry must pass fresh request, grant, and payment checks. The seller then atomically and durably redeems (iss, jti) before settlement submission or the protected operation begins.
• Only the winning request may start the authorized effects. A timeout or uncertain outcome after execution starts must not reopen the grant for a different operation.
• A separately authorized paid quote can consume its own grant.

The change adds ACK-Pay §4.1 and a cross-reference in ACK-ID §8. There are no new token types or headers. Nine Vitest lifecycle examples are wired into the docs workspace's test command. A path-scoped RFC workflow runs the existing build/check commands for this work, including PRs targeting the RFC branch; the existing Check workflow targets only main.

Validation and limits

The full pnpm run build and pnpm run check passed on the final revision in GitHub Actions. Local installation hit a disk-space limit, so validation ran in the fork. The new examples cover challenge/retry ordering, invalid inputs, changed authorization, concurrent requests, uncertain outcomes, completed operations, and issuer-scoped grant IDs.

The examples model ordering with explicit validation results and a single-process in-memory claim. They do not implement cryptographic verification, distributed storage, or live settlement. Production adapters still need durable shared state and rail-specific recovery. A crash after claiming a grant can leave an operation incomplete; this proposal does not promise exactly-once settlement or delivery.

This is separate from the existing review points about record retention through clock skew and receipt reissuance after payment. No published SDK behavior or dependency versions change.

AI assistance: I used Claude Code, Hermes, and Codex for source review and proposal development. Codex prepared the RFC edits, executable examples, and validation workflow, and ran the checks.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 99a71d59-97d9-4530-940d-cc6bc9c57b03

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[aadopii]

@AlvaroAlonso-0, I would appreciate your review of this proposal. The final revision passes the full build and repository checks: https://github.com/aadopii/ack/actions/runs/34476191309

[AlvaroAlonso-0]

Besides the leaked private keys it looks good to me.

[AlvaroAlonso-0]

Private keys are being shown