feat(reccontract): add Capabilities, UnavailableError and CheckAvailable

[cristim]

Summary

Adds the new package pkg/reccontract, step G2a of the multi-cloud contract plan. New files only; nothing calls it yet.

• Capabilities declares the request values a provider can honor (terms, payment options, lookbacks, default lookback, account scopes, offering classes, SP types) and Unavailable, a map from service to the reason it cannot be recommended through the provider's API. All fields land now so later steps (Normalize/Validate, Filter/Wrap) only add behaviour.
• UnavailableError{Provider, Service, Reason} matches ErrUnavailable via errors.Is.
• CheckAvailable(c, s) returns nil for an empty service or one not listed (nil map included), else an *UnavailableError.

Imports only stdlib and pkg/common. The first consumer is the GCP adapter marking Cloud SQL and Memorystore unavailable (G7b-1), which pins pkg to this commit after merge.

Closes #389

Verification (macOS, Go 1.26.9)

• (cd pkg && GOWORK=off go test -race -short -count=1 ./reccontract/): 7 passed. Full pkg race suite passed.
• GOWORK=off go build ./... in all five modules: pass. make build, make vet: pass.
• golangci-lint v2.10.1 (CI pin) from pkg: 0 issues. The local make lint binary crashes on this Go version, so the pinned version was run instead.
• Mutation probes (scratch copies): dropping Is, dropping the empty-service guard, dropping Provider from the error, and inverting the lookup each make a test fail.
• Independent two-pass review (non-author): pass 1 found the empty-service case did not exercise its guard (fixed: the test caps now list ""); pass 2 found a gofmt alignment issue (fixed). No other findings.

This is a pure type/function addition with unit tests; no provider, cloud call or purchase path is involved.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Provider capabilities can now describe supported request options, defaults, savings plan types, and services unavailable through the provider API.
  • Requests for unsupported non-empty options or unavailable services can now receive clear errors before a cloud request is made.
  • Unavailable-service errors identify the provider, service, and reason, and can be recognized when wrapped by other errors.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: LeanerCloud/cloud-commitments-go/.coderabbit.yaml
• Review profile: CHILL
• Plan: Essentials
• Run ID: 42256285-7cdc-409e-b1fa-298f0a306841

📥 Commits

Reviewing files that changed from the base of the PR and between 740dfbd and 84e3db8.

📒 Files selected for processing: 3

• pkg/reccontract/capabilities.go
• pkg/reccontract/errors.go
• pkg/reccontract/errors_test.go

Included review availability: This review used your included allowance. 0 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 1 review per hour.

📝 Walkthrough

The reccontract package adds a Capabilities type for provider-supported request values and unavailable services. It also adds UnavailableError, the ErrUnavailable sentinel, and CheckAvailable, with tests for availability checks and error matching.

Changes: Provider capability contract

Layer / File(s)	Summary
Capability and error contract pkg/reccontract/capabilities.go, pkg/reccontract/errors.go	Adds Capabilities fields for provider support, defaults, savings plan types, and unavailable services. Adds ErrUnavailable and the provider, service, and reason fields on UnavailableError.
Availability check and tests pkg/reccontract/errors.go, pkg/reccontract/errors_test.go	Adds error formatting and sentinel matching. CheckAvailable returns an UnavailableError for a listed service and nil for an empty or unlisted service. Tests cover these cases, error fields, formatting, and wrapped matching.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Feature

Merge Risk: ⚪ Minimal · up to 84e3d

No merge-blocking issue is identified; the new contract is ready for normal checks.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 3 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Linked Issues check		Issue #389 requires the new provider-neutral pkg/reccontract package with Capabilities, Unavailable, UnavailableError, ErrUnavailable, and CheckAvailable. The diff adds all required declar…
Out of Scope Changes check		The diff contains only the three new files in pkg/reccontract. The implementation, package documentation, and tests directly support issue #389. No provider adapter, cloud call, purchase path, or un…
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely names the three main additions: Capabilities, UnavailableError, and CheckAvailable. It matches the pull request scope.

• Fix all pre-merge checks with AI

✨ Finishing Touches: 💡 1

📝 Generate docstrings: 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

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

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

[cristim]

@coderabbitai review

[coderabbitai]

⚠️ Action not completed

Already reviewed the last commit. Use @coderabbitai full review to rerun a review of the entire changeset.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[cristim]

CodeRabbit reviewed the exact head 84e3db8 with no actionable comments. The docstring-coverage warning counts the three test functions and Error(), a standard error method whose behaviour the type doc already states. Dismissed: the exported declarations are all documented.

[cristim]

Independent adversarial review: CLEAN at 84e3db8076160852c8acf8ba2bafc7e67c2961c4 (claude-go-pr-merge-2; reviewer is a non-author agent with a cold brief, full diff vs 740dfbd).

Attacked: errors.Is/errors.As (pointer receiver, %w wrapping, unrelated errors), nil Unavailable map, empty-service guard (proven by a "" map key), typed-nil interface trap, duplication against pkg (no existing UnavailableError/ErrUnavailable or Term/Payment/Scope types to reuse). Mutation probes: Is returns false and empty-service guard removed both make tests fail.

Non-blocking notes: string-typed Terms/PaymentOptions/etc. match pkg/common (common/types.go:217-218), so typed enums would be a separate common change; fields have no caller yet (first step of #389 by design); no errors.As-through-wrap test (cosmetic).

Local verification (macOS, unit evidence, no cloud calls) at the exact head: (cd pkg && GOWORK=off go test -race -short ./...) pass, make build pass, make vet pass.

Gate: CI green on 84e3db8 (14/14 check runs success); CodeRabbit reviewed exactly 84e3db8 (coveredCommitId = head, kind=reviewed) with no actionable comments; labels mirror #389; head unchanged and mergeability CLEAN at merge time. Merging with squash and --match-head-commit 84e3db8.