feat(recommendations): make rec generation coverage-aware OR enforce 100%-coverage contract

[cristim]

Background

PR #200 / commit b318a75a5 introduced a per-account coverage cap on the dashboard "potential savings" headline. The implementation assumes recommendations are generated at 100% coverage and scales them down to the user's configured coverage on the read side.

That assumption is documented in code (internal/api/handler_dashboard.go:130-132):

Note: assumes recs are generated at 100% coverage. A follow-up on dashboard accuracy (see #196 references) will revisit if rec generation becomes coverage-aware.

The follow-up was deferred from #196's "Out of scope" list. Filing it as its own issue so it doesn't get lost.

Why this matters

If the upstream rec generator (Cost Explorer / Azure Advisor / GCP Recommender) is already coverage-aware — e.g., AWS Cost Explorer's GetReservationPurchaseRecommendation is documented to consider existing utilization — then the recs landing in our DB do NOT represent "100% coverage" potential. They already factor in current commitments.

In that case the dashboard's read-side scaling double-counts coverage: it multiplies an already-coverage-aware figure by the override coverage, producing a number lower than reality. A user setting coverage = 50 on an account where Cost Explorer is already accounting for ~40% utilization would see a headline savings figure ~half what it should be — and crucially, they'd think raising coverage would unlock proportionally more savings, when most of that is already captured.

If the rec generator is NOT coverage-aware (i.e. it really does produce 100%-coverage figures), the current scaling is correct.

The status quo is "we don't know which", and the assumption is hard-coded.

What needs investigation + fix

1. Audit per provider: for each provider's rec collector, document whether the upstream API output represents 100%-coverage potential or already-utilized-aware figures.
   • AWS Cost Explorer (providers/aws/recommendations/): inspect EstimatedSavings / EstimatedMonthlySavingsAmount semantics in the SDK + AWS docs.
   • Azure Advisor (providers/azure/): same.
   • GCP Recommender (providers/gcp/): same.
2. Adjust generation to a known baseline: pick "always 100%" as the contract and back out any provider-side coverage assumptions, OR thread the override coverage into the upstream call when the API supports it (Cost Explorer's LookbackPeriod plus current-utilization signal).
3. Update summarizeRecommendationsWithCoverage to match whatever contract is now in force; remove the deferred-assumption comment.
4. Regression test: seed recs at known per-account coverage targets, set overrides, assert dashboard math agrees with the spec.

Acceptance

• Each rec collector's coverage assumption is documented (in code or in providers/*/README.md).
• The dashboard scaler's input contract is enforced by construction, not by the deferred-assumption comment.
• A regression test pins the math.

Related

• feat(recommendations): option-B read-time filter for enabled / coverage / include-exclude per-account override fields #196 — parent feature
• fix(dashboard): coverage=0 silently zeroes savings instead of 'no scaling configured' #201 — dashboard coverage = 0 doc/code mismatch (orthogonal but adjacent)
• PR feat(recommendations): apply per-account overrides at read time (#196) #200's "Out of scope AWS + Azure: add read-only sanity checks + AWS RI exchange #3"

References

• internal/api/handler_dashboard.go:115-167 (the assumption + scaler)
• internal/api/handler_dashboard.go:130-132 (the deferred-follow-up comment)
• providers/aws/recommendations/parser_ri.go
• providers/azure/recommendations/
• providers/gcp/recommendations/

[cristim]

Verified shipped: merge commit 973a42b (PR #589) is in origin/feat/multicloud-web-frontend (compare API: feat is ahead of 973a42b). PR #589 body says "Closes #215" and audited AWS CE, Azure Advisor, and GCP Recommender savings semantics confirming all three APIs return savings sized for ~100% coverage of historical demand. Added // CONTRACT: block with per-provider evidence to summarizeRecommendationsWithCoverage and // issue #215 audit comments at each source site.