// Console-side read path for unit economics: assembling what the operator
// /fleet/economics dashboard (Task 13) renders out of sweepUsage's per-day
// accumulation (economicspass.go), an active pricing scenario
// (internal/economics), and the two most recent real bills. Like
// metricsview.go this is a bucket sweep plus an in-process cache — nothing
// here writes anything.
package console

import (
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"html/template"
	"log"
	"os"
	"sort"
	"strings"
	"sync"
	"time"

	"github.com/carlosframework/platform/internal/economics"
	"github.com/carlosframework/platform/internal/registry"
	"github.com/carlosframework/platform/internal/usage"
)

// economicsCacheTTL/economicsStaleServeCeiling/economicsSweepTimeout mirror
// metricsview.go's metricsCacheTTL/metricsStaleServeCeiling/
// metricsSweepTimeout exactly (same 60s freshness window, same 2-minute
// stale-while-revalidate ceiling) — see those constants' doc comments for
// the full reasoning, which applies here unchanged: LoadEconomics is called
// from the same kind of per-request path (the dashboard page) and must not
// make every request pay for a fresh bucket sweep.
const (
	economicsCacheTTL          = 60 * time.Second
	economicsStaleServeCeiling = 2 * time.Minute
	economicsSweepTimeout      = 15 * time.Second
)

// EconomicsView is one priced period, ready to render.
type EconomicsView struct {
	GeneratedAt time.Time
	Period      string
	Scenario    economics.Scenario // active (bucket) or DefaultScenario fallback
	// ScenarioWarning is set when active.json named a scenario that could
	// not be loaded/parsed/validated — never set when active.json is simply
	// absent (a fresh deployment, not a fault; see loadActiveScenario).
	ScenarioWarning string
	// Warning is set when the SWEEP itself degraded — currently only "no
	// registry configured/reachable", which makes every sampled unit
	// attribute to release.OpsAccount instead of its real account (see
	// loadRoutesForEconomics). Distinct from ScenarioWarning: the two can
	// both be set at once and Task 13 renders them as separate notices.
	Warning                 string
	Scenarios               []string                      // names under economics/scenarios/
	Accounts                []economics.AccountEconomics  // priced under Scenario, sorted by CostUSD desc, Account asc on ties
	Meters                  map[string]map[string]float64 // account -> meter (for embedding)
	Boxes                   []BoxEconomics
	Bills                   []economics.Bill // this month + previous, if present
	CoveredDays, PeriodDays int
	// DaysInMonth is the CURRENT real calendar month's length (statementsPass's
	// own daysInMonth derivation: time.Date(y, mo+1, 0, ...).Day()) —
	// deliberately NOT PeriodDays, which on "mtd" is only the number of days
	// elapsed so far this month. economics.Project's mtd->full-month
	// projection needs the FULL month's length as its target denominator's
	// mate; PeriodDays there would make the projected figure equal plain MTD
	// whenever coverage is complete, which is a labelled projection that
	// doesn't project (the honesty rule's whole point). Populated on every
	// view regardless of Period — only "mtd" ever renders it.
	DaysInMonth int
	DataJSON    template.JS // the embedded payload — see economicsPayload
	// Tiers is every live account's fleet-pool tier, keyed by sqid (Store.
	// AccountTiers, Task 4) — Task 6's econAccountRow reads it at render.
	// An account absent from this map (usage with no console row at all,
	// e.g. a fleet-only account whose owner never signed up) carries pool
	// semantics, same as an account present with the explicit "" tier — see
	// tierOf. Shared, read-only, like Scenario/Boxes/Bills — see
	// copyEconomicsView's doc comment.
	Tiers map[string]string
	// Names is every live account's display name, keyed by sqid (the SAME
	// s.store.Accounts() read buildEconomicsView already performs to build
	// the universe/Tiers, Account.Sqid -> Account.Name) — account-names
	// batch. Display + search only: the join/key universe (meters,
	// statements, tiers, cursors, form values) stays sqid-shaped everywhere
	// unchanged; this map exists purely so the render layer can show a
	// human name next to the sqid it already has. An account absent from
	// this map (usage with no matching console account row at all, e.g. a
	// fleet-only account whose owner never signed up) has no name to show —
	// same "index returns the zero value" shape as Tiers/tierOf, and the
	// render layer falls back to the bare sqid for it, exactly as before
	// this map existed. Shared, read-only, like Scenario/Boxes/Bills/Tiers
	// — see copyEconomicsView's doc comment; gets no defensive copy of its
	// own for the same reason Tiers doesn't.
	Names map[string]string
	// Pool is this period's fleet-pool ledger (Task 5) — see PoolLedger.
	Pool PoolLedger
}

