frutebox-node 0.1.0__py3-none-any.whl

frutebox/gpuprices.py

@@ -0,0 +1,641 @@
+"""LIVE GPU prices — what an hour of each GPU class actually costs, per provider (file 01-A).
+
+WHY THIS MODULE EXISTS
+`selection.GPU_TIERS` priced tier S at **$2.50/hr**. Reality for the 5xH200 pod we actually
+serve frontier models on is **$17.95-22.95/hr**. Every "cheaper than the frontier APIs at >=75%
+margin" figure computed from that table understated frontier cost by roughly **8x** — which
+means the guarantee the whole pricing model rests on was arithmetically false, not marginally
+off. Static numbers in source also rot silently: a provider re-prices, the table does not, and
+nothing fails loudly.
+
+So prices are fetched live per provider and cached. The static tables remain, but ONLY as the
+cold-boot fallback.
+
+WHERE THE CACHE LIVES (and why not here)
+This process is deliberately stateless across restarts — the control plane holds no database
+credentials (`directory_control.py`: the web app is the only service with database access). A
+price cache in module memory would be empty after every deploy, and Cloud Run redeploys often.
+So the cache is a Postgres table owned by the web app, read and written over
+`/api/internal/gpu-prices` with the shared admin token, exactly as the armed flag already
+works. Module state here is a hot cache in front of that.
+
+THE RULE THAT SHAPES EVERY FUNCTION BELOW: **a price lookup must never block dispatch and must
+never raise.** A provider being down, the web app being slow, an empty cache on a cold boot —
+each degrades to the next-best number (live -> cached -> static fallback) and logs. Pricing a
+job slightly wrong is a bookkeeping error; failing to answer a user's prompt because a price
+API timed out is an outage.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+from dataclasses import dataclass
+from typing import Dict, List, Optional, Tuple
+
+import httpx
+
+from .config import CONFIG
+from .envvars import env as envvar, env_required
+from . import adminheader
+
+# --- Static fallback -------------------------------------------------------------------------
+# Honest static values, corrected from the pre-file-01 table (which had S=2.50, A=0.80). These
+# are what the tiers cost when we cannot reach a single provider or the cache. Sources: RunPod
+# Community on-demand observed this project — A40 0.35-0.44/hr, 5xH200 17.95/hr.
+#
+# `static_fallback` is carried in the row itself so anything reporting a margin can say whether
+# the number it used was measured or assumed. A margin computed from a guess should not look
+# identical to one computed from a live price.
+TIER_STATIC: Dict[str, dict] = {
+    "C": {"vram_gb": 0, "usd_per_hr": 0.10, "example": "CPU / shared tiny GPU", "static_fallback": True},
+    "B": {"vram_gb": 16, "usd_per_hr": 0.40, "example": "RTX A4000 / A40 slice", "static_fallback": True},
+    "A": {"vram_gb": 48, "usd_per_hr": 0.60, "example": "A40 / A6000", "static_fallback": True},
+    "S": {"vram_gb": 80, "usd_per_hr": 18.00, "example": "H200 pool (5x = $17.95/hr)", "static_fallback": True},
+}
+
+#: Minimum usable VRAM (GB) a card must have to serve a tier. Tier C is CPU-or-anything.
+TIER_MIN_VRAM_GB: Dict[str, int] = {t: int(v["vram_gb"]) for t, v in TIER_STATIC.items()}
+
+TTL_S = float(envvar("GPUPRICE_TTL_S", "3600"))
+
+
+#: RESOLVED LAZILY, AND THAT IS NOT A STYLE CHOICE — the same finding `frutebox/deltasync.py` records
+#: above its own `web_url()`, in a second module, with a second victim.
+#:
+#: At module scope this raised `MissingConfig` ON IMPORT, and the import chain is long:
+#: `router.route()` -> `selection` -> `gpuprices`. So **file 11-E2's CI latency gate could not run at
+#: all** without `FRUTEBOX_WEB_URL` — `python scripts/perf_harness.py` died in the import, before it
+#: measured anything, on any machine or CI job that did not happen to set a variable a latency harness
+#: has no business needing. A gate that cannot start is not a gate, and it fails in the one direction
+#: nobody investigates: the run is red for a reason that looks like configuration.
+#:
+#: Only the two cache calls need the URL, and they are the only places that now pay for it — at call
+#: time, where an unset variable is a real error about a real request rather than an import failure
+#: three modules away from the thing that wanted it.
+def web_url() -> str:
+    return env_required("WEB_URL").rstrip("/")
+
+
+@dataclass(frozen=True)
+class Price:
+    provider: str
+    gpu_type: str
+    usd_per_hr: float
+    vram_gb: int = 0
+    region: str = ""
+    secure: bool = False
+    reliability: Optional[float] = None
+    available: bool = True
+
+
+# Hot cache. `fetched_at` 0.0 means "never loaded" — distinct from "loaded and found nothing",
+# which is a real answer (no configured providers) and must not trigger a refetch storm.
+_CACHE: Dict[str, object] = {"prices": [], "region_rates": {}, "fetched_at": 0.0}
+
+
+def _log(msg: str) -> None:
+    print(f"[gpuprices] {msg}")
+
+
+def cached() -> List[Price]:
+    return list(_CACHE["prices"])  # type: ignore[arg-type]
+
+
+def stale() -> bool:
+    return (time.time() - float(_CACHE["fetched_at"])) > TTL_S  # type: ignore[arg-type]
+
+
+# --- Provider fetchers -----------------------------------------------------------------------
+# Each returns [] on any failure rather than raising: one provider being unreachable must not
+# stop the other two from refreshing. Field names verified against each provider's current API
+# (RunPod GraphQL GpuType, Vast /bundles offers, Lambda /instance-types).
+
+async def _fetch_runpod() -> List[Price]:
+    # Through the ONE door (KB §0): the provider owns the endpoint, the auth header and the query.
+    # This module only maps the reply into Price rows.
+    from .gpuproviders import PROVIDERS
+    types = await PROVIDERS["runpod"].gpu_prices()
+
+    out: List[Price] = []
+    for g in types:
+        name = str(g.get("displayName") or g.get("id") or "").strip()
+        vram = int(g.get("memoryInGb") or 0)
+        if not name:
+            continue
+        # Community and Secure are genuinely different products at different prices, not two
+        # quotes for the same thing: the warm pool may use Community, `spec.secure` may not.
+        # Storing them as one row would make the pool look cheaper than a secure job can buy.
+        for field, secure in (("communityPrice", False), ("securePrice", True)):
+            p = g.get(field)
+            if isinstance(p, (int, float)) and p > 0:
+                out.append(Price("runpod", name, float(p), vram, "", secure))
+    return out
+
+
+async def _fetch_vast() -> List[Price]:
+    # THE CREDENTIAL COMES FROM THE REGISTRY, NOT THE ENVIRONMENT (§A9 / §O).
+    #
+    # This line read VAST_API_KEY straight off the process environment, which bypassed the DB
+    # precedence §O decided on a path nobody was auditing — `FRUTEBOX_PROVIDER_ENV_FALLBACK` is
+    # false, so with the key held only in the DB this returned `[]` and NOTHING FAILED. The cost
+    # is silent and it is the same shape as the merit-order defect closed one level up: no Vast
+    # rows means `rank()` has no Vast price to compare, and cheapest-first quietly degrades into
+    # "whatever order `WARMPOOL_PROVIDERS` happens to be in". A merit order that has stopped
+    # being a merit order still returns an answer.
+    #
+    # Imported inside the function, like `_fetch_runpod` and `_fetch_datacrunch` above: this
+    # module is imported by `selection` and thence by `gateway`, and the lazy edge onto the
+    # single door is the established way that stays safe regardless of import order.
+    from .gpuproviders import provider_credential
+    key = provider_credential("vast", "VAST_API_KEY")
+    if not key:
+        return []
+    try:
+        async with httpx.AsyncClient(timeout=30) as c:
+            r = await c.post(
+                "https://console.vast.ai/api/v0/bundles",
+                headers={"Authorization": f"Bearer {key}", "content-type": "application/json"},
+                json={"limit": 200, "type": "ondemand", "rentable": {"eq": True},
+                      "verified": {"eq": True}},
+            )
+            if r.status_code >= 300:
+                _log(f"vast fetch HTTP {r.status_code}")
+                return []
+            offers = (r.json() or {}).get("offers") or []
+    except Exception as e:
+        _log(f"vast fetch error: {type(e).__name__}")
+        return []
+
+    # Vast is a marketplace: many offers of the same GPU at different prices. Keep the cheapest
+    # per GPU type — that is the one the wake path would actually rent.
+    best: Dict[str, Price] = {}
+    for o in offers:
+        name = str(o.get("gpu_name") or "").strip()
+        dph = o.get("dph_total")
+        n = int(o.get("num_gpus") or 1) or 1
+        if not name or not isinstance(dph, (int, float)) or dph <= 0:
+            continue
+        per_gpu = float(dph) / n
+        rel = o.get("reliability2")
+        # gpu_ram is reported in MB.
+        vram = int(float(o.get("gpu_ram") or 0) / 1024)
+        cur = best.get(name)
+        if cur is None or per_gpu < cur.usd_per_hr:
+            best[name] = Price("vast", name, per_gpu, vram, "", False,
+                               float(rel) if isinstance(rel, (int, float)) else None)
+    return list(best.values())
+
+
+async def _fetch_lambda() -> List[Price]:
+    # THE SECOND BYPASS, IN THE SAME FILE, AND NOBODY HAD COUNTED IT. `_fetch_vast` was found by
+    # accident during a sweep; this one sat four lines of reasoning away and was invisible until
+    # the whole class was enumerated rather than the one instance. Identical failure, identical
+    # silence — see `_fetch_vast` above, and `tests/test_provider_credential_env_bypass_guard.py`
+    # for the guard that now fails when a third one appears.
+    from .gpuproviders import provider_credential
+    key = provider_credential("lambda", "LAMBDA_API_KEY")
+    if not key:
+        return []
+    try:
+        from .gpuproviders import LambdaProvider  # reuse the base URL; one source for it
+        base = LambdaProvider._BASE
+        async with httpx.AsyncClient(timeout=30) as c:
+            r = await c.get(f"{base}/instance-types",
+                            headers={"Authorization": f"Bearer {key}"})
+            if r.status_code >= 300:
+                _log(f"lambda fetch HTTP {r.status_code}")
+                return []
+            data = (r.json() or {}).get("data") or {}
+    except Exception as e:
+        _log(f"lambda fetch error: {type(e).__name__}")
+        return []
+
+    out: List[Price] = []
+    # `data` is keyed by instance-type name; each value holds the type plus its regions.
+    for entry in (data.values() if isinstance(data, dict) else []):
+        it = (entry or {}).get("instance_type") or {}
+        cents = it.get("price_cents_per_hour")
+        name = str(it.get("gpu_description") or it.get("name") or "").strip()
+        if not name or not isinstance(cents, (int, float)) or cents <= 0:
+            continue
+        regions = [str(r.get("name")) for r in ((entry or {}).get("regions_with_capacity_available") or [])
+                   if isinstance(r, dict) and r.get("name")]
+        # Lambda quotes per INSTANCE, which may hold several GPUs; divide so every provider's
+        # rows mean the same thing (price of one card-hour) and are therefore comparable.
+        n = 1
+        desc = str(it.get("description") or "")
+        for k in (8, 4, 2):
+            if f"{k}x" in name or f"{k}x" in desc:
+                n = k
+                break
+        per_gpu = (float(cents) / 100.0) / n
+        # No capacity anywhere = a real price for something you cannot rent. Keep it, but mark
+        # it unavailable so it never wins a ranking and then fails to place.
+        out.append(Price("lambda", name, per_gpu, 0, regions[0] if regions else "",
+                         True, None, bool(regions)))
+    return out
+
+
+async def _fetch_datacrunch() -> List[Price]:
+    """DataCrunch / Verda prices — the Phase-1 EU provider, so the EU half of the merit order
+    only exists once this returns rows.
+
+    Auth goes through `DataCrunchProvider._access_token()` rather than a second OAuth exchange
+    written here: one place mints DataCrunch tokens, the same way `_fetch_lambda` borrows
+    Lambda's base URL instead of restating it.
+
+    Two calls, because the vendor separates them: `/instance-types` carries the PRICE and
+    `/instance-availability` carries the STOCK. A price with no stock anywhere is a real number
+    for something you cannot rent, so it is kept but marked unavailable — identical to the Lambda
+    treatment, and it stops a phantom cheapest-row winning a ranking and then failing to place.
+    """
+    from .gpuproviders import PROVIDERS
+    prov = PROVIDERS.get("datacrunch")
+    if prov is None or not prov.configured():
+        return []
+    try:
+        headers = await prov._headers()
+        if headers is None:
+            _log("datacrunch auth failed")
+            return []
+        base = prov._BASE
+        async with httpx.AsyncClient(timeout=30) as c:
+            r = await c.get(f"{base}/instance-types", headers=headers)
+            if r.status_code >= 300:
+                _log(f"datacrunch instance-types HTTP {r.status_code}")
+                return []
+            types = r.json() or []
+            a = await c.get(f"{base}/instance-availability", headers=headers)
+            avail_rows = (a.json() or []) if a.status_code < 300 else []
+    except Exception as e:
+        _log(f"datacrunch fetch error: {type(e).__name__}")
+        return []
+
+    # {instance_type: first location offering it}
+    in_stock: Dict[str, str] = {}
+    for loc in avail_rows if isinstance(avail_rows, list) else []:
+        if not isinstance(loc, dict):
+            continue
+        code = str(loc.get("location_code") or "")
+        for t in loc.get("availabilities") or []:
+            in_stock.setdefault(str(t), code)
+
+    out: List[Price] = []
+    for t in types if isinstance(types, list) else []:
+        if not isinstance(t, dict):
+            continue
+        name = str(t.get("instance_type") or "").strip()
+        if not name:
+            continue
+        try:
+            # The vendor quotes price as a STRING ("3.17"); float() it rather than trusting a
+            # numeric type that is not there.
+            total = float(t.get("price_per_hour") or 0)
+        except (TypeError, ValueError):
+            continue
+        if total <= 0:
+            continue
+        gpu = t.get("gpu") or {}
+        n = int(gpu.get("number_of_gpus") or 1) or 1
+        vram = int((t.get("gpu_memory") or {}).get("size_in_gigabytes") or 0)
+        # Per CARD-hour, so a row here means the same thing as a RunPod/Vast/Lambda row and the
+        # merit order is comparing like with like. `vram` is likewise per card.
+        out.append(Price("datacrunch", str(gpu.get("description") or t.get("model") or name),
+                         total / n, vram // n if vram and n else vram,
+                         in_stock.get(name, ""), True, None, name in in_stock))
+    return out
+
+
+#: Nebius $/hr per PRESET, operator-supplied — `{"gpu-h100-sxm/1gpu-16vcpu-200gb": 2.95}`.
+#:
+#: WHY THE PRICE IS CONFIGURATION HERE AND DISCOVERED EVERYWHERE ELSE. Every other provider in
+#: this file publishes a price list and the fetcher reads it. Nebius does NOT: its REST surface
+#: offers `/compute/v1/platforms` (platforms, presets, gpu counts, VRAM — no money) and
+#: `/billing/v1/pricing-policies` (an ACCOUNT's policy, not a catalog). Checked against the
+#: published OpenAPI document 2026-10-16, which is the whole 443-path surface.
+#:
+#: So there are three options and only one of them is honest. Inventing a number puts a phantom
+#: cheapest row in front of the merit order — the 8x-wrong static table this module was written to
+#: delete. Scraping the marketing page makes the fleet's placement depend on a web page's markup.
+#: Or the operator states the price they are actually contracted at, which for a provider whose
+#: GPU pricing is committed-use is the only number that was ever true for this account.
+#:
+#: UNSET IS NOT AN ERROR. Nebius then contributes no price rows, and
+#: `nodewake._create_cheapest_first` already handles that case deliberately: priced providers sort
+#: first, then "any allowed provider we have no price for — an unpriced provider is still worth
+#: trying before giving up entirely". So Nebius stays reachable and simply sorts last. THAT IS A
+#: REAL COST and it is written down rather than hidden: until this is set, the preference that
+#: says "prefer Nebius over RunPod" is outranked by every provider that quotes a number.
+async def _fetch_nebius() -> List[Price]:
+    """Nebius prices — the operator's $/hr per preset, with the SHAPE discovered from the vendor.
+
+    THE SPLIT IS THE POINT, and it is §A5's ("the owner supplies what only they know, the code
+    discovers the rest") applied to a price rather than a credential:
+
+      * the operator states `platform/preset -> $/hr`, because only the account knows its rate;
+      * the code reads `/compute/v1/platforms` for the preset's gpuCount and VRAM, because those
+        are facts about the hardware and a wrong guess at them is a wrong placement.
+
+    A PRICE FOR A PRESET THE VENDOR DOES NOT OFFER IS KEPT AND MARKED UNAVAILABLE, exactly as the
+    Verda and Lambda fetchers treat a priced-but-unstocked type. Dropping it silently would make a
+    typo in the operator's table look like a provider with no capacity; `available=False` keeps it
+    out of `rank()` while leaving it visible to anyone reading the cache.
+    """
+    from .gpuproviders import PROVIDERS, NEBIUS_INSTANCES_PATH  # noqa: F401  (one door)
+    prov = PROVIDERS.get("nebius")
+    if prov is None or not prov.configured():
+        return []
+
+    # ONE PARSER, in `gpuproviders` — see `nebius_price_table`. This module used to parse the
+    # table itself, so there were two copies of the same env read and the same JSON handling for
+    # the same purpose: the price the merit order ranks on and the price the live proof's cap is
+    # checked against could have drifted apart on any fix to either copy. The parser NAMES a
+    # malformed table on `frutebox.gpuproviders`' logger, because a silent {} is
+    # indistinguishable from "the operator set no prices" and the consequence — Nebius sorting
+    # last forever — looks like a provider problem rather than a typo.
+    from .gpuproviders import nebius_price_table
+    table = nebius_price_table()
+
+    # The catalog, through the provider's own auth (one door). A failure here does NOT discard the
+    # operator's prices: the shape is then unknown, which costs a VRAM filter, while discarding the
+    # price costs the provider its place in the merit order entirely.
+    shapes: Dict[str, tuple] = {}
+    headers = None
+    try:
+        headers = await prov._headers()
+        if headers is None:
+            _log("nebius auth failed")
+            return []
+        project = await prov._resolve_project()
+        if not project:
+            _log("nebius has no project for its region — pricing without a discovered shape")
+            raise RuntimeError("no project")
+        async with httpx.AsyncClient(timeout=30) as c:
+            r = await c.get(f"{prov._BASE}/compute/v1/platforms", headers=headers,
+                            params={"parentId": project})
+        if r.status_code < 300:
+            for plat in (r.json() or {}).get("items") or []:
+                pname = str(((plat.get("metadata") or {}).get("name") or "")).strip()
+                pspec = plat.get("spec") or {}
+                for preset in pspec.get("presets") or []:
+                    res = preset.get("resources") or {}
+                    shapes[f"{pname}/{preset.get('name')}"] = (
+                        int(res.get("gpuCount") or 0),
+                        int(res.get("gpuMemoryGibibytes")
+                            or pspec.get("gpuMemoryGibibytes") or 0),
+                    )
+        else:
+            _log(f"nebius platforms HTTP {r.status_code} — pricing without a discovered shape")
+    except Exception as e:
+        _log(f"nebius platforms fetch error: {type(e).__name__} — pricing without a shape")
+
+    # THE OPERATOR'S TABLE IS NO LONGER REQUIRED, and requiring it kept Nebius out of the merit
+    # order entirely. This returned `[]` whenever `FRUTEBOX_NEBIUS_PRICES` was unset, so with a
+    # working key, a real catalog and real capacity, Nebius contributed ZERO rows to `rank()` and
+    # could never be chosen — measured 2026-10-20: "refreshed 79 prices from 1 provider(s)" with
+    # both providers configured. `derive_nebius_pod_spec` had already stopped depending on the
+    # table (the vendor prices a configuration through its calculator); this is the same
+    # correction applied to the other reader of the same fact, so the price the race ranks on and
+    # the price the cap is checked against still come from the same two sources in the same order.
+    #
+    # ORDER, AND WHY: the operator's table FIRST because it is what the account is contracted at,
+    # the calculator SECOND because it is list price for the configuration. Same precedence as the
+    # derivation — a provider that ranked on list price while spending at a contracted rate would
+    # be mis-ranked in whichever direction the discount runs.
+    gpu_keys = [k for k, (gpus, _v) in shapes.items() if gpus >= 1]
+    need = [k for k in gpu_keys if k not in table]
+    estimated: Dict[str, float] = {}
+    if need and headers is not None:
+        from .gpuproviders import _nebius_estimate_hourly
+        project = await prov._resolve_project()
+        async def _one(key: str):
+            platform, _, preset = key.partition("/")
+            return key, await _nebius_estimate_hourly(prov, headers, project, platform, preset)
+        # Concurrently, because this is one round trip per preset on a refresh path with a TTL —
+        # 17 presets served serially at 30s timeouts each is a price cache that never finishes.
+        for key, val in await asyncio.gather(*(_one(k) for k in need)):
+            if val is not None and val > 0:
+                estimated[key] = val
+
+    #: The project's region, so an EU-locked job can see that these rows ARE EU. It was left blank,
+    #: which reads as "region unknown" to every filter downstream — and a Nebius row that cannot
+    #: prove its region is one an EU-locked job must skip, so blank here costs the provider the
+    #: work the owner just said it may do.
+    #:
+    #: `_assert_eu_project` is what populates `_project_region`, so it is ASKED rather than assumed:
+    #: the region is a property of the PROJECT at Nebius, not of the instance. Its verdict is not
+    #: used to drop prices — an unverified region means these rows carry no region and are filtered
+    #: out downstream, which is the fail-closed direction already.
+    region = ""
+    try:
+        pid = await prov._resolve_project()
+        await prov._assert_eu_project(pid)
+        region = prov._project_region.get(pid, "") or ""
+    except Exception as e:
+        _log(f"nebius project region unresolved ({type(e).__name__}) — rows carry no region")
+
+    out: List[Price] = []
+    for key in sorted(set(table) | set(estimated)):
+        raw = table.get(key, estimated.get(key))
+        try:
+            total = float(raw)
+        except (TypeError, ValueError):
+            continue
+        if total <= 0:
+            continue
+        gpus, vram = shapes.get(str(key), (0, 0))
+        n = gpus or 1
+        out.append(Price(
+            "nebius", str(key),
+            # Per CARD-hour, so a nebius row means the same thing as a runpod/verda row and the
+            # merit order compares like with like.
+            total / n,
+            vram // n if vram and n else vram,
+            region, True, None,
+            # Known to the vendor's catalog? An unknown preset is a typo in the operator's table,
+            # not capacity. Kept and flagged rather than dropped. A calculator-priced row is in the
+            # catalog by construction — that is where its key came from.
+            str(key) in shapes if shapes else True,
+        ))
+    if not out:
+        _log("nebius priced nothing: operator table empty and the calculator answered for no "
+             "preset — NOT the same as 'no capacity'")
+    return out
+
+
+_FETCHERS = {"runpod": _fetch_runpod, "vast": _fetch_vast, "lambda": _fetch_lambda,
+             "datacrunch": _fetch_datacrunch, "nebius": _fetch_nebius}
+
+
+async def fetch_all() -> List[Price]:
+    """Fetch from every configured provider concurrently. Never raises."""
+    results = await asyncio.gather(*(f() for f in _FETCHERS.values()), return_exceptions=True)
+    out: List[Price] = []
+    for name, res in zip(_FETCHERS, results):
+        if isinstance(res, Exception):
+            _log(f"{name} fetch raised: {type(res).__name__}")
+            continue
+        out.extend(res)  # type: ignore[arg-type]
+    return out
+
+
+# --- Web-owned persistence -------------------------------------------------------------------
+
+def _headers() -> dict:
+    return adminheader.send(CONFIG.admin_token)
+
+
+async def persist(prices: List[Price]) -> bool:
+    if not prices:
+        return False
+    body = {"prices": [{"provider": p.provider, "gpuType": p.gpu_type, "region": p.region,
+                        "usdPerHr": p.usd_per_hr, "vramGb": p.vram_gb, "secure": p.secure,
+                        "reliability": p.reliability, "available": p.available}
+                       for p in prices]}
+    try:
+        async with httpx.AsyncClient(timeout=30) as c:
+            r = await c.post(f"{web_url()}/api/internal/gpu-prices", headers=_headers(), json=body)
+            return r.status_code < 300
+    except Exception as e:
+        _log(f"persist error: {type(e).__name__}")
+        return False
+
+
+async def load_from_web() -> bool:
+    """Populate the hot cache from the web-owned table. Used on boot, before any fetch."""
+    try:
+        async with httpx.AsyncClient(timeout=30) as c:
+            r = await c.get(f"{web_url()}/api/internal/gpu-prices", headers=_headers())
+            if r.status_code >= 300:
+                return False
+            data = r.json() or {}
+    except Exception as e:
+        _log(f"load error: {type(e).__name__}")
+        return False
+
+    prices = [Price(str(p.get("provider")), str(p.get("gpu_type")), float(p.get("usd_per_hr") or 0),
+                    int(p.get("vram_gb") or 0), str(p.get("region") or ""), bool(p.get("secure")),
+                    p.get("reliability"), p.get("available") is not False)
+              for p in (data.get("prices") or [])
+              if p.get("provider") and p.get("gpu_type") and float(p.get("usd_per_hr") or 0) > 0]
+    _CACHE["prices"] = prices
+    _CACHE["region_rates"] = data.get("region_rates") or {}
+    if prices:
+        _CACHE["fetched_at"] = time.time()
+    return bool(prices)
+
+
+async def refresh(force: bool = False) -> int:
+    """Fetch -> persist -> update the hot cache. Returns how many prices are now cached.
+
+    On a total fetch failure the previous cache is left untouched and a warning logged: a stale
+    price is always better than no price, because the alternative is falling back to the static
+    table that was 8x wrong.
+
+    TTL-GATED, so a caller on the wake path can call it every time without a fetch every time.
+    `nodewake._create_cheapest_first` is that caller: this is the only thing that puts a price in
+    the cache, and `rank()` reads the cache, so without it the merit order has nothing to order
+    by and the "cheapest provider with stock wins" race silently degrades to allow-list order.
+
+    THE WEB-OWNED TABLE IS READ ON EVERY REFRESH, not only when a fetch fails. It carries two
+    things: the cached prices AND the admin-edited `region_rates` that `economics.rates_for()`
+    prefers over its seed file (01-D2, "owner-editable via admin"). Loading it only in the
+    failure branch meant that on a deployment where the provider fetches WORK — the normal case —
+    an owner's rate edit could never reach settlement at all.
+    """
+    if not force and not stale():
+        return len(cached())
+    had = float(_CACHE["fetched_at"])   # type: ignore[arg-type]
+    await load_from_web()
+    fresh = await fetch_all()
+    if not fresh:
+        _log("no prices fetched from any provider — keeping previous cache")
+        # Reading the fallback is not a successful refresh. Leaving the clock where it was means
+        # the next wake retries the providers instead of treating the DB copy as fresh for a
+        # whole TTL and never noticing that every provider fetch is failing.
+        _CACHE["fetched_at"] = had
+        return len(cached())
+    await persist(fresh)
+    _CACHE["prices"] = fresh
+    _CACHE["fetched_at"] = time.time()
+    _log(f"refreshed {len(fresh)} prices from {len({p.provider for p in fresh})} provider(s)")
+    return len(fresh)
+
+
+# --- The read path (sync, non-blocking, never raises) ----------------------------------------
+
+def _eligible(tier: str, region: str = "", *, secure: bool = False) -> List[Price]:
+    need = TIER_MIN_VRAM_GB.get(tier, 0)
+    out = []
+    for p in cached():
+        if not p.available or p.usd_per_hr <= 0:
+            continue
+        if secure and not p.secure:
+            continue
+        # vram_gb 0 means the provider did not report it; do not exclude on unknown, except
+        # where the tier actually needs a big card and we would be guessing.
+        if need and p.vram_gb and p.vram_gb < need:
+            continue
+        if need and not p.vram_gb:
+            continue
+        if region and p.region and p.region != region:
+            continue
+        if p.reliability is not None and p.reliability < 0.95:
+            continue
+        out.append(p)
+    return out
+
+
+def price_for(tier: str, region: str = "", *, secure: bool = False) -> float:
+    """Cheapest live $/hr for one card of a class that can serve `tier`.
+
+    Falls back to the static table when no live price qualifies. Tier C has no VRAM floor, so
+    it takes the cheapest card of any size.
+    """
+    live = _eligible(tier, region, secure=secure)
+    if live:
+        return round(min(p.usd_per_hr for p in live), 4)
+    return float(TIER_STATIC.get(tier, TIER_STATIC["B"])["usd_per_hr"])
+
+
+def is_live(tier: str, region: str = "", *, secure: bool = False) -> bool:
+    """Whether `price_for` answered from a measured price or from the static fallback — so a
+    reported margin can say which it was instead of presenting a guess as a measurement."""
+    return bool(_eligible(tier, region, secure=secure))
+
+
+def rank(spec: dict, region: str = "") -> List[Tuple[str, str, float]]:
+    """Cheapest-first [(provider, gpu_type, usd_per_hr)] for a wake spec.
+
+    `spec` accepts `minVramGb`/`vram_gb`, `secure`, and `providers` (an allow-list that also
+    sets the tie-break order for equal prices).
+    """
+    need = int(spec.get("minVramGb") or spec.get("vram_gb") or 0)
+    secure = bool(spec.get("secure"))
+    allow = [p for p in (spec.get("providers") or []) if p]
+    order = {name: i for i, name in enumerate(allow)}
+
+    rows = []
+    for p in cached():
+        if not p.available or p.usd_per_hr <= 0:
+            continue
+        if secure and not p.secure:
+            continue
+        if need and (not p.vram_gb or p.vram_gb < need):
+            continue
+        if region and p.region and p.region != region:
+            continue
+        if p.reliability is not None and p.reliability < 0.95:
+            continue
+        if allow and p.provider not in order:
+            continue
+        rows.append(p)
+
+    rows.sort(key=lambda p: (round(p.usd_per_hr, 4), order.get(p.provider, 99), p.gpu_type))
+    return [(p.provider, p.gpu_type, round(p.usd_per_hr, 4)) for p in rows]
+
+
+def region_rates() -> dict:
+    """Per-region bandwidth + electricity rates, from the web cache when present."""
+    return dict(_CACHE["region_rates"])  # type: ignore[arg-type]