feat(db): nullable MonthlyCost on PurchaseHistoryRecord (closes #255)

Migration 000063 drops NOT NULL on purchase_history.monthly_cost so rows
from providers without a monthly recurring breakdown (Azure/GCP all-upfront)
can store NULL instead of a misleading 0.0.

- PurchaseHistoryRecord.MonthlyCost: float64 -> *float64
- InventoryCommitment.MonthlyCost: float64 -> *float64
- All scan loops use sql.NullFloat64; nil DB value -> nil pointer
- execution.go: remove derefFloat64; pass pointer straight through
- handler_inventory.go: skip nil MonthlyCost in coverage aggregation
- handler_history.go: sumRecommendationMonthlyCostPtr returns nil when
  every rec has nil MonthlyCost (renders as -- not $0.00)
- Frontend: monthly_cost typed number|null; inventory cell renders --
- All test fixtures and assertions updated to use *float64 (pf helper)

Author: cristim

frontend/src/api/types.ts

@@ -660,7 +660,8 @@ export interface InventoryCommitment {
   start_date: string;
   end_date: string;
   upfront_cost: number;
-  monthly_cost: number;
+  /** null when the provider API did not return a monthly recurring breakdown; "$X.XX" when populated, "—" when null. */
+  monthly_cost: number | null;
   estimated_savings: number;
   /**
    * Always "active" today — the backend filters expired rows before

frontend/src/inventory.ts

@@ -182,7 +182,7 @@ function buildCommitmentRow(c: api.InventoryCommitment): HTMLTableRowElement {
   appendCell(tr, String(c.count));
   appendCell(tr, `${c.term_years}y`);
   appendCell(tr, c.payment_option ?? '');
-  appendCell(tr, formatCurrency(c.monthly_cost));
+  appendCell(tr, c.monthly_cost != null ? formatCurrency(c.monthly_cost) : '—');
   appendCell(tr, formatDate(c.end_date));
 
   return tr;

frontend/src/types.ts

@@ -187,7 +187,7 @@ export interface HistoryPurchase {
   term: number;
   payment?: string;
   upfront_cost: number;
-  monthly_cost?: number;
+  monthly_cost?: number | null;
   estimated_savings: number;
   account_id?: string;
   plan_name?: string;

internal/api/handler_history.go

@@ -380,17 +380,15 @@ func projectRecommendationFields(row *config.PurchaseHistoryRecord, exec config.
 		row.Payment = r.Payment
 		row.UpfrontCost = r.UpfrontCost
 		row.EstimatedSavings = r.Savings
-		if r.MonthlyCost != nil {
-			row.MonthlyCost = *r.MonthlyCost
-		}
+		row.MonthlyCost = r.MonthlyCost
 		return
 	}
 	row.Region = "multiple"
 	row.ResourceType = fmt.Sprintf("%d commitment(s)", len(recs))
 	row.Service = collapseRecommendationService(recs)
 	row.Term = collapseRecommendationTerm(recs)
 	row.Payment = collapseRecommendationPayment(recs)
-	row.MonthlyCost = sumRecommendationMonthlyCost(recs)
+	row.MonthlyCost = sumRecommendationMonthlyCostPtr(recs)
 	row.UpfrontCost = exec.TotalUpfrontCost
 	row.EstimatedSavings = exec.EstimatedSavings
 }
@@ -486,21 +484,24 @@ func collapseRecommendationAccount(recs []config.RecommendationRecord) string {
 	return first
 }
 
-// sumRecommendationMonthlyCost adds up the per-rec MonthlyCost values in a
-// multi-rec execution so the Approval queue's Monthly Cost cell shows the
-// committed recurring spend for the full basket. Nil per-rec entries
-// contribute 0 (the provider API did not return a monthly breakdown for
-// that rec) — the same treatment as the single-rec branch, which only
-// copies MonthlyCost when non-nil and otherwise leaves the row's field at
-// the zero value.
-func sumRecommendationMonthlyCost(recs []config.RecommendationRecord) float64 {
+// sumRecommendationMonthlyCostPtr sums the per-rec MonthlyCost values for a
+// multi-rec execution row in the Approval queue. Nil entries (provider API
+// did not return a monthly breakdown) are skipped. Returns nil when every rec
+// has a nil MonthlyCost so the row renders as "—" rather than "$0.00".
+// Returns a pointer to the accumulated total otherwise.
+func sumRecommendationMonthlyCostPtr(recs []config.RecommendationRecord) *float64 {
 	var total float64
+	anyNonNil := false
 	for _, r := range recs {
 		if r.MonthlyCost != nil {
 			total += *r.MonthlyCost
+			anyNonNil = true
 		}
 	}
-	return total
+	if !anyNonNil {
+		return nil
+	}
+	return &total
 }
 
 // MaxHistoryDateRangeDays caps the inclusive start/end window the History

internal/api/handler_history_test.go

@@ -478,7 +478,8 @@ func TestHandler_getHistory_InProgressRowMapsRecFields(t *testing.T) {
 			assert.Equal(t, 1, row.Count)
 			assert.Equal(t, 0.0, row.UpfrontCost, "upfront must come from the rec")
 			assert.Equal(t, 1.2333, row.EstimatedSavings, "savings must come from the rec")
-			assert.Equal(t, 2.117, row.MonthlyCost, "monthly cost must come from the rec")
+			require.NotNil(t, row.MonthlyCost, "monthly cost must come from the rec")
+			assert.InDelta(t, 2.117, *row.MonthlyCost, 1e-9, "monthly cost must come from the rec")
 			assert.Equal(t, "no-upfront", row.Payment, "payment must come from the rec, not be left blank (#733)")
 			assert.NotEmpty(t, row.StatusDescription,
 				"in-progress rows must carry a human-readable status description, not render as a finished purchase")
@@ -1177,7 +1178,8 @@ func TestHandler_getHistory_ApprovalQueueColumnsPopulated(t *testing.T) {
 
 		assert.Equal(t, accountID, row.AccountID, "Account must fall back to rec.CloudAccountID when exec.CloudAccountID is nil (#733)")
 		assert.Equal(t, "all-upfront", row.Payment, "Payment must be copied from the single rec (#733)")
-		assert.Equal(t, 7.5, row.MonthlyCost, "MonthlyCost must come from the rec")
+		require.NotNil(t, row.MonthlyCost, "MonthlyCost must come from the rec")
+		assert.InDelta(t, 7.5, *row.MonthlyCost, 1e-9, "MonthlyCost must come from the rec")
 	})
 
 	t.Run("multi-rec uniform pending row collapses Account + Payment, sums MonthlyCost", func(t *testing.T) {
@@ -1214,7 +1216,8 @@ func TestHandler_getHistory_ApprovalQueueColumnsPopulated(t *testing.T) {
 
 		assert.Equal(t, accountID, row.AccountID, "Account must collapse to the shared rec value (#733)")
 		assert.Equal(t, "no-upfront", row.Payment, "Payment must collapse to the shared rec value (#733)")
-		assert.InDelta(t, 7.5, row.MonthlyCost, 1e-9, "MonthlyCost must sum across recs (#733)")
+		require.NotNil(t, row.MonthlyCost, "MonthlyCost must sum across recs (#733)")
+		assert.InDelta(t, 7.5, *row.MonthlyCost, 1e-9, "MonthlyCost must sum across recs (#733)")
 	})
 
 	t.Run("multi-rec heterogeneous Payment collapses to empty for honest dash fallback", func(t *testing.T) {

internal/api/handler_inventory.go

@@ -145,7 +145,9 @@ func (h *Handler) getCoverageBreakdown(ctx context.Context, req *events.LambdaFu
 		if !isActiveCommitment(p, now) {
 			continue
 		}
-		coveredByKey[p.Provider+":"+p.Service] += p.MonthlyCost
+		if p.MonthlyCost != nil {
+			coveredByKey[p.Provider+":"+p.Service] += *p.MonthlyCost
+		}
 	}
 
 	// --- on-demand gap: recommendations -------------------------------------

internal/api/handler_inventory_test.go

@@ -74,7 +74,7 @@ func TestHandler_listActiveCommitments_FiltersExpired(t *testing.T) {
 			Term:             1,
 			Payment:          "no-upfront",
 			Timestamp:        now.AddDate(0, -6, 0),
-			MonthlyCost:      100.0,
+			MonthlyCost:      float64Ptr(100.0),
 			EstimatedSavings: 30.0,
 		},
 		// Expired: bought 2 years ago, 1-year term.
@@ -87,7 +87,7 @@ func TestHandler_listActiveCommitments_FiltersExpired(t *testing.T) {
 			Count:            1,
 			Term:             1,
 			Timestamp:        now.AddDate(-2, 0, 0),
-			MonthlyCost:      50.0,
+			MonthlyCost:      float64Ptr(50.0),
 			EstimatedSavings: 15.0,
 		},
 	}
@@ -117,7 +117,8 @@ func TestHandler_listActiveCommitments_FiltersExpired(t *testing.T) {
 	assert.Equal(t, 2, row.Count)
 	assert.Equal(t, 1, row.TermYears)
 	assert.Equal(t, "no-upfront", row.PaymentOption)
-	assert.Equal(t, 100.0, row.MonthlyCost)
+	require.NotNil(t, row.MonthlyCost)
+	assert.Equal(t, 100.0, *row.MonthlyCost)
 	assert.Equal(t, 30.0, row.EstimatedSavings)
 	assert.Equal(t, "active", row.Status)
 	assert.False(t, row.StartDate.IsZero())
@@ -141,7 +142,7 @@ func TestHandler_listActiveCommitments_AccountFilter(t *testing.T) {
 			Timestamp:        now.AddDate(0, -3, 0),
 			Term:             1,
 			Count:            1,
-			MonthlyCost:      80.0,
+			MonthlyCost:      float64Ptr(80.0),
 			EstimatedSavings: 20.0,
 		},
 	}
@@ -378,7 +379,7 @@ func TestHandler_getCoverageBreakdown_Integration(t *testing.T) {
 			Service:     "ec2",
 			Timestamp:   now.AddDate(-1, 0, 1), // active: 1y term started ~1y ago
 			Term:        1,
-			MonthlyCost: 150.0,
+			MonthlyCost: float64Ptr(150.0),
 		},
 	}
 	recs := []config.RecommendationRecord{

internal/api/handler_per_account_perms_test.go

@@ -750,7 +750,7 @@ func TestPerAccountPerms_CoverageBreakdown_RecsFilteredByAllowedAccounts(t *test
 		Service:     "ec2",
 		Timestamp:   now.AddDate(0, -6, 0),
 		Term:        1,
-		MonthlyCost: 200.0,
+		MonthlyCost: float64Ptr(200.0),
 	}
 
 	// Recommendation for account A: on-demand gap the scoped user is allowed to see.
@@ -830,7 +830,7 @@ func TestPerAccountPerms_CoverageBreakdown_AdminSeesAll(t *testing.T) {
 		Service:     "ec2",
 		Timestamp:   now.AddDate(0, -6, 0),
 		Term:        1,
-		MonthlyCost: 200.0,
+		MonthlyCost: float64Ptr(200.0),
 	}
 	recA := config.RecommendationRecord{
 		Provider: "aws", Service: "ec2",

internal/api/types.go

@@ -508,8 +508,11 @@ type InventoryCommitment struct {
 	PaymentOption    string    `json:"payment_option,omitempty"`
 	StartDate        time.Time `json:"start_date"`
 	EndDate          time.Time `json:"end_date"`
-	UpfrontCost      float64   `json:"upfront_cost"`
-	MonthlyCost      float64   `json:"monthly_cost"`
+	UpfrontCost float64 `json:"upfront_cost"`
+	// MonthlyCost is nil when the source purchase_history row has a NULL
+	// monthly_cost (provider did not return a monthly breakdown). The
+	// frontend renders "—" for nil and "$X.XX" when non-nil.
+	MonthlyCost      *float64  `json:"monthly_cost"`
 	EstimatedSavings float64   `json:"estimated_savings"`
 	Status           string    `json:"status"`
 }

internal/config/store_postgres.go

@@ -1405,6 +1405,7 @@ func (s *PostgresStore) queryPurchaseHistory(ctx context.Context, query string,
 	for rows.Next() {
 		var record PurchaseHistoryRecord
 		var planID, planName, cloudAccountID sql.NullString
+		var monthlyCost sql.NullFloat64
 
 		err := rows.Scan(
 			&record.AccountID,
@@ -1418,7 +1419,7 @@ func (s *PostgresStore) queryPurchaseHistory(ctx context.Context, query string,
 			&record.Term,
 			&record.Payment,
 			&record.UpfrontCost,
-			&record.MonthlyCost,
+			&monthlyCost,
 			&record.EstimatedSavings,
 			&planID,
 			&planName,
@@ -1429,6 +1430,13 @@ func (s *PostgresStore) queryPurchaseHistory(ctx context.Context, query string,
 			return nil, fmt.Errorf("failed to scan purchase history: %w", err)
 		}
 
+		// Handle nullable monthly_cost: nil means "provider did not return a
+		// monthly breakdown"; 0.0 means "explicitly $0 recurring charge".
+		if monthlyCost.Valid {
+			v := monthlyCost.Float64
+			record.MonthlyCost = &v
+		}
+
 		// Handle nullable strings
 		if planID.Valid {
 			record.PlanID = planID.String