// PoolLedger is one period's fleet-pool revenue-sharing standing: how much
// the pool holds (a share of paying revenue plus a day-accrued monthly
// top-up — see poolTopupAccrual), how much pool-tier accounts have drawn
// against it in cost, and the headroom between the two — which MAY be
// negative (the pool is overdrawn this period) and must be rendered
// honestly, not clamped to zero. See buildEconomicsView's doc comment for
// the exact formula; the
// dashboard's inline knob JS (Task 6) recomputes this same ledger
// client-side from DataJSON's "tiers"/"scenario"/"meters" rather than this
// struct being marshalled itself — nothing here carries a json tag.
type PoolLedger struct {
	PoolUSD, DrawUSD, HeadroomUSD float64
	PayingRevenueUSD              float64 // the revenue the frac applies to
}

// BoxEconomics is one box, priced under Scenario over the period.
type BoxEconomics struct {
	Box           string
	Hours         float64
	CostUSD       float64
	IdleUSD       float64
	RevenueUSD    float64 // Σ over tenants: their revenue × (this box's allocated share / their total allocated cost)
	Utilization   float64 // 1 - IdleUSD/CostUSD (0 when CostUSD is 0)
	EgressMetered bool
}

// economicsPayload is DataJSON's shape: everything Task 13's inline knob JS
// needs to redo AllocateBox/PriceAccount client-side when an operator tweaks
// a scenario knob live, without a server round trip. Field names are frozen
// by that JS — change both together (economics.go's PriceAccount doc carries
// the same warning for the pricing formulas themselves). Every field,
// including the nested economics.BoxLoad/BoxAccountLoad values inside
// BoxLoads, carries an explicit snake_case json tag (compute.go) — one
// convention for the whole payload, not a mix of Go field names and
// snake_case. json.Marshal HTML-escapes '<', '>' and '&' by default (unlike
// an Encoder with SetEscapeHTML(false)) — that default is exactly what
// keeps this safe to embed inside a literal <script> block, so it must stay
// in effect: never swap this for an Encoder with escaping turned off.
type economicsPayload struct {
	Scenario    economics.Scenario            `json:"scenario"`
	Meters      map[string]map[string]float64 `json:"meters"`
	BoxLoads    map[string]economics.BoxLoad  `json:"boxLoads"`
	BoxSpecs    map[string]economics.BoxSpec  `json:"boxSpecs"`
	Bills       []economics.Bill              `json:"bills"`
	CoveredDays int                           `json:"coveredDays"`
	PeriodDays  int                           `json:"periodDays"`
	// DaysInMonth mirrors EconomicsView.DaysInMonth (this struct's doc
	// comment above explains why it must NOT be confused with PeriodDays) —
	// additive key, the JS twin of the Go-side project() call's third
	// argument.
	DaysInMonth int `json:"daysInMonth"`
	// Tiers mirrors EconomicsView.Tiers (Task 5) — additive key. The pool
	// ledger itself is NOT part of this payload: "pool" scenario knobs
	// already travel inside Scenario above, so the JS twin recomputes
	// PoolLedger client-side from Tiers + Scenario.Pool + Meters the same
	// way buildEconomicsView does (Task 6), rather than this struct
	// shipping a second, potentially stale copy of the same numbers.
	Tiers map[string]string `json:"tiers"`
	// Names mirrors EconomicsView.Names (account-names batch) — additive
	// key, sqid -> display name, for any client-side rendering that wants a
	// human name next to a sqid without a server round trip. Nothing in
	// econ_maths_js reads it today (the recompute paths key everything by
	// sqid, per the join/key universe staying sqid-shaped — see
	// EconomicsView.Names's own doc comment); it travels here purely for
	// parity with how "tiers" already does, and so it's available the
	// moment a future knob-drawer feature wants it.
	Names map[string]string `json:"names"`
	// PoolTopupUnitAccrual is Σ 1/daysInMonth(d) over [from, to] — the same
	// per-day sum poolTopupAccrual folds against Scenario.Pool.TopupUSD
	// server-side, but with topupUSD fixed at 1 so it carries no dollar
	// value of its own: poolTopupAccrual(from, to, x) == x *
	// PoolTopupUnitAccrual for any x, by that function's own linearity (each
	// day contributes topupUSD/daysInMonth(that day), so scaling topupUSD
	// scales the whole sum). The JS twin (econ_maths_js's poolLedger)
	// multiplies this dimensionless figure by whatever topup_usd the
	// operator's live knob currently reads, reproducing poolTopupAccrual
	// EXACTLY under any knob value with no client-side re-derivation of the
	// per-day loop — the carried ruling (Task 6 review) this field exists to
	// satisfy: the alternative (shipping the accrued DOLLAR figure for the
	// knob's STARTING value and trying to rescale it) breaks at
	// oldTopup==0, this doesn't. Additive key.
	PoolTopupUnitAccrual float64 `json:"poolTopupUnitAccrual"`
}

