CI deploy local

.gitattributes

@@ -33,3 +33,8 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+vendor/bit-ui/bit_ui/assets/fonts/MacMinecraft.ttf filter=lfs diff=lfs merge=lfs -text
+vendor/bit-ui/bit_ui/assets/fonts/StyreneA-Light.otf filter=lfs diff=lfs merge=lfs -text
+vendor/bit-ui/bit_ui/assets/fonts/StyreneA-Medium.otf filter=lfs diff=lfs merge=lfs -text
+vendor/bit-ui/bit_ui/assets/fonts/StyreneA-Regular.otf filter=lfs diff=lfs merge=lfs -text
+vendor/bit-ui/bit_ui/assets/fonts/StyreneA-Thin.otf filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,3 @@
+.cache/
+__pycache__/
+.pytest_cache/

README.md

@@ -1,13 +1,167 @@
 ---
-title: Bit Forecast Arena
-emoji: 🌖
-colorFrom: indigo
-colorTo: green
+title: Forecast Arena
+emoji: 📈
+colorFrom: yellow
+colorTo: gray
 sdk: gradio
-sdk_version: 6.25.0
-python_version: '3.13'
+sdk_version: "5.49.1"
 app_file: app.py
-pinned: false
+pinned: true
+license: apache-2.0
+hf_oauth: true
+short_description: Every forecast archived, every model graded
+tags:
+  - time-series
+  - forecasting
+  - finance
+  - calibration
+  - benchmark
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Forecast Arena
+
+Several time-series foundation models forecast the same markets. Every forecast
+is archived **frozen at issue**, and every model accumulates a public
+calibration record that nobody — including us — can quietly edit afterwards.
+
+Built by [The Bit Trading Company](https://huggingface.co/Bit-Trading-Company).
+The archive lives in
+[`bit-signal-store`](https://huggingface.co/datasets/The-Bit-Trading-Company/bit-signal-store).
+
+> **Nothing here is financial advice.** These are model outputs on historical
+> price series, not predictions, recommendations or signals. Forecasting
+> markets is close to the hardest thing you can ask a time-series model to do,
+> and the calibration grades on this page exist to show you how often these
+> models are wrong.
+
+## What the Arena actually measures
+
+Not accuracy. **Calibration** — whether a model's uncertainty is honest.
+
+A model that says "80% chance the price lands in this band" should be right
+about 80% of the time. If it is right 58% of the time, its bands are too narrow
+and its confidence is a lie, however good its median looks. That is the number
+this page leads with, because it is the one that tells you whether you can use
+the forecast for anything.
+
+| Grade | Gap from nominal 80% coverage |
+|---|---|
+| A | within 5 points |
+| B | within 10 points |
+| C | within 20 points |
+| D | worse |
+| – | fewer than 20 resolved forecasts — no grade shown |
+
+Refusing to grade below 20 resolved forecasts is deliberate. With a handful of
+observations a coverage estimate is mostly noise, and a confident "A" computed
+from four forecasts would be the most misleading thing here.
+
+## Method
+
+**Frozen at issue.** A forecast is written to the archive at the moment it is
+made, with its seed, its sampling settings, the model revision that produced it
+and the length of the context it saw. Those rows are never rewritten.
+Resolution appends outcomes to a *separate* tree. A track record whose history
+can be edited after the fact is not evidence of anything.
+
+**No lookahead, structurally.** Contexts are sliced at the issue timestamp and
+every adapter re-validates that slice on every call. A context bar dated after
+the issue moment raises an error rather than producing a flattering number.
+This is not a convention we ask callers to honour — there is no code path that
+skips it, including in the backfill.
+
+**Seeded and reproducible.** The same context, horizon, sample count and seed
+produce bit-identical output. Models that expose no seed argument (Kronos
+samples through a global RNG) are wrapped so their sampling is seeded anyway.
+
+**Quantiles are the models' own numbers.** The stored levels — 10/20/50/80/90 —
+were chosen so that every family emits them natively rather than by
+interpolation. Path-sampling models get empirical quantiles from their sampled
+paths; direct-quantile models return theirs unchanged.
+
+**Backfill is labelled.** A backfilled entry is a forecast made *as of* a past
+timestamp, using only data available then. It is real evidence, but it is not
+the same as a forecast issued before the outcome existed, so those entries carry
+a `BACKFILL` badge everywhere they appear and a `backfilled` column in the data.
+
+**Baselines are first-class.** A random walk and a drift model sit in the
+standings next to the foundation models. A model that cannot out-forecast
+"tomorrow looks like today" is not worth the GPU time, and a leaderboard that
+omits that comparison is flattering rather than useful.
+
+## Models and attribution
+
+| Family | Models | Licence | Emits |
+|---|---|---|---|
+| **Kronos** | `NeoQuasar/Kronos-{mini,small,base}` | MIT | sampled OHLCV paths |
+| **Chronos-Bolt** | `amazon/chronos-bolt-{tiny,mini,small,base}` | Apache-2.0 | quantile line |
+| **TimesFM** | `google/timesfm-2.5-200m-pytorch` | Apache-2.0 | quantile line |
+| **Baselines** | random walk, drift, block bootstrap | this repo | reference |
+
+**Kronos** — [Kronos: A Foundation Model for the Language of Financial
+Markets](https://arxiv.org/abs/2508.02739), Shi et al.
+[GitHub](https://github.com/shiyu-coder/Kronos). Kronos publishes weights but no
+inference package, so its source is vendored at a pinned commit under
+`vendor/kronos` with one documented local change; see the PROVENANCE there.
+It is the only family here native to candlesticks, which is why it is the one
+that can draw sampled OHLCV paths.
+
+**Chronos** — [Chronos: Learning the Language of Time
+Series](https://arxiv.org/abs/2403.07815), Ansari et al., Amazon.
+[GitHub](https://github.com/amazon-science/chronos-forecasting).
+
+**TimesFM** — [A decoder-only foundation model for time-series
+forecasting](https://arxiv.org/abs/2310.10688), Das et al., Google Research,
+ICML 2024. [GitHub](https://github.com/google-research/timesfm). Not an
+officially supported Google product.
+
+None of these models were trained by us, fine-tuned by us, or selected because
+they perform well here. They are run zero-shot, through their own official
+inference paths, at pinned revisions.
+
+## Limitations
+
+Read these before drawing any conclusion from the standings.
+
+- **Zero-shot, out of domain.** Chronos and TimesFM are general time-series
+  models; markets are not what they were built for. Kronos was pre-trained on
+  candlesticks, which is an advantage on this task and worth remembering when
+  comparing across families.
+- **Grades are per asset class, not per asset.** Crypto and equities are graded
+  separately, but BTC and ETH are not independent enough to justify separate
+  grades.
+- **Coverage is estimated from correlated observations.** Forecast windows
+  overlap, so the effective sample size is smaller than the resolved count. Read
+  small differences in coverage as noise.
+- **One sampling configuration.** Every model runs at its own defaults. A model
+  might be better calibrated at a different temperature; the Arena does not tune
+  per model, because tuning on the same data it is graded on would invalidate
+  the grade.
+- **Horizons past 64 steps are rolled forward** for Chronos, on its own median.
+  Uncertainty stops compounding properly there, which flatters its bands.
+- **Prices come from public providers** (ccxt for crypto, yfinance with a Stooq
+  fallback for equities) and carry whatever errors those carry.
+- **The archive starts small.** Backfill gives models a history without waiting
+  months for one, but a model enrolled today has a thinner record than the
+  count alone suggests.
+
+## Running it
+
+Anonymous visitors get CPU-tier models with a per-session cap. Signing in with
+Hugging Face unlocks GPU-tier models on your own quota, backfill contributions,
+and enrolling a model.
+
+**Enrolling a model** takes a Hub model id and an adapter family. Only families
+with a vetted loader are accepted, `trust_remote_code` is never set, and no
+user-supplied code is ever imported or executed. A model is pinned to an
+immutable revision and must pass a smoke test before it enters the standings.
+
+## Development
+
+```bash
+cd space
+python -m pytest tests/ -q -m "not slow"    # what CI runs; offline, no credentials
+python app.py                                # http://127.0.0.1:7860
+```
+
+The suite runs offline with no credentials. Keep it that way.

app.py

@@ -0,0 +1,555 @@
+"""Forecast Arena — a Hugging Face Space by The Bit Trading Company.
+
+Many time-series foundation models forecast the same markets. Every forecast is
+archived frozen at issue, and every model accumulates a public calibration
+record that nobody can quietly edit afterwards.
+
+Architecture, in one paragraph: the visible layer is the design's own markup,
+rendered by `src/ui/shell.py` from a plain state dict. Gradio owns the transport
+and nothing that is seen — one `gr.HTML` sink, a hidden textbox the click bridge
+writes into, and a hidden button it clicks. Every interaction is
+`state -> apply_action -> state -> render`, which keeps the whole UI a pure
+function of state and makes it testable without a browser.
+
+Model loading is lazy and cached in `src/runtime.py`; the store is read once at
+boot and refreshed only when a forecast is archived. There is no Hub call in the
+render path.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+
+import gradio as gr
+import pandas as pd
+
+from src import config, runtime, view
+from src.adapters import ALLOWED_ADAPTER_FAMILIES
+from src.store import ArenaStore, now_utc
+from src.ui import chart, chrome, shell     # noqa: F401 - sets the vendor path
+
+from bit_ui import bridge
+from bit_ui import nav as bit_nav
+from bit_ui import theme
+
+logging.basicConfig(level=logging.INFO,
+                    format="%(asctime)s %(levelname)-7s %(name)s: %(message)s")
+log = logging.getLogger("arena.app")
+
+ON_SPACE = bool(os.environ.get("SPACE_ID"))
+
+STORE_URL = f"https://huggingface.co/datasets/{config.STORE_REPO}"
+SPACE_URL = f"https://huggingface.co/spaces/{config.SPACE_REPO}"
+ORG_URL = "https://huggingface.co/Bit-Trading-Company"
+
+FOOTER_RESOURCES = (
+    ("Signal store", STORE_URL),
+    ("Backtest Lab", "https://huggingface.co/spaces/Bit-Trading-Company/bit-backtest-lab"),
+    ("Finance Atlas", "https://huggingface.co/spaces/Bit-Trading-Company/bit-finance-atlas"),
+    ("Hugging Face org", ORG_URL),
+)
+
+# Adapter families offered in the enrollment form, labelled by what they emit.
+FAMILY_LABELS = {
+    "kronos": "Kronos · OHLCV paths",
+    "chronos": "Chronos · quantile line",
+    "timesfm": "TimesFM · quantile line",
+    "baseline": "Baseline · reference",
+}
+
+
+# --------------------------------------------------------------------------
+# Boot
+# --------------------------------------------------------------------------
+
+STORE = ArenaStore(
+    local_root=os.environ.get("ARENA_LOCAL_STORE") or None,
+    offline=bool(os.environ.get("ARENA_OFFLINE")),
+)
+
+NAV = bit_nav.load(local_path=os.environ.get("ARENA_LOCAL_NAV") or None)
+
+
+def _boot() -> dict:
+    """Read everything the UI needs once, at start-up.
+
+    A failure here must not stop the Space from booting: an empty registry
+    renders the designed empty states, which is a far better outcome than a
+    Space that will not start because the dataset was briefly unreachable.
+    """
+    try:
+        registry = STORE.get_registry()
+    except Exception as e:            # pragma: no cover
+        log.warning("registry unavailable: %s", e)
+        registry = {"models": {}}
+    try:
+        standings = STORE.get_standings()
+    except Exception as e:            # pragma: no cover
+        log.warning("standings unavailable: %s", e)
+        standings = pd.DataFrame()
+    try:
+        trackrecord = STORE.all_trackrecords()
+    except Exception as e:            # pragma: no cover
+        log.warning("track record unavailable: %s", e)
+        trackrecord = pd.DataFrame()
+    return {"registry": registry, "standings": standings,
+            "trackrecord": trackrecord,
+            "summary": view.Summary(standings, trackrecord)}
+
+
+BOOT = _boot()
+
+
+def default_state() -> dict:
+    state = view.default_state()
+    entries = BOOT["registry"].get("models", {})
+    # Open on a CPU-tier foundation model: an anonymous visitor's first click
+    # must work without a sign-in, and landing on a baseline would show the
+    # reference rather than the thing people came to see.
+    ranked = sorted(
+        entries,
+        key=lambda s: (
+            entries[s].get("capabilities", {}).get("hardware") != "cpu",
+            entries[s].get("family") == "baseline",
+            s,
+        ))
+    state["selected"] = ranked[:1]
+    return state
+
+
+# --------------------------------------------------------------------------
+# Data assembly
+# --------------------------------------------------------------------------
+
+
+def model_rows(registry: dict) -> list[dict]:
+    """The picker's cards, in a stable order."""
+    out = []
+    for slug, entry in sorted(registry.get("models", {}).items()):
+        caps = entry.get("capabilities", {})
+        stand = BOOT["summary"].standing(slug, "BTC-USD")
+        grade = str(stand.get("grade", "-")) if stand else "-"
+        resolved = stand.get("resolved_count") if stand else None
+        out.append({
+            "slug": slug,
+            "name": entry.get("display", slug),
+            "family": entry.get("family", ""),
+            "size": (entry.get("components", {}).get("params")
+                     or _size_hint(entry) or ""),
+            "caps": caps,
+            "color": "var(--accent-amber-strong)",
+            "grade": grade,
+            "grade_color": view.grade_color(grade),
+            "resolved_label": (f"{view.count(resolved)} RESOLVED"
+                               if resolved else "UNRESOLVED"),
+        })
+    return out
+
+
+def _size_hint(entry: dict) -> str:
+    """Parameter count, if the adapter family recorded one."""
+    from src.adapters.chronos import CHRONOS_MODELS
+    from src.adapters.kronos import KRONOS_MODELS
+    from src.adapters.timesfm import TIMESFM_MODELS
+
+    for table in (KRONOS_MODELS, CHRONOS_MODELS, TIMESFM_MODELS):
+        spec = table.get(entry.get("model_id", ""))
+        if spec and spec.get("params"):
+            return spec["params"]
+    return ""
+
+
+def build_data(state: dict) -> dict:
+    """Everything the renderer needs. Pure with respect to the UI."""
+    registry = BOOT["registry"]
+    summary = BOOT["summary"]
+    models = model_rows(registry)
+    by_slug = {m["slug"]: m for m in models}
+
+    runs = [r for r in state.get("_runs", []) if r is not None]
+
+    panels = {}
+    for slug in state["selected"]:
+        panels[slug] = summary.panel(slug, state["asset"], state["tf"],
+                                     state["horizon"])
+
+    history = state.get("_history")
+    drawing = {}
+    if runs and history is not None and len(history):
+        drawing = chart.build(history, runs, state["asset"], state["horizon"],
+                              show_ghosts=state.get("ghosts", True))
+
+    vol = view.volatility(runs[0] if runs else None,
+                          history if history is not None else pd.DataFrame(),
+                          state["tf"])
+
+    # Anonymous visitors get CPU-tier models only; a GPU-tier pick is blocked
+    # with the designed banner rather than failing after a long wait.
+    picked_gpu = any(by_slug.get(s, {}).get("caps", {}).get("hardware") == "gpu"
+                     for s in state["selected"])
+    quota_blocked = picked_gpu and not state.get("signed_in")
+
+    archived, resolved = _totals()
+
+    return {
+        "models": models,
+        "models_by_slug": by_slug,
+        "panels": panels,
+        "runs": runs,
+        "chart": drawing,
+        "volatility": vol,
+        "stats": view.headline_stats(registry, BOOT["standings"],
+                                     archived, resolved),
+        "standings_rows": view.standings_rows(BOOT["standings"], registry,
+                                              state["cls"], state["selected"]),
+        "coverage": _coverage(state, summary),
+        "families": tuple(FAMILY_LABELS[f] for f in ALLOWED_ADAPTER_FAMILIES
+                          if f in FAMILY_LABELS),
+        "nav": NAV,
+        "archived_total": archived,
+        "resolved_total": resolved,
+        "resolver_last_ran": _resolver_last_ran(),
+        "runtime_hint": _runtime_hint(state, by_slug, quota_blocked),
+        "quota_blocked": quota_blocked,
+        "quota_msg": "GPU-tier model — sign in to use your own quota",
+        "login_url": SPACE_URL,
+        "duplicate_url": f"{SPACE_URL}?duplicate=true",
+        "store_url": STORE_URL,
+        "standings_url": f"{STORE_URL}/blob/main/{config.STANDINGS_PATH}",
+        "methodology_url": f"{SPACE_URL}/blob/main/README.md",
+        "footer_resources": FOOTER_RESOURCES,
+        "status_line": _status_line(),
+        "error": state.get("error"),
+    }
+
+
+def _totals() -> tuple[int | None, int | None]:
+    tr = BOOT["trackrecord"]
+    resolved = int(tr["forecast_id"].nunique()) if len(tr) else 0
+    stand = BOOT["standings"]
+    archived = (int(stand["forecast_count"].sum()) if len(stand)
+                and "forecast_count" in stand else resolved)
+    return archived, resolved
+
+
+def _resolver_last_ran() -> str:
+    tr = BOOT["trackrecord"]
+    if not len(tr) or "resolved_ts" not in tr:
+        return "NEVER"
+    try:
+        return pd.to_datetime(tr["resolved_ts"], utc=True).max() \
+            .strftime("%Y-%m-%d %H:%M UTC")
+    except Exception:                 # pragma: no cover
+        return "—"
+
+
+def _status_line() -> str:
+    tier = "ZEROGPU" if os.environ.get("SPACES_ZERO_GPU") else "CPU BASIC"
+    return f"SYSTEM STATUS: OPERATIONAL · HARDWARE {tier} · STORE {config.STORE_REPO}"
+
+
+def _runtime_hint(state: dict, by_slug: dict, blocked: bool) -> str:
+    if blocked:
+        return "BLOCKED"
+    total, unknown = 0.0, False
+    for slug in state["selected"]:
+        entry = BOOT["registry"].get("models", {}).get(slug, {})
+        measured = (entry.get("latency") or {}).get("warm_s")
+        if measured is None:
+            unknown = True
+        else:
+            total += float(measured)
+    if unknown or not state["selected"]:
+        return "TIMING UNKNOWN"
+    return f"~{max(1, round(total))}S"
+
+
+def _coverage(state: dict, summary: view.Summary) -> dict:
+    """How much archived history exists for the current selection."""
+    slug = state["selected"][0] if state["selected"] else None
+    if not slug:
+        return {"scope": "", "pct_label": view.DASH, "pct_width": "0%", "rows": []}
+    rows = summary.scoped(slug, state["asset"], state["tf"])
+    name = BOOT["registry"].get("models", {}).get(slug, {}).get("display", slug)
+    resolved = int(rows["forecast_id"].nunique()) if len(rows) else 0
+    target = 296     # the archive depth a full backfill would produce
+    share = min(1.0, resolved / target) if target else 0.0
+    oldest = (pd.to_datetime(rows["issued_ts"], utc=True).min().strftime("%Y-%m-%d")
+              if len(rows) else view.DASH)
+    return {
+        "scope": f"Archived coverage · {name} · {state['asset']} {state['tf']}",
+        "pct_label": view.pct(share),
+        "pct_width": f"{share * 100:.0f}%",
+        "rows": [
+            ("RESOLVED WINDOWS", f"{resolved} OF {target}"),
+            ("OLDEST ENTRY", oldest),
+            ("BACKFILLED", view.pct(float(rows["backfilled"].mean())
+                                    if len(rows) else None)),
+        ],
+    }
+
+
+# --------------------------------------------------------------------------
+# Actions
+# --------------------------------------------------------------------------
+
+
+def apply_action(state: dict, raw: str) -> dict:
+    """Fold one action into the state. Every value is validated."""
+    parsed = chrome.parse_action(raw)
+    if not parsed:
+        return state
+    key, value = parsed.key, parsed.value
+    # `parse_action` strips the nonce; it is recovered here because the
+    # duplicate-delivery guard below needs it. Two event paths mean one click
+    # can arrive twice, and "run" is expensive enough that acting on both
+    # would cost a second forecast.
+    nonce = raw.split(bridge.NONCE_SEP, 1)[1] if bridge.NONCE_SEP in raw else ""
+
+    # Two delivery paths mean one click can arrive twice. Folding a duplicate
+    # to a no-op keeps a double-delivered "run" from costing two forecasts.
+    if nonce and nonce == state.get("nonce"):
+        return state
+    state = dict(state)
+    state["nonce"] = nonce
+    state["error"] = None
+
+    if key == "mode" and value in ("playground", "matchup"):
+        state["mode"] = value
+        if value == "playground" and len(state["selected"]) > 1:
+            state["selected"] = state["selected"][:1]
+        state["_runs"] = []
+
+    elif key == "pick":
+        state = _pick(state, value)
+
+    elif key == "asset" and value in config.ASSETS:
+        state["asset"], state["_runs"] = value, []
+
+    elif key == "tf" and value in config.TIMEFRAMES:
+        state["tf"] = value
+        state["horizon"] = config.DEFAULT_HORIZON.get(value, 24)
+        state["_runs"] = []
+
+    elif key == "hz":
+        try:
+            h = int(value)
+        except (TypeError, ValueError):
+            return state
+        if 1 <= h <= config.MAX_HORIZON.get(state["tf"], 96):
+            state["horizon"], state["_runs"] = h, []
+
+    elif key == "gear":
+        state["gear"] = not state.get("gear")
+
+    elif key == "ghosts":
+        state["ghosts"] = not state.get("ghosts", True)
+
+    elif key == "cls" and value in ("All", "Crypto", "Equities"):
+        state["cls"] = value
+
+    elif key == "stand" and value in BOOT["registry"].get("models", {}):
+        state["mode"], state["selected"], state["_runs"] = "playground", [value], []
+
+    elif key == "hfid":
+        state["hfid"] = str(value)[:120]
+
+    elif key == "family":
+        for slug, label in FAMILY_LABELS.items():
+            if value in (slug, label):
+                state["family"] = label
+                break
+
+    elif key == "enroll":
+        state = _enroll(state) if value == "run" else state
+
+    elif key == "run":
+        state = _run(state)
+
+    elif key == "backfill":
+        state["backfill_requested"] = True
+
+    elif key == "dismiss":
+        state["error"] = None
+
+    return state
+
+
+def _pick(state: dict, slug: str) -> dict:
+    if slug not in BOOT["registry"].get("models", {}):
+        return state
+    if state["mode"] == "playground":
+        state["selected"] = [slug]
+    else:
+        current = list(state["selected"])
+        if slug in current:
+            if len(current) > 1:
+                current.remove(slug)
+        elif len(current) < view.MAX_MATCHUP:
+            current.append(slug)
+        state["selected"] = current
+    state["_runs"] = []
+    return state
+
+
+def _run(state: dict) -> dict:
+    """Issue and archive a forecast for every selected model."""
+    if not state["selected"]:
+        return state
+
+    if (not state.get("signed_in")
+            and state.get("session_forecasts", 0) >= config.ANON_SESSION_CAP):
+        state["error"] = {
+            "kind": "quota",
+            "title": "Session limit reached",
+            "message": (f"Anonymous sessions are capped at "
+                        f"{config.ANON_SESSION_CAP} forecasts so the shared CPU "
+                        f"stays responsive. Sign in with Hugging Face to keep going "
+                        f"on your own quota."),
+            "login_url": SPACE_URL,
+        }
+        return state
+
+    runs, history = [], None
+    for slug in state["selected"]:
+        try:
+            run = runtime.run_forecast(
+                STORE, slug, state["asset"], state["tf"],
+                horizon=state["horizon"], n_samples=state["n_samples"],
+                seed=state["seed"], registry=BOOT["registry"])
+        except runtime.ForecastUnavailable as e:
+            state["error"] = {
+                "kind": e.kind,
+                "title": ("No price history" if e.kind == "no_data"
+                          else "Model could not be loaded"),
+                "message": str(e),
+                "duplicate_url": f"{SPACE_URL}?duplicate=true",
+            }
+            continue
+        except Exception as e:              # pragma: no cover
+            log.exception("forecast failed for %s", slug)
+            state["error"] = {"kind": "load_failure",
+                              "title": "Forecast failed", "message": str(e)[:300],
+                              "duplicate_url": f"{SPACE_URL}?duplicate=true"}
+            continue
+        runs.append(run)
+        history = run.context
+
+    if runs:
+        state["_runs"] = runs
+        state["_history"] = history
+        state["session_forecasts"] = state.get("session_forecasts", 0) + len(runs)
+        state["log"] = _log_entries(runs, state) + list(state.get("log", []))
+        _flush_archive()
+    return state
+
+
+def _log_entries(runs, state) -> list[dict]:
+    name = (", ".join(r.model_slug for r in runs) if len(runs) > 1
+            else runs[0].model_slug)
+    return [{
+        "id": runs[0].forecast_id or "",
+        "time": now_utc().strftime("%H:%M"),
+        "name": f"{name} · {state['asset']}",
+        "meta": (f"{state['tf'].upper()} · H+{state['horizon']} · "
+                 f"SEED {state['seed']}"),
+    }]
+
+
+def _flush_archive() -> None:
+    """Push staged archive rows. A push failure must not lose the forecast."""
+    try:
+        pushed = STORE.flush("arena: archive forecasts")
+        if pushed:
+            log.info("archived %d file(s) to the store", pushed)
+    except Exception as e:              # pragma: no cover
+        # The rows are already in the local mirror; the next flush retries.
+        log.warning("could not push the archive: %s", e)
+
+
+def _enroll(state: dict) -> dict:
+    family = next((slug for slug, label in FAMILY_LABELS.items()
+                   if label == state.get("family")), state.get("family", ""))
+    outcome = runtime.enroll(STORE, family, state.get("hfid", ""),
+                             enrolled_by=state.get("user") or "anonymous",
+                             registry=BOOT["registry"])
+    state["enroll_ok"] = bool(outcome.ok)
+    state["enroll_note"] = outcome.message
+    if outcome.ok and not outcome.already:
+        _flush_archive()
+    return state
+
+
+# --------------------------------------------------------------------------
+# Render
+# --------------------------------------------------------------------------
+
+
+def render(state: dict) -> str:
+    return shell.page(state, build_data(state))
+
+
+def on_action(raw: str, state: dict):
+    state = apply_action(state or default_state(), raw or "")
+    return render(state), state
+
+
+# --------------------------------------------------------------------------
+# App
+# --------------------------------------------------------------------------
+
+
+def build_app() -> gr.Blocks:
+    with gr.Blocks(
+        title="Forecast Arena — The Bit Trading Company",
+        theme=theme.bit_theme(),
+        # chrome.full_css(), not theme.full_css(): the latter is bit-ui's
+        # shared CSS only and silently drops the Arena's own zone layout,
+        # card and chart rules.
+        css=chrome.full_css(),
+        analytics_enabled=False,
+        fill_width=True,
+    ) as demo:
+        state = gr.State(default_state())
+        view_html = gr.HTML(render(default_state()), elem_id="bit-view")
+
+        # Both must be rendered: `visible=False` removes an element from the
+        # DOM entirely and the delegated listener would write into nothing.
+        # They are hidden in CSS instead.
+        action = gr.Textbox("", elem_id=bridge.ACTION_ELEMENT_ID, label="",
+                            show_label=False, container=False, interactive=True)
+        trigger = gr.Button("", elem_id=bridge.TRIGGER_ELEMENT_ID)
+
+        action.change(on_action, [action, state], [view_html, state],
+                      show_progress="hidden")
+        # `api_name` keeps this reachable from `gradio_client`, which is how CI
+        # smoke-tests the deployed Space: a green build only proves the image
+        # started, not that an action still renders a page.
+        trigger.click(on_action, [action, state], [view_html, state],
+                      show_progress="hidden", api_name="action")
+
+        # Installed via its own `load` with no outputs: Gradio treats a `js=`
+        # return value as the output values, so sharing a load that has outputs
+        # would wipe them. Spaces also drops `gr.Blocks(head=...)`.
+        demo.load(fn=None, inputs=None, outputs=None, js=bridge.BRIDGE_LOAD_JS)
+
+    return demo
+
+
+demo = build_app()
+
+if __name__ == "__main__":
+    demo.launch(
+        server_name="0.0.0.0" if ON_SPACE else "127.0.0.1",
+        server_port=int(os.environ.get("PORT", 7860)),
+        show_api=False,
+        allowed_paths=theme.static_paths(),
+        # Gradio 5 defaults to SSR. The page then renders server-side and only
+        # becomes interactive once the client hydrates -- and when hydration
+        # does not complete, every handler stays unbound: the markup is all
+        # there, the buttons look right, and nothing does anything, with no
+        # console error. This app renders its own markup and needs only the
+        # event wiring, so SSR buys nothing and costs that failure mode.
+        ssr_mode=False,
+    )

pytest.ini

@@ -0,0 +1,8 @@
+[pytest]
+testpaths = tests
+pythonpath = . ..
+addopts = -q --tb=short
+markers =
+    slow: needs model weights or network; excluded from the CI gate
+filterwarnings =
+    ignore::DeprecationWarning

requirements.txt

@@ -0,0 +1,42 @@
+# Forecast Arena -- pinned to the exact versions the suite passes on, resolved
+# against Python 3.10, which is what the Space image provides.
+#
+# Two rules govern this file:
+#
+#   * ZeroGPU accepts only torch 2.11.0 / 2.10.0 / 2.9.1 / 2.8.0. A version
+#     outside that list is a CONFIG_ERROR at build time, not a warning.
+#   * `spaces` is injected by the ZeroGPU builder itself. Pinning it here
+#     conflicts with the builder's own copy, so it is deliberately absent.
+#
+# Everything under "Forecast adapters" is imported lazily inside
+# `ForecastAdapter.load()`, so booting the app never pays for it. That is what
+# keeps the cold start inside budget while still letting a GPU path work when
+# hardware is attached.
+
+# UI
+gradio[oauth]==5.49.1
+plotly==6.9.0
+
+# Store and data
+huggingface_hub==1.27.0
+pandas==2.3.3
+pyarrow==25.0.1
+numpy==2.2.6
+
+# Price providers -- batch refresh only, never in the request path.
+ccxt==4.5.64
+yfinance==1.6.0
+requests==2.34.2
+
+# Forecast adapters.
+torch==2.11.0
+chronos-forecasting==2.3.1
+# TimesFM 2.5. The model card still says "pip install coming soon" and points
+# at a git clone; that is stale -- 2.0.2 exports TimesFM_2p5_200M_torch and
+# installs with only numpy/safetensors/huggingface_hub/torch.
+timesfm==2.0.2
+# Kronos ships no inference package at all (the `kronos` name on PyPI is an
+# unrelated Django library). Its source is vendored under vendor/kronos; these
+# are what that source imports.
+einops==0.8.1
+safetensors==0.6.2

scripts/bootstrap_registry.py

@@ -0,0 +1,175 @@
+"""Enroll the v1 model line-up and write `arena/registry.json`.
+
+Every model goes through the same `runtime.enroll` path a user would: the
+revision is pinned to an immutable sha, a smoke test runs, and the result is
+recorded. Nothing is registered that has not actually produced a forecast.
+
+Latency is measured here too, and a CPU-tier model that misses its budget is
+demoted to GPU tier in the registry rather than left to time out in front of
+someone. The measurement is only meaningful on the hardware it was taken on,
+so the machine is recorded alongside the number -- run this on the Space to
+get numbers that describe the Space.
+
+    HF_TOKEN=$(cat ../../key.txt) python scripts/bootstrap_registry.py
+    python scripts/bootstrap_registry.py --dry-run     # no writes
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+import platform
+import sys
+import time
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from src import config, runtime           # noqa: E402
+from src.adapters import get_adapter      # noqa: E402
+from src.store import ArenaStore, now_utc  # noqa: E402
+
+logging.basicConfig(level=logging.INFO, format="%(levelname)-7s %(message)s")
+log = logging.getLogger("bootstrap")
+
+# The v1 line-up. Order is the order they appear in the UI.
+SEED_MODELS = [
+    ("baseline", "baseline/random-walk"),
+    ("baseline", "baseline/drift"),
+    ("baseline", "baseline/bootstrap"),
+    ("chronos", "amazon/chronos-bolt-tiny"),
+    ("chronos", "amazon/chronos-bolt-mini"),
+    ("chronos", "amazon/chronos-bolt-small"),
+    ("chronos", "amazon/chronos-bolt-base"),
+    ("timesfm", "google/timesfm-2.5-200m-pytorch"),
+    ("kronos", "NeoQuasar/Kronos-mini"),
+    ("kronos", "NeoQuasar/Kronos-small"),
+    ("kronos", "NeoQuasar/Kronos-base"),
+]
+
+# The forecast the budget is defined against: a default 1h forecast.
+BUDGET_HORIZON = 24
+BUDGET_SAMPLES = config.DEFAULT_N_SAMPLES
+
+
+def _synthetic(n=config.DEFAULT_CONTEXT_BARS):
+    rng = np.random.default_rng(7)
+    close = 50000.0 * np.exp(np.cumsum(rng.normal(0, 0.01, n)))
+    openp = np.concatenate([[50000.0], close[:-1]])
+    return pd.DataFrame({
+        "ts": pd.date_range("2025-01-01", periods=n, freq="1h", tz="UTC"),
+        "open": openp,
+        "high": np.maximum(openp, close) * 1.002,
+        "low": np.minimum(openp, close) * 0.998,
+        "close": close,
+        "volume": np.abs(rng.normal(1000, 200, n)) + 1.0,
+    })
+
+
+def measure(family: str, model_id: str, context) -> dict:
+    """Cold and warm latency for a default forecast."""
+    adapter = get_adapter(family, model_id)
+    # Measure on the context the app actually sends, not on the model's own
+    # ceiling: the cost is roughly linear in context length, so measuring at
+    # `max_context` would report a number no user ever waits for.
+    context = context.iloc[-min(len(context), config.DEFAULT_CONTEXT_BARS):]
+
+    t0 = time.time()
+    adapter.load()
+    load_s = time.time() - t0
+
+    t0 = time.time()
+    adapter.predict(context, horizon=BUDGET_HORIZON,
+                    n_samples=BUDGET_SAMPLES, seed=0)
+    cold_s = time.time() - t0
+
+    warm = []
+    for _ in range(3):
+        t0 = time.time()
+        adapter.predict(context, horizon=BUDGET_HORIZON,
+                        n_samples=BUDGET_SAMPLES, seed=0)
+        warm.append(time.time() - t0)
+    warm_s = float(np.median(warm))
+
+    declared = adapter.capabilities().hardware
+    # "Cold" for a user is load plus first forecast: the weights are not in
+    # memory when they arrive.
+    total_cold = load_s + cold_s
+    misses = declared == "cpu" and (
+        total_cold > config.CPU_BUDGET_COLD_S or warm_s > config.CPU_BUDGET_WARM_S)
+
+    return {
+        "declared_hardware": declared,
+        "hardware": "gpu" if misses else declared,
+        "demoted": bool(misses),
+        "load_s": round(load_s, 3),
+        "cold_s": round(total_cold, 3),
+        "warm_s": round(warm_s, 3),
+        "horizon": BUDGET_HORIZON,
+        "n_samples": BUDGET_SAMPLES,
+        "machine": f"{platform.system()}-{platform.machine()}-py{platform.python_version()}",
+        "on_space": bool(os.environ.get("SPACE_ID")),
+        "measured_ts": now_utc().isoformat(),
+    }
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--dry-run", action="store_true",
+                    help="measure and print, write nothing")
+    ap.add_argument("--skip-measure", action="store_true",
+                    help="enroll without a latency run (declared tiers stand)")
+    ap.add_argument("--local-root", default=None)
+    args = ap.parse_args()
+
+    offline = args.dry_run or not os.environ.get("HF_TOKEN")
+    store = ArenaStore(local_root=args.local_root, offline=offline)
+    registry = store.get_registry()
+    context = _synthetic()
+
+    for family, model_id in SEED_MODELS:
+        log.info("enrolling %s (%s)", model_id, family)
+        outcome = runtime.enroll(store, family, model_id,
+                                 enrolled_by="bit-trading-company",
+                                 registry=registry)
+        if not outcome.ok:
+            log.error("  refused: %s", outcome.message)
+            continue
+        if outcome.already:
+            log.info("  already enrolled at this revision")
+
+        entry = registry["models"][outcome.model_slug]
+        if not args.skip_measure:
+            try:
+                latency = measure(family, model_id, context)
+                entry["latency"] = latency
+                entry["capabilities"]["hardware"] = latency["hardware"]
+                flag = "  DEMOTED to gpu" if latency["demoted"] else ""
+                log.info("  cold=%.1fs warm=%.2fs tier=%s%s",
+                         latency["cold_s"], latency["warm_s"],
+                         latency["hardware"], flag)
+            except Exception as e:
+                log.error("  latency run failed: %s", e)
+                entry["latency"] = {"error": str(e)[:200]}
+
+    registry["updated_ts"] = now_utc().isoformat()
+    registry["version"] = 1
+
+    if args.dry_run:
+        print(json.dumps(registry, indent=2)[:4000])
+        log.info("dry run: nothing written")
+        return 0
+
+    store.put_registry(registry)
+    pushed = store.flush("arena: bootstrap model registry")
+    log.info("registry written (%d file(s) pushed)", pushed)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/daily_job.py

@@ -0,0 +1,97 @@
+"""The scheduled job: refresh prices, resolve what has matured, rebuild standings.
+
+Run daily. Each step is idempotent, so a re-run after a failure is safe and a
+missed day is caught up by the next run rather than lost.
+
+Deliberately *not* part of the code deploy. The store holds forecasts that cost
+real compute -- some of them contributed by signed-in users on their own quota
+-- and a stale checkout overwriting that would be unrecoverable. This job only
+appends.
+
+    HF_TOKEN=... python scripts/daily_job.py
+    python scripts/daily_job.py --skip-prices     # resolve only
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from src import config, prices as price_feed, trackrecord   # noqa: E402
+from src.store import ArenaStore, now_utc                   # noqa: E402
+
+logging.basicConfig(level=logging.INFO,
+                    format="%(asctime)s %(levelname)-7s %(message)s")
+log = logging.getLogger("daily")
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--skip-prices", action="store_true")
+    ap.add_argument("--local-root", default=None)
+    ap.add_argument("--dry-run", action="store_true")
+    args = ap.parse_args()
+
+    if not os.environ.get("HF_TOKEN") and not args.dry_run:
+        log.error("HF_TOKEN is not set")
+        return 2
+
+    store = ArenaStore(local_root=args.local_root, offline=args.dry_run)
+    registry = store.get_registry()
+    models = sorted(registry.get("models", {}))
+    if not models:
+        log.warning("registry is empty; nothing to resolve")
+        return 0
+
+    # -- 1. prices ---------------------------------------------------------
+    if not args.skip_prices:
+        for asset in config.SEED_ASSETS:
+            for tf in config.SEED_TIMEFRAMES:
+                try:
+                    added = price_feed.refresh(store, asset, tf)
+                    if added:
+                        log.info("prices %s %s: +%d bars", asset, tf, added)
+                except Exception as e:
+                    # A provider outage must not stop the resolver from
+                    # scoring everything that already has prices.
+                    log.warning("price refresh failed for %s %s: %s", asset, tf, e)
+        if not args.dry_run:
+            store.flush("arena: refresh prices")
+
+    # -- 2. resolve --------------------------------------------------------
+    resolved_total = 0
+    for model_slug in models:
+        for asset in config.SEED_ASSETS:
+            for tf in config.SEED_TIMEFRAMES:
+                try:
+                    rows = trackrecord.resolve(store, model_slug, asset, tf)
+                except Exception as e:
+                    log.warning("resolve failed for %s %s %s: %s",
+                                model_slug, asset, tf, e)
+                    continue
+                if len(rows):
+                    resolved_total += len(rows)
+                    log.info("resolved %d rows for %s %s %s",
+                             len(rows), model_slug, asset, tf)
+    log.info("resolved %d rows in total", resolved_total)
+
+    # -- 3. standings ------------------------------------------------------
+    standings = trackrecord.regenerate_standings(store, now=now_utc())
+    log.info("standings: %d rows", len(standings))
+
+    if args.dry_run:
+        log.info("dry run: nothing pushed")
+        return 0
+
+    pushed = store.flush("arena: daily resolve and standings")
+    log.info("pushed %d file(s)", pushed)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/seed_trackrecord.py

@@ -0,0 +1,190 @@
+"""Backfill the track record by forecasting through recent history, honestly.
+
+The point of a backfill is to give a new model a track record without waiting
+months for one. The danger is that a backfill is trivially easy to fake: run
+the model over history it has already seen, or let it peek at the bar it is
+predicting, and it will look extraordinary.
+
+So this script forecasts *as of* each historical timestamp. The context is
+sliced at that timestamp by `runtime.load_context`, and the adapter re-checks
+the slice against `issued_ts` on every call -- a context bar dated after the
+issue moment raises rather than producing a flattering number. Nothing here
+opts out of that check; there is no fast path that skips it.
+
+Every row written carries `backfilled: true`, and the UI badges those entries
+wherever they appear. A backfilled record is evidence of a kind, but it is not
+the same evidence as a forecast made before the outcome existed, and the
+difference is on the page rather than in a footnote.
+
+    HF_TOKEN=$(cat ../../key.txt) python scripts/seed_trackrecord.py
+    python scripts/seed_trackrecord.py --dry-run --models chronos-bolt-tiny
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+import sys
+from pathlib import Path
+
+import pandas as pd
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from src import config, runtime, trackrecord        # noqa: E402
+from src.store import ArenaStore, now_utc           # noqa: E402
+
+logging.basicConfig(level=logging.INFO, format="%(levelname)-7s %(message)s")
+log = logging.getLogger("backfill")
+
+# How many forecasts to seed per (model, asset, timeframe).
+TARGET_PER_SERIES = 60
+
+# Space the issue points out so the windows do not all overlap: consecutive
+# forecasts sharing 95% of their context would give 60 nearly identical
+# observations and a coverage figure with far less evidence behind it than the
+# count suggests.
+STRIDE = {"1h": 12, "1d": 3}
+
+
+def checkpoint_path(root: Path) -> Path:
+    return root / "backfill_checkpoint.json"
+
+
+def load_checkpoint(root: Path) -> dict:
+    p = checkpoint_path(root)
+    if p.exists():
+        try:
+            return json.loads(p.read_text())
+        except Exception:
+            log.warning("unreadable checkpoint; starting fresh")
+    return {"done": {}}
+
+
+def save_checkpoint(root: Path, state: dict) -> None:
+    checkpoint_path(root).parent.mkdir(parents=True, exist_ok=True)
+    checkpoint_path(root).write_text(json.dumps(state, indent=2, sort_keys=True))
+
+
+def series_key(model: str, asset: str, tf: str) -> str:
+    return f"{model}|{asset}|{tf}"
+
+
+def backfill_series(store: ArenaStore, model_slug: str, asset: str, tf: str,
+                    registry: dict, target: int, horizon: int,
+                    seed: int, dry_run: bool) -> int:
+    """Issue `target` as-of forecasts, oldest first. Returns rows archived."""
+    prices = store.get_prices(asset, tf)
+    if not len(prices):
+        log.warning("  no prices for %s %s", asset, tf)
+        return 0
+
+    ts = pd.to_datetime(prices["ts"], utc=True).reset_index(drop=True)
+    stride = STRIDE.get(tf, 6)
+
+    # Only issue points whose horizon has already elapsed -- an unresolved
+    # backfill row would sit in the archive forever without ever scoring.
+    latest_resolvable = len(ts) - horizon - 1
+    earliest = config.DEFAULT_CONTEXT_BARS + 1
+    if latest_resolvable <= earliest:
+        log.warning("  not enough history for %s %s (%d bars)", asset, tf, len(ts))
+        return 0
+
+    points = list(range(latest_resolvable, earliest, -stride))[:target]
+    points.reverse()
+
+    written = 0
+    for i, idx in enumerate(points):
+        as_of = ts.iloc[idx]
+        try:
+            run = runtime.run_forecast(
+                store, model_slug, asset, tf, horizon=horizon,
+                n_samples=config.DEFAULT_N_SAMPLES, seed=seed, as_of=as_of,
+                registry=registry, archive=not dry_run, backfilled=True)
+        except runtime.ForecastUnavailable as e:
+            log.warning("  %s: %s", as_of.date(), e)
+            continue
+        written += run.archived_rows
+        if (i + 1) % 10 == 0:
+            log.info("  %d/%d issued (%s)", i + 1, len(points), as_of.date())
+    return written
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--dry-run", action="store_true")
+    ap.add_argument("--models", nargs="*", default=None,
+                    help="model slugs; default is every CPU-tier enrolled model")
+    ap.add_argument("--assets", nargs="*", default=list(config.SEED_ASSETS))
+    ap.add_argument("--timeframes", nargs="*", default=list(config.SEED_TIMEFRAMES))
+    ap.add_argument("--target", type=int, default=TARGET_PER_SERIES)
+    ap.add_argument("--seed", type=int, default=42)
+    ap.add_argument("--include-gpu", action="store_true",
+                    help="also seed GPU-tier models (slow on CPU)")
+    ap.add_argument("--local-root", default=None)
+    args = ap.parse_args()
+
+    store = ArenaStore(local_root=args.local_root,
+                       offline=not os.environ.get("HF_TOKEN"))
+    registry = store.get_registry()
+    models = registry.get("models", {})
+    if not models:
+        log.error("registry is empty; run scripts/bootstrap_registry.py first")
+        return 1
+
+    if args.models:
+        chosen = [m for m in args.models if m in models]
+        missing = set(args.models) - set(chosen)
+        if missing:
+            log.error("not enrolled: %s", ", ".join(sorted(missing)))
+            return 1
+    else:
+        chosen = [slug for slug, entry in sorted(models.items())
+                  if args.include_gpu
+                  or entry.get("capabilities", {}).get("hardware") == "cpu"]
+
+    root = Path(store.local_root)
+    checkpoint = load_checkpoint(root)
+    total = 0
+
+    for model_slug in chosen:
+        log.info("model %s", model_slug)
+        for asset in args.assets:
+            for tf in args.timeframes:
+                key = series_key(model_slug, asset, tf)
+                if checkpoint["done"].get(key):
+                    log.info("  %s %s already done, skipping", asset, tf)
+                    continue
+                horizon = config.DEFAULT_HORIZON.get(tf, 24)
+                log.info("  %s %s (h=%d, target=%d)", asset, tf, horizon, args.target)
+                written = backfill_series(store, model_slug, asset, tf, registry,
+                                          args.target, horizon, args.seed,
+                                          args.dry_run)
+                total += written
+                if not args.dry_run:
+                    checkpoint["done"][key] = {
+                        "rows": written, "ts": now_utc().isoformat()}
+                    save_checkpoint(root, checkpoint)
+                    # Commit per series rather than at the end: a run that dies
+                    # halfway must not throw away hours of forecasting.
+                    store.flush(f"arena: backfill {model_slug} {asset} {tf}")
+
+    log.info("archived %d forecast rows", total)
+
+    if not args.dry_run:
+        log.info("resolving")
+        for model_slug in chosen:
+            for asset in args.assets:
+                for tf in args.timeframes:
+                    trackrecord.resolve(store, model_slug, asset, tf)
+        trackrecord.regenerate_standings(store)
+        store.flush("arena: resolve backfill and rebuild standings")
+        log.info("standings rebuilt")
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

src/adapters/__init__.py

@@ -0,0 +1,117 @@
+"""The adapter allow-list and the factory that reaches it.
+
+Enrolling a model means naming an adapter *family* and a Hub model id. The
+family list is fixed in this file. Nothing here ever imports, downloads or
+executes code chosen by a user: a user-supplied id is loaded only through an
+already-vetted family's loader, and `trust_remote_code` is never set anywhere
+in this package.
+
+That is the whole security model for the "enroll a model" flow, and it is why
+an unsupported family is a clear rejection rather than a best-effort attempt.
+"""
+
+from __future__ import annotations
+
+import re
+
+from .base import (HARDWARE_CPU, HARDWARE_GPU, OHLCV_COLUMNS,
+                   OUTPUT_OHLCV_PATHS, OUTPUT_QUANTILE_LINE, AdapterError,
+                   Capabilities, ContextError, ForecastAdapter,
+                   ForecastResult, LookaheadError, ModelNotAllowed,
+                   check_context, default_device, seed_everything)
+from .baseline import BASELINE_MODELS, BaselineAdapter
+from .chronos import CHRONOS_MODELS, ChronosAdapter
+from .kronos import KRONOS_MODELS, KronosAdapter
+from .timesfm import TIMESFM_MODELS, TimesFMAdapter
+
+__all__ = [
+    "AdapterError", "Capabilities", "ContextError", "ForecastAdapter",
+    "ForecastResult", "LookaheadError", "ModelNotAllowed", "check_context",
+    "default_device", "seed_everything", "get_adapter", "validate_model_id",
+    "ALLOWED_ADAPTER_FAMILIES", "KNOWN_MODELS", "family_for",
+    "OHLCV_COLUMNS", "OUTPUT_OHLCV_PATHS", "OUTPUT_QUANTILE_LINE",
+    "HARDWARE_CPU", "HARDWARE_GPU",
+]
+
+# The allow-list. Adding an entry here is the deliberate act of accepting a new
+# code path; there is no dynamic discovery.
+ADAPTERS: dict[str, type[ForecastAdapter]] = {
+    "kronos": KronosAdapter,
+    "chronos": ChronosAdapter,
+    "timesfm": TimesFMAdapter,
+    "baseline": BaselineAdapter,
+}
+
+ALLOWED_ADAPTER_FAMILIES = tuple(ADAPTERS)
+
+# Every model this app ships knowing about, and the family that loads it. A
+# user may enroll an id that is not on this list, but only under a family that
+# is -- see `runtime.enroll`.
+KNOWN_MODELS: dict[str, str] = {
+    **{mid: "kronos" for mid in KRONOS_MODELS},
+    **{mid: "chronos" for mid in CHRONOS_MODELS},
+    **{mid: "timesfm" for mid in TIMESFM_MODELS},
+    **{mid: "baseline" for mid in BASELINE_MODELS},
+}
+
+# `namespace/name`, the Hub's own shape. Anything else is not a model id and is
+# rejected before it reaches a loader.
+_MODEL_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,95}/[A-Za-z0-9][A-Za-z0-9._-]{0,95}$")
+
+
+def validate_model_id(model_id: str) -> str:
+    """Accept a Hub model id, or raise.
+
+    Model ids arrive from the enrollment form and are user input. Validating
+    the shape here keeps path traversal and injection out of every downstream
+    consumer -- the store writes files under a slug derived from this.
+    """
+    if not isinstance(model_id, str):
+        raise AdapterError("model id must be a string")
+    model_id = model_id.strip()
+    if not _MODEL_ID.match(model_id):
+        raise AdapterError(
+            f"{model_id!r} is not a valid Hugging Face model id "
+            f"(expected 'namespace/name')"
+        )
+    if ".." in model_id:
+        raise AdapterError("model id may not contain '..'")
+    return model_id
+
+
+def family_for(model_id: str) -> str | None:
+    """The family that ships support for this id, if any."""
+    return KNOWN_MODELS.get(model_id)
+
+
+def get_adapter(family: str, model_id: str, revision: str | None = None,
+                **kwargs) -> ForecastAdapter:
+    """Build an adapter, or refuse.
+
+    Refusing is the important half: an unknown family is `ModelNotAllowed`
+    with the supported list in the message, never a silent fallback to a
+    generic loader.
+    """
+    fam = (family or "").strip().lower()
+    if fam not in ADAPTERS:
+        raise ModelNotAllowed(
+            f"adapter family {family!r} is not supported. "
+            f"Supported families: {', '.join(ALLOWED_ADAPTER_FAMILIES)}"
+        )
+    return ADAPTERS[fam](validate_model_id(model_id), revision=revision, **kwargs)
+
+
+def model_slug(model_id: str) -> str:
+    """Store path segment for a model id.
+
+    `amazon/chronos-bolt-small` -> `chronos-bolt-small`. The namespace is
+    dropped because it is redundant with the registry entry, and the result is
+    checked against the same character class the id was, so it can never climb
+    out of the store's directory tree.
+    """
+    validate_model_id(model_id)
+    slug = model_id.split("/", 1)[1].lower()
+    slug = re.sub(r"[^a-z0-9._-]", "-", slug)
+    if not slug or slug in (".", ".."):
+        raise AdapterError(f"cannot derive a slug from {model_id!r}")
+    return slug

src/adapters/base.py

@@ -0,0 +1,409 @@
+"""The adapter interface every forecasting model is reached through.
+
+Three ideas carry most of the weight here.
+
+**Capabilities are declared, not inferred.** An adapter says what kind of
+output it produces, what hardware it needs, and how much context it can take.
+The UI renders strictly from that declaration, so there is no place outside
+this package where a model is special-cased by name. Adding a family is a new
+module plus a registry entry, never an `if model == ...` in a renderer.
+
+**Seeding is part of the interface.** `predict` takes a seed and is required to
+be bit-reproducible under it. Some upstream models expose no seed argument at
+all; those are wrapped so that their sampling is seeded anyway. A forecast that
+cannot be reproduced cannot be audited, and an archive of unauditable forecasts
+is not a track record.
+
+**Contexts are validated, not trusted.** `check_context` runs on every call. It
+is the structural guarantee behind the no-lookahead rule: a context bar dated
+after the issue timestamp raises rather than quietly producing a forecast that
+would look brilliant.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+
+import numpy as np
+import pandas as pd
+
+from .. import config
+
+log = logging.getLogger("arena.adapters")
+
+OHLCV_COLUMNS = ("open", "high", "low", "close", "volume")
+
+# Output kinds. `ohlcv_paths` models emit whole sampled candlestick paths and
+# can drive the ghost-path and dispersion views; `quantile_line` models emit a
+# band on the close and nothing else.
+OUTPUT_QUANTILE_LINE = "quantile_line"
+OUTPUT_OHLCV_PATHS = "ohlcv_paths"
+OUTPUT_KINDS = (OUTPUT_QUANTILE_LINE, OUTPUT_OHLCV_PATHS)
+
+HARDWARE_CPU = "cpu"
+HARDWARE_GPU = "gpu"
+HARDWARE_TIERS = (HARDWARE_CPU, HARDWARE_GPU)
+
+
+class AdapterError(RuntimeError):
+    """Anything an adapter refuses to do."""
+
+
+class ModelNotAllowed(AdapterError):
+    """The requested adapter family is not on the allow-list."""
+
+
+class LookaheadError(AdapterError):
+    """A context window reached past the moment the forecast is issued."""
+
+
+class ContextError(AdapterError):
+    """The context window is unusable -- gaps, NaNs, or too short."""
+
+
+# --------------------------------------------------------------------------
+# Capabilities
+# --------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Capabilities:
+    """What a model can do, as the model itself declares it.
+
+    `asset_generality` is a plain-language claim about training scope, not a
+    quality score: "financial" means the model was pre-trained on market data,
+    "general" means arbitrary time series. It drives one honest caveat in the
+    UI and nothing else.
+    """
+
+    output: str
+    hardware: str
+    max_context: int
+    asset_generality: str = "general"
+    seedable_natively: bool = True
+
+    def __post_init__(self):
+        if self.output not in OUTPUT_KINDS:
+            raise AdapterError(f"unknown output kind {self.output!r}")
+        if self.hardware not in HARDWARE_TIERS:
+            raise AdapterError(f"unknown hardware tier {self.hardware!r}")
+        if self.max_context < 1:
+            raise AdapterError("max_context must be positive")
+
+    @property
+    def emits_paths(self) -> bool:
+        return self.output == OUTPUT_OHLCV_PATHS
+
+    def as_dict(self) -> dict:
+        return {
+            "output": self.output,
+            "hardware": self.hardware,
+            "max_context": self.max_context,
+            "asset_generality": self.asset_generality,
+            "seedable_natively": self.seedable_natively,
+        }
+
+
+# --------------------------------------------------------------------------
+# Result
+# --------------------------------------------------------------------------
+
+
+@dataclass
+class ForecastResult:
+    """One multi-step forecast.
+
+    `quantiles` is (horizon, n_levels) over the *close* price, always present.
+    `paths` is (n_samples, horizon, 5) of OHLCV and is present only for
+    `ohlcv_paths` models -- the UI checks the capability, never this field, so
+    that a model which merely happens to return paths cannot change how it is
+    rendered.
+    """
+
+    quantiles: np.ndarray
+    levels: tuple[float, ...]
+    horizon: int
+    context_len: int
+    inference_version: str
+    seed: int
+    n_samples: int
+    paths: np.ndarray | None = None
+
+    def __post_init__(self):
+        self.quantiles = np.asarray(self.quantiles, dtype="float64")
+        if self.quantiles.shape != (self.horizon, len(self.levels)):
+            raise AdapterError(
+                f"quantiles shape {self.quantiles.shape} != "
+                f"{(self.horizon, len(self.levels))}"
+            )
+        if not np.all(np.isfinite(self.quantiles)):
+            raise AdapterError("forecast contains non-finite values")
+        # Quantiles must not cross. Sorting along the level axis is the honest
+        # repair for the tiny numerical inversions that sampling produces, and
+        # it is what makes the coverage arithmetic downstream well-defined.
+        self.quantiles = np.sort(self.quantiles, axis=1)
+        if self.paths is not None:
+            self.paths = np.asarray(self.paths, dtype="float64")
+            if self.paths.ndim != 3 or self.paths.shape[1] != self.horizon:
+                raise AdapterError(f"paths shape {self.paths.shape} is not (n, {self.horizon}, k)")
+
+    def level_index(self, level: float) -> int:
+        for i, lv in enumerate(self.levels):
+            if abs(lv - level) < 1e-9:
+                return i
+        raise AdapterError(f"level {level} not in {self.levels}")
+
+    def band(self, low: float = 0.1, high: float = 0.9):
+        return (self.quantiles[:, self.level_index(low)],
+                self.quantiles[:, self.level_index(high)])
+
+    def median(self) -> np.ndarray:
+        return self.quantiles[:, self.level_index(0.5)]
+
+    def dispersion(self) -> np.ndarray:
+        """Per-step spread, as a fraction of the median.
+
+        Sampled-path standard deviation where paths exist, band half-width
+        otherwise. Both are a width; they are not the same statistic, and the
+        UI labels which one it is showing.
+        """
+        med = np.abs(self.median()) + 1e-12
+        if self.paths is not None:
+            close = self.paths[:, :, OHLCV_COLUMNS.index("close")]
+            return close.std(axis=0) / med
+        lo, hi = self.band()
+        return (hi - lo) / 2.0 / med
+
+
+# --------------------------------------------------------------------------
+# Context validation
+# --------------------------------------------------------------------------
+
+
+def check_context(context: pd.DataFrame, issued_ts: pd.Timestamp | None = None,
+                  min_len: int = 32) -> pd.DataFrame:
+    """Validate a context window, or raise.
+
+    This is the structural half of the no-lookahead guarantee. It is not a
+    convention that callers are asked to honour: every adapter runs it on every
+    call, so a forecast issued from data it should not have seen fails loudly
+    at the point of use.
+    """
+    if not isinstance(context, pd.DataFrame):
+        raise ContextError("context must be a DataFrame")
+
+    missing = [c for c in OHLCV_COLUMNS if c not in context.columns]
+    if missing:
+        raise ContextError(f"context is missing columns {missing}")
+
+    if len(context) < min_len:
+        raise ContextError(f"context has {len(context)} bars, need at least {min_len}")
+
+    if "ts" not in context.columns:
+        raise ContextError("context must carry a 'ts' column")
+
+    ts = pd.to_datetime(context["ts"], utc=True)
+    if ts.isna().any():
+        raise ContextError("context has unparseable timestamps")
+    if not ts.is_monotonic_increasing:
+        raise ContextError("context timestamps are not sorted ascending")
+    if ts.duplicated().any():
+        raise ContextError("context has duplicate timestamps")
+
+    prices = context[list(OHLCV_COLUMNS)]
+    if not np.isfinite(prices.to_numpy(dtype="float64")).all():
+        raise ContextError("context contains NaN or infinite values")
+    if (context[["open", "high", "low", "close"]].to_numpy(dtype="float64") <= 0).any():
+        raise ContextError("context contains non-positive prices")
+
+    # A hole in the cache means the model sees two bars as adjacent when they
+    # are weeks apart, and produces a confident wrong answer from it.
+    #
+    # But "irregular spacing" is not the same as "missing data". An hourly
+    # equity series closes for ~17 hours every night and ~65 hours every
+    # weekend; those gaps are the market, not the cache. Judging them against
+    # the modal bar rejected every SPY and NVDA hourly context outright.
+    #
+    # So the threshold adapts to the series' own gap distribution: a session
+    # boundary recurs and therefore sits inside the 99th percentile, while a
+    # genuinely absent period stands outside it.
+    if len(ts) > 20:
+        deltas = ts.diff().dropna()
+        modal = deltas.mode()
+        if len(modal):
+            step = modal.iloc[0]
+            p99 = deltas.quantile(0.99)
+
+            # Any *single* gap far beyond the series' own worst regular one is
+            # a hole, however few there are. This is the check that survives a
+            # series where absence has become the pattern -- an adaptive
+            # threshold alone would quietly normalise that.
+            hard = max(step * 24, p99 * 5)
+            worst = deltas.max()
+            if worst > hard:
+                raise ContextError(
+                    f"context has a {worst} gap, far beyond its own session "
+                    f"pattern; the cache is incomplete for this window"
+                )
+
+            # And an accumulation of smaller anomalies is a hole too.
+            ceiling = max(step * 4, p99 * 1.5)
+            bad = deltas[deltas > ceiling]
+            if len(bad) > max(2, len(ts) // 50):
+                raise ContextError(
+                    f"context has {len(bad)} gaps beyond its own session pattern "
+                    f"(> {ceiling}); the cache is incomplete for this window"
+                )
+
+    if issued_ts is not None:
+        issued = pd.Timestamp(issued_ts)
+        if issued.tzinfo is None:
+            issued = issued.tz_localize("UTC")
+        last = ts.iloc[-1]
+        if last > issued:
+            raise LookaheadError(
+                f"context ends at {last.isoformat()}, after issued_ts "
+                f"{issued.isoformat()}: a forecast may only see data at or "
+                f"before the moment it is issued"
+            )
+
+    return context
+
+
+# --------------------------------------------------------------------------
+# Determinism
+# --------------------------------------------------------------------------
+
+
+def seed_everything(seed: int) -> None:
+    """Pin every RNG an adapter might reach for.
+
+    Seeding numpy alone is not enough: the sampling models draw through torch,
+    and Kronos in particular calls `torch.multinomial` with no seed argument of
+    its own. This is what makes "same inputs and seed produce bit-identical
+    output" true rather than aspirational.
+    """
+    seed = int(seed) % (2 ** 31 - 1)
+    np.random.seed(seed)
+    try:
+        import random
+
+        random.seed(seed)
+    except Exception:  # pragma: no cover
+        pass
+    try:
+        import torch
+
+        torch.manual_seed(seed)
+        if torch.cuda.is_available():
+            torch.cuda.manual_seed_all(seed)
+    except ImportError:
+        pass
+
+
+# --------------------------------------------------------------------------
+# The interface
+# --------------------------------------------------------------------------
+
+
+class ForecastAdapter(ABC):
+    """Uniform interface over multi-step probabilistic forecasters."""
+
+    family: str = "base"
+    # Bumped when this adapter's own logic changes the numbers it produces.
+    adapter_version: str = "1"
+
+    def __init__(self, model_id: str, revision: str | None = None,
+                 device: str | None = None):
+        self.model_id = model_id
+        self.revision = revision
+        self.device = device or default_device()
+        self._model = None
+        self._resolved_revision: str | None = None
+
+    # -- interface --------------------------------------------------------
+
+    @abstractmethod
+    def load(self, model_id: str | None = None, revision: str | None = None) -> "ForecastAdapter":
+        """Materialise the model. Idempotent."""
+
+    @abstractmethod
+    def predict(self, context_ohlcv: pd.DataFrame, horizon: int,
+                n_samples: int = config.DEFAULT_N_SAMPLES, seed: int = 0,
+                issued_ts: pd.Timestamp | None = None) -> ForecastResult:
+        """Forecast `horizon` bars ahead from `context_ohlcv`.
+
+        Must be bit-reproducible in `seed`.
+        """
+
+    @abstractmethod
+    def capabilities(self) -> Capabilities:
+        """What this model can do. The UI renders from this and nothing else."""
+
+    # -- shared -----------------------------------------------------------
+
+    def component_versions(self) -> dict[str, str]:
+        """Every external thing whose version changes the output.
+
+        Overridden by families that load a companion repo (Kronos ships its
+        tokenizer separately) or depend on an inference package whose version
+        moves the numbers.
+        """
+        return {"model": f"{self.model_id}@{self.resolved_revision}"}
+
+    def inference_version(self) -> str:
+        """Identity of everything that determines the output values.
+
+        A short hash rather than the full component list, because it is written
+        onto every archived row; the components themselves are recorded once in
+        the registry so the hash can always be expanded.
+        """
+        parts = [config.INFERENCE_VERSION, self.family, self.adapter_version]
+        parts += [f"{k}={v}" for k, v in sorted(self.component_versions().items())]
+        digest = hashlib.sha256("|".join(parts).encode()).hexdigest()[:12]
+        return f"{config.INFERENCE_VERSION}+{self.family}.{digest}"
+
+    @property
+    def resolved_revision(self) -> str:
+        return self._resolved_revision or self.revision or "unpinned"
+
+    def resolve_revision(self) -> str:
+        """Pin the model to an immutable commit sha before any inference runs.
+
+        A floating `main` would mean two forecasts a week apart are not
+        comparable and neither is reproducible, which defeats the archive.
+        """
+        if self._resolved_revision:
+            return self._resolved_revision
+        from huggingface_hub import HfApi
+
+        info = HfApi().model_info(self.model_id, revision=self.revision)
+        self._resolved_revision = info.sha
+        return self._resolved_revision
+
+    # -- helpers for subclasses -------------------------------------------
+
+    def _trim(self, context: pd.DataFrame) -> pd.DataFrame:
+        """Cut a context down to what the model can actually attend over."""
+        cap = self.capabilities().max_context
+        return context.iloc[-cap:] if len(context) > cap else context
+
+    @staticmethod
+    def _quantiles_from_paths(paths_close: np.ndarray,
+                              levels=config.QUANTILE_LEVELS) -> np.ndarray:
+        """(n_samples, horizon) -> (horizon, n_levels)."""
+        return np.quantile(paths_close, list(levels), axis=0).T
+
+
+def default_device() -> str:
+    try:
+        import torch
+
+        if torch.cuda.is_available():
+            return "cuda"
+    except ImportError:
+        pass
+    return "cpu"

src/adapters/baseline.py

@@ -0,0 +1,214 @@
+"""Naive baselines, deliberately first-class citizens of the Arena.
+
+A foundation model that cannot out-forecast "tomorrow looks like today" is not
+worth the GPU time, and a leaderboard that quietly omits that comparison is
+flattering rather than useful. So the baselines are enrolled, archived and
+graded on exactly the same footing as everything else, and they appear on the
+standings table next to the models they embarrass.
+
+They are also the only family that runs with no weights, no network and no
+torch, which makes them the fixture the test suite reasons about: capability
+gating, determinism and coverage arithmetic are all checked here first, where
+the expected answer can be worked out by hand.
+
+`random-walk` is the reference. Its band comes from the empirical distribution
+of historical log returns, scaled by sqrt(h) -- which is the correct widening
+for a driftless random walk and is why a well-calibrated foundation model
+should be able to beat it on error but will struggle to beat it on coverage.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from .. import config
+from .base import (OHLCV_COLUMNS, OUTPUT_OHLCV_PATHS, OUTPUT_QUANTILE_LINE,
+                   AdapterError, Capabilities, ForecastAdapter,
+                   ForecastResult, check_context)
+
+# `kind` -> how the median path is built, and what the adapter emits.
+BASELINE_MODELS = {
+    "baseline/random-walk": {
+        "kind": "naive",
+        "output": OUTPUT_QUANTILE_LINE,
+        "display": "Random walk",
+    },
+    "baseline/drift": {
+        "kind": "drift",
+        "output": OUTPUT_QUANTILE_LINE,
+        "display": "Drift",
+    },
+    # A bootstrap over historical candles, so there is at least one path-
+    # emitting reference to hold Kronos's ghost paths against.
+    "baseline/bootstrap": {
+        "kind": "bootstrap",
+        "output": OUTPUT_OHLCV_PATHS,
+        "display": "Block bootstrap",
+    },
+}
+
+# How much history the return distribution is estimated from.
+LOOKBACK = 256
+
+
+class BaselineAdapter(ForecastAdapter):
+    """Closed-form and bootstrap baselines. No weights, no network."""
+
+    family = "baseline"
+    adapter_version = "1"
+
+    def __init__(self, model_id: str, revision: str | None = None,
+                 device: str | None = None, hardware: str | None = None):
+        super().__init__(model_id, revision=revision, device=device)
+        spec = BASELINE_MODELS.get(model_id)
+        if spec is None:
+            raise AdapterError(
+                f"unknown baseline {model_id!r}; known: {sorted(BASELINE_MODELS)}")
+        self.kind = spec["kind"]
+        self._output = spec["output"]
+
+    def capabilities(self) -> Capabilities:
+        return Capabilities(
+            output=self._output,
+            hardware="cpu",
+            max_context=LOOKBACK,
+            asset_generality="general",
+            seedable_natively=True,
+        )
+
+    def component_versions(self) -> dict[str, str]:
+        # No revision to pin: the model *is* this file.
+        return {"model": self.model_id, "kind": self.kind, "lookback": str(LOOKBACK)}
+
+    def resolve_revision(self) -> str:
+        self._resolved_revision = "builtin"
+        return self._resolved_revision
+
+    def load(self, model_id: str | None = None, revision: str | None = None):
+        if model_id and model_id != self.model_id:
+            spec = BASELINE_MODELS.get(model_id)
+            if spec is None:
+                raise AdapterError(f"unknown baseline {model_id!r}")
+            self.model_id = model_id
+            self.kind = spec["kind"]
+            self._output = spec["output"]
+        self.resolve_revision()
+        self._model = self.kind
+        return self
+
+    def predict(self, context_ohlcv: pd.DataFrame, horizon: int,
+                n_samples: int = config.DEFAULT_N_SAMPLES, seed: int = 0,
+                issued_ts: pd.Timestamp | None = None) -> ForecastResult:
+        check_context(context_ohlcv, issued_ts=issued_ts)
+        if horizon < 1:
+            raise AdapterError("horizon must be at least 1")
+        if self._model is None:
+            self.load()
+
+        ctx = self._trim(context_ohlcv)
+        close = ctx["close"].to_numpy(dtype="float64")
+        last = float(close[-1])
+
+        log_returns = np.diff(np.log(close))
+        if len(log_returns) < 8:
+            raise AdapterError("need at least 9 bars to estimate a return distribution")
+
+        steps = np.arange(1, horizon + 1, dtype="float64")
+
+        # A local RNG, not the global one: a baseline must not be able to
+        # perturb the sampling of whatever model runs after it in a matchup.
+        rng = np.random.default_rng(int(seed))
+
+        if self.kind == "bootstrap":
+            paths = self._bootstrap_paths(ctx, horizon, n_samples, rng)
+            close_paths = paths[:, :, OHLCV_COLUMNS.index("close")]
+            quantiles = self._quantiles_from_paths(close_paths)
+            return ForecastResult(
+                quantiles=quantiles, levels=config.QUANTILE_LEVELS,
+                horizon=horizon, context_len=len(ctx),
+                inference_version=self.inference_version(),
+                seed=int(seed), n_samples=int(n_samples), paths=paths,
+            )
+
+        # Analytic band. The median is flat for `naive` and extends the mean
+        # historical return for `drift`; the width is the empirical return
+        # quantile scaled by sqrt(h), which is the random walk's own spread.
+        mu = float(log_returns.mean()) if self.kind == "drift" else 0.0
+        sigma = float(log_returns.std(ddof=1))
+
+        cols = []
+        for level in config.QUANTILE_LEVELS:
+            # Normal quantile via the error function's inverse, so scipy is not
+            # a dependency for the one family that has no dependencies.
+            z = _norm_ppf(level)
+            cols.append(last * np.exp(mu * steps + z * sigma * np.sqrt(steps)))
+        quantiles = np.stack(cols, axis=1)
+
+        return ForecastResult(
+            quantiles=quantiles, levels=config.QUANTILE_LEVELS,
+            horizon=horizon, context_len=len(ctx),
+            inference_version=self.inference_version(),
+            seed=int(seed), n_samples=int(n_samples), paths=None,
+        )
+
+    def _bootstrap_paths(self, ctx: pd.DataFrame, horizon: int,
+                         n_samples: int, rng) -> np.ndarray:
+        """Resample historical candles in blocks, chained off the last close.
+
+        Blocks rather than single bars, because independent draws destroy the
+        volatility clustering that makes a market path look like a market path.
+        """
+        frame = ctx[list(OHLCV_COLUMNS)].to_numpy(dtype="float64")
+        close = frame[:, OHLCV_COLUMNS.index("close")]
+        log_returns = np.diff(np.log(close))
+        # Per-bar shape: how open/high/low/volume sat relative to that bar's
+        # close. Resampling the shape keeps the sampled candles plausible.
+        ratios = frame[1:, :4] / close[1:, None]
+        volumes = frame[1:, OHLCV_COLUMNS.index("volume")]
+
+        block = max(1, min(8, len(log_returns) // 4))
+        n = len(log_returns)
+        paths = np.empty((n_samples, horizon, len(OHLCV_COLUMNS)), dtype="float64")
+
+        for s in range(n_samples):
+            picked_r, picked_i = [], []
+            while len(picked_r) < horizon:
+                start = int(rng.integers(0, max(1, n - block)))
+                for j in range(start, min(start + block, n)):
+                    picked_r.append(log_returns[j])
+                    picked_i.append(j)
+            picked_r = np.asarray(picked_r[:horizon])
+            picked_i = np.asarray(picked_i[:horizon])
+
+            closes = float(close[-1]) * np.exp(np.cumsum(picked_r))
+            shape = ratios[picked_i]
+            paths[s, :, 0] = closes * shape[:, 0]     # open
+            paths[s, :, 1] = closes * shape[:, 1]     # high
+            paths[s, :, 2] = closes * shape[:, 2]     # low
+            paths[s, :, 3] = closes                   # close
+            paths[s, :, 4] = volumes[picked_i]
+
+        # Keep the sampled candle self-consistent, same rule as Kronos.
+        body_hi = np.maximum(paths[:, :, 0], paths[:, :, 3])
+        body_lo = np.minimum(paths[:, :, 0], paths[:, :, 3])
+        paths[:, :, 1] = np.maximum(paths[:, :, 1], body_hi)
+        paths[:, :, 2] = np.minimum(paths[:, :, 2], body_lo)
+        return paths
+
+
+def _norm_ppf(p: float) -> float:
+    """Inverse standard normal CDF, via the inverse error function."""
+    from math import erf, sqrt
+
+    if not 0.0 < p < 1.0:
+        raise AdapterError(f"quantile level {p} out of range")
+    # Bisection: exact enough (1e-12) and keeps this file dependency-free.
+    lo, hi = -12.0, 12.0
+    for _ in range(200):
+        mid = (lo + hi) / 2.0
+        if 0.5 * (1.0 + erf(mid / sqrt(2.0))) < p:
+            lo = mid
+        else:
+            hi = mid
+    return (lo + hi) / 2.0

src/adapters/chronos.py

@@ -0,0 +1,183 @@
+"""Chronos-Bolt -- direct multi-step quantile forecasting over the close.
+
+Bolt is the fast half of Amazon's Chronos family: an encoder-decoder that emits
+quantiles for the whole horizon in a single forward pass, with no sampling
+loop. That makes it the cheapest family here by a wide margin and the natural
+CPU tier, and it is why all four sizes are enrolled -- comparing them isolates
+model capacity from every other variable in the Arena.
+
+It is a `quantile_line` model. It sees a univariate close series, not candles,
+and it emits a band and nothing else. The UI must not draw ghost paths for it,
+and the capability declaration is what stops that happening.
+
+A note on determinism: Bolt's forward pass is deterministic, so the seed does
+not change its output. The seed is still recorded on every archived row, both
+because the interface promises it and because the reproducibility test must be
+able to run identically across every family.
+"""
+
+from __future__ import annotations
+
+import logging
+
+import numpy as np
+import pandas as pd
+
+from .. import config
+from .base import (OUTPUT_QUANTILE_LINE, AdapterError, Capabilities,
+                   ForecastAdapter, ForecastResult, check_context,
+                   seed_everything)
+
+log = logging.getLogger("arena.adapters.chronos")
+
+# Context length is the training context from the Chronos-Bolt model card.
+# Bolt was trained to emit 64 steps directly; longer horizons are produced by
+# rolling the model forward, which `predict` handles explicitly.
+CHRONOS_MODELS = {
+    "amazon/chronos-bolt-tiny": {"max_context": 2048, "params": "9M", "hardware": "cpu"},
+    "amazon/chronos-bolt-mini": {"max_context": 2048, "params": "21M", "hardware": "cpu"},
+    "amazon/chronos-bolt-small": {"max_context": 2048, "params": "48M", "hardware": "cpu"},
+    "amazon/chronos-bolt-base": {"max_context": 2048, "params": "205M", "hardware": "cpu"},
+}
+
+# The horizon Bolt emits in one pass. Beyond it the forecast is rolled forward
+# on its own median, which is a real approximation and is labelled as one.
+NATIVE_HORIZON = 64
+
+
+class ChronosAdapter(ForecastAdapter):
+    """`amazon/chronos-bolt-*` direct quantile forecasters."""
+
+    family = "chronos"
+    adapter_version = "1"
+
+    def __init__(self, model_id: str, revision: str | None = None,
+                 device: str | None = None, hardware: str | None = None):
+        super().__init__(model_id, revision=revision, device=device)
+        spec = CHRONOS_MODELS.get(model_id, {})
+        self._max_context = int(spec.get("max_context", 2048))
+        self._hardware = hardware or spec.get("hardware", "cpu")
+
+    def capabilities(self) -> Capabilities:
+        return Capabilities(
+            output=OUTPUT_QUANTILE_LINE,
+            hardware=self._hardware,
+            max_context=self._max_context,
+            asset_generality="general",
+            seedable_natively=True,
+        )
+
+    def component_versions(self) -> dict[str, str]:
+        versions = {"model": f"{self.model_id}@{self.resolved_revision}"}
+        for pkg in ("chronos", "torch"):
+            try:
+                mod = __import__(pkg)
+                versions[pkg] = getattr(mod, "__version__", "unknown")
+            except ImportError:
+                pass
+        return versions
+
+    def load(self, model_id: str | None = None, revision: str | None = None):
+        if model_id and model_id != self.model_id:
+            self.model_id = model_id
+            spec = CHRONOS_MODELS.get(model_id, {})
+            self._max_context = int(spec.get("max_context", self._max_context))
+            self._hardware = spec.get("hardware", self._hardware)
+            self._model = None
+        if revision:
+            self.revision = revision
+        if self._model is not None:
+            return self
+
+        try:
+            from chronos import BaseChronosPipeline
+        except ImportError as e:  # pragma: no cover
+            raise AdapterError(
+                "chronos-forecasting is not installed; add it to requirements.txt"
+            ) from e
+
+        import torch
+
+        self.resolve_revision()
+        self._model = BaseChronosPipeline.from_pretrained(
+            self.model_id,
+            revision=self._resolved_revision,
+            device_map=self.device,
+            # float32 on CPU: bfloat16 on CPU is emulated and slower, and the
+            # Arena's whole premise is that archived numbers are reproducible,
+            # which mixed precision makes harder to guarantee across hardware.
+            torch_dtype=torch.float32 if self.device == "cpu" else torch.bfloat16,
+        )
+        return self
+
+    def predict(self, context_ohlcv: pd.DataFrame, horizon: int,
+                n_samples: int = config.DEFAULT_N_SAMPLES, seed: int = 0,
+                issued_ts: pd.Timestamp | None = None) -> ForecastResult:
+        check_context(context_ohlcv, issued_ts=issued_ts)
+        if horizon < 1:
+            raise AdapterError("horizon must be at least 1")
+
+        if self._model is None:
+            self.load()
+
+        import torch
+
+        ctx = self._trim(context_ohlcv)
+        closes = ctx["close"].to_numpy(dtype="float32")
+
+        seed_everything(seed)
+        levels = list(config.QUANTILE_LEVELS)
+
+        chunks: list[np.ndarray] = []
+        series = closes.copy()
+        remaining = horizon
+
+        while remaining > 0:
+            step = min(remaining, NATIVE_HORIZON)
+            with torch.inference_mode():
+                # chronos-forecasting 2.x takes the series positionally as
+                # `inputs`; the 1.x `context=` keyword no longer exists.
+                q, _mean = self._model.predict_quantiles(
+                    [torch.tensor(series)],
+                    prediction_length=step,
+                    quantile_levels=levels,
+                )
+            # (1, step, n_levels) -> (step, n_levels)
+            block = _to_array(q)[0][:step]
+            chunks.append(block)
+            remaining -= step
+            if remaining > 0:
+                # Roll forward on the median. This is the honest weak point of
+                # any horizon past 64: uncertainty stops compounding properly
+                # because the continuation is a point estimate.
+                median = block[:, levels.index(0.5)]
+                series = np.concatenate([series, median.astype("float32")])
+                if len(series) > self._max_context:
+                    series = series[-self._max_context:]
+
+        quantiles = np.concatenate(chunks, axis=0)[:horizon]
+
+        return ForecastResult(
+            quantiles=quantiles,
+            levels=config.QUANTILE_LEVELS,
+            horizon=horizon,
+            context_len=len(ctx),
+            inference_version=self.inference_version(),
+            seed=int(seed),
+            n_samples=int(n_samples),
+            paths=None,
+        )
+
+
+def _to_array(quantiles) -> np.ndarray:
+    """Normalise what the pipeline returns into (batch, steps, levels).
+
+    Bolt returns one stacked tensor. Keeping the unwrapping in one place means
+    a future Chronos variant that returns a list of per-item tensors is a
+    change here rather than in `predict`.
+    """
+    if isinstance(quantiles, (list, tuple)):
+        return np.stack([np.asarray(q.cpu() if hasattr(q, "cpu") else q)
+                         for q in quantiles], axis=0)
+    arr = quantiles.cpu().numpy() if hasattr(quantiles, "cpu") else np.asarray(quantiles)
+    return arr

src/adapters/kronos.py

@@ -0,0 +1,296 @@
+"""Kronos -- a foundation model trained on candlesticks rather than on numbers.
+
+Kronos is the only family here that is native to OHLCV: it tokenises whole
+candles and generates whole candles, so it is the family that can emit sampled
+price *paths* rather than just a band on the close. That is what drives the
+ghost-path view and the sampled-path dispersion widget.
+
+Two facts about it shape this adapter.
+
+**It has no inference package.** Weights ship on the Hub, the code ships only
+on GitHub, and the `kronos` name on PyPI is an unrelated Django library. The
+source is vendored under `vendor/kronos` at a pinned commit; see the
+PROVENANCE.md there.
+
+**It has no seed argument.** Sampling runs through `torch.multinomial` against
+the global RNG. Determinism is therefore something this adapter imposes, by
+seeding immediately before inference, rather than something Kronos offers.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+from .. import config
+from .base import (OHLCV_COLUMNS, OUTPUT_OHLCV_PATHS, AdapterError,
+                   Capabilities, ForecastAdapter, ForecastResult,
+                   check_context, seed_everything)
+
+log = logging.getLogger("arena.adapters.kronos")
+
+_VENDOR = Path(__file__).resolve().parents[2] / "vendor"
+if str(_VENDOR) not in sys.path:
+    sys.path.insert(0, str(_VENDOR))
+
+# Each Kronos checkpoint is trained against one tokenizer and is meaningless
+# with any other, so the pairing is fixed here rather than left to the caller.
+# Context lengths are the model card's, not guesses.
+KRONOS_MODELS = {
+    "NeoQuasar/Kronos-mini": {
+        "tokenizer": "NeoQuasar/Kronos-Tokenizer-2k",
+        "max_context": 2048,
+        "params": "4.1M",
+        # Measured 6.7-7.1s warm at h=24, n=32 on an M-series laptop. That is
+        # inside the 8s budget here but cpu-basic is slower, so the tier is
+        # confirmed by `scripts/benchmark.py` running on the Space itself and
+        # demoted in the registry if it misses.
+        "hardware": "cpu",
+    },
+    "NeoQuasar/Kronos-small": {
+        "tokenizer": "NeoQuasar/Kronos-Tokenizer-base",
+        "max_context": 512,
+        "params": "24.7M",
+        # Measured 23.5-24.3s warm at h=24, n=32 on an M-series laptop, which
+        # is faster than cpu-basic. Nowhere near the 8s warm budget.
+        "hardware": "gpu",
+    },
+    "NeoQuasar/Kronos-base": {
+        "tokenizer": "NeoQuasar/Kronos-Tokenizer-base",
+        "max_context": 512,
+        "params": "102.3M",
+        # 102M params generating autoregressively is not a cpu-basic workload.
+        "hardware": "gpu",
+    },
+}
+
+# Sampling defaults. These are the model card's own recommended values; they
+# are recorded in `component_versions` because changing them changes every
+# number the model produces.
+DEFAULT_T = 1.0
+DEFAULT_TOP_P = 0.9
+DEFAULT_TOP_K = 0
+CLIP = 5
+
+
+class KronosAdapter(ForecastAdapter):
+    """`NeoQuasar/Kronos-*` candlestick generators."""
+
+    family = "kronos"
+    adapter_version = "1"
+
+    def __init__(self, model_id: str, revision: str | None = None,
+                 device: str | None = None, tokenizer_id: str | None = None,
+                 tokenizer_revision: str | None = None,
+                 hardware: str | None = None):
+        super().__init__(model_id, revision=revision, device=device)
+        spec = KRONOS_MODELS.get(model_id, {})
+        self.tokenizer_id = tokenizer_id or spec.get("tokenizer")
+        self.tokenizer_revision = tokenizer_revision
+        self._max_context = int(spec.get("max_context", 512))
+        # The declared default, which the registry may override downward after
+        # a measured latency run. Declaring a tier a model cannot hold is how
+        # a user ends up watching a spinner for ninety seconds.
+        self._hardware = hardware or spec.get("hardware", "gpu")
+        self._tokenizer = None
+        self._resolved_tokenizer_revision: str | None = None
+
+    # -- capabilities -----------------------------------------------------
+
+    def capabilities(self) -> Capabilities:
+        return Capabilities(
+            output=OUTPUT_OHLCV_PATHS,
+            # Kronos generates autoregressively -- one forward pass per
+            # forecast step. The tier here is the declared default; a measured
+            # miss against the CPU budget demotes it in the registry.
+            hardware=self._hardware,
+            max_context=self._max_context,
+            asset_generality="financial",
+            seedable_natively=False,
+        )
+
+    def component_versions(self) -> dict[str, str]:
+        versions = {
+            "model": f"{self.model_id}@{self.resolved_revision}",
+            "tokenizer": f"{self.tokenizer_id}@{self._resolved_tokenizer_revision or 'unpinned'}",
+            "sampling": f"T={DEFAULT_T},top_p={DEFAULT_TOP_P},top_k={DEFAULT_TOP_K},clip={CLIP}",
+            "vendor": "kronos@67b630e6",
+        }
+        try:
+            import torch
+
+            versions["torch"] = torch.__version__
+        except ImportError:
+            pass
+        return versions
+
+    # -- load -------------------------------------------------------------
+
+    def load(self, model_id: str | None = None, revision: str | None = None):
+        if model_id and model_id != self.model_id:
+            self.model_id = model_id
+            spec = KRONOS_MODELS.get(model_id, {})
+            self.tokenizer_id = spec.get("tokenizer", self.tokenizer_id)
+            self._max_context = int(spec.get("max_context", self._max_context))
+            self._hardware = spec.get("hardware", self._hardware)
+            self._model = None
+        if revision:
+            self.revision = revision
+        if self._model is not None:
+            return self
+
+        if not self.tokenizer_id:
+            raise AdapterError(
+                f"no tokenizer known for {self.model_id}; Kronos checkpoints are "
+                f"only valid with the tokenizer they were trained against"
+            )
+
+        try:
+            from kronos import Kronos, KronosTokenizer
+        except ImportError as e:  # pragma: no cover
+            raise AdapterError(
+                "the vendored Kronos source is not importable; check vendor/kronos"
+            ) from e
+
+        self.resolve_revision()
+        self._resolved_tokenizer_revision = _resolve(self.tokenizer_id,
+                                                     self.tokenizer_revision)
+
+        self._tokenizer = KronosTokenizer.from_pretrained(
+            self.tokenizer_id, revision=self._resolved_tokenizer_revision)
+        self._model = Kronos.from_pretrained(
+            self.model_id, revision=self._resolved_revision)
+
+        self._tokenizer = self._tokenizer.to(self.device).eval()
+        self._model = self._model.to(self.device).eval()
+        return self
+
+    # -- predict ----------------------------------------------------------
+
+    def predict(self, context_ohlcv: pd.DataFrame, horizon: int,
+                n_samples: int = config.DEFAULT_N_SAMPLES, seed: int = 0,
+                issued_ts: pd.Timestamp | None = None) -> ForecastResult:
+        check_context(context_ohlcv, issued_ts=issued_ts)
+        if horizon < 1:
+            raise AdapterError("horizon must be at least 1")
+        if n_samples < 1:
+            raise AdapterError("n_samples must be at least 1")
+
+        if self._model is None:
+            self.load()
+
+        import torch
+
+        from kronos.kronos import auto_regressive_inference, calc_time_stamps
+
+        ctx = self._trim(context_ohlcv).reset_index(drop=True)
+        ts = pd.to_datetime(ctx["ts"], utc=True)
+
+        # Kronos consumes `amount` (quote volume) alongside OHLCV. Where the
+        # cache has no amount column, the upstream predictor's own fallback is
+        # volume times the mean price, and that is reproduced here so the
+        # inputs match what `KronosPredictor` would have built.
+        frame = ctx[list(OHLCV_COLUMNS)].astype("float64").copy()
+        if "amount" in ctx.columns:
+            frame["amount"] = ctx["amount"].astype("float64")
+        else:
+            frame["amount"] = frame["volume"] * frame[["open", "high", "low", "close"]].mean(axis=1)
+
+        x = frame.to_numpy(dtype="float32")
+        future_ts = _future_timestamps(ts, horizon)
+
+        # Normalisation, replicated from `KronosPredictor.predict`. It is
+        # replicated rather than called because the upstream method averages
+        # the sampled paths away before returning, and the paths are the point.
+        # `test_kronos_vendor.py` asserts this reproduces the upstream result.
+        x_mean = x.mean(axis=0)
+        x_std = x.std(axis=0)
+        x_norm = (x - x_mean) / (x_std + 1e-5)
+        x_norm = np.clip(x_norm, -CLIP, CLIP)
+
+        x_stamp = calc_time_stamps(ts.reset_index(drop=True)).to_numpy(dtype="float32")
+        y_stamp = calc_time_stamps(pd.Series(future_ts)).to_numpy(dtype="float32")
+
+        x_t = torch.from_numpy(x_norm[np.newaxis, :].astype("float32")).to(self.device)
+        xs_t = torch.from_numpy(x_stamp[np.newaxis, :]).to(self.device)
+        ys_t = torch.from_numpy(y_stamp[np.newaxis, :]).to(self.device)
+
+        # The seed goes in here and nowhere else: Kronos draws through the
+        # global torch RNG, so this call is what makes the result reproducible.
+        seed_everything(seed)
+
+        with torch.inference_mode():
+            raw = auto_regressive_inference(
+                self._tokenizer, self._model, x_t, xs_t, ys_t,
+                max_context=self._max_context, pred_len=horizon, clip=CLIP,
+                T=DEFAULT_T, top_k=DEFAULT_TOP_K, top_p=DEFAULT_TOP_P,
+                sample_count=int(n_samples), verbose=False,
+                return_paths=True,
+            )
+
+        # (batch=1, n_samples, seq, features) -> (n_samples, horizon, features)
+        paths = np.asarray(raw)[0][:, -horizon:, :]
+        paths = paths * (x_std + 1e-5) + x_mean
+
+        # A sampled candle can come back internally inconsistent -- a high
+        # below the close, say -- because each field is decoded from its own
+        # token. Repairing it is more honest than rendering an impossible
+        # candle, and it only ever widens the bar to contain what it must.
+        paths = _repair_candles(paths)
+
+        close = paths[:, :, OHLCV_COLUMNS.index("close")]
+        quantiles = self._quantiles_from_paths(close)
+
+        return ForecastResult(
+            quantiles=quantiles,
+            levels=config.QUANTILE_LEVELS,
+            horizon=horizon,
+            context_len=len(ctx),
+            inference_version=self.inference_version(),
+            seed=int(seed),
+            n_samples=int(n_samples),
+            paths=paths[:, :, :len(OHLCV_COLUMNS)],
+        )
+
+
+# --------------------------------------------------------------------------
+# Helpers
+# --------------------------------------------------------------------------
+
+
+def _resolve(repo_id: str, revision: str | None) -> str:
+    from huggingface_hub import HfApi
+
+    return HfApi().model_info(repo_id, revision=revision).sha
+
+
+def _future_timestamps(ts: pd.Series, horizon: int) -> pd.DatetimeIndex:
+    """Continue the context's own cadence forward.
+
+    Kronos conditions on calendar features, so the future stamps have to be
+    plausible rather than arbitrary. The modal spacing of the context is used
+    so that this works for both 1h and 1d without being told which it is.
+    """
+    if len(ts) < 2:
+        raise AdapterError("cannot infer cadence from fewer than two bars")
+    deltas = ts.diff().dropna()
+    step = deltas.mode().iloc[0] if len(deltas.mode()) else deltas.median()
+    last = ts.iloc[-1]
+    return pd.DatetimeIndex([last + step * (i + 1) for i in range(horizon)])
+
+
+def _repair_candles(paths: np.ndarray) -> np.ndarray:
+    """Force high >= max(o,c) and low <= min(o,c) on every sampled candle."""
+    o, h, l, c = (OHLCV_COLUMNS.index(k) for k in ("open", "high", "low", "close"))
+    body_hi = np.maximum(paths[:, :, o], paths[:, :, c])
+    body_lo = np.minimum(paths[:, :, o], paths[:, :, c])
+    paths[:, :, h] = np.maximum(paths[:, :, h], body_hi)
+    paths[:, :, l] = np.minimum(paths[:, :, l], body_lo)
+    # Volume is a count; a negative one is a decode artefact, not information.
+    v = OHLCV_COLUMNS.index("volume")
+    paths[:, :, v] = np.maximum(paths[:, :, v], 0.0)
+    return paths

src/adapters/timesfm.py

@@ -0,0 +1,198 @@
+"""TimesFM 2.5 -- Google's decoder-only time-series foundation model.
+
+A `quantile_line` family, like Chronos: it forecasts a univariate series and
+returns a quantile grid, with no notion of a candle and no sampled paths.
+
+Two things are worth knowing before changing this file.
+
+**The model card is out of date about installation.** It says a PyPI release is
+"coming soon" and directs you to clone the GitHub repo. That is stale --
+`timesfm==2.0.2` on PyPI does export `TimesFM_2p5_200M_torch`, and it installs
+with only numpy, safetensors, huggingface_hub and torch. Installing from a git
+URL instead would have put an unpinnable dependency in the Space's build.
+
+**It must be compiled before it can forecast, and compilation fixes the
+horizon.** `compile()` builds a cached decode function up to `max_horizon`, so
+compiling per request would dominate the latency. This adapter compiles once,
+at the largest horizon the Arena offers, and slices shorter forecasts out of
+that -- which is why `_ensure_compiled` exists rather than a line in `load`.
+"""
+
+from __future__ import annotations
+
+import logging
+
+import numpy as np
+import pandas as pd
+
+from .. import config
+from .base import (OUTPUT_QUANTILE_LINE, AdapterError, Capabilities,
+                   ForecastAdapter, ForecastResult, check_context,
+                   seed_everything)
+
+log = logging.getLogger("arena.adapters.timesfm")
+
+TIMESFM_MODELS = {
+    "google/timesfm-2.5-200m-pytorch": {
+        "max_context": 2048,   # the checkpoint supports 16384; see below
+        "params": "200M",
+        "hardware": "cpu",
+    },
+}
+
+# TimesFM 2.5's own ceiling is 16384, but `max_context` is what the compiled
+# decode function pads *every* input to, so an oversized value is paid on every
+# request whether the context is that long or not. 2048 covers the Arena's
+# longest offered context with room to spare.
+COMPILE_MAX_HORIZON = 256
+
+# The quantile grid TimesFM returns: column 0 is the mean, then 0.1 .. 0.9.
+QUANTILE_GRID = (0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9)
+
+
+class TimesFMAdapter(ForecastAdapter):
+    """`google/timesfm-2.5-*` quantile forecasters."""
+
+    family = "timesfm"
+    adapter_version = "1"
+
+    def __init__(self, model_id: str, revision: str | None = None,
+                 device: str | None = None, hardware: str | None = None):
+        super().__init__(model_id, revision=revision, device=device)
+        spec = TIMESFM_MODELS.get(model_id, {})
+        self._max_context = int(spec.get("max_context", 2048))
+        self._hardware = hardware or spec.get("hardware", "cpu")
+        self._compiled_horizon = 0
+
+    def capabilities(self) -> Capabilities:
+        return Capabilities(
+            output=OUTPUT_QUANTILE_LINE,
+            hardware=self._hardware,
+            max_context=self._max_context,
+            asset_generality="general",
+            seedable_natively=True,
+        )
+
+    def component_versions(self) -> dict[str, str]:
+        versions = {
+            "model": f"{self.model_id}@{self.resolved_revision}",
+            "forecast_config": (
+                f"max_context={self._max_context},max_horizon={COMPILE_MAX_HORIZON},"
+                f"normalize_inputs=True,continuous_quantile_head=True,"
+                f"fix_quantile_crossing=True"
+            ),
+        }
+        for pkg in ("timesfm", "torch"):
+            try:
+                mod = __import__(pkg)
+                versions[pkg] = getattr(mod, "__version__", "unknown")
+            except ImportError:
+                pass
+        return versions
+
+    def load(self, model_id: str | None = None, revision: str | None = None):
+        if model_id and model_id != self.model_id:
+            self.model_id = model_id
+            spec = TIMESFM_MODELS.get(model_id, {})
+            self._max_context = int(spec.get("max_context", self._max_context))
+            self._hardware = spec.get("hardware", self._hardware)
+            self._model = None
+            self._compiled_horizon = 0
+        if revision:
+            self.revision = revision
+        if self._model is not None:
+            return self
+
+        try:
+            import timesfm
+        except ImportError as e:  # pragma: no cover
+            raise AdapterError(
+                "timesfm is not installed; add it to requirements.txt"
+            ) from e
+
+        if not hasattr(timesfm, "TimesFM_2p5_200M_torch"):  # pragma: no cover
+            raise AdapterError(
+                "the installed timesfm does not expose the 2.5 API; pin >=2.0.2"
+            )
+
+        self.resolve_revision()
+        self._model = timesfm.TimesFM_2p5_200M_torch.from_pretrained(
+            self.model_id,
+            revision=self._resolved_revision,
+            # torch.compile spends tens of seconds warming up and buys little
+            # on a CPU box with batch size 1. It is the difference between
+            # clearing the cold-start budget and blowing straight through it.
+            torch_compile=(self.device == "cuda"),
+        )
+        return self
+
+    def _ensure_compiled(self) -> None:
+        if self._compiled_horizon >= COMPILE_MAX_HORIZON:
+            return
+        import timesfm
+
+        self._model.compile(timesfm.ForecastConfig(
+            max_context=self._max_context,
+            max_horizon=COMPILE_MAX_HORIZON,
+            normalize_inputs=True,
+            use_continuous_quantile_head=True,
+            force_flip_invariance=True,
+            infer_is_positive=True,
+            # Without this, sampled quantiles can cross at long horizons and
+            # the band arithmetic downstream stops meaning anything.
+            fix_quantile_crossing=True,
+        ))
+        self._compiled_horizon = COMPILE_MAX_HORIZON
+
+    def predict(self, context_ohlcv: pd.DataFrame, horizon: int,
+                n_samples: int = config.DEFAULT_N_SAMPLES, seed: int = 0,
+                issued_ts: pd.Timestamp | None = None) -> ForecastResult:
+        check_context(context_ohlcv, issued_ts=issued_ts)
+        if horizon < 1:
+            raise AdapterError("horizon must be at least 1")
+        if horizon > COMPILE_MAX_HORIZON:
+            raise AdapterError(
+                f"horizon {horizon} exceeds the compiled maximum {COMPILE_MAX_HORIZON}"
+            )
+
+        if self._model is None:
+            self.load()
+        self._ensure_compiled()
+
+        ctx = self._trim(context_ohlcv)
+        closes = ctx["close"].to_numpy(dtype="float32")
+
+        seed_everything(seed)
+        _point, quantile_out = self._model.forecast(
+            horizon=horizon, inputs=[closes])
+
+        # (1, horizon, 10) -> (horizon, 10); drop the mean in column 0.
+        grid = np.asarray(quantile_out)[0][:horizon, 1:]
+        if grid.shape[1] != len(QUANTILE_GRID):  # pragma: no cover
+            raise AdapterError(
+                f"expected {len(QUANTILE_GRID)} quantile columns, got {grid.shape[1]}"
+            )
+
+        # Select the Arena's levels out of the model's own grid. Every level
+        # the Arena stores is on this grid by construction -- see the comment
+        # on config.QUANTILE_LEVELS -- so nothing is interpolated.
+        cols = []
+        for level in config.QUANTILE_LEVELS:
+            matches = [i for i, g in enumerate(QUANTILE_GRID) if abs(g - level) < 1e-9]
+            if not matches:
+                raise AdapterError(
+                    f"level {level} is not on TimesFM's native grid {QUANTILE_GRID}"
+                )
+            cols.append(matches[0])
+        quantiles = grid[:, cols]
+
+        return ForecastResult(
+            quantiles=quantiles,
+            levels=config.QUANTILE_LEVELS,
+            horizon=horizon,
+            context_len=len(ctx),
+            inference_version=self.inference_version(),
+            seed=int(seed),
+            n_samples=int(n_samples),
+            paths=None,
+        )

src/config.py

@@ -0,0 +1,196 @@
+"""Configuration for the Forecast Arena.
+
+Everything that names an external resource -- a repo, a model, an asset -- is
+declared here, so that changing where the Arena reads or writes is one edit in
+one file rather than a search across the app.
+
+The store is the *organisation's* dataset, not the user account's. That is
+where the validated price cache and the signal conventions already live, and
+it is what `bit-backtest-lab` reads and writes. See docs/DECISIONS.md.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+# --------------------------------------------------------------------------
+# Repos
+# --------------------------------------------------------------------------
+
+ORG = "The-Bit-Trading-Company"
+USER = "Bit-Trading-Company"
+
+# The signal store. `BIT_STORE_REPO` overrides it for tests and local runs.
+STORE_REPO = os.environ.get("BIT_STORE_REPO", f"{ORG}/bit-signal-store")
+STORE_REPO_TYPE = "dataset"
+
+SPACE_REPO = f"{USER}/bit-forecast-arena"
+
+# Bumped when a change to *this* app alters forecast values. It travels into
+# every archived row through `inference_version()`, so a stored forecast can
+# always be traced to the code that produced it.
+INFERENCE_VERSION = "arena-1"
+
+
+# --------------------------------------------------------------------------
+# Store layout
+# --------------------------------------------------------------------------
+
+# Everything the Arena writes lives under `arena/`.
+#
+# The build spec named `signals/{model_slug}/...` for the forecast archive, but
+# that tree is already occupied. `bit-backtest-lab` writes per-bar, horizon-1
+# signals there -- columns `ts,q10,q50,q90,context_len,inference_version` -- and
+# four of its model slugs (`chronos-bolt-{tiny,mini,small,base}`) are slugs the
+# Arena also uses. Writing frozen multi-step forecasts to the same paths would
+# have merged two incompatible schemas into one file and destroyed signals that
+# cost real GPU time to produce.
+#
+# So the archive is namespaced instead. Same layout, same conventions, one
+# level down. See docs/DECISIONS.md.
+def signals_path(model_slug: str, asset: str, timeframe: str, year: int) -> str:
+    return f"arena/forecasts/{model_slug}/{asset}/{timeframe}/{year}.parquet"
+
+
+def trackrecord_path(model_slug: str, asset: str, timeframe: str) -> str:
+    return f"arena/trackrecord/{model_slug}/{asset}/{timeframe}.parquet"
+
+
+def prices_path(asset: str, timeframe: str, year: int) -> str:
+    return f"prices/{asset}/{timeframe}/{year}.parquet"
+
+
+STANDINGS_PATH = "arena/standings.parquet"
+REGISTRY_PATH = "arena/registry.json"
+
+
+# --------------------------------------------------------------------------
+# Assets and timeframes
+# --------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class Asset:
+    slug: str        # store path segment, matches the existing price cache
+    display: str
+    asset_class: str  # "crypto" | "equity"
+
+
+ASSETS: dict[str, Asset] = {
+    a.slug: a
+    for a in [
+        Asset("BTC-USD", "BTC/USD", "crypto"),
+        Asset("ETH-USD", "ETH/USD", "crypto"),
+        Asset("SOL-USD", "SOL/USD", "crypto"),
+        Asset("SPY", "SPY", "equity"),
+        Asset("NVDA", "NVDA", "equity"),
+        Asset("QQQ", "QQQ", "equity"),
+    ]
+}
+
+# The seed/backfill scope named in the build spec.
+SEED_ASSETS = ("BTC-USD", "ETH-USD", "SOL-USD", "SPY", "NVDA")
+
+
+@dataclass(frozen=True)
+class Timeframe:
+    slug: str
+    display: str
+    minutes: int
+
+
+TIMEFRAMES: dict[str, Timeframe] = {
+    t.slug: t
+    for t in [
+        Timeframe("1h", "1 hour", 60),
+        Timeframe("1d", "1 day", 1440),
+    ]
+}
+
+SEED_TIMEFRAMES = ("1h", "1d")
+
+# Default forecast horizons offered in the UI, per timeframe.
+DEFAULT_HORIZON = {"1h": 24, "1d": 30}
+MAX_HORIZON = {"1h": 168, "1d": 90}
+
+
+# --------------------------------------------------------------------------
+# Sampling and latency
+# --------------------------------------------------------------------------
+
+# Quantile levels stored for every forecast.
+#
+# These are chosen so that *every* family emits them natively. TimesFM returns
+# a fixed 0.1-step grid, so 0.25/0.75 would have had to be interpolated for it
+# while Chronos and Kronos produced theirs directly -- three models' bands
+# would then not have been the same kind of number. Snapping to 0.2/0.8 keeps
+# every stored quantile the model's own output.
+#
+# The pair either side of the median gives a second nominal band (60%) to
+# check coverage against, which is what stops a model tuning itself to look
+# calibrated at exactly one width.
+QUANTILE_LEVELS = (0.1, 0.2, 0.5, 0.8, 0.9)
+
+# How many bars of history a forecast actually conditions on.
+#
+# This is capped *below* several models' `max_context` on purpose. Kronos-mini
+# will attend over 2048 bars and TimesFM over far more, but the cost is roughly
+# linear in context and the accuracy gain past a few hundred bars is small: at
+# 2048 bars Kronos-mini took 36.8s for a 24-step forecast, and at 512 it takes
+# a fraction of that for a materially similar answer. The design says "Fetching
+# 512 candles", and 512 is what the app fetches.
+#
+# A model whose `max_context` is *smaller* than this still gets trimmed to its
+# own limit by `ForecastAdapter._trim`.
+DEFAULT_CONTEXT_BARS = 512
+
+DEFAULT_N_SAMPLES = 32
+MAX_N_SAMPLES = 128
+
+# How many sampled paths are ever sent to the browser as "ghosts". Sending all
+# of them is a payload problem, not an information gain.
+GHOST_PATHS = 12
+
+# CPU-tier budget on `cpu-basic`, in seconds. A model that misses it is demoted
+# to GPU tier in the registry rather than left to time out in front of a user.
+CPU_BUDGET_COLD_S = 20.0
+CPU_BUDGET_WARM_S = 8.0
+
+# Per-session forecast cap for anonymous visitors.
+ANON_SESSION_CAP = 12
+
+
+# --------------------------------------------------------------------------
+# Calibration grading
+# --------------------------------------------------------------------------
+
+# A grade is assigned on the absolute gap between empirical coverage of the
+# 80% band (q10..q90) and its nominal 0.80. The thresholds are deliberately
+# wide: with ~60 resolved forecasts the standard error on a coverage estimate
+# is around 5 points, so anything tighter would be grading noise.
+#
+# `MIN_RESOLVED_FOR_GRADE` is the point below which no grade is shown at all --
+# the UI renders the count instead. Refusing to grade is more honest than
+# grading 3 observations.
+# (low level, high level, nominal coverage) for each band the resolver scores.
+BANDS = ((0.1, 0.9, 0.80), (0.2, 0.8, 0.60))
+NOMINAL_COVERAGE = 0.80          # the band the headline grade is computed on
+MIN_RESOLVED_FOR_GRADE = 20
+
+GRADE_THRESHOLDS = (
+    ("A", 0.05),   # within 5 points of nominal
+    ("B", 0.10),
+    ("C", 0.20),
+    ("D", 1.00),   # anything worse
+)
+
+
+@dataclass(frozen=True)
+class Caps:
+    """Guardrails on user-funded work."""
+
+    smoke_test_steps: int = 100
+    max_enrollments_per_session: int = 3
+
+
+CAPS = Caps()

src/prices.py

@@ -0,0 +1,171 @@
+"""Price refresh. Batch path only -- never called while rendering a page.
+
+The Arena reads prices from the shared store and writes new bars back into the
+same tree the rest of the estate uses, so a refresh here also benefits the
+Backtest Lab. Provider order is crypto via ccxt, equities via yfinance falling
+back to Stooq, which is the convention the store was built on.
+
+Two properties matter more than throughput:
+
+**Only closed bars are stored.** A bar for the period currently in progress
+will change before it closes, and a forecast issued against it would be
+conditioning on a number that later moves -- a subtle lookahead that no
+timestamp check would catch.
+
+**A partial refresh is still a valid store.** Bars are appended per year file
+and deduplicated on timestamp, so a provider dying halfway leaves a shorter
+history rather than a corrupt one.
+"""
+
+from __future__ import annotations
+
+import logging
+
+import pandas as pd
+
+from . import config
+from .store import ArenaStore, now_utc
+
+log = logging.getLogger("arena.prices")
+
+PRICE_COLUMNS = ["ts", "open", "high", "low", "close", "volume"]
+
+# ccxt symbols for the crypto assets, and Stooq/yfinance symbols for equities.
+CCXT_SYMBOLS = {"BTC-USD": "BTC/USDT", "ETH-USD": "ETH/USDT", "SOL-USD": "SOL/USDT"}
+CCXT_TIMEFRAMES = {"1h": "1h", "1d": "1d"}
+STOOQ_SYMBOLS = {"SPY": "spy.us", "NVDA": "nvda.us", "QQQ": "qqq.us"}
+
+
+class ProviderError(RuntimeError):
+    pass
+
+
+def refresh(store: ArenaStore, asset: str, timeframe: str,
+            lookback_days: int = 30) -> int:
+    """Fetch recent bars and merge them into the store. Returns bars added."""
+    spec = config.ASSETS.get(asset)
+    if spec is None:
+        raise ProviderError(f"unknown asset {asset!r}")
+
+    existing = store.get_prices(asset, timeframe)
+    since = None
+    if len(existing):
+        since = pd.to_datetime(existing["ts"], utc=True).max()
+
+    if spec.asset_class == "crypto":
+        fresh = _fetch_ccxt(asset, timeframe, since, lookback_days)
+    else:
+        try:
+            fresh = _fetch_yfinance(asset, timeframe, since, lookback_days)
+        except Exception as e:
+            log.info("yfinance failed for %s (%s); falling back to Stooq", asset, e)
+            fresh = _fetch_stooq(asset, timeframe)
+
+    if fresh is None or not len(fresh):
+        return 0
+
+    fresh = _drop_open_bar(fresh, timeframe)
+    if since is not None:
+        fresh = fresh[pd.to_datetime(fresh["ts"], utc=True) > since]
+    if not len(fresh):
+        return 0
+
+    added = 0
+    combined = pd.concat([existing, fresh], ignore_index=True) if len(existing) else fresh
+    combined["ts"] = pd.to_datetime(combined["ts"], utc=True)
+    combined = (combined.drop_duplicates(subset=["ts"], keep="first")
+                .sort_values("ts").reset_index(drop=True))
+
+    for year, chunk in combined.groupby(combined["ts"].dt.year):
+        path = config.prices_path(asset, timeframe, int(year))
+        before = store.read_parquet(path)
+        if before is not None and len(before) == len(chunk):
+            continue
+        store.write_parquet(path, chunk[PRICE_COLUMNS])
+        added += len(chunk) - (len(before) if before is not None else 0)
+    return max(0, added)
+
+
+def _drop_open_bar(frame: pd.DataFrame, timeframe: str) -> pd.DataFrame:
+    """Discard the bar for the period still in progress.
+
+    An in-progress bar's close is not its close. Storing it would let a
+    forecast condition on a value that changes afterwards.
+    """
+    if not len(frame):
+        return frame
+    minutes = config.TIMEFRAMES[timeframe].minutes
+    cutoff = now_utc().floor(f"{minutes}min")
+    ts = pd.to_datetime(frame["ts"], utc=True)
+    return frame[ts < cutoff].reset_index(drop=True)
+
+
+def _fetch_ccxt(asset: str, timeframe: str, since, lookback_days: int) -> pd.DataFrame:
+    import ccxt
+
+    symbol = CCXT_SYMBOLS.get(asset)
+    if not symbol:
+        raise ProviderError(f"no ccxt symbol for {asset}")
+    tf = CCXT_TIMEFRAMES.get(timeframe)
+    if not tf:
+        raise ProviderError(f"ccxt cannot serve {timeframe}")
+
+    exchange = ccxt.binance({"enableRateLimit": True})
+    start = since if since is not None else now_utc() - pd.Timedelta(days=lookback_days)
+    ms = int(pd.Timestamp(start).timestamp() * 1000)
+
+    rows = []
+    for _ in range(20):          # bounded: 20 pages of 1000 bars is plenty
+        batch = exchange.fetch_ohlcv(symbol, tf, since=ms, limit=1000)
+        if not batch:
+            break
+        rows.extend(batch)
+        ms = batch[-1][0] + 1
+        if len(batch) < 1000:
+            break
+
+    if not rows:
+        return pd.DataFrame(columns=PRICE_COLUMNS)
+    frame = pd.DataFrame(rows, columns=["ts", "open", "high", "low", "close", "volume"])
+    frame["ts"] = pd.to_datetime(frame["ts"], unit="ms", utc=True)
+    return frame[PRICE_COLUMNS]
+
+
+def _fetch_yfinance(asset: str, timeframe: str, since, lookback_days: int) -> pd.DataFrame:
+    import yfinance as yf
+
+    interval = {"1h": "1h", "1d": "1d"}[timeframe]
+    period = f"{max(lookback_days, 7)}d" if timeframe == "1h" else "2y"
+    raw = yf.Ticker(asset).history(period=period, interval=interval, auto_adjust=False)
+    if raw is None or not len(raw):
+        raise ProviderError("yfinance returned no rows")
+
+    frame = raw.reset_index()
+    stamp = next((c for c in ("Datetime", "Date", "index") if c in frame.columns), None)
+    if stamp is None:
+        raise ProviderError(f"no timestamp column in {list(frame.columns)}")
+    frame = frame.rename(columns={stamp: "ts", "Open": "open", "High": "high",
+                                  "Low": "low", "Close": "close", "Volume": "volume"})
+    frame["ts"] = pd.to_datetime(frame["ts"], utc=True)
+    return frame[PRICE_COLUMNS]
+
+
+def _fetch_stooq(asset: str, timeframe: str) -> pd.DataFrame:
+    import io
+
+    import requests
+
+    if timeframe != "1d":
+        raise ProviderError("Stooq serves daily bars only")
+    symbol = STOOQ_SYMBOLS.get(asset)
+    if not symbol:
+        raise ProviderError(f"no Stooq symbol for {asset}")
+
+    response = requests.get(f"https://stooq.com/q/d/l/?s={symbol}&i=d", timeout=30)
+    response.raise_for_status()
+    frame = pd.read_csv(io.StringIO(response.text))
+    frame = frame.rename(columns={c: c.lower() for c in frame.columns})
+    if "date" not in frame.columns:
+        raise ProviderError("Stooq returned no date column")
+    frame["ts"] = pd.to_datetime(frame["date"], utc=True)
+    return frame[PRICE_COLUMNS]

src/runtime.py

@@ -0,0 +1,308 @@
+"""Running a forecast, and enrolling a model.
+
+This is the layer the UI calls. It owns three things the UI must not:
+
+**Adapter caching.** Loading weights costs seconds; doing it per request would
+put every model outside its latency budget. Adapters are cached per
+(family, model id, revision) and reused.
+
+**The issue moment.** `issued_ts` is the timestamp of the last bar in the
+validated price cache, never the wall clock. That is what makes a live forecast
+and a backfilled one structurally the same operation -- the backfill just
+supplies an earlier cut. There is no code path where a forecast can see a bar
+it should not have.
+
+**Enrollment.** Adding a model is: validate the id, check the family is on the
+allow-list, pin the revision to an immutable sha, run a smoke test, write the
+registry entry. No user-supplied code is ever imported or executed, and an
+unsupported family is rejected with a message that says so.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass, field
+
+import pandas as pd
+
+from . import config, trackrecord
+from .adapters import (ALLOWED_ADAPTER_FAMILIES, AdapterError, ForecastAdapter,
+                       ForecastResult, ModelNotAllowed, family_for,
+                       get_adapter, validate_model_id)
+from .adapters import model_slug as slug_for
+from .store import ArenaStore, now_utc
+
+log = logging.getLogger("arena.runtime")
+
+
+class ForecastUnavailable(RuntimeError):
+    """A forecast could not be produced. Carries a UI-renderable reason."""
+
+    def __init__(self, message: str, kind: str = "load_failure"):
+        super().__init__(message)
+        self.kind = kind
+
+
+# --------------------------------------------------------------------------
+# Adapter cache
+# --------------------------------------------------------------------------
+
+_ADAPTERS: dict[tuple, ForecastAdapter] = {}
+
+
+def adapter_for(family: str, model_id: str, revision: str | None = None,
+                **kwargs) -> ForecastAdapter:
+    """A loaded adapter, cached. Raises `ForecastUnavailable` on load failure."""
+    key = (family, model_id, revision or "pinned", tuple(sorted(kwargs.items())))
+    cached = _ADAPTERS.get(key)
+    if cached is not None:
+        return cached
+    try:
+        adapter = get_adapter(family, model_id, revision=revision, **kwargs)
+        adapter.load()
+    except ModelNotAllowed:
+        raise
+    except Exception as e:
+        # Weights that will not download or will not fit are the single most
+        # likely runtime failure, and the UI has a designed state for it.
+        raise ForecastUnavailable(
+            f"{model_id} could not be loaded: {e}", kind="load_failure") from e
+    _ADAPTERS[key] = adapter
+    return adapter
+
+
+def clear_adapter_cache() -> None:
+    _ADAPTERS.clear()
+
+
+# --------------------------------------------------------------------------
+# Forecasting
+# --------------------------------------------------------------------------
+
+
+@dataclass
+class ForecastRun:
+    """Everything the UI needs about one issued forecast."""
+
+    model_slug: str
+    model_id: str
+    family: str
+    asset: str
+    timeframe: str
+    horizon: int
+    issued_ts: pd.Timestamp
+    target_ts: pd.DatetimeIndex
+    result: ForecastResult
+    context: pd.DataFrame
+    forecast_id: str = ""
+    archived_rows: int = 0
+    elapsed_s: float = 0.0
+    capabilities: dict = field(default_factory=dict)
+
+
+def future_timestamps(context: pd.DataFrame, horizon: int) -> pd.DatetimeIndex:
+    """Continue the context's own cadence forward by `horizon` bars."""
+    ts = pd.to_datetime(context["ts"], utc=True)
+    deltas = ts.diff().dropna()
+    if not len(deltas):
+        raise AdapterError("cannot infer cadence from a single bar")
+    modal = deltas.mode()
+    step = modal.iloc[0] if len(modal) else deltas.median()
+    last = ts.iloc[-1]
+    return pd.DatetimeIndex([last + step * (i + 1) for i in range(horizon)])
+
+
+def load_context(store: ArenaStore, asset: str, timeframe: str,
+                 as_of=None, context_len: int = 512) -> pd.DataFrame:
+    """The most recent validated bars at or before `as_of`.
+
+    Slicing on `as_of` here rather than in the caller is what makes the
+    no-lookahead guarantee structural: every context the app ever builds goes
+    through this function, and it cannot return a bar past the cut.
+    """
+    prices = store.get_prices(asset, timeframe)
+    if not len(prices):
+        raise ForecastUnavailable(
+            f"no price history cached for {asset} {timeframe}", kind="no_data")
+    if as_of is not None:
+        cut = pd.Timestamp(as_of)
+        cut = cut.tz_localize("UTC") if cut.tzinfo is None else cut.tz_convert("UTC")
+        prices = prices[prices["ts"] <= cut]
+    if len(prices) < 64:
+        raise ForecastUnavailable(
+            f"only {len(prices)} bars available for {asset} {timeframe}",
+            kind="no_data")
+    return prices.iloc[-context_len:].reset_index(drop=True)
+
+
+def run_forecast(store: ArenaStore, model_slug: str, asset: str, timeframe: str,
+                 horizon: int | None = None,
+                 n_samples: int = config.DEFAULT_N_SAMPLES,
+                 seed: int = 0, as_of=None, registry: dict | None = None,
+                 archive: bool = True, backfilled: bool = False) -> ForecastRun:
+    """Issue one forecast, archive it, and return everything needed to draw it."""
+    registry = registry if registry is not None else store.get_registry()
+    entry = registry.get("models", {}).get(model_slug)
+    if entry is None:
+        raise ForecastUnavailable(
+            f"{model_slug} is not enrolled in the Arena", kind="not_enrolled")
+
+    horizon = int(horizon or config.DEFAULT_HORIZON.get(timeframe, 24))
+    max_h = config.MAX_HORIZON.get(timeframe, 168)
+    if not 1 <= horizon <= max_h:
+        raise ForecastUnavailable(
+            f"horizon must be between 1 and {max_h} for {timeframe}",
+            kind="bad_request")
+
+    adapter = adapter_for(entry["family"], entry["model_id"],
+                          revision=entry.get("revision"))
+    caps = adapter.capabilities()
+
+    # The smaller of what the model can take and what the Arena spends. See
+    # config.DEFAULT_CONTEXT_BARS for why the ceiling is not the model's own.
+    context = load_context(store, asset, timeframe, as_of=as_of,
+                           context_len=min(caps.max_context,
+                                           config.DEFAULT_CONTEXT_BARS))
+    issued_ts = pd.to_datetime(context["ts"], utc=True).iloc[-1]
+    targets = future_timestamps(context, horizon)
+
+    started = time.time()
+    result = adapter.predict(context, horizon=horizon, n_samples=n_samples,
+                             seed=int(seed), issued_ts=issued_ts)
+    elapsed = time.time() - started
+
+    run = ForecastRun(
+        model_slug=model_slug, model_id=entry["model_id"], family=entry["family"],
+        asset=asset, timeframe=timeframe, horizon=horizon,
+        issued_ts=issued_ts, target_ts=targets, result=result, context=context,
+        elapsed_s=elapsed, capabilities=caps.as_dict(),
+    )
+
+    if archive:
+        fid, written = trackrecord.archive(
+            store, result, model_slug, asset, timeframe, issued_ts, targets,
+            backfilled=backfilled)
+        run.forecast_id, run.archived_rows = fid, written
+
+    return run
+
+
+# --------------------------------------------------------------------------
+# Enrollment
+# --------------------------------------------------------------------------
+
+
+@dataclass
+class Enrollment:
+    ok: bool
+    model_slug: str = ""
+    message: str = ""
+    entry: dict | None = None
+    already: bool = False
+
+
+def enroll(store: ArenaStore, family: str, model_id: str,
+           enrolled_by: str = "anonymous", registry: dict | None = None,
+           smoke_steps: int = config.CAPS.smoke_test_steps) -> Enrollment:
+    """Validate, pin, smoke-test and register a model.
+
+    Enrolling an (id, revision) that is already registered is a no-op rather
+    than an error: the flow is idempotent so that a double-submitted form or a
+    retried job cannot fork the registry.
+    """
+    try:
+        model_id = validate_model_id(model_id)
+    except AdapterError as e:
+        return Enrollment(ok=False, message=str(e))
+
+    fam = (family or "").strip().lower()
+    if fam not in ALLOWED_ADAPTER_FAMILIES:
+        return Enrollment(ok=False, message=(
+            f"'{family}' is not a supported adapter family. The Arena runs "
+            f"models only through vetted loaders, so a model outside "
+            f"{', '.join(ALLOWED_ADAPTER_FAMILIES)} cannot be enrolled."))
+
+    known = family_for(model_id)
+    if known is not None and known != fam:
+        return Enrollment(ok=False, message=(
+            f"{model_id} is a {known} model; enrolling it as {fam} would load "
+            f"it with the wrong loader."))
+
+    registry = registry if registry is not None else store.get_registry()
+    slug = slug_for(model_id)
+
+    try:
+        adapter = get_adapter(fam, model_id)
+        revision = adapter.resolve_revision()
+    except ModelNotAllowed as e:
+        return Enrollment(ok=False, message=str(e))
+    except Exception as e:
+        return Enrollment(ok=False, message=(
+            f"could not reach {model_id} on the Hub: {e}"))
+
+    existing = registry.get("models", {}).get(slug)
+    if existing and existing.get("revision") == revision:
+        return Enrollment(ok=True, model_slug=slug, already=True,
+                          entry=existing,
+                          message=f"{model_id} is already enrolled at this revision.")
+
+    try:
+        smoke = _smoke_test(adapter, steps=smoke_steps)
+    except Exception as e:
+        return Enrollment(ok=False, message=f"{model_id} failed its smoke test: {e}")
+
+    caps = adapter.capabilities()
+    entry = {
+        "model_slug": slug,
+        "model_id": model_id,
+        "family": fam,
+        "revision": revision,
+        "display": model_id.split("/", 1)[1],
+        "capabilities": caps.as_dict(),
+        "components": adapter.component_versions(),
+        "inference_version": adapter.inference_version(),
+        "enrolled_by": str(enrolled_by or "anonymous")[:64],
+        "enrolled_ts": now_utc().isoformat(),
+        "smoke_test": smoke,
+    }
+    registry.setdefault("models", {})[slug] = entry
+    store.put_registry(registry)
+    return Enrollment(ok=True, model_slug=slug, entry=entry,
+                      message=f"{model_id} enrolled as '{slug}'.")
+
+
+def _smoke_test(adapter: ForecastAdapter, steps: int) -> dict:
+    """Forecast a synthetic series and check the output is usable.
+
+    Synthetic rather than real prices so enrollment works before the cache has
+    any coverage for a new asset, and so the test is identical every time.
+    """
+    import numpy as np
+
+    n = max(128, steps)
+    rng = np.random.default_rng(0)
+    close = 100.0 * np.exp(np.cumsum(rng.normal(0, 0.01, n)))
+    frame = pd.DataFrame({
+        "ts": pd.date_range("2025-01-01", periods=n, freq="1h", tz="UTC"),
+        "open": close, "high": close * 1.001, "low": close * 0.999,
+        "close": close, "volume": 1000.0,
+    })
+
+    horizon = min(16, max(1, steps // 8))
+    started = time.time()
+    result = adapter.predict(frame, horizon=horizon, n_samples=8, seed=0)
+    elapsed = time.time() - started
+
+    lo, hi = result.band()
+    if not (lo <= hi).all():
+        raise AdapterError("smoke test produced a crossed band")
+
+    return {
+        "ok": True,
+        "steps": int(n),
+        "horizon": int(horizon),
+        "elapsed_s": round(elapsed, 3),
+        "emits_paths": bool(result.paths is not None),
+        "ran_ts": now_utc().isoformat(),
+    }

src/store.py

@@ -0,0 +1,400 @@
+"""Read and write access to the signal store.
+
+The store is a Hugging Face dataset repo laid out as parquet under stable
+paths. `local_root` is a working mirror: reads fall back to the Hub when a file
+is absent locally, writes stage into the mirror, and `flush()` pushes them as
+one commit.
+
+The rule that shapes this whole module is **frozen at issue**. An archived
+forecast row is written once and never rewritten. Resolution appends to a
+different tree; it does not revise the archive. So `append_forecast` is
+first-write-wins on its dedup key rather than last-write-wins, which is the
+opposite of what a cache would do and is the entire point: a track record whose
+history can be edited after the fact is not evidence of anything.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import os
+import threading
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+from . import config
+
+log = logging.getLogger("arena.store")
+
+
+class StoreError(RuntimeError):
+    pass
+
+
+# --------------------------------------------------------------------------
+# Schemas
+# --------------------------------------------------------------------------
+
+# One row per (forecast, step). Flat rather than array-valued because every
+# consumer -- the resolver, the standings, the chart -- wants steps as rows.
+FORECAST_COLUMNS = [
+    "forecast_id", "model_slug", "asset", "timeframe",
+    "issued_ts", "target_ts", "step", "horizon_bars",
+    "seed", "n_samples", "context_len", "inference_version",
+    "dispersion", "path_ref", "backfilled",
+] + [f"q{int(round(q * 100)):02d}" for q in config.QUANTILE_LEVELS]
+
+QUANTILE_COLUMNS = [f"q{int(round(q * 100)):02d}" for q in config.QUANTILE_LEVELS]
+
+# Resolved outcomes. Append-only, never revised.
+TRACKRECORD_COLUMNS = [
+    "forecast_id", "model_slug", "asset", "timeframe",
+    "issued_ts", "target_ts", "step", "horizon_bars",
+    "realized_close", "q10", "q50", "q90", "q20", "q80",
+    "inside_80", "inside_60",
+    "abs_error", "pct_error", "resolved_ts", "backfilled",
+]
+
+STANDINGS_COLUMNS = [
+    "model_slug", "asset_class", "resolved_count", "forecast_count",
+    "coverage_80", "coverage_60", "median_abs_pct_error",
+    "calibration_gap", "grade", "updated_ts",
+]
+
+
+def forecast_id(model_slug: str, asset: str, timeframe: str,
+                issued_ts, seed: int) -> str:
+    """The dedup key, as a short stable hash.
+
+    Deliberately *excludes* `inference_version`. Re-running the same request
+    after a model upgrade must not append a second row: the first answer is the
+    one that was issued, and the archive records what was issued. The version
+    that produced it is kept as a column so the row is still traceable.
+    """
+    payload = "|".join([
+        str(model_slug), str(asset), str(timeframe),
+        _iso(issued_ts), str(int(seed)),
+    ])
+    return hashlib.sha256(payload.encode()).hexdigest()[:16]
+
+
+def _utc(ts) -> pd.Timestamp:
+    t = pd.Timestamp(ts)
+    return t.tz_localize("UTC") if t.tzinfo is None else t.tz_convert("UTC")
+
+
+def _iso(ts) -> str:
+    return _utc(ts).isoformat()
+
+
+def now_utc() -> pd.Timestamp:
+    """A tz-aware "now".
+
+    `pd.Timestamp.utcnow()` returns tz-aware on current pandas and tz-naive on
+    older ones, so localising it unconditionally raises. Every "now" in the app
+    comes through here so that difference is handled once.
+    """
+    return _utc(pd.Timestamp.utcnow())
+
+
+# --------------------------------------------------------------------------
+# Store
+# --------------------------------------------------------------------------
+
+
+class ArenaStore:
+    """Parquet access to the Arena's trees in the signal store.
+
+    Set `offline=True` (or leave `repo_id=None`) for a purely local store --
+    what the tests and the backfill script use before they have a token.
+    """
+
+    def __init__(self, repo_id: str | None = config.STORE_REPO,
+                 local_root: str | os.PathLike | None = None,
+                 token: str | None = None, offline: bool = False,
+                 revision: str = "main") -> None:
+        self.repo_id = repo_id
+        self.revision = revision
+        self.token = token or os.environ.get("HF_WRITE_TOKEN") or os.environ.get("HF_TOKEN")
+        self.offline = offline or repo_id is None
+        self.local_root = Path(local_root
+                               or os.environ.get("BIT_STORE_CACHE", ".cache/store"))
+        self.local_root.mkdir(parents=True, exist_ok=True)
+        self._pending: set[str] = set()
+        self._price_cache: dict[tuple[str, str], pd.DataFrame] = {}
+        self._lock = threading.RLock()
+
+    # -- low-level --------------------------------------------------------
+
+    def _local(self, repo_path: str) -> Path:
+        return self.local_root / repo_path
+
+    def _fetch(self, repo_path: str) -> Path | None:
+        local = self._local(repo_path)
+        if local.exists():
+            return local
+        if self.offline:
+            return None
+        try:
+            from huggingface_hub import hf_hub_download
+
+            return Path(hf_hub_download(
+                repo_id=self.repo_id, repo_type=config.STORE_REPO_TYPE,
+                filename=repo_path, revision=self.revision, token=self.token,
+            ))
+        except Exception:
+            # Absent from the Hub is a normal "no data" answer, not a fault.
+            return None
+
+    def read_parquet(self, repo_path: str) -> pd.DataFrame | None:
+        p = self._fetch(repo_path)
+        if p is None:
+            return None
+        try:
+            return pd.read_parquet(p)
+        except Exception as e:  # pragma: no cover
+            log.warning("unreadable parquet %s: %s", repo_path, e)
+            return None
+
+    def read_json(self, repo_path: str) -> dict | None:
+        p = self._fetch(repo_path)
+        if p is None:
+            return None
+        try:
+            return json.loads(Path(p).read_text())
+        except Exception as e:  # pragma: no cover
+            log.warning("unreadable json %s: %s", repo_path, e)
+            return None
+
+    def _stage(self, repo_path: str, write) -> None:
+        local = self._local(repo_path)
+        local.parent.mkdir(parents=True, exist_ok=True)
+        write(local)
+        with self._lock:
+            self._pending.add(repo_path)
+
+    def write_parquet(self, repo_path: str, df: pd.DataFrame) -> None:
+        self._stage(repo_path, lambda p: df.to_parquet(p, index=False))
+        if repo_path.startswith("prices/"):
+            self.invalidate_prices()
+
+    def write_json(self, repo_path: str, payload: dict) -> None:
+        self._stage(repo_path,
+                    lambda p: Path(p).write_text(json.dumps(payload, indent=2, sort_keys=True)))
+
+    @property
+    def pending(self) -> list[str]:
+        with self._lock:
+            return sorted(self._pending)
+
+    def flush(self, message: str = "arena: update") -> int:
+        """Push everything staged as one commit. Returns the file count."""
+        with self._lock:
+            paths = sorted(self._pending)
+            if not paths or self.offline:
+                self._pending.clear()
+                return 0
+        from huggingface_hub import CommitOperationAdd, HfApi
+
+        ops = [CommitOperationAdd(path_in_repo=p, path_or_fileobj=str(self._local(p)))
+               for p in paths]
+        HfApi(token=self.token).create_commit(
+            repo_id=self.repo_id, repo_type=config.STORE_REPO_TYPE,
+            operations=ops, commit_message=message, revision=self.revision,
+        )
+        with self._lock:
+            self._pending.clear()
+        return len(ops)
+
+    # -- prices -----------------------------------------------------------
+
+    def get_prices(self, asset: str, timeframe: str,
+                   start=None, end=None) -> pd.DataFrame:
+        """OHLCV slice with a `ts` column, sorted ascending.
+
+        Reads the existing price cache written by the shared pipeline; the
+        Arena never fetches a price in the request path.
+
+        The full series is memoised per (asset, timeframe). Without it the
+        backfill re-read and re-concatenated ~9,600 rows of parquet for every
+        one of its thousands of as-of forecasts, which dominated the run;
+        `invalidate_prices` drops the memo after a refresh writes new bars.
+        """
+        key = (asset, timeframe)
+        cached = self._price_cache.get(key)
+        if cached is not None:
+            return self._slice(cached, start, end)
+        full = self._read_prices(asset, timeframe)
+        self._price_cache[key] = full
+        return self._slice(full, start, end)
+
+    @staticmethod
+    def _slice(frame: pd.DataFrame, start, end) -> pd.DataFrame:
+        if start is None and end is None:
+            return frame
+        out = frame
+        if start is not None:
+            out = out[out["ts"] >= _utc(start)]
+        if end is not None:
+            out = out[out["ts"] <= _utc(end)]
+        return out.reset_index(drop=True)
+
+    def invalidate_prices(self, asset: str | None = None,
+                          timeframe: str | None = None) -> None:
+        if asset is None:
+            self._price_cache.clear()
+            return
+        self._price_cache.pop((asset, timeframe), None)
+
+    def _read_prices(self, asset: str, timeframe: str) -> pd.DataFrame:
+        start = end = None
+        years = _years_between(start, end)
+        frames = []
+        for y in years:
+            df = self.read_parquet(config.prices_path(asset, timeframe, y))
+            if df is not None and len(df):
+                frames.append(df)
+        if not frames:
+            return pd.DataFrame(columns=["ts", "open", "high", "low", "close", "volume"])
+        out = pd.concat(frames, ignore_index=True)
+        out["ts"] = pd.to_datetime(out["ts"], utc=True)
+        return out.drop_duplicates(subset=["ts"]).sort_values("ts").reset_index(drop=True)
+
+    # -- forecasts (the archive) ------------------------------------------
+
+    def get_forecasts(self, model_slug: str, asset: str, timeframe: str,
+                      years: list[int] | None = None) -> pd.DataFrame:
+        years = years or _years_between(None, None)
+        frames = []
+        for y in years:
+            df = self.read_parquet(config.signals_path(model_slug, asset, timeframe, y))
+            if df is not None and len(df):
+                frames.append(df)
+        if not frames:
+            return pd.DataFrame(columns=FORECAST_COLUMNS)
+        out = pd.concat(frames, ignore_index=True)
+        out["issued_ts"] = pd.to_datetime(out["issued_ts"], utc=True)
+        out["target_ts"] = pd.to_datetime(out["target_ts"], utc=True)
+        return out
+
+    def append_forecast(self, rows: pd.DataFrame) -> int:
+        """Archive one forecast. Returns rows actually written (0 if a dup).
+
+        First write wins. A forecast already present under this id is left
+        exactly as it was -- see the module docstring.
+        """
+        if rows is None or not len(rows):
+            return 0
+        missing = [c for c in FORECAST_COLUMNS if c not in rows.columns]
+        if missing:
+            raise StoreError(f"forecast rows missing columns {missing}")
+
+        fid = str(rows["forecast_id"].iloc[0])
+        if rows["forecast_id"].nunique() != 1:
+            raise StoreError("append_forecast takes one forecast at a time")
+
+        model_slug = str(rows["model_slug"].iloc[0])
+        asset = str(rows["asset"].iloc[0])
+        tf = str(rows["timeframe"].iloc[0])
+        year = int(_utc(rows["issued_ts"].iloc[0]).year)
+        path = config.signals_path(model_slug, asset, tf, year)
+
+        existing = self.read_parquet(path)
+        if existing is not None and len(existing):
+            if fid in set(existing["forecast_id"].astype(str)):
+                return 0
+            merged = pd.concat([existing, rows[FORECAST_COLUMNS]], ignore_index=True)
+        else:
+            merged = rows[FORECAST_COLUMNS].copy()
+
+        merged = merged.sort_values(["issued_ts", "step"]).reset_index(drop=True)
+        self.write_parquet(path, merged)
+        return len(rows)
+
+    # -- track record -----------------------------------------------------
+
+    def get_trackrecord(self, model_slug: str, asset: str,
+                        timeframe: str) -> pd.DataFrame:
+        df = self.read_parquet(config.trackrecord_path(model_slug, asset, timeframe))
+        if df is None or not len(df):
+            return pd.DataFrame(columns=TRACKRECORD_COLUMNS)
+        df["issued_ts"] = pd.to_datetime(df["issued_ts"], utc=True)
+        df["target_ts"] = pd.to_datetime(df["target_ts"], utc=True)
+        return df
+
+    def append_trackrecord(self, model_slug: str, asset: str, timeframe: str,
+                           rows: pd.DataFrame) -> int:
+        """Append resolved outcomes. Idempotent on (forecast_id, step)."""
+        if rows is None or not len(rows):
+            return 0
+        path = config.trackrecord_path(model_slug, asset, timeframe)
+        existing = self.get_trackrecord(model_slug, asset, timeframe)
+        if len(existing):
+            seen = set(zip(existing["forecast_id"].astype(str),
+                           existing["step"].astype(int)))
+            mask = [(str(f), int(s)) not in seen
+                    for f, s in zip(rows["forecast_id"], rows["step"])]
+            rows = rows[np.asarray(mask)]
+            if not len(rows):
+                return 0
+            merged = pd.concat([existing, rows[TRACKRECORD_COLUMNS]], ignore_index=True)
+        else:
+            merged = rows[TRACKRECORD_COLUMNS].copy()
+        merged = merged.sort_values(["issued_ts", "step"]).reset_index(drop=True)
+        self.write_parquet(path, merged)
+        return len(rows)
+
+    def all_trackrecords(self) -> pd.DataFrame:
+        """Every resolved row in the store, for the standings rebuild.
+
+        Walks the local mirror. The scheduled job syncs the tree first, so this
+        sees the whole store; in the Space it sees whatever has been fetched,
+        which is why standings are *read* there and never rebuilt.
+        """
+        root = self.local_root / "arena" / "trackrecord"
+        if not root.exists():
+            return pd.DataFrame(columns=TRACKRECORD_COLUMNS)
+        frames = []
+        for p in sorted(root.rglob("*.parquet")):
+            try:
+                frames.append(pd.read_parquet(p))
+            except Exception as e:  # pragma: no cover
+                log.warning("skipping unreadable trackrecord %s: %s", p, e)
+        if not frames:
+            return pd.DataFrame(columns=TRACKRECORD_COLUMNS)
+        out = pd.concat(frames, ignore_index=True)
+        out["issued_ts"] = pd.to_datetime(out["issued_ts"], utc=True)
+        out["target_ts"] = pd.to_datetime(out["target_ts"], utc=True)
+        return out
+
+    # -- standings and registry -------------------------------------------
+
+    def get_standings(self) -> pd.DataFrame:
+        df = self.read_parquet(config.STANDINGS_PATH)
+        if df is None:
+            return pd.DataFrame(columns=STANDINGS_COLUMNS)
+        return df
+
+    def put_standings(self, df: pd.DataFrame) -> None:
+        self.write_parquet(config.STANDINGS_PATH, df[STANDINGS_COLUMNS])
+
+    def get_registry(self) -> dict:
+        reg = self.read_json(config.REGISTRY_PATH)
+        if not reg:
+            return {"version": 1, "models": {}}
+        reg.setdefault("models", {})
+        return reg
+
+    def put_registry(self, registry: dict) -> None:
+        self.write_json(config.REGISTRY_PATH, registry)
+
+
+def _years_between(start, end) -> list[int]:
+    """Year partitions to look in. Defaults to a window around now."""
+    now = now_utc()
+    s = _utc(start).year if start is not None else now.year - 3
+    e = _utc(end).year if end is not None else now.year + 1
+    return list(range(int(s), int(e) + 1))

src/trackrecord.py

@@ -0,0 +1,241 @@
+"""Archiving, resolution and standings.
+
+The pipeline is three steps, and the boundary between them is the point.
+
+1. `archive` writes a forecast at the moment it is issued. Those rows are
+   final. Nothing downstream ever rewrites them.
+2. `resolve` looks for archived forecasts whose horizon has now elapsed,
+   compares them against realised prices, and *appends* the outcome to a
+   separate tree.
+3. `build_standings` derives the leaderboard from the resolved outcomes and
+   nothing else, so it is a pure function of the track record and can be
+   regenerated from scratch at any time.
+
+Keeping resolution out of the archive is what makes the record evidence rather
+than marketing. If a bad forecast could be quietly corrected once the outcome
+was known, the calibration numbers would measure nothing at all.
+"""
+
+from __future__ import annotations
+
+import logging
+
+import numpy as np
+import pandas as pd
+
+from . import config
+from .adapters import ForecastResult
+from .store import (FORECAST_COLUMNS, QUANTILE_COLUMNS, STANDINGS_COLUMNS,
+                    TRACKRECORD_COLUMNS, ArenaStore, forecast_id, now_utc)
+
+log = logging.getLogger("arena.trackrecord")
+
+
+def _as_utc(ts) -> pd.Timestamp:
+    """Normalise a caller-supplied "now" to tz-aware UTC."""
+    if ts is None:
+        return now_utc()
+    t = pd.Timestamp(ts)
+    return t.tz_localize("UTC") if t.tzinfo is None else t.tz_convert("UTC")
+
+
+# --------------------------------------------------------------------------
+# Archive
+# --------------------------------------------------------------------------
+
+
+def forecast_rows(result: ForecastResult, model_slug: str, asset: str,
+                  timeframe: str, issued_ts, target_ts,
+                  backfilled: bool = False, path_ref: str | None = None) -> pd.DataFrame:
+    """Turn an adapter result into archive rows -- one per forecast step."""
+    if len(target_ts) != result.horizon:
+        raise ValueError(
+            f"{len(target_ts)} target timestamps for a horizon of {result.horizon}")
+
+    fid = forecast_id(model_slug, asset, timeframe, issued_ts, result.seed)
+    dispersion = result.dispersion()
+
+    data = {
+        "forecast_id": fid,
+        "model_slug": model_slug,
+        "asset": asset,
+        "timeframe": timeframe,
+        "issued_ts": pd.to_datetime([issued_ts] * result.horizon, utc=True),
+        "target_ts": pd.to_datetime(list(target_ts), utc=True),
+        "step": np.arange(1, result.horizon + 1, dtype="int32"),
+        "horizon_bars": np.int32(result.horizon),
+        "seed": np.int64(result.seed),
+        "n_samples": np.int32(result.n_samples),
+        "context_len": np.int32(result.context_len),
+        "inference_version": result.inference_version,
+        "dispersion": dispersion.astype("float64"),
+        # A reference, not the paths themselves: whole sampled paths are far
+        # too heavy to inline into every archive row.
+        "path_ref": path_ref or "",
+        "backfilled": bool(backfilled),
+    }
+    for i, level in enumerate(result.levels):
+        data[f"q{int(round(level * 100)):02d}"] = result.quantiles[:, i]
+
+    return pd.DataFrame(data)[FORECAST_COLUMNS]
+
+
+def archive(store: ArenaStore, result: ForecastResult, model_slug: str,
+            asset: str, timeframe: str, issued_ts, target_ts,
+            backfilled: bool = False) -> tuple[str, int]:
+    """Archive a forecast. Returns (forecast_id, rows written; 0 if a duplicate)."""
+    rows = forecast_rows(result, model_slug, asset, timeframe,
+                         issued_ts, target_ts, backfilled=backfilled)
+    written = store.append_forecast(rows)
+    return str(rows["forecast_id"].iloc[0]), written
+
+
+# --------------------------------------------------------------------------
+# Resolve
+# --------------------------------------------------------------------------
+
+
+def resolve(store: ArenaStore, model_slug: str, asset: str, timeframe: str,
+            now=None) -> pd.DataFrame:
+    """Resolve every archived forecast whose target bar has printed.
+
+    Idempotent: rows already in the track record are skipped, so a re-run adds
+    nothing. It never touches the archive.
+    """
+    now = _as_utc(now)
+
+    forecasts = store.get_forecasts(model_slug, asset, timeframe)
+    if not len(forecasts):
+        return pd.DataFrame(columns=TRACKRECORD_COLUMNS)
+
+    already = store.get_trackrecord(model_slug, asset, timeframe)
+    seen = set(zip(already["forecast_id"].astype(str), already["step"].astype(int))) \
+        if len(already) else set()
+
+    due = forecasts[forecasts["target_ts"] <= now]
+    if len(due):
+        mask = [(str(f), int(s)) not in seen
+                for f, s in zip(due["forecast_id"], due["step"])]
+        due = due[np.asarray(mask)]
+    if not len(due):
+        return pd.DataFrame(columns=TRACKRECORD_COLUMNS)
+
+    prices = store.get_prices(asset, timeframe,
+                              start=due["target_ts"].min(),
+                              end=due["target_ts"].max())
+    if not len(prices):
+        log.info("no prices to resolve %s/%s/%s against", model_slug, asset, timeframe)
+        return pd.DataFrame(columns=TRACKRECORD_COLUMNS)
+
+    realized = prices.set_index("ts")["close"]
+    joined = due.copy()
+    joined["realized_close"] = joined["target_ts"].map(realized)
+    # A target bar that has not printed -- a market holiday, a gap in the cache
+    # -- is left unresolved rather than filled with the nearest neighbour.
+    # Resolving against a price from the wrong bar would be a silent lie.
+    joined = joined[joined["realized_close"].notna()]
+    if not len(joined):
+        return pd.DataFrame(columns=TRACKRECORD_COLUMNS)
+
+    out = pd.DataFrame({
+        "forecast_id": joined["forecast_id"].astype(str),
+        "model_slug": model_slug,
+        "asset": asset,
+        "timeframe": timeframe,
+        "issued_ts": joined["issued_ts"],
+        "target_ts": joined["target_ts"],
+        "step": joined["step"].astype("int32"),
+        "horizon_bars": joined["horizon_bars"].astype("int32"),
+        "realized_close": joined["realized_close"].astype("float64"),
+        "q10": joined["q10"].astype("float64"),
+        "q20": joined["q20"].astype("float64"),
+        "q50": joined["q50"].astype("float64"),
+        "q80": joined["q80"].astype("float64"),
+        "q90": joined["q90"].astype("float64"),
+        "resolved_ts": now,
+        "backfilled": joined["backfilled"].astype(bool),
+    })
+    out["inside_80"] = ((out["realized_close"] >= out["q10"]) &
+                        (out["realized_close"] <= out["q90"]))
+    out["inside_60"] = ((out["realized_close"] >= out["q20"]) &
+                        (out["realized_close"] <= out["q80"]))
+    out["abs_error"] = (out["realized_close"] - out["q50"]).abs()
+    out["pct_error"] = out["abs_error"] / out["realized_close"].abs().replace(0, np.nan) * 100.0
+
+    out = out[TRACKRECORD_COLUMNS]
+    store.append_trackrecord(model_slug, asset, timeframe, out)
+    return out
+
+
+# --------------------------------------------------------------------------
+# Standings
+# --------------------------------------------------------------------------
+
+
+def grade_for(gap: float, resolved_count: int) -> str:
+    """Map a calibration gap to a letter, or to '-' when there is too little.
+
+    Refusing to grade below `MIN_RESOLVED_FOR_GRADE` is deliberate: with a
+    handful of observations the coverage estimate is mostly noise, and a
+    confident 'A' computed from four forecasts would be the single most
+    misleading thing on the page.
+    """
+    if resolved_count < config.MIN_RESOLVED_FOR_GRADE:
+        return "-"
+    if gap is None or not np.isfinite(gap):
+        return "-"
+    for letter, threshold in config.GRADE_THRESHOLDS:
+        if abs(gap) <= threshold:
+            return letter
+    return config.GRADE_THRESHOLDS[-1][0]
+
+
+def build_standings(trackrecord: pd.DataFrame, now=None) -> pd.DataFrame:
+    """Derive the standings table. A pure function of the track record.
+
+    Grouped by (model, asset_class) rather than by asset: a model's calibration
+    on crypto and on equities are different claims, but BTC and ETH are not
+    independent enough for separate grades to mean much.
+    """
+    now = _as_utc(now)
+
+    if trackrecord is None or not len(trackrecord):
+        return pd.DataFrame(columns=STANDINGS_COLUMNS)
+
+    df = trackrecord.copy()
+    df["asset_class"] = df["asset"].map(
+        lambda a: config.ASSETS[a].asset_class if a in config.ASSETS else "other")
+
+    rows = []
+    for (model_slug, asset_class), group in df.groupby(["model_slug", "asset_class"],
+                                                       sort=True):
+        resolved = len(group)
+        coverage_80 = float(group["inside_80"].mean())
+        coverage_60 = float(group["inside_60"].mean())
+        median_err = float(group["pct_error"].median())
+        gap = coverage_80 - config.NOMINAL_COVERAGE
+        rows.append({
+            "model_slug": model_slug,
+            "asset_class": asset_class,
+            "resolved_count": int(resolved),
+            "forecast_count": int(group["forecast_id"].nunique()),
+            "coverage_80": coverage_80,
+            "coverage_60": coverage_60,
+            "median_abs_pct_error": median_err,
+            "calibration_gap": float(gap),
+            "grade": grade_for(gap, resolved),
+            "updated_ts": now,
+        })
+
+    out = pd.DataFrame(rows, columns=STANDINGS_COLUMNS)
+    # Deterministic order, so that "same inputs produce the same standings" is
+    # true of the bytes and not merely of the contents.
+    return out.sort_values(["model_slug", "asset_class"]).reset_index(drop=True)
+
+
+def regenerate_standings(store: ArenaStore, now=None) -> pd.DataFrame:
+    """Rebuild `arena/standings.parquet` from the whole track record."""
+    tr = store.all_trackrecords()
+    standings = build_standings(tr, now=now)
+    store.put_standings(standings)
+    return standings

src/ui/__init__.py

@@ -0,0 +1,16 @@
+"""The Arena's rendering layer.
+
+Importing this package puts the vendored `bit-ui` on the path, so every module
+under it can `from bit_ui import ...` without repeating the dance. bit-ui
+travels as a git submodule and is uploaded to the Space as ordinary files, so
+there is nothing to install at boot.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+_VENDOR = Path(__file__).resolve().parents[2] / "vendor" / "bit-ui"
+if _VENDOR.exists() and str(_VENDOR) not in sys.path:
+    sys.path.insert(0, str(_VENDOR))

src/ui/chart.py

@@ -0,0 +1,300 @@
+"""The forecast chart, as the design's own SVG.
+
+Every number in here comes from the design file rather than from taste: the
+1200x352 viewBox, the 14/252 plot band, the volume strip that starts at y=266
+and draws upward from 322, the 1.4px wicks. Reproducing them exactly is what
+makes the port faithful; rounding them to something tidier is what makes a port
+look approximately right in a way nobody can name.
+
+The chart is rendered server-side as markup rather than drawn by a plotting
+library, because the design specifies the shapes directly and a library would
+fight it the whole way.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from ..adapters import OHLCV_COLUMNS
+from bit_ui.markup import DASH, a, e  # noqa: F401
+
+# --- the design's geometry, verbatim --------------------------------------
+VIEW_W, VIEW_H = 1200, 352
+PLOT_TOP, PLOT_BOTTOM = 14.0, 252.0
+VOL_BASELINE = 266.0     # the rule under the price plot
+VOL_FLOOR = 322.0        # volume bars grow upward from here
+VOL_SCALE = 46.0
+NOW_TOP, NOW_BOTTOM = 8.0, 330.0
+GRID_LINES = 4           # produces 5 labels, hi..lo
+HISTORY_BARS = 56        # how much history the design shows
+
+# Series colours, in selection order. The design's own palette.
+SERIES_COLORS = (
+    "var(--accent-amber-strong)",
+    "var(--mute-teal)",
+    "var(--mute-violet)",
+)
+# Matchup fan styles cycle solid / hatch / open, as the design does.
+FAN_DASH = ("none", "6 4", "2 2 6 2")
+
+
+def series_color(index: int) -> str:
+    return SERIES_COLORS[index % len(SERIES_COLORS)]
+
+
+class Scale:
+    """Maps bar index and price onto the design's coordinate system."""
+
+    def __init__(self, n_history: int, horizon: int, lo: float, hi: float):
+        self.n_history = n_history
+        self.horizon = horizon
+        self.slots = max(1, n_history + horizon)
+        self.slot_w = VIEW_W / self.slots
+        self.bar_w = max(3.0, self.slot_w * 0.6)
+        pad = (hi - lo) * 0.06 or max(abs(hi), 1.0) * 0.01
+        self.lo, self.hi = lo - pad, hi + pad
+
+    def x(self, i: float) -> float:
+        return self.slot_w * (i + 0.5)
+
+    def y(self, v: float) -> float:
+        span = self.hi - self.lo
+        if span <= 0:
+            return PLOT_BOTTOM
+        return PLOT_BOTTOM - ((v - self.lo) / span) * (PLOT_BOTTOM - PLOT_TOP)
+
+
+def _fmt_price(v: float, decimals: int) -> str:
+    return f"{v:,.{decimals}f}"
+
+
+def decimals_for(asset: str) -> int:
+    """BTC prints whole dollars in the design; everything else two places."""
+    return 0 if asset.startswith("BTC") else 2
+
+
+def build(history: pd.DataFrame, runs: list, asset: str, horizon: int,
+          show_ghosts: bool = True, ghost_limit: int = 7) -> dict:
+    """Render the chart. Returns the SVG plus the overlay values around it.
+
+    `runs` is a list of `ForecastRun`. Ghost paths are drawn only for runs
+    whose *declared capability* is `ohlcv_paths` -- never because a result
+    happens to carry a `paths` array. That is the capability gate, and it lives
+    here so no renderer downstream has to know a model's name.
+    """
+    hist = history.tail(HISTORY_BARS).reset_index(drop=True)
+    n = len(hist)
+    if n == 0:
+        return {"svg": "", "grid": [], "time_labels": [], "now_left": "0%",
+                "now_time": "", "forecast_width": "0"}
+
+    lo = float(hist["low"].min())
+    hi = float(hist["high"].max())
+    for run in runs:
+        q = run.result.quantiles
+        lo = min(lo, float(q.min()))
+        hi = max(hi, float(q.max()))
+    scale = Scale(n, horizon, lo, hi)
+
+    parts: list[str] = [
+        f'<svg viewBox="0 0 {VIEW_W} {VIEW_H}" preserveAspectRatio="none" '
+        f'role="img" aria-label="Price history and forecast for {a(asset)}">',
+        '<defs><pattern id="faHatch" width="7" height="7" '
+        'patternUnits="userSpaceOnUse" patternTransform="rotate(45)">'
+        '<line x1="0" y1="0" x2="0" y2="7" stroke="var(--text-tertiary)" '
+        'stroke-width="2.4" opacity="0.5"></line></pattern></defs>',
+    ]
+
+    # -- grid ------------------------------------------------------------
+    grid = []
+    dec = decimals_for(asset)
+    for i in range(GRID_LINES + 1):
+        v = scale.hi - (scale.hi - scale.lo) * (i / GRID_LINES)
+        y = scale.y(v)
+        parts.append(f'<line x1="0" y1="{y:.1f}" x2="{VIEW_W}" y2="{y:.1f}" '
+                     f'stroke="var(--border-subtle)" stroke-width="1" opacity="0.55"></line>')
+        grid.append({"top": f"{y / VIEW_H * 100:.2f}%", "label": _fmt_price(v, dec)})
+
+    # -- the forecast region ---------------------------------------------
+    now_x = scale.x(n - 0.5)
+    parts.append(f'<rect x="{now_x:.1f}" y="8" width="{VIEW_W - now_x:.1f}" '
+                 f'height="252" fill="var(--bg-canvas)" opacity="0.5"></rect>')
+
+    # -- ghost paths, behind the fans ------------------------------------
+    if show_ghosts:
+        for idx, run in enumerate(runs):
+            if run.capabilities.get("output") != "ohlcv_paths":
+                continue          # the capability gate
+            paths = run.result.paths
+            if paths is None:
+                continue
+            color = series_color(idx)
+            parts.append(_ghost_cells(paths, scale, n, horizon, color, ghost_limit))
+
+    # -- fans -------------------------------------------------------------
+    for idx, run in enumerate(runs):
+        parts.append(_fan(run, scale, n, horizon, idx, len(runs)))
+
+    # -- candles ----------------------------------------------------------
+    parts.append(_candles(hist, scale))
+
+    # -- the now line and the volume strip --------------------------------
+    parts.append(f'<line x1="{now_x:.1f}" y1="{NOW_TOP}" x2="{now_x:.1f}" '
+                 f'y2="{NOW_BOTTOM}" stroke="var(--accent-amber)" '
+                 f'stroke-width="1.4" stroke-dasharray="5 4"></line>')
+    parts.append(f'<line x1="0" y1="{VOL_BASELINE}" x2="{VIEW_W}" y2="{VOL_BASELINE}" '
+                 f'stroke="var(--border-subtle)" stroke-width="1"></line>')
+    parts.append(_volumes(hist, runs, scale, n, horizon))
+
+    parts.append("</svg>")
+
+    ts = pd.to_datetime(hist["ts"], utc=True)
+    return {
+        "svg": "".join(parts),
+        "grid": grid,
+        "time_labels": _time_labels(ts, scale, n, horizon),
+        "now_left": f"{now_x / VIEW_W * 100:.2f}%",
+        "now_time": f"· {ts.iloc[-1].strftime('%H:%M')} UTC",
+        "forecast_width": f"{VIEW_W - now_x:.1f}",
+    }
+
+
+# --------------------------------------------------------------------------
+# Pieces
+# --------------------------------------------------------------------------
+
+
+def _candles(hist: pd.DataFrame, scale: Scale) -> str:
+    out = []
+    bw = scale.bar_w
+    o = hist["open"].to_numpy(dtype="float64")
+    h = hist["high"].to_numpy(dtype="float64")
+    lw = hist["low"].to_numpy(dtype="float64")
+    c = hist["close"].to_numpy(dtype="float64")
+    for i in range(len(hist)):
+        up = c[i] >= o[i]
+        color = "var(--fin-up)" if up else "var(--fin-down)"
+        x = scale.x(i)
+        top, bot = scale.y(max(o[i], c[i])), scale.y(min(o[i], c[i]))
+        wick_top, wick_bot = scale.y(h[i]), scale.y(lw[i])
+        out.append(
+            f'<rect x="{x - 0.7:.1f}" y="{wick_top:.1f}" width="1.4" '
+            f'height="{max(1.0, wick_bot - wick_top):.1f}" fill="{color}"></rect>'
+            f'<rect x="{x - bw / 2:.1f}" y="{top:.1f}" width="{bw:.1f}" '
+            f'height="{max(1.4, bot - top):.1f}" fill="{color}"></rect>')
+    return "".join(out)
+
+
+def _fan(run, scale: Scale, n: int, horizon: int, idx: int, total: int) -> str:
+    """The q10/q50/q90 envelope, starting from the last real close."""
+    q = run.result
+    lo_i, hi_i = q.level_index(0.1), q.level_index(0.9)
+    mid_i = q.level_index(0.5)
+    color = series_color(idx)
+
+    steps = min(horizon, q.horizon)
+    upper, lower, mid = [], [], []
+    for t in range(steps):
+        x = scale.x(n + t)
+        upper.append(f"{x:.1f} {scale.y(q.quantiles[t, hi_i]):.1f}")
+        lower.append(f"{x:.1f} {scale.y(q.quantiles[t, lo_i]):.1f}")
+        mid.append(f"{x:.1f} {scale.y(q.quantiles[t, mid_i]):.1f}")
+    if not mid:
+        return ""
+
+    last_close = float(run.context["close"].iloc[-1])
+    start = f"{scale.x(n - 1):.1f} {scale.y(last_close):.1f}"
+
+    matchup = total > 1
+    style = idx % 3 if matchup else 0
+    dash = FAN_DASH[style] if matchup else "none"
+    fill = "url(#faHatch)" if style == 1 and matchup else color
+    fill_op = "0.05" if style == 2 and matchup else ("0.9" if style == 1 and matchup
+                                                     else ("0.14" if matchup else "0.18"))
+
+    band = "M" + start + " L" + " L".join(upper) + " L" + " L".join(reversed(lower)) + " Z"
+    return (
+        f'<path d="{band}" fill="{fill}" opacity="{fill_op}"></path>'
+        f'<path d="M{start} L{" L".join(upper)}" fill="none" stroke="{color}" '
+        f'stroke-width="1.2" stroke-dasharray="2 3" opacity="0.85"></path>'
+        f'<path d="M{start} L{" L".join(lower)}" fill="none" stroke="{color}" '
+        f'stroke-width="1.2" stroke-dasharray="2 3" opacity="0.85"></path>'
+        f'<path d="M{start} L{" L".join(mid)}" fill="none" stroke="{color}" '
+        f'stroke-width="2" stroke-dasharray="{dash}"></path>')
+
+
+def _ghost_cells(paths: np.ndarray, scale: Scale, n: int, horizon: int,
+                 color: str, limit: int) -> str:
+    """Sampled OHLCV paths, drawn as faint candle bodies.
+
+    Only `limit` of them are drawn. Sending every sampled path would multiply
+    the payload by the sample count for no readable gain -- past a handful the
+    ghosts stop being individually legible and become a smear.
+    """
+    o_i, c_i = OHLCV_COLUMNS.index("open"), OHLCV_COLUMNS.index("close")
+    out = []
+    bw = scale.bar_w
+    take = min(limit, paths.shape[0])
+    # Evenly spaced through the samples rather than the first N, so the ghosts
+    # represent the spread instead of whichever paths happened to be drawn first.
+    picks = np.linspace(0, paths.shape[0] - 1, take).round().astype(int)
+    steps = min(horizon, paths.shape[1])
+    for s in picks:
+        for t in range(steps):
+            o = float(paths[s, t, o_i])
+            c = float(paths[s, t, c_i])
+            top, bot = scale.y(max(o, c)), scale.y(min(o, c))
+            out.append(
+                f'<rect x="{scale.x(n + t) - bw * 0.35:.1f}" y="{top:.1f}" '
+                f'width="{bw * 0.7:.1f}" height="{max(1.2, bot - top):.1f}" '
+                f'fill="{color}" opacity="0.17"></rect>')
+    return "".join(out)
+
+
+def _volumes(hist: pd.DataFrame, runs: list, scale: Scale, n: int,
+             horizon: int) -> str:
+    vol = hist["volume"].to_numpy(dtype="float64")
+    peak = float(vol.max()) or 1.0
+    o = hist["open"].to_numpy(dtype="float64")
+    c = hist["close"].to_numpy(dtype="float64")
+    bw = scale.bar_w
+    out = []
+    for i in range(n):
+        h = (vol[i] / peak) * VOL_SCALE
+        color = "var(--fin-up)" if c[i] >= o[i] else "var(--fin-down)"
+        out.append(f'<rect x="{scale.x(i) - bw / 2:.1f}" y="{VOL_FLOOR - h:.1f}" '
+                   f'width="{bw:.1f}" height="{h:.1f}" fill="{color}" opacity="0.55"></rect>')
+
+    # Forecast-side volume, only from a model that actually forecasts volume.
+    for idx, run in enumerate(runs[:1]):
+        if run.capabilities.get("output") != "ohlcv_paths" or run.result.paths is None:
+            continue
+        v_i = OHLCV_COLUMNS.index("volume")
+        mean_vol = run.result.paths[:, :, v_i].mean(axis=0)
+        color = series_color(idx)
+        for t in range(min(horizon, len(mean_vol))):
+            h = (float(mean_vol[t]) / peak) * VOL_SCALE
+            h = max(0.0, min(h, VOL_SCALE * 1.5))
+            out.append(f'<rect x="{scale.x(n + t) - bw / 2:.1f}" '
+                       f'y="{VOL_FLOOR - h:.1f}" width="{bw:.1f}" height="{h:.1f}" '
+                       f'fill="{color}" opacity="0.22"></rect>')
+    return "".join(out)
+
+
+def _time_labels(ts: pd.Series, scale: Scale, n: int, horizon: int) -> list[dict]:
+    if len(ts) < 2:
+        return []
+    step = ts.diff().dropna().mode()
+    step = step.iloc[0] if len(step) else pd.Timedelta("1h")
+    last = ts.iloc[-1]
+    out = []
+    for i in range(6):
+        idx = round((scale.slots - 1) * i / 5)
+        when = last + step * (idx - (n - 1))
+        x = scale.x(idx)
+        out.append({
+            "left": f"{min(97.0, max(3.0, x / VIEW_W * 100)):.2f}%",
+            "label": when.strftime("%d %H:%M"),
+        })
+    return out

src/ui/chrome.py

@@ -0,0 +1,158 @@
+"""The Arena's bridge vocabulary and its own CSS.
+
+Everything shared with the other Spaces -- the sidebar, the command palette,
+the dialogs, the design system's stylesheets, the click-bridge mechanism --
+comes from `bit_ui`. This module is the thin Arena-specific layer: the actions
+this Space accepts, and CSS for the parts of the design only this Space has.
+"""
+
+from __future__ import annotations
+
+from bit_ui import bridge, theme
+
+# Actions this Space accepts, on top of the ones bit-ui's chrome emits. An
+# action off this list is dropped by the bridge, so a hand-crafted click cannot
+# reach a code path the UI does not offer.
+ARENA_KEYS = frozenset({
+    "mode",       # playground | matchup
+    "pick",       # select/deselect a model card
+    "asset",      # choose an asset
+    "tf",         # choose a timeframe
+    "hz",         # choose a horizon
+    "gear",       # toggle the sampling popover
+    "ghosts",     # toggle sampled-path rendering
+    "run",        # issue the forecast
+    "cls",        # standings asset-class filter
+    "stand",      # a standings row: deep-link into playground
+    "hfid",       # the enrollment id box (arrives live as hfid=<text>)
+    "family",     # the enrollment adapter-family choice
+    "enroll",     # run the smoke test and enroll
+    "backfill",   # contribute a backfill run
+    "reopen",     # re-open an archived forecast from the log
+    "dismiss",    # dismiss an error banner
+})
+
+# `sidebar` is deliberately absent: collapsing is a client-side attribute flip
+# in bit_ui.bridge, not a server action. Routing it through Gradio would put a
+# full-page re-render behind a purely visual toggle.
+ALLOWED_KEYS = (bridge.SHARED_KEYS - {"sidebar"}) | ARENA_KEYS
+
+emit = bridge.make_emitter(ALLOWED_KEYS)
+
+
+def parse_action(raw):
+    return bridge.parse_action(raw, ALLOWED_KEYS)
+
+
+# --------------------------------------------------------------------------
+# Arena-only CSS
+# --------------------------------------------------------------------------
+#
+# Two kinds of rule live here.
+#
+# Layout: the design pins its zones in pixels (`railW:304px`) and switches at
+# widths Gradio knows nothing about. Those are media queries rather than the
+# design's inline JS-computed values, because the server cannot know the
+# viewport and a round trip to find out would be absurd for a layout breakpoint.
+#
+# Repeated rows: the design's inline styles are the most faithful port for
+# markup rendered once, but a model card carries ~700 bytes of inline style and
+# there are a dozen of them, re-sent on every interaction. The classes below
+# hold the design's exact values, just relocated.
+
+ARENA_CSS = """
+/* ---- zone layout ------------------------------------------------------ */
+.fa-zones { display:flex; align-items:flex-start; gap:12px; flex-wrap:nowrap; }
+.fa-main  { flex:1 1 auto; min-width:0; display:flex; flex-direction:column; gap:12px; }
+.fa-rail  { flex:0 0 304px; width:304px; min-width:0;
+            display:flex; flex-direction:column; gap:12px; }
+.fa-picker { display:grid; grid-template-columns:repeat(6,minmax(0,1fr)); gap:0; }
+.fa-foot   { display:grid; grid-template-columns:1.1fr 0.8fr 0.8fr 1.6fr; gap:0; }
+
+@media (max-width:1400px) {
+  .fa-zones { flex-wrap:wrap; }
+  .fa-main  { flex:1 1 100%; width:100%; }
+  .fa-rail  { flex:1 1 100%; width:100%; }
+}
+@media (max-width:1180px) { .fa-picker { grid-template-columns:repeat(2,minmax(0,1fr)); } }
+@media (max-width:900px)  { .fa-foot   { grid-template-columns:1fr; } }
+
+/* ---- model card (repeated) -------------------------------------------- */
+.fa-card { text-align:left; display:flex; flex-direction:column; gap:7px;
+           padding:10px 11px; border:0; border-right:1px solid var(--border-subtle);
+           border-top:3px solid transparent; cursor:pointer;
+           color:var(--text-primary); background:transparent;
+           transition:background 1s ease; }
+.fa-card:hover { background:var(--bg-raised); }
+.fa-card.on { background:var(--bg-raised); }
+.fa-card-top { display:flex; align-items:center; gap:7px; }
+.fa-card-name { font-family:var(--font-styrene); font-size:var(--text-md);
+                text-transform:uppercase; letter-spacing:var(--tracking-wide);
+                color:var(--text-secondary);
+                white-space:nowrap; overflow:hidden; text-overflow:ellipsis; }
+.fa-card.on .fa-card-name { color:var(--text-primary); }
+.fa-card-caps { display:flex; flex-wrap:wrap; gap:4px; }
+.fa-card-cal { display:flex; align-items:center; gap:6px;
+               border-top:1px solid var(--border-subtle); padding-top:6px; }
+.fa-chk { margin-left:auto; display:inline-flex; align-items:center;
+          justify-content:center; width:16px; height:16px;
+          border:1px solid var(--border-default); background:transparent;
+          color:var(--text-tertiary); font-family:var(--font-mono);
+          font-size:var(--text-2xs); line-height:1; }
+.fa-tag { font-size:var(--text-2xs); padding:1px 5px; white-space:nowrap;
+          border:1px solid var(--border-default); background:transparent; }
+
+/* ---- standings row (repeated) ----------------------------------------- */
+.fa-stand { width:100%; text-align:left; display:flex; align-items:center;
+            gap:8px; padding:6px 10px; background:transparent; border:0;
+            border-bottom:1px solid var(--border-subtle);
+            border-left:2px solid transparent; cursor:pointer;
+            color:var(--text-primary); transition:background 1s ease; }
+.fa-stand:hover { background:var(--bg-raised); }
+.fa-stand.on { background:var(--bg-raised); }
+.fa-stand-mid { flex:1 1 auto; min-width:0; display:flex;
+                flex-direction:column; gap:1px; }
+.fa-stand-name { font-size:var(--text-xs); white-space:nowrap;
+                 overflow:hidden; text-overflow:ellipsis; }
+
+/* ---- track-record thumbnails (repeated) -------------------------------- */
+.fa-trcell { flex:0 0 auto; width:112px; padding:8px 9px;
+             border-right:1px solid var(--border-subtle);
+             display:flex; flex-direction:column; gap:5px; }
+.fa-trcell.miss { background:var(--bg-raised); }
+.fa-trstrip { display:flex; gap:0; overflow-x:auto; }
+
+/* ---- pill buttons (repeated) ------------------------------------------ */
+.fa-pill { padding:3px 8px; background:transparent;
+           border:1px solid var(--border-default); color:var(--text-secondary);
+           cursor:pointer; font-family:var(--font-mono); font-size:var(--text-xs);
+           transition:background 1s ease,color 1s ease; }
+.fa-pill.on { background:var(--bg-raised); border-color:var(--accent-amber);
+              color:var(--accent-amber-strong); }
+.fa-seg { padding:3px 10px; background:transparent;
+          border:1px solid var(--border-default); border-left-width:0;
+          color:var(--text-secondary); cursor:pointer;
+          font-family:var(--font-mono); font-size:var(--text-xs);
+          transition:background 1s ease,color 1s ease; }
+.fa-seg.first { border-left-width:1px; }
+.fa-seg.on { background:var(--accent-amber); color:var(--stone-950); }
+
+/* The chart is a fixed-ratio SVG; letting it size from content makes the
+   iframe ratchet, which is the failure `bit_ui.theme.find_forced_vh` exists
+   to catch. `width:100%;height:auto` on a viewBox does the right thing. */
+.fa-chart svg { display:block; width:100%; height:auto; }
+.fa-chart { position:relative; background:var(--bg-sunken);
+            display:flex; align-items:stretch; }
+.fa-axis { flex:0 0 auto; width:66px; position:relative;
+           border-left:1px solid var(--border-subtle); }
+"""
+
+
+def full_css(extra: str = "") -> str:
+    """bit-ui's shared CSS plus the Arena's own.
+
+    Calling `theme.full_css()` directly is the mistake to avoid: it returns the
+    shared chrome only and silently drops everything above, which reads as a
+    layout bug rather than a missing stylesheet.
+    """
+    return theme.full_css(ARENA_CSS + extra)

src/ui/shell.py

@@ -0,0 +1,1056 @@
+"""The Arena's visible layer: the design's own markup, rendered from state.
+
+Gradio is the backend here and nothing else -- one `gr.HTML` sink, a hidden
+textbox the click bridge writes into, and a hidden button it clicks. Every
+control on the page is the `<button>` the design specifies, carrying a
+`data-bit` action, because the design is built from 13 buttons against 2 inputs
+and Gradio renders something structurally different for the same concepts.
+
+The one rule to keep when editing: **render from capabilities, never from a
+model's name.** `caps["output"] == "ohlcv_paths"` is what decides whether the
+ghost-path control exists. There is no branch anywhere below that mentions
+Kronos, Chronos or TimesFM.
+"""
+
+from __future__ import annotations
+
+import pandas as pd
+from bit_ui import icons, palette, sidebar
+from bit_ui.markup import a, e
+
+from .. import config, view
+from ..view import DASH, count, grade_color, num, pct
+from . import chart
+from .chrome import emit
+
+STYRENE = ("font-family:var(--font-styrene);text-transform:uppercase;"
+           "letter-spacing:var(--tracking-wide)")
+PANEL = "border:1px solid var(--border-default);background:var(--bg-panel)"
+HEAD = ("display:flex;align-items:center;gap:8px;padding:7px 10px;"
+        "border-bottom:1px solid var(--border-default)")
+
+
+def bit(action: str, value: str = "") -> str:
+    """The full `data-bit` attribute for an action, escaped.
+
+    `emit()` returns the attribute *value*, not the attribute. Interpolating it
+    bare renders `<button run:go>`, which is not a data attribute at all: the
+    delegated listener never matches it and the control does nothing, with no
+    error anywhere. This wrapper is the only way actions are attached below.
+    """
+    return f'type="button" data-bit="{a(emit(action, value))}"'
+
+
+def _panel_title(text: str, right: str = "") -> str:
+    return (f'<div style="{HEAD}">'
+            f'<span style="{STYRENE};font-size:var(--text-sm)">{e(text)}</span>'
+            f'{right}</div>')
+
+
+# --------------------------------------------------------------------------
+# Header
+# --------------------------------------------------------------------------
+
+
+def header(state: dict, data: dict) -> str:
+    archived = data.get("archived_total")
+    resolved = data.get("resolved_total")
+    tally = (f"ARCHIVE: {count(archived)} FORECASTS · {count(resolved)} RESOLVED"
+             if archived is not None else "ARCHIVE: BUILDING")
+
+    account = ("ACCOUNT · SIGNED IN" if state.get("signed_in")
+               else "Connect with Hugging Face")
+    dot = "var(--fin-up)" if state.get("signed_in") else "var(--mute-orange)"
+
+    return (
+        '<header style="position:sticky;top:0;z-index:20;background:var(--bg-panel);'
+        'border-bottom:1px solid var(--border-default)">'
+        '<div style="display:flex;align-items:center;gap:10px;padding:8px 14px;'
+        'min-height:48px;flex-wrap:wrap">'
+        '<div style="display:flex;align-items:center;gap:8px;flex:0 0 auto">'
+        '<span style="display:inline-block;width:6px;height:6px;'
+        'background:var(--fin-up);animation:bitPulse 2s ease-in-out infinite"></span>'
+        f'<span style="{STYRENE};font-size:var(--text-sm);color:var(--text-secondary)">Arena</span>'
+        '</div>'
+        f'<a href="{a(data.get("store_url", "#"))}" target="_blank" rel="noopener" '
+        'style="display:flex;align-items:center;gap:8px;padding:3px 8px;'
+        'border:1px solid var(--accent-amber-dim);color:var(--accent-amber-strong);'
+        'flex:0 0 auto;text-decoration:none">'
+        f'<span class="mono-data" style="font-size:var(--text-xs)">{e(tally)}</span></a>'
+        '<div style="flex:1 1 auto;min-width:180px;max-width:400px">'
+        f'{palette.search_bar(state.get("q", ""), emit, count_label="")}'
+        '</div>'
+        '<span style="display:inline-flex;align-items:center;gap:6px;padding:3px 8px;'
+        'border:1px solid var(--border-default);margin-left:auto">'
+        f'<span style="display:inline-block;width:5px;height:5px;background:{dot}"></span>'
+        f'<span class="mono-data" style="font-size:var(--text-2xs);'
+        f'color:var(--text-secondary);white-space:nowrap">{e(account)}</span></span>'
+        '</div>'
+        '</header>'
+    )
+
+
+# --------------------------------------------------------------------------
+# Stats and title
+# --------------------------------------------------------------------------
+
+
+def title_row(state: dict, data: dict) -> str:
+    deep = ""
+    if state.get("deep_linked"):
+        deep = ('<span style="display:inline-flex;align-items:center;gap:7px;'
+                'padding:4px 8px;border:1px solid var(--accent-amber-dim);'
+                'background:var(--bg-raised)">'
+                '<span class="pixel-text" style="color:var(--accent-amber-strong)">→</span>'
+                '<span class="mono-data" style="font-size:var(--text-2xs);'
+                f'color:var(--text-secondary)">DEEP LINK ?model={e(state["selected"][0])}'
+                ' · PRESELECTED</span></span>')
+
+    ran = data.get("resolver_last_ran") or DASH
+    return (
+        '<div style="display:flex;align-items:flex-end;gap:12px;flex-wrap:wrap">'
+        '<div style="display:flex;flex-direction:column;gap:3px;min-width:0">'
+        f'<h1 style="{STYRENE};font-weight:500;font-size:var(--text-2xl);'
+        'line-height:var(--leading-tight);margin:0">Forecast Arena</h1>'
+        '<span style="color:var(--text-secondary);font-size:var(--text-base)">'
+        'Every model forecasts. Every forecast is remembered.</span></div>'
+        f'{deep}'
+        '<span style="display:inline-flex;align-items:center;gap:6px;padding:4px 8px;'
+        f'border:1px solid var(--border-default);background:var(--bg-panel);margin-left:auto">'
+        '<span style="display:inline-block;width:5px;height:5px;'
+        'background:var(--accent-amber);animation:bitPulse 2s ease-in-out infinite"></span>'
+        '<span class="mono-data" style="font-size:var(--text-2xs);'
+        f'color:var(--text-secondary);white-space:nowrap">RESOLVER LAST RAN {e(ran)}</span>'
+        '</span></div>'
+    )
+
+
+def stats_bar(stats: list[dict]) -> str:
+    cells = []
+    for s in stats:
+        cells.append(
+            f'<div style="padding:10px 12px;border-right:1px solid var(--border-subtle);'
+            f'border-left:2px solid {a(s["mark"])}">'
+            f'<div style="{STYRENE};font-weight:300;font-size:var(--text-2xs);'
+            f'letter-spacing:var(--tracking-wider);color:var(--text-tertiary);'
+            f'white-space:nowrap;overflow:hidden;text-overflow:ellipsis">{e(s["label"])}</div>'
+            f'<div class="mono-data" style="font-size:var(--text-2xl);line-height:1.15;'
+            f'white-space:nowrap;color:{a(s["color"])}">{e(s["value"])}</div>'
+            f'<div style="font-size:var(--text-2xs);color:var(--text-tertiary);'
+            f'white-space:nowrap;overflow:hidden;text-overflow:ellipsis">{e(s["note"])}</div>'
+            f'</div>')
+    return ('<div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(190px,1fr));'
+            f'{PANEL}">{"".join(cells)}</div>')
+
+
+# --------------------------------------------------------------------------
+# Model picker
+# --------------------------------------------------------------------------
+
+
+def models_section(state: dict, data: dict) -> str:
+    mode = state["mode"]
+    selected = state["selected"]
+    sel_note = (f"MATCHUP · {len(selected)} OF {view.MAX_MATCHUP} SELECTED"
+                if mode == "matchup" else "PLAYGROUND · SINGLE MODEL")
+
+    tabs = []
+    for i, (key, label) in enumerate((("playground", "Playground"),
+                                      ("matchup", "Matchup"))):
+        on = mode == key
+        tabs.append(
+            f'<button {bit("mode", key)} style="padding:4px 12px;'
+            f'background:{"var(--accent-amber)" if on else "transparent"};'
+            f'border:1px solid var(--border-default);border-left-width:{"1px" if i == 0 else "0"};'
+            f'color:{"var(--stone-950)" if on else "var(--text-secondary)"};{STYRENE};'
+            f'font-size:var(--text-xs);cursor:pointer;transition:background 1s ease">'
+            f'{e(label)}</button>')
+
+    cards = "".join(_model_card(m, m["slug"] in selected, data)
+                    for m in data["models"])
+
+    add = (
+        f'<button {bit("enroll", "focus")} style="text-align:left;display:flex;'
+        'flex-direction:column;gap:6px;justify-content:center;padding:10px 11px;'
+        'background:transparent;border:0;border-left:1px dashed var(--border-default);'
+        'cursor:pointer;color:var(--text-tertiary)">'
+        '<span class="mono-data" style="font-size:var(--text-lg)">+</span>'
+        f'<span style="{STYRENE};font-size:var(--text-sm)">Add a fine-tune</span>'
+        '<span style="font-size:var(--text-2xs);text-wrap:pretty">Any Hub model with a '
+        'Kronos, Chronos or TimesFM adapter family</span></button>')
+
+    return (
+        f'<section style="{PANEL}">'
+        '<div style="display:flex;align-items:center;gap:10px;padding:8px 12px;'
+        'border-bottom:1px solid var(--border-default);flex-wrap:wrap">'
+        f'<span style="{STYRENE};font-size:var(--text-md)">Models</span>'
+        f'<span class="mono-data" style="font-size:var(--text-2xs);'
+        f'color:var(--text-tertiary)">{e(sel_note)}</span>'
+        f'<div style="display:flex;margin-left:auto">{"".join(tabs)}</div></div>'
+        f'<div class="fa-picker">{cards}{add}</div></section>'
+    )
+
+
+def _model_card(model: dict, on: bool, data: dict) -> str:
+    """One model card. Rendered from declared capabilities only."""
+    color = model["color"]
+    caps = model["caps"]
+
+    # The two capability chips the design specifies: what the model emits, and
+    # what hardware it costs. Both come from the adapter's declaration.
+    paths = caps.get("output") == "ohlcv_paths"
+    gpu = caps.get("hardware") == "gpu"
+    chips = [
+        ("OHLCV paths" if paths else "quantile line",
+         "var(--accent-amber-strong)" if paths else "var(--text-secondary)",
+         "var(--accent-amber-dim)" if paths else "var(--border-default)"),
+        ("your GPU quota" if gpu else "CPU · instant",
+         "var(--mute-orange)" if gpu else "var(--accent-moss-strong)",
+         "var(--mute-orange)" if gpu else "var(--accent-moss-dim)"),
+    ]
+    chip_html = "".join(
+        f'<span class="mono-data fa-tag" style="color:{a(fg)};border-color:{a(bd)}">'
+        f'{e(label)}</span>' for label, fg, bd in chips)
+
+    chk_style = (f'background:{a(color)};color:var(--stone-950);border-color:{a(color)}'
+                 if on else "")
+    return (
+        f'<button {bit("pick", model["slug"])} class="fa-card{" on" if on else ""}" '
+        f'style="border-top-color:{a(color) if on else "transparent"}">'
+        '<div class="fa-card-top">'
+        f'<span class="mono-data fa-tag" style="color:{a(color) if on else "var(--text-tertiary)"};'
+        f'border-color:{a(color) if on else "var(--border-default)"}">{e(model["family"].upper())}</span>'
+        f'<span class="mono-data" style="font-size:var(--text-2xs);'
+        f'color:var(--text-tertiary)">{e(model["size"])}</span>'
+        f'<span class="fa-chk" style="{chk_style}">{"✓" if on else ""}</span></div>'
+        f'<div class="fa-card-name">{e(model["name"])}</div>'
+        f'<div class="fa-card-caps">{chip_html}</div>'
+        '<div class="fa-card-cal">'
+        '<span class="pixel-text" style="color:var(--text-tertiary)">CALIBRATION</span>'
+        f'<span class="mono-data" style="font-size:var(--text-md);'
+        f'color:{a(model["grade_color"])};margin-left:auto">{e(model["grade"])}</span>'
+        f'<span class="mono-data" style="font-size:var(--text-2xs);'
+        f'color:var(--text-tertiary)">{e(model["resolved_label"])}</span></div>'
+        '</button>')
+
+
+# --------------------------------------------------------------------------
+# Controls
+# --------------------------------------------------------------------------
+
+
+def controls(state: dict, data: dict) -> str:
+    assets = "".join(
+        f'<button {bit("asset", slug)} class="fa-pill'
+        f'{" on" if state["asset"] == slug else ""}">{e(spec.display)}</button>'
+        for slug, spec in config.ASSETS.items())
+
+    tfs = "".join(
+        f'<button {bit("tf", slug)} class="fa-seg{" first" if i == 0 else ""}'
+        f'{" on" if state["tf"] == slug else ""}">{e(slug)}</button>'
+        for i, slug in enumerate(config.TIMEFRAMES))
+
+    options = _horizon_options(state["tf"])
+    hzs = "".join(
+        f'<button {bit("hz", str(h))} class="fa-seg{" first" if i == 0 else ""}'
+        f'{" on" if int(state["horizon"]) == h else ""}">{h} steps</button>'
+        for i, h in enumerate(options))
+
+    hours = state["horizon"] * (1 if state["tf"] == "1h" else 24)
+    hz_note = f"= {hours}H AHEAD"
+
+    gear = _gear(state) if state.get("gear") else ""
+    quota = _quota_banner(data) if data.get("quota_blocked") else ""
+
+    run_label = ("▶ Forecast" if state["mode"] == "playground"
+                 else f"▶ Forecast {len(state['selected'])} models")
+    runtime = data.get("runtime_hint", DASH)
+    blocked = bool(data.get("quota_blocked"))
+
+    return (
+        f'<section style="{PANEL};display:flex;align-items:center;gap:14px;'
+        'padding:9px 12px;flex-wrap:wrap">'
+        '<div style="display:flex;align-items:center;gap:6px;flex-wrap:wrap">'
+        '<span class="pixel-text" style="color:var(--text-tertiary)">ASSET</span>'
+        f'{assets}</div>'
+        '<div style="width:1px;height:22px;background:var(--border-subtle)"></div>'
+        '<div style="display:flex;align-items:center;gap:6px">'
+        '<span class="pixel-text" style="color:var(--text-tertiary)">TIMEFRAME</span>'
+        f'<div style="display:flex">{tfs}</div></div>'
+        '<div style="width:1px;height:22px;background:var(--border-subtle)"></div>'
+        '<div style="display:flex;align-items:center;gap:6px">'
+        '<span class="pixel-text" style="color:var(--text-tertiary)">HORIZON</span>'
+        f'<div style="display:flex">{hzs}</div>'
+        f'<span class="mono-data" style="font-size:var(--text-2xs);'
+        f'color:var(--text-tertiary)">{e(hz_note)}</span></div>'
+        '<div style="position:relative;margin-left:auto;display:flex;'
+        'align-items:center;gap:8px">'
+        f'<button {bit("gear", "toggle")} title="Sampling and seed" '
+        f'style="width:26px;height:26px;background:'
+        f'{"var(--bg-raised)" if state.get("gear") else "transparent"};'
+        f'border:1px solid {"var(--accent-amber)" if state.get("gear") else "var(--border-default)"};'
+        f'color:{"var(--accent-amber-strong)" if state.get("gear") else "var(--text-tertiary)"};'
+        'cursor:pointer;display:flex;align-items:center;justify-content:center">'
+        f'{icons.icon("sliders", size="13px")}</button>'
+        f'{gear}{quota}'
+        f'<span class="mono-data" style="font-size:var(--text-2xs);'
+        f'color:var(--text-tertiary);padding:3px 7px;'
+        f'border:1px solid var(--border-subtle)">{e(runtime)}</span>'
+        f'<button {bit("run", "go")} '
+        f'style="padding:6px 14px;background:'
+        f'{"var(--bg-raised)" if blocked else "var(--accent-amber)"};'
+        f'border:1px solid {"var(--border-default)" if blocked else "var(--accent-amber)"};'
+        f'color:{"var(--text-disabled)" if blocked else "var(--stone-950)"};'
+        f'{STYRENE};font-size:var(--text-xs);'
+        f'cursor:{"not-allowed" if blocked else "pointer"}">{e(run_label)}</button>'
+        '</div></section>'
+    )
+
+
+def _horizon_options(timeframe: str) -> list[int]:
+    """Horizon choices, capped at what the timeframe allows."""
+    ceiling = config.MAX_HORIZON.get(timeframe, 96)
+    return [h for h in (12, 24, 48, 96) if h <= ceiling] or [ceiling]
+
+
+def _gear(state: dict) -> str:
+    rows = [
+        ("Sampled paths", str(state.get("n_samples", config.DEFAULT_N_SAMPLES))),
+        ("Quantiles", "/".join(f"{q:g}" for q in config.QUANTILE_LEVELS)),
+        ("Seed", str(state.get("seed", 42))),
+    ]
+    body = "".join(
+        '<div style="display:flex;align-items:center;gap:8px">'
+        f'<span style="flex:1 1 auto;{STYRENE};font-weight:300;'
+        f'font-size:var(--text-xs);color:var(--text-secondary)">{e(label)}</span>'
+        f'<span class="mono-data" style="font-size:var(--text-xs);'
+        f'color:var(--text-primary);border:1px solid var(--border-default);'
+        f'padding:2px 7px">{e(value)}</span></div>'
+        for label, value in rows)
+    return (
+        '<div style="position:absolute;top:32px;right:0;z-index:40;width:230px;'
+        'background:var(--bg-raised);border:1px solid var(--border-strong);'
+        'padding:10px 12px;display:flex;flex-direction:column;gap:9px">'
+        f'<span style="{STYRENE};font-weight:300;font-size:var(--text-xs);'
+        'color:var(--text-tertiary)">Sampling</span>'
+        f'{body}'
+        '<span class="pixel-text" style="color:var(--text-tertiary)">'
+        'SEED IS ARCHIVED WITH THE FORECAST</span></div>')
+
+
+def _quota_banner(data: dict) -> str:
+    return (
+        '<span style="display:inline-flex;align-items:center;gap:7px;padding:4px 9px;'
+        'border:1px solid var(--mute-orange);background:var(--bg-raised)">'
+        '<span class="pixel-text" style="color:var(--mute-orange)">⚠</span>'
+        f'<span style="font-size:var(--text-xs);color:var(--text-secondary)">'
+        f'{e(data.get("quota_msg", "GPU-tier model — sign in to use your quota"))}</span>'
+        f'<a href="{a(data.get("login_url", "#"))}" style="font-family:var(--font-mono);'
+        'font-size:var(--text-2xs);white-space:nowrap">SIGN IN ↗</a></span>')
+
+
+# --------------------------------------------------------------------------
+# Chart panel
+# --------------------------------------------------------------------------
+
+
+def chart_section(state: dict, data: dict) -> str:
+    runs = data.get("runs", [])
+    mode = state["mode"]
+    primary = runs[0] if runs else None
+
+    title = "Matchup" if mode == "matchup" else "Forecast"
+    who = (f"{len(runs)} MODELS" if mode == "matchup"
+           else (data["models_by_slug"].get(state["selected"][0], {}).get("name", "")
+                 .upper() if state["selected"] else ""))
+    meta = f'{state["asset"]} · {state["tf"]} · H+{state["horizon"]} · {who}'
+
+    # The capability gate, in one place. `ghost_capable` is true when the
+    # *selected* model declares OHLCV paths -- not when a result happens to
+    # carry them.
+    ghost_capable = bool(primary
+                         and primary.capabilities.get("output") == "ohlcv_paths"
+                         and mode == "playground")
+    ghost_locked = bool(primary
+                        and primary.capabilities.get("output") != "ohlcv_paths"
+                        and mode == "playground")
+
+    if ghost_capable:
+        on = state.get("ghosts", True)
+        toggle = (
+            f'<button {bit("ghosts", "toggle")} style="display:inline-flex;'
+            'align-items:center;gap:6px;padding:3px 8px;background:'
+            f'{"var(--bg-raised)" if on else "transparent"};'
+            f'border:1px solid {"var(--accent-amber)" if on else "var(--border-default)"};'
+            f'color:{"var(--accent-amber-strong)" if on else "var(--text-secondary)"};'
+            'cursor:pointer">'
+            f'<span class="mono-data" style="font-size:var(--text-2xs)">{"✓" if on else ""}</span>'
+            f'<span style="{STYRENE};font-size:var(--text-xs)">Sampled OHLCV paths</span>'
+            '</button>')
+    elif ghost_locked:
+        toggle = (
+            '<span style="display:inline-flex;align-items:center;gap:6px;padding:3px 8px;'
+            'border:1px dashed var(--border-default);color:var(--text-disabled)">'
+            '<span class="mono-data" style="font-size:var(--text-2xs)">✕</span>'
+            f'<span style="{STYRENE};font-size:var(--text-xs)">'
+            'Quantile line only — no OHLCV paths</span></span>')
+    else:
+        toggle = ""
+
+    frozen = (f'FROZEN {primary.issued_ts.strftime("%Y-%m-%d %H:%M")} UTC · '
+              f'SEED {primary.result.seed}' if primary else "NO FORECAST ISSUED YET")
+
+    drawing = data.get("chart") or {}
+    body = _chart_body(drawing) if drawing.get("svg") else _chart_empty(data)
+
+    return (
+        f'<section style="{PANEL}">'
+        '<div style="display:flex;align-items:center;gap:10px;padding:8px 12px;'
+        'border-bottom:1px solid var(--border-default);flex-wrap:wrap">'
+        f'<span style="{STYRENE};font-size:var(--text-md)">{e(title)}</span>'
+        f'<span class="mono-data" style="font-size:var(--text-xs);'
+        'color:var(--text-secondary);padding:2px 7px;'
+        f'border:1px solid var(--border-default)">{e(meta)}</span>'
+        '<div style="display:flex;align-items:center;gap:8px;margin-left:auto;'
+        f'flex-wrap:wrap">{toggle}'
+        f'<span class="mono-data" style="font-size:var(--text-2xs);'
+        f'color:var(--text-tertiary)">{e(frozen)}</span></div></div>'
+        f'{_legend(data)}{body}</section>'
+    )
+
+
+def _legend(data: dict) -> str:
+    runs = data.get("runs", [])
+    if not runs:
+        return ""
+    items = []
+    for i, run in enumerate(runs):
+        color = chart.series_color(i)
+        panel = data["panels"].get(run.model_slug, {})
+        name = data["models_by_slug"].get(run.model_slug, {}).get("name", run.model_slug)
+        width = panel.get("width")
+        band = (f'10 / 50 / 90 · {pct(width, 1)} MEAN WIDTH' if width is not None
+                else "10 / 50 / 90")
+        grade = panel.get("grade", "-")
+        dash = chart.FAN_DASH[i % 3] if len(runs) > 1 else "none"
+        items.append(
+            '<div style="display:flex;align-items:center;gap:8px">'
+            '<svg width="34" height="12" viewBox="0 0 34 12" '
+            'style="flex:0 0 auto;display:block">'
+            f'<rect x="0" y="2" width="34" height="8" fill="{a(color)}" opacity="0.16"></rect>'
+            f'<line x1="0" y1="6" x2="34" y2="6" stroke="{a(color)}" '
+            f'stroke-width="1.6" stroke-dasharray="{a(dash)}"></line></svg>'
+            f'<span style="{STYRENE};font-size:var(--text-sm)">{e(name)}</span>'
+            f'<span class="mono-data" style="font-size:var(--text-2xs);'
+            f'color:var(--text-tertiary)">{e(band)}</span>'
+            f'<span class="mono-data" style="font-size:var(--text-xs);'
+            f'color:{a(grade_color(grade))};border:1px solid {a(grade_color(grade))};'
+            f'padding:1px 5px">{e(grade)}</span>'
+            f'<span style="font-size:var(--text-2xs);'
+            f'color:{a(panel.get("verdict_color", "var(--text-tertiary)"))}">'
+            f'{e(panel.get("verdict_short", ""))}</span></div>')
+    return ('<div style="display:flex;align-items:center;gap:14px;padding:7px 12px;'
+            'border-bottom:1px solid var(--border-subtle);background:var(--bg-raised);'
+            f'flex-wrap:wrap">{"".join(items)}</div>')
+
+
+def _chart_body(drawing: dict) -> str:
+    axis = "".join(
+        f'<span class="mono-data" style="position:absolute;right:6px;top:{a(g["top"])};'
+        'transform:translateY(-50%);font-size:var(--text-2xs);'
+        f'color:var(--text-tertiary);white-space:nowrap">{e(g["label"])}</span>'
+        for g in drawing.get("grid", []))
+    times = "".join(
+        f'<span class="mono-data" style="position:absolute;left:{a(t["left"])};'
+        'transform:translateX(-50%);font-size:var(--text-2xs);'
+        f'color:var(--text-tertiary);white-space:nowrap">{e(t["label"])}</span>'
+        for t in drawing.get("time_labels", []))
+    left = a(drawing.get("now_left", "50%"))
+    return (
+        '<div class="fa-chart"><div style="position:relative;flex:1 1 auto;min-width:0">'
+        f'{drawing["svg"]}'
+        f'<span class="mono-data" style="position:absolute;left:{left};top:5px;'
+        'transform:translateX(-100%);padding-right:6px;font-size:var(--text-2xs);'
+        f'color:var(--accent-amber-strong);white-space:nowrap">NOW '
+        f'{e(drawing.get("now_time", ""))}</span>'
+        f'<span class="mono-data" style="position:absolute;left:{left};top:5px;'
+        'padding-left:6px;font-size:var(--text-2xs);color:var(--text-tertiary);'
+        'white-space:nowrap">FORECAST →</span>'
+        '<span class="mono-data" style="position:absolute;left:4px;top:76%;'
+        'font-size:var(--text-2xs);color:var(--text-tertiary)">VOLUME</span>'
+        '<div style="position:absolute;left:0;right:0;bottom:0;height:16px">'
+        f'{times}</div></div>'
+        f'<div class="fa-axis">{axis}</div></div>')
+
+
+def _chart_empty(data: dict) -> str:
+    err = data.get("error")
+    if err:
+        return _error_state(err)
+    return (
+        '<div style="display:flex;flex-direction:column;align-items:center;gap:8px;'
+        'padding:52px 16px;background:var(--bg-sunken)">'
+        '<span class="mono-data" style="font-size:var(--text-2xl);'
+        'color:var(--text-disabled)">▱</span>'
+        f'<span style="{STYRENE};font-size:var(--text-md);color:var(--text-secondary)">'
+        'No forecast issued</span>'
+        '<span style="font-size:var(--text-xs);color:var(--text-tertiary);'
+        'text-align:center;max-width:340px;text-wrap:pretty">'
+        'Pick a model and press Forecast. The result is frozen at issue and '
+        'archived before it is drawn.</span></div>')
+
+
+def _error_state(err: dict) -> str:
+    """The designed failure states: quota, load failure, rejected enrollment."""
+    kind = err.get("kind", "load_failure")
+    glyph = {"quota": "⚠", "load_failure": "✕", "enroll": "✕",
+             "no_data": "∅"}.get(kind, "✕")
+    color = {"quota": "var(--mute-orange)"}.get(kind, "var(--fin-down)")
+    extra = ""
+    if kind == "quota":
+        extra = (f'<a href="{a(err.get("login_url", "#"))}" '
+                 'style="font-family:var(--font-mono);font-size:var(--text-2xs)">'
+                 'SIGN IN ↗</a>')
+    elif kind == "load_failure":
+        # A model that will not load on this hardware is not always a bug in
+        # the Space: duplicating it gives the user a box they control.
+        extra = (f'<a href="{a(err.get("duplicate_url", "#"))}" target="_blank" '
+                 'rel="noopener" style="font-family:var(--font-mono);'
+                 'font-size:var(--text-2xs)">DUPLICATE THIS SPACE ↗</a>')
+    return (
+        '<div style="display:flex;flex-direction:column;align-items:center;gap:9px;'
+        'padding:44px 16px;background:var(--bg-sunken)">'
+        f'<span class="mono-data" style="font-size:var(--text-2xl);color:{a(color)}">'
+        f'{e(glyph)}</span>'
+        f'<span style="{STYRENE};font-size:var(--text-md);color:var(--text-secondary)">'
+        f'{e(err.get("title", "Forecast failed"))}</span>'
+        '<span style="font-size:var(--text-xs);color:var(--text-tertiary);'
+        'text-align:center;max-width:420px;text-wrap:pretty">'
+        f'{e(err.get("message", ""))}</span>'
+        f'<div style="display:flex;gap:10px;align-items:center">{extra}'
+        f'<button {bit("dismiss", "error")} style="padding:3px 9px;'
+        'background:transparent;border:1px solid var(--border-default);'
+        'color:var(--text-secondary);cursor:pointer;font-family:var(--font-mono);'
+        'font-size:var(--text-2xs)">DISMISS</button></div></div>')
+
+
+# --------------------------------------------------------------------------
+# Track record
+# --------------------------------------------------------------------------
+
+
+def trackrecord_section(state: dict, data: dict) -> str:
+    mode = state["mode"]
+    slugs = state["selected"]
+    scope = (f'{state["asset"]} · {state["tf"]} · H+{state["horizon"]} · '
+             f'LAST {view.THUMBS} RESOLVED').upper()
+
+    if mode == "matchup" and len(slugs) > 1:
+        question = "Same stats, side by side — best in row highlighted."
+        body = _scoreboard(state, data)
+    else:
+        primary = slugs[0] if slugs else None
+        panel = data["panels"].get(primary, {})
+        name = data["models_by_slug"].get(primary, {}).get("name", primary or "")
+        question = f"How wrong has {name} been here recently?"
+        body = _empty_record() if panel.get("empty", True) else _playground_record(panel, data)
+
+    return (
+        f'<section style="{PANEL}">'
+        '<div style="display:flex;align-items:center;gap:10px;padding:8px 12px;'
+        'border-bottom:1px solid var(--border-default);'
+        'border-left:3px solid var(--accent-amber);flex-wrap:wrap">'
+        f'<span style="{STYRENE};font-size:var(--text-md)">Track record</span>'
+        f'<span style="color:var(--text-secondary);font-size:var(--text-xs)">'
+        f'{e(question)}</span>'
+        f'<span class="mono-data" style="font-size:var(--text-2xs);'
+        f'color:var(--text-tertiary);margin-left:auto">{e(scope)}</span></div>'
+        f'{body}</section>')
+
+
+def _empty_record() -> str:
+    return (
+        '<div style="display:flex;flex-direction:column;align-items:center;gap:8px;'
+        'padding:26px 16px">'
+        '<span class="mono-data" style="font-size:var(--text-2xl);'
+        'color:var(--text-disabled)">∅</span>'
+        f'<span style="{STYRENE};font-size:var(--text-md);color:var(--text-secondary)">'
+        'No history yet</span>'
+        '<span style="font-size:var(--text-xs);color:var(--text-tertiary);'
+        'text-align:center;max-width:340px;text-wrap:pretty">Forecasts made here start '
+        'the record. The first resolved forecast for this model, asset and timeframe '
+        'appears in this panel.</span>'
+        f'<button {bit("run", "go")} style="margin-top:2px;padding:4px 9px;'
+        'background:transparent;border:1px solid var(--border-default);'
+        'color:var(--text-secondary);cursor:pointer;font-family:var(--font-mono);'
+        'font-size:var(--text-2xs)">MAKE THE FIRST FORECAST →</button></div>')
+
+
+def _playground_record(panel: dict, data: dict) -> str:
+    stats = [
+        ("Empirical 80% coverage", pct(panel.get("coverage")),
+         f'target 80% · {count(panel.get("resolved"))} resolved',
+         panel.get("verdict_color", "var(--text-primary)")),
+        ("Median abs error", pct(panel.get("median_err", 0) / 100
+                                 if panel.get("median_err") is not None else None, 2),
+         "at horizon close", "var(--text-primary)"),
+        ("Mean band width", pct(panel.get("width"), 1),
+         "10→90 span, % of price", "var(--text-primary)"),
+        ("Backfilled share", pct(panel.get("backfilled_share")),
+         "labelled in the record", "var(--mute-blue)"),
+    ]
+    stat_html = "".join(
+        '<div style="padding:9px 12px;border-right:1px solid var(--border-subtle)">'
+        f'<div style="{STYRENE};font-weight:300;font-size:var(--text-2xs);'
+        f'letter-spacing:var(--tracking-wider);color:var(--text-tertiary)">{e(label)}</div>'
+        f'<div class="mono-data" style="font-size:var(--text-xl);line-height:1.2;'
+        f'color:{a(color)}">{e(value)}</div>'
+        f'<div style="font-size:var(--text-2xs);color:var(--text-tertiary)">{e(note)}</div>'
+        '</div>'
+        for label, value, note, color in stats)
+
+    cells = "".join(_thumb(t, data) for t in panel.get("thumbs", []))
+    vcolor = panel.get("verdict_color", "var(--text-tertiary)")
+
+    return (
+        '<div><div style="display:grid;'
+        'grid-template-columns:repeat(auto-fit,minmax(168px,1fr));'
+        f'border-bottom:1px solid var(--border-default)">{stat_html}</div>'
+        f'<div class="fa-trstrip">{cells}</div>'
+        '<div style="display:flex;align-items:center;gap:10px;padding:7px 12px;'
+        'border-top:1px solid var(--border-subtle);background:var(--bg-raised);'
+        'flex-wrap:wrap">'
+        f'<span class="mono-data" style="font-size:var(--text-xs);'
+        f'color:{a(vcolor)};border:1px solid {a(vcolor)};padding:2px 7px">'
+        f'{e(panel.get("verdict", ""))}</span>'
+        '<span style="font-size:var(--text-xs);color:var(--text-secondary);'
+        f'text-wrap:pretty">{e(_verdict_note(panel))}</span>'
+        f'<a href="{a(data.get("store_url", "#"))}" target="_blank" rel="noopener" '
+        'style="margin-left:auto;font-family:var(--font-mono);font-size:var(--text-2xs);'
+        f'white-space:nowrap">ALL {e(count(panel.get("total")))} ARCHIVED ↗</a>'
+        '</div></div>')
+
+
+def _verdict_note(panel: dict) -> str:
+    coverage = panel.get("coverage")
+    if coverage is None:
+        return ("Not enough resolved forecasts here to say anything about "
+                "calibration yet.")
+    gap = coverage - config.NOMINAL_COVERAGE
+    if abs(gap) <= 0.05:
+        return ("Bands hold up on this pair: the realized path stayed inside the "
+                "80% envelope about as often as it should.")
+    if gap < 0:
+        return ("Bands are narrower than the realized error justifies here. "
+                "Read the median, not the confidence.")
+    return ("Bands are wider than the realized error justifies here — the model "
+            "is hedging more than this pair has needed.")
+
+
+def _thumb(t: dict, data: dict) -> str:
+    spark = t["spark"]
+    backfill = ('<span class="pixel-text" style="color:var(--mute-blue);'
+                'margin-left:auto">BACKFILL</span>' if t["backfilled"] else "")
+    return (
+        f'<div class="fa-trcell{" miss" if t["miss"] else ""}">'
+        '<div style="display:flex;align-items:center;gap:5px">'
+        f'<span class="mono-data" style="font-size:var(--text-2xs);'
+        f'color:var(--text-tertiary)">{e(t["date"])}</span>'
+        f'<span class="mono-data" style="font-size:var(--text-xs);'
+        f'color:{a(t["hit_color"])};margin-left:auto">{e(t["hit"])}</span></div>'
+        '<svg width="94" height="38" viewBox="0 0 94 38" style="display:block">'
+        f'<path d="{a(spark["band"])}" fill="var(--accent-amber-strong)" opacity="0.2"></path>'
+        f'<path d="{a(spark["mid"])}" fill="none" stroke="var(--accent-amber-strong)" '
+        'stroke-width="1.2" stroke-dasharray="3 2"></path>'
+        f'<path d="{a(spark["real"])}" fill="none" stroke="var(--text-primary)" '
+        'stroke-width="1.4"></path></svg>'
+        '<div style="display:flex;align-items:center;gap:4px">'
+        f'<span class="mono-data" style="font-size:var(--text-2xs);'
+        f'color:var(--text-secondary)">{e(t["err"])}</span>{backfill}</div></div>')
+
+
+def _scoreboard(state: dict, data: dict) -> str:
+    """The matchup table: same stats, aligned, best in row highlighted."""
+    slugs = [s for s in state["selected"] if s in data["panels"]]
+    if not slugs:
+        return _empty_record()
+    panels = [data["panels"][s] for s in slugs]
+    cols = f'1.15fr repeat({len(slugs)},minmax(0,1fr))'
+
+    heads = "".join(
+        '<div style="padding:7px 12px;border-right:1px solid var(--border-subtle);'
+        f'border-top:3px solid {a(chart.series_color(i))};display:flex;'
+        'align-items:center;gap:7px">'
+        f'<span style="{STYRENE};font-size:var(--text-sm);white-space:nowrap;'
+        'overflow:hidden;text-overflow:ellipsis">'
+        f'{e(data["models_by_slug"].get(s, {}).get("name", s))}</span>'
+        f'<span class="mono-data" style="font-size:var(--text-xs);'
+        f'color:{a(grade_color(p.get("grade", "-")))};'
+        f'border:1px solid {a(grade_color(p.get("grade", "-")))};'
+        f'padding:1px 5px;margin-left:auto">{e(p.get("grade", "-"))}</span></div>'
+        for i, (s, p) in enumerate(zip(slugs, panels)))
+
+    # (label, hint, value fn, "best" fn or None). Coverage is scored on
+    # distance from nominal, not on being highest -- a narrower band is not a
+    # better one, and the design says so on the page.
+    rows = [
+        ("80% band coverage", "TARGET 80%",
+         lambda p: pct(p.get("coverage")),
+         lambda p: (-abs(p["coverage"] - config.NOMINAL_COVERAGE)
+                    if p.get("coverage") is not None else None)),
+        ("Median abs error", "LOWER BETTER",
+         lambda p: pct(p["median_err"] / 100 if p.get("median_err") is not None else None, 2),
+         lambda p: (-p["median_err"] if p.get("median_err") is not None else None)),
+        ("Mean band width", "CONTEXT ONLY",
+         lambda p: pct(p.get("width"), 1), None),
+        ("Resolved forecasts", "SAMPLE SIZE",
+         lambda p: count(p.get("resolved")),
+         lambda p: p.get("resolved")),
+        ("Calibration verdict", "FROM RESOLVED ONLY",
+         lambda p: p.get("verdict", DASH), None),
+    ]
+
+    body = []
+    for label, hint, value_of, best_of in rows:
+        best_index = None
+        if best_of is not None:
+            scored = [(i, best_of(p)) for i, p in enumerate(panels)]
+            scored = [(i, v) for i, v in scored if v is not None]
+            if scored:
+                best_index = max(scored, key=lambda kv: kv[1])[0]
+        cells = []
+        for i, p in enumerate(panels):
+            is_best = i == best_index
+            fg = ("var(--accent-moss-strong)" if is_best else "var(--text-primary)")
+            if label.startswith("Calibration"):
+                fg = p.get("verdict_color", "var(--text-primary)")
+            cells.append(
+                '<div style="padding:7px 12px;border-right:1px solid var(--border-subtle);'
+                f'background:{"var(--bg-raised)" if is_best else "transparent"};'
+                'display:flex;align-items:center;gap:7px">'
+                f'<span class="mono-data" style="font-size:var(--text-md);'
+                f'color:{a(fg)}">{e(value_of(p))}</span>'
+                '<span class="mono-data" style="font-size:var(--text-2xs);'
+                f'color:var(--text-tertiary);margin-left:auto">{"BEST" if is_best else ""}</span>'
+                '</div>')
+        body.append(
+            f'<div style="display:grid;grid-template-columns:{cols};'
+            'border-bottom:1px solid var(--border-subtle)">'
+            '<div style="padding:7px 12px;border-right:1px solid var(--border-subtle);'
+            'display:flex;flex-direction:column;gap:1px">'
+            f'<span style="{STYRENE};font-weight:300;font-size:var(--text-xs);'
+            f'color:var(--text-secondary)">{e(label)}</span>'
+            f'<span class="pixel-text" style="color:var(--text-tertiary)">{e(hint)}</span>'
+            f'</div>{"".join(cells)}</div>')
+
+    return (
+        f'<div><div style="display:grid;grid-template-columns:{cols};'
+        'border-bottom:1px solid var(--border-default);background:var(--bg-raised)">'
+        '<div style="padding:7px 12px;border-right:1px solid var(--border-subtle)">'
+        '<span class="pixel-text" style="color:var(--text-tertiary)">METRIC</span></div>'
+        f'{heads}</div>{"".join(body)}'
+        '<div style="display:flex;align-items:center;gap:10px;padding:7px 12px;'
+        'background:var(--bg-raised);flex-wrap:wrap">'
+        '<span class="pixel-text" style="color:var(--accent-amber-strong)">i</span>'
+        '<span style="font-size:var(--text-xs);color:var(--text-secondary);'
+        'text-wrap:pretty">Highlighted cell is best in row. Coverage closest to 80% '
+        'wins — a narrower band is not a better one.</span></div></div>')
+
+
+# --------------------------------------------------------------------------
+# Rail
+# --------------------------------------------------------------------------
+
+
+def rail(state: dict, data: dict) -> str:
+    return ('<aside class="fa-rail">'
+            f'{_standings(state, data)}{_volatility(data)}{_log(state, data)}'
+            f'{_extend(state, data)}{_enroll(state, data)}</aside>')
+
+
+def _standings(state: dict, data: dict) -> str:
+    rows = data.get("standings_rows", [])
+    enrolled = len(data.get("models", []))
+
+    tabs = "".join(
+        f'<button {bit("cls", c)} style="flex:1 1 auto;padding:4px 5px;'
+        f'background:{"var(--bg-raised)" if state["cls"] == c else "transparent"};'
+        'border:0;border-right:1px solid var(--border-subtle);'
+        f'color:{"var(--accent-amber-strong)" if state["cls"] == c else "var(--text-tertiary)"};'
+        f'{STYRENE};font-size:var(--text-2xs);cursor:pointer">{e(c)}</button>'
+        for c in ("All", "Crypto", "Equities"))
+
+    if rows:
+        body = "".join(
+            f'<button {bit("stand", r["slug"])} class="fa-stand'
+            f'{" on" if r["selected"] else ""}" '
+            f'style="border-left-color:{a(chart.series_color(0)) if r["selected"] else "transparent"}">'
+            f'<span class="mono-data" style="font-size:var(--text-2xs);'
+            f'color:var(--text-tertiary);flex:0 0 auto">{e(r["rank"])}</span>'
+            '<span class="fa-stand-mid">'
+            f'<span class="mono-data fa-stand-name">{e(r["name"])}</span>'
+            f'<span class="pixel-text" style="color:var(--text-tertiary)">{e(r["meta"])}</span>'
+            '</span>'
+            f'<span class="mono-data" style="font-size:var(--text-md);'
+            f'color:{a(r["grade_color"])};flex:0 0 auto">{e(r["grade"])}</span></button>'
+            for r in rows)
+    else:
+        body = ('<div style="padding:18px 10px;text-align:center">'
+                '<span style="font-size:var(--text-xs);color:var(--text-tertiary);'
+                'text-wrap:pretty">No forecasts have resolved yet. Standings appear '
+                'once the resolver has outcomes to score.</span></div>')
+
+    right = ('<span class="mono-data" style="font-size:var(--text-2xs);'
+             f'color:var(--text-tertiary);margin-left:auto">{enrolled} ENROLLED</span>')
+
+    return (
+        f'<div style="{PANEL}">'
+        f'{_panel_title("Arena standings", right)}'
+        f'<div style="display:flex;border-bottom:1px solid var(--border-subtle)">{tabs}</div>'
+        f'{body}'
+        '<div style="padding:6px 10px;display:flex;align-items:center">'
+        '<span class="pixel-text" style="color:var(--text-tertiary)">'
+        'GRADES FROM RESOLVED FORECASTS ONLY</span>'
+        f'<a href="{a(data.get("standings_url", "#"))}" target="_blank" rel="noopener" '
+        'style="margin-left:auto;font-family:var(--font-mono);font-size:var(--text-2xs)">'
+        'FULL TABLE ↗</a></div></div>')
+
+
+def _volatility(data: dict) -> str:
+    vol = data.get("volatility") or {}
+    rows = vol.get("rows", [])
+    if not rows:
+        return ""
+    body = "".join(
+        '<div style="display:flex;flex-direction:column;gap:4px">'
+        '<div style="display:flex;align-items:center;gap:8px">'
+        f'<span style="{STYRENE};font-weight:300;font-size:var(--text-2xs);'
+        f'color:var(--text-secondary)">{e(r["label"])}</span>'
+        f'<span class="mono-data" style="font-size:var(--text-xs);'
+        f'color:{a(r["fg"])};margin-left:auto">{e(r["value"])}</span></div>'
+        '<div style="height:5px;background:var(--bg-sunken);'
+        'border:1px solid var(--border-subtle);position:relative;overflow:hidden">'
+        f'<div style="position:absolute;left:0;top:0;bottom:0;width:{a(r["pct"])};'
+        f'background:{a(r["fg"])}"></div></div></div>'
+        for r in rows)
+    right = ('<span class="mono-data" style="font-size:var(--text-2xs);'
+             f'color:var(--text-tertiary);margin-left:auto">{e(vol.get("verdict", ""))}</span>')
+    return (
+        f'<div style="{PANEL}">{_panel_title("Volatility read", right)}'
+        '<div style="padding:10px;display:flex;flex-direction:column;gap:9px">'
+        f'{body}'
+        '<span style="font-size:var(--text-2xs);color:var(--text-tertiary);'
+        f'text-wrap:pretty">{e(vol.get("note", ""))}</span></div></div>')
+
+
+def _log(state: dict, data: dict) -> str:
+    entries = state.get("log", [])[:view.LOG_LIMIT]
+    if entries:
+        body = "".join(
+            '<div style="display:flex;align-items:center;gap:8px;padding:6px 10px;'
+            'border-bottom:1px solid var(--border-subtle)">'
+            f'<span class="mono-data" style="font-size:var(--text-2xs);'
+            f'color:var(--text-tertiary);flex:0 0 auto">{e(l["time"])}</span>'
+            '<span class="fa-stand-mid">'
+            f'<span class="mono-data fa-stand-name">{e(l["name"])}</span>'
+            f'<span class="pixel-text" style="color:var(--text-tertiary)">{e(l["meta"])}</span>'
+            '</span>'
+            f'<button {bit("reopen", l["id"])} style="background:transparent;border:0;'
+            'color:var(--accent-amber-strong);cursor:pointer;font-family:var(--font-mono);'
+            'font-size:var(--text-2xs);flex:0 0 auto">RE-OPEN</button></div>'
+            for l in entries)
+    else:
+        body = ('<div style="padding:14px 10px">'
+                '<span style="font-size:var(--text-xs);color:var(--text-tertiary)">'
+                'Forecasts you issue this session appear here.</span></div>')
+    right = ('<span class="mono-data" style="font-size:var(--text-2xs);'
+             'color:var(--text-tertiary);margin-left:auto">THIS SESSION</span>')
+    return (
+        f'<div style="{PANEL}">{_panel_title("Forecast log", right)}{body}'
+        '<div style="padding:6px 10px">'
+        '<span class="pixel-text" style="color:var(--text-tertiary)">'
+        'ARCHIVED IMMUTABLY · SEED + CONFIG SAVED</span></div></div>')
+
+
+def _extend(state: dict, data: dict) -> str:
+    cov = data.get("coverage") or {}
+    pct_label = cov.get("pct_label", DASH)
+    width = cov.get("pct_width", "0%")
+    rows = "".join(
+        '<div style="display:flex;align-items:center;gap:8px">'
+        f'<span class="pixel-text" style="color:var(--text-tertiary)">{e(label)}</span>'
+        f'<span class="mono-data" style="font-size:var(--text-2xs);'
+        f'color:var(--text-secondary);margin-left:auto">{e(value)}</span></div>'
+        for label, value in cov.get("rows", []))
+
+    label = ("Backfill queued" if state.get("backfill_requested")
+             else "Contribute a backfill run (uses your quota)")
+    return (
+        f'<div style="{PANEL}">{_panel_title("Extend the record")}'
+        '<div style="padding:10px;display:flex;flex-direction:column;gap:8px">'
+        '<div style="display:flex;align-items:center;gap:8px">'
+        f'<span style="font-size:var(--text-xs);color:var(--text-secondary)">'
+        f'{e(cov.get("scope", ""))}</span>'
+        f'<span class="mono-data" style="font-size:var(--text-md);'
+        f'color:var(--accent-amber-strong);margin-left:auto">{e(pct_label)}</span></div>'
+        '<div style="height:6px;background:var(--bg-sunken);'
+        'border:1px solid var(--border-subtle);position:relative;overflow:hidden">'
+        f'<div style="position:absolute;left:0;top:0;bottom:0;width:{a(width)};'
+        'background:var(--accent-amber)"></div></div>'
+        f'<div style="display:flex;flex-direction:column;gap:3px">{rows}</div>'
+        f'<button {bit("backfill", "run")} style="width:100%;padding:6px;'
+        'background:transparent;border:1px solid var(--border-default);'
+        f'color:var(--text-secondary);cursor:pointer;{STYRENE};'
+        f'font-size:var(--text-xs)">{e(label)}</button>'
+        '<span class="pixel-text" style="color:var(--text-tertiary)">'
+        'BACKFILLED ENTRIES ARE LABELLED IN THE RECORD</span></div></div>')
+
+
+def _enroll(state: dict, data: dict) -> str:
+    note = state.get("enroll_note") or "A smoke test runs before a model is enrolled"
+    ok = state.get("enroll_ok")
+    color = ("var(--accent-moss-strong)" if ok else
+             "var(--fin-down)" if ok is False else "var(--text-tertiary)")
+
+    families = "".join(
+        f'<button {bit("family", f)} class="fa-pill'
+        f'{" on" if state.get("family") == f else ""}" '
+        f'style="font-size:var(--text-2xs)">{e(f)}</button>'
+        for f in data.get("families", ()))
+
+    return (
+        f'<div style="{PANEL}">{_panel_title("Enroll a model")}'
+        '<div style="padding:10px;display:flex;flex-direction:column;gap:8px">'
+        f'<input value="{a(state.get("hfid", ""))}" '
+        f'data-bit-input="hfid" placeholder="author/model-name" '
+        'style="width:100%;padding:5px 7px;background:var(--bg-sunken);'
+        'border:1px solid var(--border-default);outline:none;'
+        'font-family:var(--font-mono);font-size:var(--text-xs);'
+        'color:var(--text-primary)" />'
+        f'<div style="display:flex;gap:4px;flex-wrap:wrap">{families}</div>'
+        '<div style="display:flex;align-items:center;gap:7px">'
+        f'<button {bit("enroll", "run")} style="padding:5px 10px;'
+        'background:transparent;border:1px solid var(--border-default);'
+        f'color:var(--text-secondary);cursor:pointer;{STYRENE};'
+        'font-size:var(--text-xs)">Smoke-test</button></div>'
+        f'<span class="mono-data" style="font-size:var(--text-2xs);'
+        f'color:{a(color)};text-wrap:pretty">{e(note)}</span>'
+        '<span style="font-size:var(--text-2xs);color:var(--text-tertiary);'
+        'text-wrap:pretty">Only models loadable through a vetted adapter family are '
+        'accepted. No user-supplied code is ever executed.</span></div></div>')
+
+
+# --------------------------------------------------------------------------
+# Footer
+# --------------------------------------------------------------------------
+
+
+def methodology(data: dict) -> str:
+    return (
+        '<div style="display:flex;align-items:flex-start;gap:10px;padding:9px 12px;'
+        'border:1px solid var(--border-subtle);background:var(--bg-panel)">'
+        '<span class="pixel-text" style="color:var(--accent-amber-strong);'
+        'flex:0 0 auto;margin-top:2px">i</span>'
+        '<span style="font-size:var(--text-xs);color:var(--text-secondary);'
+        'text-wrap:pretty">Forecasts are frozen at issue and never revised; quantiles '
+        'from N sampled paths where applicable; seeds shown; backfilled entries '
+        'labelled; grades computed from resolved forecasts only. Nothing here is '
+        'financial advice.</span>'
+        f'<a href="{a(data.get("methodology_url", "#"))}" target="_blank" rel="noopener" '
+        'style="margin-left:auto;font-family:var(--font-mono);font-size:var(--text-2xs);'
+        'white-space:nowrap;flex:0 0 auto">METHODOLOGY ↗</a></div>')
+
+
+def footer(data: dict) -> str:
+    nav = data.get("nav") or {}
+    products = [i.get("name", "") for i in nav.get("items", [])][:12]
+    prod_html = "".join(
+        f'<span style="color:var(--text-secondary);font-size:var(--text-xs)">{e(p)}</span>'
+        for p in products)
+    resources = "".join(
+        f'<a href="{a(url)}" target="_blank" rel="noopener" '
+        f'style="color:var(--text-secondary);font-size:var(--text-xs)">{e(label)}</a>'
+        for label, url in data.get("footer_resources", ()))
+
+    return (
+        f'<footer style="{PANEL}">'
+        '<div class="fa-foot">'
+        '<div style="padding:14px;border-right:1px solid var(--border-subtle)">'
+        f'<div style="{STYRENE};font-size:var(--text-2xs);'
+        'letter-spacing:var(--tracking-wider);color:var(--text-tertiary);'
+        'margin-bottom:8px">Products</div>'
+        '<div style="display:grid;grid-template-columns:1fr 1fr;gap:3px 12px">'
+        f'{prod_html}</div></div>'
+        '<div style="padding:14px;border-right:1px solid var(--border-subtle)">'
+        f'<div style="{STYRENE};font-size:var(--text-2xs);'
+        'letter-spacing:var(--tracking-wider);color:var(--text-tertiary);'
+        'margin-bottom:8px">Resources</div>'
+        '<div style="display:flex;flex-direction:column;gap:3px">'
+        f'{resources}</div></div>'
+        '<div style="padding:14px;border-right:1px solid var(--border-subtle)">'
+        f'<div style="{STYRENE};font-size:var(--text-2xs);'
+        'letter-spacing:var(--tracking-wider);color:var(--text-tertiary);'
+        'margin-bottom:8px">Method</div>'
+        '<div style="display:flex;flex-direction:column;gap:3px">'
+        '<span style="color:var(--text-secondary);font-size:var(--text-xs)">'
+        'Frozen at issue</span>'
+        '<span style="color:var(--text-secondary);font-size:var(--text-xs)">'
+        'Seeded and reproducible</span>'
+        '<span style="color:var(--text-secondary);font-size:var(--text-xs)">'
+        'Backfill labelled</span>'
+        '<span style="color:var(--text-secondary);font-size:var(--text-xs)">'
+        'Graded on resolved only</span></div></div>'
+        '<div style="padding:14px;background:var(--bg-raised)">'
+        '<div style="display:flex;align-items:center;gap:6px;margin-bottom:8px">'
+        '<span class="pixel-text" style="color:var(--accent-amber-strong)">⚠</span>'
+        f'<span style="{STYRENE};font-size:var(--text-2xs);'
+        'letter-spacing:var(--tracking-wider);color:var(--accent-amber-strong)">'
+        'Disclaimer</span></div>'
+        '<div class="styrene-text" style="font-size:var(--text-xs);'
+        'text-transform:uppercase;letter-spacing:var(--tracking-wide);'
+        'color:var(--text-secondary);line-height:var(--leading-normal);'
+        'text-wrap:pretty">The Bit Trading Company publishes research tools and '
+        'educational software. Nothing here is financial advice. Forecasts are model '
+        'output, not predictions. Past performance does not predict future results.'
+        '</div></div></div>'
+        '<div style="display:flex;align-items:center;gap:14px;padding:8px 14px;'
+        'border-top:1px solid var(--border-subtle);flex-wrap:wrap">'
+        '<span style="display:inline-block;width:6px;height:6px;background:var(--fin-up);'
+        'animation:bitPulse 2s ease-in-out infinite"></span>'
+        '<span class="mono-data" style="font-size:var(--text-2xs);'
+        f'color:var(--text-tertiary)">{e(data.get("status_line", ""))}</span>'
+        '<span class="mono-data" style="font-size:var(--text-2xs);'
+        'color:var(--text-tertiary);margin-left:auto">'
+        '© 2026 THE BIT TRADING COMPANY</span></div></footer>')
+
+
+# --------------------------------------------------------------------------
+# The page
+# --------------------------------------------------------------------------
+
+
+def page(state: dict, data: dict) -> str:
+    """The whole document body, from state. Pure -- no I/O anywhere below."""
+    return (
+        '<div class="bit-root" style="background:var(--bg-canvas);'
+        'color:var(--text-primary);display:flex;align-items:stretch;'
+        'font-family:var(--font-body);font-size:var(--text-base)">'
+        f'{sidebar.render(data.get("nav") or {}, active="Forecast Arena", emit=emit)}'
+        '<div style="flex:1 1 auto;min-width:0;display:flex;flex-direction:column">'
+        f'{header(state, data)}'
+        '<main style="flex:1 1 auto;min-width:0;padding:12px;display:flex;'
+        'flex-direction:column;gap:12px">'
+        f'{title_row(state, data)}'
+        f'{stats_bar(data.get("stats", []))}'
+        f'{models_section(state, data)}'
+        f'{controls(state, data)}'
+        '<div class="fa-zones">'
+        '<div class="fa-main">'
+        f'{chart_section(state, data)}'
+        f'{trackrecord_section(state, data)}'
+        '</div>'
+        f'{rail(state, data)}'
+        '</div>'
+        f'{methodology(data)}'
+        f'{footer(data)}'
+        '</main></div></div>')

src/view.py

@@ -0,0 +1,396 @@
+"""State, and the derivations the UI renders from.
+
+The whole UI is a pure function of the dict `default_state()` returns. Actions
+fold that dict forward; the renderer turns it into markup. Nothing in the view
+layer reaches for a model, a store or a clock, which is what lets the entire
+interface be tested without a browser or a network.
+
+Numbers that do not exist render as an em dash, never as `0.00`. A model with
+no resolved forecasts has no coverage -- saying `0%` would claim it was wrong
+every time, which is the opposite of the truth.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from . import config
+from .store import now_utc
+from .trackrecord import grade_for
+
+DASH = "—"
+
+MAX_MATCHUP = 3
+LOG_LIMIT = 8
+THUMBS = 10
+
+
+def default_state() -> dict:
+    return {
+        "mode": "playground",
+        "selected": [],            # filled at boot from the registry
+        "asset": "BTC-USD",
+        "tf": "1h",
+        "horizon": config.DEFAULT_HORIZON["1h"],
+        "ghosts": True,
+        "gear": False,
+        "cls": "All",
+        "seed": 42,
+        "n_samples": config.DEFAULT_N_SAMPLES,
+        "hfid": "",
+        "family": "kronos",
+        "enroll_note": "",
+        "enroll_ok": None,
+        "log": [],
+        "error": None,
+        "session_forecasts": 0,
+        "signed_in": False,
+        "user": "",
+        "backfill_requested": False,
+        "nonce": "",
+    }
+
+
+# --------------------------------------------------------------------------
+# Formatting
+# --------------------------------------------------------------------------
+
+
+def pct(value, digits: int = 0) -> str:
+    if value is None or (isinstance(value, float) and not np.isfinite(value)):
+        return DASH
+    return f"{value * 100:.{digits}f}%"
+
+
+def num(value, digits: int = 2) -> str:
+    if value is None or (isinstance(value, float) and not np.isfinite(value)):
+        return DASH
+    return f"{value:,.{digits}f}"
+
+
+def count(value) -> str:
+    if value is None:
+        return DASH
+    return f"{int(value):,}"
+
+
+def grade_color(grade: str) -> str:
+    head = (grade or "")[:1]
+    if head == "A":
+        return "var(--accent-moss-strong)"
+    if head == "B":
+        return "var(--accent-amber-strong)"
+    if head in ("C", "D"):
+        return "var(--mute-orange)"
+    return "var(--text-tertiary)"
+
+
+def verdict_for(coverage, resolved: int) -> tuple[str, str, str]:
+    """(chip, short, colour) describing a model's calibration in words.
+
+    The wording is deliberately unflattering where the data is unflattering: a
+    model whose bands are too narrow is called overconfident on the page, not
+    in a footnote.
+    """
+    if resolved < config.MIN_RESOLVED_FOR_GRADE or coverage is None:
+        return ("NOT YET GRADED", "too few resolved", "var(--text-tertiary)")
+    gap = coverage - config.NOMINAL_COVERAGE
+    if abs(gap) <= 0.05:
+        return ("WELL CALIBRATED", "bands match reality", "var(--accent-moss-strong)")
+    if gap < -0.15:
+        return ("OVERCONFIDENT · BANDS TOO NARROW",
+                f"runs {abs(gap) * 100:.0f}pts under", "var(--mute-orange)")
+    if gap < 0:
+        return ("SLIGHTLY OVERCONFIDENT",
+                f"runs {abs(gap) * 100:.0f}pts under", "var(--accent-amber-strong)")
+    if gap > 0.15:
+        return ("UNDERCONFIDENT · BANDS TOO WIDE",
+                f"runs {gap * 100:.0f}pts over", "var(--mute-orange)")
+    return ("SLIGHTLY UNDERCONFIDENT",
+            f"runs {gap * 100:.0f}pts over", "var(--accent-amber-strong)")
+
+
+# --------------------------------------------------------------------------
+# Summaries
+# --------------------------------------------------------------------------
+
+
+class Summary:
+    """Precomputed per-(model, asset, timeframe) track record.
+
+    Built once at boot from the standings table and the resolved rows, so the
+    Track Record panel is an in-memory lookup rather than a parquet read on
+    every interaction.
+    """
+
+    def __init__(self, standings: pd.DataFrame, trackrecord: pd.DataFrame):
+        self.standings = standings if standings is not None else pd.DataFrame()
+        self.trackrecord = trackrecord if trackrecord is not None else pd.DataFrame()
+
+    def class_of(self, asset: str) -> str:
+        spec = config.ASSETS.get(asset)
+        return spec.asset_class if spec else "other"
+
+    def standing(self, model_slug: str, asset: str) -> dict:
+        """The standings row for this model in this asset's class."""
+        if not len(self.standings):
+            return {}
+        rows = self.standings[
+            (self.standings["model_slug"] == model_slug)
+            & (self.standings["asset_class"] == self.class_of(asset))]
+        return rows.iloc[0].to_dict() if len(rows) else {}
+
+    def scoped(self, model_slug: str, asset: str, timeframe: str) -> pd.DataFrame:
+        if not len(self.trackrecord):
+            return pd.DataFrame()
+        tr = self.trackrecord
+        return tr[(tr["model_slug"] == model_slug) & (tr["asset"] == asset)
+                  & (tr["timeframe"] == timeframe)]
+
+    def panel(self, model_slug: str, asset: str, timeframe: str,
+              horizon: int) -> dict:
+        """Everything the Track Record panel needs for one model."""
+        rows = self.scoped(model_slug, asset, timeframe)
+        stand = self.standing(model_slug, asset)
+        resolved = len(rows)
+
+        if resolved:
+            coverage = float(rows["inside_80"].mean())
+            median_err = float(rows["pct_error"].median())
+            width = float(((rows["q90"] - rows["q10"]).abs()
+                           / rows["realized_close"].abs()).median())
+            backfilled = float(rows["backfilled"].mean())
+        else:
+            coverage = median_err = width = backfilled = None
+
+        chip, short, color = verdict_for(coverage, resolved)
+        grade = stand.get("grade") or grade_for(
+            (coverage - config.NOMINAL_COVERAGE) if coverage is not None else None,
+            resolved)
+
+        return {
+            "empty": resolved == 0,
+            "resolved": resolved,
+            "coverage": coverage,
+            "median_err": median_err,
+            "width": width,
+            "backfilled_share": backfilled,
+            "grade": grade,
+            "grade_color": grade_color(grade),
+            "verdict": chip,
+            "verdict_short": short,
+            "verdict_color": color,
+            "thumbs": self.thumbs(rows, horizon),
+            "total": int(stand.get("resolved_count") or resolved),
+        }
+
+    def thumbs(self, rows: pd.DataFrame, horizon: int) -> list[dict]:
+        """The last ~10 resolved forecasts, as sparkline thumbnails."""
+        if not len(rows):
+            return []
+        out = []
+        # One thumbnail per forecast, newest first.
+        for fid, group in sorted(rows.groupby("forecast_id"),
+                                 key=lambda kv: kv[1]["issued_ts"].max(),
+                                 reverse=True)[:THUMBS]:
+            group = group.sort_values("step")
+            hit = bool(group["inside_80"].mean() >= 0.5)
+            err = float(group["pct_error"].median())
+            out.append({
+                "id": str(fid),
+                "date": pd.Timestamp(group["issued_ts"].iloc[0]).strftime("%m-%d %H:%M"),
+                "hit": "✓" if hit else "✕",
+                "hit_color": "var(--fin-up)" if hit else "var(--fin-down)",
+                "miss": not hit,
+                "err": f"{err:.2f}% ERR",
+                "backfilled": bool(group["backfilled"].any()),
+                "spark": _spark(group),
+            })
+        return out
+
+
+def _spark(group: pd.DataFrame) -> dict:
+    """Band, median and realised path as SVG paths in a 94x38 box."""
+    n = len(group)
+    if n < 2:
+        return {"band": "", "mid": "", "real": ""}
+    lo = group["q10"].to_numpy(dtype="float64")
+    hi = group["q90"].to_numpy(dtype="float64")
+    mid = group["q50"].to_numpy(dtype="float64")
+    real = group["realized_close"].to_numpy(dtype="float64")
+
+    floor = float(min(lo.min(), real.min()))
+    ceil = float(max(hi.max(), real.max()))
+    span = (ceil - floor) or 1.0
+
+    def xy(i, v):
+        return f"{6 + i * (82 / max(1, n - 1)):.1f} {35 - (v - floor) / span * 32:.1f}"
+
+    upper = [xy(i, hi[i]) for i in range(n)]
+    lower = [xy(i, lo[i]) for i in range(n)]
+    return {
+        "band": "M" + " L".join(upper) + " L" + " L".join(reversed(lower)) + " Z",
+        "mid": "M" + " L".join(xy(i, mid[i]) for i in range(n)),
+        "real": "M" + " L".join(xy(i, real[i]) for i in range(n)),
+    }
+
+
+# --------------------------------------------------------------------------
+# Volatility
+# --------------------------------------------------------------------------
+
+
+def volatility(run, history: pd.DataFrame, timeframe: str) -> dict:
+    """Forecast dispersion against trailing realised volatility.
+
+    For a path model the forecast figure is the standard deviation across
+    sampled paths; for a quantile-only model it is the band half-width. Those
+    are not the same statistic, and the label says which one is on screen
+    rather than quietly presenting them as comparable.
+    """
+    bars_per_day = 24 if timeframe == "1h" else 1
+    horizon_days = max(1.0, (run.horizon / bars_per_day)) if run else 1.0
+
+    # Before any forecast has been issued there is no history to read. An
+    # empty frame has no columns at all, so this guards on the column rather
+    # than on the length.
+    if history is None or "close" not in getattr(history, "columns", []):
+        return {"rows": [], "verdict": DASH, "note": "", "kind": ""}
+    close = history["close"].to_numpy(dtype="float64")
+    if len(close) < 10:
+        return {"rows": [], "verdict": DASH, "note": "", "kind": ""}
+
+    log_returns = np.diff(np.log(close))
+    # `a or b` on an array is a truthiness test, not a fallback. Slice widths
+    # are clamped explicitly instead.
+    recent_n = max(2, min(len(log_returns), int(bars_per_day)))
+    week_n = max(2, min(len(log_returns), int(bars_per_day * 7)))
+    realized_recent = float(np.std(log_returns[-recent_n:]))
+    realized_week = float(np.std(log_returns[-week_n:]))
+    scale = np.sqrt(bars_per_day)
+    realized_recent_d = realized_recent * scale
+    realized_week_d = realized_week * scale
+
+    if run is None:
+        forecast = None
+        kind = ""
+    else:
+        # Terminal dispersion, expressed per-day so it is comparable with the
+        # realised figures next to it.
+        forecast = float(run.result.dispersion()[-1]) / np.sqrt(horizon_days)
+        kind = ("SAMPLED-PATH DISPERSION"
+                if run.capabilities.get("output") == "ohlcv_paths"
+                else "BAND HALF-WIDTH")
+
+    peak = max(v for v in (forecast or 0, realized_recent_d, realized_week_d, 1e-9))
+    rows = [
+        {"label": f"Forecast-implied vol", "value": pct(forecast, 2) + " / 24H",
+         "pct": f"{min(100, (forecast or 0) / peak * 100):.0f}%",
+         "fg": "var(--accent-amber-strong)"},
+        {"label": "Realized vol · recent", "value": pct(realized_recent_d, 2) + " / 24H",
+         "pct": f"{min(100, realized_recent_d / peak * 100):.0f}%",
+         "fg": "var(--text-secondary)"},
+        {"label": "Realized vol · 7d avg", "value": pct(realized_week_d, 2) + " / 24H",
+         "pct": f"{min(100, realized_week_d / peak * 100):.0f}%",
+         "fg": "var(--text-tertiary)"},
+    ]
+
+    if forecast is None:
+        verdict, note = DASH, "Run a forecast to compare its dispersion with realised volatility."
+    else:
+        ratio = forecast / (realized_week_d or 1e-9)
+        if ratio > 1.15:
+            verdict = "FORECAST > REALIZED"
+            note = (f"{kind.capitalize()} is running {(ratio - 1) * 100:.0f}% above "
+                    f"trailing realised vol — this model is pricing a wider range "
+                    f"than the last week delivered.")
+        elif ratio < 0.85:
+            verdict = "FORECAST < REALIZED"
+            note = (f"{kind.capitalize()} is {(1 - ratio) * 100:.0f}% below trailing "
+                    f"realised vol — the bands are tighter than recent moves justify.")
+        else:
+            verdict = "FORECAST ≈ REALIZED"
+            note = (f"{kind.capitalize()} is close to trailing realised vol.")
+
+    return {"rows": rows, "verdict": verdict, "note": note, "kind": kind}
+
+
+# --------------------------------------------------------------------------
+# Headline stats
+# --------------------------------------------------------------------------
+
+
+def headline_stats(registry: dict, standings: pd.DataFrame,
+                   archived: int | None, resolved: int | None) -> list[dict]:
+    models = registry.get("models", {})
+    families = {m.get("family") for m in models.values() if m.get("family")}
+
+    best_label, best_note, best_color = DASH, "no graded models yet", "var(--text-primary)"
+    if standings is not None and len(standings):
+        graded = standings[standings["grade"] != "-"]
+        if len(graded):
+            best = graded.assign(_gap=graded["calibration_gap"].abs()) \
+                         .sort_values("_gap").iloc[0]
+            best_label = str(best["grade"])
+            best_note = (f"{best['model_slug']} · "
+                         f"{pct(float(best['coverage_80']))} coverage")
+            best_color = grade_color(best_label)
+
+    awaiting = None
+    if archived is not None and resolved is not None:
+        awaiting = max(0, archived - resolved)
+
+    return [
+        {"label": "Models enrolled", "value": count(len(models)),
+         "note": f"{len(families)} adapter families",
+         "mark": "var(--accent-amber)", "color": "var(--text-primary)"},
+        {"label": "Forecasts archived", "value": count(archived),
+         "note": "frozen at issue, never revised",
+         "mark": "var(--border-strong)", "color": "var(--text-primary)"},
+        {"label": "Resolved", "value": count(resolved),
+         "note": (f"{count(awaiting)} awaiting horizon" if awaiting is not None
+                  else "awaiting the first resolver run"),
+         "mark": "var(--border-strong)", "color": "var(--text-primary)"},
+        {"label": "Best calibrated", "value": best_label, "note": best_note,
+         "mark": "var(--accent-moss)", "color": best_color},
+    ]
+
+
+def standings_rows(standings: pd.DataFrame, registry: dict, cls: str,
+                   selected: list[str]) -> list[dict]:
+    """The rail's leaderboard, filtered by asset class."""
+    if standings is None or not len(standings):
+        return []
+    df = standings
+    if cls and cls != "All":
+        wanted = {"Crypto": "crypto", "Equities": "equity"}.get(cls, cls.lower())
+        df = df[df["asset_class"] == wanted]
+    if not len(df):
+        return []
+
+    # Rank by calibration first, then by how much evidence there is. A model
+    # with a perfect gap over 20 forecasts should not outrank one with a nearly
+    # perfect gap over two thousand.
+    df = df.assign(_gap=df["calibration_gap"].abs(),
+                   _graded=(df["grade"] != "-").astype(int))
+    df = df.sort_values(["_graded", "_gap", "resolved_count"],
+                        ascending=[False, True, False])
+
+    models = registry.get("models", {})
+    out = []
+    for i, (_, row) in enumerate(df.iterrows()):
+        slug = str(row["model_slug"])
+        entry = models.get(slug, {})
+        out.append({
+            "rank": f"{i + 1:02d}",
+            "slug": slug,
+            "name": entry.get("display", slug),
+            "grade": str(row["grade"]),
+            "grade_color": grade_color(str(row["grade"])),
+            "meta": (f"{count(row['resolved_count'])} RESOLVED · "
+                     f"{pct(float(row['coverage_80']))} COV · "
+                     f"{str(row['asset_class']).upper()}"),
+            "selected": slug in selected,
+        })
+    return out

tests/conftest.py

@@ -0,0 +1,34 @@
+"""Shared fixtures. Everything here runs offline with no credentials."""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+# No test may reach the Hub. Pointing the store at a temp dir is not enough --
+# a missing local file falls back to a download -- so `offline` is set on every
+# store the suite builds, and this is the belt to that pair of braces.
+os.environ.setdefault("HF_HUB_OFFLINE", "1")
+os.environ.pop("HF_TOKEN", None)
+os.environ.pop("HF_WRITE_TOKEN", None)
+
+
+@pytest.fixture
+def store(tmp_path):
+    from src.store import ArenaStore
+
+    return ArenaStore(repo_id=None, local_root=tmp_path / "store", offline=True)
+
+
+@pytest.fixture
+def context():
+    from tests.fixture import synth
+
+    return synth(400)

tests/fixture.py

@@ -0,0 +1,33 @@
+"""Synthetic market data with known statistics.
+
+A geometric random walk is used rather than a recorded price series because
+the coverage test needs a distribution whose true quantiles are known in
+closed form. Real prices would make that test a measurement of the market
+rather than of the arithmetic.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+
+def synth(n: int = 600, tf: str = "1h", seed: int = 7, s0: float = 50000.0,
+          sigma: float = 0.01, mu: float = 0.0) -> pd.DataFrame:
+    rng = np.random.default_rng(seed)
+    r = rng.normal(mu, sigma, n)
+    close = s0 * np.exp(np.cumsum(r))
+    openp = np.concatenate([[s0], close[:-1]])
+    hi = np.maximum(openp, close) * (1 + np.abs(rng.normal(0, sigma / 3, n)))
+    lo = np.minimum(openp, close) * (1 - np.abs(rng.normal(0, sigma / 3, n)))
+    vol = np.abs(rng.normal(1000, 200, n)) + 1.0
+    step = pd.Timedelta("1h") if tf == "1h" else pd.Timedelta("1d")
+    ts = pd.date_range("2025-01-01", periods=n, freq=step, tz="UTC")
+    return pd.DataFrame({"ts": ts, "open": openp, "high": hi, "low": lo,
+                         "close": close, "volume": vol})
+
+
+def future_ts(context: pd.DataFrame, horizon: int) -> pd.DatetimeIndex:
+    ts = pd.to_datetime(context["ts"], utc=True)
+    step = ts.diff().dropna().mode().iloc[0]
+    return pd.DatetimeIndex([ts.iloc[-1] + step * (i + 1) for i in range(horizon)])

tests/test_acceptance.py

@@ -0,0 +1,426 @@
+"""The acceptance suite.
+
+Each test here corresponds to a numbered promise the Arena makes about its own
+data. They are the gate on deploying, so they are written to fail loudly rather
+than to pass conveniently, and every one of them runs offline in under a
+second.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+import pytest
+
+from src import config, trackrecord as tr
+from src.adapters import (ForecastResult, LookaheadError, ModelNotAllowed,
+                          check_context, get_adapter)
+from src.adapters.base import ContextError
+from src.store import forecast_id
+from tests.fixture import future_ts, synth
+
+CPU_FAMILIES = ["baseline/random-walk", "baseline/drift", "baseline/bootstrap"]
+
+
+# --------------------------------------------------------------------------
+# 1. Determinism
+# --------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize("model_id", CPU_FAMILIES)
+def test_same_seed_is_bit_identical(model_id, context):
+    """Same (context, horizon, n_samples, seed) => bit-identical output."""
+    a = get_adapter("baseline", model_id).load()
+    kw = dict(horizon=12, n_samples=16, seed=1234)
+    first = a.predict(context, **kw)
+    second = a.predict(context, **kw)
+
+    assert np.array_equal(first.quantiles, second.quantiles)
+    if first.paths is not None:
+        assert np.array_equal(first.paths, second.paths)
+    assert first.inference_version == second.inference_version
+
+
+@pytest.mark.parametrize("model_id", CPU_FAMILIES)
+def test_different_seed_changes_sampled_output(model_id, context):
+    """A seed that does nothing is a seed that is not wired up."""
+    a = get_adapter("baseline", model_id).load()
+    kw = dict(horizon=12, n_samples=16)
+    first = a.predict(context, seed=1, **kw)
+    second = a.predict(context, seed=2, **kw)
+    if a.capabilities().emits_paths:
+        assert not np.array_equal(first.paths, second.paths)
+    else:
+        # The analytic baselines are closed-form: no sampling, so the seed
+        # legitimately does not move them. Asserting the opposite would be
+        # asserting a bug.
+        assert np.array_equal(first.quantiles, second.quantiles)
+
+
+@pytest.mark.slow
+@pytest.mark.parametrize("family,model_id", [
+    ("chronos", "amazon/chronos-bolt-tiny"),
+    ("timesfm", "google/timesfm-2.5-200m-pytorch"),
+    ("kronos", "NeoQuasar/Kronos-mini"),
+])
+def test_determinism_across_all_three_families(family, model_id):
+    """The same promise, against real weights. Needs network; not in the gate."""
+    ctx = synth(400)
+    a = get_adapter(family, model_id).load()
+    kw = dict(horizon=8, n_samples=4, seed=99)
+    first = a.predict(ctx, **kw)
+    second = a.predict(ctx, **kw)
+    assert np.array_equal(first.quantiles, second.quantiles)
+    if first.paths is not None:
+        assert np.array_equal(first.paths, second.paths)
+
+
+# --------------------------------------------------------------------------
+# 2. No lookahead
+# --------------------------------------------------------------------------
+
+
+def test_context_after_issued_ts_raises(context):
+    """A context bar dated after the issue moment is refused, structurally."""
+    issued = pd.to_datetime(context["ts"], utc=True).iloc[-5]
+    with pytest.raises(LookaheadError):
+        check_context(context, issued_ts=issued)
+
+
+def test_context_at_issued_ts_is_allowed(context):
+    """The boundary is inclusive: a bar *at* the issue moment is legitimate."""
+    issued = pd.to_datetime(context["ts"], utc=True).iloc[-1]
+    assert check_context(context, issued_ts=issued) is context
+
+
+def test_adapters_enforce_lookahead_on_every_call(context):
+    a = get_adapter("baseline", "baseline/random-walk").load()
+    issued = pd.to_datetime(context["ts"], utc=True).iloc[-5]
+    with pytest.raises(LookaheadError):
+        a.predict(context, horizon=4, seed=0, issued_ts=issued)
+
+
+def test_backfill_slicing_is_structurally_clean():
+    """As-of slicing on a fixture passes the same check the live path uses."""
+    bars = synth(300)
+    ts = pd.to_datetime(bars["ts"], utc=True)
+    for cut in (120, 200, 260):
+        issued = ts.iloc[cut]
+        as_of = bars.iloc[:cut + 1]
+        assert check_context(as_of, issued_ts=issued) is as_of
+
+
+def test_context_rejects_nans_and_gaps(context):
+    bad = context.copy()
+    bad.loc[bad.index[10], "close"] = np.nan
+    with pytest.raises(ContextError):
+        check_context(bad)
+
+
+# --------------------------------------------------------------------------
+# 3. Frozen at issue
+# --------------------------------------------------------------------------
+
+
+def _issue(store, seed=7, horizon=6, backfilled=False, model="baseline/random-walk"):
+    ctx = synth(200)
+    a = get_adapter("baseline", model).load()
+    result = a.predict(ctx, horizon=horizon, n_samples=8, seed=seed)
+    issued = pd.to_datetime(ctx["ts"], utc=True).iloc[-1]
+    targets = future_ts(ctx, horizon)
+    fid, written = tr.archive(store, result, "random-walk", "BTC-USD", "1h",
+                              issued, targets, backfilled=backfilled)
+    return fid, written, ctx, targets, issued
+
+
+def test_resolution_leaves_archived_rows_byte_identical(store):
+    *_, issued = _issue(store, horizon=4)
+    path = config.signals_path("random-walk", "BTC-USD", "1h", issued.year)
+    # The archive lives in the local mirror; read the bytes, not the frame.
+    local = store.local_root / path
+    before = local.read_bytes()
+
+    _seed_prices(store, "BTC-USD", "1h")
+    resolved = tr.resolve(store, "random-walk", "BTC-USD", "1h",
+                          now=issued + pd.Timedelta("400d"))
+
+    # Without this the assertion below would pass vacuously if the resolver
+    # silently did nothing at all.
+    assert len(resolved) == 4, "nothing was resolved; the test proves nothing"
+    assert local.read_bytes() == before, "resolution rewrote the archive"
+
+
+def test_resolver_is_idempotent(store):
+    *_, issued = _issue(store, horizon=4)
+    _seed_prices(store, "BTC-USD", "1h")
+    later = issued + pd.Timedelta("400d")
+
+    first = tr.resolve(store, "random-walk", "BTC-USD", "1h", now=later)
+    second = tr.resolve(store, "random-walk", "BTC-USD", "1h", now=later)
+
+    assert len(first) > 0
+    assert len(second) == 0, "a second resolve appended rows again"
+    assert len(store.get_trackrecord("random-walk", "BTC-USD", "1h")) == len(first)
+
+
+# --------------------------------------------------------------------------
+# 4. Coverage arithmetic
+# --------------------------------------------------------------------------
+
+
+def test_empirical_coverage_matches_nominal_on_a_known_distribution():
+    """Draw from the band's own distribution; coverage must land on nominal.
+
+    The forecast is a standard normal band and the outcomes are standard
+    normal draws, so 80% of them belong inside q10..q90 by construction. If
+    this drifts, the inside-band arithmetic is wrong -- not the model.
+    """
+    rng = np.random.default_rng(0)
+    n = 20000
+    realized = rng.normal(0.0, 1.0, n)
+    q10, q90 = -1.2815515655446004, 1.2815515655446004   # exact N(0,1) deciles
+    q20, q80 = -0.8416212335729143, 0.8416212335729143
+
+    frame = pd.DataFrame({
+        "forecast_id": [f"f{i}" for i in range(n)],
+        "model_slug": "synthetic", "asset": "BTC-USD", "timeframe": "1h",
+        "issued_ts": pd.Timestamp("2026-01-01", tz="UTC"),
+        "target_ts": pd.Timestamp("2026-01-02", tz="UTC"),
+        "step": 1, "horizon_bars": 1,
+        "realized_close": realized,
+        "q10": q10, "q20": q20, "q50": 0.0, "q80": q80, "q90": q90,
+        "inside_80": (realized >= q10) & (realized <= q90),
+        "inside_60": (realized >= q20) & (realized <= q80),
+        "abs_error": np.abs(realized), "pct_error": np.abs(realized),
+        "resolved_ts": pd.Timestamp("2026-01-02", tz="UTC"), "backfilled": False,
+    })
+
+    standings = tr.build_standings(frame)
+    row = standings.iloc[0]
+    # 3 standard errors at n=20000 is about 0.008.
+    assert abs(row["coverage_80"] - 0.80) < 0.01
+    assert abs(row["coverage_60"] - 0.60) < 0.01
+    assert row["grade"] == "A"
+
+
+@pytest.mark.parametrize("gap,expected", [
+    (0.00, "A"), (0.04, "A"), (-0.05, "A"),
+    (0.06, "B"), (-0.10, "B"),
+    (0.15, "C"), (-0.20, "C"),
+    (0.30, "D"), (-0.55, "D"),
+])
+def test_grade_thresholds_map_correctly(gap, expected):
+    assert tr.grade_for(gap, resolved_count=100) == expected
+
+
+def test_grade_withheld_below_the_minimum():
+    """Too little evidence produces no grade, not a flattering one."""
+    assert tr.grade_for(0.0, resolved_count=config.MIN_RESOLVED_FOR_GRADE - 1) == "-"
+    assert tr.grade_for(0.0, resolved_count=config.MIN_RESOLVED_FOR_GRADE) == "A"
+
+
+# --------------------------------------------------------------------------
+# 5. Dedup
+# --------------------------------------------------------------------------
+
+
+def test_identical_forecast_issued_twice_archives_once(store):
+    fid1, written1, *_ = _issue(store, seed=7)
+    fid2, written2, *_ = _issue(store, seed=7)
+
+    assert fid1 == fid2
+    assert written1 > 0
+    assert written2 == 0, "the duplicate was archived a second time"
+
+    rows = store.get_forecasts("random-walk", "BTC-USD", "1h")
+    assert rows["forecast_id"].nunique() == 1
+    assert len(rows) == written1
+
+
+def test_a_different_seed_is_a_different_forecast(store):
+    fid1, *_ = _issue(store, seed=7)
+    fid2, written2, *_ = _issue(store, seed=8)
+    assert fid1 != fid2
+    assert written2 > 0
+
+
+def test_forecast_id_excludes_inference_version():
+    """Re-issuing after a model upgrade must not fork the archive."""
+    a = forecast_id("m", "BTC-USD", "1h", "2026-01-01T00:00:00+00:00", 3)
+    b = forecast_id("m", "BTC-USD", "1h", pd.Timestamp("2026-01-01", tz="UTC"), 3)
+    assert a == b
+
+
+# --------------------------------------------------------------------------
+# 6. Capability gating
+# --------------------------------------------------------------------------
+
+
+def test_quantile_line_models_declare_no_paths(context):
+    a = get_adapter("baseline", "baseline/random-walk").load()
+    caps = a.capabilities()
+    assert caps.output == "quantile_line"
+    assert caps.emits_paths is False
+    result = a.predict(context, horizon=6, n_samples=8, seed=0)
+    assert result.paths is None
+
+
+def test_path_models_declare_and_return_paths(context):
+    a = get_adapter("baseline", "baseline/bootstrap").load()
+    caps = a.capabilities()
+    assert caps.output == "ohlcv_paths"
+    assert caps.emits_paths is True
+    result = a.predict(context, horizon=6, n_samples=8, seed=0)
+    assert result.paths is not None
+    assert result.paths.shape[:2] == (8, 6)
+
+
+def test_dispersion_is_defined_for_both_output_kinds(context):
+    for model_id in ("baseline/random-walk", "baseline/bootstrap"):
+        a = get_adapter("baseline", model_id).load()
+        result = a.predict(context, horizon=6, n_samples=8, seed=0)
+        d = result.dispersion()
+        assert d.shape == (6,)
+        assert np.all(np.isfinite(d)) and np.all(d >= 0)
+
+
+def test_unknown_family_is_refused():
+    with pytest.raises(ModelNotAllowed):
+        get_adapter("definitely-not-a-family", "someone/somemodel")
+
+
+# --------------------------------------------------------------------------
+# 8. Standings are a pure function of the track record
+# --------------------------------------------------------------------------
+
+
+def test_standings_are_deterministic_in_their_input():
+    frame = _synthetic_trackrecord()
+    now = pd.Timestamp("2026-06-01", tz="UTC")
+    first = tr.build_standings(frame, now=now)
+    second = tr.build_standings(frame.sample(frac=1.0, random_state=3), now=now)
+    pd.testing.assert_frame_equal(first, second)
+
+
+def test_standings_ignore_everything_but_the_track_record():
+    frame = _synthetic_trackrecord()
+    now = pd.Timestamp("2026-06-01", tz="UTC")
+    baseline = tr.build_standings(frame, now=now)
+    # Columns the standings must not read.
+    noisy = frame.copy()
+    noisy["backfilled"] = ~noisy["backfilled"]
+    noisy["resolved_ts"] = pd.Timestamp("2030-01-01", tz="UTC")
+    pd.testing.assert_frame_equal(tr.build_standings(noisy, now=now), baseline)
+
+
+def test_empty_trackrecord_gives_empty_standings():
+    out = tr.build_standings(pd.DataFrame())
+    assert len(out) == 0
+    assert list(out.columns) == list(tr.STANDINGS_COLUMNS)
+
+
+# --------------------------------------------------------------------------
+# Helpers
+# --------------------------------------------------------------------------
+
+
+def _seed_prices(store, asset, timeframe):
+    """Put a price history into the store covering the fixture's future."""
+    bars = synth(600, tf=timeframe)
+    ts = pd.to_datetime(bars["ts"], utc=True)
+    step = ts.diff().dropna().mode().iloc[0]
+    forward = pd.DataFrame({
+        "ts": pd.DatetimeIndex([ts.iloc[-1] + step * (i + 1) for i in range(200)]),
+        "open": 50000.0, "high": 50100.0, "low": 49900.0,
+        "close": 50000.0, "volume": 1000.0,
+    })
+    full = pd.concat([bars, forward], ignore_index=True)
+    for year, chunk in full.groupby(full["ts"].dt.year):
+        store.write_parquet(config.prices_path(asset, timeframe, int(year)), chunk)
+
+
+def _synthetic_trackrecord(n=200):
+    rng = np.random.default_rng(11)
+    realized = rng.normal(100.0, 5.0, n)
+    return pd.DataFrame({
+        "forecast_id": [f"f{i // 4}" for i in range(n)],
+        "model_slug": ["alpha" if i % 2 else "beta" for i in range(n)],
+        "asset": ["BTC-USD" if i % 3 else "SPY" for i in range(n)],
+        "timeframe": "1h",
+        "issued_ts": pd.Timestamp("2026-01-01", tz="UTC"),
+        "target_ts": pd.Timestamp("2026-01-02", tz="UTC"),
+        "step": [(i % 4) + 1 for i in range(n)],
+        "horizon_bars": 4,
+        "realized_close": realized,
+        "q10": 92.0, "q20": 95.0, "q50": 100.0, "q80": 105.0, "q90": 108.0,
+        "inside_80": (realized >= 92.0) & (realized <= 108.0),
+        "inside_60": (realized >= 95.0) & (realized <= 105.0),
+        "abs_error": np.abs(realized - 100.0),
+        "pct_error": np.abs(realized - 100.0) / realized * 100,
+        "resolved_ts": pd.Timestamp("2026-01-02", tz="UTC"),
+        "backfilled": [bool(i % 5 == 0) for i in range(n)],
+    })
+
+
+# --------------------------------------------------------------------------
+# Context validation must not reject a market's own trading calendar
+# --------------------------------------------------------------------------
+
+
+def _equity_hours(days: int = 90) -> pd.DataFrame:
+    """Hourly bars that trade 09:30-16:00 on weekdays and close otherwise.
+
+    Regression fixture. Judging gaps against the modal bar rejected every SPY
+    and NVDA hourly context outright -- 73 "gaps" in 512 bars that were simply
+    overnight and weekend closures. Nobody could forecast an equity intraday
+    series at all.
+    """
+    stamps = []
+    day = pd.Timestamp("2026-01-05", tz="UTC")     # a Monday
+    for _ in range(days):
+        if day.weekday() < 5:
+            stamps += [day + pd.Timedelta(hours=h) for h in range(14, 21)]
+        day += pd.Timedelta(days=1)
+    ts = pd.DatetimeIndex(stamps)
+    rng = np.random.default_rng(5)
+    close = 600 * np.exp(np.cumsum(rng.normal(0, 0.004, len(ts))))
+    openp = np.concatenate([[600.0], close[:-1]])
+    return pd.DataFrame({
+        "ts": ts, "open": openp,
+        "high": np.maximum(openp, close) * 1.001,
+        "low": np.minimum(openp, close) * 0.999,
+        "close": close, "volume": 1000.0,
+    })
+
+
+def test_equity_session_gaps_are_not_treated_as_missing_data():
+    bars = _equity_hours()
+    assert len(bars) > 400
+    assert check_context(bars) is bars
+
+
+def test_a_real_hole_in_the_cache_is_still_caught():
+    """The session-aware threshold must not have disabled the check.
+
+    A missing month in an hourly series is ~720 hours against a worst regular
+    gap of ~65 (a weekend), so it is caught by the hard ceiling even though it
+    is a single gap.
+    """
+    bars = _equity_hours()
+    ts = pd.to_datetime(bars["ts"], utc=True)
+    start = ts.iloc[200]
+    holed = bars[(ts < start) | (ts > start + pd.Timedelta(days=30))]
+
+    with pytest.raises(ContextError, match="cache is incomplete"):
+        check_context(holed.reset_index(drop=True))
+
+
+def test_a_crypto_series_still_rejects_a_modest_hole():
+    """24/7 data has no sessions, so its tolerance stays tight."""
+    bars = synth(400)
+    ts = pd.to_datetime(bars["ts"], utc=True)
+    start = ts.iloc[100]
+    holed = bars[(ts < start) | (ts > start + pd.Timedelta(hours=60))]
+
+    with pytest.raises(ContextError):
+        check_context(holed.reset_index(drop=True))

tests/test_app.py

@@ -0,0 +1,168 @@
+"""The app's state machine: actions fold correctly, and nothing else moves.
+
+`apply_action` is the only way state changes, so these tests are the contract
+for every control on the page. They run against the real module with the store
+pointed at a temp directory, so no network and no credentials are involved.
+"""
+
+from __future__ import annotations
+
+import importlib
+import os
+
+import pytest
+
+
+@pytest.fixture(scope="module")
+def app(tmp_path_factory):
+    """The app module, booted against an empty local store."""
+    os.environ["ARENA_OFFLINE"] = "1"
+    os.environ["ARENA_LOCAL_STORE"] = str(tmp_path_factory.mktemp("store"))
+    os.environ["ARENA_LOCAL_NAV"] = ""
+    import app as app_module
+
+    app_module = importlib.reload(app_module)
+
+    # Enroll the dependency-free baselines so the selection tests exercise real
+    # registry entries rather than skipping. They need no weights or network.
+    from src import runtime as rt
+
+    for model_id in ("baseline/random-walk", "baseline/drift", "baseline/bootstrap"):
+        rt.enroll(app_module.STORE, "baseline", model_id, enrolled_by="tests",
+                  registry=app_module.BOOT["registry"])
+    app_module.BOOT["registry"] = app_module.STORE.get_registry()
+    return app_module
+
+
+def _state(app, **over):
+    state = app.default_state()
+    state.update(over)
+    return state
+
+
+# --------------------------------------------------------------------------
+# Action folding
+# --------------------------------------------------------------------------
+
+
+def test_an_unknown_action_changes_nothing(app):
+    before = _state(app)
+    after = app.apply_action(before, "not-an-action:whatever|n1")
+    assert after == before
+
+
+def test_a_malformed_payload_changes_nothing(app):
+    before = _state(app)
+    for raw in ("", "no-colon", "|", None):
+        assert app.apply_action(before, raw) == before
+
+
+def test_asset_and_timeframe_are_validated(app):
+    state = _state(app)
+    assert app.apply_action(state, "asset:BTC-USD|n1")["asset"] == "BTC-USD"
+    # Off the known list: ignored, not stored.
+    assert app.apply_action(state, "asset:DOGE-USD|n2")["asset"] == state["asset"]
+    assert app.apply_action(state, "tf:1d|n3")["tf"] == "1d"
+    assert app.apply_action(state, "tf:7y|n4")["tf"] == state["tf"]
+
+
+def test_changing_the_timeframe_resets_the_horizon_to_its_default(app):
+    state = app.apply_action(_state(app), "hz:96|n1")
+    assert state["horizon"] == 96
+    state = app.apply_action(state, "tf:1d|n2")
+    assert state["horizon"] == app.config.DEFAULT_HORIZON["1d"]
+
+
+def test_an_out_of_range_horizon_is_rejected(app):
+    state = _state(app, tf="1d")
+    assert app.apply_action(state, "hz:100000|n1")["horizon"] == state["horizon"]
+    assert app.apply_action(state, "hz:-4|n2")["horizon"] == state["horizon"]
+    assert app.apply_action(state, "hz:notanumber|n3")["horizon"] == state["horizon"]
+
+
+def test_the_same_nonce_twice_folds_once(app):
+    """Two delivery paths mean one click can arrive twice."""
+    state = _state(app, gear=False)
+    once = app.apply_action(state, "gear:toggle|abc")
+    twice = app.apply_action(once, "gear:toggle|abc")
+    assert once["gear"] is True
+    assert twice["gear"] is True, "the duplicate delivery toggled it back"
+
+
+def test_playground_holds_one_model_and_matchup_holds_up_to_three(app):
+    slugs = sorted(app.BOOT["registry"].get("models", {}))
+    if len(slugs) < 2:
+        pytest.skip("needs at least two enrolled models")
+
+    state = _state(app, mode="matchup", selected=[slugs[0]])
+    for slug in slugs[1:5]:
+        state = app.apply_action(state, f"pick:{slug}|n{slug}")
+    assert len(state["selected"]) <= app.view.MAX_MATCHUP
+
+    state = app.apply_action(state, "mode:playground|nz")
+    assert len(state["selected"]) == 1
+
+
+def test_deselecting_the_last_model_is_refused(app):
+    slugs = sorted(app.BOOT["registry"].get("models", {}))
+    if not slugs:
+        pytest.skip("needs an enrolled model")
+    state = _state(app, mode="matchup", selected=[slugs[0]])
+    state = app.apply_action(state, f"pick:{slugs[0]}|n1")
+    assert state["selected"] == [slugs[0]], "left the UI with no model selected"
+
+
+def test_picking_an_unenrolled_model_is_ignored(app):
+    state = _state(app)
+    after = app.apply_action(state, "pick:some-model-nobody-enrolled|n1")
+    assert after["selected"] == state["selected"]
+
+
+def test_standings_class_filter_is_validated(app):
+    state = _state(app)
+    assert app.apply_action(state, "cls:Crypto|n1")["cls"] == "Crypto"
+    assert app.apply_action(state, "cls:Nonsense|n2")["cls"] == state["cls"]
+
+
+def test_the_enrollment_box_is_length_capped(app):
+    state = app.apply_action(_state(app), "hfid:" + "x" * 5000 + "|n1")
+    assert len(state["hfid"]) <= 120
+
+
+# --------------------------------------------------------------------------
+# Rendering
+# --------------------------------------------------------------------------
+
+
+def test_the_page_renders_for_every_mode(app):
+    for mode in ("playground", "matchup"):
+        html = app.render(_state(app, mode=mode))
+        assert "Forecast Arena" in html
+        assert len(html) > 5000
+
+
+def test_the_page_renders_with_no_models_enrolled(app, monkeypatch):
+    """An empty registry is the first-boot state, not an error."""
+    monkeypatch.setitem(app.BOOT, "registry", {"models": {}})
+    html = app.render(_state(app, selected=[]))
+    assert "Forecast Arena" in html
+
+
+def test_the_disclaimer_is_always_on_the_page(app):
+    """A forecast must never be presented as advice, on any state of the page."""
+    html = app.render(_state(app)).lower()
+    assert "nothing here is financial advice" in html
+    # Twice: once beside the method note, once in the footer.
+    assert html.count("financial advice") >= 2
+
+
+def test_the_methodology_promises_are_on_the_page(app):
+    html = app.render(_state(app))
+    for promise in ("frozen at issue", "backfilled entries", "resolved forecasts only"):
+        assert promise in html.lower()
+
+
+def test_on_action_returns_html_and_state(app):
+    html, state = app.on_action("cls:Crypto|n1", app.default_state())
+    assert isinstance(html, str) and len(html) > 1000
+    assert state["cls"] == "Crypto"

tests/test_kronos_vendor.py

@@ -0,0 +1,88 @@
+"""The vendored Kronos source is what was reviewed, and behaves like upstream.
+
+`vendor/kronos` is third-party source carrying two local patches. Two things
+can go wrong with that arrangement and both are silent:
+
+* someone re-vendors from a newer upstream and the patches quietly vanish, or
+  arrive alongside changes nobody read;
+* the normalisation `adapters/kronos.py` replicates drifts away from the
+  normalisation `KronosPredictor.predict` actually applies, so archived Kronos
+  forecasts stop matching what the model would really have said.
+
+The hash test catches the first. The equivalence test catches the second, by
+running both paths and requiring the mean of the adapter's sampled paths to
+equal upstream's averaged output for the same seed.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+import numpy as np
+import pytest
+
+VENDOR = Path(__file__).resolve().parents[1] / "vendor" / "kronos"
+
+# Update these deliberately, and only after reading the diff.
+REVIEWED = {
+    "__init__.py": "f8f856ca3fedadcaac97e196be23d1aeda1c3c9ffe8903d66d43ea3bcac6240c",
+    "module.py": "a07edbadc0e96804c8158c021bbc6063bb7cc43b34d7fc470d5c8ff2005a409f",
+}
+
+
+@pytest.mark.parametrize("name,expected", sorted(REVIEWED.items()))
+def test_vendored_files_are_the_reviewed_content(name, expected):
+    digest = hashlib.sha256((VENDOR / name).read_bytes()).hexdigest()
+    assert digest == expected, (
+        f"vendor/kronos/{name} changed. Read the diff, then update REVIEWED."
+    )
+
+
+def test_the_two_local_patches_are_present():
+    source = (VENDOR / "kronos.py").read_text()
+    assert "from .module import *" in source, "relative-import patch is missing"
+    assert "return_paths" in source, "path-returning patch is missing"
+    assert "from model.module import *" not in source
+
+
+@pytest.mark.slow
+def test_adapter_normalisation_matches_upstream_predictor():
+    """The adapter's replicated normalisation reproduces upstream's answer."""
+    import sys
+
+    import pandas as pd
+    import torch
+
+    sys.path.insert(0, str(VENDOR.parent))
+    from kronos import Kronos, KronosPredictor, KronosTokenizer
+
+    from src.adapters import get_adapter
+    from tests.fixture import synth
+
+    ctx = synth(300)
+    horizon, n_samples, seed = 6, 4, 4321
+
+    adapter = get_adapter("kronos", "NeoQuasar/Kronos-mini").load()
+    mine = adapter.predict(ctx, horizon=horizon, n_samples=n_samples, seed=seed)
+
+    predictor = KronosPredictor(adapter._model, adapter._tokenizer,
+                                device=adapter.device, max_context=2048)
+    frame = ctx[["open", "high", "low", "close", "volume"]].copy()
+    frame["amount"] = frame["volume"] * frame[["open", "high", "low", "close"]].mean(axis=1)
+    ts = pd.to_datetime(ctx["ts"], utc=True)
+    step = ts.diff().dropna().mode().iloc[0]
+    future = pd.Series([ts.iloc[-1] + step * (i + 1) for i in range(horizon)])
+
+    torch.manual_seed(seed % (2 ** 31 - 1))
+    np.random.seed(seed % (2 ** 31 - 1))
+    theirs = predictor.predict(df=frame, x_timestamp=ts, y_timestamp=future,
+                               pred_len=horizon, T=1.0, top_p=0.9, top_k=0,
+                               sample_count=n_samples, verbose=False)
+
+    # Upstream returns the mean over samples; the adapter keeps them, so the
+    # comparison is against the mean of what it kept.
+    mine_mean_close = mine.paths[:, :, 3].mean(axis=0)
+    np.testing.assert_allclose(mine_mean_close,
+                               theirs["close"].to_numpy(dtype="float64"),
+                               rtol=1e-6, atol=1e-6)

tests/test_runtime.py

@@ -0,0 +1,167 @@
+"""Enrollment, the no-lookahead guarantee at the runtime layer, and tiering.
+
+These cover the parts of the acceptance list that live between the adapters and
+the UI: that enrollment is idempotent and refuses anything it cannot load
+safely, that `load_context` cannot hand a model a bar from the future, and that
+a CPU-tier model either meets its budget or is recorded as demoted.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+import pytest
+
+from src import config, runtime
+from src.adapters import LookaheadError
+from tests.fixture import synth
+
+
+@pytest.fixture
+def seeded_store(store):
+    """A store with prices and one enrolled baseline."""
+    bars = synth(600)
+    for year, chunk in bars.groupby(bars["ts"].dt.year):
+        store.write_parquet(config.prices_path("BTC-USD", "1h", int(year)), chunk)
+    outcome = runtime.enroll(store, "baseline", "baseline/random-walk",
+                             enrolled_by="tests")
+    assert outcome.ok, outcome.message
+    return store
+
+
+# --------------------------------------------------------------------------
+# 5. Enrollment is idempotent, and refuses what it cannot vouch for
+# --------------------------------------------------------------------------
+
+
+def test_enrolling_the_same_revision_twice_is_a_no_op(store):
+    first = runtime.enroll(store, "baseline", "baseline/drift", enrolled_by="a")
+    registry = store.get_registry()
+    second = runtime.enroll(store, "baseline", "baseline/drift", enrolled_by="b",
+                            registry=registry)
+
+    assert first.ok and second.ok
+    assert second.already is True
+    assert len(registry["models"]) == 1
+    # The second attempt must not have rewritten who enrolled it.
+    assert registry["models"]["drift"]["enrolled_by"] == "a"
+
+
+def test_unsupported_family_is_refused_with_a_clear_message(store):
+    outcome = runtime.enroll(store, "llama", "meta-llama/Llama-3-8B")
+    assert not outcome.ok
+    assert "not a supported adapter family" in outcome.message
+    assert "baseline" in outcome.message      # names what *is* supported
+
+
+def test_a_malformed_model_id_is_refused(store):
+    for bad in ("not-a-model-id", "../../etc/passwd", "a/b/c", ""):
+        outcome = runtime.enroll(store, "baseline", bad)
+        assert not outcome.ok, f"{bad!r} was accepted"
+
+
+def test_enrolling_under_the_wrong_family_is_refused(store):
+    """A known Chronos model must not be loaded through the Kronos loader."""
+    outcome = runtime.enroll(store, "kronos", "amazon/chronos-bolt-tiny")
+    assert not outcome.ok
+    assert "chronos" in outcome.message
+
+
+def test_enrollment_records_what_it_verified(store):
+    runtime.enroll(store, "baseline", "baseline/bootstrap", enrolled_by="tests")
+    entry = store.get_registry()["models"]["bootstrap"]
+
+    assert entry["revision"]                       # pinned
+    assert entry["smoke_test"]["ok"] is True       # actually ran
+    assert entry["capabilities"]["output"] == "ohlcv_paths"
+    assert entry["enrolled_by"] == "tests"
+    assert entry["inference_version"]
+
+
+# --------------------------------------------------------------------------
+# 2. No lookahead, at the runtime layer
+# --------------------------------------------------------------------------
+
+
+def test_load_context_never_returns_a_bar_after_the_cut(seeded_store):
+    prices = seeded_store.get_prices("BTC-USD", "1h")
+    cut = pd.to_datetime(prices["ts"], utc=True).iloc[300]
+
+    context = runtime.load_context(seeded_store, "BTC-USD", "1h", as_of=cut)
+    assert pd.to_datetime(context["ts"], utc=True).max() <= cut
+
+
+def test_an_as_of_forecast_is_issued_from_the_cut_not_the_clock(seeded_store):
+    prices = seeded_store.get_prices("BTC-USD", "1h")
+    cut = pd.to_datetime(prices["ts"], utc=True).iloc[400]
+
+    run = runtime.run_forecast(seeded_store, "random-walk", "BTC-USD", "1h",
+                               horizon=6, seed=1, as_of=cut, archive=False)
+    assert run.issued_ts <= cut
+    assert run.target_ts[0] > cut
+
+
+def test_a_context_reaching_past_the_issue_moment_raises(seeded_store):
+    """The adapter re-checks, so a caller cannot smuggle one past it."""
+    from src.adapters import get_adapter
+
+    context = runtime.load_context(seeded_store, "BTC-USD", "1h")
+    stale = pd.to_datetime(context["ts"], utc=True).iloc[-10]
+    adapter = get_adapter("baseline", "baseline/random-walk").load()
+
+    with pytest.raises(LookaheadError):
+        adapter.predict(context, horizon=4, seed=0, issued_ts=stale)
+
+
+def test_forecast_targets_start_after_the_context_ends(seeded_store):
+    run = runtime.run_forecast(seeded_store, "random-walk", "BTC-USD", "1h",
+                               horizon=8, seed=3, archive=False)
+    assert run.target_ts[0] > run.issued_ts
+    assert len(run.target_ts) == 8
+
+
+# --------------------------------------------------------------------------
+# 7. Tiering
+# --------------------------------------------------------------------------
+
+
+def test_a_cpu_tier_model_either_meets_the_budget_or_is_recorded_as_demoted(store):
+    """The rule the bootstrap script applies, checked directly.
+
+    The registry on the Hub is written by a measurement run; this asserts the
+    rule that run enforces, so a change to the thresholds cannot silently let a
+    model sit in the CPU tier while missing its budget.
+    """
+    from scripts.bootstrap_registry import measure
+
+    context = synth(config.DEFAULT_CONTEXT_BARS)
+    latency = measure("baseline", "baseline/random-walk", context)
+
+    assert latency["cold_s"] <= config.CPU_BUDGET_COLD_S
+    assert latency["warm_s"] <= config.CPU_BUDGET_WARM_S
+    assert latency["hardware"] == "cpu"
+    assert latency["demoted"] is False
+    # The measurement is meaningless without the machine it was taken on.
+    assert latency["machine"]
+
+
+def test_the_demotion_rule_fires_when_a_budget_is_missed(monkeypatch):
+    """A CPU-declared model that is too slow must come back as gpu."""
+    from scripts import bootstrap_registry
+
+    context = synth(config.DEFAULT_CONTEXT_BARS)
+    monkeypatch.setattr(config, "CPU_BUDGET_WARM_S", 0.0)
+    latency = bootstrap_registry.measure("baseline", "baseline/drift", context)
+
+    assert latency["declared_hardware"] == "cpu"
+    assert latency["hardware"] == "gpu"
+    assert latency["demoted"] is True
+
+
+# --------------------------------------------------------------------------
+# Anonymous session cap
+# --------------------------------------------------------------------------
+
+
+def test_the_session_cap_is_a_real_number():
+    assert config.ANON_SESSION_CAP > 0

tests/test_ui.py

@@ -0,0 +1,360 @@
+"""The rendering layer: the design ports faithfully, and stays capability-gated.
+
+Two classes of test here.
+
+*Fidelity*: every stylesheet the design system ships actually reaches the page,
+and nothing forces height from `vh` (which ratchets the Spaces iframe). These
+catch the failure where the app looks approximately right in a way that is hard
+to name.
+
+*Gating*: the UI decides what to draw from an adapter's declared capabilities
+and never from a model's name. The fixture adapters below exist so that claim
+can be tested without loading a single weight.
+"""
+
+from __future__ import annotations
+
+import re
+
+import numpy as np
+import pandas as pd
+import pytest
+
+from src import config, view
+from src.adapters.base import (OUTPUT_OHLCV_PATHS, OUTPUT_QUANTILE_LINE,
+                               Capabilities, ForecastAdapter, ForecastResult)
+from src.ui import chart, chrome, shell
+from tests.fixture import future_ts, synth
+
+from bit_ui import theme
+
+
+# --------------------------------------------------------------------------
+# Fixture adapters -- declared capabilities, no weights
+# --------------------------------------------------------------------------
+
+
+class _Fixture(ForecastAdapter):
+    """An adapter that declares whatever the test needs it to."""
+
+    family = "fixture"
+
+    def __init__(self, output=OUTPUT_QUANTILE_LINE, hardware="cpu"):
+        super().__init__("fixture/model", revision="test")
+        self._output, self._hardware = output, hardware
+
+    def capabilities(self):
+        return Capabilities(output=self._output, hardware=self._hardware,
+                            max_context=256)
+
+    def load(self, model_id=None, revision=None):
+        self._model = True
+        self._resolved_revision = "test"
+        return self
+
+    def predict(self, context_ohlcv, horizon=6, n_samples=8, seed=0,
+                issued_ts=None):
+        last = float(context_ohlcv["close"].iloc[-1])
+        q = np.tile(np.array([0.97, 0.99, 1.0, 1.01, 1.03]) * last, (horizon, 1))
+        paths = None
+        if self._output == OUTPUT_OHLCV_PATHS:
+            paths = np.tile(last, (n_samples, horizon, 5)).astype("float64")
+        return ForecastResult(
+            quantiles=q, levels=config.QUANTILE_LEVELS, horizon=horizon,
+            context_len=len(context_ohlcv), inference_version="fixture",
+            seed=seed, n_samples=n_samples, paths=paths)
+
+
+class _Run:
+    """The shape `shell` expects from `runtime.ForecastRun`."""
+
+    def __init__(self, adapter, context, horizon=6, slug="fixture"):
+        self.model_slug = slug
+        self.model_id = "fixture/model"
+        self.family = "fixture"
+        self.asset, self.timeframe, self.horizon = "BTC-USD", "1h", horizon
+        self.context = context
+        self.result = adapter.predict(context, horizon=horizon)
+        self.issued_ts = pd.to_datetime(context["ts"], utc=True).iloc[-1]
+        self.target_ts = future_ts(context, horizon)
+        self.capabilities = adapter.capabilities().as_dict()
+        self.forecast_id, self.archived_rows, self.elapsed_s = "fid", horizon, 0.1
+
+
+def _data(runs, state, **over):
+    models = [{
+        "slug": r.model_slug, "name": r.model_slug, "family": "fixture",
+        "size": "1M", "caps": r.capabilities, "color": "var(--accent-amber-strong)",
+        "grade": "-", "grade_color": "var(--text-tertiary)",
+        "resolved_label": "UNRESOLVED",
+    } for r in runs] or [{
+        "slug": "fixture", "name": "fixture", "family": "fixture", "size": "1M",
+        "caps": {"output": OUTPUT_QUANTILE_LINE, "hardware": "cpu"},
+        "color": "var(--accent-amber-strong)", "grade": "-",
+        "grade_color": "var(--text-tertiary)", "resolved_label": "UNRESOLVED"}]
+    data = {
+        "models": models,
+        "models_by_slug": {m["slug"]: m for m in models},
+        "panels": {r.model_slug: {"empty": True} for r in runs},
+        "runs": runs,
+        "chart": (chart.build(runs[0].context, runs, "BTC-USD", runs[0].horizon)
+                  if runs else {}),
+        "volatility": {"rows": [], "verdict": "", "note": ""},
+        "stats": [], "standings_rows": [], "families": ("kronos",),
+        "coverage": {"scope": "", "pct_label": "—", "pct_width": "0%", "rows": []},
+        "nav": {}, "archived_total": 0, "resolved_total": 0,
+        "resolver_last_ran": "NEVER", "runtime_hint": "~1S",
+        "quota_blocked": False, "footer_resources": (), "status_line": "",
+        "error": None,
+    }
+    data.update(over)
+    return data
+
+
+@pytest.fixture
+def context():
+    return synth(300)
+
+
+def _state(**over):
+    state = view.default_state()
+    state["selected"] = ["fixture"]
+    state.update(over)
+    return state
+
+
+# --------------------------------------------------------------------------
+# 6. Capability gating (fixture adapter)
+# --------------------------------------------------------------------------
+
+
+def test_quantile_model_never_reaches_the_ghost_path_code(context):
+    adapter = _Fixture(output=OUTPUT_QUANTILE_LINE).load()
+    run = _Run(adapter, context)
+    html = shell.chart_section(_state(), _data([run], _state()))
+
+    assert "Quantile line only" in html
+    assert "Sampled OHLCV paths" not in html
+    # The ghost renderer's own opacity value must appear nowhere.
+    assert 'opacity="0.17"' not in html
+
+
+def test_path_model_gets_the_ghost_control_and_the_ghosts(context):
+    adapter = _Fixture(output=OUTPUT_OHLCV_PATHS).load()
+    run = _Run(adapter, context)
+    html = shell.chart_section(_state(ghosts=True), _data([run], _state()))
+
+    assert "Sampled OHLCV paths" in html
+    assert "Quantile line only" not in html
+
+
+def test_ghosts_are_suppressed_when_the_toggle_is_off(context):
+    adapter = _Fixture(output=OUTPUT_OHLCV_PATHS).load()
+    run = _Run(adapter, context)
+    drawing = chart.build(context, [run], "BTC-USD", run.horizon, show_ghosts=False)
+    assert 'opacity="0.17"' not in drawing["svg"]
+
+    drawing_on = chart.build(context, [run], "BTC-USD", run.horizon, show_ghosts=True)
+    assert 'opacity="0.17"' in drawing_on["svg"]
+
+
+def test_chart_ignores_paths_when_the_capability_does_not_declare_them(context):
+    """A result carrying paths but declaring `quantile_line` draws no ghosts.
+
+    This is the gate that matters: rendering keys off the declaration, not off
+    whether the array happens to be populated.
+    """
+    adapter = _Fixture(output=OUTPUT_OHLCV_PATHS).load()
+    run = _Run(adapter, context)
+    assert run.result.paths is not None
+    run.capabilities = {"output": OUTPUT_QUANTILE_LINE, "hardware": "cpu"}
+
+    drawing = chart.build(context, [run], "BTC-USD", run.horizon, show_ghosts=True)
+    assert 'opacity="0.17"' not in drawing["svg"]
+
+
+def test_hardware_capability_drives_the_cpu_gpu_chip(context):
+    for hardware, expected in (("cpu", "CPU · instant"), ("gpu", "your GPU quota")):
+        adapter = _Fixture(hardware=hardware).load()
+        run = _Run(adapter, context)
+        html = shell.models_section(_state(), _data([run], _state()))
+        assert expected in html
+
+
+def test_no_model_family_is_named_in_the_rendering_layer():
+    """The UI must not special-case a model by name.
+
+    Capability flags are the whole interface between adapters and rendering;
+    a name check here is how that boundary rots.
+    """
+    import pathlib
+
+    for name in ("shell.py", "chart.py"):
+        source = (pathlib.Path(__file__).resolve().parents[1]
+                  / "src" / "ui" / name).read_text().lower()
+        # Prose in docstrings is fine; a comparison against a model name is not.
+        for family in ("kronos", "chronos", "timesfm"):
+            assert f'== "{family}' not in source
+            assert f"'{family}'" not in source.replace("'kronos, chronos or timesfm'", "")
+
+
+# --------------------------------------------------------------------------
+# Design fidelity
+# --------------------------------------------------------------------------
+
+
+def test_every_design_system_stylesheet_reaches_the_page():
+    """Keyed on a rule only that file contains.
+
+    Vendoring the token files and forgetting `base.css` is the classic version
+    of this bug: the app inherits the framework's rounded corners and roomy
+    padding and looks approximately right in a way nobody can name.
+    """
+    css = chrome.full_css()
+    markers = {
+        "colors.css": "--bg-canvas",
+        "typography.css": "--text-2xs",
+        "spacing.css": "--tracking-wider",
+        "base.css": "user-select",
+    }
+    for filename, marker in markers.items():
+        assert marker in css, f"{filename} did not reach the page ({marker} missing)"
+
+
+def test_arena_css_reaches_the_page_too():
+    """`theme.full_css()` alone would silently drop the Arena's own rules."""
+    css = chrome.full_css()
+    for marker in (".fa-rail", ".fa-picker", ".fa-card", ".fa-chart"):
+        assert marker in css
+
+
+def test_nothing_forces_height_from_vh(context):
+    """`height:100vh` inside the Spaces iframe ratchets the page height."""
+    adapter = _Fixture(output=OUTPUT_OHLCV_PATHS).load()
+    run = _Run(adapter, context)
+    state = _state()
+    html = shell.page(state, _data([run], state))
+    offenders = theme.find_forced_vh(html)
+    assert not offenders, f"forced vh heights: {offenders}"
+
+
+def test_chart_uses_the_designs_geometry(context):
+    adapter = _Fixture().load()
+    run = _Run(adapter, context)
+    svg = chart.build(context, [run], "BTC-USD", run.horizon)["svg"]
+    assert 'viewBox="0 0 1200 352"' in svg
+
+
+def test_interpolated_values_are_escaped(context):
+    """Model ids and user text reach the markup; they must not become markup."""
+    state = _state(hfid='"><script>alert(1)</script>')
+    html = shell._enroll(state, _data([], state))
+    assert "<script>alert(1)" not in html
+    assert "&lt;script&gt;" in html or "&quot;&gt;" in html
+
+
+# --------------------------------------------------------------------------
+# 9. Error states
+# --------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize("kind,needle", [
+    ("quota", "SIGN IN"),
+    ("load_failure", "DUPLICATE THIS SPACE"),
+    ("no_data", "∅"),
+])
+def test_designed_error_states_render(kind, needle):
+    state = _state()
+    err = {"kind": kind, "title": "Something went wrong",
+           "message": "the detail", "login_url": "#", "duplicate_url": "#"}
+    html = shell.chart_section(state, _data([], state, error=err))
+    assert needle in html
+    assert "the detail" in html
+    assert "DISMISS" in html
+
+
+def test_quota_banner_renders_when_blocked():
+    state = _state()
+    html = shell.controls(state, _data([], state, quota_blocked=True,
+                                       quota_msg="GPU-tier model — sign in",
+                                       runtime_hint="BLOCKED"))
+    assert "GPU-tier model" in html
+    assert "BLOCKED" in html
+
+
+def test_rejected_enrollment_renders_its_message():
+    state = _state(enroll_ok=False,
+                   enroll_note="'nope' is not a supported adapter family.")
+    html = shell._enroll(state, _data([], state))
+    assert "not a supported adapter family" in html
+    assert "var(--fin-down)" in html
+
+
+def test_empty_track_record_renders_the_designed_state():
+    state = _state()
+    html = shell.trackrecord_section(state, _data([], state))
+    assert "No history yet" in html
+    assert "MAKE THE FIRST FORECAST" in html
+
+
+# --------------------------------------------------------------------------
+# Bridge
+# --------------------------------------------------------------------------
+
+
+def test_actions_off_the_allow_list_are_dropped():
+    assert chrome.parse_action("definitely-not-an-action:1|n") is None
+    assert chrome.parse_action("run:go|n1") is not None
+
+
+def test_emit_refuses_an_action_it_does_not_know():
+    with pytest.raises(Exception):
+        chrome.emit("not-a-real-action", "x")
+
+
+def test_sidebar_collapse_is_not_a_server_action():
+    """Routing it through Gradio would re-render the whole page to move a rail."""
+    assert "sidebar" not in chrome.ALLOWED_KEYS
+
+
+# --------------------------------------------------------------------------
+# The bridge actually reaches the markup
+# --------------------------------------------------------------------------
+
+
+def test_every_control_carries_a_real_data_bit_attribute(context):
+    """Regression: `emit()` returns the attribute *value*, not the attribute.
+
+    Interpolating it bare renders `<button run:go>` -- an unknown attribute,
+    no `data-bit`, so the delegated listener never matches and every control on
+    the page silently does nothing. Nothing else in the suite caught that,
+    because the markup was still well-formed and still contained the action
+    strings. This asserts the attribute, not the string.
+    """
+    adapter = _Fixture(output=OUTPUT_OHLCV_PATHS).load()
+    run = _Run(adapter, context)
+    state = _state()
+    html = shell.page(state, _data([run], state))
+
+    buttons = re.findall(r"<button\b[^>]*>", html)
+    assert len(buttons) > 12, f"only {len(buttons)} buttons rendered"
+
+    # The sidebar toggle is the one deliberate exception: collapsing is a
+    # client-side class flip (`data-bit-sidebar-toggle`), never a server
+    # action, because routing it through Gradio would re-render the whole page
+    # to move a rail 160px.
+    without = [b for b in buttons
+               if "data-bit=" not in b and "data-bit-sidebar-toggle" not in b]
+    assert not without, f"buttons with no data-bit: {without[:3]}"
+
+    # And the actions that reach it must be ones the bridge accepts.
+    for value in re.findall(r'data-bit="([^"]+)"', html):
+        assert chrome.parse_action(f"{value}|nonce") is not None, \
+            f"{value!r} would be dropped by the bridge"
+
+
+def test_the_run_control_is_present_and_addressable(context):
+    """The single most important control on the page."""
+    state = _state()
+    html = shell.controls(state, _data([], state))
+    assert 'data-bit="run:go"' in html

vendor/bit-ui/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.DS_Store
+key.txt
+*.key
+.env

vendor/bit-ui/README.md

@@ -0,0 +1,85 @@
+# bit-ui
+
+Shared chrome for The Bit Trading Company's Hugging Face Spaces: the App
+Sidebar, the design system's stylesheets and fonts, the Phosphor icon set, the
+click bridge, the ⌘K command palette, and the coming-soon / contact dialogs.
+
+Every BTC Space wears this, so a change here lands everywhere.
+
+## How a Space consumes it
+
+As a **git submodule**, vendored under the Space's app directory:
+
+```bash
+git submodule add https://github.com/Bit-Trading-Company/bit-ui space/vendor/bit-ui
+```
+
+```python
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).resolve().parent / "vendor" / "bit-ui"))
+
+from bit_ui import bridge, dialogs, nav, palette, sidebar, theme
+```
+
+The Space deploy uploads a folder, so the submodule's contents travel as
+ordinary files — no pip install, no build step, and no requirement that this
+repo be public.
+
+CI needs `submodules: recursive` on checkout.
+
+## Two mechanisms, on purpose
+
+| | Shared via | Changes reach a Space |
+|---|---|---|
+| **Code** (rendering, styles, bridge) | this repo, pinned per Space by the submodule commit | when that Space bumps and redeploys |
+| **Config** (nav links, launch status) | `nav.json` in the `bit-config` dataset, read at boot | on the Space's next restart — no redeploy |
+
+The split is the point. The thing that changes often — which modules are live,
+where they point — is data, so promoting a module from *coming soon* to *live*
+is one edit to one JSON file rather than nine pull requests. The thing that
+changes rarely is code, and it is pinned so a bad change cannot break every
+Space at once.
+
+## Modules
+
+| Module | What |
+|---|---|
+| `nav.py` | the shared navigation document: load, validate, fall back |
+| `sidebar.py` | the App Sidebar, collapsible, collapsed by default |
+| `palette.py` | the ⌘K command palette and the live search bar |
+| `dialogs.py` | coming-soon and contact modals |
+| `theme.py` | design-system CSS, Gradio theme, the forced-`vh` checker |
+| `bridge.py` | design `<button>`s → Python actions |
+| `icons.py` | vendored Phosphor paths (MIT) |
+| `markup.py` | `e()` / `a()` escaping |
+
+## Rules
+
+1. **Escape everything interpolated.** `nav.json` is data, and it reaches every
+   Space at once.
+2. **Never force height from `vh`.** `height:100vh` / `min-height:100vh` inside
+   the Spaces iframe ratchets the page height — measured at 3890px against
+   2100px of real content. `max-height` is fine. `theme.find_forced_vh()` and
+   the test suite enforce this.
+3. **Never name a module after a stdlib module.** `html.py` at a package root
+   shadows the real `html` for the whole process; it broke pytest before it was
+   renamed to `markup.py`.
+4. **Don't ship placeholder details.** No `555` phone numbers, no invented
+   build-progress percentages. If it is not real, it does not render.
+5. **Key CSS off a class on the element, not `body`.** Gradio re-emits every
+   rule prefixed `.gradio-container … .contain`; a `body`-rooted selector
+   cannot be prefixed, so only the weak unprefixed copy survives and it loses
+   to the prefixed base rule.
+6. **Purely visual state stays client-side.** Every Gradio action re-renders
+   and re-sends the whole page. The sidebar collapse is a class flip in
+   `bridge.py`, with `<body data-sidebar>` as the source of truth because it
+   survives a re-render.
+
+## Tests
+
+```bash
+python -m pytest tests/ -q
+```
+
+Offline, no credentials. 40 tests.

vendor/bit-ui/bit_ui/__init__.py

@@ -0,0 +1,41 @@
+"""bit-ui — shared chrome for The Bit Trading Company's Hugging Face Spaces.
+
+Every BTC Space wears the same shell: the App Sidebar, the design system's
+stylesheets and fonts, the Phosphor icon set, the click bridge that lets the
+design's own `<button>`s reach Python, and the coming-soon / contact dialogs.
+This package is that shell, in one place, so a change lands everywhere.
+
+It is consumed as a **git submodule mounted at `space/src/bit_ui/`**. The Space
+deploy uploads a folder, so the submodule's contents travel as ordinary files
+— no pip install, no build step, and no requirement that this repo be public.
+
+Two things are shared, by two different mechanisms, on purpose:
+
+  **Code** — this package. Pinned per Space by the submodule commit, so a bad
+  change here cannot break all nine Spaces at once. Bump deliberately.
+
+  **Config** — `nav.py` reads the navigation (which modules exist, which are
+  live, where they point) from a shared Hugging Face dataset at boot, with a
+  baked-in fallback. Flipping a module from "coming soon" to live updates every
+  Space on its next restart, with no redeploy and no submodule bump anywhere.
+
+That split is the point: the thing that changes often (links, launch status) is
+data, and the thing that changes rarely (how it renders) is code.
+
+Usage:
+
+    from src.bit_ui import bridge, dialogs, icons, nav, sidebar, theme
+
+    navigation = nav.load()
+    html = sidebar.render(navigation, active="Finance Atlas", collapsed=True)
+"""
+
+from __future__ import annotations
+
+__version__ = "1.0.0"
+
+from . import (bridge, dialogs, icons, markup, nav, palette,  # noqa: F401
+               sidebar, theme)
+
+__all__ = ["bridge", "dialogs", "icons", "markup", "nav", "palette",
+           "sidebar", "theme", "__version__"]

vendor/bit-ui/bit_ui/assets/fonts/MacMinecraft.ttf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8a437149023107ac856b4d305ac6c9a6f810273895d23437156378ccf505aa81
+size 252332

vendor/bit-ui/bit_ui/assets/fonts/StyreneA-Light.otf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:48979155896cea590bb6085850a98bf7ccb5b48e9761ad03b8e8f671e92c746c
+size 134944

vendor/bit-ui/bit_ui/assets/fonts/StyreneA-Medium.otf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:012e4c8b383b2e9b6758524018a81352e3cd61e2967a4ed5b8b127890e46994c
+size 141072

vendor/bit-ui/bit_ui/assets/fonts/StyreneA-Regular.otf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0d282ef9078d7899784c452efef335121768aedc33283ae5b4b4c225e1a176e9
+size 134580

vendor/bit-ui/bit_ui/assets/fonts/StyreneA-Thin.otf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0a71505a658d6ddfb2327afc23e235d1d276ef15e30a857f1e642a5b42f4ce9f
+size 133416

vendor/bit-ui/bit_ui/assets/tokens/base.css

@@ -0,0 +1,33 @@
+*{box-sizing:border-box;border-radius:0 !important;user-select:none}
+input,textarea,[contenteditable],code,kbd,.mono-data,.bit-selectable{user-select:text}
+@keyframes bitFadeIn{from{opacity:0}to{opacity:1}}
+@keyframes bitPopIn{from{opacity:0;transform:scale(0.96)}to{opacity:1;transform:scale(1)}}
+@keyframes bitPopUp{from{opacity:0;transform:translateY(8px) scale(0.9)}to{opacity:1;transform:translateY(0) scale(1)}}
+html,body{margin:0;padding:0;background:var(--bg-canvas);color:var(--text-primary);font-family:var(--font-body);font-weight:var(--weight-body);font-size:var(--text-base);line-height:var(--leading-normal)}
+h1,h2,h3,h4,h5,h6{font-family:var(--font-heading);font-weight:var(--weight-heading);margin:0;text-transform:uppercase;letter-spacing:var(--tracking-wide)}
+a{color:var(--accent-amber);text-decoration:none;transition:color var(--duration) var(--ease)}
+a:hover{color:var(--accent-amber-strong);text-decoration:underline}
+.styrene-text{font-family:var(--font-styrene);font-weight:var(--weight-styrene-thin);text-transform:none;letter-spacing:normal}
+.small-caps{font-variant:small-caps;text-transform:lowercase;letter-spacing:var(--tracking-wide)}
+.pixel-text,.mono-tiny{font-family:var(--font-tiny);font-weight:var(--weight-tiny);font-size:8px !important;letter-spacing:0;text-transform:uppercase}
+code,kbd,.mono-data{font-family:var(--font-mono);font-weight:var(--weight-mono);font-variant-numeric:tabular-nums;letter-spacing:0}
+:focus-visible{outline:2px solid var(--focus-ring);outline-offset:2px}
+.bit-btn-secondary:not(:disabled):hover,.bit-btn-ghost:not(:disabled):hover{background:var(--accent-amber);color:var(--stone-950);border-color:var(--accent-amber)}
+.bit-btn-primary:not(:disabled):hover{background:var(--stone-950);color:var(--accent-amber);border-color:var(--accent-amber)}
+.bit-btn-danger:not(:disabled):hover{background:var(--off-white);color:var(--mute-red);border-color:var(--mute-red)}
+.bit-btn-buy:not(:disabled):hover{background:var(--fin-buy-strong);color:var(--stone-950);border-color:var(--fin-buy-strong)}
+.bit-btn-sell:not(:disabled):hover{background:var(--fin-sell-strong);color:var(--stone-950);border-color:var(--fin-sell-strong)}
+.bit-btn:not(:disabled):active{filter:brightness(0.9)}
+.bit-iconbtn:hover{background:var(--bg-raised);border-color:var(--border-default)}
+.bit-avatar{border-radius:50% !important}
+.bit-pill{border-radius:999px !important}
+.bit-rounded-sm{border-radius:var(--radius-sm) !important}
+.bit-rounded{border-radius:var(--radius-md) !important}
+.bit-glass{background:var(--glass-bg);backdrop-filter:blur(var(--glass-blur));-webkit-backdrop-filter:blur(var(--glass-blur));border:1px solid var(--glass-border)}
+.bit-menu-item:hover{background:var(--bg-raised)}
+.bit-vote:hover{color:var(--text-primary) !important}
+::selection{background:var(--accent-amber);color:var(--stone-950)}
+*{scrollbar-color:var(--bg-canvas) var(--bg-canvas)}
+::-webkit-scrollbar{width:12px;height:12px}
+::-webkit-scrollbar-track{background:var(--bg-canvas);border-radius: 0;}
+::-webkit-scrollbar-thumb{background:var(--bg-canvas);border-radius: 0;border:2px solid var(--border-strong);}

vendor/bit-ui/bit_ui/assets/tokens/colors.css

@@ -0,0 +1,125 @@
+:root{
+--pure-black:#000000;
+--pure-white:#ffffff;
+--stone-950:#161512;
+--stone-900:#1d1c18;
+--stone-850:#24221d;
+--stone-800:#2c2a24;
+--stone-700:#3d3a32;
+--stone-600:#54503f;
+--stone-500:#6f6a56;
+--stone-400:#918c76;
+--stone-300:#b6b09a;
+--stone-200:#d6d1bf;
+--stone-100:#ece8dc;
+--stone-50:#f5f3ea;
+--off-white:#f7f4ec;
+
+--accent-moss:#68781e;
+--accent-moss-strong:#7d901f;
+--accent-moss-dim:#4d5817;
+--accent-amber:#af9209;
+--accent-amber-strong:#cfab0a;
+--accent-amber-dim:#7d6a09;
+
+--mute-red:#8a5a54;
+--mute-orange:#8a6f54;
+--mute-yellow:#8a8154;
+--mute-green:#6e8a54;
+--mute-teal:#54898a;
+--mute-blue:#59656e;
+--mute-indigo:#5c5c8a;
+--mute-violet:#75588a;
+
+--fin-up:oklch(66% 0.22 149);
+--fin-up-strong:oklch(72% 0.24 149);
+--fin-down:oklch(62% 0.26 24);
+--fin-down-strong:oklch(68% 0.27 24);
+--fin-flat:var(--stone-400);
+--fin-up-cvd:oklch(58% 0.13 240);
+--fin-up-cvd-strong:oklch(64% 0.14 240);
+--fin-down-cvd:oklch(58% 0.13 55);
+--fin-down-cvd-strong:oklch(64% 0.14 55);
+--fin-buy:var(--fin-up);
+--fin-buy-strong:var(--fin-up-strong);
+--fin-sell:var(--fin-down);
+--fin-sell-strong:var(--fin-down-strong);
+
+--focus-ring:var(--accent-amber);
+
+--bg-canvas:var(--stone-950);
+--bg-panel:var(--stone-900);
+--bg-raised:var(--stone-850);
+--bg-sunken:var(--pure-black);
+--border-subtle:var(--stone-800);
+--border-default:var(--stone-700);
+--border-strong:var(--stone-500);
+--text-primary:var(--off-white);
+--text-secondary:var(--stone-300);
+--text-tertiary:var(--stone-500);
+--text-disabled:var(--stone-600);
+--text-inverse:var(--stone-950);
+--surface-accent-fg:var(--stone-950);
+
+--glass-bg:rgba(29,28,24,0.72);
+--glass-border:rgba(247,244,236,0.14);
+--glass-blur:20px;
+}
+[data-theme="dark"]{
+--bg-canvas:var(--stone-950);
+--bg-panel:var(--stone-900);
+--bg-raised:var(--stone-850);
+--bg-sunken:var(--pure-black);
+--border-subtle:var(--stone-800);
+--border-default:var(--stone-700);
+--border-strong:var(--stone-500);
+--text-primary:var(--off-white);
+--text-secondary:var(--stone-300);
+--text-tertiary:var(--stone-500);
+--text-disabled:var(--stone-600);
+--text-inverse:var(--stone-950);
+--surface-accent-fg:var(--stone-950);
+}
+[data-colorblind="true"]{
+--fin-up:var(--fin-up-cvd);
+--fin-up-strong:var(--fin-up-cvd-strong);
+--fin-down:var(--fin-down-cvd);
+--fin-down-strong:var(--fin-down-cvd-strong);
+}
+[data-theme="light"]{
+--bg-canvas:var(--off-white);
+--bg-panel:var(--stone-50);
+--bg-raised:var(--pure-white);
+--bg-sunken:var(--stone-100);
+--border-subtle:var(--stone-200);
+--border-default:var(--stone-300);
+--border-strong:var(--stone-500);
+--text-primary:var(--stone-950);
+--text-secondary:var(--stone-700);
+--text-tertiary:var(--stone-500);
+--text-disabled:var(--stone-300);
+--text-inverse:var(--off-white);
+--surface-accent-fg:var(--stone-950);
+--glass-bg:rgba(245,243,234,0.72);
+--glass-border:rgba(22,21,18,0.1);
+}
+/* Custom themes: copy this block, rename the [data-theme] value, and override only
+the tokens that should change. Every component reads these tokens, never raw colors,
+so a new theme needs no component edits — set data-theme on any ancestor (SidebarNav's
+theme selector does this at the app root) and everything downstream updates. */
+[data-theme="custom"]{
+--bg-canvas:var(--stone-950);
+--bg-panel:var(--stone-900);
+--bg-raised:var(--stone-850);
+--bg-sunken:var(--pure-black);
+--border-subtle:var(--stone-800);
+--border-default:var(--stone-700);
+--border-strong:var(--accent-amber-dim);
+--text-primary:var(--off-white);
+--text-secondary:var(--stone-300);
+--text-tertiary:var(--stone-500);
+--text-disabled:var(--stone-600);
+--text-inverse:var(--stone-950);
+--surface-accent-fg:var(--stone-950);
+}
+

vendor/bit-ui/bit_ui/assets/tokens/spacing.css

@@ -0,0 +1,29 @@
+:root{
+--space-0:0px;
+--space-1:4px;
+--space-2:8px;
+--space-3:12px;
+--space-4:16px;
+--space-5:24px;
+--space-6:32px;
+--space-7:48px;
+--space-8:64px;
+--space-9:96px;
+
+--radius-0:0px;
+--radius-sm:4px;
+--radius-md:8px;
+--radius-pill:999px;
+--border-width:1px;
+--border-width-strong:2px;
+
+--ease:ease;/* @kind other */
+--duration:1s;/* @kind other */
+
+--shadow-none:none;
+--shadow-panel:0 0 0 var(--border-width) var(--border-default);
+--z-header:100;/* @kind other */
+--z-menu:200;/* @kind other */
+--z-modal:300;/* @kind other */
+--z-toast:400;/* @kind other */
+}

vendor/bit-ui/bit_ui/assets/tokens/typography.css

@@ -0,0 +1,38 @@
+:root{
+--font-styrene:'Styrene A',sans-serif;
+--font-system:-apple-system,BlinkMacSystemFont,system-ui,sans-serif;
+--font-mono:'JetBrains Mono',ui-monospace,'SFMono-Regular',Menlo,monospace;
+--font-tiny:'Mac Minecraft',monospace;
+--font-body:var(--font-system);
+--font-heading:var(--font-styrene);
+--weight-heading:400;
+--weight-body:300;
+--weight-styrene-thin:100;
+--weight-styrene-light:300;
+--weight-styrene-regular:400;
+--weight-styrene-medium:500;
+--weight-mono:400;
+--weight-tiny:400;
+--weight-strong:700;
+
+--text-2xs:8px;
+--text-xs:10px;
+--text-sm:11px;
+--text-base:12px;
+--text-md:16px;
+--text-lg:19px;
+--text-xl:25px;
+--text-2xl:33px;
+--text-3xl:45px;
+--text-4xl:62px;
+
+--leading-tight:1.1;
+--leading-snug:1.3;
+--leading-normal:1.5;
+--leading-relaxed:1.7;
+
+--tracking-tight:-0.01em;
+--tracking-normal:0;
+--tracking-wide:0.04em;
+--tracking-wider:0.12em;
+}

vendor/bit-ui/bit_ui/bridge.py

@@ -0,0 +1,329 @@
+"""Click bridge: the design's markup in, Python state out.
+
+The designs are built from real `<button>` elements with exact inline styles.
+Gradio renders a structurally different DOM for the same concepts — a
+`gr.Radio` is a `<fieldset>` of `<label>`s wrapping hidden inputs — so
+restyling Gradio's controls only ever approximates the design. Instead the
+visible layer is the design's own markup, and this module is how a real
+`<button>` reaches Python:
+
+    <button data-bit="sort:Likes">Likes</button>
+                |
+                |  delegated listener (installed via demo.load(js=...))
+                v
+    hidden Textbox #bit-action  <- value set via the native setter
+                |
+                v
+    hidden Button #bit-trigger clicked -> Python handler -> re-render
+
+A nonce is appended to every action because Gradio's `.change()` only fires
+when the value actually differs; clicking the same button twice must still
+register.
+
+## Allow-lists are per Space
+
+This module owns the mechanism; each Space owns its vocabulary. `SHARED_KEYS`
+covers what bit-ui's own components emit (the sidebar toggle, the dialogs);
+a Space unions its own keys on top and builds an emitter:
+
+    ALLOWED_KEYS = bridge.SHARED_KEYS | frozenset({"task", "sort", ...})
+    emit = bridge.make_emitter(ALLOWED_KEYS)
+
+Nothing here evaluates anything. Actions are `key:value` pairs, the key must be
+on the caller's allow-list, and the value is returned as an opaque string for
+the caller to validate against its own domain.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# What bit-ui's own components emit. A Space that renders the sidebar or the
+# dialogs must allow these, or its own chrome will not respond.
+SHARED_KEYS = frozenset({
+    "sidebar",      # sidebar:toggle -- collapse / expand the rail
+    "soon",         # soon:<module> to open, soon:close to dismiss
+    "contact",      # contact:open | contact:close | contact:form | contact:send
+    "topic",        # topic:<name> -- contact form topic chip
+    "notify",       # notify:<module> -- "tell me when this launches"
+    "nemail",       # the address typed into that dialog's field
+    "cname", "cemail", "cmsg",   # contact form fields (arrive as key=value)
+    "palette",      # palette:open | palette:close | palette:go=<target>
+    "pq",           # palette query -- arrives live as pq=<text> while typing
+    "noop",         # explicit no-op; also stops click-through on dialog panels
+})
+
+ACTION_ELEMENT_ID = "bit-action"
+TRIGGER_ELEMENT_ID = "bit-trigger"
+
+# Separates the action from its nonce. A pipe rather than a space because
+# action values are human-readable names -- "Recently updated", "Data
+# correction" -- which legitimately contain spaces. No value contains a pipe.
+NONCE_SEP = "|"
+
+
+@dataclass(frozen=True)
+class Action:
+    key: str
+    value: str
+
+    @property
+    def is_noop(self) -> bool:
+        return self.key == "noop"
+
+
+def emit(action: str, value: str = "") -> str:
+    """Build a `data-bit` value from either `"key:value"` or (key, value).
+
+    Accepts the combined form so bit-ui's components can emit `"soon:close"`
+    without knowing the host's emitter signature.
+    """
+    if ":" in action and not value:
+        key, _, value = action.partition(":")
+    else:
+        key = action
+    if NONCE_SEP in str(value):
+        raise ValueError(f"action values may not contain {NONCE_SEP!r}")
+    return f"{key}:{value}"
+
+
+def make_emitter(allowed):
+    """An `emit` that refuses any key not on this Space's allow-list.
+
+    Failing at render time rather than silently at click time is the point: a
+    control the bridge would drop is a control that does nothing, and that is
+    much cheaper to find here.
+    """
+    allowed = frozenset(allowed)
+
+    def _emit(action: str, value: str = "") -> str:
+        key = action.partition(":")[0] if ":" in action and not value else action
+        if key not in allowed:
+            raise ValueError(
+                f"{key!r} is not an allowed UI action "
+                f"(add it to ALLOWED_KEYS)")
+        return emit(action, value)
+
+    return _emit
+
+
+def parse_action(raw, allowed=None):
+    """Parse what the bridge wrote into the hidden textbox.
+
+    Returns None for anything unparseable or off the allow-list, so a
+    malformed or hand-crafted payload is ignored rather than raising.
+    """
+    if not raw or not isinstance(raw, str):
+        return None
+    payload = raw.split(NONCE_SEP, 1)[0]
+    if ":" not in payload:
+        return None
+    key, _, value = payload.partition(":")
+    key = key.strip()
+    if allowed is not None and key not in allowed:
+        return None
+    return Action(key=key, value=value.strip())
+
+
+def parse_pair(value: str):
+    """Split a compound action value like `fast_ma=20` -> ("fast_ma", "20")."""
+    name, _, val = value.partition("=")
+    return name.strip(), val.strip()
+
+
+# `demo.load(js=...)` takes a JS *function*. Spaces drops
+# `gr.Blocks(head=...)`, so this is the path that actually works once deployed.
+BRIDGE_LOAD_JS = """
+() => {
+  if (window.__bitBridgeInstalled) return;
+  window.__bitBridgeInstalled = true;
+
+  function holder() {
+    var root = document.getElementById('__ELEM_ID__');
+    return root ? root.querySelector('textarea, input') : null;
+  }
+
+  function send(payload) {
+    var box = holder();
+    if (!box) return;
+    var nonce = Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
+
+    // Assigning .value does not reliably wake Svelte's binding, so the native
+    // setter is used and both events are dispatched...
+    var proto = box.tagName === 'TEXTAREA'
+      ? window.HTMLTextAreaElement.prototype : window.HTMLInputElement.prototype;
+    var setter = Object.getOwnPropertyDescriptor(proto, 'value').set;
+    setter.call(box, payload + '|' + nonce);
+    box.dispatchEvent(new Event('input', { bubbles: true }));
+    box.dispatchEvent(new Event('change', { bubbles: true }));
+
+    // ...and a hidden Gradio Button is then clicked. A real click on a real
+    // Button is the one event path Gradio always honours, so the handler fires
+    // even if the textbox binding did not register.
+    var trigger = document.getElementById('__TRIGGER_ID__');
+    var btn = trigger ? (trigger.tagName === 'BUTTON'
+                         ? trigger : trigger.querySelector('button')) : null;
+    if (btn) { setTimeout(function () { btn.click(); }, 0); }
+  }
+  window.__bitSend = send;
+
+  // The sidebar collapse is pure presentation, so it is handled entirely
+  // here: flip an attribute on <body> and stop. No server call, no re-render.
+  // Round-tripping it meant re-sending the whole page (1.16 MB on the Atlas,
+  // 95% of it the model table) to move a rail 160px -- 1.5-2.2s for something
+  // that should be instant.
+  //
+  // <body> and not a wrapper inside the app: everything inside the gr.HTML
+  // sink is replaced on the next re-render, which would reset the rail.
+  var SIDEBAR_KEY = 'bit-sidebar';
+  // The class goes on the rail itself. Gradio emits a scoped copy of every
+  // rule prefixed with `.gradio-container ... .contain`, and a selector rooted
+  // at `body` cannot be prefixed legally, so it silently loses the cascade to
+  // the prefixed base rule. <body> stays the source of truth because it
+  // survives a re-render; `applySidebar` mirrors it onto the rail.
+  function applySidebar() {
+    var expanded = document.body.getAttribute('data-sidebar') === 'expanded';
+    var rail = document.querySelector('.bit-sidebar');
+    if (rail) {
+      rail.classList.toggle('is-expanded', expanded);
+    }
+    var btn = document.querySelector('[data-bit-sidebar-toggle]');
+    if (btn) {
+      btn.setAttribute('aria-expanded', expanded ? 'true' : 'false');
+      btn.setAttribute('title', (expanded ? 'Collapse' : 'Expand') + ' sidebar');
+    }
+  }
+
+  function setSidebar(expanded) {
+    if (expanded) { document.body.setAttribute('data-sidebar', 'expanded'); }
+    else { document.body.removeAttribute('data-sidebar'); }
+    applySidebar();
+    try { localStorage.setItem(SIDEBAR_KEY, expanded ? 'expanded' : 'collapsed'); }
+    catch (err) {}
+  }
+  try {
+    if (localStorage.getItem(SIDEBAR_KEY) === 'expanded') setSidebar(true);
+  } catch (err) {}
+
+  document.addEventListener('click', function (e) {
+    var toggle = e.target && e.target.closest
+      ? e.target.closest('[data-bit-sidebar-toggle]') : null;
+    if (toggle) {
+      e.preventDefault();
+      e.stopPropagation();
+      setSidebar(document.body.getAttribute('data-sidebar') !== 'expanded');
+      return;
+    }
+
+    var el = e.target && e.target.closest ? e.target.closest('[data-bit]') : null;
+    if (!el) return;
+    var action = el.getAttribute('data-bit');
+    // `noop:` stops the closest() walk without acting -- it is what keeps a
+    // click inside a dialog panel from reaching the backdrop's close action.
+    if (!action || action.indexOf('noop:') === 0) return;
+    e.preventDefault();
+    e.stopPropagation();
+    send(action);
+  }, true);
+
+  // Text and number fields commit on blur / Enter, not per keystroke, so a
+  // re-render is not triggered on every character typed.
+  // NOTE the ':' separator. Fields used to send `key=value`, which has no
+  // colon, and `parse_action` splits on ':' -- so every keystroke was parsed
+  // as an unknown action and dropped. The search box silently did nothing.
+  function commit(el) {
+    if (!el || !el.hasAttribute || !el.hasAttribute('data-bit-input')) return;
+    send(el.getAttribute('data-bit-input') + ':' + el.value);
+  }
+  document.addEventListener('change', function (e) { commit(e.target); }, true);
+  document.addEventListener('keydown', function (e) {
+    if (e.key === 'Enter' && e.target && e.target.tagName !== 'TEXTAREA') {
+      commit(e.target);
+    }
+  }, true);
+
+  // Live fields (`data-bit-live`) send as you type, debounced. Search wants
+  // this: waiting for Enter to see whether anything matched is the difference
+  // between a search box and a form field. The debounce is what stops it from
+  // being one round trip per keystroke.
+  var liveTimer = null, liveLast = null;
+  document.addEventListener('input', function (e) {
+    var el = e.target;
+    if (!el || !el.hasAttribute || !el.hasAttribute('data-bit-live')) return;
+    var key = el.getAttribute('data-bit-live');
+    var val = el.value;
+    if (val === liveLast) return;
+    liveLast = val;
+    clearTimeout(liveTimer);
+    liveTimer = setTimeout(function () { send(key + ':' + val); }, 220);
+  }, true);
+
+  // Palette keyboard navigation. Arrow keys move the highlight and Enter
+  // activates it, entirely client-side -- a server round trip per arrow press
+  // would make the list feel broken.
+  function paletteRows() {
+    return Array.prototype.slice.call(
+      document.querySelectorAll('[data-bit-option]'));
+  }
+  function highlight(rows, next) {
+    rows.forEach(function (r, i) {
+      var on = i === next;
+      r.setAttribute('data-active', on ? '1' : '0');
+      if (on && r.scrollIntoView) r.scrollIntoView({ block: 'nearest' });
+    });
+  }
+  document.addEventListener('keydown', function (e) {
+    if (e.key !== 'ArrowDown' && e.key !== 'ArrowUp' && e.key !== 'Enter') return;
+    var rows = paletteRows();
+    if (!rows.length) return;
+    var cur = rows.findIndex(function (r) {
+      return r.getAttribute('data-active') === '1'; });
+    if (e.key === 'Enter') {
+      if (cur < 0) return;
+      e.preventDefault();
+      e.stopPropagation();
+      rows[cur].click();
+      return;
+    }
+    e.preventDefault();
+    var next = e.key === 'ArrowDown'
+      ? (cur + 1) % rows.length
+      : (cur <= 0 ? rows.length - 1 : cur - 1);
+    highlight(rows, next);
+  }, true);
+
+  // Keyboard shortcuts declared in the markup as data-bit-key="<combo>".
+  // Cmd/Ctrl+K opens the command palette; Escape closes whatever is open.
+  document.addEventListener('keydown', function (e) {
+    var mod = e.metaKey || e.ctrlKey;
+    if (mod && (e.key === 'k' || e.key === 'K')) {
+      e.preventDefault();
+      send('palette:open');
+      return;
+    }
+    if (e.key === 'Escape') {
+      var el = document.querySelector('[data-bit-escape]');
+      if (el) { e.preventDefault(); send(el.getAttribute('data-bit-escape')); }
+    }
+  }, true);
+
+  // Focus whatever the freshly rendered page asks for -- the palette input
+  // after Cmd+K, without which the shortcut opens a box you must then click.
+  var focusPending = null;
+  function applyAutofocus() {
+    var el = document.querySelector('[data-bit-autofocus]');
+    if (!el || el === focusPending) return;
+    focusPending = el;
+    setTimeout(function () {
+      try { el.focus(); if (el.select) el.select(); } catch (err) {}
+    }, 30);
+  }
+  // A re-render replaces the rail and the toggle, so both are restored from
+  // the attribute that survived on <body>.
+  new MutationObserver(function () { applyAutofocus(); applySidebar(); })
+    .observe(document.body, { childList: true, subtree: true });
+  applyAutofocus();
+  applySidebar();
+}
+""".replace("__ELEM_ID__", ACTION_ELEMENT_ID).replace(
+    "__TRIGGER_ID__", TRIGGER_ELEMENT_ID)

vendor/bit-ui/bit_ui/dialogs.py

@@ -0,0 +1,311 @@
+"""Coming-soon and contact dialogs.
+
+Both follow the design's own markup. Two deliberate departures, both for the
+same reason — a public page should not carry details that are not real:
+
+**No placeholder contact details.** The design fills the contact card with
+`atlas@bittrading.co` and `+1 617 555 0142`. The `555` prefix is reserved for
+fiction, and a phone number that rings nowhere is worse than no phone number.
+Channels come from `nav.json` instead, so real ones can be added without a
+code change, and only what is configured renders.
+
+**No invented progress bar.** The design shows BUILD PROGRESS at 64%, 72%, 58%.
+Nobody is tracking those numbers. The bar renders only when `nav.json` gives a
+real percentage for that module; otherwise the dialog says the module is in
+build and leaves it there.
+
+Both dialogs emit actions through the host Space's bridge. The host is
+responsible for handling `contact:close`, `soon:close`, `contact:send` and
+`notify:<module>` — see `ALLOWED_KEYS` in its bridge module.
+"""
+
+from __future__ import annotations
+
+from .markup import a, e
+from .icons import icon
+
+# The panel carries a `noop:` marker so a click inside it does not bubble up to
+# the backdrop's close action and dismiss the dialog mid-typing. The bridge
+# returns early on `noop:`, which stops `closest('[data-bit]')` at the panel.
+PANEL_GUARD = 'data-bit="noop:"'
+
+
+def _close_button(action: str, emit) -> str:
+    return (
+        f'<button type="button" data-bit="{a(emit(action))}" title="Close" '
+        f'aria-label="Close" class="bit-hover-strong" '
+        f'style="margin-left:auto;background:transparent;'
+        f'border:1px solid var(--border-default);color:var(--text-tertiary);'
+        f'width:22px;height:22px;display:flex;align-items:center;'
+        f'justify-content:center;cursor:pointer">{icon("close", "11px")}</button>'
+    )
+
+
+def _backdrop(action: str, emit, z: int, body: str) -> str:
+    return (
+        f'<div data-bit="{a(emit(action))}" style="position:fixed;inset:0;'
+        f'z-index:{z};background:rgba(10,10,8,0.6);display:flex;'
+        f'align-items:center;justify-content:center;padding:24px;'
+        f'animation:bitFade 0.3s ease">{body}</div>'
+    )
+
+
+# --------------------------------------------------------------------------
+# Coming soon
+# --------------------------------------------------------------------------
+
+
+def coming_soon(item: dict, navigation: dict, emit, notice: str = "") -> str:
+    """The dialog shown for a module that is planned but not built."""
+    if not item:
+        return ""
+
+    name = item.get("name", "")
+    kind = item.get("kind") or "SPACE · IN BUILD"
+    progress = item.get("progress")
+
+    if progress is None:
+        # No real figure, so no bar. Said plainly rather than drawn vaguely.
+        progress_block = (
+            f'<div style="display:flex;align-items:center;gap:8px;padding:7px 9px;'
+            f'border:1px solid var(--border-subtle);background:var(--bg-raised)">'
+            f'<span class="pixel-text" style="color:var(--text-tertiary)">·</span>'
+            f'<span class="mono-data" style="font-size:var(--text-2xs);'
+            f'color:var(--text-tertiary)">NO PUBLISHED BUILD DATE</span></div>'
+        )
+    else:
+        progress_block = (
+            f'<div><div style="display:flex;justify-content:space-between;'
+            f'margin-bottom:5px">'
+            f'<span class="mono-data" style="font-size:var(--text-2xs);'
+            f'color:var(--text-tertiary)">BUILD PROGRESS</span>'
+            f'<span class="mono-data" style="font-size:var(--text-2xs);'
+            f'color:var(--accent-amber-strong)">{progress}%</span></div>'
+            f'<div style="height:6px;background:var(--bg-raised);'
+            f'border:1px solid var(--border-default);position:relative;'
+            f'overflow:hidden"><div style="position:absolute;left:0;top:0;'
+            f'bottom:0;width:{progress}%;background:var(--accent-amber)"></div>'
+            f'</div></div>'
+        )
+
+    live = [i for g in navigation.get("groups") or ()
+            for i in g.get("items") or ()
+            if i.get("status") == "live" and i.get("url")]
+    if live:
+        target = live[0]
+        live_row = (
+            f'<div style="display:flex;align-items:center;gap:10px;'
+            f'border-top:1px solid var(--border-subtle);padding-top:10px">'
+            f'<span class="pixel-text" style="color:var(--text-tertiary)">'
+            f'OR OPEN A TOOL THAT IS LIVE</span>'
+            f'<a href="{a(target["url"])}" target="_blank" rel="noopener noreferrer" '
+            f'class="bit-hover-connect" style="margin-left:auto;'
+            f'display:inline-flex;align-items:center;gap:6px;padding:4px 9px;'
+            f'border:1px solid var(--accent-amber-dim);'
+            f'color:var(--accent-amber-strong);text-decoration:none">'
+            f'<span style="font-family:var(--font-styrene);'
+            f'font-size:var(--text-xs);text-transform:uppercase;'
+            f'letter-spacing:var(--tracking-wide);white-space:nowrap;'
+            f'margin-top:2px">{e(target["name"])}</span>'
+            f'{icon("chevronRight", "11px")}</a></div>'
+        )
+    else:
+        live_row = ""
+
+    note = ""
+    if notice:
+        note = (f'<span class="mono-data" style="font-size:var(--text-2xs);'
+                f'color:var(--accent-moss-strong)">{e(notice)}</span>')
+
+    body = f"""
+<div {PANEL_GUARD} role="dialog" aria-modal="true" aria-label="{a(name)} — coming soon"
+     style="width:min(460px,100%);background:var(--bg-panel);
+     border:1px solid var(--border-strong)">
+  <div style="display:flex;align-items:center;gap:8px;padding:8px 12px;
+       border-bottom:1px solid var(--border-default);background:var(--bg-raised)">
+    <span style="display:inline-block;width:6px;height:6px;
+          background:var(--accent-amber);animation:bitPulse 2s ease-in-out infinite"></span>
+    <span style="font-family:var(--font-styrene);font-size:var(--text-2xs);
+          text-transform:uppercase;letter-spacing:var(--tracking-wider);
+          color:var(--text-tertiary)">Coming soon</span>
+    {_close_button('soon:close', emit)}
+  </div>
+  <div style="padding:18px 16px;display:flex;flex-direction:column;gap:14px;
+       position:relative;overflow:hidden">
+    <div aria-hidden="true" style="position:absolute;left:0;right:0;top:0;
+         height:1px;background:var(--accent-amber);opacity:0.55"></div>
+    <div style="display:flex;align-items:center;gap:12px">
+      <span aria-hidden="true" style="flex:0 0 auto;width:40px;height:40px;
+            display:flex;align-items:center;justify-content:center;
+            border:1px solid var(--border-default);background:var(--bg-raised);
+            color:var(--text-tertiary)">{icon(item.get('icon') or 'cube', '20px')}</span>
+      <div style="min-width:0">
+        <div style="font-family:var(--font-styrene);font-size:var(--text-lg);
+             text-transform:uppercase;letter-spacing:var(--tracking-wide);
+             line-height:var(--leading-tight)">{e(name)}</div>
+        <div class="mono-data" style="font-size:var(--text-2xs);
+             color:var(--text-tertiary);margin-top:3px">{e(kind)}</div>
+      </div>
+    </div>
+    <div style="color:var(--text-secondary);text-wrap:pretty">This Space is
+      still in build. Finance Atlas and Backtest Lab are the tools open right
+      now — everything else unlocks as it clears validation.</div>
+    {progress_block}
+    <div style="display:flex;gap:8px;align-items:center">
+      <input data-bit-input="nemail" type="email" placeholder="you@firm.com"
+        aria-label="Email me when {a(name)} launches"
+        style="flex:1 1 auto;min-width:0;padding:6px 8px;background:var(--bg-sunken);
+        border:1px solid var(--border-default);outline:none;
+        font-family:var(--font-mono);font-size:var(--text-xs);
+        color:var(--text-primary)" />
+      <button type="button" data-bit="{a(emit('notify:' + name))}"
+        class="bit-hover-cta" style="flex:0 0 auto;padding:6px 11px;
+        background:var(--accent-amber);border:1px solid var(--accent-amber);
+        color:var(--stone-950);cursor:pointer;font-family:var(--font-styrene);
+        font-size:var(--text-xs);text-transform:uppercase;
+        letter-spacing:var(--tracking-wide)">Notify me</button>
+    </div>
+    {note}
+    {live_row}
+  </div>
+</div>"""
+    return _backdrop("soon:close", emit, 80, body)
+
+
+# --------------------------------------------------------------------------
+# Contact
+# --------------------------------------------------------------------------
+
+
+def contact(navigation: dict, state: dict, emit) -> str:
+    """The contact dialog: real channels, plus a message form."""
+    config = navigation.get("contact") or {}
+    channels = config.get("channels") or []
+    topics = config.get("topics") or ["Data correction", "Press", "Other"]
+
+    rows = []
+    for index, channel in enumerate(channels):
+        href = channel.get("href") or ""
+        last = index == len(channels) - 1
+        border = "" if last else "border-bottom:1px solid var(--border-subtle);"
+        rows.append(
+            f'<a href="{a(href)}" target="_blank" rel="noopener noreferrer" '
+            f'class="bit-hover-row" style="display:flex;align-items:center;'
+            f'gap:10px;padding:10px 12px;{border}text-decoration:none">'
+            f'{icon(channel.get("icon") or "cube", "14px", "var(--accent-amber-strong)")}'
+            f'<span style="flex:1 1 auto;min-width:0;display:flex;'
+            f'flex-direction:column;gap:1px">'
+            f'<span style="font-family:var(--font-styrene);font-weight:300;'
+            f'font-size:var(--text-2xs);text-transform:uppercase;'
+            f'letter-spacing:var(--tracking-wider);color:var(--text-tertiary)">'
+            f'{e(channel.get("kind") or "")}</span>'
+            f'<span class="mono-data" style="font-size:var(--text-xs);'
+            f'color:var(--text-primary)">{e(channel.get("value") or "")}</span>'
+            f'</span>'
+            f'<span class="mono-data" style="font-size:var(--text-2xs);'
+            f'color:var(--text-tertiary)">{e(channel.get("note") or "")}</span></a>'
+        )
+
+    open_form = bool(state.get("contact_form_open"))
+    chosen = state.get("contact_topic") or topics[0]
+    topic_chips = "".join(
+        f'<button type="button" data-bit="{a(emit("topic:" + t))}" '
+        f'aria-pressed="{"true" if t == chosen else "false"}" '
+        f'style="padding:2px 7px;'
+        f'background:{"var(--accent-amber-dim)" if t == chosen else "transparent"};'
+        f'border:1px solid '
+        f'{"var(--accent-amber)" if t == chosen else "var(--border-default)"};'
+        f'color:{"var(--text-primary)" if t == chosen else "var(--text-secondary)"};'
+        f'cursor:pointer;font-family:var(--font-mono);font-size:var(--text-2xs)">'
+        f'{e(t)}</button>'
+        for t in topics
+    )
+
+    sent_note = state.get("contact_note") or "NO ATTACHMENTS · PLAIN TEXT ONLY"
+    sent_colour = ("var(--accent-moss-strong)" if state.get("contact_ok")
+                   else "var(--text-tertiary)")
+
+    form = ""
+    if open_form:
+        form = f"""
+    <div style="padding:12px;display:flex;flex-direction:column;gap:10px">
+      <div style="display:flex;gap:8px;flex-wrap:wrap">
+        <div style="flex:1 1 140px;min-width:0">
+          {_field_label('Name')}
+          <input data-bit-input="cname" value="{a(state.get('contact_name') or '')}"
+            placeholder="Full name" style="{_INPUT}" />
+        </div>
+        <div style="flex:1 1 140px;min-width:0">
+          {_field_label('Email')}
+          <input data-bit-input="cemail" type="email"
+            value="{a(state.get('contact_email') or '')}"
+            placeholder="you@firm.com" style="{_INPUT}" />
+        </div>
+      </div>
+      <div>{_field_label('Topic')}
+        <div style="display:flex;flex-wrap:wrap;gap:4px">{topic_chips}</div>
+      </div>
+      <div>{_field_label('Message')}
+        <textarea data-bit-input="cmsg" rows="4"
+          placeholder="Model ID, page, or question — be specific."
+          style="{_INPUT};resize:vertical">{e(state.get('contact_message') or '')}</textarea>
+      </div>
+      <div style="display:flex;align-items:center;gap:8px;flex-wrap:wrap">
+        <button type="button" data-bit="{a(emit('contact:send'))}"
+          class="bit-hover-cta" style="padding:7px 12px;
+          background:var(--accent-amber);border:1px solid var(--accent-amber);
+          color:var(--stone-950);cursor:pointer;font-family:var(--font-styrene);
+          font-size:var(--text-sm);text-transform:uppercase;
+          letter-spacing:var(--tracking-wide)">Send</button>
+        <span class="mono-data" style="font-size:var(--text-2xs);
+              color:{sent_colour}">{e(sent_note)}</span>
+      </div>
+      <div class="styrene-text" style="font-size:var(--text-xs);
+           text-transform:uppercase;letter-spacing:var(--tracking-wide);
+           color:var(--text-tertiary);text-wrap:pretty">The Bit Trading Company
+        answers research and data questions. We do not give financial advice and
+        we cannot discuss individual positions.</div>
+    </div>"""
+
+    body = f"""
+<div {PANEL_GUARD} role="dialog" aria-modal="true" aria-label="Contact us"
+     class="bit-scroll" style="width:min(460px,100%);max-height:90vh;
+     overflow-y:auto;background:var(--bg-panel);
+     border:1px solid var(--border-strong)">
+  <div style="display:flex;align-items:center;gap:8px;padding:9px 12px;
+       border-bottom:1px solid var(--border-default);background:var(--bg-raised)">
+    <span style="display:inline-block;width:5px;height:5px;
+          background:var(--accent-amber);animation:bitPulse 2s ease-in-out infinite"></span>
+    <span style="font-family:var(--font-styrene);font-size:var(--text-md);
+          text-transform:uppercase;letter-spacing:var(--tracking-wide)">Contact us</span>
+    {_close_button('contact:close', emit)}
+  </div>
+  <div style="border-bottom:1px solid var(--border-default)">{''.join(rows)}</div>
+  <button type="button" data-bit="{a(emit('contact:form'))}"
+    class="bit-hover-row" style="width:100%;display:flex;align-items:center;
+    gap:8px;padding:9px 12px;background:transparent;border:none;
+    border-bottom:1px solid var(--border-default);cursor:pointer;
+    color:var(--text-primary);text-align:left">
+    <span style="font-family:var(--font-styrene);font-size:var(--text-sm);
+          text-transform:uppercase;letter-spacing:var(--tracking-wide)">Send a message</span>
+    <span class="mono-data" style="font-size:var(--text-2xs);
+          color:var(--text-tertiary)">{'' if open_form else 'CORRECTIONS · VERIFICATION REQUESTS · PRESS'}</span>
+    <span class="mono-data" aria-hidden="true" style="margin-left:auto;
+          font-size:var(--text-2xs);color:var(--text-tertiary)">{'▴' if open_form else '▾'}</span>
+  </button>
+  {form}
+</div>"""
+    return _backdrop("contact:close", emit, 90, body)
+
+
+_INPUT = ("width:100%;padding:5px 7px;background:var(--bg-sunken);"
+          "border:1px solid var(--border-default);outline:none;"
+          "font-family:var(--font-mono);font-size:var(--text-xs);"
+          "color:var(--text-primary)")
+
+
+def _field_label(text: str) -> str:
+    return (f'<div style="font-family:var(--font-styrene);font-weight:300;'
+            f'font-size:var(--text-2xs);text-transform:uppercase;'
+            f'letter-spacing:var(--tracking-wider);color:var(--text-tertiary);'
+            f'margin-bottom:3px">{e(text)}</div>')

vendor/bit-ui/bit_ui/icons.py

@@ -0,0 +1,65 @@
+"""Phosphor icon paths, vendored.
+
+The design system pulls these from `unpkg.com/@phosphor-icons/web` at runtime.
+Vendoring the two dozen the Atlas actually uses keeps the Space self-contained:
+no third-party request on the critical path, and the icons still render if
+unpkg is unreachable.
+
+Phosphor Icons is MIT licensed (https://phosphoricons.com). These are the
+"fill" weight, which is what the design system uses -- the flat, solid look is
+part of the visual language and the outline weight reads as a different system.
+
+Generated from phosphor-icons/core; the mapping from the design's icon names to
+Phosphor's kebab-case names is the design system's own NAME_MAP.
+"""
+
+from __future__ import annotations
+
+from html import escape
+
+# name -> inner SVG markup, viewBox 0 0 256 256
+PATHS = {
+    'search': '<path d="M168,112a56,56,0,1,1-56-56A56,56,0,0,1,168,112Zm61.66,117.66a8,8,0,0,1-11.32,0l-50.06-50.07a88,88,0,1,1,11.32-11.31l50.06,50.06A8,8,0,0,1,229.66,229.66ZM112,184a72,72,0,1,0-72-72A72.08,72.08,0,0,0,112,184Z"/>',
+    'chevronRight': '<path d="M181.66,133.66l-80,80A8,8,0,0,1,88,208V48a8,8,0,0,1,13.66-5.66l80,80A8,8,0,0,1,181.66,133.66Z"/>',
+    'filter': '<path d="M227.81,66.76l-.08.09L160,139.17v55.49A16,16,0,0,1,152.87,208l-32,21.34A16,16,0,0,1,96,216V139.17L28.27,66.85l-.08-.09A16,16,0,0,1,40,40H216a16,16,0,0,1,11.84,26.76Z"/>',
+    'close': '<path d="M208,32H48A16,16,0,0,0,32,48V208a16,16,0,0,0,16,16H208a16,16,0,0,0,16-16V48A16,16,0,0,0,208,32ZM181.66,170.34a8,8,0,0,1-11.32,11.32L128,139.31,85.66,181.66a8,8,0,0,1-11.32-11.32L116.69,128,74.34,85.66A8,8,0,0,1,85.66,74.34L128,116.69l42.34-42.35a8,8,0,0,1,11.32,11.32L139.31,128Z"/>',
+    'globe': '<path d="M128,24h0A104,104,0,1,0,232,128,104.12,104.12,0,0,0,128,24Zm78.36,64H170.71a135.28,135.28,0,0,0-22.3-45.6A88.29,88.29,0,0,1,206.37,88ZM216,128a87.61,87.61,0,0,1-3.33,24H174.16a157.44,157.44,0,0,0,0-48h38.51A87.61,87.61,0,0,1,216,128ZM128,43a115.27,115.27,0,0,1,26,45H102A115.11,115.11,0,0,1,128,43ZM102,168H154a115.11,115.11,0,0,1-26,45A115.27,115.27,0,0,1,102,168Zm-3.9-16a140.84,140.84,0,0,1,0-48h59.88a140.84,140.84,0,0,1,0,48Zm50.35,61.6a135.28,135.28,0,0,0,22.3-45.6h35.66A88.29,88.29,0,0,1,148.41,213.6Z"/>',
+    'chart': '<path d="M216,40H40A16,16,0,0,0,24,56V200a16,16,0,0,0,16,16H216a16,16,0,0,0,16-16V56A16,16,0,0,0,216,40ZM200,176a8,8,0,0,1,0,16H56a8,8,0,0,1-8-8V72a8,8,0,0,1,16,0v62.92l34.88-29.07a8,8,0,0,1,9.56-.51l43,28.69,43.41-36.18a8,8,0,0,1,10.24,12.3l-48,40a8,8,0,0,1-9.56.51l-43-28.69L64,155.75V176Z"/>',
+    'fileText': '<path d="M213.66,82.34l-56-56A8,8,0,0,0,152,24H56A16,16,0,0,0,40,40V216a16,16,0,0,0,16,16H200a16,16,0,0,0,16-16V88A8,8,0,0,0,213.66,82.34ZM160,176H96a8,8,0,0,1,0-16h64a8,8,0,0,1,0,16Zm0-32H96a8,8,0,0,1,0-16h64a8,8,0,0,1,0,16Zm-8-56V44l44,44Z"/>',
+    'file': '<path d="M213.66,82.34l-56-56A8,8,0,0,0,152,24H56A16,16,0,0,0,40,40V216a16,16,0,0,0,16,16H200a16,16,0,0,0,16-16V88A8,8,0,0,0,213.66,82.34ZM152,88V44l44,44Z"/>',
+    'trend': '<path d="M240,56v64a8,8,0,0,1-13.66,5.66L200,99.31l-58.34,58.35a8,8,0,0,1-11.32,0L96,123.31,29.66,189.66a8,8,0,0,1-11.32-11.32l72-72a8,8,0,0,1,11.32,0L136,140.69,188.69,88,162.34,61.66A8,8,0,0,1,168,48h64A8,8,0,0,1,240,56Z"/>',
+    'sliders': '<path d="M32,80a8,8,0,0,1,8-8H77.17a28,28,0,0,1,53.66,0H216a8,8,0,0,1,0,16H130.83a28,28,0,0,1-53.66,0H40A8,8,0,0,1,32,80Zm184,88H194.83a28,28,0,0,0-53.66,0H40a8,8,0,0,0,0,16H141.17a28,28,0,0,0,53.66,0H216a8,8,0,0,0,0-16Z"/>',
+    'star': '<path d="M234.29,114.85l-45,38.83L203,211.75a16.4,16.4,0,0,1-24.5,17.82L128,198.49,77.47,229.57A16.4,16.4,0,0,1,53,211.75l13.76-58.07-45-38.83A16.46,16.46,0,0,1,31.08,86l59-4.76,22.76-55.08a16.36,16.36,0,0,1,30.27,0l22.75,55.08,59,4.76a16.46,16.46,0,0,1,9.37,28.86Z"/>',
+    'braces': '<path d="M216,40H40A16,16,0,0,0,24,56V200a16,16,0,0,0,16,16H216a16,16,0,0,0,16-16V56A16,16,0,0,0,216,40ZM88,155.84c.29,14.26.41,20.16,16,20.16a8,8,0,0,1,0,16c-31.27,0-31.72-22.43-32-35.84C71.71,141.9,71.59,136,56,136a8,8,0,0,1,0-16c15.59,0,15.71-5.9,16-20.16C72.28,86.43,72.73,64,104,64a8,8,0,0,1,0,16c-15.59,0-15.71,5.9-16,20.16-.17,8.31-.41,20.09-8,27.84C87.59,135.75,87.83,147.53,88,155.84ZM200,136c-15.59,0-15.71,5.9-16,20.16-.28,13.41-.73,35.84-32,35.84a8,8,0,0,1,0-16c15.59,0,15.71-5.9,16-20.16.17-8.31.41-20.09,8-27.84-7.6-7.75-7.84-19.53-8-27.84C167.71,85.9,167.59,80,152,80a8,8,0,0,1,0-16c31.27,0,31.72,22.43,32,35.84.29,14.26.41,20.16,16,20.16a8,8,0,0,1,0,16Z"/>',
+    'flag': '<path d="M232,56V176a8,8,0,0,1-2.76,6c-15.28,13.23-29.89,18-43.82,18-18.91,0-36.57-8.74-53-16.85C105.87,170,82.79,158.61,56,179.77V224a8,8,0,0,1-16,0V56a8,8,0,0,1,2.77-6h0c36-31.18,68.31-15.21,96.79-1.12C167,62.46,190.79,74.2,218.76,50A8,8,0,0,1,232,56Z"/>',
+    'grid': '<path d="M120,56v48a16,16,0,0,1-16,16H56a16,16,0,0,1-16-16V56A16,16,0,0,1,56,40h48A16,16,0,0,1,120,56Zm80-16H152a16,16,0,0,0-16,16v48a16,16,0,0,0,16,16h48a16,16,0,0,0,16-16V56A16,16,0,0,0,200,40Zm-96,96H56a16,16,0,0,0-16,16v48a16,16,0,0,0,16,16h48a16,16,0,0,0,16-16V152A16,16,0,0,0,104,136Zm96,0H152a16,16,0,0,0-16,16v48a16,16,0,0,0,16,16h48a16,16,0,0,0,16-16V152A16,16,0,0,0,200,136Z"/>',
+    'cube': '<path d="M223.68,66.15,135.68,18a15.88,15.88,0,0,0-15.36,0l-88,48.17a16,16,0,0,0-8.32,14v95.64a16,16,0,0,0,8.32,14l88,48.17a15.88,15.88,0,0,0,15.36,0l88-48.17a16,16,0,0,0,8.32-14V80.18A16,16,0,0,0,223.68,66.15ZM128,120,47.65,76,128,32l80.35,44Zm8,99.64V133.83l80-43.78v85.76Z"/>',
+    'shield': '<path d="M208,40H48A16,16,0,0,0,32,56v56c0,52.72,25.52,84.67,46.93,102.19,23.06,18.86,46,25.26,47,25.53a8,8,0,0,0,4.2,0c1-.27,23.91-6.67,47-25.53C198.48,196.67,224,164.72,224,112V56A16,16,0,0,0,208,40Zm-34.32,69.66-56,56a8,8,0,0,1-11.32,0l-24-24a8,8,0,0,1,11.32-11.32L112,148.69l50.34-50.35a8,8,0,0,1,11.32,11.32Z"/>',
+    'list2': '<path d="M208,32H48A16,16,0,0,0,32,48V208a16,16,0,0,0,16,16H208a16,16,0,0,0,16-16V48A16,16,0,0,0,208,32ZM68,188a12,12,0,1,1,12-12A12,12,0,0,1,68,188Zm0-48a12,12,0,1,1,12-12A12,12,0,0,1,68,140Zm0-48A12,12,0,1,1,80,80,12,12,0,0,1,68,92Zm124,92H104a8,8,0,0,1,0-16h88a8,8,0,0,1,0,16Zm0-48H104a8,8,0,0,1,0-16h88a8,8,0,0,1,0,16Zm0-48H104a8,8,0,0,1,0-16h88a8,8,0,0,1,0,16Z"/>',
+    'database': '<path d="M128,24C74.17,24,32,48.6,32,80v96c0,31.4,42.17,56,96,56s96-24.6,96-56V80C224,48.6,181.83,24,128,24Zm80,104c0,9.62-7.88,19.43-21.61,26.92C170.93,163.35,150.19,168,128,168s-42.93-4.65-58.39-13.08C55.88,147.43,48,137.62,48,128V111.36c17.06,15,46.23,24.64,80,24.64s62.94-9.68,80-24.64Zm-21.61,74.92C170.93,211.35,150.19,216,128,216s-42.93-4.65-58.39-13.08C55.88,195.43,48,185.62,48,176V159.36c17.06,15,46.23,24.64,80,24.64s62.94-9.68,80-24.64V176C208,185.62,200.12,195.43,186.39,202.92Z"/>',
+    'shape': '<path d="M224,48V208a16,16,0,0,1-16,16H48a16,16,0,0,1-16-16V48A16,16,0,0,1,48,32H208A16,16,0,0,1,224,48Z"/>',
+    'code': '<path d="M216,40H40A16,16,0,0,0,24,56V200a16,16,0,0,0,16,16H216a16,16,0,0,0,16-16V56A16,16,0,0,0,216,40ZM92.8,145.6a8,8,0,1,1-9.6,12.8l-32-24a8,8,0,0,1,0-12.8l32-24a8,8,0,0,1,9.6,12.8L69.33,128Zm58.89-71.4-32,112a8,8,0,1,1-15.38-4.4l32-112a8,8,0,0,1,15.38,4.4Zm53.11,60.2-32,24a8,8,0,0,1-9.6-12.8L186.67,128,163.2,110.4a8,8,0,1,1,9.6-12.8l32,24a8,8,0,0,1,0,12.8Z"/>',
+    'bookmark': '<path d="M184,32H72A16,16,0,0,0,56,48V224a8,8,0,0,0,12.24,6.78L128,193.43l59.77,37.35A8,8,0,0,0,200,224V48A16,16,0,0,0,184,32Z"/>',
+    'chat': '<path d="M232,128A104,104,0,0,1,79.12,219.82L45.07,231.17a16,16,0,0,1-20.24-20.24l11.35-34.05A104,104,0,1,1,232,128Z"/>',
+    'question': '<path d="M128,24A104,104,0,1,0,232,128,104.11,104.11,0,0,0,128,24Zm0,168a12,12,0,1,1,12-12A12,12,0,0,1,128,192Zm8-48.72V144a8,8,0,0,1-16,0v-8a8,8,0,0,1,8-8c13.23,0,24-9,24-20s-10.77-20-24-20-24,9-24,20v4a8,8,0,0,1-16,0v-4c0-19.85,17.94-36,40-36s40,16.15,40,36C168,125.38,154.24,139.93,136,143.28Z"/>',
+    'paperPlane': '<path d="M231.4,44.34s0,.1,0,.15l-58.2,191.94a15.88,15.88,0,0,1-14,11.51q-.69.06-1.38.06a15.86,15.86,0,0,1-14.42-9.15L107,164.15a4,4,0,0,1,.77-4.58l57.92-57.92a8,8,0,0,0-11.31-11.31L96.43,148.26a4,4,0,0,1-4.58.77L17.08,112.64a16,16,0,0,1,2.49-29.8l191.94-58.2.15,0A16,16,0,0,1,231.4,44.34Z"/>',
+    'headset': '<path d="M232,128v80a40,40,0,0,1-40,40H136a8,8,0,0,1,0-16h56a24,24,0,0,0,24-24H192a24,24,0,0,1-24-24V144a24,24,0,0,1,24-24h23.65A88,88,0,0,0,66,65.54,87.29,87.29,0,0,0,40.36,120H64a24,24,0,0,1,24,24v40a24,24,0,0,1-24,24H48a24,24,0,0,1-24-24V128A104.11,104.11,0,0,1,201.89,54.66,103.41,103.41,0,0,1,232,128Z"/>',
+}
+
+
+def icon(name: str, size: str = "14px", color: str = "currentColor",
+         extra_style: str = "") -> str:
+    """One inline SVG. An unknown name renders nothing rather than raising.
+
+    Icons are decorative here -- every control they sit inside carries its own
+    text or a title attribute -- so they are hidden from assistive technology.
+    """
+    body = PATHS.get(name)
+    if not body:
+        return ""
+    style = f"flex:0 0 auto;{extra_style}"
+    return (
+        f'<svg viewBox="0 0 256 256" width="{escape(size)}" height="{escape(size)}" '
+        f'fill="{escape(color)}" aria-hidden="true" focusable="false" '
+        f'style="{escape(style, quote=True)}">{body}</svg>'
+    )

vendor/bit-ui/bit_ui/markup.py

@@ -0,0 +1,32 @@
+"""Escaping helpers.
+
+Named `markup` rather than `html` on purpose: a module called `html.py` at a
+package root shadows Python's own stdlib `html` for the entire process the
+moment that directory lands on `sys.path`. It broke pytest itself (pygments
+imports `html`), and it would break just as silently inside a Space.
+
+Small, but the single most important module here. Everything a Space renders
+into its markup — model ids, licences, red-flag text, nav labels pulled from a
+shared config file — is data from somewhere else, and it goes through one of
+these two functions on the way in.
+
+`e()` for element content, `a()` for attribute values. The difference is that
+`a()` escapes quotes; forgetting it is how a value breaks out of an attribute
+and becomes markup.
+"""
+
+from __future__ import annotations
+
+from html import escape
+
+DASH = "—"
+
+
+def e(value) -> str:
+    """Escape text for element content."""
+    return escape("" if value is None else str(value), quote=False)
+
+
+def a(value) -> str:
+    """Escape text for an attribute value (quotes included)."""
+    return escape("" if value is None else str(value), quote=True)