feat(mcp): require a USD cap on every real purchase

[cristim]

Summary

This is part 2 of 3 for #51. It is stacked on #66: the base is feat/51-usd-spend-cap, so merge #66 first and then retarget this PR to main.

The existing per-call caps bound request size, not money: CUDLY_MCP_MAX_COUNT=50 still admitted 50 x u-24tb1, roughly $286M over three years. Real purchases now also require CUDLY_MCP_MAX_COMMITMENT_USD.

• Before credentials: authorizeRealPurchase reads the USD cap. Unset, empty, non-numeric, NaN, Inf or <= 0 refuses the purchase before ResolveClient, with no credential or network use. The parsed limit is passed down, so the env var is read once.
• After ResolveClient, before the idempotency token or PurchaseCommitment: enforceUSDCap (from feat(tools): compute the total USD a purchase commits #66) prices the purchase and refuses a total above the cap. A purchase it cannot price is refused too.
• GCP: real GCP CUD purchases are now refused, because the pinned library cannot price them (go#321). The owner chose this over bumping the pin first. Re-enabling is tracked in feat(gcp): bump cloud-commitments-go past go#321 and re-enable priced GCP CUD purchases #67.
• ExecutePurchase's response tail moved into purchaseResponse, which keeps the function under the gocyclo limit. This is a pure extraction.
• Operator surface:
  • mcpb/manifest.json: env var in all 3 platform blocks, plus a max_commitment_usd user setting whose title matches the refusal message.
  • server.json
  • README spend-cap paragraph and CHANGELOG Breaking / Added / Security entries.

Refs #51 (the issue stays open for part 3, the cumulative budget)

Test changes that narrow coverage (deliberate)

Under the GCP refusal, four tests that asserted a successful real GCP purchase now assert the refusal:

• TestGCPComputeEngineCUDPurchaseHandleRealPurchase
• the protocol-level TestGCPComputeEngineCUDPurchaseStructuredCost (explicit-zero cost, fix(deps): adopt reviewed cloud-commitments-go purchase safeguards #35/test(gcp): cover adopted purchase safeguards in MCP consumer #43)
• the GCP count-at-cap case in TestSpendCapCountAcrossEveryCountBearingBuilder
• the memory-within-cap case in TestSpendCapGCPMemory

The over-cap refusals are still asserted. The library-boundary GCP cost proof stays in tools/gcp_computeengine_cud_safeguards_test.go. #67 lists all four tests to restore. No test-only bypass seam was added.

rdsOffering in tools/adopted_go_safeguards_test.go gains a price and currency, because the real RDS library path now has to clear the cap.

Verification (local, macOS, at d2e389b)

Fake-cloud and unit evidence only. No real purchase or cloud call is made.

• gofmt, go vet ./... and make build pass.
• go test -race -count=1 ./... passes in all 3 packages. golangci-lint and gosec, both run with GOTOOLCHAIN=go1.26.9, report 0 issues.
• gocyclo -over 10 lists no non-test code. markdownlint passes on README and CHANGELOG, and both JSON files parse.
• Regression: TestUSDCapRegressionExpensiveRI (EC2 u-24tb1 x 50, $5.72M each, cap $1000). Without the enforceUSDCap call the purchase executes (purchaseCalls == 1, the test fails). With it the call is refused, naming CUDLY_MCP_MAX_COMMITMENT_USD, with purchaseCalls == 0 after the client resolved.
• TestUSDCapUnsetRefusesBeforeResolve checks that an unset cap leaves the client unresolved and makes no offering call.
• Mutation probes by the reviewer (scratch copy, restored): each of these fails tests:
  • deleting the cap call
  • skipping the pre-resolve read
  • moving the cap check after PurchaseCommitment

Review

An independent reviewer (Sonnet, high effort, non-author) did two passes. Pass 1 found no high or medium issues. It traced all 8 ExecutePurchase call sites to the single choke point, confirmed previews stay offline, and confirmed the purchaseResponse extraction preserves behaviour. Its four low findings were handled as follows:

1. CHANGELOG wording on the "required" setting: fixed.
2. The GCP refusal runs after ResolveClient: accepted. It needs no network, and the docs only promise a pre-credential refusal for an unset cap.
3. An unproven "same offering is bought" sentence: softened.
4. Cap refusals are not audited, the same as every existing pre-purchase refusal: follow-up feat(audit): record pre-purchase refusals in the purchase audit log #68.

Pass 2 found no actionable findings. CodeRabbit is not pinged because the org's CR quota is exhausted.

🤖 Generated with Claude Code

[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: Repository: LeanerCloud/cloud-commitments-mcp/.coderabbit.yaml
• Review profile: CHILL
• Plan: Essentials
• Run ID: 0108b59d-084f-44f2-a280-d17c46844cdf

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

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

[cristim]

Merge-driver verdict: CLEAN at d2e389b86a365b5bafcee4b5f9e15f3bfc869543

Scope. This reviews the delta 5ffa001..d2e389b on top of #66. The same independent reviewer reviewed #66 (Sonnet, high effort, cold brief, not the author). It found no blocking findings.

Verified:

• Every real purchase is capped. All eight purchase tools route through ExecutePurchase. The only PurchaseCommitment call is at tools/purchase.go:664. The order is authorize, then ResolveClient, then enforceUSDCap on the same rec, then PurchaseCommitment. No path bypasses the cap.
• Previews are not blocked. They return before the cap is read.
• The cap fails closed. An empty, whitespace, unparsable, NaN, Inf, zero or negative cap refuses the purchase before ResolveClient (TestUSDCapUnsetRefusesBeforeResolve, TestUSDCapEnvParsing).
• Wording. Refusals use the refusing real purchase: prefix from spend_caps.go, and GCP is "refused" (go#321) with zero provider calls.
• No weakened tests. The removed lines are GCP success assertions, replaced by refusal assertions. The new usd_cap_wiring_test.go covers the $286M regression case.

Mutation probes (3), all killed:

1. Deleting the enforceUSDCap call made 6 tests fail.
2. Replacing the cap read with a huge constant made 2 tests fail.
3. Loosening zero-rejection from <= 0 to < 0 made the env-parsing test fail.

Local verification on macOS (real runs, fixture and mock pricing, no cloud calls):

• Toolchain: GOTOOLCHAIN=go1.26.9, the version pinned in go.mod. The local go1.27.2 install is broken.
• go build ./... passes.
• go test -count=1 ./... passes: 809 tests.
• Real-account coverage gap: no live purchase was exercised, by design.

Non-blocking notes (for follow-up):

• GCP is refused only after ResolveClient, so credentials are resolved first. The README says scope checks run before credentials are touched. An early refusal in authorizeRealPurchase would make that claim true.
• The manifest has max_commitment_usd min: 1, while the server accepts any value above 0.
• The GCP real-success structured-cost coverage is gone; restore it with the go#321 pin bump.

Gate status:

• CR waived: quota, adversarial review + local verification + green CI.
• Merge order: feat(tools): compute the total USD a purchase commits #66 first. Then this PR is rebased onto main with --onto, dropping feat(tools): compute the total USD a purchase commits #66's commits. If the range-diff is empty, this verdict carries over. Full CI on main is required before merge.

[cristim]

Follow-ups for the non-blocking notes:

• GCP refused after ResolveClient, and the GCP success coverage: both added to feat(gcp): bump cloud-commitments-go past go#321 and re-enable priced GCP CUD purchases #67's scope.
• Manifest min: 1 vs. server > 0: no change. The manifest is the stricter of the two, the server still fails closed on <= 0, and a sub-dollar cap would refuse every real purchase anyway. The feat(mcp): USD spend cap on the execute path and a cumulative purchase budget #51 B branch uses the same min: 1 for budget_usd. [claude-mcp-impl]

[cristim]

Automated review of d2e389b: no blocking findings and CI is green. Ready to merge.
USD cap is read before credentials, priced via the provider offering lookup, and fails closed on unset, invalid, non-USD, zero or unpriceable values. GCP CUDs are refused. Wiring and unit tests cover the main paths. No blocking bugs found.

• (optional) tools/purchase.go:652: The USD cap passes the pre-purchase price check, but the returned total is discarded. Recording it in the audit record or response would help operators. Cap refusals write no audit entry, which is documented in the comment.
• (optional) CHANGELOG.md:28: One bullet is a very long line, and the Breaking section now has a blank line splitting its bullets. Tidy the wrapping.

Posted by a read-only review sweep. It stays silent on this commit and re-reviews only after a new push.