// economicsCacheEntry is one period's cached sweep — the metricsCache
// pattern (metricsview.go:187-338) copied per period rather than once: mu
// guards the fields and is never held across bucket IO; sweeping/done
// serialise the IO instead, so a cold sweep for "mtd" never blocks a caller
// asking for "last". See metricsCache's doc comment for the full reasoning
// behind every field here — it applies verbatim, just keyed by period.
type economicsCacheEntry struct {
	mu       sync.Mutex
	at       time.Time
	view     *EconomicsView
	sweeping bool
	done     chan struct{}
}

// economicsCache holds one economicsCacheEntry per period ("mtd", "last",
// "7d") — a small map rather than three named fields, since LoadEconomics
// normalizes any period string to one of those three before ever touching
// the cache (normalizeEconomicsPeriod), so the map never grows past three
// entries. entries itself is guarded by mu; each entry's own mu guards that
// entry's fields, exactly as metricsCache guards its single set.
type economicsCache struct {
	mu      sync.Mutex
	entries map[string]*economicsCacheEntry
}

// entry returns the stable cache slot for period, creating it on first use.
func (s *Server) economicsCacheEntry(period string) *economicsCacheEntry {
	c := &s.economicsCache
	c.mu.Lock()
	defer c.mu.Unlock()
	if c.entries == nil {
		c.entries = map[string]*economicsCacheEntry{}
	}
	e := c.entries[period]
	if e == nil {
		e = &economicsCacheEntry{}
		c.entries[period] = e
	}
	return e
}

// normalizeEconomicsPeriod maps any unrecognized period string to "mtd" —
// the brief's default, and the shape that keeps the cache map bounded to
// exactly three entries regardless of what a caller passes.
func normalizeEconomicsPeriod(period string) string {
	switch period {
	case "mtd", "last", "7d":
		return period
	default:
		return "mtd"
	}
}

// economicsPeriodBounds turns a normalized period into a [from, to] range,
// evaluated against now: "mtd" is the first of this month through now;
// "last" is the WHOLE previous calendar month; "7d" is now-7d through now.
// Previous-month arithmetic goes through the first of THIS month rather than
// now.AddDate(0, -1, 0) directly, to dodge time.AddDate's day-overflow
// behaviour (e.g. Mar 31 minus one month normalizing to Mar 3, not Feb 28) —
// day 1 never overflows.
func economicsPeriodBounds(period string, now time.Time) (from, to time.Time) {
	now = now.UTC()
	firstOfThisMonth := time.Date(now.Year(), now.Month(), 1, 0, 0, 0, 0, time.UTC)
	switch period {
	case "last":
		firstOfLastMonth := firstOfThisMonth.AddDate(0, -1, 0)
		lastOfLastMonth := firstOfThisMonth.AddDate(0, 0, -1)
		return firstOfLastMonth, lastOfLastMonth
	case "7d":
		return now.AddDate(0, 0, -7), now
	default: // "mtd"
		return firstOfThisMonth, now
	}
}

