Live computation, not stored

ARCHITECTURE: LIVE COMPUTATION:

  Read budget detail
    ↓
  SELECT SUM(costColumn(hasBilling))
  FROM cost_records
  WHERE (scope matches budget's filter)
    AND (date in current budget period)
    ↓
  Return the sum

ARCHITECTURE NOT USED: STORED CURRENT_SPEND:
  Cron writes current_spend_usd column periodically
  Read budget → return stored value
  (this approach was used in v2; dropped April 2026)

1. ACCURACY
   Always current. No stale data. New cost records show up in the
   budget reading immediately (next read).
   Stored values lag by however long the last cron ran.

2. SIMPLICITY
   One source of truth (cost_records). No sync logic.
   Stored values require maintenance:
     - When cost records change, recompute
     - When scope changes, recompute
     - Handle race conditions during recompute
     - Detect and reconcile drift
     None of this exists in the live-compute model.

3. FLEXIBILITY
   Easy to compute any scope. New filters work immediately.
   Stored would require materialized columns for every possible
   filter combination: impractical at scale.

4. CORRECTNESS
   No drift. The computation matches what reports show.
   Stored values can diverge from actuals (rare, but possible
   bugs cause this; we eliminate the class of bug entirely).

TYPICAL BUDGET READ COSTS (with proper indexing):

  Per-resource budget:    ~5 ms   (single resource_uid filter)
  Per-group budget:       ~10-25 ms (small to medium group)
  Per-team budget:         ~10-50 ms (most teams; tag-indexed)
  Org-wide rollup:         ~50-150 ms (full table scan with date filter)

DASHBOARD with 12 budget widgets: ~200-400 ms total
  Fast enough for sub-second page renders.

STORED-COLUMN READ COSTS:
  Per budget read: 1-2 ms (single row read)

  But: more complex sync logic
       Stored values lag behind actuals by minutes-to-hours
       Re-computation on scope change adds latency to write

costColumn(hasBilling):
  hasBilling = true   →  COALESCE(actual_cost_usd, cost_usd)
  hasBilling = false  →  cost_usd

1. SPEND UPDATES IMMEDIATELY when new cost records land
   - Hourly: discovery cron writes new rack-rate cost records
   - 24h: billing sync updates actual_cost_usd
   - In both cases, next budget read picks up the new value
   - Budget transitions from green to yellow to red as data arrives;
     no batch processing delay

2. COST SOURCE LABEL visible on budget detail
   - "Computed from billed cost" (mostly billing data; ideal)
   - "Computed from rack rate" (only calculated; pre-billing-sync
     setup or sync paused)
   - "Mixed" (some billing data, some rack rate)
   - The label lets the user know which cost column is in play

3. BUDGET CHANGES TAKE EFFECT IMMEDIATELY
   - New threshold added: next read evaluates against the new threshold
   - Scope changed (added a resource group): next read includes the
     new scope
   - No stored spend to "recompute": there is nothing to migrate;
     the next read uses the new scope

NOTIFICATION CRON (runs hourly):

  For each active budget:
    spend = live_compute_spend(budget)
    threshold_crossings = check_thresholds(spend, last_known_spend)

    For each newly-crossed threshold:
      fire_notification(threshold, channels)
      record(audit_log, threshold_crossing)

    Update budget.last_known_spend = spend
      (this is the only "stored" value: it's a "did we already
       notify on this threshold?" flag, not the spend itself)

MIGRATION (2026-04-30):
  1. PR #1078: convert all budget reads to live computation
              Validate against the stored value (parity check)
              No customer-visible change

  2. PR #1108: drop the stored column from the schema
              Remove the cron that maintained it
              Simplify the budget service code

CUSTOMER IMPACT: zero
  Reads use the same underlying cost data, just computed live.
  Performance is comparable (within 50 ms).
  Accuracy improved (no stale-data window).
  Audit log is unchanged.

LIVE COMPUTE BREAKS DOWN if:
  - Underlying data is very expensive to query (billion-row scans
    without indexing)
  - Aggregation is recursive or graph-walking
  - Realtime requirement is sub-millisecond (it's not for budgets)

For ZopNight's cost_records table:
  - Indexed appropriately; queries hit indices
  - Aggregation is straightforward SUM with date + scope filter
  - 50 ms is fine for budgets

So live compute is the right answer here.

SCENARIO: Customer adjusts a budget's scope mid-period.

T+0       Open budget detail
          Current spend: $4,200 (live computed)
          Scope: dev-platform-eu group

T+30 s    Click Edit; change scope to:
          dev-platform-eu group + staging-eu group
          (adding a second group to the scope)

T+45 s    Save the change

T+46 s    Refresh the budget detail page
          Recomputed live: spend = $6,800
          (new scope includes the additional group's spend)

NO BATCH delay. NO cron wait. NO migration job to rerun current_spend_usd.

This works because:
  - The budget definition stores the scope filter
  - Every read evaluates the filter against cost_records
  - No stored value to refresh
  - The change takes effect at read time, not write time

CONTRAST with stored-column architecture:
  - Save would trigger a recompute job
  - User refreshes; sees stale value until job completes
  - User wonders if the change took effect
  - Possible race condition between recompute and read

1. Open any budget in your org
   Current spend (note value): $__________
   Cost source label: __________ (billed / rack rate / mixed)

2. Wait an hour (or come back tomorrow)
   Refresh the budget detail
   Has the spend value changed? Yes / No
   New value: $__________

3. If your billing sync just completed (or if it's been > 24h),
   the cost source label may have changed from "rack rate" to
   "billed" for the most recent days. Note any change.

4. Audit observation:
   Did the budget transition green/yellow/red during the period?
   __________

5. Architectural check:
   Open the API endpoint /v1/budgets/{your-budget-id}
   The response should include the same computed spend
   API response: $__________  (matches UI? yes / no)