Add burst compute billing meter

Author: Mohamed Habib

internal/api/capacity.go

@@ -249,11 +249,11 @@ func (s *Server) getCapacityBillableEvents(c echo.Context) error {
 
 	eventType := c.QueryParam("eventType")
 	switch eventType {
-	case "", db.BillableEventReservedUsage, db.BillableEventOverageUsage, db.BillableEventDiskOverageUsage:
+	case "", db.BillableEventReservedUsage, db.BillableEventOverageUsage, db.BillableEventBurstUsage, db.BillableEventDiskOverageUsage:
 		// ok
 	default:
 		return c.JSON(http.StatusBadRequest, map[string]string{
-			"error": "eventType must be one of reserved_usage, overage_usage, disk_overage_usage (or omitted for all)",
+			"error": "eventType must be one of reserved_usage, overage_usage, burst_usage, disk_overage_usage (or omitted for all)",
 		})
 	}
 

internal/billing/billable_events_sender.go

@@ -138,7 +138,7 @@ func (s *BillableEventsSender) shipOne(ctx context.Context, p db.PendingBillable
 }
 
 // meterEventNameFor maps an outbox event_type → Stripe meter event_name.
-// All three event types route to a single meter each — overage is flat
+// All event types route to a single meter each — overage and burst are flat
 // (the per-tier memory_mb on the outbox row is preserved for analytics
 // but ignored when shipping; Stripe sums GB-seconds across rows).
 func (s *BillableEventsSender) meterEventNameFor(eventType string, memoryMB int) (string, error) {
@@ -153,6 +153,11 @@ func (s *BillableEventsSender) meterEventNameFor(eventType string, memoryMB int)
 			return "", fmt.Errorf("overage meter not provisioned (run EnsureProducts)")
 		}
 		return s.stripe.OverageMeterEventName, nil
+	case db.BillableEventBurstUsage:
+		if s.stripe.BurstMeterEventName == "" {
+			return "", fmt.Errorf("burst meter not provisioned (run EnsureProducts)")
+		}
+		return s.stripe.BurstMeterEventName, nil
 	case db.BillableEventDiskOverageUsage:
 		if s.stripe.DiskOverageMeterEventName == "" {
 			return "", fmt.Errorf("disk overage meter not provisioned")

internal/billing/billable_events_sender_test.go

@@ -10,12 +10,13 @@ import (
 // meterEventNameFor pins the (event_type, memory_mb) → Stripe meter
 // routing. Overage is flat — memory_mb is preserved on the outbox row
 // for analytics but ignored at ship time so a 1 GB and 64 GB sandbox
-// hit the same meter.
+// hit the same meter. Burst is also flat, but routed to its own meter.
 
 func newSenderForTest() *BillableEventsSender {
 	stripe := &StripeClient{
 		ReservedMeterEventName:    "sandbox_compute_sandbox_reserved",
 		OverageMeterEventName:     "sandbox_compute_sandbox_overage",
+		BurstMeterEventName:       "sandbox_compute_sandbox_burst",
 		DiskOverageMeterEventName: "sandbox_compute_sandbox_disk_overage",
 	}
 	return &BillableEventsSender{stripe: stripe}
@@ -56,6 +57,17 @@ func TestSender_meterEventName_diskOverage(t *testing.T) {
 	}
 }
 
+func TestSender_meterEventName_burstFlat(t *testing.T) {
+	s := newSenderForTest()
+	got, err := s.meterEventNameFor(db.BillableEventBurstUsage, 0)
+	if err != nil {
+		t.Fatalf("err: %v", err)
+	}
+	if got != "sandbox_compute_sandbox_burst" {
+		t.Errorf("got %q", got)
+	}
+}
+
 func TestSender_meterEventName_unknownTypeRejected(t *testing.T) {
 	s := newSenderForTest()
 	_, err := s.meterEventNameFor("totally_made_up", 0)
@@ -74,6 +86,7 @@ func TestSender_meterEventName_missingProvisionRejected(t *testing.T) {
 	}{
 		{db.BillableEventReservedUsage, "reserved meter not provisioned"},
 		{db.BillableEventOverageUsage, "overage meter not provisioned"},
+		{db.BillableEventBurstUsage, "burst meter not provisioned"},
 		{db.BillableEventDiskOverageUsage, "disk overage meter not provisioned"},
 	}
 	for _, tc := range cases {

internal/billing/capacity_reconciler.go

@@ -14,7 +14,7 @@ import (
 // it scans for closed 15-min buckets that are at least `settle` past
 // their end and haven't been processed yet, runs the per-second
 // integration walk for each (org, bucket), and emits the resulting
-// reserved_usage / overage_usage / disk_overage_usage rows to the
+// reserved_usage / overage_usage / burst_usage / disk_overage_usage rows to the
 // `billable_events` outbox.
 //
 // Phase 2 runs in shadow: the rows are written but not delivered to
@@ -152,6 +152,7 @@ func (r *CapacityReconciler) processBucket(ctx context.Context, orgID uuid.UUID,
 // is org-level, summed across all running events at each segment.
 type BucketTotals struct {
 	OverageGBSecondsByTier map[int]float64
+	BurstGBSeconds         float64
 	DiskOverageGBSeconds   float64
 	ReservedFloorGBSeconds float64 // reservedGb × secs accumulated across segments — for shadow validation only
 }
@@ -176,6 +177,7 @@ type clippedEvent struct {
 	From, To time.Time
 	TierMB   int
 	DiskMB   int
+	Burst    bool
 }
 
 // clipEvent restricts a ScaleEvent's lifetime to the bucket window.
@@ -192,7 +194,7 @@ func clipEvent(e db.ScaleEvent, bucketStart, bucketEnd time.Time) (clippedEvent,
 	if !to.After(from) {
 		return clippedEvent{}, false
 	}
-	return clippedEvent{From: from, To: to, TierMB: e.MemoryMB, DiskMB: e.DiskMB}, true
+	return clippedEvent{From: from, To: to, TierMB: e.MemoryMB, DiskMB: e.DiskMB, Burst: e.Burst}, true
 }
 
 func collectBoundaries(events []clippedEvent, bucketStart, bucketEnd time.Time) []time.Time {
@@ -216,9 +218,10 @@ func collectBoundaries(events []clippedEvent, bucketStart, bucketEnd time.Time)
 }
 
 type segment struct {
-	From, To       time.Time
-	RunningByTier  map[int]int // tier_mb → running GB at this tier
-	DiskOverageMB  int         // sum of (disk_mb − 20480) over running events
+	From, To      time.Time
+	RunningByTier map[int]int // non-burst tier_mb → running GB at this tier
+	BurstGB       int
+	DiskOverageMB int // sum of (disk_mb − 20480) over running events
 }
 
 func walkSegments(boundaries []time.Time, events []clippedEvent) []segment {
@@ -229,20 +232,26 @@ func walkSegments(boundaries []time.Time, events []clippedEvent) []segment {
 			continue
 		}
 		tiers := map[int]int{}
+		burstGB := 0
 		diskOver := 0
 		for _, e := range events {
 			// Event is "running" in [from, to) if it covers the segment
 			// fully — i.e. e.From <= from AND e.To >= to. Since the
 			// boundary set includes every event endpoint, every segment
 			// is fully contained in any event whose span covers `from`.
 			if !e.From.After(from) && !e.To.Before(to) {
-				tiers[e.TierMB] += e.TierMB / 1024
+				gb := e.TierMB / 1024
+				if e.Burst {
+					burstGB += gb
+				} else {
+					tiers[e.TierMB] += gb
+				}
 				if e.DiskMB > 20480 {
 					diskOver += e.DiskMB - 20480
 				}
 			}
 		}
-		segs = append(segs, segment{From: from, To: to, RunningByTier: tiers, DiskOverageMB: diskOver})
+		segs = append(segs, segment{From: from, To: to, RunningByTier: tiers, BurstGB: burstGB, DiskOverageMB: diskOver})
 	}
 	return segs
 }
@@ -251,6 +260,10 @@ func integrateSegments(segs []segment, reservedGB int) BucketTotals {
 	out := BucketTotals{OverageGBSecondsByTier: map[int]float64{}}
 	for _, s := range segs {
 		secs := s.To.Sub(s.From).Seconds()
+		if s.BurstGB > 0 {
+			out.BurstGBSeconds += float64(s.BurstGB) * secs
+		}
+
 		usage := 0
 		for _, gb := range s.RunningByTier {
 			usage += gb
@@ -281,7 +294,9 @@ func integrateSegments(segs []segment, reservedGB int) BucketTotals {
 //     actual usage — the customer paid for the floor whether or not
 //     they used it).
 //   - overage_usage   — one row per (org, sandbox_tier, bucket) where
-//     the tier's overage contribution is non-zero.
+//     the non-burst tier's overage contribution is non-zero.
+//   - burst_usage — one row per (org, bucket) when burst sandboxes ran.
+//     Burst is billed independently and does not consume reserved floors.
 //   - disk_overage_usage — one row per (org, bucket) when any sandbox
 //     in the bucket exceeded the 20 GB allowance.
 //
@@ -319,6 +334,20 @@ func emitBucket(ctx context.Context, store *db.Store, orgID uuid.UUID, bucketSta
 		}
 	}
 
+	if totals.BurstGBSeconds > 0 {
+		ev := db.BillableEvent{
+			OrgID:       orgID,
+			EventType:   db.BillableEventBurstUsage,
+			MemoryMB:    0,
+			GBSeconds:   totals.BurstGBSeconds,
+			BucketStart: bucketStart,
+			BucketEnd:   bucketEnd,
+		}
+		if _, err := store.UpsertBillableEvent(ctx, ev); err != nil {
+			return err
+		}
+	}
+
 	if totals.DiskOverageGBSeconds > 0 {
 		ev := db.BillableEvent{
 			OrgID:       orgID,

internal/billing/capacity_reconciler_test.go

@@ -66,6 +66,19 @@ func TestIntegrateBucket_zeroReservation_replaysLegacy(t *testing.T) {
 	}
 }
 
+func TestIntegrateBucket_burstUsageSeparateFromOverage(t *testing.T) {
+	bs, be := canonicalBucket()
+	totals := IntegrateBucket(bs, be, 8, []db.ScaleEvent{
+		{MemoryMB: 8192, DiskMB: 20480, Burst: true, StartedAt: bs, EndedAt: &be},
+		{MemoryMB: 8192, DiskMB: 20480, StartedAt: bs, EndedAt: &be},
+	})
+	eq(t, "burst", totals.BurstGBSeconds, 8*900)
+	eq(t, "reserved floor", totals.ReservedFloorGBSeconds, 8*900)
+	if len(totals.OverageGBSecondsByTier) != 0 {
+		t.Errorf("expected burst to stay out of overage, got %v", totals.OverageGBSecondsByTier)
+	}
+}
+
 func TestIntegrateBucket_fullCoverage_noOverage(t *testing.T) {
 	bs, be := canonicalBucket()
 	// One 8 GB sandbox, reservation covers it.

internal/billing/pricing.go

@@ -54,8 +54,8 @@ var TierPriceKey = map[int]string{
 // full lifetime of the sandbox (running OR hibernated, since the workspace
 // qcow2 still occupies host disk).
 const (
-	DiskFreeAllowanceMB            = 20480      // 20GB included with every sandbox
-	DiskOveragePricePerGBPerSecond = 0.0000001  // ~$0.26 per GB-month
+	DiskFreeAllowanceMB            = 20480     // 20GB included with every sandbox
+	DiskOveragePricePerGBPerSecond = 0.0000001 // ~$0.26 per GB-month
 	DiskOverageMetadataKey         = "sandbox_disk_overage"
 )
 
@@ -68,6 +68,8 @@ const (
 //     reserve capacity pay this.
 //   - Overage: customer-facing name "instant." Flat per-GB rate
 //     regardless of sandbox tier.
+//   - Burst: customer-facing name "burst." Flat per-GB rate for
+//     restartable burst sandboxes, independent of reserved capacity.
 //
 // **Dollar rates are deliberately not in code.** Stripe Prices are
 // configured in the Stripe Dashboard (or via Stripe API by the
@@ -92,6 +94,10 @@ const (
 	// Instant (overage): single meter, flat across all sandbox sizes.
 	OverageMeterKey = "sandbox_overage"
 	OveragePriceKey = "sandbox_overage_v1"
+
+	// Burst: single meter, flat across all sandbox sizes.
+	BurstMeterKey = "sandbox_burst"
+	BurstPriceKey = "sandbox_burst_v1"
 )
 
 // DiskOverageGBSeconds returns the chargeable GB-seconds for one usage summary

internal/billing/stripe.go

@@ -32,17 +32,19 @@ type StripeClient struct {
 	MeterEventNames map[int]string
 
 	// Disk overage meter / price (single dimension: GB-seconds above 20GB).
-	DiskOveragePriceID       string
+	DiskOveragePriceID        string
 	DiskOverageMeterEventName string
 
-	// Phase-3 unified-pipeline meters and prices. Two flat meters
-	// (overage + reserved) used by new orgs (`billing_mode='unified'`).
+	// Phase-3 unified-pipeline meters and prices. Flat meters
+	// (overage + reserved + burst) used by new orgs (`billing_mode='unified'`).
 	// Legacy per-tier meters above are untouched and continue to serve
 	// existing orgs via UsageReporter.
 	OveragePriceID         string // flat overage Price for `overage_usage` events
 	OverageMeterEventName  string // "sandbox_compute_sandbox_overage"
 	ReservedPriceID        string // flat reserved Price for `reserved_usage` events
 	ReservedMeterEventName string // "sandbox_compute_sandbox_reserved"
+	BurstPriceID           string // flat burst Price for `burst_usage` events
+	BurstMeterEventName    string // "sandbox_compute_sandbox_burst"
 
 	// Per-agent paywalled-feature prices. Configured from env and
 	// referenced by name from the dashboard subscribe handlers. Empty
@@ -236,8 +238,8 @@ func (s *StripeClient) EnsureProducts() error {
 		log.Printf("billing: created disk overage price (id=%s)", p.ID)
 	}
 
-	// 5. Phase-3 unified-pipeline meters. Two flat meters (overage +
-	//    reserved) at unit GB-seconds. Code creates the *meters* (their
+	// 5. Phase-3 unified-pipeline meters. Flat meters (overage, reserved,
+	//    and burst) at unit GB-seconds. Code creates the *meters* (their
 	//    event names are stable wire-protocol coupling) but **does not
 	//    create Prices** — those are configured in the Stripe Dashboard
 	//    so pricing changes don't need a code deploy. The Price IDs
@@ -246,6 +248,7 @@ func (s *StripeClient) EnsureProducts() error {
 	//    linked to the meter in Stripe.
 	s.OverageMeterEventName = ensureMeter(existingMeters, "sandbox_compute_"+OverageMeterKey, "Sandbox Instant Compute (GB-seconds)")
 	s.ReservedMeterEventName = ensureMeter(existingMeters, "sandbox_compute_"+ReservedMeterKey, "Sandbox Reserved Capacity (GB-seconds)")
+	s.BurstMeterEventName = ensureMeter(existingMeters, "sandbox_compute_"+BurstMeterKey, "Sandbox Burst Compute (GB-seconds)")
 
 	if id, ok := existingPrices[OveragePriceKey]; ok {
 		s.OveragePriceID = id
@@ -259,6 +262,12 @@ func (s *StripeClient) EnsureProducts() error {
 	} else {
 		log.Printf("billing: no reserved price configured for meter %s — meter events will flow but won't appear on invoices until a Price is created in Stripe", s.ReservedMeterEventName)
 	}
+	if id, ok := existingPrices[BurstPriceKey]; ok {
+		s.BurstPriceID = id
+		log.Printf("billing: found existing burst price (id=%s)", id)
+	} else {
+		log.Printf("billing: no burst price configured for meter %s — meter events will flow but won't appear on invoices until a Price is created in Stripe", s.BurstMeterEventName)
+	}
 
 	return nil
 }

internal/db/billable_events.go

@@ -19,9 +19,10 @@ import (
 // Event types written to billable_events.event_type. Mirror the schema
 // CHECK constraint in migration 030.
 const (
-	BillableEventReservedUsage     = "reserved_usage"
-	BillableEventOverageUsage      = "overage_usage"
-	BillableEventDiskOverageUsage  = "disk_overage_usage"
+	BillableEventReservedUsage    = "reserved_usage"
+	BillableEventOverageUsage     = "overage_usage"
+	BillableEventBurstUsage       = "burst_usage"
+	BillableEventDiskOverageUsage = "disk_overage_usage"
 )
 
 // Delivery states. Mirror the schema CHECK constraint in migration 030.
@@ -33,22 +34,23 @@ const (
 
 // BillableEvent is one outbox row.
 //
-// `MemoryMB` is 0 for `reserved_usage` and `disk_overage_usage` (sentinel
-// for "not a sandbox tier"), and the running sandbox tier for
+// `MemoryMB` is 0 for `reserved_usage`, `burst_usage`, and
+// `disk_overage_usage` (sentinel for "not a sandbox tier"), and the
+// running sandbox tier for
 // `overage_usage` (one row per tier per bucket via the proportional split
 // rule — see ws-pricing/work/001 "Per-second integration walk").
 type BillableEvent struct {
-	ID             uuid.UUID  `json:"id"`
-	OrgID          uuid.UUID  `json:"orgId"`
-	EventType      string     `json:"eventType"`
-	MemoryMB       int        `json:"memoryMB"`
-	GBSeconds      float64    `json:"gbSeconds"`
-	BucketStart    time.Time  `json:"bucketStart"`
-	BucketEnd      time.Time  `json:"bucketEnd"`
-	DeliveryState  string     `json:"deliveryState"`
-	StripeEventID  *string    `json:"stripeEventId,omitempty"`
-	CreatedAt      time.Time  `json:"createdAt"`
-	DeliveredAt    *time.Time `json:"deliveredAt,omitempty"`
+	ID            uuid.UUID  `json:"id"`
+	OrgID         uuid.UUID  `json:"orgId"`
+	EventType     string     `json:"eventType"`
+	MemoryMB      int        `json:"memoryMB"`
+	GBSeconds     float64    `json:"gbSeconds"`
+	BucketStart   time.Time  `json:"bucketStart"`
+	BucketEnd     time.Time  `json:"bucketEnd"`
+	DeliveryState string     `json:"deliveryState"`
+	StripeEventID *string    `json:"stripeEventId,omitempty"`
+	CreatedAt     time.Time  `json:"createdAt"`
+	DeliveredAt   *time.Time `json:"deliveredAt,omitempty"`
 }
 
 // UpsertBillableEvent inserts a new outbox row, or no-ops if a row with
@@ -304,7 +306,18 @@ func (s *Store) GetReservedGBForBucket(ctx context.Context, orgID uuid.UUID, buc
 // metering. See the same NOT EXISTS in GetOrgUsage for rationale.
 func (s *Store) GetScaleEventsForBucket(ctx context.Context, orgID uuid.UUID, bucketStart, bucketEnd time.Time) ([]ScaleEvent, error) {
 	rows, err := s.pool.Query(ctx, `
-		SELECT id, sandbox_id, org_id, memory_mb, cpu_percent, disk_mb, started_at, ended_at
+		SELECT id, sandbox_id, org_id, memory_mb, cpu_percent, disk_mb,
+		       EXISTS (
+		         SELECT 1
+		         FROM sandbox_sessions ss
+		         WHERE ss.sandbox_id = se.sandbox_id
+		           AND (
+		             COALESCE((ss.config->>'burst')::boolean, false)
+		             OR COALESCE((ss.config->>'resumable')::boolean, false)
+		             OR ss.config->>'sandboxFamily' IN ('spot', 'resumable', 'burst')
+		           )
+		       ) AS burst,
+		       started_at, ended_at
 		FROM sandbox_scale_events se
 		WHERE org_id = $1
 		  AND started_at < $3
@@ -330,7 +343,7 @@ func (s *Store) GetScaleEventsForBucket(ctx context.Context, orgID uuid.UUID, bu
 	for rows.Next() {
 		var e ScaleEvent
 		var orgUUID uuid.UUID
-		if err := rows.Scan(&e.ID, &e.SandboxID, &orgUUID, &e.MemoryMB, &e.CPUPct, &e.DiskMB, &e.StartedAt, &e.EndedAt); err != nil {
+		if err := rows.Scan(&e.ID, &e.SandboxID, &orgUUID, &e.MemoryMB, &e.CPUPct, &e.DiskMB, &e.Burst, &e.StartedAt, &e.EndedAt); err != nil {
 			return nil, fmt.Errorf("scan scale event: %w", err)
 		}
 		e.OrgID = orgUUID.String()

internal/db/migrations/030_billable_events.up.sql

@@ -13,6 +13,8 @@
 --   'overage_usage'       — instant usage above the reserved floor,
 --                           emitted per running sandbox tier with the
 --                           tier as memory_mb
+--   'burst_usage'         — burst sandbox compute, billed as GB-seconds
+--                           independent of reserved capacity; memory_mb = 0
 --   'disk_overage_usage'  — disk above the 20 GB allowance, org-level
 --                           per bucket; memory_mb = 0
 CREATE TABLE IF NOT EXISTS billable_events (
@@ -28,7 +30,7 @@ CREATE TABLE IF NOT EXISTS billable_events (
     created_at          TIMESTAMPTZ NOT NULL DEFAULT now(),
     delivered_at        TIMESTAMPTZ,
     UNIQUE (org_id, event_type, memory_mb, bucket_start),
-    CHECK (event_type IN ('reserved_usage', 'overage_usage', 'disk_overage_usage')),
+    CHECK (event_type IN ('reserved_usage', 'overage_usage', 'burst_usage', 'disk_overage_usage')),
     CHECK (delivery_state IN ('pending', 'sent', 'failed')),
     CHECK (gb_seconds > 0),
     CHECK (memory_mb >= 0),