// LoadEconomics prices usage over period ("mtd" default, "last", "7d") under
// the active scenario, caching the result per period in-process — the same
// three-state freshness logic as LoadMetrics (metricsview.go:257-338):
// FRESH within economicsCacheTTL returns immediately; STALE-WITHIN-CEILING
// (past the TTL but within economicsStaleServeCeiling) also returns
// immediately and kicks a background refresh; COLD or STALE-PAST-THE-CEILING
// blocks for a real sweep and surfaces its error. See LoadMetrics's doc
// comment for the full reasoning — it applies here verbatim, just against a
// per-period cache entry instead of one shared cache.
//
// The returned *EconomicsView is otherwise READ-ONLY: it (or its unexported
// twin) is shared with the in-process cache and any other concurrent caller
// of the same period. copyEconomicsView gives each caller its own Accounts
// backing array and top-level Meters map specifically so a caller may
// freely sort.Slice(view.Accounts, ...) or add/remove top-level Meters
// entries without racing the cache or another caller doing the same —
// Task 13's dashboard sort is the motivating case. Every OTHER field
// (Scenario, Boxes, Bills, Scenarios, DataJSON, Tiers, Names, Pool, ...) is
// still shared: treat those, and the inner per-account meter maps Meters'
// values point at, as immutable. Tiers (Task 5) and Names (account-names
// batch) are both read-only exactly like Scenario or Bills — nothing
// mutates either after buildEconomicsView returns, so neither gets a
// defensive copy of its own. Pool is a plain value struct
// (PoolLedger), copied for free by copyEconomicsView's `cp := *v`, same as
// every other non-pointer, non-slice, non-map field on EconomicsView.
func (s *Server) LoadEconomics(ctx context.Context, period string) (*EconomicsView, error) {
	period = normalizeEconomicsPeriod(period)
	c := s.economicsCacheEntry(period)
	for {
		c.mu.Lock()
		if !c.at.IsZero() && time.Since(c.at) < economicsCacheTTL {
			view := c.view
			c.mu.Unlock()
			return copyEconomicsView(view), nil
		}
		if !c.at.IsZero() && time.Since(c.at) <= economicsStaleServeCeiling {
			view := c.view
			if !c.sweeping {
				s.startBackgroundEconomicsSweep(c, period)
			}
			c.mu.Unlock()
			return copyEconomicsView(view), nil
		}
		if c.sweeping {
			wait := c.done
			c.mu.Unlock()
			select {
			case <-wait:
				continue
			case <-ctx.Done():
				return nil, ctx.Err()
			}
		}
		c.sweeping = true
		c.done = make(chan struct{})
		done := c.done
		c.mu.Unlock()

		var (
			view *EconomicsView
			err  = errors.New("console: economics sweep did not complete")
		)
		func() {
			defer func() {
				c.mu.Lock()
				if err == nil {
					c.at = time.Now()
					c.view = view
				}
				c.sweeping = false
				close(done)
				c.mu.Unlock()
			}()
			view, err = s.buildEconomicsView(ctx, period)
		}()

		if err != nil {
			return nil, err
		}
		return copyEconomicsView(view), nil
	}
}

// copyEconomicsView returns a shallow copy of v safe for a caller to sort or
// otherwise rearrange in place without racing the cache: Accounts gets a
// fresh backing array (Task 14's dashboard sorts it) and Meters gets a fresh
// top-level map (inner per-account maps are still shared by reference —
// cheap at this size, and no known caller rewrites a meter value in place
// rather than reading it). See LoadEconomics's doc comment for the full
// read-only contract this exists to enforce.
func copyEconomicsView(v *EconomicsView) *EconomicsView {
	cp := *v
	cp.Accounts = append([]economics.AccountEconomics(nil), v.Accounts...)
	cp.Meters = make(map[string]map[string]float64, len(v.Meters))
	for acct, mm := range v.Meters {
		cp.Meters[acct] = mm
	}
	return &cp
}

// startBackgroundEconomicsSweep mirrors startBackgroundSweep
// (metricsview.go:361-391): launches buildEconomicsView on its own
// goroutine, detached (context.Background(), since there is no caller
// behind it — buildEconomicsView bounds itself with economicsSweepTimeout),
// with an explicit recover since no net/http per-connection recover sits
// above it. A failed or panicked background sweep is only logged: no caller
// is waiting on its error, and the stale cache it leaves untouched is still
// valid data. Must be called with c.mu held.
func (s *Server) startBackgroundEconomicsSweep(c *economicsCacheEntry, period string) {
	c.sweeping = true
	c.done = make(chan struct{})
	done := c.done
	go func() {
		var (
			view *EconomicsView
			err  = errors.New("console: background economics sweep did not complete")
		)
		defer func() {
			rec := recover()
			c.mu.Lock()
			if err == nil {
				c.at = time.Now()
				c.view = view
			}
			c.sweeping = false
			close(done)
			c.mu.Unlock()
			switch {
			case rec != nil:
				log.Printf("console: background economics sweep panic, cache left at its last good sweep: %v", rec)
			case err != nil:
				log.Printf("console: background economics sweep: %v", err)
			}
		}()
		view, err = s.buildEconomicsView(context.Background(), period)
	}()
}

