Feat: Warn before scaling a cluster below its memory usage

[fabribet]

What changed

qcloud cluster scale now asks the platform whether the target package still holds what the cluster is using, and prints a warning above the confirmation prompt when it does not. Until now the CLI submitted every downscale without comment, because the platform stopped refusing them in CCL-1549. The warning is advisory: it never blocks a scale, and --force skips the prompt but still prints the warning, so a scripted downscale leaves the reason in its log.

What the platform answers, and what the CLI does with it:

Verdict	CLI output
RAM is not being reduced	no call is made
NO_RISK	nothing
USAGE_EXCEEDS_TARGET	warns that the cluster is using more RAM than the target provides
USAGE_UNKNOWN, an unknown status, or a failed call	warns that current usage could not be determined

Why

The memory check no longer sits on the submit path, so the platform accepts a downscale that leaves a cluster with less RAM than its data needs. The Cloud UI already warns before that happens. The CLI did not, which made it the one surface where a user could scale a cluster into an out-of-memory condition without ever being told.

Screenshot of usage

Notes

• The warning goes to stderr, above the existing prompt, so -o json on stdout is unchanged.
• The verdict is requested only when the candidate package books less RAM than the current one, so --nodes, --disk and CPU-only scales cost no extra round trip.
• A verdict that cannot be read, whether an RPC error, an unknown status or a response with no memory entry, warns that usage is unknown and lets the scale through. The platform allows the downscale either way, so failing the command would be the worse answer. The call is bounded at 5 seconds.
• --debug prints the verdict, or the reason the check was skipped. Silence is the correct output for NO_RISK, and that is the only way to tell it apart from a check that never ran.
• Node-count reductions are not covered. The platform derives the verdict from the candidate package alone, so dropping a cluster from three nodes to one draws no warning even though per-node usage can rise. This is a documented limitation on the platform side, not something the CLI can work around.
• No dependency bump. GetClusterDownscaleRisk has been in the generated client since qdrant-cloud-public-api 0.168.0 and this repo pins 0.176.0.
• docs/reference/qcloud_cluster_scale.md is regenerated output from make docs.
• Covered by 7 tests in scale_test.go. Not yet exercised against a live cluster: hybrid packages in dev start at the size the test cluster already runs, so there is no smaller package to scale to.

[Copilot]

Copilot review overview

🟡 Changes recommended

The test labeled for unknown statuses only exercises a missing memory entry, leaving the unknown-status fallback unverified.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 1

Open (1)

• Test unknown status handling with an unknown memory risk value · New

What changed in this PR

Adds an advisory platform check before RAM downscaling, warning users when usage may exceed the target package.

Changes:

• Added downscale-risk API support to the test fake.
• Implemented timeout-bounded risk checks and warnings.
• Added tests and updated generated command documentation.

File	Description
internal/​testutil/​fake_cluster.go	Adds fake RPC support.
internal/​cmd/​cluster/​scale.go	Performs risk checks and prints warnings.
internal/​cmd/​cluster/​scale_test.go	Covers warning and scale behavior.
docs/​reference/​qcloud_cluster_scale.md	Documents downscale warnings.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[fabribet]

8c4036c

[andres-qd]

lgtm