// buildEconomicsView is the bucket half of LoadEconomics: sweepUsage over
// the period's bounds, the active scenario, priced accounts and boxes, the
// two most recent bills, and the embedded payload — on a context detached
// from the caller's (WithoutCancel) and bounded by economicsSweepTimeout,
// exactly like sweepAll (metricsview.go:404-411). It holds no lock.
func (s *Server) buildEconomicsView(ctx context.Context, period string) (*EconomicsView, error) {
	sweepCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), economicsSweepTimeout)
	defer cancel()

	now := time.Now().UTC()
	from, to := economicsPeriodBounds(period, now)
	// daysInMonth is the CURRENT real month's length, statementsPass's own
	// derivation (economicspass.go) — see EconomicsView.DaysInMonth's doc
	// comment for why this must be the full month, not PeriodDays.
	daysInMonth := time.Date(now.Year(), now.Month()+1, 0, 0, 0, 0, 0, time.UTC).Day()

	routes, warning := s.loadRoutesForEconomics(sweepCtx)

	sweep, err := s.sweepUsage(sweepCtx, from, to, routes)
	if err != nil {
		return nil, fmt.Errorf("console: load economics: %w", err)
	}
	if err := s.foldStorageAndCensus(sweepCtx, from, to, sweep.PerAccount); err != nil {
		return nil, fmt.Errorf("console: load economics: %w", err)
	}

	// Fleet meters (Task 3's fleetMeters) fold into sweep.PerAccount exactly
	// like statementsPass's own union merge (economicspass.go) — an account
	// with ONLY fleet usage and no platform route still needs its meter
	// keys before universe below is built from sweep.PerAccount's keys, or
	// it would never get a priced row at all.
	//
	// Unlike statementsPass (a WRITE pass, which refuses the whole run on a
	// fleetMeters error — see that function's doc comment), THIS is a READ
	// path: a bad registry read or a bucket hiccup under a fleet prefix
	// degrades to "no fleet meters this render" plus a visible Warning,
	// never a failed dashboard — the same asymmetry loadRoutesForEconomics
	// already draws for the registry itself. Called once per
	// buildEconomicsView call, which is already the unit the 60s
	// stale-while-revalidate cache (economicsCacheTTL) bounds — no separate
	// throttling needed here. A registry-less console would otherwise show
	// TWO banners for the SAME missing registry (loadRoutesForEconomics's
	// and this one, since fleetMeters opens that identical registry) — see
	// the warning=="" guard below, which keeps it to one banner, one cause.
	if fleetMM, ferr := s.fleetMeters(sweepCtx, from, to); ferr != nil {
		log.Printf("console: load economics: fleet meters unavailable: %v", ferr)
		// Suppress a second banner when routes are ALREADY degraded
		// (warning != "" here can only mean loadRoutesForEconomics found no
		// usable registry, the one thing that precedes this call): fleetMeters
		// opens that exact same registry, so its failure here is the same
		// root cause restated, not a second independent fault. One banner,
		// one cause — still logged above for whoever reads the process log.
		if warning == "" {
			warning = fmt.Sprintf("fleet metering unavailable: %v", ferr)
		}
	} else {
		for acct, mm := range fleetMM {
			dst := sweep.PerAccount[acct]
			if dst == nil {
				dst = map[string]float64{}
				sweep.PerAccount[acct] = dst
			}
			for meter, v := range mm {
				dst[meter] += v
			}
		}
	}

	sc, scenarioWarning := s.loadActiveScenario(sweepCtx)

	scenarioNames, err := s.listScenarioNames(sweepCtx)
	if err != nil {
		return nil, fmt.Errorf("console: load economics: %w", err)
	}

	// Union of accounts to price: every account with usage this period plus
	// every live console account — the same "an account with zero usage
	// still gets a row" reasoning statementsPass documents (economicspass.go)
	// applies to the dashboard just as much as to statements.
	accounts, err := s.store.Accounts()
	if err != nil {
		return nil, fmt.Errorf("console: load economics: %w", err)
	}
	tiers, err := s.store.AccountTiers()
	if err != nil {
		return nil, fmt.Errorf("console: load economics: %w", err)
	}
	universe := map[string]bool{}
	for acct := range sweep.PerAccount {
		universe[acct] = true
	}
	// names (account-names batch): sqid -> display name, from the SAME
	// accounts read the universe/Tiers loop above already performs — see
	// EconomicsView.Names's own doc comment for the display-only contract
	// this map exists under.
	names := make(map[string]string, len(accounts))
	for _, a := range accounts {
		universe[a.Sqid] = true
		names[a.Sqid] = a.Name
	}

	// Allocate each box's period cost across the accounts that used it
	// (economics.AllocateBox), and remember each account's TOTAL allocated
	// cost across every box it touched — PriceAccount needs that total, and
	// the per-box revenue attribution below needs each box's SHARE of it.
	type boxAlloc struct {
		perAccount        map[string]float64
		idleUSD, totalUSD float64
	}
	allocByBox := make(map[string]boxAlloc, len(sweep.PerBox))
	totalAllocated := map[string]float64{}
	for box, load := range sweep.PerBox {
		perAcct, idle, total := economics.AllocateBox(sc.RateCard, sc.Allocation, load)
		allocByBox[box] = boxAlloc{perAccount: perAcct, idleUSD: idle, totalUSD: total}
		for acct, usd := range perAcct {
			totalAllocated[acct] += usd
		}
	}

	meters := make(map[string]map[string]float64, len(universe))
	accountRows := make([]economics.AccountEconomics, 0, len(universe))
	for acct := range universe {
		mm := sweep.PerAccount[acct]
		if mm == nil {
			mm = map[string]float64{}
		}
		meters[acct] = mm
		row := economics.PriceAccount(sc, acct, mm, totalAllocated[acct])
		// Tier-aware revenue (Task 5): PriceAccount stays tier-unaware by
		// design (see its own doc comment) — a pool/try/"" account's
		// revenue is pooled, not individually priced, so this view
		// overrides the priced row for those tiers AFTER PriceAccount runs.
		// Its cost stands untouched. FreeTierPos is overridden too, not
		// left at whatever PriceAccount computed: a fleet-only pool account
		// can carry real (fleet) revenue under PriceAccount's tier-unaware
		// maths, so naively zeroing revenue and recomputing "inside" off
		// that zero would misreport it as sitting inside the free tier
		// rather than pooled — the carried ruling this override exists to
		// satisfy.
		if isPoolTier(tierOf(tiers, acct)) {
			row.RevenueUSD = 0
			row.MarginFrac = 0
			row.FreeTierPos = "pooled"
		}
		accountRows = append(accountRows, row)
	}
	// CostUSD desc, Account asc on ties — a stable tie-break so the
	// zero-cost tail (every account with no usage this period, all tied at
	// 0) doesn't visibly reshuffle on every 60s background sweep.
	sort.Slice(accountRows, func(i, j int) bool {
		if accountRows[i].CostUSD != accountRows[j].CostUSD {
			return accountRows[i].CostUSD > accountRows[j].CostUSD
		}
		return accountRows[i].Account < accountRows[j].Account
	})

	// PoolLedger (Task 5): PayingRevenueUSD sums the revenue of every
	// account priced normally (hosted/fleet/dedicated — i.e. everything
	// NOT pool-tier, since accountRows already carries the RevenueUSD=0
	// override above for pool/try/"" accounts, summing them contributes
	// nothing extra either way); DrawUSD sums the COST of every pool-tier
	// account, which is real spend the pool must cover since those
	// accounts carry no individual revenue of their own. TopupUSD is
	// accrued day-by-day over [from, to] — see poolTopupAccrual — NOT the
	// single PeriodDays/DaysInMonth fraction the brief states literally:
	// that fraction is dishonest on period=last, whose PeriodDays counts
	// LAST month's days while DaysInMonth (EconomicsView.DaysInMonth's own
	// doc comment) is pinned to THIS month's — a Jan-from-Feb "last" view
	// would credit 31/28 of a month's top-up, over 100%. Headroom is
	// Pool-Draw and MAY be negative — rendered honestly, never clamped
	// (brief).
	var payingRevenue, poolDraw float64
	for _, row := range accountRows {
		if isPoolTier(tierOf(tiers, row.Account)) {
			poolDraw += row.CostUSD
		} else {
			payingRevenue += row.RevenueUSD
		}
	}
	// poolTopupUnitAccrual: see economicsPayload.PoolTopupUnitAccrual's doc
	// comment on the field this feeds — topupUSD fixed at 1 turns
	// poolTopupAccrual into the dimensionless per-day sum the JS twin scales
	// by the live topup knob.
	poolTopupUnitAccrual := poolTopupAccrual(from, to, 1)
	poolUSD := sc.Pool.RevenueFrac*payingRevenue + sc.Pool.TopupUSD*poolTopupUnitAccrual
	pool := PoolLedger{
		PoolUSD:          poolUSD,
		DrawUSD:          poolDraw,
		HeadroomUSD:      poolUSD - poolDraw,
		PayingRevenueUSD: payingRevenue,
	}

	// Revenue attribution to boxes: for each account, boxShare =
	// allocated[box][acct] / totalAllocated[acct] (0 when the total is 0),
	// box.RevenueUSD += acct.RevenueUSD * boxShare (brief step 3 formula).
	boxRows := make([]BoxEconomics, 0, len(sweep.PerBox))
	for box, load := range sweep.PerBox {
		alloc := allocByBox[box]
		var revenue float64
		for _, ae := range accountRows {
			total := totalAllocated[ae.Account]
			if total == 0 {
				continue
			}
			share := alloc.perAccount[ae.Account] / total
			revenue += ae.RevenueUSD * share
		}
		util := 0.0
		if alloc.totalUSD > 0 {
			util = 1 - alloc.idleUSD/alloc.totalUSD
		}
		boxRows = append(boxRows, BoxEconomics{
			Box:           box,
			Hours:         load.Hours,
			CostUSD:       alloc.totalUSD,
			IdleUSD:       alloc.idleUSD,
			RevenueUSD:    revenue,
			Utilization:   util,
			EgressMetered: sweep.EgressMetered[box], // absent boxes default false — see usageSweep.EgressMetered
		})
	}
	sort.Slice(boxRows, func(i, j int) bool { return boxRows[i].Box < boxRows[j].Box })

	bills, err := s.loadRecentBills(sweepCtx, now)
	if err != nil {
		return nil, fmt.Errorf("console: load economics: %w", err)
	}

	payload := economicsPayload{
		Scenario:             sc,
		Meters:               meters,
		BoxLoads:             sweep.PerBox,
		BoxSpecs:             sc.RateCard.Boxes,
		Bills:                bills,
		CoveredDays:          sweep.CoveredDays,
		PeriodDays:           sweep.PeriodDays,
		DaysInMonth:          daysInMonth,
		Tiers:                tiers,
		Names:                names,
		PoolTopupUnitAccrual: poolTopupUnitAccrual,
	}
	raw, err := json.Marshal(payload)
	if err != nil {
		return nil, fmt.Errorf("console: load economics: marshal payload: %w", err)
	}

	return &EconomicsView{
		GeneratedAt:     now,
		Period:          period,
		Scenario:        sc,
		ScenarioWarning: scenarioWarning,
		Warning:         warning,
		Scenarios:       scenarioNames,
		Accounts:        accountRows,
		Meters:          meters,
		Boxes:           boxRows,
		Bills:           bills,
		CoveredDays:     sweep.CoveredDays,
		PeriodDays:      sweep.PeriodDays,
		DaysInMonth:     daysInMonth,
		DataJSON:        template.JS(raw),
		Tiers:           tiers,
		Names:           names,
		Pool:            pool,
	}, nil
}

// tierOf returns acct's fleet-pool tier from tiers — "" (pool semantics,
// same as the explicit "pool" tier — see isPoolTier) both when acct is
// simply absent from tiers (usage with no matching console account row,
// e.g. a fleet-only account) and when it's present with the explicit ""
// tier (a live account never yet placed). A plain map index already
// returns the zero value for a missing key, so this exists purely to give
// that lookup one named call site, per the brief.
func tierOf(tiers map[string]string, acct string) string {
	return tiers[acct]
}

// isPoolTier reports whether tier draws from the shared fleet-pool rather
// than being individually priced — the "", "try" and "pool" tiers (Task 4's
// validAccountTiers minus the three that price normally: hosted, fleet,
// dedicated).
func isPoolTier(tier string) bool {
	switch tier {
	case "", "try", "pool":
		return true
	default:
		return false
	}
}

// poolTopupAccrual accrues Scenario.Pool.TopupUSD — a flat MONTHLY figure —
// day-by-day over [from, to] (both truncated to UTC midnight, inclusive):
// precedent foldStorageAndCensus's per-day denominator (economicspass.go),
// applied here because the naive single-fraction reading of the brief
// (TopupUSD * PeriodDays/DaysInMonth, using ONE daysInMonth for the whole
// period) is dishonest whenever the period isn't wholly inside the CURRENT
// calendar month: period=last's PeriodDays counts last month's days while
// buildEconomicsView's daysInMonth is pinned to THIS month's (see
// EconomicsView.DaysInMonth's doc comment) — a Jan-from-Feb "last" view
// would credit 31/28 of a month's top-up, over 100%. Each day here instead
// contributes topupUSD/daysInMonth(that day's OWN calendar month), so:
//   - "mtd" (wholly inside the current month) sums to exactly the old
//     PeriodDays/DaysInMonth fraction — unchanged behavior.
//   - "last" (the WHOLE previous calendar month) sums to exactly topupUSD —
//     one full month's top-up, never more or less.
//   - "7d" straddling a month boundary charges each day at its own month's
//     rate rather than borrowing one denominator for days in a different
//     month.
func poolTopupAccrual(from, to time.Time, topupUSD float64) float64 {
	fromDay := from.UTC().Truncate(24 * time.Hour)
	toDay := to.UTC().Truncate(24 * time.Hour)
	var total float64
	for d := fromDay; !d.After(toDay); d = d.AddDate(0, 0, 1) {
		y, mo, _ := d.Date()
		dim := time.Date(y, mo+1, 0, 0, 0, 0, 0, time.UTC).Day()
		total += topupUSD / float64(dim)
	}
	return total
}

// loadRoutesForEconomics resolves the routes sweepUsage needs to attribute
// sampled units to accounts, DEGRADING rather than failing when the
// registry is missing or unreadable — the opposite of openPassRegistry's
// refusal, and deliberately so: that refusal protects a WRITE pass from
// reading registry.Open's freshly-created empty sqlite as "zero routes" and
// writing a permanent, uncorrectable all-zero day. This is a READ path —
// there is nothing to protect by refusing. A nil routes list simply means
// unitOwner falls every sampled unit through to release.OpsAccount
// (indistinguishable from platform overhead, same as any other unmatched
// unit), and the dashboard still renders with a visible warning rather than
// a blank 500 — precedent: commit 0958fa3, instances health degrading on a
// console with no registry rather than failing the page.
func (s *Server) loadRoutesForEconomics(ctx context.Context) (routes []registry.Route, warning string) {
	reg, err := s.openPassRegistry()
	if err != nil {
		return nil, fmt.Sprintf("no registry available (%v); usage cannot be attributed to accounts by route this sweep", err)
	}
	routes, err = reg.List()
	if err != nil {
		return nil, fmt.Sprintf("registry: %v; usage cannot be attributed to accounts by route this sweep", err)
	}
	return routes, ""
}

// loadActiveScenario resolves economics.ActiveKey -> named scenario ->
// Validate, per the spec's fallback rule: economics/active.json simply not
// existing yet is a FRESH DEPLOYMENT, not a fault — DefaultScenario with no
// warning. Every OTHER failure past that point (active.json unreadable or
// corrupt, the scenario it names missing, corrupt, or failing Validate) IS a
// fault worth a visible warning, but still degrades to DefaultScenario
// rather than failing the whole view — the dashboard must still render.
func (s *Server) loadActiveScenario(ctx context.Context) (sc economics.Scenario, warning string) {
	raw, _, err := s.cfg.Releases.Get(ctx, economics.ActiveKey)
	if err != nil {
		if errors.Is(err, os.ErrNotExist) {
			return economics.DefaultScenario(), ""
		}
		return economics.DefaultScenario(), fmt.Sprintf("read %s: %v; using the default scenario", economics.ActiveKey, err)
	}
	var active economics.Active
	if jerr := json.Unmarshal(raw, &active); jerr != nil {
		return economics.DefaultScenario(), fmt.Sprintf("%s is corrupt: %v; using the default scenario", economics.ActiveKey, jerr)
	}

	scRaw, _, err := s.cfg.Releases.Get(ctx, economics.ScenarioKey(active.Name))
	if err != nil {
		return economics.DefaultScenario(), fmt.Sprintf("active scenario %q: %v; using the default scenario", active.Name, err)
	}
	var scenario economics.Scenario
	if jerr := json.Unmarshal(scRaw, &scenario); jerr != nil {
		return economics.DefaultScenario(), fmt.Sprintf("active scenario %q is corrupt: %v; using the default scenario", active.Name, jerr)
	}
	if verr := scenario.Validate(); verr != nil {
		return economics.DefaultScenario(), fmt.Sprintf("active scenario %q is invalid: %v; using the default scenario", active.Name, verr)
	}
	return scenario, ""
}

// listScenarioNames lists economics/scenarios/*.json and strips both the
// prefix and the extension — the flat set of names a scenario picker (Task
// 13) offers, alongside "default" (DefaultScenario is never itself stored).
func (s *Server) listScenarioNames(ctx context.Context) ([]string, error) {
	keys, err := s.cfg.Releases.List(ctx, economics.ScenariosPrefix)
	if err != nil {
		return nil, fmt.Errorf("list %s: %w", economics.ScenariosPrefix, err)
	}
	names := make([]string, 0, len(keys))
	for _, key := range keys {
		rest := strings.TrimPrefix(key, economics.ScenariosPrefix)
		name := strings.TrimSuffix(rest, ".json")
		if name == "" || name == rest || strings.Contains(name, "/") {
			continue // defensive: skip anything not a flat "<name>.json" scenario file
		}
		names = append(names, name)
	}
	sort.Strings(names)
	return names, nil
}

// loadRecentBills reads economics.BillKey for now's month and the one
// before it — regardless of the requested period, per the brief — and
// simply omits a month with no bill object rather than erroring: a missing
// bill is a normal, ongoing state (this month's hasn't been pulled yet),
// not a fault.
func (s *Server) loadRecentBills(ctx context.Context, now time.Time) ([]economics.Bill, error) {
	firstOfThisMonth := time.Date(now.Year(), now.Month(), 1, 0, 0, 0, 0, time.UTC)
	firstOfLastMonth := firstOfThisMonth.AddDate(0, -1, 0)
	months := []string{usage.MonthOf(now), usage.MonthOf(firstOfLastMonth)}

	var bills []economics.Bill
	for _, month := range months {
		raw, _, err := s.cfg.Releases.Get(ctx, economics.BillKey(month))
		if err != nil {
			if errors.Is(err, os.ErrNotExist) {
				continue
			}
			return nil, fmt.Errorf("bill %s: %w", month, err)
		}
		var b economics.Bill
		if jerr := json.Unmarshal(raw, &b); jerr != nil {
			log.Printf("console: load economics: parse %s: %v", economics.BillKey(month), jerr)
			continue
		}
		bills = append(bills, b)
	}
	return bills, nil
}