Backtest Lab v1.0.0

.env.example

@@ -0,0 +1,9 @@
+# Backtest Lab — required Space secrets (names only; never commit values)
+
+# Write token for the bit-signal-store dataset repo. Set as a Space secret,
+# server-side only. Used by store.py's CommitScheduler for coverage write-back.
+HF_WRITE_TOKEN=
+
+# Optional. Only needed to enable the Tiingo equity provider fallback.
+# The provider chain works without it (yfinance -> Stooq).
+TIINGO_KEY=

.gitattributes

@@ -33,3 +33,12 @@ 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
+assets/fonts/MacMinecraft.ttf filter=lfs diff=lfs merge=lfs -text
+assets/fonts/StyreneA-Light.otf filter=lfs diff=lfs merge=lfs -text
+assets/fonts/StyreneA-LightItalic.otf filter=lfs diff=lfs merge=lfs -text
+assets/fonts/StyreneA-Medium.otf filter=lfs diff=lfs merge=lfs -text
+assets/fonts/StyreneA-MediumItalic.otf filter=lfs diff=lfs merge=lfs -text
+assets/fonts/StyreneA-Regular.otf filter=lfs diff=lfs merge=lfs -text
+assets/fonts/StyreneA-RegularItalic.otf filter=lfs diff=lfs merge=lfs -text
+assets/fonts/StyreneA-Thin.otf filter=lfs diff=lfs merge=lfs -text
+assets/fonts/StyreneA-ThinItalic.otf filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.env
+.env.local
+key.txt
+.cache/
+.hf_scheduler/
+.pytest_cache/

DESIGN_NOTES.md

@@ -0,0 +1,124 @@
+# Design reference — Backtest Lab
+
+Extracted from `Bit Trading Portal Dashboard/Backtest Lab.dc.html` plus the Bit
+design system (`_ds/bit-design-system-b707c3d1…`). This file is the contract the
+Gradio UI is built against; `assets/tokens/*.css` and `assets/fonts/*` are
+vendored verbatim from that design system.
+
+## Design system
+
+Dark-first, terminal-flavoured. Tokens only — components never use raw colors.
+
+| Role | Token | Value |
+|---|---|---|
+| Canvas | `--bg-canvas` | `#161512` (stone-950) |
+| Panel | `--bg-panel` | `#1d1c18` (stone-900) |
+| Raised | `--bg-raised` | `#24221d` (stone-850) |
+| Border subtle / default | `--border-subtle` / `--border-default` | `#2c2a24` / `#3d3a32` |
+| Text primary / secondary / tertiary | | `#f7f4ec` / `#b6b09a` / `#6f6a56` |
+| Primary accent | `--accent-amber` / `-strong` | `#af9209` / `#cfab0a` |
+| Secondary accent | `--accent-moss` / `-strong` | `#68781e` / `#7d901f` |
+| Up / down | `--fin-up` / `--fin-down` | `oklch(66% .22 149)` / `oklch(62% .26 24)` |
+
+Colorblind mode (`[data-colorblind=true]`) swaps up/down to blue/orange, and
+direction is **also** marked with ▲/▼ glyphs — never color alone.
+
+Fonts: headings `Styrene A` (400), body system sans (300), `JetBrains Mono` for
+numbers, `Mac Minecraft` for the 8–10px pixel labels. Sizes are small:
+`--text-2xs:8px … --text-base:12px … --text-4xl:62px`.
+
+Radii are near-square (`--radius-sm:4px`, `--radius-md:8px`); panels are a 1px
+border, no drop shadows (`--shadow-panel: 0 0 0 1px var(--border-default)`).
+
+Section headings are ALL-CAPS Styrene with `--tracking-wide`; micro-labels are
+uppercase Mac Minecraft with `--tracking-wider`.
+
+## Layout
+
+Three zones; left `286px`, right `306px` (collapses to `46px`), center fluid.
+
+- **Top bar** — BIT mark, `BIT / Backtest Lab`, context chip
+  (`BTC-USD · 1H · 2021-08-15 → 2026-08-15 · WALK-FORWARD`), run-status chip,
+  elapsed (`~4S`), amber **▶ Run backtest**, Display menu (Dark mode /
+  Colorblind-safe prices, footnote `UP/DOWN ALSO MARKED ▲ ▼`), `Portal ↗`.
+- **Left — Strategy Builder** (`CFG #0142`), five numbered collapsible sections:
+  1. Strategy — preset select + params
+  2. Universe & Data — ticker chips (`+ ticker`), Asset class segmented
+     (Crypto/Equities/Both), Timeframe chips, Date range (`1Y 3Y 5Y Max`),
+     Regime filter (`Bull only / Bear only / Chop only`, `NEW` badge)
+  3. Costs & Execution — Commission/side `0.10%`, Slippage `5 BPS`,
+     slippage model (`Fixed bps / Volume-scaled / Spread-based`),
+     fill (`Next bar open / Same bar close`), funding.
+     Warning: **"Costs on. Turning these off is how strategies lie to you."**
+  4. Sizing & Risk — sizing (`Fixed % / Kelly fraction / Vol-target 15% ann.`),
+     leverage `1X…3X`, Max position `35%`, Max concurrent `2`
+  5. Validation — `TRAIN 12MO · TEST 3MO · ROLL 3MO`, ■ TRAIN / ■ TEST bands,
+     OOS holdout `LAST 6MO`
+  Footer: `Save config`, `Share link`.
+- **Center — Results Canvas**, tabs: `Overview · Trades · Comparison · Robustness · Report`
+- **Right — Run Manager** — `RUNNING · {progress}`, Run history (`n/6 SELECTED`,
+  star = favourite, Sharpe color-coded), Trending public configs, `Clone config`,
+  `Metrics glossary`.
+- **Footer** — always visible:
+  "Simulated results with modeled costs. Backtests are hypotheses, not promises.
+  Past performance does not predict future results. Not financial advice."
+  Right: `BITTRADING SDK 0.9.3`.
+
+## States
+
+- **Empty**: "No run loaded" / "Configure a strategy on the left, or start from a
+  worked example and edit it." + `Load example: Sentiment-Gated Momentum · BTC 1h`
+  + shortcut hints `⌘↵ RUN`, `⌘S SAVE CONFIG`, `⌘K COMMANDS`.
+- **Loading**: staged labels — `Fetching data`, `Simulating N trades`,
+  `Walk-forward window k/n`, `Computing robustness`.
+
+## Tab contents
+
+**Overview** — stat band (each stat shows `IS x · OOS y`); `EQUITY CURVE`
+(`STRATEGY VS BUY & HOLD`, log-scale toggle, drawdown shading, hatched `HOLDOUT`
+band, `REGIME` strip); `UNDERWATER · MAX −23.6%`; `ROLLING 90D SHARPE · MEDIAN 1.24`;
+price+trades chart (`▲ ENTRY · ▼ EXIT · HOLLOW = SHORT · HOVER A FLAG FOR THE TRADE CARD`);
+`NET P&L DISTRIBUTION`, `HOLDING PERIOD (HOURS)`, `MAE / MFE SCATTER`;
+`COSTS PAID TOTAL: $1,842` with the note that the costed number is the real one.
+
+**Trades** — `312 TOTAL · SHOWING 14`, `Export CSV →`, sortable columns:
+id, entry/exit time, side, entry/exit px, size, gross, costs, net, R, duration,
+MAE, trigger.
+
+**Comparison** — `Time-scale matrix` (`CELL = OOS SHARPE · CLICK TO LOAD RUN`,
+scale −0.5 → 2.0), `n/6 SELECTED`, small-multiples equity grid, overlaid
+cumulative return (`SHARED SCALE · OOS PERIOD SHADED`), metrics table
+(rows: Total return, CAGR, OOS Sharpe, Max drawdown, Win rate, Trades; best
+value amber+bold), `RETURN CORRELATION · ARE THESE THE SAME BET?`,
+`RETURN ACROSS REGIMES · BULL / BEAR / CHOP`.
+
+**Robustness** — `Overfit verdict` with grade + checklist; `PARAMETER SENSITIVITY ·
+FAST MA × SLOW MA · OOS SHARPE` heatmap with `□ CHOSEN` marker;
+`MONTE CARLO · 1,000 TRADE RESHUFFLES` cone with `P5 / P50 / P95` and
+`P(RUIN > 30% DD)`; `WALK-FORWARD WINDOWS · OOS RETURN` bars with
+`CONSISTENCY 6/8 POSITIVE`; `SLIPPAGE STRESS · SHARPE VS BPS`.
+
+**Report** — prose summary, `EQUITY CURVE · STRATEGY VS BUY & HOLD`,
+`CONFIG SNAPSHOT`, verdict line, actions: `Export PDF`, `Publish to leaderboard`,
+`Publish to graveyard`, `Copy share link`, `Export trades CSV`, `Open in Colab`.
+
+## Presets (design list)
+
+`SMA Crossover`, `RSI Mean Reversion`, `Bollinger Breakout`, `MACD Momentum`,
+`Sentiment-Gated Momentum`, `Chronos Forecast Follower`, `Pairs Trading`,
+`Buy & Hold (benchmark)`, `Custom (code)`.
+
+`Custom (code)` is shown **disabled** — see DECISIONS.md (D-004). Executing
+user-supplied strategy code is forbidden by the build spec, so the control is
+present but inert with an explanation rather than silently removed.
+
+## Glossary copy (verbatim, used in the Run Manager tray)
+
+- **SHARPE** — Annualized mean excess return divided by return volatility. Above 1 is good; above 3 usually means a bug.
+- **SORTINO** — Sharpe with only downside deviation in the denominator.
+- **MAX DRAWDOWN** — Worst peak-to-trough decline of the equity curve.
+- **PROFIT FACTOR** — Gross profit over gross loss. Below 1.2 rarely survives real costs.
+- **R-MULTIPLE** — Trade P&L expressed in units of initial risk.
+- **MAE / MFE** — Worst and best unrealized excursion while the trade was open.
+- **WALK-FORWARD** — Train on a rolling window, test on the next unseen window, repeat.
+- **OOS** — Out of sample: data the parameters never saw during fitting.

README.md

@@ -1,13 +1,177 @@
 ---
 title: Bit Backtest Lab
-emoji: 😻
+emoji: 📉
 colorFrom: yellow
-colorTo: yellow
+colorTo: gray
 sdk: gradio
-sdk_version: 6.24.0
-python_version: '3.13'
+sdk_version: 5.49.1
+python_version: "3.11"
 app_file: app.py
-pinned: false
+pinned: true
+license: apache-2.0
+hf_oauth: true
+hf_oauth_scopes:
+  - inference-api
+short_description: Backtest forecasting models against honest costs
+tags:
+  - finance
+  - backtesting
+  - time-series
+  - forecasting
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Backtest Lab
+
+**The Bit Trading Company** · backtest and compare forecasting models and
+rule-based trading strategies against a shared, precomputed signal store.
+
+- **App**: https://huggingface.co/spaces/Bit-Trading-Company/bit-backtest-lab
+- **Signal store**: https://huggingface.co/datasets/The-Bit-Trading-Company/bit-signal-store
+
+## What it is
+
+Most backtesting tools make it easy to produce a beautiful, false result. This
+one is built around the handful of things that actually decide whether a
+backtest means anything: when you are allowed to trade, what it costs, and
+whether you ever tested on data you had not already fitted.
+
+The store holds **raw model outputs and prices only** — never trade decisions.
+Trading rules, costs and sizing are applied live, per request, so many
+strategies can be compared over the same forecasts without re-running inference.
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────┐
+│  bit-backtest-lab  (Gradio Space)            │
+│                                              │
+│  Strategy Builder ─┐                         │
+│                    ├─► engine.py (vectorbt)  │
+│  Results Canvas ◄──┘   next-bar-open fills   │
+│                        costs, stops, sizing  │
+│                        walk-forward + holdout│
+│         │                                    │
+│         │ read-only          ┌─────────────┐ │
+│         └───────────────────►│  LRU cache  │ │
+│                              └──────┬──────┘ │
+│  "Extend coverage"                  │        │
+│   └─► @spaces.GPU (user's quota)    │        │
+│        └─► CommitScheduler ──┐      │        │
+└──────────────────────────────┼──────┼────────┘
+                               ▼      │
+        ┌──────────────────────────────────────┐
+        │  bit-signal-store  (Dataset)         │
+        │  manifest.json    coverage map       │
+        │  signals/  raw q10/q50/q90           │
+        │  prices/   OHLCV cache + source      │
+        │  comparisons/  precomputed tables    │
+        │  runs/     saved run summaries       │
+        └──────────────────────────────────────┘
+                     ▲
+                     │ batch refresh only
+        ┌────────────┴─────────────────────────┐
+        │ ccxt (Binance→Coinbase)              │
+        │ yfinance → Stooq → Tiingo            │
+        └──────────────────────────────────────┘
+```
+
+## How results are computed
+
+**Fills.** Every fill executes at the **next bar's open**. A decision made at
+bar `t` is shifted forward one bar by the engine and filled at `open[t+1]`.
+There is no configuration that enters on the signal bar; `run_backtest` applies
+the shift itself and a strategy cannot bypass it.
+
+**No lookahead.** Strategies are checked by *perturbation*, not by convention:
+the tail of the price series is scaled up and down, the indicator is re-run, and
+every output before the perturbation point must be bit-identical. A strategy
+that reads bar `t+1` — or normalises by a full-sample statistic, or uses a
+centred rolling window — changes its earlier outputs and is caught.
+
+**Costs.** On by default: commission per side plus a slippage model
+(fixed bps or volume-scaled). Slippage is embedded in the fill price, so it is
+reconstructed from the unslipped reference price and booked onto the trade row.
+`gross − costs = net` holds exactly on every trade. Turning costs off is
+possible and is labelled, loudly, as not real.
+
+**Validation.** Simple split, walk-forward (configurable train/test/roll), and a
+locked last-N-months holdout. Train and test never share a bar. The holdout is
+excluded from `selectable_index()`, which is the only index any
+parameter-selection path is given — it cannot be fitted on by accident. When a
+configuration produces no out-of-sample period, the app says so instead of
+printing `0.00`.
+
+**Metrics.** Total return, CAGR, Sharpe, Sortino, max drawdown, win rate,
+profit factor, exposure and trade count, each computed in-sample,
+out-of-sample, and on the holdout. Every displayed number comes from
+`metrics.py` operating on the equity curve or the trade list.
+
+## Honest limitations
+
+- **Coverage is sparse.** The v1 seed covers 6 assets across 3 timeframes with
+  Chronos-Bolt small and base. Anything else needs extending.
+- **Binance is geo-blocked from the seeding machine**, so crypto prices came
+  from Coinbase. Prices will not tick-match another venue.
+- **Equity intraday history is provider-capped** — roughly 730 days of hourly
+  and 60 days of 15-minute bars. This is recorded in the manifest as a coverage
+  boundary, not hidden and not reported as an error.
+- **Stooq began serving an HTML block page** instead of CSV during the build, so
+  the equity fallback chain effectively runs on yfinance alone right now.
+- **Sentiment is a stub.** `Sentiment-Gated Momentum` runs against a labelled,
+  deterministic price-derived proxy, *not* news sentiment. It sits behind a
+  `SentimentSource` interface for a real feed later.
+- **Pairs Trading and Custom (code)** appear in the design's preset list but are
+  not runnable. Custom-code strategies are disabled deliberately: this Space
+  never executes user-supplied code.
+- **A backtest is a hypothesis.** Survivorship, regime change, liquidity and
+  your own future behaviour are not modelled.
+
+## Extending coverage
+
+Anonymous visitors get full read and backtest access. Extending coverage
+requires signing in with Hugging Face, because inference runs inside a
+`@spaces.GPU` function on **your** ZeroGPU quota:
+
+1. Pick a model, asset, timeframe and range in the **Coverage** tab.
+2. **Estimate** shows the step count; the request is deduplicated against
+   `manifest.json`, so an already-covered range recomputes nothing.
+3. Per-request caps apply (2 years daily / 6 months hourly / 2 months 15m).
+4. On success the new slice, the manifest, and the regenerated comparison
+   tables are written back in a single atomic commit, attributed to you.
+
+**Add model** takes an adapter family plus a Hub model id, resolves and pins the
+revision, and runs a 100-step smoke test on your quota before the model appears
+in the coverage map. Only allow-listed adapter families (`chronos`, `timesfm`)
+can be constructed, and model ids are validated before they reach the Hub.
+
+If your quota is exhausted the app says so and offers a duplicate-this-Space
+link — the store is public, so a duplicate reads the same data.
+
+## Running locally
+
+```bash
+uv venv --python 3.11 && uv pip install -r requirements.txt
+python app.py
+```
+
+Seeding your own store:
+
+```bash
+python scripts/seed_store.py --plan v1 --dry-run
+python scripts/seed_store.py --plan smoke --push
+```
+
+Tests:
+
+```bash
+bash tests/run_all.sh
+```
+
+`HF_WRITE_TOKEN` is required only for write-back; reading and backtesting work
+without any token. See `.env.example`.
+
+## Disclaimer
+
+Backtested results are hypothetical, derived from historical data, and are not
+indicative of future results. Nothing here is investment advice. The Bit Trading
+Company is not a licensed investment adviser.

app.py

@@ -0,0 +1,871 @@
+"""Bit Trading Company — Backtest Lab.
+
+Gradio Blocks implementation of the Backtest Lab design: Strategy Builder on
+the left, tabbed Results Canvas in the centre, Run Manager on the right, with
+the disclaimer pinned to the footer.
+
+The app reads exclusively from the cached signal store. The only path that can
+reach an external provider is the batch refresh in `scripts/seed_store.py`, and
+the only path that runs inference is the ZeroGPU extension flow in
+`src/extension.py`, which spends the signed-in user's own quota.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import asdict
+
+import gradio as gr
+import pandas as pd
+
+from src import charts, comparisons, config, runtime, strategies
+from src.runtime import RunError, RunRecord, RunRequest
+from src.ui import theme
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s %(name)s %(message)s")
+log = logging.getLogger("bit.app")
+
+MAX_COMPARE = 6
+GLOSSARY = [
+    ("SHARPE", "Annualized mean excess return divided by return volatility. "
+               "Above 1 is good; above 3 usually means a bug."),
+    ("SORTINO", "Sharpe with only downside deviation in the denominator."),
+    ("MAX DRAWDOWN", "Worst peak-to-trough decline of the equity curve."),
+    ("PROFIT FACTOR", "Gross profit over gross loss. Below 1.2 rarely survives real costs."),
+    ("R-MULTIPLE", "Trade P&L expressed in units of initial risk."),
+    ("MAE / MFE", "Worst and best unrealized excursion while the trade was open."),
+    ("WALK-FORWARD", "Train on a rolling window, test on the next unseen window, repeat."),
+    ("OOS", "Out of sample: data the parameters never saw during fitting."),
+]
+
+
+# --------------------------------------------------------------------------
+# Formatting helpers
+# --------------------------------------------------------------------------
+
+
+def pct(v, digits=1, signed=True) -> str:
+    if v is None or pd.isna(v):
+        return "—"
+    return f"{v * 100:+.{digits}f}%" if signed else f"{v * 100:.{digits}f}%"
+
+
+def num(v, digits=2) -> str:
+    if v is None or pd.isna(v):
+        return "—"
+    return f"{v:.{digits}f}"
+
+
+def money(v) -> str:
+    if v is None or pd.isna(v):
+        return "—"
+    return f"${v:,.0f}"
+
+
+def _cls(v) -> str:
+    if v is None or pd.isna(v) or v == 0:
+        return ""
+    return "bit-up" if v > 0 else "bit-down"
+
+
+def _arrow(v) -> str:
+    if v is None or pd.isna(v) or v == 0:
+        return ""
+    return " ▲" if v > 0 else " ▼"
+
+
+def seg(metrics, fmt, *args, **kwargs) -> str:
+    """Format a segment metric, or an em dash when that segment has no bars.
+
+    A segment with no data must never render as 0.00 -- "the out-of-sample
+    Sharpe is zero" and "there is no out-of-sample period" are different claims,
+    and only one of them is true here.
+    """
+    if metrics is None or metrics.bars == 0:
+        return "—"
+    return fmt(*args, **kwargs)
+
+
+def stat_band_html(rec: RunRecord | None) -> str:
+    """The stat band. Every stat carries its IS and OOS split, per the design."""
+    if rec is None:
+        return ""
+    r = rec.result
+    a, i, o = r.metrics_all, r.metrics_is, r.metrics_oos
+
+    def isoos(fmt, ikey, okey, *fargs):
+        iv = seg(i, fmt, getattr(i, ikey), *fargs)
+        ov = seg(o, fmt, getattr(o, okey), *fargs)
+        return f"IS {iv} · OOS {ov}"
+    bench_gap = a.total_return - (
+        float(r.benchmark_equity.iloc[-1] / r.benchmark_equity.iloc[0] - 1.0)
+        if len(r.benchmark_equity) else 0.0
+    )
+
+    cells = [
+        ("Total return", f"{pct(a.total_return)}{_arrow(a.total_return)}", _cls(a.total_return),
+         isoos(pct, "total_return", "total_return"),
+         "Cumulative return of the strategy equity curve, costs included."),
+        ("CAGR", pct(a.cagr), _cls(a.cagr), isoos(pct, "cagr", "cagr"),
+         "Compound annual growth rate implied by the equity curve."),
+        ("Sharpe", num(a.sharpe), _cls(a.sharpe),
+         isoos(num, "sharpe", "sharpe"), GLOSSARY[0][1]),
+        ("Sortino", num(a.sortino), _cls(a.sortino),
+         isoos(num, "sortino", "sortino"), GLOSSARY[1][1]),
+        ("Max drawdown", pct(a.max_drawdown), "bit-down",
+         isoos(pct, "max_drawdown", "max_drawdown"), GLOSSARY[2][1]),
+        ("Win rate", pct(a.win_rate, 0, signed=False), "",
+         f"IS {seg(i, pct, i.win_rate, 0, False)} · OOS {seg(o, pct, o.win_rate, 0, False)}",
+         "Share of closed trades with positive net P&L."),
+        ("Profit factor", num(a.profit_factor), _cls(a.profit_factor - 1.0),
+         isoos(num, "profit_factor", "profit_factor"), GLOSSARY[3][1]),
+        ("Trades", f"{a.trade_count}", "",
+         f"IS {seg(i, str, i.trade_count)} · OOS {seg(o, str, o.trade_count)}",
+         "Closed round-trip trades in the period."),
+        ("Exposure", pct(a.exposure, 0, signed=False), "",
+         f"IS {seg(i, pct, i.exposure, 0, False)} · OOS {seg(o, pct, o.exposure, 0, False)}",
+         "Fraction of bars holding a position."),
+        ("vs buy & hold", f"{pct(bench_gap)}", _cls(bench_gap),
+         f"costs paid {money(r.costs_paid)}",
+         "Strategy return minus buy-and-hold return over the same window."),
+    ]
+    html = ['<div class="bit-statband">']
+    for label, value, cls, sub, tip in cells:
+        html.append(
+            f'<div class="bit-stat" title="{tip}">'
+            f'<div class="bit-stat-label">{label}</div>'
+            f'<div class="bit-stat-value {cls}">{value}</div>'
+            f'<div class="bit-stat-sub">{sub}</div></div>'
+        )
+    html.append("</div>")
+    for note in getattr(r.plan, "notes", []):
+        html.append(f'<div class="bit-note bit-note-danger">{note}</div>')
+    if rec.result.metrics_holdout is not None:
+        h = rec.result.metrics_holdout
+        html.append(
+            f'<div class="bit-note">LOCKED HOLDOUT · return {pct(h.total_return)} · '
+            f'Sharpe {num(h.sharpe)} · {h.bars} bars never used for any parameter choice.</div>'
+        )
+    return "".join(html)
+
+
+def context_chip(req: RunRequest) -> str:
+    mode = {"walk_forward": "WALK-FORWARD", "holdout": "HOLDOUT",
+            "split": "SPLIT", "none": "NO SPLIT"}.get(req.validation_mode, "")
+    try:
+        s, e = runtime.window_for(req.asset, req.timeframe, req.date_range)
+        span = f"{s.date()} → {e.date()}"
+    except Exception:
+        span = req.date_range
+    return (f'<span class="bit-chip">{req.asset} · {req.timeframe.upper()} · '
+            f'{span} · {mode}</span>')
+
+
+def top_bar_html(status_text="NO RUN LOADED", status_cls="bit-chip", chip="") -> str:
+    return f"""
+<div class="bit-topbar">
+  <span class="bit-mark"></span>
+  <span class="bit-h1">BIT</span>
+  <span style="color:var(--text-tertiary)">/</span>
+  <span class="bit-h1">Backtest Lab</span>
+  {chip}
+  <span style="flex:1"></span>
+  <span class="{status_cls}">{status_text}</span>
+  <a class="bit-chip" href="https://huggingface.co/datasets/{config.STORE_REPO}"
+     target="_blank" rel="noopener">SIGNAL STORE ↗</a>
+</div>"""
+
+
+FOOTER_HTML = f"""
+<div class="bit-footer">
+  <span>{config.DISCLAIMER}</span>
+  <span style="white-space:nowrap">BITTRADING BACKTEST LAB v1.0.0</span>
+</div>"""
+
+
+EMPTY_HTML = """
+<div class="bit-empty">
+  <div class="bit-h2">No run loaded</div>
+  <div style="color:var(--text-secondary);max-width:46ch">
+    Configure a strategy on the left, or start from a worked example and edit it.
+  </div>
+  <div style="display:flex;gap:8px;margin-top:8px">
+    <span class="bit-kbd">⌘↵ RUN</span>
+    <span class="bit-kbd">⌘S SAVE CONFIG</span>
+    <span class="bit-kbd">COSTS DEFAULT ON</span>
+  </div>
+</div>"""
+
+
+def glossary_html() -> str:
+    rows = "".join(
+        f'<div style="margin-bottom:8px"><div class="bit-micro">{t}</div>'
+        f'<div style="font-size:11px;color:var(--text-secondary)">{d}</div></div>'
+        for t, d in GLOSSARY
+    )
+    return f'<div class="bit-panel">{rows}</div>'
+
+
+def trades_frame(rec: RunRecord | None) -> pd.DataFrame:
+    cols = ["#", "Entry", "Exit", "Side", "Entry px", "Exit px", "Size",
+            "Gross", "Costs", "Net", "R", "Bars", "MAE", "Segment", "Trigger"]
+    if rec is None or rec.result.trades.empty:
+        return pd.DataFrame(columns=cols)
+    t = rec.result.trades
+    return pd.DataFrame({
+        "#": t["id"],
+        "Entry": t["entry_ts"].dt.strftime("%Y-%m-%d %H:%M"),
+        "Exit": t["exit_ts"].dt.strftime("%Y-%m-%d %H:%M"),
+        "Side": t["side"].str.upper(),
+        "Entry px": t["entry_px"].round(2),
+        "Exit px": t["exit_px"].round(2),
+        "Size": t["size"].round(4),
+        "Gross": t["gross_pnl"].round(2),
+        "Costs": t["costs"].round(2),
+        "Net": t["net_pnl"].round(2),
+        "R": t["r_multiple"].round(2),
+        "Bars": t["duration_bars"],
+        "MAE": (t["mae"] * 100).round(1),
+        "Segment": t["segment"],
+        "Trigger": t["trigger"],
+    })
+
+
+def report_markdown(rec: RunRecord | None) -> str:
+    if rec is None:
+        return "_Run a backtest to generate the report._"
+    r, req = rec.result, rec.request
+    a, o, h = r.metrics_all, r.metrics_oos, r.metrics_holdout
+    bench = float(r.benchmark_equity.iloc[-1] / r.benchmark_equity.iloc[0] - 1.0) \
+        if len(r.benchmark_equity) else 0.0
+    ratio = (o.sharpe / r.metrics_is.sharpe) if r.metrics_is.sharpe else float("nan")
+    grade, checks = runtime.overfit_verdict(rec)
+
+    lines = [
+        f"### {rec.label}",
+        f"`RUN {rec.run_id} · {rec.created_at} · "
+        f"{req.validation_mode.upper()} · COSTS {'ON' if req.costs_on else 'OFF'}`",
+        "",
+        f"Over {a.bars} bars and {a.trade_count} trades the strategy returns "
+        f"**{pct(a.total_return)}** (CAGR {pct(a.cagr)}, Sharpe {num(a.sharpe)}) "
+        f"against **{pct(bench)}** for buy and hold, with a maximum drawdown of "
+        f"{pct(a.max_drawdown)}. Modelled costs of {money(r.costs_paid)} are already "
+        f"deducted — the costed number is the real one.",
+        "",
+        (f"Out-of-sample Sharpe is {num(o.sharpe)}, which is {num(ratio)} of the "
+         f"in-sample figure." if o.bars else
+         "**No out-of-sample period was produced for this configuration**, so every "
+         "number above is in-sample. Widen the date range or shorten the training "
+         "window before reading anything into it.")
+        + (f" On the locked holdout — {h.bars} bars that no parameter choice ever "
+           f"touched — it returns {pct(h.total_return)} at Sharpe {num(h.sharpe)}."
+           if h else ""),
+        "",
+        f"**Verdict: {grade}**",
+        "",
+    ]
+    lines += [f"- {mark} {text}" for mark, text in checks]
+    lines += ["", "#### Config snapshot", "```json",
+              _pretty_config(req), "```"]
+    return "\n".join(lines)
+
+
+def _pretty_config(req: RunRequest) -> str:
+    import json
+    return json.dumps(asdict(req), indent=2, sort_keys=True)
+
+
+# --------------------------------------------------------------------------
+# Handlers
+# --------------------------------------------------------------------------
+
+
+def collect_request(strategy, asset, timeframe, date_range, model_slug,
+                    p1, p2, p3, costs_on, commission_bps, slippage_bps,
+                    slippage_model, sizing_mode, size_pct, leverage,
+                    sl_pct, tp_pct, trail_pct,
+                    validation_mode, train_m, test_m, roll_m, holdout_m) -> RunRequest:
+    preset = strategies.PRESETS.get(strategy)
+    params = {}
+    if preset:
+        for (key, _label, _d, _lo, _hi), value in zip(preset.params, (p1, p2, p3)):
+            if value is not None:
+                params[key] = value
+    return RunRequest(
+        strategy=strategy, asset=asset, timeframe=timeframe, date_range=date_range,
+        model_slug=model_slug or "", params=params,
+        costs_on=bool(costs_on), commission_bps=float(commission_bps),
+        slippage_bps=float(slippage_bps),
+        slippage_model="volume_scaled" if slippage_model == "Volume-scaled" else "fixed",
+        sizing_mode={"Fixed %": "fixed_pct", "Vol-target 15% ann.": "vol_target"}.get(
+            sizing_mode, "fixed_pct"),
+        size_pct=float(size_pct), leverage=float(leverage),
+        sl_pct=(float(sl_pct) / 100.0 if sl_pct else None),
+        tp_pct=(float(tp_pct) / 100.0 if tp_pct else None),
+        trail_pct=(float(trail_pct) / 100.0 if trail_pct else None),
+        validation_mode={"Walk-forward": "walk_forward", "Simple split": "split",
+                         "Holdout only": "holdout", "None": "none"}.get(
+                             validation_mode, "walk_forward"),
+        train_months=int(train_m), test_months=int(test_m), roll_months=int(roll_m),
+        holdout_months=int(holdout_m),
+    )
+
+
+def build_app() -> gr.Blocks:
+    css = theme.full_css()
+
+    with gr.Blocks(theme=theme.bit_theme(), css=css, title="Bit · Backtest Lab",
+                   analytics_enabled=False, fill_height=True) as demo:
+
+        history = gr.State([])       # list[RunRecord]
+        selected = gr.State([])      # run_ids chosen for comparison
+        current = gr.State(None)     # RunRecord
+
+        top_bar = gr.HTML(top_bar_html())
+
+        with gr.Row(equal_height=False):
+            # ============================ LEFT ============================
+            with gr.Column(scale=2, min_width=280):
+                gr.HTML('<div class="bit-h2" style="padding:12px 4px 4px">Strategy Builder</div>')
+
+                with gr.Accordion("1 · STRATEGY", open=True, elem_classes="bit-accordion"):
+                    strategy = gr.Dropdown(
+                        choices=[p.name for p in strategies.PRESETS.values()],
+                        value="SMA Crossover", label="Preset", interactive=True,
+                    )
+                    preset_note = gr.HTML("")
+                    p1 = gr.Number(label="Fast MA", value=20, precision=4)
+                    p2 = gr.Number(label="Slow MA", value=50, precision=4)
+                    p3 = gr.Number(label="—", value=None, visible=False, precision=4)
+                    model_slug = gr.Dropdown(
+                        choices=runtime.available_models(), value=None,
+                        label="Forecast model", visible=False, interactive=True,
+                    )
+
+                with gr.Accordion("2 · UNIVERSE & DATA", open=True, elem_classes="bit-accordion"):
+                    asset = gr.Dropdown(choices=runtime.available_assets(),
+                                        value="BTC-USD", label="Asset")
+                    timeframe = gr.Radio(choices=list(config.TIMEFRAMES),
+                                         value="1d", label="Timeframe")
+                    date_range = gr.Radio(choices=["1Y", "3Y", "5Y", "Max"],
+                                          value="3Y", label="Date range")
+                    coverage_note = gr.HTML("")
+
+                with gr.Accordion("3 · COSTS & EXECUTION", open=False, elem_classes="bit-accordion"):
+                    costs_on = gr.Checkbox(value=True, label="Costs on")
+                    gr.HTML('<div class="bit-note">Costs on. Turning these off is how '
+                            'strategies lie to you.</div>')
+                    commission_bps = gr.Number(value=10.0, label="Commission bps / side")
+                    slippage_bps = gr.Number(value=5.0, label="Slippage bps")
+                    slippage_model = gr.Radio(choices=["Fixed bps", "Volume-scaled"],
+                                              value="Fixed bps", label="Slippage model")
+                    gr.Radio(choices=["Next bar open"], value="Next bar open",
+                             label="Fill", interactive=False,
+                             info="Next-bar-open execution is enforced by the engine.")
+
+                with gr.Accordion("4 · SIZING & RISK", open=False, elem_classes="bit-accordion"):
+                    sizing_mode = gr.Radio(choices=["Fixed %", "Vol-target 15% ann."],
+                                           value="Fixed %", label="Sizing")
+                    size_pct = gr.Slider(0.05, 1.0, value=1.0, step=0.05,
+                                         label="Position size (fraction of equity)")
+                    leverage = gr.Slider(1.0, 3.0, value=1.0, step=0.5, label="Leverage")
+                    sl_pct = gr.Number(value=None, label="Stop loss %")
+                    tp_pct = gr.Number(value=None, label="Take profit %")
+                    trail_pct = gr.Number(value=None, label="Trailing stop %")
+
+                with gr.Accordion("5 · VALIDATION", open=False, elem_classes="bit-accordion"):
+                    validation_mode = gr.Radio(
+                        choices=["Walk-forward", "Simple split", "Holdout only", "None"],
+                        value="Walk-forward", label="Mode")
+                    train_m = gr.Number(value=12, label="Train months", precision=0)
+                    test_m = gr.Number(value=3, label="Test months", precision=0)
+                    roll_m = gr.Number(value=3, label="Roll months", precision=0)
+                    holdout_m = gr.Number(value=6, label="OOS holdout months", precision=0)
+
+                run_btn = gr.Button("▶ Run backtest", variant="primary",
+                                    elem_classes="bit-run-btn")
+                with gr.Row():
+                    example_btn = gr.Button("Load example", size="sm",
+                                            elem_classes="bit-ghost-btn")
+                    share_btn = gr.Button("Share link", size="sm",
+                                          elem_classes="bit-ghost-btn")
+                share_out = gr.Textbox(label="Share token", visible=False,
+                                       show_copy_button=True, lines=2)
+
+            # =========================== CENTER ===========================
+            with gr.Column(scale=7, min_width=520):
+                run_status = gr.HTML("")
+                stat_band = gr.HTML("")
+                empty_state = gr.HTML(EMPTY_HTML)
+
+                with gr.Tabs():
+                    with gr.Tab("Overview"):
+                        equity_plot = gr.Plot(label=None)
+                        with gr.Row():
+                            log_scale = gr.Checkbox(value=False, label="Log scale")
+                            cvd = gr.Checkbox(value=False, label="Colorblind-safe prices")
+                        regime_plot = gr.Plot(label=None)
+                        with gr.Row():
+                            underwater_plot = gr.Plot(label=None)
+                            rolling_plot = gr.Plot(label=None)
+                        price_plot = gr.Plot(label=None)
+                        with gr.Row():
+                            pnl_plot = gr.Plot(label=None)
+                            hold_plot = gr.Plot(label=None)
+                            mae_plot = gr.Plot(label=None)
+                        costs_note = gr.HTML("")
+
+                    with gr.Tab("Trades"):
+                        trades_head = gr.HTML("")
+                        trades_table = gr.Dataframe(
+                            value=pd.DataFrame(), interactive=False, wrap=False,
+                            elem_classes="bit-table", max_height=520,
+                        )
+                        export_btn = gr.Button("Export CSV →", size="sm",
+                                               elem_classes="bit-ghost-btn")
+                        export_file = gr.File(label="trades.csv", visible=False)
+
+                    with gr.Tab("Comparison"):
+                        gr.HTML('<div class="bit-micro">CELL = OOS SHARPE · '
+                                'PRECOMPUTED FROM THE SIGNAL STORE</div>')
+                        heatmap_plot = gr.Plot(label=None)
+                        gr.HTML('<div class="bit-micro">SELECTED RUNS · '
+                                f'MAX {MAX_COMPARE}</div>')
+                        compare_picker = gr.CheckboxGroup(choices=[], value=[],
+                                                          label="Runs to compare")
+                        overlay_plot = gr.Plot(label=None)
+                        small_mult_plot = gr.Plot(label=None)
+                        with gr.Row():
+                            corr_plot = gr.Plot(label=None)
+                            regime_bars_plot = gr.Plot(label=None)
+                        metrics_table = gr.Dataframe(value=pd.DataFrame(),
+                                                     interactive=False,
+                                                     elem_classes="bit-table")
+
+                    with gr.Tab("Robustness"):
+                        verdict_html = gr.HTML("")
+                        with gr.Row():
+                            wf_plot = gr.Plot(label=None)
+                            mc_plot = gr.Plot(label=None)
+                        with gr.Row():
+                            sens_plot = gr.Plot(label=None)
+                            slip_plot = gr.Plot(label=None)
+                        robust_btn = gr.Button(
+                            "Run sensitivity + slippage stress (slower)",
+                            size="sm", elem_classes="bit-ghost-btn")
+
+                    with gr.Tab("Report"):
+                        report_md = gr.Markdown("_Run a backtest to generate the report._")
+                        report_equity = gr.Plot(label=None)
+                        with gr.Row():
+                            save_run_btn = gr.Button("Save run summary", size="sm",
+                                                     elem_classes="bit-ghost-btn")
+                            copy_cfg_btn = gr.Button("Copy share link", size="sm",
+                                                     elem_classes="bit-ghost-btn")
+                        save_note = gr.HTML("")
+
+                    with gr.Tab("Coverage"):
+                        gr.HTML('<div class="bit-micro">SIGNAL STORE COVERAGE MAP · '
+                                'MODEL × ASSET × TIMEFRAME</div>')
+                        coverage_table = gr.Dataframe(
+                            value=runtime.coverage_frame(), interactive=False,
+                            elem_classes="bit-table", max_height=420)
+                        gr.HTML('<div class="bit-micro" style="margin-top:8px">'
+                                'EXTEND COVERAGE</div>')
+                        extend_panel = gr.HTML("")
+                        with gr.Row():
+                            ext_model = gr.Dropdown(choices=list(config.SEED_MODELS),
+                                                    label="Model", scale=2)
+                            ext_asset = gr.Dropdown(choices=list(config.ASSETS),
+                                                    label="Asset", scale=2)
+                            ext_tf = gr.Dropdown(choices=list(config.TIMEFRAMES),
+                                                 value="1d", label="Timeframe", scale=1)
+                        with gr.Row():
+                            ext_start = gr.Textbox(label="Start (YYYY-MM-DD)", scale=2)
+                            ext_end = gr.Textbox(label="End (YYYY-MM-DD)", scale=2)
+                        with gr.Row():
+                            estimate_btn = gr.Button("Estimate", size="sm",
+                                                     elem_classes="bit-ghost-btn")
+                            extend_btn = gr.Button("Extend coverage", size="sm",
+                                                   elem_classes="bit-run-btn")
+                        extend_out = gr.HTML("")
+
+                        gr.HTML('<div class="bit-micro" style="margin-top:16px">'
+                                'ADD MODEL</div>')
+                        with gr.Row():
+                            add_family = gr.Dropdown(
+                                choices=list(config.ALLOWED_ADAPTER_FAMILIES),
+                                value="chronos", label="Adapter family", scale=1)
+                            add_model_id = gr.Textbox(label="HF model id (owner/name)",
+                                                      scale=2)
+                            add_btn = gr.Button("Smoke test & add", size="sm",
+                                                elem_classes="bit-ghost-btn", scale=1)
+                        add_out = gr.HTML("")
+
+            # ============================ RIGHT ===========================
+            with gr.Column(scale=2, min_width=250):
+                gr.HTML('<div class="bit-h2" style="padding:12px 4px 4px">Run Manager</div>')
+                login_slot = gr.HTML("")
+                try:
+                    gr.LoginButton(value="Sign in with Hugging Face", size="sm")
+                except Exception:
+                    login_slot.value = (
+                        '<div class="bit-note">Sign-in appears when the Space runs '
+                        'on Hugging Face with OAuth enabled.</div>')
+                history_html = gr.HTML(
+                    '<div class="bit-micro">NO RUNS YET IN THIS SESSION</div>')
+                with gr.Accordion("METRICS GLOSSARY", open=False,
+                                  elem_classes="bit-accordion"):
+                    gr.HTML(glossary_html())
+                with gr.Accordion("HOW RESULTS ARE COMPUTED", open=False,
+                                  elem_classes="bit-accordion"):
+                    gr.Markdown(
+                        "- Fills execute at the **next bar's open**. A decision at bar "
+                        "`t` can never trade at bar `t`.\n"
+                        "- Strategies are checked for lookahead by perturbing future "
+                        "prices and asserting past outputs do not move.\n"
+                        "- Costs are **on by default**: commission per side plus a "
+                        "slippage model, both booked onto every trade row.\n"
+                        "- The locked holdout is excluded from every parameter-selection "
+                        "path, not merely reported separately.\n"
+                        "- The store holds raw model outputs only. Trading rules are "
+                        "applied live, per run."
+                    )
+
+        gr.HTML(FOOTER_HTML)
+
+        # ------------------------------------------------------------------
+        # Wiring
+        # ------------------------------------------------------------------
+
+        builder_inputs = [strategy, asset, timeframe, date_range, model_slug,
+                          p1, p2, p3, costs_on, commission_bps, slippage_bps,
+                          slippage_model, sizing_mode, size_pct, leverage,
+                          sl_pct, tp_pct, trail_pct,
+                          validation_mode, train_m, test_m, roll_m, holdout_m]
+
+        overview_outputs = [equity_plot, regime_plot, underwater_plot, rolling_plot,
+                            price_plot, pnl_plot, hold_plot, mae_plot, costs_note]
+
+        def on_strategy_change(name):
+            preset = strategies.PRESETS.get(name)
+            if preset is None:
+                return (gr.update(), gr.update(), gr.update(), gr.update(), "")
+            if not preset.available:
+                note = (f'<div class="bit-note bit-note-danger">{name} is unavailable. '
+                        f'{preset.unavailable_reason}</div>')
+            else:
+                note = ""
+            ups = []
+            for i in range(3):
+                if i < len(preset.params):
+                    key, label, default, lo, hi = preset.params[i]
+                    ups.append(gr.update(label=label, value=default, visible=True))
+                else:
+                    ups.append(gr.update(visible=False, value=None))
+            model_up = gr.update(visible=preset.needs_signals,
+                                 choices=runtime.available_models(),
+                                 value=(runtime.available_models() or [None])[0]
+                                 if preset.needs_signals else None)
+            return (*ups, model_up, note)
+
+        strategy.change(on_strategy_change, [strategy], [p1, p2, p3, model_slug, preset_note])
+
+        def on_universe_change(a, tf):
+            cov = runtime.price_coverage_for(a, tf)
+            models = runtime.available_models(a, tf)
+            if cov is None:
+                html = ('<div class="bit-note bit-note-danger">No cached price coverage '
+                        f'for {a} {tf}. Pick another pair or extend coverage.</div>')
+            else:
+                html = (f'<div class="bit-micro">CACHED {cov[0]} → {cov[1]}'
+                        + (f' · MODELS: {", ".join(models)}' if models else
+                           ' · NO MODEL SIGNALS') + '</div>')
+            return html, gr.update(choices=models,
+                                   value=(models[0] if models else None))
+
+        asset.change(on_universe_change, [asset, timeframe], [coverage_note, model_slug])
+        timeframe.change(on_universe_change, [asset, timeframe], [coverage_note, model_slug])
+
+        def do_run(hist, *vals, progress=gr.Progress()):
+            progress(0.05, desc="Reading cached slices")
+            req = collect_request(*vals)
+            try:
+                progress(0.35, desc="Simulating trades")
+                rec = runtime.execute(req)
+            except (RunError, ValueError) as e:
+                err = f'<div class="bit-note bit-note-danger">{e}</div>'
+                return (hist, None, top_bar_html("RUN FAILED", "bit-chip bit-chip-warn"),
+                        err, "", gr.update(visible=True), *(gr.update(),) * 9,
+                        "", pd.DataFrame(), "", gr.update(choices=[], value=[]),
+                        "_Run failed._", None)
+
+            progress(0.75, desc="Building charts")
+            hist = ([rec] + list(hist))[:40]
+            figs = build_overview(rec, log_scale=False, cvd=False)
+            progress(0.95, desc="Computing robustness")
+
+            choices = [f"{r.run_id} · {r.label}" for r in hist]
+            return (
+                hist, rec,
+                top_bar_html(f"RUN {rec.run_id} COMPLETE · {rec.elapsed_s:.1f}S",
+                             "bit-chip bit-chip-ok", context_chip(req)),
+                "", stat_band_html(rec), gr.update(visible=False),
+                *figs,
+                trades_head_html(rec), trades_frame(rec),
+                history_list_html(hist),
+                gr.update(choices=choices, value=choices[:1]),
+                report_markdown(rec),
+                charts.equity_curve(rec.result.equity, rec.result.benchmark_equity,
+                                    plan=rec.result.plan),
+            )
+
+        run_outputs = [history, current, top_bar, run_status, stat_band, empty_state,
+                       *overview_outputs, trades_head, trades_table, history_html,
+                       compare_picker, report_md, report_equity]
+
+        run_btn.click(do_run, [history, *builder_inputs], run_outputs)
+
+        def load_example():
+            """The design's worked example: Sentiment-Gated Momentum on BTC 1h."""
+            return ("Sentiment-Gated Momentum", "BTC-USD", "1h", "1Y",
+                    gr.update(value=20, label="Fast MA", visible=True),
+                    gr.update(value=50, label="Slow MA", visible=True),
+                    gr.update(value=0.40, label="Sentiment gate", visible=True),
+                    True, "Walk-forward")
+
+        example_btn.click(
+            load_example, None,
+            [strategy, asset, timeframe, date_range, p1, p2, p3, costs_on, validation_mode],
+        ).then(do_run, [history, *builder_inputs], run_outputs)
+
+        def replot(rec, log_s, colorblind):
+            if rec is None:
+                return (gr.update(),) * 9
+            return build_overview(rec, log_scale=log_s, cvd=colorblind)
+
+        log_scale.change(replot, [current, log_scale, cvd], overview_outputs)
+        cvd.change(replot, [current, log_scale, cvd], overview_outputs)
+
+        def do_share(*vals):
+            req = collect_request(*vals)
+            return gr.update(value=req.encode(), visible=True)
+
+        share_btn.click(do_share, builder_inputs, [share_out])
+        copy_cfg_btn.click(lambda r: gr.update(value=r.request.encode(), visible=True)
+                           if r else gr.update(), [current], [share_out])
+
+        def do_export(rec):
+            if rec is None or rec.result.trades.empty:
+                return gr.update(visible=False)
+            path = f"/tmp/trades_{rec.run_id}.csv"
+            rec.result.trades.to_csv(path, index=False)
+            return gr.update(value=path, visible=True)
+
+        export_btn.click(do_export, [current], [export_file])
+
+        def do_save(rec):
+            if rec is None:
+                return '<div class="bit-note">Nothing to save yet.</div>'
+            try:
+                rid = runtime.save_run_summary(rec)
+                return (f'<div class="bit-note">Run <b>{rid}</b> staged for the store. '
+                        f'It is committed with the next batch.</div>')
+            except Exception as e:
+                return f'<div class="bit-note bit-note-danger">Could not save: {e}</div>'
+
+        save_run_btn.click(do_save, [current], [save_note])
+
+        def do_compare(hist, picks):
+            hist = list(hist or [])
+            by_id = {f"{r.run_id} · {r.label}": r for r in hist}
+            chosen = [by_id[p] for p in (picks or [])[:MAX_COMPARE] if p in by_id]
+            if not chosen:
+                empty = charts.empty_figure("select runs to compare")
+                return empty, empty, empty, empty, pd.DataFrame()
+
+            curves = {r.label[:28]: r.result.equity for r in chosen}
+            rets = {r.label[:28]: r.result.equity.pct_change().dropna() for r in chosen}
+            regimes = [runtime.regime_breakdown(r) for r in chosen]
+            regime_df = regimes[0] if regimes else pd.DataFrame()
+            for extra in regimes[1:]:
+                if not extra.empty and not regime_df.empty:
+                    regime_df = regime_df.merge(extra, on="regime", how="outer")
+
+            rows = []
+            for label, key in (("Total return", "total_return"), ("CAGR", "cagr"),
+                               ("OOS Sharpe", None), ("Max drawdown", "max_drawdown"),
+                               ("Win rate", "win_rate"), ("Trades", "trade_count")):
+                row = {"Metric": label}
+                for r in chosen:
+                    if key is None:
+                        row[r.label[:22]] = num(r.result.metrics_oos.sharpe)
+                    elif key == "trade_count":
+                        row[r.label[:22]] = r.result.metrics_all.trade_count
+                    elif key == "win_rate":
+                        row[r.label[:22]] = pct(r.result.metrics_all.win_rate, 0, False)
+                    else:
+                        row[r.label[:22]] = pct(getattr(r.result.metrics_all, key))
+                rows.append(row)
+
+            return (charts.overlaid_returns(curves),
+                    charts.small_multiples(curves),
+                    charts.correlation_matrix(rets),
+                    charts.regime_bars(regime_df),
+                    pd.DataFrame(rows))
+
+        compare_picker.change(do_compare, [history, compare_picker],
+                              [overlay_plot, small_mult_plot, corr_plot,
+                               regime_bars_plot, metrics_table])
+
+        def do_robustness(rec):
+            if rec is None:
+                e = charts.empty_figure("run a backtest first")
+                return "", e, e, e, e
+            grade, checks = runtime.overfit_verdict(rec)
+            items = "".join(
+                f'<div style="font-size:11px;color:var(--text-secondary)">{m} {t}</div>'
+                for m, t in checks)
+            html = (f'<div class="bit-panel"><div class="bit-h2">Overfit verdict: '
+                    f'<span style="color:var(--accent-amber-strong)">{grade}</span></div>'
+                    f'{items}</div>')
+            wf = charts.walk_forward_bars(rec.result.windows)
+            mc = charts.monte_carlo_cone(charts.monte_carlo_paths(rec.result.trades))
+            e = charts.empty_figure("press the button below to run the sweep")
+            return html, wf, mc, e, e
+
+        current.change(do_robustness, [current],
+                       [verdict_html, wf_plot, mc_plot, sens_plot, slip_plot])
+
+        def do_sweep(rec, progress=gr.Progress()):
+            if rec is None:
+                e = charts.empty_figure("run a backtest first")
+                return e, e
+            req = rec.request
+            preset = strategies.PRESETS.get(req.strategy)
+            keys = [p[0] for p in (preset.params if preset else [])][:2]
+            if len(keys) < 2:
+                sens = charts.empty_figure("this preset has fewer than two parameters")
+            else:
+                progress(0.1, desc="Parameter sweep")
+                base_x = req.params.get(keys[0], 20)
+                base_y = req.params.get(keys[1], 50)
+                xs = sorted({max(2, int(base_x * m)) for m in (0.5, 0.75, 1.0, 1.5, 2.0)})
+                ys = sorted({max(3, int(base_y * m)) for m in (0.5, 0.75, 1.0, 1.5, 2.0)})
+                grid = runtime.parameter_sweep(req, keys[0], xs, keys[1], ys)
+                sens = charts.parameter_sensitivity(grid, x=keys[0], y=keys[1])
+            progress(0.7, desc="Slippage stress")
+            slip = charts.slippage_stress(runtime.slippage_stress(req))
+            return sens, slip
+
+        robust_btn.click(do_sweep, [current], [sens_plot, slip_plot])
+
+        # ---- Coverage / extension (Phase 4) ----
+        from src import extension
+
+        estimate_btn.click(extension.estimate_ui, [ext_model, ext_asset, ext_tf,
+                                                   ext_start, ext_end], [extend_out])
+        extend_btn.click(extension.extend_ui,
+                         [ext_model, ext_asset, ext_tf, ext_start, ext_end],
+                         [extend_out, coverage_table])
+        add_btn.click(extension.add_model_ui, [add_family, add_model_id],
+                      [add_out, coverage_table])
+
+        # ---- Load: heatmap, coverage, share-link restore ----
+        def on_load(request: gr.Request):
+            store = runtime.get_store()
+            heat = comparisons.load_table(store, comparisons.HEATMAP)
+            fig = charts.strategy_timeframe_heatmap(heat)
+            cov_html = ""
+            restored = [gr.update()] * 4
+            token = None
+            try:
+                token = dict(request.query_params).get("cfg") if request else None
+            except Exception:
+                token = None
+            if token:
+                try:
+                    req = RunRequest.decode(token)
+                    restored = [gr.update(value=req.strategy), gr.update(value=req.asset),
+                                gr.update(value=req.timeframe),
+                                gr.update(value=req.date_range)]
+                    cov_html = '<div class="bit-note">Config restored from share link.</div>'
+                except Exception as e:
+                    cov_html = (f'<div class="bit-note bit-note-danger">'
+                                f'Share link rejected: {e}</div>')
+            return (fig, runtime.coverage_frame(), extension.status_html(),
+                    cov_html, *restored)
+
+        demo.load(on_load, None,
+                  [heatmap_plot, coverage_table, extend_panel, run_status,
+                   strategy, asset, timeframe, date_range])
+
+        demo.load(lambda: on_universe_change("BTC-USD", "1d"), None,
+                  [coverage_note, model_slug])
+
+    return demo
+
+
+def trades_head_html(rec: RunRecord | None) -> str:
+    if rec is None or rec.result.trades.empty:
+        return '<div class="bit-micro">NO TRADES</div>'
+    n = len(rec.result.trades)
+    costs = rec.result.costs_paid
+    return (f'<div class="bit-micro">{n} TOTAL · COSTS PAID {money(costs)} · '
+            f'FILLS AT NEXT BAR OPEN</div>')
+
+
+def history_list_html(hist) -> str:
+    if not hist:
+        return '<div class="bit-micro">NO RUNS YET IN THIS SESSION</div>'
+    rows = []
+    for r in hist[:12]:
+        s = r.sharpe
+        color = ("var(--accent-moss-strong)" if s >= 1
+                 else "var(--fin-down)" if s < 0 else "var(--text-secondary)")
+        rows.append(
+            f'<div style="border:1px solid var(--border-subtle);padding:6px;margin-bottom:4px">'
+            f'<div style="font-size:11px;color:var(--text-primary)">{r.label[:34]}</div>'
+            f'<div class="bit-micro">{r.meta}</div>'
+            f'<div style="font-family:var(--font-mono);font-size:12px;color:{color}">'
+            f'SHARPE {s:.2f}</div></div>'
+        )
+    return "".join(rows)
+
+
+def build_overview(rec: RunRecord, *, log_scale: bool, cvd: bool):
+    r = rec.result
+    bpy = config.bars_per_year(rec.request.asset, rec.request.timeframe)
+    window = {"1d": 90, "1h": 24 * 30, "15m": 4 * 24 * 14}.get(rec.request.timeframe, 90)
+
+    costs_html = (
+        f'<div class="bit-note">COSTS PAID TOTAL: {money(r.costs_paid)}. '
+        f'The costed number is the real one.</div>'
+        if rec.request.costs_on else
+        '<div class="bit-note bit-note-danger">COSTS ARE OFF. '
+        'These numbers are not achievable.</div>'
+    )
+    return (
+        charts.equity_curve(r.equity, r.benchmark_equity, plan=r.plan,
+                            log_scale=log_scale, cvd=cvd),
+        charts.regime_strip(r.prices),
+        charts.underwater_chart(r.equity),
+        charts.rolling_sharpe_chart(r.equity, window, bpy),
+        charts.price_with_trades(r.prices, r.trades, cvd=cvd),
+        charts.pnl_histogram(r.trades, cvd=cvd),
+        charts.holding_period_histogram(r.trades),
+        charts.mae_mfe_scatter(r.trades, cvd=cvd),
+        costs_html,
+    )
+
+
+demo = build_app()
+
+if __name__ == "__main__":
+    gr.set_static_paths(paths=theme.static_paths())
+    demo.queue(max_size=32).launch(
+        server_name="0.0.0.0",
+        server_port=int(os.environ.get("PORT", 7860)),
+        show_api=False,
+    )

assets/fonts/MacMinecraft.ttf

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

assets/fonts/StyreneA-Light.otf

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

assets/fonts/StyreneA-LightItalic.otf

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

assets/fonts/StyreneA-Medium.otf

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

assets/fonts/StyreneA-MediumItalic.otf

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

assets/fonts/StyreneA-Regular.otf

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

assets/fonts/StyreneA-RegularItalic.otf

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

assets/fonts/StyreneA-Thin.otf

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

assets/fonts/StyreneA-ThinItalic.otf

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

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);}

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);
+}
+

assets/tokens/fonts.css

@@ -0,0 +1,10 @@
+@import url('https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600;700&display=swap');
+@font-face{font-family:'Styrene A';src:url('../assets/fonts/StyreneA-Thin.otf') format('opentype');font-weight:100;font-style:normal;font-display:swap}
+@font-face{font-family:'Styrene A';src:url('../assets/fonts/StyreneA-ThinItalic.otf') format('opentype');font-weight:100;font-style:italic;font-display:swap}
+@font-face{font-family:'Styrene A';src:url('../assets/fonts/StyreneA-Light.otf') format('opentype');font-weight:300;font-style:normal;font-display:swap}
+@font-face{font-family:'Styrene A';src:url('../assets/fonts/StyreneA-LightItalic.otf') format('opentype');font-weight:300;font-style:italic;font-display:swap}
+@font-face{font-family:'Styrene A';src:url('../assets/fonts/StyreneA-Regular.otf') format('opentype');font-weight:400;font-style:normal;font-display:swap}
+@font-face{font-family:'Styrene A';src:url('../assets/fonts/StyreneA-RegularItalic.otf') format('opentype');font-weight:400;font-style:italic;font-display:swap}
+@font-face{font-family:'Styrene A';src:url('../assets/fonts/StyreneA-Medium.otf') format('opentype');font-weight:500;font-style:normal;font-display:swap}
+@font-face{font-family:'Styrene A';src:url('../assets/fonts/StyreneA-MediumItalic.otf') format('opentype');font-weight:500;font-style:italic;font-display:swap}
+@font-face{font-family:'Mac Minecraft';src:url('../assets/fonts/MacMinecraft.ttf') format('truetype');font-weight:400;font-style:normal;font-display:swap}

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 */
+}

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;
+}

conftest.py

@@ -0,0 +1,2 @@
+import sys, pathlib
+sys.path.insert(0, str(pathlib.Path(__file__).parent))

pytest.ini

@@ -0,0 +1,6 @@
+[pytest]
+testpaths = tests
+markers =
+    slow: tests that load a real model or hit the network
+filterwarnings =
+    ignore::DeprecationWarning

requirements.txt

@@ -0,0 +1,32 @@
+# Backtest Lab — pinned. Every version here is the one the test suite passes on.
+
+# UI
+gradio[oauth]==5.49.1
+plotly==6.9.0
+
+# Engine
+vectorbt==1.1.0
+numpy==2.4.6
+pandas==2.3.3
+numba==0.67.0
+scipy==1.17.1
+scikit-learn==1.9.0
+
+# Store
+huggingface_hub==1.27.0
+pyarrow==25.0.1
+
+# Price providers
+ccxt==4.5.73
+yfinance==1.6.0
+requests==2.34.2
+
+# Forecast adapters. Imported lazily inside ForecastAdapter.load(), so app boot
+# never pays for them -- this keeps cold start fast on cpu-basic while still
+# letting the ZeroGPU extension path work when GPU hardware is attached.
+torch==2.13.0
+chronos-forecasting==2.3.1
+
+# ZeroGPU runtime. Absent locally and on cpu-basic; extension.py degrades to a
+# "coming soon" state when it cannot be imported.
+spaces==0.44.1

scripts/seed_store.py

@@ -0,0 +1,318 @@
+#!/usr/bin/env python
+"""Seed the signal store: refresh prices, run inference, build comparison tables.
+
+Runnable locally, in Colab, or from the Space's ZeroGPU function. Progress is
+checkpointed after every batch, so an interrupted run resumes where it stopped
+rather than paying for the same inference twice.
+
+    python scripts/seed_store.py --plan v1 --dry-run
+    python scripts/seed_store.py --plan v1 --prices-only
+    python scripts/seed_store.py --plan v1 --push
+
+Nothing is recomputed that the manifest already covers.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+import sys
+import time
+from dataclasses import dataclass, asdict, field
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from src import comparisons, config  # noqa: E402
+from src.adapters import build_windows, get_adapter  # noqa: E402
+from src.data import refresh  # noqa: E402
+from src.store import SignalStore  # noqa: E402
+
+log = logging.getLogger("seed")
+
+
+# --------------------------------------------------------------------------
+# Seed plans
+# --------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class SeedTarget:
+    model_slug: str
+    asset: str
+    timeframe: str
+    years: float
+    # Placeholder targets are written with inference_version PLACEHOLDER and
+    # are replaced the moment a real run covers the same slice.
+    placeholder: bool = False
+
+    @property
+    def key(self) -> str:
+        return f"{self.model_slug}|{self.asset}|{self.timeframe}"
+
+
+CRYPTO = ["BTC-USD", "ETH-USD", "SOL-USD"]
+EQUITIES = ["SPY", "QQQ", "NVDA"]
+
+
+def plan_v1() -> list[SeedTarget]:
+    """The v1 seed: crypto-first, honest about provider depth limits.
+
+    Daily coverage is real for every asset on both Chronos models. Hourly is
+    real for crypto on the small model. 15-minute coverage is placeholder-only
+    in v1 -- the inference cost is large and the provider depth for equities is
+    60 days, so it is labelled rather than faked as real.
+    """
+    targets: list[SeedTarget] = []
+
+    for asset in CRYPTO + EQUITIES:
+        targets.append(SeedTarget("chronos-bolt-small", asset, "1d", 3.0))
+    for asset in CRYPTO:
+        targets.append(SeedTarget("chronos-bolt-base", asset, "1d", 3.0))
+
+    # Hourly: crypto has full depth from the exchange; equities are capped at
+    # the provider's ~730 days, recorded as a boundary in the manifest.
+    for asset in CRYPTO:
+        targets.append(SeedTarget("chronos-bolt-small", asset, "1h", 1.0))
+    for asset in EQUITIES:
+        targets.append(SeedTarget("chronos-bolt-small", asset, "1h", 1.5))
+
+    # 15-minute crypto. Batched Chronos-Bolt inference turned out to cost about
+    # a millisecond per step on this hardware, so these are real rather than
+    # placeholder -- the v1 seed ships with no synthetic slices at all.
+    for asset in CRYPTO:
+        targets.append(SeedTarget("chronos-bolt-small", asset, "15m", 0.25))
+    return targets
+
+
+def plan_smoke() -> list[SeedTarget]:
+    """One model, one asset, six months -- proves the pipeline end to end."""
+    return [SeedTarget("chronos-bolt-small", "BTC-USD", "1d", 0.5)]
+
+
+PLANS = {"v1": plan_v1, "smoke": plan_smoke}
+
+
+# --------------------------------------------------------------------------
+# Checkpointing
+# --------------------------------------------------------------------------
+
+
+@dataclass
+class Checkpoint:
+    path: Path
+    done: dict[str, str] = field(default_factory=dict)  # key -> last ts written
+    failed: dict[str, str] = field(default_factory=dict)
+
+    @classmethod
+    def load(cls, path: str | os.PathLike) -> "Checkpoint":
+        p = Path(path)
+        if p.exists():
+            try:
+                raw = json.loads(p.read_text())
+                return cls(path=p, done=raw.get("done", {}), failed=raw.get("failed", {}))
+            except json.JSONDecodeError:
+                log.warning("checkpoint at %s was corrupt; starting fresh", p)
+        return cls(path=p)
+
+    def save(self) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.path.write_text(json.dumps(
+            {"done": self.done, "failed": self.failed,
+             "updated_at": pd.Timestamp.now(tz="UTC").isoformat()}, indent=2))
+
+    def mark(self, key: str, last_ts) -> None:
+        self.done[key] = str(last_ts)
+        self.failed.pop(key, None)
+        self.save()
+
+    def mark_failed(self, key: str, reason: str) -> None:
+        self.failed[key] = reason
+        self.save()
+
+    def last_ts(self, key: str) -> pd.Timestamp | None:
+        v = self.done.get(key)
+        return pd.Timestamp(v) if v else None
+
+
+# --------------------------------------------------------------------------
+# Steps
+# --------------------------------------------------------------------------
+
+
+def refresh_prices(store: SignalStore, targets: list[SeedTarget]) -> list[str]:
+    """Fetch only the price ranges the store is missing."""
+    notes = []
+    wanted: dict[tuple[str, str], float] = {}
+    for t in targets:
+        k = (t.asset, t.timeframe)
+        wanted[k] = max(wanted.get(k, 0.0), t.years)
+
+    end = pd.Timestamp.now(tz="UTC").floor("h")
+    for (asset, tf), years in sorted(wanted.items()):
+        start = end - pd.Timedelta(days=int(365 * years) + 30)
+        rep = refresh(store, asset, tf, start, end)
+        log.info("%s", rep.summary())
+        notes.append(rep.summary())
+        for n in rep.boundary_notes:
+            log.info("  boundary: %s", n)
+            notes.append(f"  boundary: {n}")
+    return notes
+
+
+def seed_target(store: SignalStore, target: SeedTarget, ckpt: Checkpoint,
+                *, batch_size: int = 256, device: str | None = None,
+                force_placeholder: bool = False) -> str:
+    """Run inference for one (model, asset, timeframe) and write the slice."""
+    spec = config.SEED_MODELS.get(target.model_slug)
+    if spec is None:
+        return f"SKIP {target.key}: unknown model"
+
+    prices = store.get_prices(target.asset, target.timeframe)
+    if prices.empty:
+        return f"SKIP {target.key}: no price coverage"
+
+    end = prices.index[-1]
+    start = end - pd.Timedelta(days=int(365 * target.years))
+    prices = prices[prices.index >= start]
+    close = prices["close"]
+
+    use_placeholder = target.placeholder or force_placeholder
+    family = "placeholder" if use_placeholder else spec.family
+    ctx_len = min(spec.context_len, max(64, len(close) // 3))
+
+    adapter = get_adapter(family, spec.model_id, context_len=ctx_len, device=device)
+    adapter.load()
+    revision = adapter.resolved_revision
+    version = adapter.inference_version()
+
+    stamps, windows = build_windows(close, ctx_len)
+    if len(stamps) == 0:
+        return f"SKIP {target.key}: only {len(close)} bars, need > {ctx_len}"
+
+    # Idempotency: never recompute what the manifest already covers. The range
+    # to check is the one the windows actually produce -- signals start a full
+    # context window after the first price bar, so checking the price range
+    # would always report the leading context as an uncovered gap.
+    missing = store.missing_ranges(target.model_slug, revision, target.asset,
+                                   target.timeframe, stamps[0], stamps[-1])
+    if not missing:
+        return f"SKIP {target.key}: already covered by the manifest"
+
+    resume_from = ckpt.last_ts(target.key)
+    if resume_from is not None:
+        keep = stamps > resume_from
+        stamps, windows = stamps[keep], windows[keep]
+        if len(stamps) == 0:
+            return f"SKIP {target.key}: checkpoint says complete"
+
+    t0 = time.perf_counter()
+    written = 0
+    for i in range(0, len(stamps), batch_size):
+        bs, bw = stamps[i:i + batch_size], windows[i:i + batch_size]
+        forecast = adapter.predict(bw)
+        frame = forecast.as_frame(bs, version)
+        store.write_signals(
+            target.model_slug, spec.model_id, revision, target.asset,
+            target.timeframe, frame,
+            inference_version=version, contributed_by="seed",
+        )
+        written += len(frame)
+        ckpt.mark(target.key, bs[-1])
+        log.info("  %s %d/%d", target.key, min(i + batch_size, len(stamps)), len(stamps))
+
+    dt = time.perf_counter() - t0
+    tag = " [PLACEHOLDER]" if use_placeholder else ""
+    return (f"OK   {target.key}: {written} steps in {dt:.1f}s "
+            f"({dt / max(written, 1) * 1000:.0f} ms/step){tag}")
+
+
+# --------------------------------------------------------------------------
+# Main
+# --------------------------------------------------------------------------
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="Seed the bit signal store")
+    ap.add_argument("--plan", default="v1", choices=sorted(PLANS))
+    ap.add_argument("--store-root", default=".cache/store")
+    ap.add_argument("--checkpoint", default=".cache/seed_checkpoint.json")
+    ap.add_argument("--repo", default=config.STORE_REPO)
+    ap.add_argument("--batch-size", type=int, default=256)
+    ap.add_argument("--device", default=None)
+    ap.add_argument("--prices-only", action="store_true")
+    ap.add_argument("--skip-prices", action="store_true")
+    ap.add_argument("--placeholder-only", action="store_true",
+                    help="write labelled synthetic signals instead of running models")
+    ap.add_argument("--no-comparisons", action="store_true")
+    ap.add_argument("--push", action="store_true", help="commit to the Hub when done")
+    ap.add_argument("--offline", action="store_true")
+    ap.add_argument("--dry-run", action="store_true")
+    ap.add_argument("--only", default=None, help="substring filter on target keys")
+    args = ap.parse_args(argv)
+
+    logging.basicConfig(level=logging.INFO, format="%(message)s")
+
+    targets = PLANS[args.plan]()
+    if args.only:
+        targets = [t for t in targets if args.only in t.key]
+
+    if args.dry_run:
+        print(f"plan={args.plan}  targets={len(targets)}")
+        for t in targets:
+            print(f"  {t.key:48s} years={t.years:<5g} placeholder={t.placeholder}")
+        return 0
+
+    store = SignalStore(repo_id=None if args.offline else args.repo,
+                        local_root=args.store_root, offline=args.offline)
+    ckpt = Checkpoint.load(args.checkpoint)
+    results: list[str] = []
+
+    if not args.skip_prices:
+        log.info("== refreshing prices ==")
+        results.extend(refresh_prices(store, targets))
+
+    if not args.prices_only:
+        log.info("== running inference ==")
+        for t in targets:
+            try:
+                msg = seed_target(store, t, ckpt, batch_size=args.batch_size,
+                                  device=args.device,
+                                  force_placeholder=args.placeholder_only)
+            except Exception as e:
+                log.exception("target %s failed", t.key)
+                ckpt.mark_failed(t.key, f"{type(e).__name__}: {e}")
+                msg = f"FAIL {t.key}: {type(e).__name__}: {e}"
+            log.info("%s", msg)
+            results.append(msg)
+
+    if not args.no_comparisons:
+        log.info("== regenerating comparison tables ==")
+        report = comparisons.regenerate(store)
+        results.append(
+            f"comparisons: perf={len(report.model_performance)} "
+            f"calib={len(report.calibration)} dir={len(report.directional)} "
+            f"heatmap={len(report.heatmap)}"
+        )
+        log.info("%s", results[-1])
+
+    if args.push and not args.offline:
+        log.info("== pushing to %s ==", args.repo)
+        oid = store.flush(f"Seed store ({args.plan})")
+        log.info("commit: %s", oid)
+        results.append(f"pushed commit {oid}")
+
+    print("\n=== SEED SUMMARY ===")
+    for r in results:
+        print(r)
+    failures = [r for r in results if r.startswith("FAIL")]
+    return 1 if failures else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

src/adapters.py

@@ -0,0 +1,367 @@
+"""Forecast model adapters.
+
+Adding a model means giving a model id and naming an adapter *family*. The
+family list is fixed in `config.ALLOWED_ADAPTER_FAMILIES`; nothing here ever
+imports, downloads or executes code chosen by a user. A user-supplied model id
+is loaded only through an already-vetted family's loader, and `trust_remote_code`
+is never enabled.
+
+Every adapter reports an `inference_version` that pins the adapter's own logic
+alongside the model revision, so a stored slice can always be traced back to
+exactly what produced it.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import os
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+
+from . import config
+
+log = logging.getLogger("bit.adapters")
+
+DEFAULT_QUANTILES = (0.1, 0.5, 0.9)
+
+
+class AdapterError(RuntimeError):
+    pass
+
+
+class ModelNotAllowed(AdapterError):
+    """The requested adapter family is not on the allow-list."""
+
+
+@dataclass
+class Forecast:
+    """One horizon-1 forecast per input window."""
+
+    q10: np.ndarray
+    q50: np.ndarray
+    q90: np.ndarray
+    context_len: int
+
+    def __post_init__(self):
+        if not (len(self.q10) == len(self.q50) == len(self.q90)):
+            raise AdapterError("quantile arrays have mismatched lengths")
+
+    def as_frame(self, ts: pd.DatetimeIndex, inference_version: str) -> pd.DataFrame:
+        if len(ts) != len(self.q50):
+            raise AdapterError(
+                f"timestamp count {len(ts)} != forecast count {len(self.q50)}"
+            )
+        # Quantiles must not cross; sorting is the honest repair for tiny
+        # numerical inversions and makes the store's validator pass.
+        stacked = np.sort(np.vstack([self.q10, self.q50, self.q90]), axis=0)
+        return pd.DataFrame({
+            "ts": ts,
+            "q10": stacked[0], "q50": stacked[1], "q90": stacked[2],
+            "context_len": self.context_len,
+            "inference_version": inference_version,
+        })
+
+
+class ForecastAdapter(ABC):
+    """Uniform interface over quantile forecasters."""
+
+    family: str = "base"
+    adapter_version: str = "1"
+
+    def __init__(self, model_id: str, revision: str | None = None,
+                 context_len: int = 512, device: str | None = None):
+        self.model_id = model_id
+        self.revision = revision
+        self.context_len = context_len
+        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_windows: np.ndarray) -> Forecast:
+        """`context_windows` is (n_windows, context_len). Returns horizon-1 quantiles."""
+
+    def inference_version(self) -> str:
+        """Identity of everything that determines the output values."""
+        rev = self._resolved_revision or self.revision or "unpinned"
+        payload = f"{self.family}|{self.adapter_version}|{self.model_id}|{rev}|{self.context_len}"
+        digest = hashlib.sha256(payload.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"
+
+    # -- shared helpers ---------------------------------------------------
+
+    def resolve_revision(self) -> str:
+        """Pin the model to an immutable commit sha before any inference runs."""
+        if self._resolved_revision:
+            return self._resolved_revision
+        try:
+            from huggingface_hub import HfApi
+
+            info = HfApi().model_info(self.model_id, revision=self.revision)
+            self._resolved_revision = info.sha
+        except Exception as e:
+            log.warning("could not resolve revision for %s: %s", self.model_id, e)
+            self._resolved_revision = self.revision or "unpinned"
+        return self._resolved_revision
+
+
+def _default_device() -> str:
+    try:
+        import torch
+
+        if torch.cuda.is_available():
+            return "cuda"
+        if getattr(torch.backends, "mps", None) and torch.backends.mps.is_available():
+            return "mps"
+    except Exception:
+        pass
+    return "cpu"
+
+
+# --------------------------------------------------------------------------
+# Chronos / Chronos-Bolt
+# --------------------------------------------------------------------------
+
+
+class ChronosAdapter(ForecastAdapter):
+    """amazon/chronos-* and amazon/chronos-bolt-* quantile forecasters."""
+
+    family = "chronos"
+    adapter_version = "1"
+
+    def load(self, model_id: str | None = None, revision: str | None = None):
+        if model_id:
+            self.model_id = model_id
+        if revision:
+            self.revision = revision
+        if self._model is not None:
+            return self
+
+        self.resolve_revision()
+        try:
+            from chronos import BaseChronosPipeline
+        except ImportError as e:
+            raise AdapterError(
+                "chronos-forecasting is not installed; add it to requirements.txt"
+            ) from e
+
+        import torch
+
+        dtype = torch.float32 if self.device in ("cpu", "mps") else torch.bfloat16
+        self._model = BaseChronosPipeline.from_pretrained(
+            self.model_id,
+            revision=self._resolved_revision if self._resolved_revision != "unpinned" else None,
+            device_map=self.device,
+            torch_dtype=dtype,
+        )
+        return self
+
+    def predict(self, context_windows: np.ndarray) -> Forecast:
+        if self._model is None:
+            self.load()
+        import torch
+
+        ctx = np.asarray(context_windows, dtype="float32")
+        if ctx.ndim == 1:
+            ctx = ctx[None, :]
+        tensors = [torch.tensor(row) for row in ctx]
+
+        q_levels = list(DEFAULT_QUANTILES)
+        with torch.inference_mode():
+            quantiles, _mean = self._model.predict_quantiles(
+                tensors, prediction_length=1, quantile_levels=q_levels,
+            )
+        # (n_series, prediction_length, n_quantiles) -> horizon 1
+        arr = quantiles.float().cpu().numpy()[:, 0, :]
+        return Forecast(q10=arr[:, 0], q50=arr[:, 1], q90=arr[:, 2],
+                        context_len=ctx.shape[1])
+
+
+# --------------------------------------------------------------------------
+# TimesFM
+# --------------------------------------------------------------------------
+
+
+class TimesFMAdapter(ForecastAdapter):
+    """google/timesfm-* forecasters.
+
+    TimesFM returns a fixed quantile grid; the 0.1/0.5/0.9 columns are selected
+    from it rather than re-derived, so the stored numbers are the model's own.
+    """
+
+    family = "timesfm"
+    adapter_version = "1"
+    _QUANTILE_GRID = (0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9)
+
+    def load(self, model_id: str | None = None, revision: str | None = None):
+        if model_id:
+            self.model_id = model_id
+        if revision:
+            self.revision = revision
+        if self._model is not None:
+            return self
+
+        self.resolve_revision()
+        try:
+            import timesfm
+        except ImportError as e:
+            raise AdapterError(
+                "timesfm is not installed; add it to requirements.txt to enable "
+                "this adapter family"
+            ) from e
+
+        backend = {"cuda": "gpu", "mps": "cpu"}.get(self.device, "cpu")
+        self._model = timesfm.TimesFm(
+            hparams=timesfm.TimesFmHparams(
+                backend=backend, per_core_batch_size=32,
+                context_len=self.context_len, horizon_len=1,
+            ),
+            checkpoint=timesfm.TimesFmCheckpoint(huggingface_repo_id=self.model_id),
+        )
+        return self
+
+    def predict(self, context_windows: np.ndarray) -> Forecast:
+        if self._model is None:
+            self.load()
+
+        ctx = np.asarray(context_windows, dtype="float32")
+        if ctx.ndim == 1:
+            ctx = ctx[None, :]
+
+        _point, quantile_out = self._model.forecast(
+            [row for row in ctx], freq=[0] * len(ctx)
+        )
+        arr = np.asarray(quantile_out)[:, 0, :]  # horizon 1
+        grid = list(self._QUANTILE_GRID)
+        # Column 0 of TimesFM's output is the mean; quantiles follow.
+        offset = arr.shape[1] - len(grid)
+        i10, i50, i90 = (grid.index(q) + offset for q in DEFAULT_QUANTILES)
+        return Forecast(q10=arr[:, i10], q50=arr[:, i50], q90=arr[:, i90],
+                        context_len=ctx.shape[1])
+
+
+# --------------------------------------------------------------------------
+# Placeholder (no GPU / no model available)
+# --------------------------------------------------------------------------
+
+
+class PlaceholderAdapter(ForecastAdapter):
+    """Structurally identical synthetic output, permanently labelled.
+
+    Exists so the UI has complete shape before every cell has real coverage.
+    Its `inference_version` is the literal string `PLACEHOLDER`, which the store
+    and the UI both key off to mark the data as not-real. It is deterministic:
+    the same window always yields the same numbers.
+    """
+
+    family = "placeholder"
+    adapter_version = "1"
+
+    def load(self, model_id: str | None = None, revision: str | None = None):
+        if model_id:
+            self.model_id = model_id
+        self._resolved_revision = "PLACEHOLDER"
+        return self
+
+    def inference_version(self) -> str:
+        return config.PLACEHOLDER_VERSION
+
+    def predict(self, context_windows: np.ndarray) -> Forecast:
+        ctx = np.asarray(context_windows, dtype="float64")
+        if ctx.ndim == 1:
+            ctx = ctx[None, :]
+
+        last = ctx[:, -1]
+        # Deterministic pseudo-drift seeded by the window itself, plus a band
+        # scaled to that window's realised volatility.
+        seedvals = np.abs(np.sum(ctx[:, -8:], axis=1) * 1e6).astype("int64")
+        drift = np.array([
+            (np.random.default_rng(int(s) % (2**32)).normal(0.0, 1.0)) for s in seedvals
+        ])
+        vol = np.std(np.diff(ctx, axis=1), axis=1) / np.maximum(np.abs(last), 1e-9)
+        vol = np.clip(vol, 1e-4, 0.2)
+
+        q50 = last * (1.0 + 0.25 * drift * vol)
+        band = last * vol * 1.28
+        return Forecast(q10=q50 - band, q50=q50, q90=q50 + band,
+                        context_len=ctx.shape[1])
+
+
+# --------------------------------------------------------------------------
+# Factory
+# --------------------------------------------------------------------------
+
+_FAMILIES: dict[str, type[ForecastAdapter]] = {
+    "chronos": ChronosAdapter,
+    "timesfm": TimesFMAdapter,
+    "placeholder": PlaceholderAdapter,
+}
+
+
+def get_adapter(family: str, model_id: str, revision: str | None = None,
+                context_len: int = 512, device: str | None = None) -> ForecastAdapter:
+    """Build an adapter. Only allow-listed families are constructible."""
+    fam = (family or "").strip().lower()
+    if fam == "placeholder":
+        return PlaceholderAdapter(model_id, revision, context_len, device)
+    if fam not in config.ALLOWED_ADAPTER_FAMILIES:
+        raise ModelNotAllowed(
+            f"adapter family {family!r} is not allowed; pick one of "
+            f"{list(config.ALLOWED_ADAPTER_FAMILIES)}"
+        )
+    return _FAMILIES[fam](model_id, revision, context_len, device)
+
+
+def validate_model_id(model_id: str) -> str:
+    """Reject anything that is not a plain `owner/name` Hub id."""
+    mid = (model_id or "").strip()
+    if not mid or mid.count("/") != 1:
+        raise AdapterError(f"{model_id!r} is not a valid Hub model id (owner/name)")
+    owner, name = mid.split("/")
+    ok = set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_.")
+    if not owner or not name or set(mid) - ok - {"/"}:
+        raise AdapterError(f"{model_id!r} contains characters that are not allowed")
+    if ".." in mid:
+        raise AdapterError("model id may not contain '..'")
+    return mid
+
+
+# --------------------------------------------------------------------------
+# Rolling-window construction (shared by the seed script and the GPU path)
+# --------------------------------------------------------------------------
+
+
+def build_windows(series: pd.Series, context_len: int, stride: int = 1):
+    """Yield (timestamp, trailing window) pairs.
+
+    The window for timestamp `t` ends at `t` inclusive, so the forecast stored
+    at `t` used only data available at `t`. The engine then shifts it before any
+    trade can act on it.
+    """
+    values = series.to_numpy(dtype="float64")
+    index = series.index
+    n = len(values)
+    if n <= context_len:
+        return [], np.empty((0, context_len))
+
+    stamps, rows = [], []
+    for i in range(context_len, n, stride):
+        stamps.append(index[i])
+        rows.append(values[i - context_len + 1: i + 1])
+    if not rows:
+        return [], np.empty((0, context_len))
+    return pd.DatetimeIndex(stamps), np.vstack(rows)

src/charts.py

@@ -0,0 +1,615 @@
+"""Plotly figures in the Bit design language.
+
+Colors come from `PALETTE`, which mirrors the design system tokens. Plotly
+cannot read CSS variables, so the token values are resolved here once; if the
+design system changes, this table is the single place to update.
+
+Every figure returns a `go.Figure` with the app's dark canvas, square corners,
+tight type, and direction encoded by shape as well as color (the design marks
+up/down with ▲/▼ so colorblind users are not reading hue alone).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+import plotly.graph_objects as go
+
+from .metrics import drawdown_series, rolling_sharpe
+
+# --------------------------------------------------------------------------
+# Palette (mirrors _ds/tokens/colors.css)
+# --------------------------------------------------------------------------
+
+PALETTE = {
+    "canvas": "#161512",
+    "panel": "#1d1c18",
+    "raised": "#24221d",
+    "sunken": "#000000",
+    "border_subtle": "#2c2a24",
+    "border": "#3d3a32",
+    "border_strong": "#6f6a56",
+    "text": "#f7f4ec",
+    "text_secondary": "#b6b09a",
+    "text_tertiary": "#6f6a56",
+    "amber": "#af9209",
+    "amber_strong": "#cfab0a",
+    "amber_dim": "#7d6a09",
+    "moss": "#68781e",
+    "moss_strong": "#7d901f",
+    "moss_dim": "#4d5817",
+    "up": "#19b35a",
+    "up_strong": "#22c765",
+    "down": "#e0483c",
+    "down_strong": "#ee6152",
+    "up_cvd": "#3f7fd0",
+    "down_cvd": "#c07a2a",
+    "mute_red": "#8a5a54",
+    "mute_teal": "#54898a",
+    "mute_blue": "#59656e",
+    "mute_indigo": "#5c5c8a",
+    "mute_violet": "#75588a",
+    "mute_green": "#6e8a54",
+    "mute_yellow": "#8a8154",
+}
+
+SERIES_COLORS = [
+    PALETTE["amber_strong"], PALETTE["mute_teal"], PALETTE["mute_violet"],
+    PALETTE["moss_strong"], PALETTE["mute_indigo"], PALETTE["mute_red"],
+]
+
+FONT = "ui-monospace, 'JetBrains Mono', SFMono-Regular, Menlo, monospace"
+HEAD_FONT = "'Styrene A', -apple-system, system-ui, sans-serif"
+
+
+def up_color(cvd: bool = False) -> str:
+    return PALETTE["up_cvd"] if cvd else PALETTE["up"]
+
+
+def down_color(cvd: bool = False) -> str:
+    return PALETTE["down_cvd"] if cvd else PALETTE["down"]
+
+
+def _base_layout(fig: go.Figure, height: int = 320, *, showlegend: bool = False,
+                 margin: tuple[int, int, int, int] = (8, 8, 8, 8)) -> go.Figure:
+    l, r, t, b = margin
+    fig.update_layout(
+        template="plotly_dark",
+        paper_bgcolor=PALETTE["panel"],
+        plot_bgcolor=PALETTE["panel"],
+        font=dict(family=FONT, size=10, color=PALETTE["text_secondary"]),
+        height=height,
+        margin=dict(l=l, r=r, t=t, b=b),
+        showlegend=showlegend,
+        legend=dict(bgcolor="rgba(0,0,0,0)", borderwidth=0,
+                    font=dict(size=9, color=PALETTE["text_secondary"]),
+                    orientation="h", yanchor="bottom", y=1.0, x=0),
+        hoverlabel=dict(bgcolor=PALETTE["raised"], bordercolor=PALETTE["border"],
+                        font=dict(family=FONT, size=10, color=PALETTE["text"])),
+        xaxis=dict(gridcolor=PALETTE["border_subtle"], zerolinecolor=PALETTE["border"],
+                   linecolor=PALETTE["border"], tickfont=dict(size=9)),
+        yaxis=dict(gridcolor=PALETTE["border_subtle"], zerolinecolor=PALETTE["border"],
+                   linecolor=PALETTE["border"], tickfont=dict(size=9)),
+        dragmode="pan",
+    )
+    return fig
+
+
+def empty_figure(message: str = "No data", height: int = 320) -> go.Figure:
+    fig = go.Figure()
+    fig.add_annotation(text=message.upper(), showarrow=False,
+                       font=dict(family=FONT, size=11, color=PALETTE["text_tertiary"]),
+                       x=0.5, y=0.5, xref="paper", yref="paper")
+    fig.update_xaxes(visible=False)
+    fig.update_yaxes(visible=False)
+    return _base_layout(fig, height)
+
+
+# --------------------------------------------------------------------------
+# Equity curve
+# --------------------------------------------------------------------------
+
+
+def equity_curve(
+    equity: pd.Series,
+    benchmark: pd.Series | None = None,
+    *,
+    plan=None,
+    log_scale: bool = False,
+    height: int = 340,
+    drawdown_shading: bool = True,
+    cvd: bool = False,
+) -> go.Figure:
+    """Strategy vs buy & hold, with drawdown shading and validation bands."""
+    if equity is None or equity.empty:
+        return empty_figure("no equity curve", height)
+
+    fig = go.Figure()
+    base = float(equity.iloc[0])
+    pct = (equity / base - 1.0) * 100.0
+
+    if drawdown_shading:
+        dd = drawdown_series(equity)
+        # Shade the stretches spent more than 5% below the running peak.
+        in_dd = dd < -0.05
+        for lo, hi in _true_runs(in_dd):
+            fig.add_vrect(x0=equity.index[lo], x1=equity.index[hi],
+                          fillcolor=PALETTE["down"], opacity=0.10,
+                          line_width=0, layer="below")
+
+    if plan is not None:
+        for w in getattr(plan, "windows", []):
+            fig.add_vrect(x0=w.test_start, x1=w.test_end,
+                          fillcolor=PALETTE["moss"], opacity=0.07,
+                          line_width=0, layer="below")
+        hs = getattr(plan, "holdout_start", None)
+        if hs is not None:
+            fig.add_vrect(
+                x0=hs, x1=equity.index[-1], fillcolor=PALETTE["amber"], opacity=0.10,
+                line_width=1, line_color=PALETTE["amber_dim"], layer="below",
+                annotation_text="HOLDOUT", annotation_position="top left",
+                annotation_font=dict(family=FONT, size=9, color=PALETTE["amber_strong"]),
+            )
+
+    if benchmark is not None and not benchmark.empty:
+        bpct = (benchmark / float(benchmark.iloc[0]) - 1.0) * 100.0
+        fig.add_trace(go.Scatter(
+            x=bpct.index, y=bpct.to_numpy(), name="BUY & HOLD",
+            line=dict(color=PALETTE["text_tertiary"], width=1.2, dash="dash"),
+            hovertemplate="buy & hold %{y:.1f}%<extra></extra>",
+        ))
+
+    fig.add_trace(go.Scatter(
+        x=pct.index, y=pct.to_numpy(), name="STRATEGY",
+        line=dict(color=PALETTE["amber_strong"], width=1.8),
+        hovertemplate="strategy %{y:.1f}%<extra></extra>",
+    ))
+
+    fig.update_yaxes(ticksuffix="%", title=None)
+    if log_scale:
+        # Log scale needs a positive series, so plot the equity multiple.
+        fig.data = ()
+        mult = equity / base
+        if benchmark is not None and not benchmark.empty:
+            fig.add_trace(go.Scatter(
+                x=benchmark.index, y=(benchmark / float(benchmark.iloc[0])).to_numpy(),
+                name="BUY & HOLD",
+                line=dict(color=PALETTE["text_tertiary"], width=1.2, dash="dash")))
+        fig.add_trace(go.Scatter(x=mult.index, y=mult.to_numpy(), name="STRATEGY",
+                                 line=dict(color=PALETTE["amber_strong"], width=1.8)))
+        fig.update_yaxes(type="log", ticksuffix="x")
+
+    return _base_layout(fig, height, showlegend=True, margin=(8, 8, 24, 8))
+
+
+def _true_runs(mask: pd.Series) -> list[tuple[int, int]]:
+    """Contiguous [start, end] index positions where `mask` is True."""
+    arr = mask.to_numpy()
+    runs, start = [], None
+    for i, v in enumerate(arr):
+        if v and start is None:
+            start = i
+        elif not v and start is not None:
+            runs.append((start, i - 1))
+            start = None
+    if start is not None:
+        runs.append((start, len(arr) - 1))
+    return runs
+
+
+# --------------------------------------------------------------------------
+# Underwater / rolling Sharpe
+# --------------------------------------------------------------------------
+
+
+def underwater_chart(equity: pd.Series, height: int = 150) -> go.Figure:
+    if equity is None or equity.empty:
+        return empty_figure("no drawdown data", height)
+    dd = drawdown_series(equity) * 100.0
+    fig = go.Figure(go.Scatter(
+        x=dd.index, y=dd.to_numpy(), fill="tozeroy", mode="lines",
+        line=dict(color=PALETTE["down"], width=1.0),
+        fillcolor="rgba(224,72,60,0.35)",
+        hovertemplate="%{y:.1f}%<extra></extra>",
+    ))
+    fig.update_yaxes(ticksuffix="%")
+    return _base_layout(fig, height)
+
+
+def rolling_sharpe_chart(equity: pd.Series, window: int, bars_per_year: float,
+                         height: int = 150) -> go.Figure:
+    if equity is None or equity.empty:
+        return empty_figure("no rolling sharpe", height)
+    rs = rolling_sharpe(equity, window, bars_per_year)
+    if rs.empty:
+        return empty_figure(f"needs > {window} bars", height)
+    fig = go.Figure(go.Scatter(
+        x=rs.index, y=rs.to_numpy(), mode="lines",
+        line=dict(color=PALETTE["mute_teal"], width=1.2),
+        hovertemplate="sharpe %{y:.2f}<extra></extra>",
+    ))
+    fig.add_hline(y=0, line=dict(color=PALETTE["border"], width=1))
+    fig.add_hline(y=1, line=dict(color=PALETTE["moss_dim"], width=1, dash="dot"))
+    return _base_layout(fig, height)
+
+
+# --------------------------------------------------------------------------
+# Price + trade flags
+# --------------------------------------------------------------------------
+
+
+def price_with_trades(
+    prices: pd.DataFrame, trades: pd.DataFrame, *, height: int = 420,
+    max_bars: int = 600, cvd: bool = False,
+) -> go.Figure:
+    """Candlesticks with volume, entry/exit flags and win/loss connectors."""
+    if prices is None or prices.empty:
+        return empty_figure("no price data", height)
+
+    px = prices.tail(max_bars)
+    up, down = up_color(cvd), down_color(cvd)
+
+    fig = go.Figure()
+    fig.add_trace(go.Candlestick(
+        x=px.index, open=px["open"], high=px["high"], low=px["low"], close=px["close"],
+        increasing=dict(line=dict(color=up, width=1), fillcolor=up),
+        decreasing=dict(line=dict(color=down, width=1), fillcolor=down),
+        name="price", yaxis="y", showlegend=False,
+    ))
+
+    if "volume" in px.columns:
+        vmax = float(px["volume"].max()) or 1.0
+        pmin = float(px["low"].min())
+        prange = float(px["high"].max()) - pmin or 1.0
+        scaled = pmin + (px["volume"] / vmax) * prange * 0.16
+        fig.add_trace(go.Bar(
+            x=px.index, y=scaled - pmin, base=pmin, marker_color=PALETTE["border"],
+            opacity=0.5, name="volume", showlegend=False, hoverinfo="skip",
+        ))
+
+    if trades is not None and not trades.empty:
+        window = trades[(trades["entry_ts"] >= px.index[0])
+                        & (trades["entry_ts"] <= px.index[-1])]
+        for t in window.itertuples():
+            won = t.net_pnl > 0
+            color = up if won else down
+            hollow = str(t.side).lower() == "short"
+            fig.add_trace(go.Scatter(
+                x=[t.entry_ts, t.exit_ts], y=[t.entry_px, t.exit_px],
+                mode="lines", line=dict(color=color, width=1, dash="dot"),
+                showlegend=False, hoverinfo="skip",
+            ))
+            card = (
+                f"#{t.id} {str(t.side).upper()}<br>"
+                f"net {t.net_pnl:+,.2f}  ({t.r_multiple:+.2f}R)<br>"
+                f"costs {t.costs:,.2f}<br>"
+                f"MAE {t.mae:.2%} · MFE {t.mfe:.2%}<br>"
+                f"<i>{t.trigger}</i>"
+            )
+            fig.add_trace(go.Scatter(
+                x=[t.entry_ts], y=[t.entry_px], mode="markers", showlegend=False,
+                marker=dict(symbol="triangle-up", size=10, color="rgba(0,0,0,0)" if hollow else color,
+                            line=dict(color=color, width=1.5)),
+                hovertemplate=card + "<extra></extra>",
+            ))
+            fig.add_trace(go.Scatter(
+                x=[t.exit_ts], y=[t.exit_px], mode="markers", showlegend=False,
+                marker=dict(symbol="triangle-down", size=10, color="rgba(0,0,0,0)" if hollow else color,
+                            line=dict(color=color, width=1.5)),
+                hovertemplate=card + "<extra></extra>",
+            ))
+
+    fig.update_layout(xaxis_rangeslider_visible=False, barmode="overlay")
+    return _base_layout(fig, height)
+
+
+# --------------------------------------------------------------------------
+# Distributions
+# --------------------------------------------------------------------------
+
+
+def pnl_histogram(trades: pd.DataFrame, height: int = 200, cvd: bool = False) -> go.Figure:
+    if trades is None or trades.empty:
+        return empty_figure("no trades", height)
+    net = trades["net_pnl"].astype(float)
+    colors = [up_color(cvd) if v > 0 else down_color(cvd) for v in net]
+    fig = go.Figure(go.Histogram(
+        x=net, nbinsx=min(40, max(8, len(net) // 3)),
+        marker=dict(color=PALETTE["mute_blue"], line=dict(color=PALETTE["border"], width=1)),
+        hovertemplate="%{y} trades in %{x}<extra></extra>",
+    ))
+    fig.add_vline(x=0, line=dict(color=PALETTE["text_tertiary"], width=1))
+    return _base_layout(fig, height)
+
+
+def holding_period_histogram(trades: pd.DataFrame, height: int = 200) -> go.Figure:
+    if trades is None or trades.empty or "duration_bars" in trades.columns is None:
+        return empty_figure("no trades", height)
+    dur = trades["duration_bars"].dropna().astype(float)
+    if dur.empty:
+        return empty_figure("no durations", height)
+    fig = go.Figure(go.Histogram(
+        x=dur, nbinsx=min(30, max(6, len(dur) // 3)),
+        marker=dict(color=PALETTE["mute_indigo"], line=dict(color=PALETTE["border"], width=1)),
+        hovertemplate="%{y} trades held %{x} bars<extra></extra>",
+    ))
+    return _base_layout(fig, height)
+
+
+def mae_mfe_scatter(trades: pd.DataFrame, height: int = 200, cvd: bool = False) -> go.Figure:
+    if trades is None or trades.empty:
+        return empty_figure("no trades", height)
+    t = trades.dropna(subset=["mae", "mfe"])
+    if t.empty:
+        return empty_figure("no excursion data", height)
+    won = t["net_pnl"] > 0
+    fig = go.Figure()
+    for label, mask, color, sym in (
+        ("wins", won, up_color(cvd), "triangle-up"),
+        ("losses", ~won, down_color(cvd), "triangle-down"),
+    ):
+        sub = t[mask]
+        if sub.empty:
+            continue
+        fig.add_trace(go.Scatter(
+            x=(sub["mae"] * 100).to_numpy(), y=(sub["mfe"] * 100).to_numpy(),
+            mode="markers", name=label.upper(),
+            marker=dict(color=color, size=6, symbol=sym, opacity=0.75),
+            customdata=sub[["id", "net_pnl"]].to_numpy(),
+            hovertemplate="#%{customdata[0]} net %{customdata[1]:+,.0f}<br>"
+                          "MAE %{x:.1f}% · MFE %{y:.1f}%<extra></extra>",
+        ))
+    fig.update_xaxes(title=dict(text="MAE %", font=dict(size=9)), ticksuffix="%")
+    fig.update_yaxes(title=dict(text="MFE %", font=dict(size=9)), ticksuffix="%")
+    return _base_layout(fig, height, showlegend=True, margin=(8, 8, 22, 28))
+
+
+# --------------------------------------------------------------------------
+# Comparison
+# --------------------------------------------------------------------------
+
+
+def strategy_timeframe_heatmap(df: pd.DataFrame, *, height: int = 320,
+                               value_col: str = "oos_sharpe") -> go.Figure:
+    """Strategy x timeframe OOS-Sharpe matrix. Scale fixed at -0.5 -> 2.0."""
+    if df is None or df.empty:
+        return empty_figure("no comparison coverage", height)
+    pivot = df.pivot_table(index="strategy", columns="timeframe",
+                           values=value_col, aggfunc="mean")
+    order = [tf for tf in ("15m", "1h", "1d") if tf in pivot.columns]
+    pivot = pivot.reindex(columns=order or list(pivot.columns))
+
+    fig = go.Figure(go.Heatmap(
+        z=pivot.to_numpy(), x=list(pivot.columns), y=list(pivot.index),
+        zmin=-0.5, zmax=2.0,
+        colorscale=[[0.0, PALETTE["down"]], [0.2, PALETTE["panel"]],
+                    [0.5, PALETTE["moss_dim"]], [1.0, PALETTE["amber_strong"]]],
+        hovertemplate="%{y} · %{x}<br>OOS Sharpe %{z:.2f}<extra></extra>",
+        colorbar=dict(thickness=8, len=0.8, tickfont=dict(size=9),
+                      outlinewidth=0, title=dict(text="SHARPE", font=dict(size=9))),
+        xgap=2, ygap=2,
+    ))
+    return _base_layout(fig, height, margin=(8, 8, 8, 8))
+
+
+def overlaid_returns(curves: dict[str, pd.Series], *, height: int = 300,
+                     oos_start=None) -> go.Figure:
+    """Cumulative return of several runs on one shared scale."""
+    if not curves:
+        return empty_figure("select runs to compare", height)
+    fig = go.Figure()
+    for i, (name, eq) in enumerate(curves.items()):
+        if eq is None or eq.empty:
+            continue
+        pct = (eq / float(eq.iloc[0]) - 1.0) * 100.0
+        fig.add_trace(go.Scatter(
+            x=pct.index, y=pct.to_numpy(), name=name[:34],
+            line=dict(color=SERIES_COLORS[i % len(SERIES_COLORS)], width=1.4),
+            hovertemplate=f"{name}: %{{y:.1f}}%<extra></extra>",
+        ))
+    if oos_start is not None:
+        fig.add_vrect(x0=oos_start, x1=max(s.index[-1] for s in curves.values() if len(s)),
+                      fillcolor=PALETTE["moss"], opacity=0.07, line_width=0, layer="below")
+    fig.update_yaxes(ticksuffix="%")
+    return _base_layout(fig, height, showlegend=True, margin=(8, 8, 26, 8))
+
+
+def small_multiples(curves: dict[str, pd.Series], *, height: int = 260) -> go.Figure:
+    """Grid of equity curves, one per selected run, on a shared y-scale."""
+    from plotly.subplots import make_subplots
+
+    if not curves:
+        return empty_figure("select runs to compare", height)
+    n = len(curves)
+    cols = min(3, n)
+    rows = (n + cols - 1) // cols
+    fig = make_subplots(rows=rows, cols=cols, subplot_titles=[k[:26] for k in curves],
+                        vertical_spacing=0.18, horizontal_spacing=0.06)
+    for i, (name, eq) in enumerate(curves.items()):
+        r, c = divmod(i, cols)
+        pct = (eq / float(eq.iloc[0]) - 1.0) * 100.0 if len(eq) else eq
+        fig.add_trace(go.Scatter(
+            x=pct.index, y=pct.to_numpy(), showlegend=False,
+            line=dict(color=SERIES_COLORS[i % len(SERIES_COLORS)], width=1.2),
+        ), row=r + 1, col=c + 1)
+    fig.update_annotations(font=dict(family=FONT, size=9, color=PALETTE["text_secondary"]))
+    return _base_layout(fig, max(height, 130 * rows), margin=(8, 8, 22, 8))
+
+
+def correlation_matrix(returns: dict[str, pd.Series], height: int = 280) -> go.Figure:
+    """Return correlation between selected runs -- 'are these the same bet?'"""
+    if len(returns) < 2:
+        return empty_figure("select at least two runs", height)
+    df = pd.DataFrame({k: v for k, v in returns.items()}).dropna()
+    if df.empty or df.shape[1] < 2:
+        return empty_figure("no overlapping period", height)
+    corr = df.corr()
+    fig = go.Figure(go.Heatmap(
+        z=corr.to_numpy(), x=[c[:18] for c in corr.columns], y=[c[:18] for c in corr.index],
+        zmin=-1, zmax=1,
+        colorscale=[[0.0, PALETTE["mute_blue"]], [0.5, PALETTE["panel"]],
+                    [1.0, PALETTE["amber_strong"]]],
+        hovertemplate="%{y} vs %{x}<br>r = %{z:.2f}<extra></extra>",
+        colorbar=dict(thickness=8, len=0.8, tickfont=dict(size=9), outlinewidth=0),
+        xgap=2, ygap=2,
+    ))
+    return _base_layout(fig, height)
+
+
+def regime_bars(by_regime: pd.DataFrame, height: int = 260, cvd: bool = False) -> go.Figure:
+    """Return grouped by market regime (bull / bear / chop)."""
+    if by_regime is None or by_regime.empty:
+        return empty_figure("no regime breakdown", height)
+    fig = go.Figure()
+    for i, col in enumerate([c for c in by_regime.columns if c != "regime"]):
+        fig.add_trace(go.Bar(
+            x=by_regime["regime"], y=by_regime[col] * 100.0, name=col[:24],
+            marker_color=SERIES_COLORS[i % len(SERIES_COLORS)],
+            hovertemplate="%{x}: %{y:.1f}%<extra></extra>",
+        ))
+    fig.add_hline(y=0, line=dict(color=PALETTE["border"], width=1))
+    fig.update_yaxes(ticksuffix="%")
+    return _base_layout(fig, height, showlegend=True, margin=(8, 8, 26, 8))
+
+
+# --------------------------------------------------------------------------
+# Robustness
+# --------------------------------------------------------------------------
+
+
+def parameter_sensitivity(grid: pd.DataFrame, *, x: str, y: str, z: str = "oos_sharpe",
+                          chosen: tuple | None = None, height: int = 300) -> go.Figure:
+    """Heatmap of OOS Sharpe across a two-parameter sweep."""
+    if grid is None or grid.empty:
+        return empty_figure("run a sweep to see sensitivity", height)
+    pivot = grid.pivot_table(index=y, columns=x, values=z, aggfunc="mean")
+    fig = go.Figure(go.Heatmap(
+        z=pivot.to_numpy(), x=list(pivot.columns), y=list(pivot.index),
+        colorscale=[[0.0, PALETTE["down"]], [0.35, PALETTE["panel"]],
+                    [0.7, PALETTE["moss_dim"]], [1.0, PALETTE["amber_strong"]]],
+        hovertemplate=f"{x} %{{x}} · {y} %{{y}}<br>Sharpe %{{z:.2f}}<extra></extra>",
+        colorbar=dict(thickness=8, len=0.8, tickfont=dict(size=9), outlinewidth=0),
+        xgap=1, ygap=1,
+    ))
+    if chosen is not None:
+        fig.add_shape(type="rect",
+                      x0=chosen[0] - 0.5, x1=chosen[0] + 0.5,
+                      y0=chosen[1] - 0.5, y1=chosen[1] + 0.5,
+                      line=dict(color=PALETTE["text"], width=2))
+    fig.update_xaxes(title=dict(text=x.upper(), font=dict(size=9)))
+    fig.update_yaxes(title=dict(text=y.upper(), font=dict(size=9)))
+    return _base_layout(fig, height, margin=(8, 8, 8, 28))
+
+
+def monte_carlo_cone(paths: np.ndarray, index=None, *, height: int = 300) -> go.Figure:
+    """P5 / P50 / P95 cone over reshuffled trade sequences."""
+    if paths is None or len(paths) == 0:
+        return empty_figure("needs trades to reshuffle", height)
+    p5 = np.percentile(paths, 5, axis=0) * 100.0
+    p50 = np.percentile(paths, 50, axis=0) * 100.0
+    p95 = np.percentile(paths, 95, axis=0) * 100.0
+    x = list(index) if index is not None else list(range(len(p50)))
+
+    fig = go.Figure()
+    fig.add_trace(go.Scatter(x=x + x[::-1], y=list(p95) + list(p5)[::-1],
+                             fill="toself", fillcolor="rgba(175,146,9,0.14)",
+                             line=dict(width=0), hoverinfo="skip", showlegend=False))
+    fig.add_trace(go.Scatter(x=x, y=p50, line=dict(color=PALETTE["amber_strong"], width=1.6),
+                             name="P50", hovertemplate="P50 %{y:.1f}%<extra></extra>"))
+    fig.add_hline(y=0, line=dict(color=PALETTE["border"], width=1))
+    fig.update_yaxes(ticksuffix="%")
+    return _base_layout(fig, height)
+
+
+def walk_forward_bars(windows, height: int = 240, cvd: bool = False) -> go.Figure:
+    """Per-window OOS return -- the consistency check."""
+    if not windows:
+        return empty_figure("no walk-forward windows", height)
+    labels = [f"W{w.window.idx + 1}" for w in windows]
+    vals = [w.metrics.total_return * 100.0 for w in windows]
+    colors = [up_color(cvd) if v > 0 else down_color(cvd) for v in vals]
+    fig = go.Figure(go.Bar(
+        x=labels, y=vals, marker_color=colors,
+        hovertemplate="%{x}: %{y:+.1f}% OOS<extra></extra>",
+    ))
+    fig.add_hline(y=0, line=dict(color=PALETTE["border"], width=1))
+    fig.update_yaxes(ticksuffix="%")
+    return _base_layout(fig, height)
+
+
+def slippage_stress(points: list[tuple[float, float]], height: int = 240) -> go.Figure:
+    """Sharpe as modelled slippage rises -- where does the edge die?"""
+    if not points:
+        return empty_figure("no stress run", height)
+    xs = [p[0] for p in points]
+    ys = [p[1] for p in points]
+    fig = go.Figure(go.Scatter(
+        x=xs, y=ys, mode="lines+markers",
+        line=dict(color=PALETTE["amber_strong"], width=1.6),
+        marker=dict(size=7, color=PALETTE["amber_strong"]),
+        hovertemplate="%{x} bps → Sharpe %{y:.2f}<extra></extra>",
+    ))
+    fig.add_hline(y=0, line=dict(color=PALETTE["down"], width=1, dash="dot"))
+    fig.update_xaxes(title=dict(text="SLIPPAGE (BPS)", font=dict(size=9)))
+    return _base_layout(fig, height, margin=(8, 8, 8, 28))
+
+
+def regime_strip(prices: pd.DataFrame, height: int = 42) -> go.Figure:
+    """Thin bull/bear/chop band shown under the equity curve."""
+    if prices is None or prices.empty:
+        return empty_figure("", height)
+    reg = classify_regime(prices)
+    color_of = {"bull": PALETTE["moss_strong"], "bear": PALETTE["down"],
+                "chop": PALETTE["mute_yellow"]}
+    fig = go.Figure()
+    for lo, hi, label in _segments(reg):
+        fig.add_vrect(x0=reg.index[lo], x1=reg.index[hi],
+                      fillcolor=color_of.get(label, PALETTE["border"]),
+                      opacity=0.8, line_width=0)
+    fig.update_xaxes(visible=False)
+    fig.update_yaxes(visible=False, range=[0, 1])
+    fig.update_layout(margin=dict(l=0, r=0, t=0, b=0))
+    return _base_layout(fig, height, margin=(0, 0, 0, 0))
+
+
+def classify_regime(prices: pd.DataFrame, window: int = 60) -> pd.Series:
+    """Bull / bear / chop from trailing trend and volatility. Causal."""
+    close = prices["close"]
+    trend = close.pct_change(window)
+    vol = close.pct_change().rolling(window).std()
+    med_vol = vol.rolling(window * 3, min_periods=window).median()
+    out = pd.Series("chop", index=close.index, dtype="object")
+    out[(trend > 0.05) & (vol <= med_vol * 1.5)] = "bull"
+    out[trend < -0.05] = "bear"
+    return out.fillna("chop")
+
+
+def _segments(series: pd.Series) -> list[tuple[int, int, str]]:
+    vals = series.to_numpy()
+    out, start = [], 0
+    for i in range(1, len(vals)):
+        if vals[i] != vals[start]:
+            out.append((start, i - 1, vals[start]))
+            start = i
+    if len(vals):
+        out.append((start, len(vals) - 1, vals[start]))
+    return out
+
+
+def monte_carlo_paths(trades: pd.DataFrame, n_paths: int = 1000, seed: int = 0) -> np.ndarray:
+    """Reshuffle the realised trade sequence `n_paths` times.
+
+    Seeded, so the cone the UI shows is reproducible run to run.
+    """
+    if trades is None or trades.empty:
+        return np.empty((0, 0))
+    rets = (trades["net_pnl"] / trades["entry_px"].abs().clip(lower=1e-9)
+            / trades["size"].abs().clip(lower=1e-9)).to_numpy()
+    rets = rets[np.isfinite(rets)]
+    if len(rets) == 0:
+        return np.empty((0, 0))
+    rng = np.random.default_rng(seed)
+    out = np.empty((n_paths, len(rets)))
+    for i in range(n_paths):
+        out[i] = np.cumprod(1.0 + rng.permutation(rets)) - 1.0
+    return out

src/comparisons.py

@@ -0,0 +1,324 @@
+"""Derived comparison tables written into the store's `comparisons/` folder.
+
+These are precomputed so the UI can render the Comparison tab instantly instead
+of running inference or a sweep of backtests per page load. They are
+regenerated after any coverage extension, so they never describe a stale store.
+
+Four artefacts:
+
+* `model_performance.parquet` — per (model, asset, timeframe): OOS Sharpe,
+  return and drawdown under the *default* Forecast Follower rule.
+* `calibration.parquet` — empirical coverage of the q10-q90 band, plus pinball
+  losses. Answers "when this model says it is 80% sure, is it?".
+* `directional_accuracy.parquet` — the model against three naive baselines.
+* `strategy_timeframe_heatmap.parquet` — the strategy x timeframe OOS-Sharpe
+  matrix behind the Comparison tab's time-scale grid.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+
+from . import config, strategies
+from .engine import BacktestConfig, Costs, Validation, run_backtest
+from .metrics import (
+    calibration_coverage,
+    calibration_error,
+    directional_accuracy,
+    pinball_loss,
+)
+from .store import SignalStore
+
+log = logging.getLogger("bit.comparisons")
+
+MODEL_PERF = "comparisons/model_performance.parquet"
+CALIBRATION = "comparisons/calibration.parquet"
+DIRECTIONAL = "comparisons/directional_accuracy.parquet"
+HEATMAP = "comparisons/strategy_timeframe_heatmap.parquet"
+INDEX_JSON = "comparisons/index.json"
+
+# Strategies shown in the time-scale matrix.
+HEATMAP_STRATEGIES = (
+    "Buy & Hold (benchmark)",
+    "SMA Crossover",
+    "RSI Mean Reversion",
+    "Bollinger Breakout",
+    "MACD Momentum",
+    "Sentiment-Gated Momentum",
+    "Chronos Forecast Follower",
+)
+
+
+def _default_config(asset: str, timeframe: str, strategy: str) -> BacktestConfig:
+    """The single canonical config every comparison number is computed under.
+
+    Costs on, walk-forward validation, six-month locked holdout. Changing this
+    changes every published comparison, so it lives in one place.
+    """
+    return BacktestConfig(
+        asset=asset, timeframe=timeframe, strategy=strategy,
+        params=strategies.defaults_for(strategy),
+        costs=Costs(enabled=True),
+        validation=Validation(mode="walk_forward", train_months=12,
+                              test_months=3, roll_months=3, holdout_months=6),
+    )
+
+
+@dataclass
+class ComparisonReport:
+    model_performance: pd.DataFrame
+    calibration: pd.DataFrame
+    directional: pd.DataFrame
+    heatmap: pd.DataFrame
+
+    def is_empty(self) -> bool:
+        return all(df.empty for df in
+                   (self.model_performance, self.calibration, self.directional, self.heatmap))
+
+
+# --------------------------------------------------------------------------
+# Calibration & directional accuracy
+# --------------------------------------------------------------------------
+
+
+def calibration_row(prices: pd.DataFrame, signals: pd.DataFrame,
+                    model_slug: str, asset: str, timeframe: str) -> dict | None:
+    """Compare each forecast against the outcome it was predicting.
+
+    The forecast stored at `t` is a one-step-ahead prediction, so it is scored
+    against the close at `t+1`, never against the close at `t`.
+    """
+    if signals.empty or prices.empty:
+        return None
+    close = prices["close"]
+    aligned = signals.reindex(close.index).dropna(subset=["q50"])
+    if aligned.empty:
+        return None
+
+    actual_next = close.shift(-1).reindex(aligned.index)
+    valid = actual_next.notna()
+    if valid.sum() < 20:
+        return None
+
+    actual_next = actual_next[valid]
+    q10 = aligned.loc[valid.index[valid], "q10"]
+    q50 = aligned.loc[valid.index[valid], "q50"]
+    q90 = aligned.loc[valid.index[valid], "q90"]
+
+    coverage = calibration_coverage(actual_next, q10, q90)
+    return {
+        "model_slug": model_slug, "asset": asset, "timeframe": timeframe,
+        "n": int(valid.sum()),
+        "coverage_q10_q90": coverage,
+        "nominal_coverage": 0.80,
+        "calibration_error": calibration_error(coverage, 0.80),
+        "pinball_q10": pinball_loss(actual_next, q10, 0.10),
+        "pinball_q50": pinball_loss(actual_next, q50, 0.50),
+        "pinball_q90": pinball_loss(actual_next, q90, 0.90),
+        "is_placeholder": bool(
+            (aligned["inference_version"] == config.PLACEHOLDER_VERSION).any()
+            if "inference_version" in aligned.columns else False
+        ),
+    }
+
+
+def directional_row(prices: pd.DataFrame, signals: pd.DataFrame,
+                    model_slug: str, asset: str, timeframe: str,
+                    seed: int = 0) -> dict | None:
+    """Model directional hit-rate against three naive baselines.
+
+    Baselines: coin-flip (seeded, so the table is reproducible), momentum
+    (continue the last move), and yesterday's-move repeated. All are computed
+    causally from data available at the decision bar.
+    """
+    if signals.empty or prices.empty:
+        return None
+    close = prices["close"]
+    aligned = signals.reindex(close.index).dropna(subset=["q50"])
+    if aligned.empty:
+        return None
+
+    ref = close.reindex(aligned.index)
+    actual_next = close.shift(-1).reindex(aligned.index)
+    mask = actual_next.notna() & ref.notna()
+    if mask.sum() < 20:
+        return None
+
+    ref, actual_next = ref[mask], actual_next[mask]
+    q50 = aligned.loc[mask.index[mask], "q50"]
+
+    prev_move = close.diff().reindex(ref.index).fillna(0.0)
+    rng = np.random.default_rng(seed)
+    coin = pd.Series(rng.choice([-1.0, 1.0], size=len(ref)), index=ref.index)
+
+    return {
+        "model_slug": model_slug, "asset": asset, "timeframe": timeframe,
+        "n": int(mask.sum()),
+        "model_accuracy": directional_accuracy(actual_next, q50, ref),
+        "baseline_random": directional_accuracy(actual_next, ref + coin, ref),
+        "baseline_momentum": directional_accuracy(actual_next, ref + prev_move, ref),
+        "baseline_yesterday_move": directional_accuracy(
+            actual_next, ref + prev_move.shift(1).fillna(0.0), ref
+        ),
+        "is_placeholder": bool(
+            (aligned["inference_version"] == config.PLACEHOLDER_VERSION).any()
+            if "inference_version" in aligned.columns else False
+        ),
+    }
+
+
+# --------------------------------------------------------------------------
+# Backtest-derived tables
+# --------------------------------------------------------------------------
+
+
+def _run(strategy: str, prices: pd.DataFrame, signals: pd.DataFrame | None,
+         asset: str, timeframe: str):
+    cfg = _default_config(asset, timeframe, strategy)
+    out = strategies.build(strategy, prices, cfg.params, signals)
+    return run_backtest(prices, out, cfg,
+                        bars_per_year=config.bars_per_year(asset, timeframe))
+
+
+def model_performance_row(prices, signals, model_slug, asset, timeframe) -> dict | None:
+    """OOS performance of the default Forecast Follower rule over this model."""
+    if signals is None or signals.empty:
+        return None
+    try:
+        res = _run("Chronos Forecast Follower", prices, signals, asset, timeframe)
+    except Exception as e:
+        log.warning("forecast-follower run failed for %s/%s/%s: %s",
+                    model_slug, asset, timeframe, e)
+        return None
+
+    m = res.metrics_oos
+    return {
+        "model_slug": model_slug, "asset": asset, "timeframe": timeframe,
+        "strategy": "Chronos Forecast Follower",
+        "oos_sharpe": m.sharpe, "oos_return": m.total_return,
+        "oos_max_drawdown": m.max_drawdown, "oos_sortino": m.sortino,
+        "trades": m.trade_count, "win_rate": m.win_rate,
+        "costs_paid": res.costs_paid,
+        "holdout_sharpe": res.metrics_holdout.sharpe if res.metrics_holdout else float("nan"),
+        "is_sharpe": res.metrics_is.sharpe,
+        "oos_is_ratio": (m.sharpe / res.metrics_is.sharpe)
+                        if res.metrics_is.sharpe not in (0.0, None) else float("nan"),
+        "is_placeholder": bool(
+            (signals["inference_version"] == config.PLACEHOLDER_VERSION).any()
+            if "inference_version" in signals.columns else False
+        ),
+    }
+
+
+def heatmap_rows(store: SignalStore, asset: str, model_slug: str | None = None) -> list[dict]:
+    """OOS Sharpe for every (strategy, timeframe) pair that has price coverage."""
+    rows = []
+    for tf in config.TIMEFRAMES:
+        prices = store.get_prices(asset, tf)
+        if len(prices) < 120:
+            continue
+        signals = (store.get_signals(model_slug, asset, tf)
+                   if model_slug else pd.DataFrame())
+        for strategy in HEATMAP_STRATEGIES:
+            preset = strategies.PRESETS.get(strategy)
+            if preset is None or not preset.available:
+                continue
+            if preset.needs_signals and (signals is None or signals.empty):
+                rows.append({"asset": asset, "strategy": strategy, "timeframe": tf,
+                             "oos_sharpe": float("nan"), "trades": 0,
+                             "status": "no signal coverage"})
+                continue
+            try:
+                res = _run(strategy, prices, signals, asset, tf)
+                rows.append({
+                    "asset": asset, "strategy": strategy, "timeframe": tf,
+                    "oos_sharpe": res.metrics_oos.sharpe,
+                    "oos_return": res.metrics_oos.total_return,
+                    "trades": res.metrics_oos.trade_count,
+                    "status": "ok",
+                })
+            except Exception as e:
+                log.warning("heatmap cell failed %s/%s/%s: %s", asset, strategy, tf, e)
+                rows.append({"asset": asset, "strategy": strategy, "timeframe": tf,
+                             "oos_sharpe": float("nan"), "trades": 0,
+                             "status": f"error: {type(e).__name__}"})
+    return rows
+
+
+# --------------------------------------------------------------------------
+# Regeneration
+# --------------------------------------------------------------------------
+
+
+def regenerate(store: SignalStore, *, assets: list[str] | None = None,
+               write: bool = True) -> ComparisonReport:
+    """Rebuild every comparison table from what the store currently holds."""
+    manifest = store.load_manifest()
+    assets = assets or sorted({e.asset for e in manifest.signals.values()}
+                              | {p.asset for p in manifest.prices.values()})
+
+    perf, calib, direc, heat = [], [], [], []
+
+    for entry in manifest.signals.values():
+        if assets and entry.asset not in assets:
+            continue
+        prices = store.get_prices(entry.asset, entry.timeframe)
+        signals = store.get_signals(entry.model_slug, entry.asset, entry.timeframe)
+        if prices.empty or signals.empty:
+            continue
+
+        r = model_performance_row(prices, signals, entry.model_slug,
+                                  entry.asset, entry.timeframe)
+        if r:
+            perf.append(r)
+        r = calibration_row(prices, signals, entry.model_slug, entry.asset, entry.timeframe)
+        if r:
+            calib.append(r)
+        r = directional_row(prices, signals, entry.model_slug, entry.asset, entry.timeframe)
+        if r:
+            direc.append(r)
+
+    for asset in assets:
+        best_model = None
+        candidates = manifest.find_signals(asset=asset)
+        if candidates:
+            best_model = candidates[0].model_slug
+        heat.extend(heatmap_rows(store, asset, best_model))
+
+    report = ComparisonReport(
+        model_performance=pd.DataFrame(perf),
+        calibration=pd.DataFrame(calib),
+        directional=pd.DataFrame(direc),
+        heatmap=pd.DataFrame(heat),
+    )
+
+    if write:
+        if not report.model_performance.empty:
+            store.write_table(MODEL_PERF, report.model_performance)
+        if not report.calibration.empty:
+            store.write_table(CALIBRATION, report.calibration)
+        if not report.directional.empty:
+            store.write_table(DIRECTIONAL, report.directional)
+        if not report.heatmap.empty:
+            store.write_table(HEATMAP, report.heatmap)
+        store.write_json(INDEX_JSON, {
+            "generated_at": pd.Timestamp.now(tz="UTC").isoformat(),
+            "assets": list(assets),
+            "tables": {
+                "model_performance": {"path": MODEL_PERF, "rows": len(report.model_performance)},
+                "calibration": {"path": CALIBRATION, "rows": len(report.calibration)},
+                "directional_accuracy": {"path": DIRECTIONAL, "rows": len(report.directional)},
+                "strategy_timeframe_heatmap": {"path": HEATMAP, "rows": len(report.heatmap)},
+            },
+            "default_rule": "Chronos Forecast Follower, costs on, walk-forward 12/3/3, 6mo holdout",
+        })
+    return report
+
+
+def load_table(store: SignalStore, path: str) -> pd.DataFrame:
+    df = store.read_parquet(path)
+    return df if df is not None else pd.DataFrame()

src/config.py

@@ -0,0 +1,207 @@
+"""Central configuration for the Backtest Lab.
+
+Everything that a maintainer might want to tune -- repo ids, provider chains,
+asset universe, rate limits, guardrails -- lives here as data, not code.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+# --------------------------------------------------------------------------
+# Repos
+# --------------------------------------------------------------------------
+
+ORG = "The-Bit-Trading-Company"
+
+# The shared signal store lives under the org (the company-branded data asset).
+STORE_REPO = os.environ.get("BIT_STORE_REPO", f"{ORG}/bit-signal-store")
+STORE_REPO_TYPE = "dataset"
+
+# The Space itself. Gradio Spaces under an org require a paid Team/Enterprise
+# plan, so the app is hosted under the owner's PRO personal namespace.
+# See DECISIONS.md (D-001).
+SPACE_REPO = os.environ.get("BIT_SPACE_REPO", "Bit-Trading-Company/bit-backtest-lab")
+
+MANIFEST_PATH = "manifest.json"
+MANIFEST_SCHEMA_VERSION = 1
+
+# Bumped whenever a change to inference or storage semantics invalidates
+# previously-written signal slices.
+INFERENCE_VERSION = "1.0.0"
+PLACEHOLDER_VERSION = "PLACEHOLDER"
+
+# --------------------------------------------------------------------------
+# Assets & timeframes
+# --------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Asset:
+    """One tradable symbol, with the per-provider symbol spellings it needs."""
+
+    slug: str  # canonical id used in store paths, e.g. "BTC-USD"
+    display: str
+    kind: str  # "crypto" | "equity"
+    ccxt_symbol: str | None = None
+    yahoo_symbol: str | None = None
+    stooq_symbol: str | None = None
+    tiingo_symbol: str | None = None
+
+
+ASSETS: dict[str, Asset] = {
+    a.slug: a
+    for a in [
+        Asset("BTC-USD", "Bitcoin", "crypto", ccxt_symbol="BTC/USDT", yahoo_symbol="BTC-USD"),
+        Asset("ETH-USD", "Ethereum", "crypto", ccxt_symbol="ETH/USDT", yahoo_symbol="ETH-USD"),
+        Asset("SOL-USD", "Solana", "crypto", ccxt_symbol="SOL/USDT", yahoo_symbol="SOL-USD"),
+        Asset("SPY", "S&P 500 ETF", "equity", yahoo_symbol="SPY",
+              stooq_symbol="spy.us", tiingo_symbol="SPY"),
+        Asset("QQQ", "Nasdaq 100 ETF", "equity", yahoo_symbol="QQQ",
+              stooq_symbol="qqq.us", tiingo_symbol="QQQ"),
+        Asset("NVDA", "NVIDIA", "equity", yahoo_symbol="NVDA",
+              stooq_symbol="nvda.us", tiingo_symbol="NVDA"),
+    ]
+}
+
+
+@dataclass(frozen=True)
+class Timeframe:
+    slug: str
+    pandas_freq: str
+    minutes: int
+    bars_per_year: float
+    ccxt_tf: str | None = None
+    yahoo_interval: str | None = None
+    # Provider-imposed history depth, in days. None = no practical limit.
+    # These are honest coverage boundaries, not errors (see data.py).
+    yahoo_max_days: int | None = None
+
+
+TIMEFRAMES: dict[str, Timeframe] = {
+    t.slug: t
+    for t in [
+        Timeframe("1d", "D", 1440, 365.0, ccxt_tf="1d", yahoo_interval="1d"),
+        Timeframe("1h", "h", 60, 365.0 * 24, ccxt_tf="1h", yahoo_interval="1h",
+                  yahoo_max_days=730),
+        Timeframe("15m", "15min", 15, 365.0 * 24 * 4, ccxt_tf="15m",
+                  yahoo_interval="15m", yahoo_max_days=60),
+    ]
+}
+
+# Equities only trade during market hours, so a calendar year holds far fewer
+# bars than the wall-clock math above. Annualisation uses these instead.
+EQUITY_BARS_PER_YEAR = {"1d": 252.0, "1h": 252.0 * 6.5, "15m": 252.0 * 26.0}
+
+
+def bars_per_year(asset_slug: str, tf_slug: str) -> float:
+    """Annualisation factor for Sharpe/CAGR, respecting market calendars."""
+    asset = ASSETS.get(asset_slug)
+    if asset is not None and asset.kind == "equity":
+        return EQUITY_BARS_PER_YEAR[tf_slug]
+    return TIMEFRAMES[tf_slug].bars_per_year
+
+
+# --------------------------------------------------------------------------
+# Provider chain (config, not code -- data.py walks these in order)
+# --------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class ProviderSpec:
+    name: str
+    kinds: tuple[str, ...]
+    # Minimum seconds between calls, and backoff schedule on failure.
+    min_interval_s: float = 0.25
+    max_retries: int = 4
+    backoff_base_s: float = 1.5
+    requires_env: str | None = None
+
+
+PROVIDER_CHAIN: tuple[ProviderSpec, ...] = (
+    ProviderSpec("binance", ("crypto",), min_interval_s=0.10),
+    ProviderSpec("coinbase", ("crypto",), min_interval_s=0.35),
+    ProviderSpec("yfinance", ("equity",), min_interval_s=1.20),
+    ProviderSpec("stooq", ("equity",), min_interval_s=1.00),
+    ProviderSpec("tiingo", ("equity",), min_interval_s=0.60, requires_env="TIINGO_KEY"),
+)
+
+
+def providers_for(kind: str) -> list[ProviderSpec]:
+    """Ordered, currently-usable providers for an asset kind."""
+    out = []
+    for p in PROVIDER_CHAIN:
+        if kind not in p.kinds:
+            continue
+        if p.requires_env and not os.environ.get(p.requires_env):
+            continue
+        out.append(p)
+    return out
+
+
+# --------------------------------------------------------------------------
+# Models
+# --------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class ModelSpec:
+    slug: str  # store path segment
+    model_id: str  # HF model id
+    family: str  # adapter family
+    display: str
+    context_len: int = 512
+    quantile_levels: tuple[float, ...] = (0.1, 0.5, 0.9)
+
+
+SEED_MODELS: dict[str, ModelSpec] = {
+    m.slug: m
+    for m in [
+        ModelSpec("chronos-bolt-small", "amazon/chronos-bolt-small", "chronos",
+                  "Chronos-Bolt Small", context_len=512),
+        ModelSpec("chronos-bolt-base", "amazon/chronos-bolt-base", "chronos",
+                  "Chronos-Bolt Base", context_len=512),
+        ModelSpec("timesfm-2-500m", "google/timesfm-2.0-500m-pytorch", "timesfm",
+                  "TimesFM 2.0 500M", context_len=512),
+    ]
+}
+
+# Adapter families a user may pick from in the "Add model" flow. Restricting to
+# a fixed set is what keeps arbitrary model code from ever being executed.
+ALLOWED_ADAPTER_FAMILIES = ("chronos", "timesfm")
+
+
+# --------------------------------------------------------------------------
+# Guardrails for user-funded coverage extension
+# --------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class ExtensionCaps:
+    max_days: dict[str, int] = field(
+        default_factory=lambda: {"1d": 730, "1h": 183, "15m": 62}
+    )
+    max_steps_per_run: int = 4000
+    smoke_test_steps: int = 100
+
+
+CAPS = ExtensionCaps()
+
+# --------------------------------------------------------------------------
+# Backtest defaults
+# --------------------------------------------------------------------------
+
+DEFAULT_INIT_CASH = 10_000.0
+DEFAULT_COMMISSION_BPS = 10.0  # per side
+DEFAULT_SLIPPAGE_BPS = 5.0
+DEFAULT_HOLDOUT_MONTHS = 6
+
+# In-process LRU sizing for parquet slices (Phase 3 perf target: <2s runs).
+PARQUET_CACHE_SIZE = 64
+
+DISCLAIMER = (
+    "Backtested results are hypothetical, derived from historical data, and are "
+    "not indicative of future results. Nothing here is investment advice. "
+    "The Bit Trading Company is not a licensed investment adviser."
+)

src/data.py

@@ -0,0 +1,458 @@
+"""OHLCV acquisition: provider chain, rate limiting, validation, refresh.
+
+Two hard rules enforced here:
+
+1. **Only the batch refresh path touches an external provider.** User-facing
+   requests read exclusively from the cached store. `allow_network()` gates
+   every outbound call and is off unless a refresh explicitly opens it.
+2. **Never silently return partial data.** Every fetch reports what it actually
+   got versus what was asked for; short coverage becomes an honest boundary in
+   the manifest, never a silent truncation and never an error.
+
+Providers are declared in `config.PROVIDER_CHAIN`; adding one means adding a
+spec plus a fetch function to `_FETCHERS`, not restructuring the chain.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import io
+import logging
+import os
+import random
+import threading
+import time
+from dataclasses import dataclass, field
+
+import pandas as pd
+
+from . import config
+from .config import Asset, ProviderSpec
+from .store import PRICE_COLUMNS, SignalStore, _iso, _utc, validate_price_frame
+
+log = logging.getLogger("bit.data")
+
+# --------------------------------------------------------------------------
+# Network gate
+# --------------------------------------------------------------------------
+
+_network = threading.local()
+
+
+def network_allowed() -> bool:
+    return getattr(_network, "allowed", False)
+
+
+@contextlib.contextmanager
+def allow_network():
+    """Open the gate for a batch refresh. Scoped to the calling thread."""
+    prev = getattr(_network, "allowed", False)
+    _network.allowed = True
+    try:
+        yield
+    finally:
+        _network.allowed = prev
+
+
+class ProviderError(RuntimeError):
+    """A provider failed in a way that should advance the chain."""
+
+
+class NetworkNotAllowed(RuntimeError):
+    """A user-facing code path tried to reach an external provider."""
+
+
+# --------------------------------------------------------------------------
+# Rate limiting + backoff
+# --------------------------------------------------------------------------
+
+
+class RateLimiter:
+    """Per-provider minimum spacing between outbound calls, process-wide."""
+
+    _locks: dict[str, threading.Lock] = {}
+    _last: dict[str, float] = {}
+    _guard = threading.Lock()
+
+    @classmethod
+    def wait(cls, name: str, min_interval_s: float) -> None:
+        with cls._guard:
+            lock = cls._locks.setdefault(name, threading.Lock())
+        with lock:
+            last = cls._last.get(name, 0.0)
+            delta = time.monotonic() - last
+            if delta < min_interval_s:
+                time.sleep(min_interval_s - delta)
+            cls._last[name] = time.monotonic()
+
+
+def with_backoff(spec: ProviderSpec, fn, *args, **kwargs):
+    """Run `fn` under the provider's rate limit with exponential backoff."""
+    last_err: Exception | None = None
+    for attempt in range(spec.max_retries):
+        RateLimiter.wait(spec.name, spec.min_interval_s)
+        try:
+            return fn(*args, **kwargs)
+        except Exception as e:  # provider libs raise a wide variety
+            last_err = e
+            if attempt == spec.max_retries - 1:
+                break
+            sleep_s = (spec.backoff_base_s ** attempt) + random.uniform(0, 0.4)
+            log.warning(
+                "provider %s attempt %d/%d failed (%s); backing off %.1fs",
+                spec.name, attempt + 1, spec.max_retries, type(e).__name__, sleep_s,
+            )
+            time.sleep(sleep_s)
+    raise ProviderError(f"{spec.name} exhausted retries: {last_err}") from last_err
+
+
+# --------------------------------------------------------------------------
+# Fetch result
+# --------------------------------------------------------------------------
+
+
+@dataclass
+class FetchResult:
+    frame: pd.DataFrame
+    source: str
+    requested_start: pd.Timestamp
+    requested_end: pd.Timestamp
+    # True when the provider's own history depth, not our request, set the floor.
+    truncated_by_provider: bool = False
+    provider_max_days: int | None = None
+    notes: list[str] = field(default_factory=list)
+
+    @property
+    def rows(self) -> int:
+        return len(self.frame)
+
+    @property
+    def actual_start(self) -> pd.Timestamp | None:
+        return None if self.frame.empty else _utc(self.frame["ts"].iloc[0])
+
+    @property
+    def actual_end(self) -> pd.Timestamp | None:
+        return None if self.frame.empty else _utc(self.frame["ts"].iloc[-1])
+
+
+def _frame(rows: list[dict], source: str) -> pd.DataFrame:
+    df = pd.DataFrame(rows, columns=["ts", "open", "high", "low", "close", "volume"])
+    df["source"] = source
+    if not df.empty:
+        df["ts"] = df["ts"].map(_utc)
+        df = df.drop_duplicates(subset="ts", keep="last").sort_values("ts")
+    return df.loc[:, PRICE_COLUMNS].reset_index(drop=True)
+
+
+# --------------------------------------------------------------------------
+# Providers
+# --------------------------------------------------------------------------
+
+
+def _ccxt_exchange(name: str):
+    import ccxt
+
+    klass = getattr(ccxt, name)
+    ex = klass({"enableRateLimit": True, "timeout": 20000})
+    return ex
+
+
+def _fetch_ccxt(exchange_name: str, spec: ProviderSpec, asset: Asset,
+                tf: str, start, end) -> pd.DataFrame:
+    if not asset.ccxt_symbol:
+        raise ProviderError(f"{asset.slug} has no ccxt symbol")
+    ex = _ccxt_exchange(exchange_name)
+    ccxt_tf = config.TIMEFRAMES[tf].ccxt_tf
+    step_ms = config.TIMEFRAMES[tf].minutes * 60_000
+    since = int(_utc(start).timestamp() * 1000)
+    end_ms = int(_utc(end).timestamp() * 1000)
+    rows: list[dict] = []
+    guard = 0
+
+    while since < end_ms and guard < 4000:
+        guard += 1
+        batch = with_backoff(
+            spec, ex.fetch_ohlcv, asset.ccxt_symbol, ccxt_tf, since, 1000
+        )
+        if not batch:
+            break
+        for ts, o, h, l, c, v in batch:
+            if ts > end_ms:
+                break
+            rows.append({"ts": pd.Timestamp(ts, unit="ms", tz="UTC"),
+                         "open": o, "high": h, "low": l, "close": c, "volume": v})
+        last = batch[-1][0]
+        if last <= since:
+            break
+        since = last + step_ms
+
+    with contextlib.suppress(Exception):
+        ex.close()
+    return _frame(rows, exchange_name)
+
+
+def _fetch_binance(spec, asset, tf, start, end):
+    return _fetch_ccxt("binance", spec, asset, tf, start, end)
+
+
+def _fetch_coinbase(spec, asset, tf, start, end):
+    return _fetch_ccxt("coinbase", spec, asset, tf, start, end)
+
+
+def _fetch_yfinance(spec: ProviderSpec, asset: Asset, tf: str, start, end) -> pd.DataFrame:
+    if not asset.yahoo_symbol:
+        raise ProviderError(f"{asset.slug} has no Yahoo symbol")
+    import yfinance as yf
+
+    interval = config.TIMEFRAMES[tf].yahoo_interval
+    max_days = config.TIMEFRAMES[tf].yahoo_max_days
+    s, e = _utc(start), _utc(end)
+    if max_days is not None:
+        floor = pd.Timestamp.now(tz="UTC") - pd.Timedelta(days=max_days - 1)
+        s = max(s, floor)  # honest boundary; see refresh() notes
+
+    def _call():
+        return yf.download(
+            asset.yahoo_symbol, start=s.date(), end=(e + pd.Timedelta(days=1)).date(),
+            interval=interval, auto_adjust=False, progress=False, threads=False,
+        )
+
+    raw = with_backoff(spec, _call)
+    if raw is None or raw.empty:
+        raise ProviderError("yfinance returned no rows")
+    if isinstance(raw.columns, pd.MultiIndex):
+        raw.columns = raw.columns.get_level_values(0)
+    # reset_index first: the timestamp arrives as the index ("Date"/"Datetime")
+    # and only becomes a column here, so lowercasing must happen afterwards.
+    raw = raw.reset_index()
+    raw.columns = [str(c).lower() for c in raw.columns]
+    tcol = next((c for c in ("datetime", "date", "index") if c in raw.columns), None)
+    if tcol is None:
+        raise ProviderError(f"yfinance frame has no timestamp column: {list(raw.columns)}")
+    rows = [
+        {"ts": r[tcol], "open": r["open"], "high": r["high"],
+         "low": r["low"], "close": r["close"], "volume": r.get("volume", 0.0)}
+        for _, r in raw.iterrows()
+    ]
+    return _frame(rows, "yfinance")
+
+
+def _fetch_stooq(spec: ProviderSpec, asset: Asset, tf: str, start, end) -> pd.DataFrame:
+    """Stooq CSV endpoint -- no key, daily only."""
+    if tf != "1d":
+        raise ProviderError("stooq serves daily bars only")
+    if not asset.stooq_symbol:
+        raise ProviderError(f"{asset.slug} has no Stooq symbol")
+    import requests
+
+    url = f"https://stooq.com/q/d/l/?s={asset.stooq_symbol}&i=d"
+
+    def _call():
+        r = requests.get(url, timeout=20)
+        r.raise_for_status()
+        if "Date" not in r.text[:64]:
+            raise ProviderError("stooq returned no CSV header (rate limited?)")
+        return r.text
+
+    text = with_backoff(spec, _call)
+    raw = pd.read_csv(io.StringIO(text))
+    raw.columns = [c.lower() for c in raw.columns]
+    raw = raw.dropna(subset=["open", "high", "low", "close"])
+    s, e = _utc(start), _utc(end)
+    rows = []
+    for _, r in raw.iterrows():
+        ts = _utc(r["date"])
+        if ts < s or ts > e:
+            continue
+        rows.append({"ts": ts, "open": r["open"], "high": r["high"],
+                     "low": r["low"], "close": r["close"], "volume": r.get("volume", 0.0)})
+    return _frame(rows, "stooq")
+
+
+def _fetch_tiingo(spec: ProviderSpec, asset: Asset, tf: str, start, end) -> pd.DataFrame:
+    if tf != "1d":
+        raise ProviderError("tiingo adapter covers daily bars only")
+    key = os.environ.get("TIINGO_KEY")
+    if not key:
+        raise ProviderError("TIINGO_KEY not set")
+    import requests
+
+    sym = asset.tiingo_symbol or asset.slug
+    url = f"https://api.tiingo.com/tiingo/daily/{sym}/prices"
+    params = {"startDate": _utc(start).date().isoformat(),
+              "endDate": _utc(end).date().isoformat(), "token": key}
+
+    def _call():
+        r = requests.get(url, params=params, timeout=20)
+        r.raise_for_status()
+        return r.json()
+
+    payload = with_backoff(spec, _call)
+    rows = [
+        {"ts": _utc(d["date"]), "open": d["open"], "high": d["high"],
+         "low": d["low"], "close": d["close"], "volume": d.get("volume", 0.0)}
+        for d in payload
+    ]
+    return _frame(rows, "tiingo")
+
+
+_FETCHERS = {
+    "binance": _fetch_binance,
+    "coinbase": _fetch_coinbase,
+    "yfinance": _fetch_yfinance,
+    "stooq": _fetch_stooq,
+    "tiingo": _fetch_tiingo,
+}
+
+
+# --------------------------------------------------------------------------
+# Chain walk
+# --------------------------------------------------------------------------
+
+
+def fetch_ohlcv(asset_slug: str, timeframe: str, start, end) -> FetchResult:
+    """Walk the provider chain for `asset_slug` until one returns rows."""
+    if not network_allowed():
+        raise NetworkNotAllowed(
+            "external providers are reachable only from the batch refresh path; "
+            "user-facing requests must read from the cached store"
+        )
+    asset = config.ASSETS.get(asset_slug)
+    if asset is None:
+        raise ProviderError(f"unknown asset {asset_slug!r}")
+    if timeframe not in config.TIMEFRAMES:
+        raise ProviderError(f"unknown timeframe {timeframe!r}")
+
+    s, e = _utc(start), _utc(end)
+    chain = config.providers_for(asset.kind)
+    if not chain:
+        raise ProviderError(f"no usable provider for {asset.kind}")
+
+    notes: list[str] = []
+    for spec in chain:
+        fetcher = _FETCHERS.get(spec.name)
+        if fetcher is None:
+            continue
+        try:
+            frame = fetcher(spec, asset, timeframe, s, e)
+        except Exception as exc:
+            notes.append(f"{spec.name}: {type(exc).__name__}: {exc}")
+            log.warning("provider %s failed for %s %s: %s", spec.name, asset_slug, timeframe, exc)
+            continue
+        if frame.empty:
+            notes.append(f"{spec.name}: returned 0 rows")
+            continue
+
+        max_days = config.TIMEFRAMES[timeframe].yahoo_max_days if spec.name == "yfinance" else None
+        actual_start = _utc(frame["ts"].iloc[0])
+        truncated = max_days is not None and actual_start > s + pd.Timedelta(days=1)
+        if truncated:
+            notes.append(
+                f"{spec.name} serves at most ~{max_days}d of {timeframe} bars; "
+                f"coverage starts {_iso(actual_start)}"
+            )
+        return FetchResult(
+            frame=frame, source=spec.name, requested_start=s, requested_end=e,
+            truncated_by_provider=truncated, provider_max_days=max_days, notes=notes,
+        )
+
+    raise ProviderError(
+        f"all providers failed for {asset_slug} {timeframe} "
+        f"[{_iso(s)} .. {_iso(e)}]: " + " | ".join(notes)
+    )
+
+
+# --------------------------------------------------------------------------
+# Refresh
+# --------------------------------------------------------------------------
+
+
+@dataclass
+class RefreshReport:
+    asset: str
+    timeframe: str
+    fetched_ranges: list[tuple[str, str]] = field(default_factory=list)
+    rows_added: int = 0
+    sources: list[str] = field(default_factory=list)
+    skipped_cached: bool = False
+    gaps: int = 0
+    boundary_notes: list[str] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return not self.errors
+
+    def summary(self) -> str:
+        if self.skipped_cached:
+            return f"{self.asset} {self.timeframe}: already cached, nothing fetched"
+        if self.errors:
+            return f"{self.asset} {self.timeframe}: FAILED -- {'; '.join(self.errors)}"
+        return (
+            f"{self.asset} {self.timeframe}: +{self.rows_added} rows "
+            f"from {','.join(self.sources) or 'n/a'} ({self.gaps} gaps)"
+        )
+
+
+def missing_price_ranges(
+    store: SignalStore, asset: str, timeframe: str, start, end
+) -> list[tuple[pd.Timestamp, pd.Timestamp]]:
+    """Sub-ranges of [start, end] absent from the price cache."""
+    s, e = _utc(start), _utc(end)
+    if s > e:
+        return []
+    cov = store.load_manifest().prices.get(f"{asset}|{timeframe}")
+    if cov is None or cov.rows == 0:
+        return [(s, e)]
+    cs, ce = _utc(cov.start_ts), _utc(cov.end_ts)
+    step = pd.Timedelta(minutes=config.TIMEFRAMES[timeframe].minutes)
+    out = []
+    if s < cs:
+        out.append((s, min(e, cs - step)))
+    if e > ce:
+        out.append((max(s, ce + step), e))
+    return [(a, b) for a, b in out if a <= b]
+
+
+def refresh(
+    store: SignalStore, asset: str, timeframe: str, start, end, *, strict: bool = False
+) -> RefreshReport:
+    """Fetch only what the cache is missing, validate it, and write it.
+
+    Never fetches a range the manifest already covers.
+    """
+    rep = RefreshReport(asset=asset, timeframe=timeframe)
+    try:
+        gaps = missing_price_ranges(store, asset, timeframe, start, end)
+    except Exception as e:
+        rep.errors.append(f"coverage lookup failed: {e}")
+        return rep
+
+    if not gaps:
+        rep.skipped_cached = True
+        return rep
+
+    with allow_network():
+        for gs, ge in gaps:
+            try:
+                res = fetch_ohlcv(asset, timeframe, gs, ge)
+            except Exception as e:
+                rep.errors.append(f"[{_iso(gs)}..{_iso(ge)}] {e}")
+                continue
+
+            _, report = validate_price_frame(res.frame, timeframe, strict=strict)
+            if report.problems:
+                # Partial or dirty data is surfaced, never silently accepted.
+                rep.errors.append(
+                    f"[{_iso(gs)}..{_iso(ge)}] validation: {'; '.join(report.problems)}"
+                )
+                continue
+
+            cov = store.write_prices(asset, timeframe, res.frame, strict=strict)
+            rep.fetched_ranges.append((_iso(gs), _iso(ge)))
+            rep.rows_added += res.rows
+            rep.gaps = max(rep.gaps, cov.gaps)
+            if res.source not in rep.sources:
+                rep.sources.append(res.source)
+            rep.boundary_notes.extend(res.notes)
+    return rep

src/engine.py

@@ -0,0 +1,707 @@
+"""Backtest engine.
+
+Two properties are enforced structurally rather than by convention:
+
+**Fills happen at the next bar's open.** A strategy's decision at bar `t` is
+shifted forward one bar by `_shift_decisions`, which `run_backtest` always
+applies and a strategy cannot bypass, and the fill price handed to vectorbt is
+`open`. There is no code path that enters on the signal bar.
+
+**Strategies cannot see the future.** `assert_causal` perturbs the tail of a
+price series, re-runs the indicator, and requires that every output before the
+perturbation is bit-identical. A strategy that reads bar `t+1` changes its
+earlier outputs when the future changes, and is caught. This is a property
+test on the function, not a promise in a docstring.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field, asdict, replace
+
+import numpy as np
+import pandas as pd
+import vectorbt as vbt
+
+from . import config
+from .metrics import Metrics, compute_metrics
+
+# --------------------------------------------------------------------------
+# Errors
+# --------------------------------------------------------------------------
+
+
+class EngineError(RuntimeError):
+    pass
+
+
+class LookaheadError(AssertionError):
+    """A strategy's output at bar t depended on data after bar t."""
+
+
+# --------------------------------------------------------------------------
+# Configuration
+# --------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Costs:
+    """Trading frictions. On by default -- turning them off is how a backtest lies."""
+
+    enabled: bool = True
+    commission_bps: float = config.DEFAULT_COMMISSION_BPS  # per side
+    slippage_bps: float = config.DEFAULT_SLIPPAGE_BPS
+    slippage_model: str = "fixed"  # "fixed" | "volume_scaled"
+    volume_scale_k: float = 0.5
+
+    @property
+    def commission_rate(self) -> float:
+        return (self.commission_bps / 10_000.0) if self.enabled else 0.0
+
+    @property
+    def slippage_rate(self) -> float:
+        return (self.slippage_bps / 10_000.0) if self.enabled else 0.0
+
+
+@dataclass(frozen=True)
+class Sizing:
+    mode: str = "fixed_pct"  # "fixed_pct" | "vol_target" | "fixed_units"
+    pct: float = 1.0  # fraction of equity when fixed_pct
+    units: float = 1.0  # units when fixed_units
+    vol_target_ann: float = 0.15
+    vol_lookback: int = 20
+    leverage: float = 1.0
+    max_position: float = 1.0  # cap as fraction of equity
+
+
+@dataclass(frozen=True)
+class Stops:
+    sl_pct: float | None = None
+    tp_pct: float | None = None
+    trail_pct: float | None = None
+
+    @property
+    def any_set(self) -> bool:
+        return any(v is not None for v in (self.sl_pct, self.tp_pct, self.trail_pct))
+
+
+@dataclass(frozen=True)
+class Validation:
+    """How the period is carved into in-sample and out-of-sample."""
+
+    mode: str = "holdout"  # "none" | "split" | "walk_forward" | "holdout"
+    split_frac: float = 0.7
+    train_months: int = 12
+    test_months: int = 3
+    roll_months: int = 3
+    holdout_months: int = config.DEFAULT_HOLDOUT_MONTHS
+
+
+@dataclass(frozen=True)
+class BacktestConfig:
+    asset: str = "BTC-USD"
+    timeframe: str = "1d"
+    strategy: str = "Buy & Hold"
+    params: dict = field(default_factory=dict)
+    costs: Costs = field(default_factory=Costs)
+    sizing: Sizing = field(default_factory=Sizing)
+    stops: Stops = field(default_factory=Stops)
+    validation: Validation = field(default_factory=Validation)
+    init_cash: float = config.DEFAULT_INIT_CASH
+    fill: str = "next_open"  # the only supported value; see module docstring
+    direction: str = "longonly"  # "longonly" | "both"
+    # Used for R-multiple when no stop is configured. Documented, not hidden.
+    risk_per_trade_pct: float = 0.02
+
+    def fingerprint(self) -> str:
+        """Stable hash of everything that can change results -- determinism key."""
+        payload = json.dumps(asdict(self), sort_keys=True, default=str)
+        return hashlib.sha256(payload.encode()).hexdigest()[:16]
+
+
+# --------------------------------------------------------------------------
+# Strategy output
+# --------------------------------------------------------------------------
+
+
+@dataclass
+class StrategyOutput:
+    """Decisions aligned to bar *close*. The engine shifts them, not you."""
+
+    entries: pd.Series
+    exits: pd.Series
+    triggers: pd.Series | None = None
+    short_entries: pd.Series | None = None
+    short_exits: pd.Series | None = None
+    shifted: bool = False
+
+    def validate(self, index: pd.Index) -> None:
+        for name in ("entries", "exits", "short_entries", "short_exits"):
+            s = getattr(self, name)
+            if s is None:
+                continue
+            if not s.index.equals(index):
+                raise EngineError(f"{name} index does not match the price index")
+
+
+def _shift_decisions(out: StrategyOutput) -> StrategyOutput:
+    """Move every decision one bar forward, so it can only act at the next open."""
+    if out.shifted:
+        raise EngineError("decisions were already shifted; shift exactly once")
+
+    def sh(s):
+        if s is None:
+            return None
+        # Cast before filling: filling an object-dtype series with False and
+        # then downcasting is deprecated in pandas and would change behaviour.
+        return s.astype("boolean").shift(1).fillna(False).astype(bool)
+
+    def sh_obj(s):
+        if s is None:
+            return None
+        return s.shift(1)
+
+    return StrategyOutput(
+        entries=sh(out.entries),
+        exits=sh(out.exits),
+        triggers=sh_obj(out.triggers),
+        short_entries=sh(out.short_entries),
+        short_exits=sh(out.short_exits),
+        shifted=True,
+    )
+
+
+# --------------------------------------------------------------------------
+# Structural causality check
+# --------------------------------------------------------------------------
+
+
+def assert_causal(
+    indicator_fn,
+    prices: pd.DataFrame,
+    *,
+    probe_fracs: tuple[float, ...] = (0.4, 0.55, 0.7, 0.85),
+    bumps: tuple[float, ...] = (1.35, 0.65),
+) -> None:
+    """Fail if `indicator_fn`'s output before bar k depends on data after bar k.
+
+    `indicator_fn(prices) -> StrategyOutput | Series | DataFrame`. For each
+    probe point the tail of the price frame is scaled, and every output value
+    strictly before the probe must be unchanged.
+
+    The tail is scaled both up and down. One direction alone is not enough: a
+    boolean comparison that is already `True` can survive an upward bump
+    unchanged, so a peeking strategy would slip through. Perturbing both ways
+    forces any future-dependent comparison to flip in at least one of them.
+    """
+    baseline = _as_frame(indicator_fn(prices))
+    n = len(prices)
+
+    for frac in probe_fracs:
+        k = int(n * frac)
+        if k < 2 or k >= n:
+            continue
+        for bump in bumps:
+            perturbed = prices.copy()
+            tail = perturbed.index[k:]
+            for col in ("open", "high", "low", "close"):
+                if col in perturbed.columns:
+                    perturbed.loc[tail, col] = perturbed.loc[tail, col] * bump
+            if "volume" in perturbed.columns:
+                perturbed.loc[tail, "volume"] = perturbed.loc[tail, "volume"] * bump
+
+            probed = _as_frame(indicator_fn(perturbed))
+            a, b = baseline.iloc[:k], probed.iloc[:k]
+            if not _frames_equal(a, b):
+                where = _first_difference(a, b)
+                raise LookaheadError(
+                    f"output changed before the perturbation point (bar {k}, "
+                    f"{prices.index[k]}, tail scaled by {bump}): first divergence "
+                    f"at {where}. The strategy is using information from after "
+                    f"the bar it acts on."
+                )
+
+
+def _as_frame(obj) -> pd.DataFrame:
+    if isinstance(obj, StrategyOutput):
+        cols = {"entries": obj.entries, "exits": obj.exits}
+        if obj.short_entries is not None:
+            cols["short_entries"] = obj.short_entries
+        if obj.short_exits is not None:
+            cols["short_exits"] = obj.short_exits
+        return pd.DataFrame(cols)
+    if isinstance(obj, pd.Series):
+        return obj.to_frame("value")
+    if isinstance(obj, pd.DataFrame):
+        return obj
+    raise EngineError(f"cannot interpret indicator output of type {type(obj)}")
+
+
+def _frames_equal(a: pd.DataFrame, b: pd.DataFrame) -> bool:
+    if list(a.columns) != list(b.columns) or len(a) != len(b):
+        return False
+    for c in a.columns:
+        x, y = a[c], b[c]
+        if x.dtype == bool or y.dtype == bool:
+            xa = x.astype('boolean').fillna(False).astype(bool).to_numpy()
+            ya = y.astype('boolean').fillna(False).astype(bool).to_numpy()
+            if not (xa == ya).all():
+                return False
+        elif np.issubdtype(x.dtype, np.number):
+            if not np.allclose(x.fillna(0).to_numpy(), y.fillna(0).to_numpy(),
+                               rtol=1e-12, atol=1e-12):
+                return False
+        else:
+            if not (x.fillna("").astype(str).to_numpy()
+                    == y.fillna("").astype(str).to_numpy()).all():
+                return False
+    return True
+
+
+def _first_difference(a: pd.DataFrame, b: pd.DataFrame) -> str:
+    for c in a.columns:
+        x = a[c].fillna(0) if np.issubdtype(a[c].dtype, np.number) else a[c].fillna("")
+        y = b[c].fillna(0) if np.issubdtype(b[c].dtype, np.number) else b[c].fillna("")
+        diff = np.where(x.to_numpy() != y.to_numpy())[0]
+        if len(diff):
+            return f"column {c!r}, bar {int(diff[0])} ({a.index[int(diff[0])]})"
+    return "unknown"
+
+
+# --------------------------------------------------------------------------
+# Validation plans
+# --------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Window:
+    idx: int
+    train_start: pd.Timestamp
+    train_end: pd.Timestamp
+    test_start: pd.Timestamp
+    test_end: pd.Timestamp
+
+    def validate(self) -> None:
+        if self.train_start > self.train_end:
+            raise EngineError(f"window {self.idx}: inverted train range")
+        if self.test_start > self.test_end:
+            raise EngineError(f"window {self.idx}: inverted test range")
+        if self.test_start <= self.train_end:
+            raise EngineError(
+                f"window {self.idx}: test starts {self.test_start} which is not "
+                f"after train end {self.train_end} -- train/test would overlap"
+            )
+
+
+@dataclass
+class ValidationPlan:
+    mode: str
+    index: pd.DatetimeIndex
+    holdout_start: pd.Timestamp | None = None
+    is_end: pd.Timestamp | None = None
+    windows: list[Window] = field(default_factory=list)
+    # Honest notes about what this plan could not do, surfaced in the UI.
+    notes: list[str] = field(default_factory=list)
+
+    @property
+    def holdout_mask(self) -> pd.Series:
+        if self.holdout_start is None:
+            return pd.Series(False, index=self.index)
+        return pd.Series(self.index >= self.holdout_start, index=self.index)
+
+    def selectable_index(self) -> pd.DatetimeIndex:
+        """Bars any parameter-selection path is permitted to touch.
+
+        The holdout is excluded here and nowhere else, so a caller cannot fit
+        on it by accident.
+        """
+        if self.holdout_start is None:
+            return self.index
+        return self.index[self.index < self.holdout_start]
+
+    def segment_of(self, ts: pd.Timestamp) -> str:
+        if self.holdout_start is not None and ts >= self.holdout_start:
+            return "holdout"
+        if self.is_end is not None:
+            return "IS" if ts <= self.is_end else "OOS"
+        for w in self.windows:
+            if w.test_start <= ts <= w.test_end:
+                return "OOS"
+        return "IS"
+
+
+def build_validation_plan(index: pd.DatetimeIndex, v: Validation) -> ValidationPlan:
+    if len(index) == 0:
+        return ValidationPlan(mode=v.mode, index=index)
+
+    start, end = index[0], index[-1]
+
+    # A locked holdout applies to every mode except "none". Walk-forward in
+    # particular must not roll its windows into reserved data -- the design
+    # shows rolling windows and an "OOS holdout LAST 6MO" side by side.
+    holdout_start = None
+    if v.mode != "none" and v.holdout_months > 0:
+        holdout_start = end - pd.DateOffset(months=v.holdout_months)
+        if holdout_start <= start:
+            holdout_start = None
+
+    plan = ValidationPlan(mode=v.mode, index=index, holdout_start=holdout_start)
+
+    if v.mode == "none":
+        plan.is_end = end
+        return plan
+
+    if v.mode == "split":
+        cut = int(len(index) * v.split_frac)
+        cut = min(max(cut, 1), len(index) - 1)
+        plan.is_end = index[cut - 1]
+        return plan
+
+    if v.mode == "holdout":
+        plan.is_end = (holdout_start - pd.Timedelta(seconds=1)) if holdout_start else end
+        return plan
+
+    if v.mode == "walk_forward":
+        usable = plan.selectable_index() if holdout_start is not None else index
+        if len(usable) == 0:
+            return plan
+        w_start = usable[0]
+        i = 0
+        last = usable[-1]
+        while True:
+            train_start = w_start
+            train_end = train_start + pd.DateOffset(months=v.train_months)
+            test_start = train_end
+            test_end = test_start + pd.DateOffset(months=v.test_months)
+            if test_start >= last:
+                break
+            # train_end is exclusive of the test side: nudge back one instant so
+            # the two never share a boundary bar.
+            win = Window(
+                idx=i,
+                train_start=train_start,
+                train_end=train_end - pd.Timedelta(seconds=1),
+                test_start=test_start,
+                test_end=min(test_end - pd.Timedelta(seconds=1), last),
+            )
+            win.validate()
+            plan.windows.append(win)
+            i += 1
+            w_start = w_start + pd.DateOffset(months=v.roll_months)
+            if i > 200:
+                break
+        if not plan.windows:
+            span_days = (usable[-1] - usable[0]).days
+            plan.notes.append(
+                f"Walk-forward produced no out-of-sample windows: the selectable "
+                f"period is {span_days} days, which is shorter than one "
+                f"{v.train_months}-month train plus {v.test_months}-month test "
+                f"window. There is no OOS result to report — widen the date range "
+                f"or shorten the training window."
+            )
+        return plan
+
+    raise EngineError(f"unknown validation mode {v.mode!r}")
+
+
+# --------------------------------------------------------------------------
+# Results
+# --------------------------------------------------------------------------
+
+
+@dataclass
+class WindowResult:
+    window: Window
+    metrics: Metrics
+    equity: pd.Series
+
+
+@dataclass
+class BacktestResult:
+    config: BacktestConfig
+    equity: pd.Series
+    benchmark_equity: pd.Series
+    position: pd.Series
+    trades: pd.DataFrame
+    metrics_all: Metrics
+    metrics_is: Metrics
+    metrics_oos: Metrics
+    metrics_holdout: Metrics | None
+    plan: ValidationPlan
+    windows: list[WindowResult] = field(default_factory=list)
+    prices: pd.DataFrame | None = None
+    fingerprint: str = ""
+    elapsed_s: float = 0.0
+
+    @property
+    def costs_paid(self) -> float:
+        return float(self.trades["costs"].sum()) if len(self.trades) else 0.0
+
+    def summary(self) -> dict:
+        return {
+            "fingerprint": self.fingerprint,
+            "trades": int(len(self.trades)),
+            "total_return": self.metrics_all.total_return,
+            "oos_sharpe": self.metrics_oos.sharpe,
+            "max_drawdown": self.metrics_all.max_drawdown,
+            "costs_paid": self.costs_paid,
+        }
+
+
+# --------------------------------------------------------------------------
+# Sizing / slippage helpers
+# --------------------------------------------------------------------------
+
+
+def _size_args(prices: pd.DataFrame, sizing: Sizing) -> tuple:
+    """Return (size, size_type) for vectorbt."""
+    if sizing.mode == "fixed_units":
+        return sizing.units, "amount"
+
+    if sizing.mode == "vol_target":
+        rets = prices["close"].pct_change()
+        realised = rets.rolling(sizing.vol_lookback).std()
+        bpy = config.bars_per_year("BTC-USD", "1d")  # scale set by caller's tf
+        ann = realised * np.sqrt(bpy)
+        target = (sizing.vol_target_ann / ann.replace(0.0, np.nan))
+        target = target.clip(upper=sizing.max_position * sizing.leverage)
+        target = target.fillna(sizing.pct).clip(lower=0.0)
+        return target.to_numpy(), "percent"
+
+    frac = min(sizing.pct * sizing.leverage, sizing.max_position * sizing.leverage)
+    return float(frac), "percent"
+
+
+def _slippage_arg(prices: pd.DataFrame, costs: Costs):
+    base = costs.slippage_rate
+    if base == 0.0:
+        return 0.0
+    if costs.slippage_model != "volume_scaled":
+        return base
+    vol = prices["volume"].astype("float64")
+    med = float(vol.replace(0.0, np.nan).median())
+    if not np.isfinite(med) or med <= 0:
+        return base
+    # Thin bars cost more to trade than typical ones.
+    scale = 1.0 + costs.volume_scale_k * ((med / vol.replace(0.0, np.nan)) - 1.0)
+    return (base * scale.clip(lower=0.5, upper=5.0).fillna(1.0)).to_numpy()
+
+
+# --------------------------------------------------------------------------
+# Trade list construction
+# --------------------------------------------------------------------------
+
+
+def _build_trades(
+    pf, prices: pd.DataFrame, triggers: pd.Series | None,
+    cfg: BacktestConfig, plan: ValidationPlan,
+) -> pd.DataFrame:
+    """Turn vectorbt's records into the trade list the UI and metrics use."""
+    cols = ["id", "entry_ts", "exit_ts", "side", "entry_px", "exit_px", "size",
+            "gross_pnl", "costs", "net_pnl", "r_multiple", "mae", "mfe",
+            "duration_bars", "trigger", "segment", "status"]
+    rec = pf.trades.records_readable
+    if rec is None or len(rec) == 0:
+        return pd.DataFrame(columns=cols)
+
+    idx = prices.index
+    pos_of = {ts: i for i, ts in enumerate(idx)}
+    slip = cfg.costs.slippage_rate
+    rows = []
+
+    # to_dict("records") preserves the spaced column names; itertuples would
+    # rename "Entry Timestamp" to a positional field.
+    for n, d in enumerate(rec.to_dict("records")):
+        entry_ts = pd.Timestamp(d["Entry Timestamp"])
+        exit_ts = pd.Timestamp(d["Exit Timestamp"])
+        size = float(d["Size"])
+        entry_px = float(d["Avg Entry Price"])
+        exit_px = float(d["Avg Exit Price"])
+        fees = float(d["Entry Fees"]) + float(d["Exit Fees"])
+        net = float(d["PnL"])
+        side = str(d["Direction"]).lower()
+        status = str(d.get("Status", "Closed"))
+
+        # Slippage is embedded in the fill price rather than booked as a fee, so
+        # it is reconstructed from the unslipped reference price. Slippage
+        # always works against the trade: a buy fills high, a sell fills low.
+        if slip:
+            if side == "long":
+                raw_entry, raw_exit = entry_px / (1 + slip), exit_px / (1 - slip)
+            else:
+                raw_entry, raw_exit = entry_px / (1 - slip), exit_px / (1 + slip)
+            slip_cost = slip * size * (raw_entry + raw_exit)
+        else:
+            slip_cost = 0.0
+        costs_total = fees + slip_cost
+        gross = net + costs_total
+
+        i0, i1 = pos_of.get(entry_ts), pos_of.get(exit_ts)
+        mae = mfe = float("nan")
+        if i0 is not None and i1 is not None and i1 >= i0:
+            window = prices.iloc[i0:i1 + 1]
+            lo, hi = float(window["low"].min()), float(window["high"].max())
+            if side == "long":
+                mae = lo / entry_px - 1.0
+                mfe = hi / entry_px - 1.0
+            else:
+                mae = 1.0 - hi / entry_px
+                mfe = 1.0 - lo / entry_px
+
+        if cfg.stops.sl_pct:
+            risk = cfg.stops.sl_pct * entry_px * size
+        else:
+            risk = cfg.risk_per_trade_pct * entry_px * size
+        r_mult = (net / risk) if risk else float("nan")
+
+        trig = ""
+        if triggers is not None and entry_ts in triggers.index:
+            v = triggers.loc[entry_ts]
+            trig = "" if (v is None or (isinstance(v, float) and np.isnan(v))) else str(v)
+
+        rows.append({
+            "id": n + 1,
+            "entry_ts": entry_ts, "exit_ts": exit_ts, "side": side,
+            "entry_px": entry_px, "exit_px": exit_px, "size": size,
+            "gross_pnl": gross, "costs": costs_total, "net_pnl": net,
+            "r_multiple": r_mult, "mae": mae, "mfe": mfe,
+            "duration_bars": (i1 - i0) if (i0 is not None and i1 is not None) else np.nan,
+            "trigger": trig,
+            "segment": plan.segment_of(entry_ts),
+            "status": status,
+        })
+
+    return pd.DataFrame(rows, columns=cols)
+
+
+# --------------------------------------------------------------------------
+# The run
+# --------------------------------------------------------------------------
+
+
+def run_backtest(
+    prices: pd.DataFrame,
+    output: StrategyOutput,
+    cfg: BacktestConfig,
+    *,
+    bars_per_year: float | None = None,
+) -> BacktestResult:
+    """Simulate `output` on `prices` under `cfg`.
+
+    `output` must carry decisions aligned to bar close; the shift to next-bar
+    execution is applied here and only here.
+    """
+    import time
+
+    t0 = time.perf_counter()
+
+    if prices.empty:
+        raise EngineError("no price data for the requested range")
+    for c in ("open", "high", "low", "close"):
+        if c not in prices.columns:
+            raise EngineError(f"price frame missing {c!r}")
+    if cfg.fill != "next_open":
+        raise EngineError(
+            f"fill={cfg.fill!r} is not supported; next-bar-open execution is "
+            "non-negotiable in this engine"
+        )
+
+    prices = prices.sort_index()
+    output.validate(prices.index)
+    shifted = _shift_decisions(output)
+    if not shifted.shifted:
+        raise EngineError("internal: decisions were not shifted")
+
+    bpy = bars_per_year if bars_per_year is not None else config.bars_per_year(
+        cfg.asset, cfg.timeframe
+    )
+    plan = build_validation_plan(prices.index, cfg.validation)
+
+    size, size_type = _size_args(prices, cfg.sizing)
+    slippage = _slippage_arg(prices, cfg.costs)
+
+    kwargs = dict(
+        close=prices["close"],
+        entries=shifted.entries,
+        exits=shifted.exits,
+        price=prices["open"],  # next-bar-open execution
+        open=prices["open"], high=prices["high"], low=prices["low"],
+        fees=cfg.costs.commission_rate,
+        slippage=slippage,
+        init_cash=cfg.init_cash,
+        size=size, size_type=size_type,
+        freq=pd.infer_freq(prices.index) or f"{config.TIMEFRAMES[cfg.timeframe].minutes}min",
+        direction=cfg.direction,
+        seed=0,  # determinism
+    )
+    if shifted.short_entries is not None:
+        kwargs["short_entries"] = shifted.short_entries
+        kwargs["short_exits"] = shifted.short_exits
+        kwargs["direction"] = "both"
+    if cfg.stops.sl_pct is not None:
+        kwargs["sl_stop"] = cfg.stops.sl_pct
+    if cfg.stops.trail_pct is not None:
+        kwargs["sl_stop"] = cfg.stops.trail_pct
+        kwargs["sl_trail"] = True
+    if cfg.stops.tp_pct is not None:
+        kwargs["tp_stop"] = cfg.stops.tp_pct
+
+    pf = vbt.Portfolio.from_signals(**kwargs)
+
+    equity = pf.value()
+    try:
+        position = pf.asset_flow().cumsum()
+    except Exception:
+        position = pd.Series(0.0, index=prices.index)
+
+    trades = _build_trades(pf, prices, shifted.triggers, cfg, plan)
+
+    # Benchmark: buy and hold the same asset, same costs-free basis, so the
+    # comparison isolates the strategy rather than the fee schedule.
+    bench = prices["close"] / prices["close"].iloc[0] * cfg.init_cash
+
+    def slice_metrics(mask: pd.Series, seg: str) -> Metrics:
+        eq = equity[mask]
+        if len(eq) < 2:
+            return Metrics(segment=seg)
+        tr = trades[trades["segment"] == seg] if len(trades) else trades
+        return compute_metrics(eq, tr, bpy, segment=seg,
+                               position=position[mask] if position is not None else None)
+
+    holdout_mask = plan.holdout_mask
+    in_holdout = holdout_mask.to_numpy()
+    if plan.is_end is not None:
+        is_mask = pd.Series((prices.index <= plan.is_end) & ~in_holdout, index=prices.index)
+        oos_mask = pd.Series((prices.index > plan.is_end) & ~in_holdout, index=prices.index)
+    else:
+        seg = pd.Series([plan.segment_of(t) for t in prices.index], index=prices.index)
+        is_mask = (seg == "IS") & ~in_holdout
+        oos_mask = (seg == "OOS") & ~in_holdout
+
+    metrics_all = compute_metrics(equity, trades, bpy, segment="all", position=position)
+    metrics_is = slice_metrics(is_mask, "IS")
+    metrics_oos = slice_metrics(oos_mask, "OOS")
+    metrics_holdout = slice_metrics(holdout_mask, "holdout") if in_holdout.any() else None
+
+    windows: list[WindowResult] = []
+    for w in plan.windows:
+        m = (prices.index >= w.test_start) & (prices.index <= w.test_end)
+        eq = equity[m]
+        if len(eq) < 2:
+            continue
+        tr = trades[(trades["entry_ts"] >= w.test_start)
+                    & (trades["entry_ts"] <= w.test_end)] if len(trades) else trades
+        windows.append(WindowResult(
+            window=w,
+            metrics=compute_metrics(eq, tr, bpy, segment=f"W{w.idx + 1}"),
+            equity=eq,
+        ))
+
+    return BacktestResult(
+        config=cfg, equity=equity, benchmark_equity=bench, position=position,
+        trades=trades, metrics_all=metrics_all, metrics_is=metrics_is,
+        metrics_oos=metrics_oos, metrics_holdout=metrics_holdout, plan=plan,
+        windows=windows, prices=prices, fingerprint=cfg.fingerprint(),
+        elapsed_s=time.perf_counter() - t0,
+    )

src/extension.py

@@ -0,0 +1,385 @@
+"""User-funded coverage extension and add-model, on ZeroGPU.
+
+Inference runs inside a `@spaces.GPU` function so it draws on the *signed-in
+user's* ZeroGPU quota, not the Space owner's. Anonymous visitors keep full read
+and backtest access; only extension is gated.
+
+Safety properties enforced here:
+
+* **Dedup** — a range the manifest already covers is never recomputed.
+* **Caps** — per-request range limits keep one user from monopolising the queue.
+* **Single writer** — a process-wide lock serialises commits, so concurrent
+  extensions cannot interleave and corrupt the manifest.
+* **Allow-list** — only vetted adapter families load, and model ids are
+  validated before they reach the Hub.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import threading
+from dataclasses import dataclass
+
+import gradio as gr
+import pandas as pd
+
+from . import comparisons, config, runtime
+from .adapters import AdapterError, ModelNotAllowed, build_windows, get_adapter, validate_model_id
+from .store import _utc
+
+log = logging.getLogger("bit.extension")
+
+# One writer at a time. Commits to the store are serialised process-wide so a
+# second extension cannot land between another's data write and its manifest
+# update.
+_WRITE_LOCK = threading.Lock()
+
+try:
+    import spaces  # provided by the ZeroGPU runtime
+    HAS_SPACES = True
+except Exception:  # running locally or on CPU-only hardware
+    spaces = None
+    HAS_SPACES = False
+
+
+def _gpu(duration=120):
+    """Apply @spaces.GPU when the runtime offers it, otherwise run on CPU."""
+    def deco(fn):
+        if HAS_SPACES:
+            return spaces.GPU(duration=duration)(fn)
+        return fn
+    return deco
+
+
+class ExtensionError(RuntimeError):
+    pass
+
+
+class QuotaExhausted(ExtensionError):
+    pass
+
+
+# --------------------------------------------------------------------------
+# Estimation & guardrails
+# --------------------------------------------------------------------------
+
+
+@dataclass
+class Estimate:
+    model_slug: str
+    asset: str
+    timeframe: str
+    start: pd.Timestamp
+    end: pd.Timestamp
+    steps: int
+    already_covered: bool
+    capped: bool
+    cap_days: int
+    note: str = ""
+
+
+def estimate(model_slug: str, asset: str, timeframe: str, start, end) -> Estimate:
+    if model_slug not in config.SEED_MODELS:
+        raise ExtensionError(f"unknown model {model_slug!r}")
+    if asset not in config.ASSETS:
+        raise ExtensionError(f"unknown asset {asset!r}")
+    if timeframe not in config.TIMEFRAMES:
+        raise ExtensionError(f"unknown timeframe {timeframe!r}")
+
+    try:
+        s, e = _utc(start), _utc(end)
+    except Exception as exc:
+        raise ExtensionError(f"could not parse the date range: {exc}") from exc
+    if s >= e:
+        raise ExtensionError("start must be before end")
+
+    cap_days = config.CAPS.max_days.get(timeframe, 365)
+    capped = (e - s).days > cap_days
+    if capped:
+        s = e - pd.Timedelta(days=cap_days)
+
+    store = runtime.get_store()
+    prices = store.get_prices(asset, timeframe, s, e)
+    if prices.empty:
+        raise ExtensionError(
+            f"No cached prices for {asset} {timeframe} in that range. "
+            "Price coverage has to exist before signals can be generated."
+        )
+
+    spec = config.SEED_MODELS[model_slug]
+    ctx = min(spec.context_len, max(64, len(prices) // 3))
+    steps = max(0, len(prices) - ctx)
+    if steps > config.CAPS.max_steps_per_run:
+        steps = config.CAPS.max_steps_per_run
+
+    # Dedup must compare against the range this request would actually
+    # *produce*, not the range the user typed. A forecast needs a full trailing
+    # context window, so the first producible timestamp sits `ctx` bars after
+    # the start of the price slice. Comparing the typed range instead would
+    # report an already-covered slice as uncovered and pay for it twice.
+    stamps, _ = build_windows(prices["close"], ctx)
+    if len(stamps) == 0:
+        produced_start, produced_end = s, e
+        steps = 0
+    else:
+        produced_start = _utc(stamps[0])
+        produced_end = _utc(stamps[min(steps, len(stamps)) - 1]) if steps else produced_start
+
+    # Revision is resolved lazily to avoid a Hub round-trip on every keystroke,
+    # so this matches any revision of the model.
+    covered = any(
+        ent.model_slug == model_slug and ent.asset == asset
+        and ent.timeframe == timeframe
+        and _utc(ent.start_ts) <= produced_start and _utc(ent.end_ts) >= produced_end
+        for ent in store.load_manifest().signals.values()
+    )
+
+    note = ""
+    if capped:
+        note = (f"Range trimmed to the {cap_days}-day cap for {timeframe} bars.")
+    return Estimate(model_slug, asset, timeframe, s, e, steps, covered,
+                    capped, cap_days, note)
+
+
+# --------------------------------------------------------------------------
+# GPU inference
+# --------------------------------------------------------------------------
+
+
+@_gpu(duration=180)
+def run_inference(model_id: str, family: str, values: list, ctx_len: int) -> dict:
+    """Inference on the caller's ZeroGPU allocation.
+
+    Kept deliberately small and picklable: it takes plain values and returns
+    plain lists, so nothing in the store or the app leaks into the GPU worker.
+    """
+    import numpy as np
+
+    adapter = get_adapter(family, model_id, context_len=ctx_len)
+    adapter.load()
+    windows = np.asarray(values, dtype="float32")
+    forecast = adapter.predict(windows)
+    return {
+        "q10": forecast.q10.tolist(),
+        "q50": forecast.q50.tolist(),
+        "q90": forecast.q90.tolist(),
+        "context_len": int(forecast.context_len),
+        "revision": adapter.resolved_revision,
+        "inference_version": adapter.inference_version(),
+    }
+
+
+def _is_quota_error(exc: Exception) -> bool:
+    text = f"{type(exc).__name__} {exc}".lower()
+    return any(k in text for k in ("quota", "gpu task aborted", "exceeded",
+                                   "no gpu available", "zerogpu"))
+
+
+QUOTA_FALLBACK = (
+    '<div class="bit-note bit-note-danger">'
+    "Your ZeroGPU quota is exhausted, so this extension could not run. "
+    "The quota refills over time. If you need to run a large batch now, "
+    f'<a href="https://huggingface.co/spaces/{config.SPACE_REPO}?duplicate=true" '
+    'target="_blank" rel="noopener">duplicate this Space</a> and run it on your '
+    "own hardware — the signal store is public, so a duplicate reads the same data."
+    "</div>"
+)
+
+
+# --------------------------------------------------------------------------
+# The extend flow
+# --------------------------------------------------------------------------
+
+
+def extend_coverage(model_slug: str, asset: str, timeframe: str, start, end,
+                    username: str = "anonymous", progress=None) -> str:
+    """Dedup, estimate, run inference, commit, regenerate comparisons."""
+    est = estimate(model_slug, asset, timeframe, start, end)
+    if est.already_covered:
+        return ('<div class="bit-note">That range is already covered — nothing was '
+                "recomputed. Coverage is deduplicated against the manifest.</div>")
+    if est.steps <= 0:
+        return ('<div class="bit-note bit-note-danger">Not enough cached price '
+                "history in that range to build a single context window.</div>")
+
+    spec = config.SEED_MODELS[model_slug]
+    store = runtime.get_store()
+    prices = store.get_prices(asset, timeframe, est.start, est.end)
+    close = prices["close"]
+    ctx = min(spec.context_len, max(64, len(prices) // 3))
+
+    if progress:
+        progress(0.15, desc=f"Preparing {est.steps} context windows")
+    stamps, windows = build_windows(close, ctx)
+    if len(stamps) == 0:
+        return ('<div class="bit-note bit-note-danger">Not enough bars for a '
+                "context window.</div>")
+    stamps, windows = stamps[:est.steps], windows[:est.steps]
+
+    if progress:
+        progress(0.35, desc=f"Running {spec.display} on your GPU quota")
+    try:
+        out = run_inference(spec.model_id, spec.family, windows.tolist(), ctx)
+    except Exception as exc:
+        if _is_quota_error(exc):
+            log.warning("ZeroGPU quota exhausted for %s: %s", username, exc)
+            return QUOTA_FALLBACK
+        log.exception("extension inference failed")
+        return (f'<div class="bit-note bit-note-danger">Inference failed: '
+                f"{type(exc).__name__}: {exc}</div>")
+
+    frame = pd.DataFrame({
+        "ts": stamps, "q10": out["q10"], "q50": out["q50"], "q90": out["q90"],
+        "context_len": out["context_len"], "inference_version": out["inference_version"],
+    })
+
+    if progress:
+        progress(0.75, desc="Committing to the signal store")
+    with _WRITE_LOCK:
+        entry = store.write_signals(
+            model_slug, spec.model_id, out["revision"], asset, timeframe, frame,
+            inference_version=out["inference_version"],
+            contributed_by=username,
+        )
+        if progress:
+            progress(0.9, desc="Regenerating comparison tables")
+        try:
+            comparisons.regenerate(store, assets=[asset])
+        except Exception:
+            log.exception("comparison regeneration failed (coverage still written)")
+        oid = store.flush(f"Extend {model_slug}/{asset}/{timeframe} by @{username}")
+
+    runtime.cache_clear()
+    return (f'<div class="bit-note">Coverage extended by <b>@{username}</b> — '
+            f"{len(frame):,} new steps for {model_slug} on {asset} {timeframe} "
+            f"({entry.start_ts[:10]} → {entry.end_ts[:10]})."
+            + (f" Commit <code>{str(oid)[:8]}</code>." if oid else "")
+            + "</div>")
+
+
+def add_model(family: str, model_id: str, username: str = "anonymous") -> str:
+    """Smoke-test a user-supplied model, then register it if it passes."""
+    try:
+        model_id = validate_model_id(model_id)
+    except AdapterError as e:
+        return f'<div class="bit-note bit-note-danger">{e}</div>'
+    if family not in config.ALLOWED_ADAPTER_FAMILIES:
+        return (f'<div class="bit-note bit-note-danger">Adapter family {family!r} '
+                "is not on the allow-list.</div>")
+
+    store = runtime.get_store()
+    asset, timeframe = "BTC-USD", "1d"
+    prices = store.get_prices(asset, timeframe)
+    if prices.empty:
+        return ('<div class="bit-note bit-note-danger">No cached prices to smoke '
+                "test against.</div>")
+
+    n = config.CAPS.smoke_test_steps
+    close = prices["close"]
+    ctx = min(512, max(64, len(close) // 3))
+    stamps, windows = build_windows(close, ctx)
+    if len(stamps) < n:
+        return ('<div class="bit-note bit-note-danger">Not enough history for a '
+                f"{n}-step smoke test.</div>")
+    stamps, windows = stamps[-n:], windows[-n:]
+
+    try:
+        out = run_inference(model_id, family, windows.tolist(), ctx)
+    except ModelNotAllowed as e:
+        return f'<div class="bit-note bit-note-danger">{e}</div>'
+    except Exception as exc:
+        if _is_quota_error(exc):
+            return QUOTA_FALLBACK
+        return (f'<div class="bit-note bit-note-danger">Smoke test failed: '
+                f"{type(exc).__name__}: {exc}</div>")
+
+    slug = model_id.split("/")[-1].lower()
+    frame = pd.DataFrame({
+        "ts": stamps, "q10": out["q10"], "q50": out["q50"], "q90": out["q90"],
+        "context_len": out["context_len"], "inference_version": out["inference_version"],
+    })
+    with _WRITE_LOCK:
+        store.write_signals(slug, model_id, out["revision"], asset, timeframe, frame,
+                            inference_version=out["inference_version"],
+                            contributed_by=username)
+        store.flush(f"Add model {model_id} (smoke test) by @{username}")
+    runtime.cache_clear()
+
+    return (f'<div class="bit-note">Smoke test passed: <b>{model_id}</b> '
+            f"(revision <code>{str(out['revision'])[:8]}</code>) produced {n} "
+            f"schema-valid steps and now appears in the coverage map as "
+            f"<code>{slug}</code>.</div>")
+
+
+# --------------------------------------------------------------------------
+# Gradio bindings
+# --------------------------------------------------------------------------
+
+
+def status_html() -> str:
+    if HAS_SPACES:
+        return ('<div class="bit-micro">ZEROGPU AVAILABLE · EXTENSION RUNS ON '
+                "YOUR OWN QUOTA WHEN SIGNED IN</div>")
+    return ('<div class="bit-note">This Space is running on CPU, so coverage '
+            "extension is disabled. Reading and backtesting the existing store "
+            "works normally.</div>")
+
+
+def _username(profile) -> str | None:
+    if profile is None:
+        return None
+    return getattr(profile, "username", None) or getattr(profile, "name", None)
+
+
+def estimate_ui(model_slug, asset, timeframe, start, end):
+    if not (model_slug and asset and timeframe and start and end):
+        return '<div class="bit-micro">PICK A MODEL, ASSET, TIMEFRAME AND RANGE</div>'
+    try:
+        est = estimate(model_slug, asset, timeframe, start, end)
+    except ExtensionError as e:
+        return f'<div class="bit-note bit-note-danger">{e}</div>'
+    if est.already_covered:
+        return ('<div class="bit-note">Already covered — running this would '
+                "recompute nothing. Pick a wider range.</div>")
+    return (f'<div class="bit-note">About <b>{est.steps:,}</b> inference steps for '
+            f"{est.start.date()} → {est.end.date()}. "
+            + (est.note + " " if est.note else "")
+            + "This runs on your ZeroGPU quota once you sign in.</div>")
+
+
+def extend_ui(model_slug, asset, timeframe, start, end,
+              profile: gr.OAuthProfile | None = None, progress=None):
+    user = _username(profile)
+    if user is None:
+        return ('<div class="bit-note bit-note-danger">Sign in with Hugging Face to '
+                "extend coverage. Reading and backtesting stay open to everyone; "
+                "extension spends your own GPU quota, so it needs an account.</div>",
+                runtime.coverage_frame())
+    if not HAS_SPACES:
+        return (status_html(), runtime.coverage_frame())
+    try:
+        html = extend_coverage(model_slug, asset, timeframe, start, end,
+                               username=user, progress=progress)
+    except ExtensionError as e:
+        html = f'<div class="bit-note bit-note-danger">{e}</div>'
+    except Exception as e:
+        log.exception("extend failed")
+        html = f'<div class="bit-note bit-note-danger">{type(e).__name__}: {e}</div>'
+    return html, runtime.coverage_frame()
+
+
+def add_model_ui(family, model_id, profile: gr.OAuthProfile | None = None):
+    user = _username(profile)
+    if user is None:
+        return ('<div class="bit-note bit-note-danger">Sign in with Hugging Face to '
+                "add a model — the smoke test runs on your GPU quota.</div>",
+                runtime.coverage_frame())
+    if not HAS_SPACES:
+        return (status_html(), runtime.coverage_frame())
+    try:
+        html = add_model(family, model_id, username=user)
+    except Exception as e:
+        log.exception("add model failed")
+        html = f'<div class="bit-note bit-note-danger">{type(e).__name__}: {e}</div>'
+    return html, runtime.coverage_frame()

src/metrics.py

@@ -0,0 +1,263 @@
+"""Performance metrics, computed from the equity curve and trade list.
+
+Every number the UI shows comes from this module, so each one is traceable to
+an equity curve or a trade row rather than to a library's internal accounting.
+Metrics are pure functions of their inputs -- no globals, no randomness.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, asdict, field
+
+import numpy as np
+import pandas as pd
+
+TRADING_DAYS = 252.0
+
+
+@dataclass
+class Metrics:
+    """One performance summary. `segment` names the slice it describes."""
+
+    segment: str = "all"
+    start_ts: str | None = None
+    end_ts: str | None = None
+    bars: int = 0
+
+    total_return: float = 0.0
+    cagr: float = 0.0
+    sharpe: float = 0.0
+    sortino: float = 0.0
+    max_drawdown: float = 0.0
+    volatility: float = 0.0
+
+    win_rate: float = 0.0
+    profit_factor: float = 0.0
+    exposure: float = 0.0
+    trade_count: int = 0
+
+    avg_win: float = 0.0
+    avg_loss: float = 0.0
+    avg_r: float = 0.0
+    best_trade: float = 0.0
+    worst_trade: float = 0.0
+    costs_paid: float = 0.0
+    gross_pnl: float = 0.0
+    net_pnl: float = 0.0
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+def _clean_returns(equity: pd.Series) -> pd.Series:
+    r = equity.astype("float64").pct_change()
+    return r.replace([np.inf, -np.inf], np.nan).dropna()
+
+
+def total_return(equity: pd.Series) -> float:
+    if len(equity) < 2 or equity.iloc[0] == 0:
+        return 0.0
+    return float(equity.iloc[-1] / equity.iloc[0] - 1.0)
+
+
+def cagr(equity: pd.Series, bars_per_year: float) -> float:
+    if len(equity) < 2 or equity.iloc[0] <= 0 or equity.iloc[-1] <= 0:
+        return 0.0
+    years = (len(equity) - 1) / bars_per_year
+    if years <= 0:
+        return 0.0
+    return float((equity.iloc[-1] / equity.iloc[0]) ** (1.0 / years) - 1.0)
+
+
+def sharpe(equity: pd.Series, bars_per_year: float, rf: float = 0.0) -> float:
+    r = _clean_returns(equity)
+    if len(r) < 2:
+        return 0.0
+    excess = r - (rf / bars_per_year)
+    sd = float(excess.std(ddof=1))
+    if sd == 0 or not math.isfinite(sd):
+        return 0.0
+    return float(excess.mean() / sd * math.sqrt(bars_per_year))
+
+
+def sortino(equity: pd.Series, bars_per_year: float, rf: float = 0.0) -> float:
+    r = _clean_returns(equity)
+    if len(r) < 2:
+        return 0.0
+    excess = r - (rf / bars_per_year)
+    downside = excess[excess < 0]
+    if len(downside) == 0:
+        return 0.0
+    dd = float(np.sqrt((downside ** 2).mean()))
+    if dd == 0 or not math.isfinite(dd):
+        return 0.0
+    return float(excess.mean() / dd * math.sqrt(bars_per_year))
+
+
+def volatility(equity: pd.Series, bars_per_year: float) -> float:
+    r = _clean_returns(equity)
+    if len(r) < 2:
+        return 0.0
+    return float(r.std(ddof=1) * math.sqrt(bars_per_year))
+
+
+def drawdown_series(equity: pd.Series) -> pd.Series:
+    if equity.empty:
+        return equity
+    peak = equity.cummax()
+    return equity / peak - 1.0
+
+
+def max_drawdown(equity: pd.Series) -> float:
+    if len(equity) < 2:
+        return 0.0
+    dd = drawdown_series(equity)
+    return float(dd.min()) if len(dd) else 0.0
+
+
+def rolling_sharpe(equity: pd.Series, window: int, bars_per_year: float) -> pd.Series:
+    r = _clean_returns(equity)
+    if len(r) < window:
+        return pd.Series(dtype="float64", index=pd.DatetimeIndex([], tz="UTC"))
+    mean = r.rolling(window).mean()
+    sd = r.rolling(window).std(ddof=1)
+    out = (mean / sd.replace(0.0, np.nan)) * math.sqrt(bars_per_year)
+    return out.dropna()
+
+
+def underwater(equity: pd.Series) -> pd.Series:
+    return drawdown_series(equity)
+
+
+def exposure(position: pd.Series) -> float:
+    """Fraction of bars holding a non-zero position."""
+    if position is None or len(position) == 0:
+        return 0.0
+    return float((position.abs() > 1e-12).mean())
+
+
+# --------------------------------------------------------------------------
+# Trade-derived statistics
+# --------------------------------------------------------------------------
+
+
+def trade_stats(trades: pd.DataFrame) -> dict:
+    """Win rate, profit factor and friends from the trade list."""
+    empty = {
+        "trade_count": 0, "win_rate": 0.0, "profit_factor": 0.0,
+        "avg_win": 0.0, "avg_loss": 0.0, "avg_r": 0.0,
+        "best_trade": 0.0, "worst_trade": 0.0,
+        "costs_paid": 0.0, "gross_pnl": 0.0, "net_pnl": 0.0,
+    }
+    if trades is None or trades.empty:
+        return empty
+
+    net = trades["net_pnl"].astype("float64")
+    wins = net[net > 0]
+    losses = net[net < 0]
+    gross_profit = float(wins.sum())
+    gross_loss = float(-losses.sum())
+
+    if gross_loss > 0:
+        pf = gross_profit / gross_loss
+    elif gross_profit > 0:
+        pf = float("inf")
+    else:
+        pf = 0.0
+
+    r_vals = trades["r_multiple"].replace([np.inf, -np.inf], np.nan).dropna() \
+        if "r_multiple" in trades.columns else pd.Series(dtype="float64")
+
+    return {
+        "trade_count": int(len(trades)),
+        "win_rate": float(len(wins) / len(net)) if len(net) else 0.0,
+        "profit_factor": float(pf),
+        "avg_win": float(wins.mean()) if len(wins) else 0.0,
+        "avg_loss": float(losses.mean()) if len(losses) else 0.0,
+        "avg_r": float(r_vals.mean()) if len(r_vals) else 0.0,
+        "best_trade": float(net.max()),
+        "worst_trade": float(net.min()),
+        "costs_paid": float(trades["costs"].sum()) if "costs" in trades.columns else 0.0,
+        "gross_pnl": float(trades["gross_pnl"].sum()) if "gross_pnl" in trades.columns else 0.0,
+        "net_pnl": float(net.sum()),
+    }
+
+
+def compute_metrics(
+    equity: pd.Series,
+    trades: pd.DataFrame | None,
+    bars_per_year: float,
+    *,
+    segment: str = "all",
+    position: pd.Series | None = None,
+) -> Metrics:
+    """Assemble the full metric set for one equity slice."""
+    equity = equity.dropna()
+    m = Metrics(
+        segment=segment,
+        start_ts=str(equity.index[0]) if len(equity) else None,
+        end_ts=str(equity.index[-1]) if len(equity) else None,
+        bars=int(len(equity)),
+        total_return=total_return(equity),
+        cagr=cagr(equity, bars_per_year),
+        sharpe=sharpe(equity, bars_per_year),
+        sortino=sortino(equity, bars_per_year),
+        max_drawdown=max_drawdown(equity),
+        volatility=volatility(equity, bars_per_year),
+        exposure=exposure(position) if position is not None else 0.0,
+    )
+    for k, v in trade_stats(trades).items():
+        setattr(m, k, v)
+    return m
+
+
+# --------------------------------------------------------------------------
+# Forecast quality (used by comparisons/ in Phase 2)
+# --------------------------------------------------------------------------
+
+
+def calibration_coverage(
+    actual: pd.Series, lower: pd.Series, upper: pd.Series
+) -> float:
+    """Empirical coverage: share of actuals inside [lower, upper].
+
+    A well-calibrated q10-q90 band should cover ~0.80 of outcomes.
+    """
+    df = pd.concat([actual, lower, upper], axis=1).dropna()
+    if df.empty:
+        return float("nan")
+    a, lo, hi = df.iloc[:, 0], df.iloc[:, 1], df.iloc[:, 2]
+    return float(((a >= lo) & (a <= hi)).mean())
+
+
+def calibration_error(coverage: float, nominal: float = 0.80) -> float:
+    """Signed miss against the nominal band width. 0.0 is perfect."""
+    if not math.isfinite(coverage):
+        return float("nan")
+    return float(coverage - nominal)
+
+
+def directional_accuracy(actual_next: pd.Series, predicted_next: pd.Series,
+                         reference: pd.Series) -> float:
+    """Share of bars where the predicted direction matched the realised one."""
+    df = pd.concat([actual_next, predicted_next, reference], axis=1).dropna()
+    if df.empty:
+        return float("nan")
+    a, p, ref = df.iloc[:, 0], df.iloc[:, 1], df.iloc[:, 2]
+    actual_dir = np.sign(a - ref)
+    pred_dir = np.sign(p - ref)
+    mask = actual_dir != 0
+    if not mask.any():
+        return float("nan")
+    return float((actual_dir[mask] == pred_dir[mask]).mean())
+
+
+def pinball_loss(actual: pd.Series, pred: pd.Series, q: float) -> float:
+    """Quantile (pinball) loss -- lower is better."""
+    df = pd.concat([actual, pred], axis=1).dropna()
+    if df.empty:
+        return float("nan")
+    a, p = df.iloc[:, 0], df.iloc[:, 1]
+    diff = a - p
+    return float(np.maximum(q * diff, (q - 1) * diff).mean())

src/runtime.py

@@ -0,0 +1,480 @@
+"""App runtime: cached store access, run execution, run history, share links.
+
+Hub I/O is cached in-process behind an LRU so a repeated backtest never
+re-downloads a parquet slice. The cache key includes the store's manifest
+`updated_at`, so a coverage extension invalidates exactly the slices that
+changed instead of serving stale data forever.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import logging
+import os
+import threading
+import time
+import uuid
+from dataclasses import dataclass, field, asdict
+from datetime import datetime, timezone
+
+import pandas as pd
+
+from . import comparisons, config, strategies
+from .engine import (
+    BacktestConfig,
+    Costs,
+    Sizing,
+    Stops,
+    Validation,
+    BacktestResult,
+    run_backtest,
+)
+from .store import SignalStore
+
+log = logging.getLogger("bit.runtime")
+
+_store: SignalStore | None = None
+_store_lock = threading.Lock()
+
+
+def get_store() -> SignalStore:
+    """Process-wide store handle. Read-only for anonymous user traffic."""
+    global _store
+    with _store_lock:
+        if _store is None:
+            token = os.environ.get("HF_WRITE_TOKEN") or os.environ.get("HF_TOKEN")
+            _store = SignalStore(
+                repo_id=config.STORE_REPO,
+                local_root=os.environ.get("BIT_STORE_CACHE", ".cache/store"),
+                token=token,
+            )
+        return _store
+
+
+# --------------------------------------------------------------------------
+# Cached slice access
+# --------------------------------------------------------------------------
+
+_slice_cache: dict[tuple, pd.DataFrame] = {}
+_cache_order: list[tuple] = []
+_cache_lock = threading.Lock()
+
+
+def _cache_get(key):
+    with _cache_lock:
+        hit = _slice_cache.get(key)
+        if hit is not None:
+            _cache_order.remove(key)
+            _cache_order.append(key)
+        return hit
+
+
+def _cache_put(key, value):
+    with _cache_lock:
+        _slice_cache[key] = value
+        _cache_order.append(key)
+        while len(_cache_order) > config.PARQUET_CACHE_SIZE:
+            old = _cache_order.pop(0)
+            _slice_cache.pop(old, None)
+
+
+def cache_clear() -> None:
+    with _cache_lock:
+        _slice_cache.clear()
+        _cache_order.clear()
+
+
+def _manifest_stamp() -> str:
+    try:
+        return get_store().load_manifest().updated_at
+    except Exception:
+        return "unknown"
+
+
+def load_prices(asset: str, timeframe: str, start=None, end=None) -> pd.DataFrame:
+    key = ("px", asset, timeframe, str(start), str(end), _manifest_stamp())
+    hit = _cache_get(key)
+    if hit is not None:
+        return hit
+    df = get_store().get_prices(asset, timeframe, start, end)
+    _cache_put(key, df)
+    return df
+
+
+def load_signals(model_slug: str, asset: str, timeframe: str,
+                 start=None, end=None) -> pd.DataFrame:
+    if not model_slug:
+        return pd.DataFrame()
+    key = ("sig", model_slug, asset, timeframe, str(start), str(end), _manifest_stamp())
+    hit = _cache_get(key)
+    if hit is not None:
+        return hit
+    df = get_store().get_signals(model_slug, asset, timeframe, start, end)
+    _cache_put(key, df)
+    return df
+
+
+# --------------------------------------------------------------------------
+# Coverage map
+# --------------------------------------------------------------------------
+
+
+@dataclass
+class CoverageCell:
+    model_slug: str
+    asset: str
+    timeframe: str
+    start: str
+    end: str
+    rows: int
+    is_placeholder: bool
+    contributed_by: str
+
+
+def coverage_map() -> list[CoverageCell]:
+    m = get_store().load_manifest()
+    return [
+        CoverageCell(
+            model_slug=e.model_slug, asset=e.asset, timeframe=e.timeframe,
+            start=e.start_ts[:10], end=e.end_ts[:10], rows=e.rows,
+            is_placeholder=e.is_placeholder, contributed_by=e.contributed_by,
+        )
+        for e in sorted(m.signals.values(),
+                        key=lambda x: (x.model_slug, x.asset, x.timeframe))
+    ]
+
+
+def coverage_frame() -> pd.DataFrame:
+    cells = coverage_map()
+    if not cells:
+        return pd.DataFrame(columns=["Model", "Asset", "TF", "Coverage", "Rows",
+                                     "Source", "Real?"])
+    return pd.DataFrame([{
+        "Model": c.model_slug, "Asset": c.asset, "TF": c.timeframe,
+        "Coverage": f"{c.start} → {c.end}", "Rows": f"{c.rows:,}",
+        "Source": c.contributed_by,
+        "Real?": "PLACEHOLDER" if c.is_placeholder else "real",
+    } for c in cells])
+
+
+def available_models(asset: str | None = None, timeframe: str | None = None) -> list[str]:
+    m = get_store().load_manifest()
+    return sorted({e.model_slug for e in m.find_signals(asset=asset, timeframe=timeframe)})
+
+
+def available_assets() -> list[str]:
+    m = get_store().load_manifest()
+    found = sorted({p.asset for p in m.prices.values()})
+    return found or list(config.ASSETS)
+
+
+def price_coverage_for(asset: str, timeframe: str) -> tuple[str, str] | None:
+    cov = get_store().load_manifest().prices.get(f"{asset}|{timeframe}")
+    return (cov.start_ts[:10], cov.end_ts[:10]) if cov else None
+
+
+# --------------------------------------------------------------------------
+# Run configuration
+# --------------------------------------------------------------------------
+
+RANGE_YEARS = {"1Y": 1.0, "3Y": 3.0, "5Y": 5.0, "Max": 99.0}
+
+
+@dataclass
+class RunRequest:
+    """Everything the Strategy Builder collects, in one serialisable object."""
+
+    strategy: str = "SMA Crossover"
+    asset: str = "BTC-USD"
+    timeframe: str = "1d"
+    date_range: str = "3Y"
+    model_slug: str = ""
+    params: dict = field(default_factory=dict)
+
+    costs_on: bool = True
+    commission_bps: float = config.DEFAULT_COMMISSION_BPS
+    slippage_bps: float = config.DEFAULT_SLIPPAGE_BPS
+    slippage_model: str = "fixed"
+
+    sizing_mode: str = "fixed_pct"
+    size_pct: float = 1.0
+    leverage: float = 1.0
+    max_position: float = 1.0
+
+    sl_pct: float | None = None
+    tp_pct: float | None = None
+    trail_pct: float | None = None
+
+    validation_mode: str = "walk_forward"
+    train_months: int = 12
+    test_months: int = 3
+    roll_months: int = 3
+    holdout_months: int = 6
+
+    def to_config(self) -> BacktestConfig:
+        return BacktestConfig(
+            asset=self.asset, timeframe=self.timeframe, strategy=self.strategy,
+            params=dict(self.params),
+            costs=Costs(enabled=self.costs_on, commission_bps=self.commission_bps,
+                        slippage_bps=self.slippage_bps, slippage_model=self.slippage_model),
+            sizing=Sizing(mode=self.sizing_mode, pct=self.size_pct,
+                          leverage=self.leverage, max_position=self.max_position),
+            stops=Stops(sl_pct=self.sl_pct, tp_pct=self.tp_pct, trail_pct=self.trail_pct),
+            validation=Validation(mode=self.validation_mode, train_months=self.train_months,
+                                  test_months=self.test_months, roll_months=self.roll_months,
+                                  holdout_months=self.holdout_months),
+        )
+
+    # -- share links ------------------------------------------------------
+
+    def encode(self) -> str:
+        raw = json.dumps(asdict(self), sort_keys=True, separators=(",", ":"))
+        return base64.urlsafe_b64encode(raw.encode()).decode().rstrip("=")
+
+    @classmethod
+    def decode(cls, token: str) -> "RunRequest":
+        pad = "=" * (-len(token) % 4)
+        raw = base64.urlsafe_b64decode(token + pad).decode()
+        data = json.loads(raw)
+        known = {k: v for k, v in data.items() if k in cls.__dataclass_fields__}
+        req = cls(**known)
+        req.validate()
+        return req
+
+    def validate(self) -> None:
+        """Reject anything a share link could smuggle in."""
+        if self.strategy not in strategies.PRESETS:
+            raise ValueError(f"unknown strategy {self.strategy!r}")
+        if self.asset not in config.ASSETS:
+            raise ValueError(f"unknown asset {self.asset!r}")
+        if self.timeframe not in config.TIMEFRAMES:
+            raise ValueError(f"unknown timeframe {self.timeframe!r}")
+        if self.validation_mode not in ("none", "split", "walk_forward", "holdout"):
+            raise ValueError(f"unknown validation mode {self.validation_mode!r}")
+        if self.slippage_model not in ("fixed", "volume_scaled"):
+            raise ValueError(f"unknown slippage model {self.slippage_model!r}")
+        if self.sizing_mode not in ("fixed_pct", "vol_target", "fixed_units"):
+            raise ValueError(f"unknown sizing mode {self.sizing_mode!r}")
+        if not isinstance(self.params, dict):
+            raise ValueError("params must be an object")
+        for k in self.params:
+            if not isinstance(k, str) or not k.replace("_", "").isalnum():
+                raise ValueError(f"bad parameter name {k!r}")
+
+
+# --------------------------------------------------------------------------
+# Execution
+# --------------------------------------------------------------------------
+
+
+@dataclass
+class RunRecord:
+    run_id: str
+    label: str
+    request: RunRequest
+    result: BacktestResult
+    created_at: str
+    elapsed_s: float
+
+    @property
+    def sharpe(self) -> float:
+        return self.result.metrics_oos.sharpe or self.result.metrics_all.sharpe
+
+    @property
+    def meta(self) -> str:
+        r = self.request
+        mode = {"walk_forward": "WF", "holdout": "HOLDOUT",
+                "split": "SPLIT", "none": "—"}.get(r.validation_mode, r.validation_mode)
+        return f"{r.timeframe} · {r.date_range} · {mode}"
+
+
+class RunError(RuntimeError):
+    pass
+
+
+def window_for(asset: str, timeframe: str, date_range: str):
+    cov = price_coverage_for(asset, timeframe)
+    if cov is None:
+        raise RunError(
+            f"No cached price coverage for {asset} {timeframe}. "
+            "Pick another pair, or extend coverage."
+        )
+    start_cov, end_cov = pd.Timestamp(cov[0], tz="UTC"), pd.Timestamp(cov[1], tz="UTC")
+    years = RANGE_YEARS.get(date_range, 3.0)
+    start = max(start_cov, end_cov - pd.Timedelta(days=int(365 * years)))
+    return start, end_cov
+
+
+def execute(req: RunRequest) -> RunRecord:
+    """Run one backtest against cached data only. Never touches a provider."""
+    t0 = time.perf_counter()
+    req.validate()
+
+    preset = strategies.PRESETS[req.strategy]
+    if not preset.available:
+        raise RunError(f"{req.strategy}: {preset.unavailable_reason}")
+
+    start, end = window_for(req.asset, req.timeframe, req.date_range)
+    prices = load_prices(req.asset, req.timeframe, start, end)
+    if prices.empty or len(prices) < 60:
+        raise RunError(
+            f"Only {len(prices)} cached bars for {req.asset} {req.timeframe} — "
+            "not enough to backtest. Try a longer range or another timeframe."
+        )
+
+    signals = pd.DataFrame()
+    if preset.needs_signals:
+        model = req.model_slug or (available_models(req.asset, req.timeframe) or [""])[0]
+        if not model:
+            raise RunError(
+                f"{req.strategy} needs stored model signals, and none are cached "
+                f"for {req.asset} {req.timeframe}. Use Extend coverage to add them."
+            )
+        signals = load_signals(model, req.asset, req.timeframe, start, end)
+        if signals.empty:
+            raise RunError(f"No signal coverage for {model} on {req.asset} {req.timeframe}.")
+
+    params = {**strategies.defaults_for(req.strategy), **(req.params or {})}
+    out = strategies.build(req.strategy, prices, params, signals)
+    cfg = req.to_config()
+    result = run_backtest(prices, out, cfg,
+                          bars_per_year=config.bars_per_year(req.asset, req.timeframe))
+
+    return RunRecord(
+        run_id=uuid.uuid4().hex[:8],
+        label=f"{req.strategy} · {req.asset} {req.timeframe}",
+        request=req, result=result,
+        created_at=datetime.now(timezone.utc).isoformat(timespec="seconds"),
+        elapsed_s=time.perf_counter() - t0,
+    )
+
+
+# --------------------------------------------------------------------------
+# Robustness helpers
+# --------------------------------------------------------------------------
+
+
+def parameter_sweep(req: RunRequest, x_key: str, x_vals: list, y_key: str,
+                    y_vals: list) -> pd.DataFrame:
+    """Two-parameter OOS-Sharpe sweep for the sensitivity heatmap.
+
+    Runs against the selection window only; the holdout is never touched,
+    because `build_validation_plan` excludes it from every window it emits.
+    """
+    rows = []
+    for xv in x_vals:
+        for yv in y_vals:
+            trial = RunRequest(**{**asdict(req), "params": {**req.params, x_key: xv, y_key: yv}})
+            try:
+                rec = execute(trial)
+                rows.append({x_key: xv, y_key: yv,
+                             "oos_sharpe": rec.result.metrics_oos.sharpe})
+            except Exception:
+                rows.append({x_key: xv, y_key: yv, "oos_sharpe": float("nan")})
+    return pd.DataFrame(rows)
+
+
+def slippage_stress(req: RunRequest, bps_points=(0, 5, 10, 20)) -> list[tuple[float, float]]:
+    out = []
+    for bps in bps_points:
+        trial = RunRequest(**{**asdict(req), "costs_on": True, "slippage_bps": float(bps)})
+        try:
+            rec = execute(trial)
+            out.append((float(bps), rec.result.metrics_oos.sharpe))
+        except Exception:
+            out.append((float(bps), float("nan")))
+    return out
+
+
+def regime_breakdown(rec: RunRecord) -> pd.DataFrame:
+    """Strategy return within each market regime."""
+    from .charts import classify_regime
+
+    res = rec.result
+    if res.prices is None or res.prices.empty:
+        return pd.DataFrame()
+    reg = classify_regime(res.prices)
+    eq = res.equity.reindex(reg.index).ffill()
+    rets = eq.pct_change().fillna(0.0)
+    rows = []
+    for name in ("bull", "bear", "chop"):
+        mask = reg == name
+        if not mask.any():
+            continue
+        rows.append({"regime": name.upper(),
+                     rec.label[:24]: float((1 + rets[mask]).prod() - 1.0)})
+    return pd.DataFrame(rows)
+
+
+def overfit_verdict(rec: RunRecord) -> tuple[str, list[tuple[str, str]]]:
+    """A blunt grade plus the checks behind it."""
+    res = rec.result
+    checks: list[tuple[str, str]] = []
+    score = 0
+
+    is_s, oos_s = res.metrics_is.sharpe, res.metrics_oos.sharpe
+    if res.metrics_oos.bars == 0:
+        checks.append(("✗", "no out-of-sample period was produced — this result is "
+                            "entirely in-sample and cannot be trusted"))
+    else:
+        ratio = (oos_s / is_s) if is_s else float("nan")
+        if pd.notna(ratio) and ratio >= 0.5:
+            checks.append(("✓", f"OOS Sharpe holds at {ratio:.2f} of in-sample"))
+            score += 1
+        else:
+            checks.append(("✗", f"OOS Sharpe collapses to {ratio:.2f} of in-sample"))
+
+    n = res.metrics_all.trade_count
+    if n >= 30:
+        checks.append(("✓", f"{n} trades is enough to mean something"))
+        score += 1
+    else:
+        checks.append(("✗", f"only {n} trades — the result is mostly noise"))
+
+    if res.windows:
+        pos = sum(1 for w in res.windows if w.metrics.total_return > 0)
+        if pos >= len(res.windows) * 0.6:
+            checks.append(("✓", f"{pos}/{len(res.windows)} walk-forward windows positive"))
+            score += 1
+        else:
+            checks.append(("✗", f"only {pos}/{len(res.windows)} windows positive"))
+    else:
+        checks.append(("·", "no walk-forward windows in this configuration"))
+
+    if res.costs_paid > 0:
+        checks.append(("✓", f"costs modelled: ${res.costs_paid:,.0f} paid"))
+        score += 1
+    else:
+        checks.append(("✗", "costs are off — this number is not real"))
+
+    if res.metrics_holdout is not None:
+        hs = res.metrics_holdout.sharpe
+        if hs > 0:
+            checks.append(("✓", f"locked holdout Sharpe {hs:.2f}"))
+            score += 1
+        else:
+            checks.append(("✗", f"locked holdout Sharpe {hs:.2f} — it fails on unseen data"))
+    else:
+        checks.append(("·", "no locked holdout reserved"))
+
+    grade = ["FAILS", "FRAGILE", "FRAGILE", "PLAUSIBLE", "PLAUSIBLE", "SOLID"][min(score, 5)]
+    return grade, checks
+
+
+def save_run_summary(rec: RunRecord) -> str:
+    """Write a shareable run summary into the store's runs/ folder."""
+    payload = {
+        "run_id": rec.run_id, "label": rec.label, "created_at": rec.created_at,
+        "config": asdict(rec.request), "share_token": rec.request.encode(),
+        "summary": rec.result.summary(),
+        "metrics": {
+            "all": rec.result.metrics_all.to_dict(),
+            "is": rec.result.metrics_is.to_dict(),
+            "oos": rec.result.metrics_oos.to_dict(),
+            "holdout": rec.result.metrics_holdout.to_dict()
+            if rec.result.metrics_holdout else None,
+        },
+    }
+    get_store().write_json(f"runs/{rec.run_id}.json", payload)
+    return rec.run_id

src/store.py

@@ -0,0 +1,760 @@
+"""Signal store: manifest, coverage queries, and append-only Hub writes.
+
+The store holds *raw model outputs and prices only* -- never trade decisions.
+Trading rules, costs and sizing are applied live by engine.py per request.
+
+Layout inside the dataset repo:
+
+    manifest.json
+    signals/{model_slug}/{asset}/{timeframe}/{year}.parquet
+    prices/{asset}/{timeframe}/{year}.parquet
+    comparisons/*.parquet | *.json
+    runs/{run_id}.json
+
+Writes are staged into a local mirror directory and pushed as a *single*
+atomic commit per flush, with the manifest as the last operation in the
+commit. A CommitScheduler can be attached to batch flushes in the running
+Space (see `attach_scheduler`).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+from dataclasses import dataclass, field, asdict
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Iterable, Literal
+
+import pandas as pd
+
+from . import config
+
+# --------------------------------------------------------------------------
+# Errors
+# --------------------------------------------------------------------------
+
+
+class StoreError(RuntimeError):
+    """Raised when the store is asked to do something inconsistent."""
+
+
+class SchemaError(StoreError):
+    """Raised when a manifest or parquet slice fails schema validation."""
+
+
+# --------------------------------------------------------------------------
+# Schema
+# --------------------------------------------------------------------------
+
+SIGNAL_COLUMNS_QUANTILE = ["ts", "q10", "q50", "q90", "context_len", "inference_version"]
+SIGNAL_COLUMNS_CLASSIFIER = ["ts", "pred", "confidence", "context_len", "inference_version"]
+PRICE_COLUMNS = ["ts", "open", "high", "low", "close", "volume", "source"]
+
+SignalKind = Literal["quantile", "classifier"]
+
+
+def _utc(ts) -> pd.Timestamp:
+    """Coerce anything timestamp-ish to a UTC-aware pandas 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().replace("+00:00", "Z")
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds").replace("+00:00", "Z")
+
+
+def signal_key(model_slug: str, model_revision: str, asset: str, timeframe: str) -> str:
+    """Canonical manifest key. Revision is part of the identity on purpose:
+    a different model revision is a different signal series."""
+    return f"{model_slug}@{model_revision}|{asset}|{timeframe}"
+
+
+def price_key(asset: str, timeframe: str) -> str:
+    return f"{asset}|{timeframe}"
+
+
+@dataclass
+class CoverageEntry:
+    """One (model, revision, asset, timeframe) coverage record."""
+
+    model_slug: str
+    model_id: str
+    model_revision: str
+    asset: str
+    timeframe: str
+    start_ts: str
+    end_ts: str
+    rows: int
+    inference_version: str
+    last_updated: str
+    contributed_by: str
+    signal_kind: SignalKind = "quantile"
+
+    @property
+    def key(self) -> str:
+        return signal_key(self.model_slug, self.model_revision, self.asset, self.timeframe)
+
+    @property
+    def is_placeholder(self) -> bool:
+        return self.inference_version == config.PLACEHOLDER_VERSION
+
+    def validate(self) -> None:
+        for f in ("model_slug", "model_id", "model_revision", "asset",
+                  "timeframe", "inference_version", "contributed_by"):
+            if not getattr(self, f):
+                raise SchemaError(f"CoverageEntry.{f} must be non-empty")
+        if self.timeframe not in config.TIMEFRAMES:
+            raise SchemaError(f"unknown timeframe {self.timeframe!r}")
+        if self.rows < 0:
+            raise SchemaError("CoverageEntry.rows must be >= 0")
+        if _utc(self.start_ts) > _utc(self.end_ts):
+            raise SchemaError(f"start_ts after end_ts for {self.key}")
+        if self.signal_kind not in ("quantile", "classifier"):
+            raise SchemaError(f"bad signal_kind {self.signal_kind!r}")
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "CoverageEntry":
+        known = {k: v for k, v in d.items() if k in cls.__dataclass_fields__}
+        return cls(**known)
+
+
+@dataclass
+class PriceCoverage:
+    """Cached OHLCV coverage for one (asset, timeframe).
+
+    `provider_max_days` records an honest provider depth boundary (e.g. Yahoo
+    only serves ~730d of 1h bars). It is a fact about coverage, not an error.
+    """
+
+    asset: str
+    timeframe: str
+    start_ts: str
+    end_ts: str
+    rows: int
+    sources: list[str]
+    last_updated: str
+    provider_max_days: int | None = None
+    gaps: int = 0
+
+    @property
+    def key(self) -> str:
+        return price_key(self.asset, self.timeframe)
+
+    def validate(self) -> None:
+        if self.timeframe not in config.TIMEFRAMES:
+            raise SchemaError(f"unknown timeframe {self.timeframe!r}")
+        if self.rows < 0:
+            raise SchemaError("PriceCoverage.rows must be >= 0")
+        if _utc(self.start_ts) > _utc(self.end_ts):
+            raise SchemaError(f"start_ts after end_ts for {self.key}")
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "PriceCoverage":
+        known = {k: v for k, v in d.items() if k in cls.__dataclass_fields__}
+        return cls(**known)
+
+
+@dataclass
+class Manifest:
+    schema_version: int = config.MANIFEST_SCHEMA_VERSION
+    updated_at: str = field(default_factory=_now_iso)
+    signals: dict[str, CoverageEntry] = field(default_factory=dict)
+    prices: dict[str, PriceCoverage] = field(default_factory=dict)
+
+    # -- serialisation ----------------------------------------------------
+
+    def to_dict(self) -> dict:
+        return {
+            "schema_version": self.schema_version,
+            "updated_at": self.updated_at,
+            "signals": {k: asdict(v) for k, v in sorted(self.signals.items())},
+            "prices": {k: asdict(v) for k, v in sorted(self.prices.items())},
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Manifest":
+        if not isinstance(d, dict):
+            raise SchemaError("manifest must be a JSON object")
+        ver = d.get("schema_version")
+        if ver is None:
+            raise SchemaError("manifest missing schema_version")
+        if int(ver) > config.MANIFEST_SCHEMA_VERSION:
+            raise SchemaError(
+                f"manifest schema_version {ver} is newer than this app supports "
+                f"({config.MANIFEST_SCHEMA_VERSION}); upgrade the Space"
+            )
+        m = cls(
+            schema_version=int(ver),
+            updated_at=d.get("updated_at") or _now_iso(),
+            signals={k: CoverageEntry.from_dict(v) for k, v in (d.get("signals") or {}).items()},
+            prices={k: PriceCoverage.from_dict(v) for k, v in (d.get("prices") or {}).items()},
+        )
+        m.validate()
+        return m
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict(), indent=2, sort_keys=False) + "\n"
+
+    @classmethod
+    def from_json(cls, text: str) -> "Manifest":
+        try:
+            return cls.from_dict(json.loads(text))
+        except json.JSONDecodeError as e:
+            raise SchemaError(f"manifest is not valid JSON: {e}") from e
+
+    def validate(self) -> None:
+        for k, e in self.signals.items():
+            e.validate()
+            if e.key != k:
+                raise SchemaError(f"manifest signal key {k!r} != entry key {e.key!r}")
+        for k, p in self.prices.items():
+            p.validate()
+            if p.key != k:
+                raise SchemaError(f"manifest price key {k!r} != entry key {p.key!r}")
+
+    # -- queries ----------------------------------------------------------
+
+    def get_signal(self, model_slug, model_revision, asset, timeframe) -> CoverageEntry | None:
+        return self.signals.get(signal_key(model_slug, model_revision, asset, timeframe))
+
+    def find_signals(self, model_slug=None, asset=None, timeframe=None) -> list[CoverageEntry]:
+        out = []
+        for e in self.signals.values():
+            if model_slug and e.model_slug != model_slug:
+                continue
+            if asset and e.asset != asset:
+                continue
+            if timeframe and e.timeframe != timeframe:
+                continue
+            out.append(e)
+        return sorted(out, key=lambda e: (e.model_slug, e.asset, e.timeframe))
+
+    def upsert_signal(self, entry: CoverageEntry) -> None:
+        """Merge a new slice into coverage, widening the range and summing rows.
+
+        Coverage is a *union*; re-writing an overlapping slice must not double
+        count, so callers pass the post-merge row count via `rows`.
+        """
+        entry.validate()
+        prev = self.signals.get(entry.key)
+        if prev is not None:
+            entry.start_ts = _iso(min(_utc(prev.start_ts), _utc(entry.start_ts)))
+            entry.end_ts = _iso(max(_utc(prev.end_ts), _utc(entry.end_ts)))
+        self.signals[entry.key] = entry
+        self.updated_at = _now_iso()
+
+    def upsert_price(self, cov: PriceCoverage) -> None:
+        cov.validate()
+        prev = self.prices.get(cov.key)
+        if prev is not None:
+            cov.start_ts = _iso(min(_utc(prev.start_ts), _utc(cov.start_ts)))
+            cov.end_ts = _iso(max(_utc(prev.end_ts), _utc(cov.end_ts)))
+            cov.sources = sorted(set(prev.sources) | set(cov.sources))
+        self.prices[cov.key] = cov
+        self.updated_at = _now_iso()
+
+
+def empty_manifest() -> Manifest:
+    return Manifest()
+
+
+# --------------------------------------------------------------------------
+# Frame validation
+# --------------------------------------------------------------------------
+
+
+def validate_signal_frame(df: pd.DataFrame, kind: SignalKind = "quantile") -> pd.DataFrame:
+    """Check and normalise a signal frame. Returns a sorted, UTC-indexed copy."""
+    cols = SIGNAL_COLUMNS_QUANTILE if kind == "quantile" else SIGNAL_COLUMNS_CLASSIFIER
+    missing = [c for c in cols if c not in df.columns]
+    if missing:
+        raise SchemaError(f"signal frame missing columns: {missing}")
+    out = df.loc[:, cols].copy()
+    out["ts"] = out["ts"].map(_utc)
+    if out["ts"].duplicated().any():
+        dupes = out.loc[out["ts"].duplicated(), "ts"].head(3).tolist()
+        raise SchemaError(f"signal frame has duplicate timestamps, e.g. {dupes}")
+    if kind == "quantile":
+        for c in ("q10", "q50", "q90"):
+            if out[c].isna().any():
+                raise SchemaError(f"signal frame column {c} contains NaN")
+        # Quantiles must be monotone; a crossed quantile means a broken adapter.
+        bad = (out["q10"] > out["q50"]) | (out["q50"] > out["q90"])
+        if bad.any():
+            raise SchemaError(
+                f"{int(bad.sum())} rows have crossed quantiles (q10>q50 or q50>q90)"
+            )
+    return out.sort_values("ts").reset_index(drop=True)
+
+
+@dataclass
+class PriceValidation:
+    """Outcome of validating an OHLCV frame -- the gap report lives here."""
+
+    rows: int
+    gaps: int = 0
+    gap_ranges: list[tuple[str, str]] = field(default_factory=list)
+    problems: list[str] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return not self.problems
+
+
+def validate_price_frame(
+    df: pd.DataFrame, timeframe: str, *, strict: bool = True
+) -> tuple[pd.DataFrame, PriceValidation]:
+    """Validate an OHLCV frame and report gaps.
+
+    Rejects: missing columns, duplicate timestamps, negative/zero prices,
+    non-finite values, and OHLC bars that are internally inconsistent
+    (high < low, or a high below open/close).
+    """
+    missing = [c for c in PRICE_COLUMNS if c not in df.columns]
+    if missing:
+        raise SchemaError(f"price frame missing columns: {missing}")
+
+    out = df.loc[:, PRICE_COLUMNS].copy()
+    out["ts"] = out["ts"].map(_utc)
+    out = out.sort_values("ts").reset_index(drop=True)
+    report = PriceValidation(rows=len(out))
+
+    if out["ts"].duplicated().any():
+        dupes = out.loc[out["ts"].duplicated(), "ts"].head(3).tolist()
+        report.problems.append(f"duplicate timestamps: {dupes}")
+
+    ohlc = ["open", "high", "low", "close"]
+    for c in ohlc:
+        vals = pd.to_numeric(out[c], errors="coerce")
+        if vals.isna().any():
+            report.problems.append(f"{c} has non-numeric or NaN values")
+        if (vals <= 0).any():
+            n = int((vals <= 0).sum())
+            report.problems.append(f"{c} has {n} non-positive values")
+        out[c] = vals
+
+    vol = pd.to_numeric(out["volume"], errors="coerce")
+    if (vol < 0).any():
+        report.problems.append(f"volume has {int((vol < 0).sum())} negative values")
+    out["volume"] = vol
+
+    inconsistent = (
+        (out["high"] < out["low"])
+        | (out["high"] < out["open"])
+        | (out["high"] < out["close"])
+        | (out["low"] > out["open"])
+        | (out["low"] > out["close"])
+    )
+    if inconsistent.any():
+        report.problems.append(f"{int(inconsistent.sum())} bars have inconsistent OHLC")
+
+    # Gap report: how many expected bars are absent from the series.
+    if len(out) > 2:
+        step = pd.Timedelta(minutes=config.TIMEFRAMES[timeframe].minutes)
+        deltas = out["ts"].diff().dropna()
+        gap_mask = deltas > step * 1.5
+        report.gaps = int(gap_mask.sum())
+        idx = list(deltas.index[gap_mask])[:20]
+        report.gap_ranges = [
+            (_iso(out["ts"].iloc[i - 1]), _iso(out["ts"].iloc[i])) for i in idx
+        ]
+
+    if strict and report.problems:
+        raise SchemaError("price validation failed: " + "; ".join(report.problems))
+    return out, report
+
+
+# --------------------------------------------------------------------------
+# The store
+# --------------------------------------------------------------------------
+
+
+def _years(start, end) -> list[int]:
+    return list(range(_utc(start).year, _utc(end).year + 1))
+
+
+class SignalStore:
+    """Read/write access to the signal store.
+
+    `local_root` is a working mirror of the repo. Reads fall back to the Hub
+    when a file is absent locally; writes stage into the mirror and are pushed
+    by `flush()` as one atomic commit.
+
+    Set `offline=True` (or leave `repo_id=None`) for a purely local store --
+    used by tests and by the seed script before it has 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 Path(os.environ.get("BIT_STORE_CACHE", ".cache/store")))
+        self.local_root.mkdir(parents=True, exist_ok=True)
+        self._manifest: Manifest | None = None
+        self._pending: set[str] = set()  # repo-relative paths staged for commit
+        self._lock = threading.RLock()
+        self._scheduler = None
+
+    # -- paths ------------------------------------------------------------
+
+    @staticmethod
+    def signal_path(model_slug: str, asset: str, timeframe: str, year: int) -> str:
+        return f"signals/{model_slug}/{asset}/{timeframe}/{year}.parquet"
+
+    @staticmethod
+    def price_path(asset: str, timeframe: str, year: int) -> str:
+        return f"prices/{asset}/{timeframe}/{year}.parquet"
+
+    @staticmethod
+    def comparison_path(name: str) -> str:
+        return f"comparisons/{name}"
+
+    def _local(self, repo_path: str) -> Path:
+        return self.local_root / repo_path
+
+    # -- low-level file access -------------------------------------------
+
+    def _fetch(self, repo_path: str) -> Path | None:
+        """Return a local path for `repo_path`, pulling from the Hub if needed."""
+        local = self._local(repo_path)
+        if local.exists():
+            return local
+        if self.offline:
+            return None
+        try:
+            from huggingface_hub import hf_hub_download
+
+            got = hf_hub_download(
+                repo_id=self.repo_id,
+                repo_type=config.STORE_REPO_TYPE,
+                filename=repo_path,
+                revision=self.revision,
+                token=self.token,
+            )
+            return Path(got)
+        except Exception:
+            # Absent from the Hub is a normal "no coverage" 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
+        return pd.read_parquet(p)
+
+    def _stage(self, repo_path: str, write) -> None:
+        """Write a file into the local mirror and mark it for the next commit."""
+        local = self._local(repo_path)
+        local.parent.mkdir(parents=True, exist_ok=True)
+        write(local)
+        with self._lock:
+            self._pending.add(repo_path)
+
+    # -- manifest ---------------------------------------------------------
+
+    def load_manifest(self, force: bool = False) -> Manifest:
+        with self._lock:
+            if self._manifest is not None and not force:
+                return self._manifest
+            local = self._local(config.MANIFEST_PATH)
+            text = None
+            if local.exists():
+                text = local.read_text()
+            elif not self.offline:
+                p = self._fetch(config.MANIFEST_PATH)
+                if p is not None:
+                    text = Path(p).read_text()
+            self._manifest = Manifest.from_json(text) if text else empty_manifest()
+            return self._manifest
+
+    def save_manifest(self, manifest: Manifest | None = None) -> Manifest:
+        with self._lock:
+            m = manifest or self.load_manifest()
+            m.validate()
+            m.updated_at = _now_iso()
+            self._manifest = m
+            self._stage(config.MANIFEST_PATH, lambda p: p.write_text(m.to_json()))
+            return m
+
+    # -- coverage queries -------------------------------------------------
+
+    def has_coverage(
+        self, model_slug: str, model_revision: str, asset: str, timeframe: str,
+        start=None, end=None, *, allow_placeholder: bool = True,
+    ) -> bool:
+        e = self.load_manifest().get_signal(model_slug, model_revision, asset, timeframe)
+        if e is None or e.rows == 0:
+            return False
+        if not allow_placeholder and e.is_placeholder:
+            return False
+        if start is not None and _utc(start) < _utc(e.start_ts):
+            return False
+        if end is not None and _utc(end) > _utc(e.end_ts):
+            return False
+        return True
+
+    def missing_ranges(
+        self, model_slug: str, model_revision: str, asset: str, timeframe: str, start, end
+    ) -> list[tuple[pd.Timestamp, pd.Timestamp]]:
+        """Sub-ranges of [start, end] not yet covered. Drives extension dedup:
+        an already-covered request returns [] and must never be recomputed."""
+        s, e = _utc(start), _utc(end)
+        if s > e:
+            return []
+        entry = self.load_manifest().get_signal(model_slug, model_revision, asset, timeframe)
+        if entry is None or entry.rows == 0:
+            return [(s, e)]
+        cs, ce = _utc(entry.start_ts), _utc(entry.end_ts)
+        out = []
+        if s < cs:
+            out.append((s, min(e, cs - pd.Timedelta(seconds=1))))
+        if e > ce:
+            out.append((max(s, ce + pd.Timedelta(seconds=1)), e))
+        return [(a, b) for a, b in out if a <= b]
+
+    # -- reads ------------------------------------------------------------
+
+    def _read_years(self, path_fn, years: Iterable[int]) -> pd.DataFrame | None:
+        frames = []
+        for y in years:
+            df = self.read_parquet(path_fn(y))
+            if df is not None and len(df):
+                frames.append(df)
+        if not frames:
+            return None
+        out = pd.concat(frames, ignore_index=True)
+        out["ts"] = out["ts"].map(_utc)
+        return out.sort_values("ts").reset_index(drop=True)
+
+    def get_signals(
+        self, model_slug: str, asset: str, timeframe: str, start=None, end=None
+    ) -> pd.DataFrame:
+        """Signal slice, ts-indexed. Empty frame when there is no coverage."""
+        m = self.load_manifest()
+        entries = m.find_signals(model_slug=model_slug, asset=asset, timeframe=timeframe)
+        if start is None or end is None:
+            if not entries:
+                return pd.DataFrame(columns=SIGNAL_COLUMNS_QUANTILE).set_index(
+                    pd.DatetimeIndex([], tz="UTC", name="ts")
+                )
+            start = start or min(_utc(e.start_ts) for e in entries)
+            end = end or max(_utc(e.end_ts) for e in entries)
+        s, e = _utc(start), _utc(end)
+        df = self._read_years(
+            lambda y: self.signal_path(model_slug, asset, timeframe, y), _years(s, e)
+        )
+        if df is None:
+            return pd.DataFrame(columns=SIGNAL_COLUMNS_QUANTILE).set_index(
+                pd.DatetimeIndex([], tz="UTC", name="ts")
+            )
+        df = df[(df["ts"] >= s) & (df["ts"] <= e)]
+        return df.set_index("ts").sort_index()
+
+    def get_prices(self, asset: str, timeframe: str, start=None, end=None) -> pd.DataFrame:
+        """OHLCV slice, ts-indexed. Empty frame when there is no coverage."""
+        m = self.load_manifest()
+        cov = m.prices.get(price_key(asset, timeframe))
+        if start is None:
+            start = cov.start_ts if cov else "1970-01-01"
+        if end is None:
+            end = cov.end_ts if cov else _now_iso()
+        s, e = _utc(start), _utc(end)
+        df = self._read_years(lambda y: self.price_path(asset, timeframe, y), _years(s, e))
+        if df is None:
+            return pd.DataFrame(columns=PRICE_COLUMNS).set_index(
+                pd.DatetimeIndex([], tz="UTC", name="ts")
+            )
+        df = df[(df["ts"] >= s) & (df["ts"] <= e)]
+        return df.set_index("ts").sort_index()
+
+    # -- writes -----------------------------------------------------------
+
+    def _merge_year(self, repo_path: str, new: pd.DataFrame) -> pd.DataFrame:
+        """Append-only merge: existing rows win on a ts collision."""
+        existing = self.read_parquet(repo_path)
+        if existing is None or not len(existing):
+            return new.sort_values("ts").reset_index(drop=True)
+        existing = existing.copy()
+        existing["ts"] = existing["ts"].map(_utc)
+        merged = pd.concat([existing, new], ignore_index=True)
+        merged = merged.drop_duplicates(subset="ts", keep="first")
+        return merged.sort_values("ts").reset_index(drop=True)
+
+    def write_signals(
+        self,
+        model_slug: str,
+        model_id: str,
+        model_revision: str,
+        asset: str,
+        timeframe: str,
+        df: pd.DataFrame,
+        *,
+        inference_version: str = config.INFERENCE_VERSION,
+        contributed_by: str = "seed",
+        signal_kind: SignalKind = "quantile",
+    ) -> CoverageEntry:
+        """Stage a signal slice and update the manifest. Idempotent per ts."""
+        frame = validate_signal_frame(df, kind=signal_kind)
+        if frame.empty:
+            raise StoreError("refusing to write an empty signal frame")
+
+        total_rows = 0
+        for year, part in frame.groupby(frame["ts"].dt.year):
+            path = self.signal_path(model_slug, asset, timeframe, int(year))
+            merged = self._merge_year(path, part)
+            self._stage(path, lambda p, m=merged: m.to_parquet(p, index=False))
+            total_rows += len(merged)
+
+        # Row count reflects the union across every year touched, so an
+        # overlapping re-write does not inflate the manifest.
+        m = self.load_manifest()
+        prev = m.get_signal(model_slug, model_revision, asset, timeframe)
+        untouched = 0
+        if prev is not None:
+            touched_years = set(frame["ts"].dt.year.unique())
+            for y in _years(prev.start_ts, prev.end_ts):
+                if y not in touched_years:
+                    old = self.read_parquet(self.signal_path(model_slug, asset, timeframe, y))
+                    untouched += 0 if old is None else len(old)
+
+        entry = CoverageEntry(
+            model_slug=model_slug,
+            model_id=model_id,
+            model_revision=model_revision,
+            asset=asset,
+            timeframe=timeframe,
+            start_ts=_iso(frame["ts"].iloc[0]),
+            end_ts=_iso(frame["ts"].iloc[-1]),
+            rows=total_rows + untouched,
+            inference_version=inference_version,
+            last_updated=_now_iso(),
+            contributed_by=contributed_by,
+            signal_kind=signal_kind,
+        )
+        m.upsert_signal(entry)
+        self.save_manifest(m)
+        return entry
+
+    def write_prices(
+        self, asset: str, timeframe: str, df: pd.DataFrame, *, strict: bool = True
+    ) -> PriceCoverage:
+        """Stage an OHLCV slice and update price coverage."""
+        frame, report = validate_price_frame(df, timeframe, strict=strict)
+        if frame.empty:
+            raise StoreError("refusing to write an empty price frame")
+
+        total_rows = 0
+        for year, part in frame.groupby(frame["ts"].dt.year):
+            path = self.price_path(asset, timeframe, int(year))
+            merged = self._merge_year(path, part)
+            self._stage(path, lambda p, m=merged: m.to_parquet(p, index=False))
+            total_rows += len(merged)
+
+        m = self.load_manifest()
+        prev = m.prices.get(price_key(asset, timeframe))
+        untouched = 0
+        if prev is not None:
+            touched_years = set(frame["ts"].dt.year.unique())
+            for y in _years(prev.start_ts, prev.end_ts):
+                if y not in touched_years:
+                    old = self.read_parquet(self.price_path(asset, timeframe, y))
+                    untouched += 0 if old is None else len(old)
+
+        cov = PriceCoverage(
+            asset=asset,
+            timeframe=timeframe,
+            start_ts=_iso(frame["ts"].iloc[0]),
+            end_ts=_iso(frame["ts"].iloc[-1]),
+            rows=total_rows + untouched,
+            sources=sorted(set(frame["source"].dropna().astype(str))),
+            last_updated=_now_iso(),
+            provider_max_days=config.TIMEFRAMES[timeframe].yahoo_max_days,
+            gaps=report.gaps,
+        )
+        m.upsert_price(cov)
+        self.save_manifest(m)
+        return cov
+
+    def write_json(self, repo_path: str, payload: dict) -> None:
+        self._stage(repo_path, lambda p: p.write_text(json.dumps(payload, indent=2) + "\n"))
+
+    def write_table(self, repo_path: str, df: pd.DataFrame) -> None:
+        self._stage(repo_path, lambda p: df.to_parquet(p, index=False))
+
+    # -- commit -----------------------------------------------------------
+
+    @property
+    def pending(self) -> list[str]:
+        with self._lock:
+            return sorted(self._pending)
+
+    def flush(self, message: str = "Update signal store") -> str | None:
+        """Push every staged file as ONE atomic commit, manifest operation last.
+
+        A single commit is strictly stronger than writing the manifest after
+        the data files: readers never observe a manifest that references a
+        parquet slice that is not yet present.
+        """
+        with self._lock:
+            paths = sorted(self._pending)
+            if not paths:
+                return None
+            if self.offline:
+                self._pending.clear()
+                return None
+
+            from huggingface_hub import CommitOperationAdd, HfApi
+
+            # Manifest last so it is the final operation in the commit.
+            ordered = [p for p in paths if p != config.MANIFEST_PATH]
+            if config.MANIFEST_PATH in paths:
+                ordered.append(config.MANIFEST_PATH)
+
+            ops = [
+                CommitOperationAdd(path_in_repo=p, path_or_fileobj=str(self._local(p)))
+                for p in ordered
+            ]
+            api = HfApi(token=self.token)
+            info = api.create_commit(
+                repo_id=self.repo_id,
+                repo_type=config.STORE_REPO_TYPE,
+                revision=self.revision,
+                operations=ops,
+                commit_message=message,
+            )
+            self._pending.clear()
+            return getattr(info, "oid", None) or str(info)
+
+    def attach_scheduler(self, every_minutes: float = 5.0):
+        """Batch commits in the background while the Space runs.
+
+        The scheduler watches the same local mirror `flush()` stages into, so
+        the two paths never disagree about what is on disk.
+        """
+        if self.offline or self._scheduler is not None:
+            return self._scheduler
+        from huggingface_hub import CommitScheduler
+
+        self._scheduler = CommitScheduler(
+            repo_id=self.repo_id,
+            repo_type=config.STORE_REPO_TYPE,
+            folder_path=str(self.local_root),
+            every=every_minutes,
+            token=self.token,
+            squash_history=False,
+        )
+        return self._scheduler

src/strategies.py

@@ -0,0 +1,348 @@
+"""Strategy presets.
+
+Every strategy is a pure function of price history (and, optionally, stored
+model signals) that returns decisions aligned to **bar close**. None of them
+shift their own output -- `engine.run_backtest` does that, exactly once, so
+next-bar-open execution cannot be bypassed by a strategy.
+
+Every indicator here is causal: it uses `rolling`/`ewm` over past bars only.
+`tests/test_engine.py` proves this by perturbation rather than trusting it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Protocol
+
+import numpy as np
+import pandas as pd
+
+from .engine import StrategyOutput
+
+# --------------------------------------------------------------------------
+# Sentiment interface (stubbed for v1, real source lands later)
+# --------------------------------------------------------------------------
+
+
+class SentimentSource(Protocol):
+    """Anything that can score sentiment per bar, causally."""
+
+    def score(self, index: pd.DatetimeIndex, asset: str) -> pd.Series:
+        """Value in [-1, 1] per bar, using only information available at that bar."""
+        ...
+
+
+class NeutralSentiment:
+    """Default source: no opinion. Keeps the gate open so the momentum leg
+    behaves as plain momentum until a real feed is wired in."""
+
+    name = "neutral-stub"
+    is_stub = True
+
+    def score(self, index: pd.DatetimeIndex, asset: str) -> pd.Series:
+        return pd.Series(1.0, index=index, dtype="float64")
+
+
+class PriceProxySentiment:
+    """Deterministic stand-in derived from realised momentum.
+
+    Clearly labelled as a proxy -- it is *not* news sentiment. It exists so the
+    Sentiment-Gated preset is demonstrable end to end before the real feed
+    exists, and it is causal by construction.
+    """
+
+    name = "price-proxy-stub"
+    is_stub = True
+
+    def __init__(self, lookback: int = 24):
+        self.lookback = lookback
+
+    def score(self, index: pd.DatetimeIndex, asset: str) -> pd.Series:
+        return pd.Series(np.nan, index=index, dtype="float64")
+
+    def score_from_prices(self, prices: pd.DataFrame) -> pd.Series:
+        ret = prices["close"].pct_change(self.lookback)
+        scaled = np.tanh(ret / (ret.rolling(self.lookback * 4).std().replace(0, np.nan) + 1e-12))
+        return scaled.fillna(0.0).clip(-1.0, 1.0)
+
+
+# --------------------------------------------------------------------------
+# Indicator helpers (all causal)
+# --------------------------------------------------------------------------
+
+
+def sma(s: pd.Series, n: int) -> pd.Series:
+    return s.rolling(int(n), min_periods=int(n)).mean()
+
+
+def ema(s: pd.Series, n: int) -> pd.Series:
+    return s.ewm(span=int(n), adjust=False, min_periods=int(n)).mean()
+
+
+def rsi(s: pd.Series, n: int = 14) -> pd.Series:
+    delta = s.diff()
+    gain = delta.clip(lower=0.0)
+    loss = -delta.clip(upper=0.0)
+    avg_gain = gain.ewm(alpha=1 / int(n), adjust=False, min_periods=int(n)).mean()
+    avg_loss = loss.ewm(alpha=1 / int(n), adjust=False, min_periods=int(n)).mean()
+    rs = avg_gain / avg_loss.replace(0.0, np.nan)
+    return (100.0 - 100.0 / (1.0 + rs)).fillna(50.0)
+
+
+def bollinger(s: pd.Series, n: int = 20, k: float = 2.0):
+    mid = s.rolling(int(n), min_periods=int(n)).mean()
+    sd = s.rolling(int(n), min_periods=int(n)).std(ddof=0)
+    return mid - k * sd, mid, mid + k * sd
+
+
+def macd(s: pd.Series, fast: int = 12, slow: int = 26, signal: int = 9):
+    line = ema(s, fast) - ema(s, slow)
+    sig = line.ewm(span=int(signal), adjust=False, min_periods=int(signal)).mean()
+    return line, sig, line - sig
+
+
+def _cross_up(a: pd.Series, b: pd.Series) -> pd.Series:
+    return ((a > b) & (a.shift(1) <= b.shift(1))).astype("boolean").fillna(False).astype(bool)
+
+
+def _cross_down(a: pd.Series, b: pd.Series) -> pd.Series:
+    return ((a < b) & (a.shift(1) >= b.shift(1))).astype("boolean").fillna(False).astype(bool)
+
+
+def _triggers(index, entries, exits, entry_text: str, exit_text: str) -> pd.Series:
+    t = pd.Series("", index=index, dtype="object")
+    t[entries] = entry_text
+    t[exits] = exit_text
+    return t
+
+
+# --------------------------------------------------------------------------
+# Presets
+# --------------------------------------------------------------------------
+
+
+def buy_and_hold(prices: pd.DataFrame, params: dict | None = None,
+                 signals: pd.DataFrame | None = None) -> StrategyOutput:
+    """Enter on the first bar, never exit. The benchmark every claim is measured against."""
+    idx = prices.index
+    entries = pd.Series(False, index=idx)
+    exits = pd.Series(False, index=idx)
+    if len(idx):
+        entries.iloc[0] = True
+    return StrategyOutput(entries=entries, exits=exits,
+                          triggers=_triggers(idx, entries, exits, "buy and hold entry", ""))
+
+
+def sma_crossover(prices: pd.DataFrame, params: dict | None = None,
+                  signals: pd.DataFrame | None = None) -> StrategyOutput:
+    p = params or {}
+    fast_n, slow_n = int(p.get("fast_ma", 20)), int(p.get("slow_ma", 50))
+    close = prices["close"]
+    fast, slow = sma(close, fast_n), sma(close, slow_n)
+    entries = _cross_up(fast, slow)
+    exits = _cross_down(fast, slow)
+    return StrategyOutput(
+        entries=entries, exits=exits,
+        triggers=_triggers(prices.index, entries, exits,
+                           f"SMA{fast_n} crossed above SMA{slow_n}",
+                           f"SMA{fast_n} crossed below SMA{slow_n}"),
+    )
+
+
+def rsi_mean_reversion(prices: pd.DataFrame, params: dict | None = None,
+                       signals: pd.DataFrame | None = None) -> StrategyOutput:
+    p = params or {}
+    n = int(p.get("rsi_period", 14))
+    lo, hi = float(p.get("oversold", 30)), float(p.get("overbought", 70))
+    r = rsi(prices["close"], n)
+    entries = ((r < lo) & (r.shift(1) >= lo)).astype("boolean").fillna(False).astype(bool)
+    exits = ((r > hi) & (r.shift(1) <= hi)).astype("boolean").fillna(False).astype(bool)
+    return StrategyOutput(
+        entries=entries, exits=exits,
+        triggers=_triggers(prices.index, entries, exits,
+                           f"RSI({n}) fell below {lo:g}", f"RSI({n}) rose above {hi:g}"),
+    )
+
+
+def bollinger_breakout(prices: pd.DataFrame, params: dict | None = None,
+                       signals: pd.DataFrame | None = None) -> StrategyOutput:
+    p = params or {}
+    n, k = int(p.get("bb_period", 20)), float(p.get("bb_std", 2.0))
+    close = prices["close"]
+    lower, mid, upper = bollinger(close, n, k)
+    entries = ((close > upper) & (close.shift(1) <= upper.shift(1))).astype("boolean").fillna(False).astype(bool)
+    exits = ((close < mid) & (close.shift(1) >= mid.shift(1))).astype("boolean").fillna(False).astype(bool)
+    return StrategyOutput(
+        entries=entries, exits=exits,
+        triggers=_triggers(prices.index, entries, exits,
+                           f"close broke above the {n}/{k:g}σ upper band",
+                           "close fell back through the band midline"),
+    )
+
+
+def macd_momentum(prices: pd.DataFrame, params: dict | None = None,
+                  signals: pd.DataFrame | None = None) -> StrategyOutput:
+    p = params or {}
+    f, s, g = int(p.get("macd_fast", 12)), int(p.get("macd_slow", 26)), int(p.get("macd_signal", 9))
+    line, sig, _ = macd(prices["close"], f, s, g)
+    entries = _cross_up(line, sig)
+    exits = _cross_down(line, sig)
+    return StrategyOutput(
+        entries=entries, exits=exits,
+        triggers=_triggers(prices.index, entries, exits,
+                           f"MACD({f},{s}) crossed above its {g}-period signal",
+                           f"MACD({f},{s}) crossed below its {g}-period signal"),
+    )
+
+
+def forecast_follower(prices: pd.DataFrame, params: dict | None = None,
+                      signals: pd.DataFrame | None = None) -> StrategyOutput:
+    """Rule over stored quantiles: go long when the median forecast implies
+    enough upside; optionally exit when price breaches the q10 floor.
+
+    The stored forecast at bar `t` was produced from data up to `t`, and the
+    engine shifts it before acting, so the earliest possible fill is `t+1`'s open.
+    """
+    p = params or {}
+    threshold = float(p.get("threshold", 0.005))
+    use_q10_stop = bool(p.get("use_q10_stop", True))
+    exit_threshold = float(p.get("exit_threshold", 0.0))
+
+    idx = prices.index
+    close = prices["close"]
+    if signals is None or signals.empty or "q50" not in signals.columns:
+        false = pd.Series(False, index=idx)
+        return StrategyOutput(entries=false, exits=false.copy(),
+                              triggers=pd.Series("", index=idx, dtype="object"))
+
+    q50 = signals["q50"].reindex(idx).ffill()
+    q10 = signals["q10"].reindex(idx).ffill() if "q10" in signals.columns else None
+
+    edge = (q50 / close) - 1.0
+    entries = ((edge > threshold) & (edge.shift(1) <= threshold)).astype("boolean").fillna(False).astype(bool)
+    exits = ((edge < exit_threshold) & (edge.shift(1) >= exit_threshold)).astype("boolean").fillna(False).astype(bool)
+    if use_q10_stop and q10 is not None:
+        breach = (close < q10).astype("boolean").fillna(False).astype(bool)
+        prev_breach = breach.astype("boolean").shift(1).fillna(False).astype(bool)
+        exits = (exits | (breach & ~prev_breach)).astype("boolean").fillna(False).astype(bool)
+
+    trig = pd.Series("", index=idx, dtype="object")
+    trig[entries] = f"forecast median implied >{threshold:.2%} upside"
+    trig[exits] = "forecast edge closed or price breached the q10 floor"
+    return StrategyOutput(entries=entries, exits=exits, triggers=trig)
+
+
+def sentiment_gated_momentum(prices: pd.DataFrame, params: dict | None = None,
+                             signals: pd.DataFrame | None = None,
+                             sentiment: SentimentSource | None = None) -> StrategyOutput:
+    """Momentum that only fires while the sentiment gate is open.
+
+    The sentiment input sits behind `SentimentSource`. Until a real feed is
+    wired in, the default is a labelled stub -- see `NeutralSentiment`.
+    """
+    p = params or {}
+    fast_n, slow_n = int(p.get("fast_ma", 20)), int(p.get("slow_ma", 50))
+    gate = float(p.get("sentiment_gate", 0.40))
+    trail = p.get("trail_pct")
+
+    close = prices["close"]
+    fast, slow = sma(close, fast_n), sma(close, slow_n)
+
+    src = sentiment or PriceProxySentiment()
+    if hasattr(src, "score_from_prices"):
+        score = src.score_from_prices(prices)
+    else:
+        score = src.score(prices.index, "")
+    score = score.reindex(prices.index).fillna(0.0)
+
+    gate_open = score >= gate
+    entries = (_cross_up(fast, slow) & gate_open).astype("boolean").fillna(False).astype(bool)
+    was_open = gate_open.astype("boolean").shift(1).fillna(False).astype(bool)
+    exits = (_cross_down(fast, slow) | (~gate_open & was_open)) \
+        .astype("boolean").fillna(False).astype(bool)
+
+    trig = pd.Series("", index=prices.index, dtype="object")
+    trig[entries] = f"MA cross up with sentiment ≥ {gate:.2f}"
+    trig[exits] = "MA cross down or sentiment gate closed"
+    if trail:
+        trig[entries] = trig[entries] + f" (trailing stop {float(trail):.1%})"
+    return StrategyOutput(entries=entries, exits=exits, triggers=trig)
+
+
+# --------------------------------------------------------------------------
+# Registry
+# --------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Preset:
+    name: str
+    fn: Callable
+    needs_signals: bool = False
+    available: bool = True
+    unavailable_reason: str = ""
+    params: tuple[tuple[str, str, float, float, float], ...] = ()
+    # (key, label, default, min, max)
+
+
+PRESETS: dict[str, Preset] = {
+    p.name: p
+    for p in [
+        Preset("Buy & Hold (benchmark)", buy_and_hold),
+        Preset("SMA Crossover", sma_crossover, params=(
+            ("fast_ma", "Fast MA", 20, 2, 200),
+            ("slow_ma", "Slow MA", 50, 3, 400),
+        )),
+        Preset("RSI Mean Reversion", rsi_mean_reversion, params=(
+            ("rsi_period", "RSI period", 14, 2, 100),
+            ("oversold", "Oversold", 30, 1, 49),
+            ("overbought", "Overbought", 70, 51, 99),
+        )),
+        Preset("Bollinger Breakout", bollinger_breakout, params=(
+            ("bb_period", "Period", 20, 5, 200),
+            ("bb_std", "Std devs", 2.0, 0.5, 5.0),
+        )),
+        Preset("MACD Momentum", macd_momentum, params=(
+            ("macd_fast", "Fast EMA", 12, 2, 100),
+            ("macd_slow", "Slow EMA", 26, 3, 200),
+            ("macd_signal", "Signal", 9, 2, 50),
+        )),
+        Preset("Chronos Forecast Follower", forecast_follower, needs_signals=True, params=(
+            ("threshold", "Entry edge", 0.005, 0.0, 0.2),
+            ("exit_threshold", "Exit edge", 0.0, -0.1, 0.1),
+        )),
+        Preset("Sentiment-Gated Momentum", sentiment_gated_momentum, params=(
+            ("fast_ma", "Fast MA", 20, 2, 200),
+            ("slow_ma", "Slow MA", 50, 3, 400),
+            ("sentiment_gate", "Sentiment gate", 0.40, -1.0, 1.0),
+        )),
+        # Present in the design; not runnable in v1.
+        Preset("Pairs Trading", buy_and_hold, available=False,
+               unavailable_reason="Needs a second leg; single-asset runs only in v1."),
+        Preset("Custom (code)", buy_and_hold, available=False,
+               unavailable_reason="Running user-supplied strategy code is disabled by "
+                                  "design — this Space never executes untrusted code."),
+    ]
+}
+
+PRESET_NAMES = list(PRESETS)
+
+
+def build(name: str, prices: pd.DataFrame, params: dict | None = None,
+          signals: pd.DataFrame | None = None) -> StrategyOutput:
+    """Run a preset by name. Unknown or unavailable presets raise."""
+    preset = PRESETS.get(name)
+    if preset is None:
+        raise KeyError(f"unknown strategy preset {name!r}")
+    if not preset.available:
+        raise ValueError(f"{name} is not available: {preset.unavailable_reason}")
+    if preset.needs_signals and (signals is None or signals.empty):
+        raise ValueError(f"{name} needs stored model signals for this asset and timeframe")
+    return preset.fn(prices, params or {}, signals)
+
+
+def defaults_for(name: str) -> dict:
+    preset = PRESETS.get(name)
+    if preset is None:
+        return {}
+    return {k: d for k, _, d, _, _ in preset.params}

src/ui/theme.py

@@ -0,0 +1,282 @@
+"""Gradio theme and CSS built from the Bit design system tokens.
+
+`assets/tokens/*.css` is vendored verbatim from the design system and imported
+here rather than retyped, so token values cannot drift. This module adds only
+the app-shell layout the design specifies (three zones, panels, chips, stat
+band) on top of those tokens.
+
+Fonts are served as static files. If they fail to load the page degrades to the
+system sans / mono stack rather than breaking.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import gradio as gr
+
+ASSETS = Path(__file__).resolve().parent.parent.parent / "assets"
+FONT_DIR = ASSETS / "fonts"
+
+
+def _font_face_css() -> str:
+    """@font-face rules pointing at Gradio's static file route."""
+    faces = [
+        ("Styrene A", "StyreneA-Light.otf", 300, "normal"),
+        ("Styrene A", "StyreneA-Regular.otf", 400, "normal"),
+        ("Styrene A", "StyreneA-Medium.otf", 500, "normal"),
+        ("Mac Minecraft", "MacMinecraft.ttf", 400, "normal"),
+    ]
+    out = []
+    for family, filename, weight, style in faces:
+        path = FONT_DIR / filename
+        if not path.exists():
+            continue
+        fmt = "opentype" if filename.endswith(".otf") else "truetype"
+        out.append(
+            f"@font-face{{font-family:'{family}';"
+            f"src:url('/gradio_api/file={path}') format('{fmt}');"
+            f"font-weight:{weight};font-style:{style};font-display:swap}}"
+        )
+    return "\n".join(out)
+
+
+def _tokens_css() -> str:
+    """Inline the vendored token files so there is one source of truth."""
+    parts = []
+    for name in ("colors.css", "typography.css", "spacing.css"):
+        p = ASSETS / "tokens" / name
+        if p.exists():
+            parts.append(p.read_text())
+    return "\n".join(parts)
+
+
+SHELL_CSS = """
+/* ---------- app shell ---------- */
+.gradio-container{
+  max-width:100% !important; padding:0 !important;
+  background:var(--bg-canvas) !important;
+  font-family:var(--font-body); font-weight:var(--weight-body);
+  color:var(--text-primary);
+}
+.gradio-container *{ border-radius:var(--radius-sm) !important; }
+footer{ display:none !important; }
+
+/* ---------- typography ---------- */
+.bit-h1,.bit-h2,.bit-h3{
+  font-family:var(--font-heading); font-weight:var(--weight-heading);
+  letter-spacing:var(--tracking-wide); text-transform:uppercase;
+  color:var(--text-primary); margin:0;
+}
+.bit-h1{ font-size:var(--text-lg); }
+.bit-h2{ font-size:var(--text-md); }
+.bit-h3{ font-size:var(--text-base); }
+.bit-micro{
+  font-family:var(--font-tiny); font-size:var(--text-xs);
+  letter-spacing:var(--tracking-wider); text-transform:uppercase;
+  color:var(--text-tertiary);
+}
+.bit-mono{ font-family:var(--font-mono); font-size:var(--text-base); }
+
+/* ---------- panels ---------- */
+.bit-panel{
+  background:var(--bg-panel); border:var(--border-width) solid var(--border-default);
+  padding:var(--space-4); margin-bottom:var(--space-3);
+}
+.bit-panel-head{
+  display:flex; align-items:center; gap:var(--space-3);
+  border-bottom:var(--border-width) solid var(--border-subtle);
+  padding-bottom:var(--space-2); margin-bottom:var(--space-3);
+}
+
+/* ---------- top bar ---------- */
+.bit-topbar{
+  display:flex; align-items:center; gap:var(--space-4);
+  background:var(--bg-panel); border-bottom:var(--border-width) solid var(--border-default);
+  padding:var(--space-3) var(--space-4); position:sticky; top:0; z-index:var(--z-header);
+}
+.bit-mark{ width:22px; height:22px; background:var(--accent-amber); display:inline-block; }
+.bit-chip{
+  display:inline-flex; align-items:center; gap:6px;
+  font-family:var(--font-mono); font-size:var(--text-sm);
+  border:var(--border-width) solid var(--border-default);
+  padding:3px var(--space-2); color:var(--text-secondary);
+}
+.bit-chip-ok{ color:var(--accent-moss-strong); border-color:var(--accent-moss-dim); }
+.bit-chip-run{ color:var(--accent-amber-strong); border-color:var(--accent-amber-dim); }
+.bit-chip-warn{ color:var(--fin-down); border-color:var(--fin-down); }
+
+/* ---------- stat band ---------- */
+.bit-statband{ display:flex; flex-wrap:wrap; border:var(--border-width) solid var(--border-default); }
+.bit-stat{
+  flex:1 1 150px; padding:var(--space-3) var(--space-4);
+  border-right:var(--border-width) solid var(--border-subtle);
+}
+.bit-stat:last-child{ border-right:none; }
+.bit-stat-label{
+  font-family:var(--font-tiny); font-size:var(--text-xs);
+  letter-spacing:var(--tracking-wider); text-transform:uppercase; color:var(--text-tertiary);
+}
+.bit-stat-value{
+  font-family:var(--font-mono); font-size:var(--text-xl);
+  line-height:var(--leading-tight); color:var(--text-primary); margin:2px 0;
+}
+.bit-stat-sub{ font-family:var(--font-mono); font-size:var(--text-xs); color:var(--text-tertiary); }
+.bit-up{ color:var(--fin-up-strong); } .bit-down{ color:var(--fin-down-strong); }
+
+/* ---------- warnings / notes ---------- */
+.bit-note{
+  font-family:var(--font-mono); font-size:var(--text-sm);
+  border-left:var(--border-width-strong) solid var(--accent-amber);
+  background:var(--bg-raised); padding:var(--space-2) var(--space-3);
+  color:var(--text-secondary);
+}
+.bit-note-danger{ border-left-color:var(--fin-down); }
+
+/* ---------- footer disclaimer (always visible) ---------- */
+.bit-footer{
+  position:sticky; bottom:0; z-index:var(--z-header);
+  display:flex; justify-content:space-between; gap:var(--space-4);
+  background:var(--bg-panel); border-top:var(--border-width) solid var(--border-default);
+  padding:var(--space-2) var(--space-4);
+  font-family:var(--font-mono); font-size:var(--text-sm); color:var(--text-tertiary);
+}
+
+/* ---------- gradio overrides ---------- */
+.gradio-container .tabs > .tab-nav{
+  border-bottom:var(--border-width) solid var(--border-default) !important;
+  background:transparent !important; gap:0 !important;
+}
+.gradio-container .tabs > .tab-nav > button{
+  font-family:var(--font-heading) !important; text-transform:uppercase;
+  letter-spacing:var(--tracking-wide); font-size:var(--text-base) !important;
+  color:var(--text-tertiary) !important; background:transparent !important;
+  border:none !important; border-bottom:2px solid transparent !important;
+  padding:var(--space-2) var(--space-4) !important;
+}
+.gradio-container .tabs > .tab-nav > button.selected{
+  color:var(--text-primary) !important;
+  border-bottom-color:var(--accent-amber) !important;
+}
+.gradio-container .form, .gradio-container .block{
+  background:transparent !important; border:none !important;
+}
+/* Field captions only -- scoped so it never swallows radio/checkbox option text. */
+.block > label > span, .block > .form > label > span{
+  font-family:var(--font-tiny) !important; font-size:var(--text-xs) !important;
+  letter-spacing:var(--tracking-wider) !important; text-transform:uppercase;
+  color:var(--text-tertiary) !important;
+}
+input, select, textarea{
+  font-family:var(--font-mono) !important; font-size:var(--text-base) !important;
+  background:var(--bg-sunken) !important; color:var(--text-primary) !important;
+  border:var(--border-width) solid var(--border-default) !important;
+}
+
+/* Radio / checkbox options read as segmented chips, per the design. */
+.gradio-container fieldset label,
+.gradio-container .wrap label:has(input[type="radio"]),
+.gradio-container .wrap label:has(input[type="checkbox"]){
+  background:transparent !important;
+  border:var(--border-width) solid var(--border-default) !important;
+  color:var(--text-secondary) !important;
+  padding:4px 10px !important; margin:2px !important;
+}
+.gradio-container fieldset label span,
+.gradio-container .wrap label:has(input[type="radio"]) span,
+.gradio-container .wrap label:has(input[type="checkbox"]) span{
+  font-family:var(--font-mono) !important; font-size:var(--text-base) !important;
+  letter-spacing:var(--tracking-normal) !important; text-transform:none !important;
+  color:var(--text-secondary) !important; opacity:1 !important;
+}
+.gradio-container fieldset label.selected,
+.gradio-container fieldset label:has(input:checked),
+.gradio-container .wrap label:has(input[type="radio"]:checked){
+  background:var(--accent-amber) !important;
+  border-color:var(--accent-amber) !important;
+}
+.gradio-container fieldset label.selected span,
+.gradio-container fieldset label:has(input:checked) span,
+.gradio-container .wrap label:has(input[type="radio"]:checked) span{
+  color:var(--stone-950) !important; font-weight:500 !important;
+}
+.gradio-container input[type="radio"], .gradio-container input[type="checkbox"]{
+  accent-color:var(--accent-amber);
+}
+.bit-run-btn{
+  background:var(--accent-amber) !important; color:var(--stone-950) !important;
+  font-family:var(--font-heading) !important; text-transform:uppercase;
+  letter-spacing:var(--tracking-wide); border:none !important; font-weight:500 !important;
+}
+.bit-run-btn:hover{ background:var(--accent-amber-strong) !important; }
+.bit-ghost-btn{
+  background:transparent !important; color:var(--text-secondary) !important;
+  border:var(--border-width) solid var(--border-default) !important;
+  font-family:var(--font-mono) !important; font-size:var(--text-sm) !important;
+}
+.bit-accordion{ border:var(--border-width) solid var(--border-subtle) !important; }
+
+/* ---------- tables ---------- */
+.bit-table table{ font-family:var(--font-mono) !important; font-size:var(--text-sm) !important; }
+.bit-table thead th{
+  font-family:var(--font-tiny) !important; font-size:var(--text-xs) !important;
+  letter-spacing:var(--tracking-wider); text-transform:uppercase;
+  color:var(--text-tertiary) !important; background:var(--bg-raised) !important;
+}
+
+/* ---------- empty state ---------- */
+.bit-empty{
+  display:flex; flex-direction:column; align-items:center; justify-content:center;
+  gap:var(--space-3); padding:var(--space-9) var(--space-4); text-align:center;
+  border:var(--border-width) dashed var(--border-default); background:var(--bg-panel);
+}
+.bit-kbd{
+  font-family:var(--font-mono); font-size:var(--text-xs); color:var(--text-tertiary);
+  border:var(--border-width) solid var(--border-default); padding:2px 6px;
+}
+@media (max-width: 900px){
+  .bit-statband{ flex-direction:column; }
+  .bit-stat{ border-right:none; border-bottom:var(--border-width) solid var(--border-subtle); }
+}
+"""
+
+
+def full_css() -> str:
+    return "\n".join([_font_face_css(), _tokens_css(), SHELL_CSS])
+
+
+def bit_theme() -> gr.Theme:
+    """Gradio theme aligned to the token palette.
+
+    The CSS above does the detailed work; this makes Gradio's own generated
+    chrome start from the right colors instead of fighting it everywhere.
+    """
+    return gr.themes.Base(
+        primary_hue=gr.themes.colors.yellow,
+        secondary_hue=gr.themes.colors.lime,
+        neutral_hue=gr.themes.colors.stone,
+        font=[gr.themes.GoogleFont("Inter"), "system-ui", "sans-serif"],
+        font_mono=[gr.themes.GoogleFont("JetBrains Mono"), "ui-monospace", "monospace"],
+    ).set(
+        body_background_fill="#161512",
+        body_text_color="#f7f4ec",
+        background_fill_primary="#1d1c18",
+        background_fill_secondary="#24221d",
+        block_background_fill="#1d1c18",
+        block_border_color="#3d3a32",
+        block_label_text_color="#6f6a56",
+        border_color_primary="#3d3a32",
+        button_primary_background_fill="#af9209",
+        button_primary_text_color="#161512",
+        button_secondary_background_fill="transparent",
+        button_secondary_text_color="#b6b09a",
+        input_background_fill="#000000",
+        block_radius="4px",
+        button_large_radius="4px",
+        button_small_radius="4px",
+    )
+
+
+def static_paths() -> list[str]:
+    """Directories Gradio may serve (fonts, mark)."""
+    return [str(ASSETS)]

tests/run_all.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# Full test suite. Exits non-zero if anything fails.
+#
+#   bash tests/run_all.sh          # everything except the real-model test
+#   bash tests/run_all.sh --slow   # including the 100-step Chronos smoke test
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+PY="${PYTHON:-python}"
+[ -x "../.venv/bin/python" ] && PY="../.venv/bin/python"
+
+MARK=(-m "not slow")
+if [ "${1:-}" = "--slow" ]; then MARK=(); fi
+
+echo "== Backtest Lab test suite =="
+# The ${arr[@]+"${arr[@]}"} form keeps an empty array safe under `set -u`
+# on the bash 3.2 that ships with macOS.
+"$PY" -m pytest tests/ -q ${MARK[@]+"${MARK[@]}"} -W "error::FutureWarning"
+
+echo
+echo "== Known-answer tests (Phase 1 gate) =="
+"$PY" -m pytest tests/test_engine.py -q -k "ka1 or ka2 or ka3 or ka4 or ka5 or ka6"
+
+echo
+echo "All green."

tests/test_adapters.py

@@ -0,0 +1,345 @@
+"""Phase 2 acceptance: adapter contract, checkpoint resume, calibration maths.
+
+The real-model smoke test is marked `slow` and skipped unless `chronos` is
+importable, so the default suite stays fast and offline.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from src import config
+from src.adapters import (
+    AdapterError,
+    Forecast,
+    ModelNotAllowed,
+    PlaceholderAdapter,
+    build_windows,
+    get_adapter,
+    validate_model_id,
+)
+from src.metrics import calibration_coverage, calibration_error, directional_accuracy
+from src.store import SignalStore, validate_signal_frame
+from scripts.seed_store import Checkpoint, SeedTarget, plan_v1, seed_target
+
+
+def series(n=600, seed=0, start="2023-01-01"):
+    rng = np.random.default_rng(seed)
+    return pd.Series(
+        100 * np.exp(np.cumsum(rng.normal(0.0005, 0.02, n))),
+        index=pd.date_range(start, periods=n, freq="D", tz="UTC"),
+    )
+
+
+def price_frame(n=600, seed=0):
+    close = series(n, seed)
+    open_ = close.shift(1).fillna(close.iloc[0] * 0.999)
+    return pd.DataFrame({
+        "open": open_, "high": pd.concat([open_, close], axis=1).max(axis=1) * 1.004,
+        "low": pd.concat([open_, close], axis=1).min(axis=1) * 0.996,
+        "close": close, "volume": 1000.0, "source": "synthetic",
+    })
+
+
+# --------------------------------------------------------------------------
+# Allow-list: no arbitrary code execution
+# --------------------------------------------------------------------------
+
+
+def test_unknown_adapter_family_is_refused():
+    with pytest.raises(ModelNotAllowed, match="not allowed"):
+        get_adapter("evil-custom", "someone/backdoor")
+
+
+def test_allowed_families_are_exactly_the_configured_set():
+    assert set(config.ALLOWED_ADAPTER_FAMILIES) == {"chronos", "timesfm"}
+
+
+@pytest.mark.parametrize("bad", [
+    "", "no-slash", "a/b/c", "../../etc/passwd", "owner/../name",
+    "owner/name;rm -rf /", "owner/na me", "owner/$(whoami)",
+])
+def test_malformed_model_ids_are_rejected(bad):
+    with pytest.raises(AdapterError):
+        validate_model_id(bad)
+
+
+@pytest.mark.parametrize("good", [
+    "amazon/chronos-bolt-small", "google/timesfm-2.0-500m-pytorch", "org/model_v1.2",
+])
+def test_well_formed_model_ids_pass(good):
+    assert validate_model_id(good) == good
+
+
+# --------------------------------------------------------------------------
+# Windowing is causal
+# --------------------------------------------------------------------------
+
+
+def test_window_ends_at_its_own_timestamp():
+    s = series(n=100)
+    stamps, wins = build_windows(s, context_len=30)
+    assert wins.shape == (len(stamps), 30)
+    # The window stored at `t` must end with the value observed at `t`.
+    for i, ts in enumerate(list(stamps)[:5]):
+        assert wins[i, -1] == pytest.approx(float(s.loc[ts]))
+
+
+def test_windows_never_include_future_values():
+    s = series(n=200)
+    stamps, wins = build_windows(s, context_len=50)
+    pos = {ts: i for i, ts in enumerate(s.index)}
+    for i, ts in enumerate(list(stamps)[:10]):
+        expected = s.to_numpy()[pos[ts] - 49: pos[ts] + 1]
+        assert np.allclose(wins[i], expected)
+
+
+def test_too_short_series_yields_no_windows():
+    stamps, wins = build_windows(series(n=20), context_len=50)
+    assert len(stamps) == 0 and wins.shape[0] == 0
+
+
+# --------------------------------------------------------------------------
+# Placeholder adapter
+# --------------------------------------------------------------------------
+
+
+def test_placeholder_is_labelled_and_deterministic():
+    a = PlaceholderAdapter("synthetic/placeholder").load()
+    assert a.inference_version() == config.PLACEHOLDER_VERSION
+
+    _, wins = build_windows(series(n=300), 100)
+    first, second = a.predict(wins[:20]), a.predict(wins[:20])
+    assert np.allclose(first.q50, second.q50)
+    assert np.allclose(first.q10, second.q10)
+
+
+def test_placeholder_output_is_schema_valid():
+    a = PlaceholderAdapter("synthetic/placeholder").load()
+    stamps, wins = build_windows(series(n=300), 100)
+    df = a.predict(wins[:50]).as_frame(stamps[:50], a.inference_version())
+    out = validate_signal_frame(df)
+    assert len(out) == 50
+    assert (out["inference_version"] == config.PLACEHOLDER_VERSION).all()
+    assert ((out["q10"] <= out["q50"]) & (out["q50"] <= out["q90"])).all()
+
+
+def test_forecast_frame_sorts_crossed_quantiles():
+    f = Forecast(q10=np.array([5.0]), q50=np.array([1.0]), q90=np.array([3.0]),
+                 context_len=10)
+    df = f.as_frame(pd.DatetimeIndex(["2024-01-01"], tz="UTC"), "v1")
+    assert df["q10"].iloc[0] <= df["q50"].iloc[0] <= df["q90"].iloc[0]
+
+
+def test_forecast_rejects_mismatched_timestamp_count():
+    f = Forecast(q10=np.zeros(3), q50=np.zeros(3), q90=np.zeros(3), context_len=10)
+    with pytest.raises(AdapterError, match="!="):
+        f.as_frame(pd.DatetimeIndex(["2024-01-01"], tz="UTC"), "v1")
+
+
+def test_inference_version_pins_model_and_revision():
+    a = get_adapter("chronos", "amazon/chronos-bolt-small", revision="abc123")
+    a._resolved_revision = "abc123"
+    b = get_adapter("chronos", "amazon/chronos-bolt-small", revision="def456")
+    b._resolved_revision = "def456"
+    assert a.inference_version() != b.inference_version()
+    assert a.inference_version() == a.inference_version()
+
+
+# --------------------------------------------------------------------------
+# Checkpoint resume
+# --------------------------------------------------------------------------
+
+
+def test_checkpoint_round_trips(tmp_path):
+    p = tmp_path / "ckpt.json"
+    c = Checkpoint.load(p)
+    c.mark("m|BTC-USD|1d", pd.Timestamp("2024-06-01", tz="UTC"))
+    again = Checkpoint.load(p)
+    assert again.last_ts("m|BTC-USD|1d") == pd.Timestamp("2024-06-01", tz="UTC")
+
+
+def test_corrupt_checkpoint_starts_fresh_instead_of_crashing(tmp_path):
+    p = tmp_path / "ckpt.json"
+    p.write_text("{not json")
+    assert Checkpoint.load(p).done == {}
+
+
+def test_checkpoint_records_failures_separately(tmp_path):
+    c = Checkpoint.load(tmp_path / "c.json")
+    c.mark_failed("m|ETH-USD|1h", "boom")
+    assert Checkpoint.load(tmp_path / "c.json").failed["m|ETH-USD|1h"] == "boom"
+
+
+def test_seed_resumes_from_checkpoint_and_skips_finished_work(tmp_path, monkeypatch):
+    """An interrupted seed must not redo inference it already paid for."""
+    store = SignalStore(repo_id=None, local_root=tmp_path / "store", offline=True)
+    px = price_frame(n=400)
+    store.write_prices("BTC-USD", "1d", px.reset_index(names="ts"))
+
+    monkeypatch.setitem(config.SEED_MODELS, "test-model", config.ModelSpec(
+        slug="test-model", model_id="test/model", family="placeholder",
+        display="Test", context_len=100,
+    ))
+    target = SeedTarget("test-model", "BTC-USD", "1d", 3.0, placeholder=True)
+    ckpt = Checkpoint.load(tmp_path / "ckpt.json")
+
+    msg = seed_target(store, target, ckpt, batch_size=64, force_placeholder=True)
+    assert msg.startswith("OK")
+    first_rows = len(store.get_signals("test-model", "BTC-USD", "1d"))
+    assert first_rows > 0
+    assert ckpt.last_ts(target.key) is not None
+
+    # Second call: the checkpoint says complete, so nothing more is computed.
+    msg2 = seed_target(store, target, ckpt, batch_size=64, force_placeholder=True)
+    assert "SKIP" in msg2
+    assert len(store.get_signals("test-model", "BTC-USD", "1d")) == first_rows
+
+
+def test_seed_skips_targets_already_in_the_manifest(tmp_path, monkeypatch):
+    store = SignalStore(repo_id=None, local_root=tmp_path / "store", offline=True)
+    store.write_prices("BTC-USD", "1d", price_frame(n=400).reset_index(names="ts"))
+    monkeypatch.setitem(config.SEED_MODELS, "test-model", config.ModelSpec(
+        slug="test-model", model_id="test/model", family="placeholder",
+        display="Test", context_len=100,
+    ))
+    target = SeedTarget("test-model", "BTC-USD", "1d", 3.0, placeholder=True)
+
+    seed_target(store, target, Checkpoint.load(tmp_path / "a.json"),
+                batch_size=64, force_placeholder=True)
+    # Fresh checkpoint, but the manifest already covers the range.
+    msg = seed_target(store, target, Checkpoint.load(tmp_path / "b.json"),
+                      batch_size=64, force_placeholder=True)
+    assert "already covered" in msg
+
+
+def test_seed_skips_when_there_is_no_price_coverage(tmp_path, monkeypatch):
+    store = SignalStore(repo_id=None, local_root=tmp_path / "store", offline=True)
+    monkeypatch.setitem(config.SEED_MODELS, "test-model", config.ModelSpec(
+        slug="test-model", model_id="test/model", family="placeholder",
+        display="Test", context_len=100,
+    ))
+    msg = seed_target(store, SeedTarget("test-model", "ETH-USD", "1d", 1.0),
+                      Checkpoint.load(tmp_path / "c.json"), force_placeholder=True)
+    assert "no price coverage" in msg
+
+
+def test_v1_plan_covers_the_specified_universe():
+    targets = plan_v1()
+    assets = {t.asset for t in targets}
+    assert {"BTC-USD", "ETH-USD", "SOL-USD"} <= assets
+    assert {"SPY", "QQQ", "NVDA"} <= assets
+    assert {t.timeframe for t in targets} == {"1d", "1h", "15m"}
+    # The v1 seed is entirely real: batched inference was cheap enough that no
+    # slice needs a synthetic placeholder.
+    assert not any(t.placeholder for t in targets)
+    assert len({t.model_slug for t in targets}) >= 2
+
+
+# --------------------------------------------------------------------------
+# Calibration maths against a synthetic series of KNOWN coverage
+# --------------------------------------------------------------------------
+
+
+def test_calibration_recovers_a_known_80_percent_coverage():
+    """Construct a series where exactly 80% of actuals sit inside the band."""
+    n = 1000
+    idx = pd.DatetimeIndex(pd.date_range("2024-01-01", periods=n, freq="D", tz="UTC"))
+    lower = pd.Series(90.0, index=idx)
+    upper = pd.Series(110.0, index=idx)
+    actual = pd.Series(100.0, index=idx)  # inside
+    actual.iloc[:200] = 500.0             # 20% outside, by construction
+
+    cov = calibration_coverage(actual, lower, upper)
+    assert cov == pytest.approx(0.80, abs=1e-12)
+    assert calibration_error(cov, 0.80) == pytest.approx(0.0, abs=1e-12)
+
+
+@pytest.mark.parametrize("frac", [0.0, 0.25, 0.5, 0.9, 1.0])
+def test_calibration_recovers_any_known_coverage(frac):
+    n = 200
+    idx = pd.date_range("2024-01-01", periods=n, freq="D", tz="UTC")
+    lower, upper = pd.Series(0.0, index=idx), pd.Series(1.0, index=idx)
+    actual = pd.Series(5.0, index=idx)
+    inside = int(round(n * frac))
+    actual.iloc[:inside] = 0.5
+    assert calibration_coverage(actual, lower, upper) == pytest.approx(frac, abs=1e-12)
+
+
+def test_overconfident_band_reads_as_undercoverage():
+    n = 500
+    idx = pd.date_range("2024-01-01", periods=n, freq="D", tz="UTC")
+    rng = np.random.default_rng(3)
+    actual = pd.Series(rng.normal(0, 1, n), index=idx)
+    # A band far narrower than the true spread must score well under 0.80.
+    lower, upper = pd.Series(-0.05, index=idx), pd.Series(0.05, index=idx)
+    cov = calibration_coverage(actual, lower, upper)
+    assert cov < 0.20
+    assert calibration_error(cov, 0.80) < -0.5
+
+
+def test_calibration_of_a_correctly_specified_normal_band():
+    """A true 10th/90th percentile band on normal data covers ~80%."""
+    n = 20_000
+    idx = pd.date_range("2000-01-01", periods=n, freq="D", tz="UTC")
+    rng = np.random.default_rng(11)
+    actual = pd.Series(rng.normal(0, 1, n), index=idx)
+    lower = pd.Series(-1.2815515655446004, index=idx)
+    upper = pd.Series(1.2815515655446004, index=idx)
+    assert calibration_coverage(actual, lower, upper) == pytest.approx(0.80, abs=0.02)
+
+
+def test_directional_accuracy_is_perfect_for_a_perfect_forecast():
+    idx = pd.date_range("2024-01-01", periods=100, freq="D", tz="UTC")
+    ref = pd.Series(np.linspace(100, 200, 100), index=idx)
+    actual_next = ref.shift(-1).ffill()
+    assert directional_accuracy(actual_next, actual_next, ref) == pytest.approx(1.0)
+
+
+def test_directional_accuracy_is_zero_for_a_perfectly_wrong_forecast():
+    idx = pd.date_range("2024-01-01", periods=100, freq="D", tz="UTC")
+    ref = pd.Series(np.linspace(100, 200, 100), index=idx)
+    actual_next = ref.shift(-1).ffill()
+    inverted = ref - (actual_next - ref)
+    assert directional_accuracy(actual_next, inverted, ref) == pytest.approx(0.0)
+
+
+# --------------------------------------------------------------------------
+# Real-model smoke test
+# --------------------------------------------------------------------------
+
+
+def _chronos_available() -> bool:
+    try:
+        import chronos  # noqa: F401
+        return True
+    except Exception:
+        return False
+
+
+@pytest.mark.slow
+@pytest.mark.skipif(not _chronos_available(), reason="chronos-forecasting not installed")
+def test_chronos_100_step_run_is_schema_valid():
+    """Phase 2 acceptance: 100 steps on the real model, output schema-valid."""
+    a = get_adapter("chronos", "amazon/chronos-bolt-small", context_len=256).load()
+    assert a.resolved_revision not in ("", "unpinned")
+
+    stamps, wins = build_windows(series(n=600), 256)
+    stamps, wins = stamps[:100], wins[:100]
+    df = a.predict(wins).as_frame(stamps, a.inference_version())
+
+    out = validate_signal_frame(df)
+    assert len(out) == 100
+    assert ((out["q10"] <= out["q50"]) & (out["q50"] <= out["q90"])).all()
+    assert (out["context_len"] == 256).all()
+    assert out["inference_version"].nunique() == 1
+    assert out["inference_version"].iloc[0] != config.PLACEHOLDER_VERSION
+    assert np.isfinite(out[["q10", "q50", "q90"]].to_numpy()).all()

tests/test_data.py

@@ -0,0 +1,270 @@
+"""Phase 0 acceptance: provider chain, network gate, incremental refresh.
+
+No test here touches the network; provider fetchers are substituted.
+"""
+
+from __future__ import annotations
+
+import time
+
+import pandas as pd
+import pytest
+
+from src import config, data
+from src.data import (
+    NetworkNotAllowed,
+    ProviderError,
+    RateLimiter,
+    allow_network,
+    fetch_ohlcv,
+    missing_price_ranges,
+    refresh,
+)
+from src.store import SignalStore
+
+
+@pytest.fixture
+def store(tmp_path) -> SignalStore:
+    return SignalStore(repo_id=None, local_root=tmp_path / "store", offline=True)
+
+
+def ohlcv(n=30, start="2024-01-01", freq="D", source="fake", base=100.0) -> pd.DataFrame:
+    ts = pd.date_range(start, periods=n, freq=freq, tz="UTC")
+    close = pd.Series([base + i for i in range(n)], dtype="float64")
+    return pd.DataFrame({
+        "ts": ts, "open": close * 0.99, "high": close * 1.02,
+        "low": close * 0.98, "close": close, "volume": 1000.0, "source": source,
+    })
+
+
+@pytest.fixture
+def fake_chain(monkeypatch):
+    """Replace every provider fetcher with a recorder we control."""
+    calls: list[str] = []
+
+    def make(name, *, rows=30, fail=False, start="2024-01-01"):
+        def _f(spec, asset, tf, s, e):
+            calls.append(name)
+            if fail:
+                raise ProviderError(f"{name} is down")
+            return ohlcv(n=rows, start=start, source=name)
+        return _f
+
+    monkeypatch.setattr(data, "_FETCHERS", {}, raising=False)
+    return calls, make
+
+
+# --------------------------------------------------------------------------
+# Network gate — user-facing paths must never reach a provider
+# --------------------------------------------------------------------------
+
+
+def test_fetch_is_blocked_outside_the_refresh_path():
+    with pytest.raises(NetworkNotAllowed, match="cached store"):
+        fetch_ohlcv("BTC-USD", "1d", "2024-01-01", "2024-02-01")
+
+
+def test_gate_closes_again_after_the_context_exits():
+    assert not data.network_allowed()
+    with allow_network():
+        assert data.network_allowed()
+    assert not data.network_allowed()
+
+
+def test_gate_is_thread_local():
+    import threading
+
+    seen = {}
+
+    def worker():
+        seen["other"] = data.network_allowed()
+
+    with allow_network():
+        t = threading.Thread(target=worker)
+        t.start()
+        t.join()
+    assert seen["other"] is False
+
+
+# --------------------------------------------------------------------------
+# Chain walk / fallback
+# --------------------------------------------------------------------------
+
+
+def test_primary_provider_wins(fake_chain, monkeypatch):
+    calls, make = fake_chain
+    monkeypatch.setitem(data._FETCHERS, "binance", make("binance"))
+    monkeypatch.setitem(data._FETCHERS, "coinbase", make("coinbase"))
+    with allow_network():
+        res = fetch_ohlcv("BTC-USD", "1d", "2024-01-01", "2024-02-01")
+    assert res.source == "binance"
+    assert calls == ["binance"]
+
+
+def test_falls_back_when_primary_fails(fake_chain, monkeypatch):
+    calls, make = fake_chain
+    monkeypatch.setitem(data._FETCHERS, "binance", make("binance", fail=True))
+    monkeypatch.setitem(data._FETCHERS, "coinbase", make("coinbase"))
+    with allow_network():
+        res = fetch_ohlcv("BTC-USD", "1d", "2024-01-01", "2024-02-01")
+    assert res.source == "coinbase"
+    assert calls == ["binance", "coinbase"]
+
+
+def test_exhausted_chain_raises_with_every_reason(fake_chain, monkeypatch):
+    _, make = fake_chain
+    monkeypatch.setitem(data._FETCHERS, "binance", make("binance", fail=True))
+    monkeypatch.setitem(data._FETCHERS, "coinbase", make("coinbase", fail=True))
+    with allow_network():
+        with pytest.raises(ProviderError) as exc:
+            fetch_ohlcv("BTC-USD", "1d", "2024-01-01", "2024-02-01")
+    assert "binance is down" in str(exc.value)
+    assert "coinbase is down" in str(exc.value)
+
+
+def test_equity_and_crypto_use_different_chains():
+    crypto = [p.name for p in config.providers_for("crypto")]
+    equity = [p.name for p in config.providers_for("equity")]
+    assert crypto[:2] == ["binance", "coinbase"]
+    assert equity[:2] == ["yfinance", "stooq"]
+    assert not set(crypto) & set(equity)
+
+
+def test_tiingo_only_joins_the_chain_when_its_key_is_present(monkeypatch):
+    monkeypatch.delenv("TIINGO_KEY", raising=False)
+    assert "tiingo" not in [p.name for p in config.providers_for("equity")]
+    monkeypatch.setenv("TIINGO_KEY", "x")
+    assert "tiingo" in [p.name for p in config.providers_for("equity")]
+
+
+def test_unknown_asset_is_rejected():
+    with allow_network():
+        with pytest.raises(ProviderError, match="unknown asset"):
+            fetch_ohlcv("DOGE-USD", "1d", "2024-01-01", "2024-02-01")
+
+
+# --------------------------------------------------------------------------
+# Rate limiting + backoff
+# --------------------------------------------------------------------------
+
+
+def test_rate_limiter_spaces_calls():
+    name = "unit-test-limiter"
+    RateLimiter.wait(name, 0.0)
+    t0 = time.monotonic()
+    RateLimiter.wait(name, 0.15)
+    assert time.monotonic() - t0 >= 0.14
+
+
+def test_backoff_retries_then_succeeds(monkeypatch):
+    monkeypatch.setattr(time, "sleep", lambda s: None)
+    spec = config.ProviderSpec("retry-test", ("crypto",), min_interval_s=0.0,
+                               max_retries=4, backoff_base_s=1.0)
+    attempts = {"n": 0}
+
+    def flaky():
+        attempts["n"] += 1
+        if attempts["n"] < 3:
+            raise RuntimeError("transient")
+        return "ok"
+
+    assert data.with_backoff(spec, flaky) == "ok"
+    assert attempts["n"] == 3
+
+
+def test_backoff_gives_up_and_reports(monkeypatch):
+    monkeypatch.setattr(time, "sleep", lambda s: None)
+    spec = config.ProviderSpec("giveup-test", ("crypto",), min_interval_s=0.0,
+                               max_retries=3, backoff_base_s=1.0)
+
+    def always_fails():
+        raise RuntimeError("nope")
+
+    with pytest.raises(ProviderError, match="exhausted retries"):
+        data.with_backoff(spec, always_fails)
+
+
+# --------------------------------------------------------------------------
+# Incremental refresh — only fetch what is missing
+# --------------------------------------------------------------------------
+
+
+def test_missing_ranges_on_empty_cache(store):
+    gaps = missing_price_ranges(store, "BTC-USD", "1d", "2024-01-01", "2024-03-01")
+    assert len(gaps) == 1
+
+
+def test_missing_ranges_fully_cached(store):
+    store.write_prices("BTC-USD", "1d", ohlcv(n=60, start="2024-01-01"))
+    assert missing_price_ranges(store, "BTC-USD", "1d",
+                                "2024-01-10", "2024-02-10") == []
+
+
+def test_missing_ranges_finds_both_edges(store):
+    store.write_prices("BTC-USD", "1d", ohlcv(n=30, start="2024-02-01"))
+    gaps = missing_price_ranges(store, "BTC-USD", "1d", "2024-01-01", "2024-04-01")
+    assert len(gaps) == 2
+    assert gaps[0][0] < pd.Timestamp("2024-02-01", tz="UTC")
+    assert gaps[1][1] > pd.Timestamp("2024-03-01", tz="UTC")
+
+
+def test_refresh_skips_a_fully_cached_range(store, fake_chain, monkeypatch):
+    calls, make = fake_chain
+    monkeypatch.setitem(data._FETCHERS, "binance", make("binance", rows=60))
+    store.write_prices("BTC-USD", "1d", ohlcv(n=60, start="2024-01-01"))
+
+    rep = refresh(store, "BTC-USD", "1d", "2024-01-10", "2024-02-10")
+    assert rep.skipped_cached and rep.rows_added == 0
+    assert calls == []  # no provider was contacted
+
+
+def test_refresh_fetches_and_writes(store, fake_chain, monkeypatch):
+    calls, make = fake_chain
+    monkeypatch.setitem(data._FETCHERS, "binance", make("binance", rows=30))
+    rep = refresh(store, "BTC-USD", "1d", "2024-01-01", "2024-01-30")
+    assert rep.ok and rep.rows_added == 30
+    assert rep.sources == ["binance"]
+    assert len(store.get_prices("BTC-USD", "1d")) == 30
+
+
+def test_refresh_reports_failure_rather_than_returning_partial_data(
+    store, fake_chain, monkeypatch
+):
+    _, make = fake_chain
+    monkeypatch.setitem(data._FETCHERS, "binance", make("binance", fail=True))
+    monkeypatch.setitem(data._FETCHERS, "coinbase", make("coinbase", fail=True))
+    rep = refresh(store, "BTC-USD", "1d", "2024-01-01", "2024-01-30")
+    assert not rep.ok
+    assert rep.rows_added == 0
+    assert "FAILED" in rep.summary()
+
+
+def test_refresh_surfaces_dirty_data_instead_of_writing_it(
+    store, fake_chain, monkeypatch
+):
+    def bad(spec, asset, tf, s, e):
+        df = ohlcv(n=30, source="binance")
+        df.loc[5, "close"] = -1.0
+        return df
+
+    monkeypatch.setitem(data._FETCHERS, "binance", bad)
+    monkeypatch.setitem(data._FETCHERS, "coinbase", bad)
+    rep = refresh(store, "BTC-USD", "1d", "2024-01-01", "2024-01-30")
+    assert not rep.ok
+    assert any("non-positive" in e for e in rep.errors)
+    assert store.get_prices("BTC-USD", "1d").empty
+
+
+def test_refresh_records_source_per_row(store, fake_chain, monkeypatch):
+    _, make = fake_chain
+    monkeypatch.setitem(data._FETCHERS, "binance", make("binance", rows=20))
+    refresh(store, "BTC-USD", "1d", "2024-01-01", "2024-01-20")
+    got = store.get_prices("BTC-USD", "1d")
+    assert set(got["source"].unique()) == {"binance"}
+
+
+def test_provider_depth_limit_is_recorded_as_a_boundary_not_an_error(store):
+    """Yahoo serves ~730d of 1h bars; that is coverage truth, not a failure."""
+    store.write_prices("SPY", "1h", ohlcv(n=48, start="2025-01-01", freq="h"))
+    cov = store.load_manifest().prices["SPY|1h"]
+    assert cov.provider_max_days == config.TIMEFRAMES["1h"].yahoo_max_days == 730

tests/test_engine.py

@@ -0,0 +1,506 @@
+"""Phase 1 acceptance: the six known-answer tests, plus engine invariants.
+
+The numbered tests map one-to-one onto the build spec's list. They are the gate
+for the whole engine; if any of them fails, nothing downstream is trustworthy.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+import pytest
+
+from src import strategies
+from src.engine import (
+    BacktestConfig,
+    Costs,
+    EngineError,
+    LookaheadError,
+    Sizing,
+    Stops,
+    StrategyOutput,
+    Validation,
+    assert_causal,
+    build_validation_plan,
+    run_backtest,
+)
+
+BARS_PER_YEAR = 365.0
+
+
+# --------------------------------------------------------------------------
+# Deterministic synthetic price series
+# --------------------------------------------------------------------------
+
+
+def prices(n=400, seed=7, start="2022-01-01", freq="D", trend=0.0004, vol=0.02):
+    rng = np.random.default_rng(seed)
+    steps = rng.normal(trend, vol, n)
+    close = 100.0 * np.exp(np.cumsum(steps))
+    idx = pd.date_range(start, periods=n, freq=freq, tz="UTC")
+    close = pd.Series(close, index=idx)
+    open_ = close.shift(1).fillna(close.iloc[0] * 0.999)
+    high = pd.concat([open_, close], axis=1).max(axis=1) * 1.004
+    low = pd.concat([open_, close], axis=1).min(axis=1) * 0.996
+    return pd.DataFrame({
+        "open": open_, "high": high, "low": low, "close": close,
+        "volume": pd.Series(rng.uniform(800, 1200, n), index=idx),
+        "source": "synthetic",
+    })
+
+
+def linear_prices(n=100, start="2022-01-01"):
+    """Monotone series -- makes hand-computed expectations trivial."""
+    idx = pd.date_range(start, periods=n, freq="D", tz="UTC")
+    close = pd.Series(np.linspace(100.0, 200.0, n), index=idx)
+    open_ = close * 0.995
+    return pd.DataFrame({
+        "open": open_, "high": close * 1.01, "low": open_ * 0.99,
+        "close": close, "volume": 1000.0, "source": "synthetic",
+    })
+
+
+def no_costs() -> Costs:
+    return Costs(enabled=False)
+
+
+def cfg(**kw) -> BacktestConfig:
+    base = dict(
+        asset="BTC-USD", timeframe="1d", strategy="Buy & Hold (benchmark)",
+        costs=no_costs(), validation=Validation(mode="none"), init_cash=100_000.0,
+    )
+    base.update(kw)
+    return BacktestConfig(**base)
+
+
+# ==========================================================================
+# KNOWN-ANSWER TEST 1
+# Buy & Hold with zero costs reproduces the asset's return over the period.
+# ==========================================================================
+
+
+@pytest.mark.parametrize("px", [linear_prices(), prices(n=300, seed=3)])
+def test_ka1_buy_and_hold_zero_costs_matches_asset_return(px):
+    out = strategies.buy_and_hold(px)
+    res = run_backtest(px, out, cfg(), bars_per_year=BARS_PER_YEAR)
+
+    # Execution is next-bar-open, so the position is opened at the second bar's
+    # open. That fill price is the honest basis for "the asset's return".
+    expected = float(px["close"].iloc[-1] / px["open"].iloc[1] - 1.0)
+    assert res.metrics_all.total_return == pytest.approx(expected, abs=1e-9)
+    assert len(res.trades) == 1
+    assert res.trades["costs"].sum() == pytest.approx(0.0, abs=1e-12)
+
+
+def test_ka1_entry_fill_is_the_second_bars_open_not_the_first():
+    px = linear_prices()
+    res = run_backtest(px, strategies.buy_and_hold(px), cfg(), bars_per_year=BARS_PER_YEAR)
+    entry_px = float(res.trades["entry_px"].iloc[0])
+    assert entry_px == pytest.approx(float(px["open"].iloc[1]), abs=1e-9)
+    assert entry_px != pytest.approx(float(px["open"].iloc[0]), abs=1e-9)
+    assert res.trades["entry_ts"].iloc[0] == px.index[1]
+
+
+# ==========================================================================
+# KNOWN-ANSWER TEST 2
+# A deliberately lookahead-biased strategy is caught structurally.
+# ==========================================================================
+
+
+def peeking_strategy(px: pd.DataFrame) -> StrategyOutput:
+    """Cheats: decides at bar t using bar t+1's close."""
+    future = px["close"].shift(-1)
+    entries = (future > px["close"]).fillna(False)
+    exits = (future <= px["close"]).fillna(False)
+    return StrategyOutput(entries=entries, exits=exits)
+
+
+def subtle_peeking_strategy(px: pd.DataFrame) -> StrategyOutput:
+    """Cheats less obviously: a centred rolling mean leaks the future."""
+    centred = px["close"].rolling(11, center=True, min_periods=1).mean()
+    entries = (px["close"] > centred).fillna(False)
+    exits = (px["close"] <= centred).fillna(False)
+    return StrategyOutput(entries=entries, exits=exits)
+
+
+def test_ka2_obvious_lookahead_is_caught():
+    px = prices(n=300, seed=11)
+    with pytest.raises(LookaheadError, match="after the bar it acts on"):
+        assert_causal(peeking_strategy, px)
+
+
+def test_ka2_subtle_lookahead_is_caught():
+    px = prices(n=300, seed=12)
+    with pytest.raises(LookaheadError):
+        assert_causal(subtle_peeking_strategy, px)
+
+
+def test_ka2_global_normalisation_lookahead_is_caught():
+    """Scaling by the full-sample max leaks the future into every early bar."""
+    def global_scaled(px):
+        z = px["close"] / px["close"].max()
+        entries = (z > 0.8).fillna(False)
+        return StrategyOutput(entries=entries, exits=(~entries).fillna(False))
+
+    with pytest.raises(LookaheadError):
+        assert_causal(global_scaled, prices(n=300, seed=13))
+
+
+@pytest.mark.parametrize("name", [
+    "Buy & Hold (benchmark)", "SMA Crossover", "RSI Mean Reversion",
+    "Bollinger Breakout", "MACD Momentum", "Sentiment-Gated Momentum",
+])
+def test_ka2_every_shipped_preset_is_causal(name):
+    px = prices(n=400, seed=5)
+    assert_causal(lambda p: strategies.build(name, p, strategies.defaults_for(name)), px)
+
+
+def test_ka2_forecast_follower_is_causal_against_stored_signals():
+    px = prices(n=300, seed=17)
+    sig = pd.DataFrame({
+        "q10": px["close"] * 0.97, "q50": px["close"] * 1.01, "q90": px["close"] * 1.05,
+    }, index=px.index)
+    # Signals are pinned, so only the price path is perturbed -- exactly the
+    # situation the store creates when a cached forecast slice is replayed.
+    assert_causal(lambda p: strategies.forecast_follower(p, {"threshold": 0.005}, sig), px)
+
+
+def test_ka2_engine_refuses_same_bar_fills():
+    px = linear_prices()
+    with pytest.raises(EngineError, match="non-negotiable"):
+        run_backtest(px, strategies.buy_and_hold(px), cfg(fill="same_bar_close"),
+                     bars_per_year=BARS_PER_YEAR)
+
+
+def test_ka2_decisions_cannot_be_shifted_twice():
+    from src.engine import _shift_decisions
+
+    px = linear_prices()
+    once = _shift_decisions(strategies.buy_and_hold(px))
+    with pytest.raises(EngineError, match="already shifted"):
+        _shift_decisions(once)
+
+
+# ==========================================================================
+# KNOWN-ANSWER TEST 3
+# Zero-cost vs costed runs differ by exactly the modeled costs on the trades.
+# ==========================================================================
+
+
+def alternating(px: pd.DataFrame, hold=7, gap=5) -> StrategyOutput:
+    """Deterministic in-and-out signal, independent of price."""
+    entries = pd.Series(False, index=px.index)
+    exits = pd.Series(False, index=px.index)
+    i = 10
+    while i + hold < len(px) - 2:
+        entries.iloc[i] = True
+        exits.iloc[i + hold] = True
+        i += hold + gap
+    return StrategyOutput(entries=entries, exits=exits)
+
+
+def test_ka3_cost_difference_equals_sum_of_trade_costs():
+    px = prices(n=300, seed=21)
+    out = alternating(px)
+
+    # Fixed unit sizing keeps costs additive: with percent sizing, fees change
+    # position size and the difference compounds instead of summing.
+    sizing = Sizing(mode="fixed_units", units=1.0)
+    free = run_backtest(px, alternating(px),
+                        cfg(costs=no_costs(), sizing=sizing), bars_per_year=BARS_PER_YEAR)
+    paid = run_backtest(px, out,
+                        cfg(costs=Costs(enabled=True, commission_bps=10.0,
+                                        slippage_bps=5.0, slippage_model="fixed"),
+                            sizing=sizing), bars_per_year=BARS_PER_YEAR)
+
+    assert len(free.trades) == len(paid.trades) > 3
+
+    pnl_gap = float(free.trades["net_pnl"].sum() - paid.trades["net_pnl"].sum())
+    modeled = float(paid.trades["costs"].sum())
+    assert pnl_gap == pytest.approx(modeled, rel=1e-9, abs=1e-6)
+
+
+def test_ka3_gross_minus_costs_equals_net_on_every_trade():
+    px = prices(n=300, seed=22)
+    res = run_backtest(px, alternating(px),
+                       cfg(costs=Costs(enabled=True, commission_bps=8.0, slippage_bps=4.0),
+                           sizing=Sizing(mode="fixed_units", units=1.0)),
+                       bars_per_year=BARS_PER_YEAR)
+    residual = res.trades["gross_pnl"] - res.trades["costs"] - res.trades["net_pnl"]
+    assert np.allclose(residual.to_numpy(), 0.0, atol=1e-9)
+
+
+def test_ka3_costs_are_on_by_default():
+    c = Costs()
+    assert c.enabled
+    assert c.commission_rate > 0 and c.slippage_rate > 0
+    assert BacktestConfig().costs.enabled
+
+
+def test_ka3_more_slippage_never_helps():
+    px = prices(n=300, seed=23)
+    sizing = Sizing(mode="fixed_units", units=1.0)
+    returns = []
+    for bps in (0.0, 5.0, 20.0):
+        r = run_backtest(px, alternating(px),
+                         cfg(costs=Costs(enabled=True, commission_bps=0.0, slippage_bps=bps),
+                             sizing=sizing), bars_per_year=BARS_PER_YEAR)
+        returns.append(float(r.trades["net_pnl"].sum()))
+    assert returns[0] > returns[1] > returns[2]
+
+
+# ==========================================================================
+# KNOWN-ANSWER TEST 4
+# A strategy with no signals produces flat equity and zero trades.
+# ==========================================================================
+
+
+def test_ka4_no_signals_gives_flat_equity_and_no_trades():
+    px = prices(n=200, seed=31)
+    silent = StrategyOutput(
+        entries=pd.Series(False, index=px.index),
+        exits=pd.Series(False, index=px.index),
+    )
+    res = run_backtest(px, silent, cfg(), bars_per_year=BARS_PER_YEAR)
+
+    assert len(res.trades) == 0
+    assert res.metrics_all.trade_count == 0
+    assert res.equity.nunique() == 1
+    assert float(res.equity.iloc[-1]) == pytest.approx(100_000.0, abs=1e-9)
+    assert res.metrics_all.total_return == pytest.approx(0.0, abs=1e-12)
+    assert res.metrics_all.max_drawdown == pytest.approx(0.0, abs=1e-12)
+    assert res.metrics_all.sharpe == 0.0
+    assert res.metrics_all.win_rate == 0.0
+    assert res.metrics_all.profit_factor == 0.0
+    assert res.costs_paid == 0.0
+
+
+def test_ka4_flat_run_with_costs_still_pays_nothing():
+    px = prices(n=200, seed=32)
+    silent = StrategyOutput(entries=pd.Series(False, index=px.index),
+                            exits=pd.Series(False, index=px.index))
+    res = run_backtest(px, silent, cfg(costs=Costs(enabled=True)), bars_per_year=BARS_PER_YEAR)
+    assert res.costs_paid == 0.0
+    assert float(res.equity.iloc[-1]) == pytest.approx(100_000.0, abs=1e-9)
+
+
+# ==========================================================================
+# KNOWN-ANSWER TEST 5
+# Walk-forward boundaries never overlap; the holdout is never selectable.
+# ==========================================================================
+
+
+def test_ka5_walk_forward_windows_never_overlap_train_and_test():
+    idx = pd.date_range("2021-01-01", "2026-01-01", freq="D", tz="UTC")
+    plan = build_validation_plan(idx, Validation(
+        mode="walk_forward", train_months=12, test_months=3, roll_months=3,
+    ))
+    assert len(plan.windows) >= 4
+    for w in plan.windows:
+        assert w.train_start < w.train_end
+        assert w.test_start > w.train_end, f"window {w.idx} overlaps"
+        assert w.test_start <= w.test_end
+
+
+def test_ka5_consecutive_test_windows_do_not_overlap_each_other():
+    idx = pd.date_range("2021-01-01", "2026-01-01", freq="D", tz="UTC")
+    plan = build_validation_plan(idx, Validation(
+        mode="walk_forward", train_months=12, test_months=3, roll_months=3,
+    ))
+    for a, b in zip(plan.windows, plan.windows[1:]):
+        assert b.test_start > a.test_end
+
+
+def test_ka5_holdout_is_excluded_from_the_parameter_selection_index():
+    idx = pd.date_range("2021-01-01", "2026-01-01", freq="D", tz="UTC")
+    plan = build_validation_plan(idx, Validation(mode="holdout", holdout_months=6))
+    assert plan.holdout_start is not None
+
+    selectable = plan.selectable_index()
+    holdout = idx[idx >= plan.holdout_start]
+
+    assert len(holdout) > 0
+    assert len(set(selectable) & set(holdout)) == 0
+    assert selectable.max() < holdout.min()
+
+
+def test_ka5_walk_forward_windows_never_reach_into_the_holdout():
+    idx = pd.date_range("2021-01-01", "2026-01-01", freq="D", tz="UTC")
+    v = Validation(mode="walk_forward", train_months=12, test_months=3,
+                   roll_months=3, holdout_months=6)
+    plan = build_validation_plan(idx, v)
+    assert plan.holdout_start is not None
+    assert len(plan.windows) > 0
+    for w in plan.windows:
+        assert w.test_end < plan.holdout_start
+        assert w.train_end < plan.holdout_start
+
+
+def test_ka5_holdout_bars_are_labelled_holdout_not_oos():
+    px = prices(n=900, seed=41, start="2022-01-01")
+    res = run_backtest(px, strategies.buy_and_hold(px),
+                       cfg(validation=Validation(mode="holdout", holdout_months=6)),
+                       bars_per_year=BARS_PER_YEAR)
+    assert res.metrics_holdout is not None
+    assert res.metrics_holdout.bars > 0
+    assert res.plan.segment_of(px.index[-1]) == "holdout"
+    assert res.plan.segment_of(px.index[0]) == "IS"
+
+
+def test_ka5_split_mode_partitions_every_bar_exactly_once():
+    """With no holdout reserved, IS and OOS must tile the whole period."""
+    px = prices(n=400, seed=42)
+    res = run_backtest(px, strategies.buy_and_hold(px),
+                       cfg(validation=Validation(mode="split", split_frac=0.7,
+                                                 holdout_months=0)),
+                       bars_per_year=BARS_PER_YEAR)
+    assert res.metrics_holdout is None
+    assert res.metrics_is.bars + res.metrics_oos.bars == len(px)
+    assert res.metrics_is.bars == pytest.approx(280, abs=1)
+
+
+def test_ka5_holdout_is_carved_out_of_split_mode_too():
+    """A reserved holdout is honoured regardless of how the rest is divided."""
+    px = prices(n=900, seed=43, start="2022-01-01")
+    res = run_backtest(px, strategies.buy_and_hold(px),
+                       cfg(validation=Validation(mode="split", split_frac=0.7,
+                                                 holdout_months=6)),
+                       bars_per_year=BARS_PER_YEAR)
+    assert res.metrics_holdout is not None and res.metrics_holdout.bars > 0
+    total = res.metrics_is.bars + res.metrics_oos.bars + res.metrics_holdout.bars
+    assert total == len(px)
+
+
+# ==========================================================================
+# KNOWN-ANSWER TEST 6
+# Same config + same data => bit-identical results.
+# ==========================================================================
+
+
+def _signature(res) -> tuple:
+    return (
+        tuple(np.round(res.equity.to_numpy(), 12)),
+        tuple(np.round(res.trades["net_pnl"].to_numpy(), 12)),
+        tuple(np.round(res.trades["costs"].to_numpy(), 12)),
+        res.metrics_all.total_return,
+        res.metrics_all.sharpe,
+        res.metrics_oos.sharpe,
+    )
+
+
+def test_ka6_repeated_runs_are_bit_identical():
+    px = prices(n=400, seed=51)
+    c = cfg(strategy="SMA Crossover", costs=Costs(enabled=True),
+            validation=Validation(mode="walk_forward"))
+    params = {"fast_ma": 20, "slow_ma": 50}
+
+    runs = [
+        run_backtest(px, strategies.build("SMA Crossover", px, params), c,
+                     bars_per_year=BARS_PER_YEAR)
+        for _ in range(3)
+    ]
+    assert _signature(runs[0]) == _signature(runs[1]) == _signature(runs[2])
+
+
+def test_ka6_fingerprint_is_stable_and_config_sensitive():
+    a = cfg(strategy="SMA Crossover", params={"fast_ma": 20})
+    b = cfg(strategy="SMA Crossover", params={"fast_ma": 20})
+    c = cfg(strategy="SMA Crossover", params={"fast_ma": 21})
+    assert a.fingerprint() == b.fingerprint()
+    assert a.fingerprint() != c.fingerprint()
+
+
+def test_ka6_cost_change_changes_the_fingerprint():
+    a = cfg(costs=Costs(enabled=True, commission_bps=10.0))
+    b = cfg(costs=Costs(enabled=True, commission_bps=11.0))
+    assert a.fingerprint() != b.fingerprint()
+
+
+# ==========================================================================
+# Engine invariants beyond the six
+# ==========================================================================
+
+
+def test_trade_list_carries_every_documented_column():
+    px = prices(n=300, seed=61)
+    res = run_backtest(px, alternating(px), cfg(costs=Costs(enabled=True)),
+                       bars_per_year=BARS_PER_YEAR)
+    for col in ("id", "entry_ts", "exit_ts", "side", "entry_px", "exit_px", "size",
+                "gross_pnl", "costs", "net_pnl", "r_multiple", "mae", "mfe",
+                "duration_bars", "trigger", "segment"):
+        assert col in res.trades.columns
+
+
+def test_mae_is_never_positive_and_mfe_never_negative_for_longs():
+    px = prices(n=300, seed=62)
+    res = run_backtest(px, alternating(px), cfg(), bars_per_year=BARS_PER_YEAR)
+    longs = res.trades[res.trades["side"] == "long"]
+    assert (longs["mae"] <= 1e-12).all()
+    assert (longs["mfe"] >= -1e-12).all()
+
+
+def test_trigger_reason_is_populated_from_the_strategy():
+    px = prices(n=400, seed=63)
+    out = strategies.build("SMA Crossover", px, {"fast_ma": 10, "slow_ma": 30})
+    res = run_backtest(px, out, cfg(strategy="SMA Crossover"), bars_per_year=BARS_PER_YEAR)
+    assert len(res.trades) > 0
+    assert (res.trades["trigger"].str.len() > 0).all()
+    assert "crossed above" in res.trades["trigger"].iloc[0]
+
+
+def test_index_mismatch_is_rejected():
+    px = prices(n=100, seed=64)
+    bad = StrategyOutput(
+        entries=pd.Series(False, index=px.index[:50]),
+        exits=pd.Series(False, index=px.index[:50]),
+    )
+    with pytest.raises(EngineError, match="index does not match"):
+        run_backtest(px, bad, cfg(), bars_per_year=BARS_PER_YEAR)
+
+
+def test_empty_prices_are_rejected():
+    empty = pd.DataFrame(columns=["open", "high", "low", "close", "volume"])
+    out = StrategyOutput(entries=pd.Series(dtype=bool), exits=pd.Series(dtype=bool))
+    with pytest.raises(EngineError, match="no price data"):
+        run_backtest(empty, out, cfg(), bars_per_year=BARS_PER_YEAR)
+
+
+def test_stops_are_applied_when_configured():
+    px = prices(n=400, seed=65, trend=-0.002, vol=0.03)
+    with_stop = run_backtest(px, alternating(px),
+                             cfg(stops=Stops(sl_pct=0.02)), bars_per_year=BARS_PER_YEAR)
+    without = run_backtest(px, alternating(px), cfg(), bars_per_year=BARS_PER_YEAR)
+    assert with_stop.trades["net_pnl"].min() > without.trades["net_pnl"].min()
+
+
+def test_r_multiple_uses_the_configured_stop_distance():
+    px = prices(n=300, seed=66)
+    res = run_backtest(px, alternating(px), cfg(stops=Stops(sl_pct=0.05)),
+                       bars_per_year=BARS_PER_YEAR)
+    t = res.trades.iloc[0]
+    expected = t["net_pnl"] / (0.05 * t["entry_px"] * t["size"])
+    assert t["r_multiple"] == pytest.approx(expected, rel=1e-9)
+
+
+def test_unavailable_presets_refuse_to_run():
+    px = prices(n=100, seed=67)
+    with pytest.raises(ValueError, match="never executes untrusted code"):
+        strategies.build("Custom (code)", px)
+    with pytest.raises(ValueError, match="second leg"):
+        strategies.build("Pairs Trading", px)
+
+
+def test_forecast_follower_requires_signals():
+    px = prices(n=100, seed=68)
+    with pytest.raises(ValueError, match="needs stored model signals"):
+        strategies.build("Chronos Forecast Follower", px, {}, signals=None)
+
+
+def test_default_run_completes_well_under_two_seconds():
+    """Perf budget: a 3-year daily run must leave room for chart building."""
+    px = prices(n=365 * 3, seed=69)
+    out = strategies.build("SMA Crossover", px, {"fast_ma": 20, "slow_ma": 50})
+    res = run_backtest(px, out, cfg(strategy="SMA Crossover", costs=Costs(enabled=True),
+                                    validation=Validation(mode="walk_forward")),
+                       bars_per_year=BARS_PER_YEAR)
+    assert res.elapsed_s < 2.0, f"engine took {res.elapsed_s:.2f}s"

tests/test_extension.py

@@ -0,0 +1,307 @@
+"""Phase 4 acceptance: extend flow, dedup, quota fallback, manifest atomicity.
+
+Auth and GPU inference are both mocked, so these run offline and deterministically.
+"""
+
+from __future__ import annotations
+
+import sys
+import threading
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from src import config, extension, runtime
+from src.extension import ExtensionError, add_model, estimate, extend_coverage
+from src.store import SignalStore
+
+
+@dataclass
+class FakeProfile:
+    username: str
+
+
+def ohlcv(n=900, start="2023-01-01", freq="D"):
+    rng = np.random.default_rng(4)
+    close = pd.Series(100 * np.exp(np.cumsum(rng.normal(0.0004, 0.02, n))))
+    ts = pd.date_range(start, periods=n, freq=freq, tz="UTC")
+    return pd.DataFrame({
+        "ts": ts, "open": close * 0.999, "high": close * 1.02,
+        "low": close * 0.98, "close": close, "volume": 1000.0, "source": "test",
+    })
+
+
+@pytest.fixture
+def wired(tmp_path, monkeypatch):
+    """A fresh offline store wired into runtime, with GPU inference mocked."""
+    store = SignalStore(repo_id=None, local_root=tmp_path / "store", offline=True)
+    store.write_prices("BTC-USD", "1d", ohlcv())
+    monkeypatch.setattr(runtime, "_store", store, raising=False)
+    monkeypatch.setattr(runtime, "get_store", lambda: store)
+    monkeypatch.setattr(extension, "HAS_SPACES", True)
+    runtime.cache_clear()
+
+    calls = {"n": 0}
+
+    def fake_inference(model_id, family, values, ctx_len):
+        calls["n"] += 1
+        arr = np.asarray(values, dtype="float64")
+        last = arr[:, -1]
+        return {
+            "q10": (last * 0.97).tolist(), "q50": last.tolist(),
+            "q90": (last * 1.03).tolist(), "context_len": int(ctx_len),
+            "revision": "deadbeef", "inference_version": "1.0.0+test.deadbeef",
+        }
+
+    monkeypatch.setattr(extension, "run_inference", fake_inference)
+    return store, calls
+
+
+# --------------------------------------------------------------------------
+# Auth gating
+# --------------------------------------------------------------------------
+
+
+def test_anonymous_users_cannot_extend(wired):
+    html, _ = extension.extend_ui("chronos-bolt-small", "BTC-USD", "1d",
+                                  "2024-01-01", "2024-06-01", profile=None)
+    assert "Sign in with Hugging Face" in html
+    assert "spends your own GPU quota" in html
+
+
+def test_anonymous_users_cannot_add_models(wired):
+    html, _ = extension.add_model_ui("chronos", "amazon/chronos-bolt-small", profile=None)
+    assert "Sign in" in html
+
+
+def test_signed_in_user_can_extend(wired):
+    store, calls = wired
+    html, cov = extension.extend_ui("chronos-bolt-small", "BTC-USD", "1d",
+                                    "2024-01-01", "2024-06-01",
+                                    profile=FakeProfile("alice"))
+    assert "Coverage extended by <b>@alice</b>" in html
+    assert calls["n"] == 1
+    assert not cov.empty
+
+
+def test_contribution_is_attributed_to_the_user(wired):
+    store, _ = wired
+    extend_coverage("chronos-bolt-small", "BTC-USD", "1d",
+                    "2024-01-01", "2024-06-01", username="bob")
+    entries = store.load_manifest().find_signals(model_slug="chronos-bolt-small")
+    assert entries and entries[0].contributed_by == "bob"
+
+
+# --------------------------------------------------------------------------
+# Dedup — never recompute covered ranges
+# --------------------------------------------------------------------------
+
+
+def test_second_identical_request_recomputes_nothing(wired):
+    store, calls = wired
+    first = extend_coverage("chronos-bolt-small", "BTC-USD", "1d",
+                            "2024-01-01", "2024-06-01", username="alice")
+    assert "Coverage extended" in first
+    assert calls["n"] == 1
+
+    second = extend_coverage("chronos-bolt-small", "BTC-USD", "1d",
+                             "2024-01-01", "2024-06-01", username="alice")
+    assert "already covered" in second
+    assert calls["n"] == 1, "inference ran again for an already-covered range"
+
+
+def test_estimate_reports_already_covered(wired):
+    extend_coverage("chronos-bolt-small", "BTC-USD", "1d",
+                    "2024-01-01", "2024-06-01", username="alice")
+    est = estimate("chronos-bolt-small", "BTC-USD", "1d", "2024-02-01", "2024-05-01")
+    assert est.already_covered
+
+
+def test_estimate_counts_steps_for_an_uncovered_range(wired):
+    est = estimate("chronos-bolt-small", "BTC-USD", "1d", "2024-01-01", "2024-06-01")
+    assert est.steps > 0 and not est.already_covered
+
+
+# --------------------------------------------------------------------------
+# Guardrails
+# --------------------------------------------------------------------------
+
+
+def test_range_is_capped_per_timeframe(wired):
+    est = estimate("chronos-bolt-small", "BTC-USD", "1d", "2015-01-01", "2025-01-01")
+    assert est.capped
+    assert (est.end - est.start).days <= config.CAPS.max_days["1d"]
+    assert "cap" in est.note
+
+
+def test_steps_never_exceed_the_per_run_ceiling(wired):
+    est = estimate("chronos-bolt-small", "BTC-USD", "1d", "2023-01-01", "2025-01-01")
+    assert est.steps <= config.CAPS.max_steps_per_run
+
+
+@pytest.mark.parametrize("bad", [
+    ("nope-model", "BTC-USD", "1d"),
+    ("chronos-bolt-small", "DOGE-USD", "1d"),
+    ("chronos-bolt-small", "BTC-USD", "3y"),
+])
+def test_unknown_selections_are_rejected(wired, bad):
+    with pytest.raises(ExtensionError):
+        estimate(bad[0], bad[1], bad[2], "2024-01-01", "2024-06-01")
+
+
+def test_inverted_range_is_rejected(wired):
+    with pytest.raises(ExtensionError, match="start must be before end"):
+        estimate("chronos-bolt-small", "BTC-USD", "1d", "2024-06-01", "2024-01-01")
+
+
+def test_extension_requires_existing_price_coverage(wired):
+    with pytest.raises(ExtensionError, match="No cached prices"):
+        estimate("chronos-bolt-small", "ETH-USD", "1d", "2024-01-01", "2024-06-01")
+
+
+def test_add_model_rejects_hostile_ids(wired):
+    for bad in ("../../etc/passwd", "no-slash", "owner/name;rm -rf /"):
+        html = add_model("chronos", bad, username="alice")
+        assert "not a valid Hub model id" in html or "not allowed" in html
+
+
+def test_add_model_rejects_families_off_the_allow_list(wired):
+    html = add_model("evil", "someone/backdoor", username="alice")
+    assert "not on the allow-list" in html
+
+
+def test_add_model_smoke_test_registers_on_success(wired):
+    store, calls = wired
+    html = add_model("chronos", "amazon/chronos-bolt-small", username="carol")
+    assert "Smoke test passed" in html
+    assert calls["n"] == 1
+    slugs = {e.model_slug for e in store.load_manifest().signals.values()}
+    assert "chronos-bolt-small" in slugs
+
+
+# --------------------------------------------------------------------------
+# Quota exhaustion
+# --------------------------------------------------------------------------
+
+
+def test_quota_exhaustion_renders_the_duplicate_space_fallback(wired, monkeypatch):
+    def boom(*a, **k):
+        raise RuntimeError("ZeroGPU quota exceeded for this account")
+
+    monkeypatch.setattr(extension, "run_inference", boom)
+    html = extend_coverage("chronos-bolt-small", "BTC-USD", "1d",
+                           "2024-01-01", "2024-06-01", username="alice")
+    assert "quota is exhausted" in html
+    assert "duplicate=true" in html
+
+
+@pytest.mark.parametrize("message", [
+    "GPU task aborted", "ZeroGPU quota exceeded", "No GPU available right now",
+])
+def test_quota_errors_are_recognised(message):
+    assert extension._is_quota_error(RuntimeError(message))
+
+
+def test_ordinary_errors_are_not_mistaken_for_quota_errors(wired, monkeypatch):
+    monkeypatch.setattr(extension, "run_inference",
+                        lambda *a, **k: (_ for _ in ()).throw(ValueError("bad tensor shape")))
+    html = extend_coverage("chronos-bolt-small", "BTC-USD", "1d",
+                           "2024-01-01", "2024-06-01", username="alice")
+    assert "quota" not in html.lower()
+    assert "bad tensor shape" in html
+
+
+# --------------------------------------------------------------------------
+# Manifest atomicity under concurrent writers
+# --------------------------------------------------------------------------
+
+
+def test_parallel_extensions_do_not_corrupt_the_manifest(wired):
+    """Simulated parallel writers must leave a valid, complete manifest."""
+    store, calls = wired
+    store.write_prices("ETH-USD", "1d", ohlcv())
+    store.write_prices("SOL-USD", "1d", ohlcv())
+
+    targets = [("BTC-USD", "alice"), ("ETH-USD", "bob"), ("SOL-USD", "carol")]
+    errors: list[Exception] = []
+    barrier = threading.Barrier(len(targets))
+
+    def worker(asset, user):
+        try:
+            barrier.wait(timeout=10)  # maximise overlap
+            extend_coverage("chronos-bolt-small", asset, "1d",
+                            "2024-01-01", "2024-06-01", username=user)
+        except Exception as e:
+            errors.append(e)
+
+    threads = [threading.Thread(target=worker, args=t) for t in targets]
+    for t in threads:
+        t.start()
+    for t in threads:
+        t.join(timeout=60)
+
+    assert not errors, f"concurrent extensions raised: {errors}"
+
+    # Manifest must still validate and hold every contribution.
+    m = store.load_manifest(force=True)
+    m.validate()
+    assets = {e.asset for e in m.signals.values()}
+    assert assets == {"BTC-USD", "ETH-USD", "SOL-USD"}
+    contributors = {e.contributed_by for e in m.signals.values()}
+    assert contributors == {"alice", "bob", "carol"}
+
+    # And every referenced slice must actually exist and be readable.
+    for e in m.signals.values():
+        df = store.get_signals(e.model_slug, e.asset, e.timeframe)
+        assert not df.empty, f"manifest references an empty slice for {e.key}"
+
+
+def test_repeated_parallel_requests_for_the_same_slice_run_inference_once(wired):
+    store, calls = wired
+    barrier = threading.Barrier(4)
+
+    def worker():
+        barrier.wait(timeout=10)
+        extend_coverage("chronos-bolt-small", "BTC-USD", "1d",
+                        "2024-01-01", "2024-06-01", username="alice")
+
+    threads = [threading.Thread(target=worker) for _ in range(4)]
+    for t in threads:
+        t.start()
+    for t in threads:
+        t.join(timeout=60)
+
+    m = store.load_manifest(force=True)
+    m.validate()
+    entries = [e for e in m.signals.values() if e.asset == "BTC-USD"]
+    assert len(entries) == 1, "duplicate manifest entries for the same slice"
+
+
+def test_write_lock_serialises_commits():
+    assert isinstance(extension._WRITE_LOCK, type(threading.Lock()))
+
+
+# --------------------------------------------------------------------------
+# CPU-only degradation
+# --------------------------------------------------------------------------
+
+
+def test_cpu_only_space_disables_extension_with_an_explanation(wired, monkeypatch):
+    monkeypatch.setattr(extension, "HAS_SPACES", False)
+    html, _ = extension.extend_ui("chronos-bolt-small", "BTC-USD", "1d",
+                                  "2024-01-01", "2024-06-01",
+                                  profile=FakeProfile("alice"))
+    assert "running on CPU" in html
+    assert "works normally" in html
+
+
+def test_status_html_states_which_mode_the_space_is_in(monkeypatch):
+    monkeypatch.setattr(extension, "HAS_SPACES", True)
+    assert "ZEROGPU AVAILABLE" in extension.status_html()
+    monkeypatch.setattr(extension, "HAS_SPACES", False)
+    assert "CPU" in extension.status_html()

tests/test_store.py

@@ -0,0 +1,361 @@
+"""Phase 0 acceptance: manifest round-trip, idempotent writes, price validation."""
+
+from __future__ import annotations
+
+import json
+
+import pandas as pd
+import pytest
+
+from src import config
+from src.store import (
+    CoverageEntry,
+    Manifest,
+    PriceCoverage,
+    SchemaError,
+    SignalStore,
+    empty_manifest,
+    signal_key,
+    validate_price_frame,
+    validate_signal_frame,
+)
+
+
+# --------------------------------------------------------------------------
+# Fixtures
+# --------------------------------------------------------------------------
+
+
+@pytest.fixture
+def store(tmp_path) -> SignalStore:
+    return SignalStore(repo_id=None, local_root=tmp_path / "store", offline=True)
+
+
+def make_signals(n=30, start="2024-01-01", freq="D", base=100.0) -> pd.DataFrame:
+    ts = pd.date_range(start, periods=n, freq=freq, tz="UTC")
+    q50 = pd.Series([base + i for i in range(n)], dtype="float64")
+    return pd.DataFrame({
+        "ts": ts,
+        "q10": q50 * 0.97,
+        "q50": q50,
+        "q90": q50 * 1.03,
+        "context_len": 512,
+        "inference_version": config.INFERENCE_VERSION,
+    })
+
+
+def make_prices(n=30, start="2024-01-01", freq="D", base=100.0) -> pd.DataFrame:
+    ts = pd.date_range(start, periods=n, freq=freq, tz="UTC")
+    close = pd.Series([base + i for i in range(n)], dtype="float64")
+    return pd.DataFrame({
+        "ts": ts,
+        "open": close * 0.99,
+        "high": close * 1.02,
+        "low": close * 0.98,
+        "close": close,
+        "volume": 1000.0,
+        "source": "test",
+    })
+
+
+# --------------------------------------------------------------------------
+# Manifest round-trip
+# --------------------------------------------------------------------------
+
+
+def test_empty_manifest_round_trips():
+    m = empty_manifest()
+    again = Manifest.from_json(m.to_json())
+    assert again.schema_version == config.MANIFEST_SCHEMA_VERSION
+    assert again.signals == {} and again.prices == {}
+
+
+def test_manifest_round_trip_preserves_entries():
+    m = empty_manifest()
+    m.upsert_signal(CoverageEntry(
+        model_slug="chronos-bolt-small", model_id="amazon/chronos-bolt-small",
+        model_revision="abc123", asset="BTC-USD", timeframe="1d",
+        start_ts="2022-01-01T00:00:00Z", end_ts="2024-12-31T00:00:00Z",
+        rows=1096, inference_version="1.0.0", last_updated="2026-08-15T00:00:00Z",
+        contributed_by="seed",
+    ))
+    m.upsert_price(PriceCoverage(
+        asset="BTC-USD", timeframe="1d", start_ts="2022-01-01T00:00:00Z",
+        end_ts="2024-12-31T00:00:00Z", rows=1096, sources=["binance"],
+        last_updated="2026-08-15T00:00:00Z",
+    ))
+
+    again = Manifest.from_json(m.to_json())
+    assert again.to_dict()["signals"] == m.to_dict()["signals"]
+    assert again.to_dict()["prices"] == m.to_dict()["prices"]
+
+    e = again.get_signal("chronos-bolt-small", "abc123", "BTC-USD", "1d")
+    assert e is not None and e.rows == 1096
+    assert e.key == signal_key("chronos-bolt-small", "abc123", "BTC-USD", "1d")
+
+
+def test_manifest_rejects_missing_schema_version():
+    with pytest.raises(SchemaError, match="schema_version"):
+        Manifest.from_json(json.dumps({"signals": {}, "prices": {}}))
+
+
+def test_manifest_rejects_future_schema_version():
+    with pytest.raises(SchemaError, match="newer than this app"):
+        Manifest.from_json(json.dumps({"schema_version": 999}))
+
+
+def test_manifest_rejects_malformed_json():
+    with pytest.raises(SchemaError, match="not valid JSON"):
+        Manifest.from_json("{not json")
+
+
+def test_manifest_rejects_inverted_range():
+    m = empty_manifest()
+    bad = CoverageEntry(
+        model_slug="m", model_id="o/m", model_revision="r", asset="BTC-USD",
+        timeframe="1d", start_ts="2024-12-31T00:00:00Z", end_ts="2022-01-01T00:00:00Z",
+        rows=1, inference_version="1.0.0", last_updated="x", contributed_by="seed",
+    )
+    with pytest.raises(SchemaError, match="start_ts after end_ts"):
+        m.upsert_signal(bad)
+
+
+def test_revision_is_part_of_identity():
+    """Two revisions of the same model are distinct coverage, never merged."""
+    m = empty_manifest()
+    for rev in ("rev-a", "rev-b"):
+        m.upsert_signal(CoverageEntry(
+            model_slug="chronos", model_id="amazon/chronos", model_revision=rev,
+            asset="BTC-USD", timeframe="1d", start_ts="2024-01-01T00:00:00Z",
+            end_ts="2024-02-01T00:00:00Z", rows=32, inference_version="1.0.0",
+            last_updated="x", contributed_by="seed",
+        ))
+    assert len(m.signals) == 2
+
+
+# --------------------------------------------------------------------------
+# Store persistence + idempotency
+# --------------------------------------------------------------------------
+
+
+def test_store_manifest_persists_to_disk(store, tmp_path):
+    store.write_signals("m1", "org/m1", "rev1", "BTC-USD", "1d", make_signals())
+    path = tmp_path / "store" / config.MANIFEST_PATH
+    assert path.exists()
+    reloaded = SignalStore(repo_id=None, local_root=tmp_path / "store", offline=True)
+    assert reloaded.load_manifest().get_signal("m1", "rev1", "BTC-USD", "1d").rows == 30
+
+
+def test_signal_write_is_idempotent(store):
+    df = make_signals(n=30)
+    first = store.write_signals("m1", "org/m1", "rev1", "BTC-USD", "1d", df)
+    second = store.write_signals("m1", "org/m1", "rev1", "BTC-USD", "1d", df)
+
+    assert first.rows == second.rows == 30
+    got = store.get_signals("m1", "BTC-USD", "1d")
+    assert len(got) == 30
+    assert not got.index.duplicated().any()
+
+
+def test_rewriting_a_slice_does_not_change_stored_values(store):
+    """Append-only: an existing ts keeps its original value."""
+    store.write_signals("m1", "org/m1", "rev1", "BTC-USD", "1d", make_signals(base=100.0))
+    before = store.get_signals("m1", "BTC-USD", "1d")["q50"].tolist()
+
+    conflicting = make_signals(base=999.0)
+    store.write_signals("m1", "org/m1", "rev1", "BTC-USD", "1d", conflicting)
+    after = store.get_signals("m1", "BTC-USD", "1d")["q50"].tolist()
+
+    assert before == after
+
+
+def test_extending_coverage_widens_range_and_adds_rows(store):
+    store.write_signals("m1", "org/m1", "rev1", "BTC-USD", "1d",
+                        make_signals(n=30, start="2024-01-01"))
+    entry = store.write_signals("m1", "org/m1", "rev1", "BTC-USD", "1d",
+                                make_signals(n=30, start="2024-02-01"))
+    assert entry.rows == 60
+    assert entry.start_ts.startswith("2024-01-01")
+    assert entry.end_ts.startswith("2024-03-01")
+    assert len(store.get_signals("m1", "BTC-USD", "1d")) == 60
+
+
+def test_write_spanning_year_boundary_splits_files(store, tmp_path):
+    store.write_signals("m1", "org/m1", "rev1", "BTC-USD", "1d",
+                        make_signals(n=60, start="2023-12-10"))
+    root = tmp_path / "store" / "signals" / "m1" / "BTC-USD" / "1d"
+    assert (root / "2023.parquet").exists()
+    assert (root / "2024.parquet").exists()
+    assert len(store.get_signals("m1", "BTC-USD", "1d")) == 60
+
+
+def test_coverage_across_years_counts_untouched_years(store):
+    store.write_signals("m1", "org/m1", "rev1", "BTC-USD", "1d",
+                        make_signals(n=20, start="2023-01-01"))
+    entry = store.write_signals("m1", "org/m1", "rev1", "BTC-USD", "1d",
+                                make_signals(n=20, start="2024-06-01"))
+    assert entry.rows == 40
+
+
+def test_has_coverage_and_missing_ranges(store):
+    assert not store.has_coverage("m1", "rev1", "BTC-USD", "1d")
+    store.write_signals("m1", "org/m1", "rev1", "BTC-USD", "1d",
+                        make_signals(n=30, start="2024-01-01"))
+
+    assert store.has_coverage("m1", "rev1", "BTC-USD", "1d",
+                              "2024-01-05", "2024-01-20")
+    assert not store.has_coverage("m1", "rev1", "BTC-USD", "1d",
+                                  "2023-01-01", "2024-01-20")
+
+    # Fully covered -> nothing to recompute. This is the extension dedup gate.
+    assert store.missing_ranges("m1", "rev1", "BTC-USD", "1d",
+                                "2024-01-05", "2024-01-20") == []
+    gaps = store.missing_ranges("m1", "rev1", "BTC-USD", "1d",
+                                "2023-06-01", "2024-06-01")
+    assert len(gaps) == 2
+
+
+def test_placeholder_coverage_can_be_excluded(store):
+    store.write_signals("m1", "org/m1", "rev1", "BTC-USD", "1d", make_signals(),
+                        inference_version=config.PLACEHOLDER_VERSION)
+    assert store.has_coverage("m1", "rev1", "BTC-USD", "1d")
+    assert not store.has_coverage("m1", "rev1", "BTC-USD", "1d",
+                                  allow_placeholder=False)
+
+
+def test_get_signals_respects_window(store):
+    store.write_signals("m1", "org/m1", "rev1", "BTC-USD", "1d",
+                        make_signals(n=30, start="2024-01-01"))
+    got = store.get_signals("m1", "BTC-USD", "1d", "2024-01-10", "2024-01-14")
+    assert len(got) == 5
+    assert str(got.index[0].date()) == "2024-01-10"
+
+
+def test_missing_coverage_returns_empty_frame_not_error(store):
+    got = store.get_signals("nope", "BTC-USD", "1d", "2024-01-01", "2024-02-01")
+    assert got.empty
+
+
+def test_pending_files_are_tracked_for_commit(store):
+    store.write_signals("m1", "org/m1", "rev1", "BTC-USD", "1d", make_signals())
+    pending = store.pending
+    assert config.MANIFEST_PATH in pending
+    assert any(p.startswith("signals/m1/BTC-USD/1d/") for p in pending)
+
+
+# --------------------------------------------------------------------------
+# Signal frame validation
+# --------------------------------------------------------------------------
+
+
+def test_signal_validation_rejects_crossed_quantiles():
+    df = make_signals(n=10)
+    df.loc[3, "q10"] = df.loc[3, "q90"] + 5  # q10 > q50 > q90
+    with pytest.raises(SchemaError, match="crossed quantiles"):
+        validate_signal_frame(df)
+
+
+def test_signal_validation_rejects_duplicate_timestamps():
+    df = make_signals(n=10)
+    df.loc[5, "ts"] = df.loc[4, "ts"]
+    with pytest.raises(SchemaError, match="duplicate timestamps"):
+        validate_signal_frame(df)
+
+
+def test_signal_validation_rejects_missing_columns():
+    df = make_signals(n=10).drop(columns=["q90"])
+    with pytest.raises(SchemaError, match="missing columns"):
+        validate_signal_frame(df)
+
+
+def test_signal_validation_normalises_naive_timestamps_to_utc():
+    df = make_signals(n=5)
+    df["ts"] = df["ts"].dt.tz_localize(None)
+    out = validate_signal_frame(df)
+    assert str(out["ts"].dt.tz) == "UTC"
+
+
+# --------------------------------------------------------------------------
+# Price validation — injected bad rows must be caught
+# --------------------------------------------------------------------------
+
+
+def test_price_validation_accepts_clean_frame():
+    out, report = validate_price_frame(make_prices(), "1d")
+    assert report.ok and report.gaps == 0 and len(out) == 30
+
+
+def test_price_validation_catches_negative_price():
+    df = make_prices()
+    df.loc[7, "close"] = -50.0
+    with pytest.raises(SchemaError, match="non-positive"):
+        validate_price_frame(df, "1d")
+
+
+def test_price_validation_catches_zero_price():
+    df = make_prices()
+    df.loc[2, "open"] = 0.0
+    with pytest.raises(SchemaError, match="non-positive"):
+        validate_price_frame(df, "1d")
+
+
+def test_price_validation_catches_duplicate_timestamps():
+    df = make_prices()
+    df.loc[9, "ts"] = df.loc[8, "ts"]
+    with pytest.raises(SchemaError, match="duplicate timestamps"):
+        validate_price_frame(df, "1d")
+
+
+def test_price_validation_catches_inconsistent_ohlc():
+    df = make_prices()
+    df.loc[4, "high"] = df.loc[4, "low"] - 1.0
+    with pytest.raises(SchemaError, match="inconsistent OHLC"):
+        validate_price_frame(df, "1d")
+
+
+def test_price_validation_catches_negative_volume():
+    df = make_prices()
+    df.loc[11, "volume"] = -1.0
+    with pytest.raises(SchemaError, match="negative"):
+        validate_price_frame(df, "1d")
+
+
+def test_price_validation_catches_nan_price():
+    df = make_prices()
+    df.loc[6, "close"] = float("nan")
+    with pytest.raises(SchemaError, match="NaN"):
+        validate_price_frame(df, "1d")
+
+
+def test_price_validation_reports_gaps_without_failing():
+    """A gap is a fact about coverage, not a validation failure."""
+    df = make_prices(n=30).drop(index=[10, 11, 12]).reset_index(drop=True)
+    out, report = validate_price_frame(df, "1d")
+    assert report.ok
+    assert report.gaps == 1
+    assert len(report.gap_ranges) == 1
+    assert len(out) == 27
+
+
+def test_price_validation_non_strict_collects_problems(make_bad=None):
+    df = make_prices()
+    df.loc[7, "close"] = -50.0
+    out, report = validate_price_frame(df, "1d", strict=False)
+    assert not report.ok
+    assert any("non-positive" in p for p in report.problems)
+
+
+def test_price_write_and_read_round_trip(store):
+    cov = store.write_prices("BTC-USD", "1d", make_prices(n=40))
+    assert cov.rows == 40 and cov.sources == ["test"]
+    got = store.get_prices("BTC-USD", "1d")
+    assert len(got) == 40
+    assert list(got.columns) == ["open", "high", "low", "close", "volume", "source"]
+
+
+def test_price_write_is_idempotent(store):
+    df = make_prices(n=40)
+    store.write_prices("BTC-USD", "1d", df)
+    cov = store.write_prices("BTC-USD", "1d", df)
+    assert cov.rows == 40
+    assert len(store.get_prices("BTC-USD", "1d")) == 40

tests/test_ui.py

@@ -0,0 +1,298 @@
+"""Phase 3 acceptance: the UI renders, and every displayed number is traceable.
+
+These run against the real cached store when it is present, and skip cleanly
+when it is not (a fresh clone with no `.cache/store` yet).
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+import pandas as pd
+import plotly.graph_objects as go
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+import app as bitapp
+from src import charts, comparisons, config, runtime, strategies
+from src.runtime import RunRequest
+
+
+def _store_ready() -> bool:
+    try:
+        m = runtime.get_store().load_manifest()
+        return len(m.prices) > 0
+    except Exception:
+        return False
+
+
+pytestmark = pytest.mark.skipif(not _store_ready(),
+                                reason="no cached signal store available")
+
+
+@pytest.fixture(scope="module")
+def rec():
+    return runtime.execute(RunRequest(
+        strategy="SMA Crossover", asset="BTC-USD", timeframe="1d", date_range="3Y",
+    ))
+
+
+@pytest.fixture(scope="module")
+def three_runs():
+    reqs = [
+        RunRequest(strategy="SMA Crossover", asset="BTC-USD", timeframe="1d", date_range="3Y"),
+        RunRequest(strategy="RSI Mean Reversion", asset="ETH-USD", timeframe="1d", date_range="3Y"),
+        RunRequest(strategy="Buy & Hold (benchmark)", asset="SPY", timeframe="1d", date_range="3Y"),
+    ]
+    return [runtime.execute(r) for r in reqs]
+
+
+# --------------------------------------------------------------------------
+# App construction
+# --------------------------------------------------------------------------
+
+
+def test_app_object_exists():
+    assert bitapp.demo is not None
+
+
+def test_theme_css_carries_the_design_tokens():
+    from src.ui import theme
+
+    css = theme.full_css()
+    for token in ("--bg-canvas", "--accent-amber", "--fin-up", "--font-styrene"):
+        assert token in css, f"{token} missing from theme CSS"
+    assert "#161512" in css  # stone-950 canvas
+    assert "#af9209" in css  # accent amber
+
+
+def test_disclaimer_is_present_in_the_footer():
+    assert "not indicative of future results" in bitapp.FOOTER_HTML
+    assert "Not financial advice" in bitapp.FOOTER_HTML or \
+           "not a licensed investment adviser" in bitapp.FOOTER_HTML
+
+
+def test_empty_state_offers_the_worked_example():
+    assert "No run loaded" in bitapp.EMPTY_HTML
+    assert "worked example" in bitapp.EMPTY_HTML
+
+
+def test_glossary_covers_every_design_term():
+    terms = {t for t, _ in bitapp.GLOSSARY}
+    assert {"SHARPE", "SORTINO", "MAX DRAWDOWN", "PROFIT FACTOR",
+            "R-MULTIPLE", "MAE / MFE", "WALK-FORWARD", "OOS"} <= terms
+
+
+# --------------------------------------------------------------------------
+# The stat band must match engine output exactly
+# --------------------------------------------------------------------------
+
+
+def test_stat_band_values_match_engine_metrics(rec):
+    html = bitapp.stat_band_html(rec)
+    m = rec.result.metrics_all
+
+    assert bitapp.pct(m.total_return) in html
+    assert bitapp.pct(m.cagr) in html
+    assert bitapp.num(m.sharpe) in html
+    assert bitapp.num(m.sortino) in html
+    assert bitapp.pct(m.max_drawdown) in html
+    assert bitapp.num(m.profit_factor) in html
+    assert f">{m.trade_count}<" in html
+
+
+def test_stat_band_shows_is_and_oos_for_every_stat(rec):
+    html = bitapp.stat_band_html(rec)
+    assert html.count("IS ") >= 9
+    assert html.count("· OOS") >= 9
+    assert bitapp.num(rec.result.metrics_oos.sharpe) in html
+    assert bitapp.num(rec.result.metrics_is.sharpe) in html
+
+
+def test_stat_band_reports_costs_actually_paid(rec):
+    html = bitapp.stat_band_html(rec)
+    assert bitapp.money(rec.result.costs_paid) in html
+    assert rec.result.costs_paid > 0, "costs default to ON, so this must be positive"
+
+
+def test_empty_segment_renders_an_em_dash_not_a_zero():
+    """A segment with no bars must not read as 0.00."""
+    short = runtime.execute(RunRequest(
+        strategy="SMA Crossover", asset="BTC-USD", timeframe="1h", date_range="1Y"))
+    if short.result.metrics_oos.bars:
+        pytest.skip("this range did produce OOS windows")
+    html = bitapp.stat_band_html(short)
+    assert "· OOS —" in html
+    assert "no out-of-sample windows" in html
+
+
+def test_trade_table_rows_match_the_engine_trade_list(rec):
+    df = bitapp.trades_frame(rec)
+    assert len(df) == len(rec.result.trades)
+    if len(df):
+        assert df["Net"].iloc[0] == pytest.approx(
+            round(float(rec.result.trades["net_pnl"].iloc[0]), 2))
+        assert set(df["Segment"]) <= {"IS", "OOS", "holdout"}
+        assert (df["Costs"] >= 0).all()
+
+
+def test_report_quotes_the_same_numbers_as_the_stat_band(rec):
+    md = bitapp.report_markdown(rec)
+    assert bitapp.pct(rec.result.metrics_all.total_return) in md
+    assert bitapp.money(rec.result.costs_paid) in md
+    assert rec.run_id in md
+
+
+def test_costs_off_is_called_out_as_not_real():
+    off = runtime.execute(RunRequest(
+        strategy="SMA Crossover", asset="BTC-USD", timeframe="1d",
+        date_range="3Y", costs_on=False))
+    _, _, _, _, _, _, _, _, note = bitapp.build_overview(off, log_scale=False, cvd=False)
+    assert "COSTS ARE OFF" in note
+    assert off.result.costs_paid == 0.0
+
+
+# --------------------------------------------------------------------------
+# Charts
+# --------------------------------------------------------------------------
+
+
+def test_overview_builds_every_figure(rec):
+    figs = bitapp.build_overview(rec, log_scale=False, cvd=False)
+    assert len(figs) == 9
+    for f in figs[:8]:
+        assert isinstance(f, go.Figure)
+    assert isinstance(figs[8], str)
+
+
+def test_log_scale_and_colorblind_variants_render(rec):
+    for log_s in (False, True):
+        for cb in (False, True):
+            figs = bitapp.build_overview(rec, log_scale=log_s, cvd=cb)
+            assert isinstance(figs[0], go.Figure)
+
+
+def test_equity_chart_marks_the_holdout_band(rec):
+    fig = charts.equity_curve(rec.result.equity, rec.result.benchmark_equity,
+                              plan=rec.result.plan)
+    if rec.result.plan.holdout_start is not None:
+        texts = [str(a.text) for a in fig.layout.annotations]
+        assert any("HOLDOUT" in t for t in texts)
+
+
+def test_charts_survive_empty_inputs():
+    empty = pd.Series(dtype="float64")
+    assert isinstance(charts.equity_curve(empty), go.Figure)
+    assert isinstance(charts.underwater_chart(empty), go.Figure)
+    assert isinstance(charts.pnl_histogram(pd.DataFrame()), go.Figure)
+    assert isinstance(charts.mae_mfe_scatter(pd.DataFrame()), go.Figure)
+    assert isinstance(charts.walk_forward_bars([]), go.Figure)
+    assert isinstance(charts.monte_carlo_cone(None), go.Figure)
+
+
+def test_colorblind_palette_differs_from_default():
+    assert charts.up_color(cvd=True) != charts.up_color(cvd=False)
+    assert charts.down_color(cvd=True) != charts.down_color(cvd=False)
+
+
+# --------------------------------------------------------------------------
+# Comparison tab with three runs
+# --------------------------------------------------------------------------
+
+
+def test_comparison_renders_three_runs(three_runs):
+    curves = {r.label[:28]: r.result.equity for r in three_runs}
+    rets = {r.label[:28]: r.result.equity.pct_change().dropna() for r in three_runs}
+
+    assert len(curves) == 3
+    assert isinstance(charts.overlaid_returns(curves), go.Figure)
+    assert isinstance(charts.small_multiples(curves), go.Figure)
+
+    corr = charts.correlation_matrix(rets)
+    assert isinstance(corr, go.Figure)
+    assert len(corr.data[0].z) == 3
+
+
+def test_comparison_respects_the_six_run_cap():
+    assert bitapp.MAX_COMPARE == 6
+
+
+def test_precomputed_heatmap_loads_from_the_store():
+    heat = comparisons.load_table(runtime.get_store(), comparisons.HEATMAP)
+    if heat.empty:
+        pytest.skip("comparison tables not generated yet")
+    assert {"asset", "strategy", "timeframe", "oos_sharpe"} <= set(heat.columns)
+    assert isinstance(charts.strategy_timeframe_heatmap(heat), go.Figure)
+
+
+def test_regime_breakdown_covers_the_named_regimes(rec):
+    df = runtime.regime_breakdown(rec)
+    if df.empty:
+        pytest.skip("no regime variation in this window")
+    assert set(df["regime"]) <= {"BULL", "BEAR", "CHOP"}
+
+
+# --------------------------------------------------------------------------
+# Coverage map & share links
+# --------------------------------------------------------------------------
+
+
+def test_coverage_map_renders_from_the_live_manifest():
+    df = runtime.coverage_frame()
+    assert not df.empty
+    assert {"Model", "Asset", "TF", "Coverage", "Rows", "Real?"} <= set(df.columns)
+
+
+def test_placeholder_slices_are_labelled_in_the_coverage_map():
+    df = runtime.coverage_frame()
+    assert set(df["Real?"]) <= {"real", "PLACEHOLDER"}
+
+
+def test_share_link_round_trips():
+    req = RunRequest(strategy="RSI Mean Reversion", asset="ETH-USD",
+                     timeframe="1h", date_range="1Y", params={"rsi_period": 21})
+    again = RunRequest.decode(req.encode())
+    assert again.strategy == req.strategy
+    assert again.asset == req.asset
+    assert again.params["rsi_period"] == 21
+
+
+@pytest.mark.parametrize("payload", [
+    '{"strategy":"__import__(\'os\').system","asset":"BTC-USD"}',
+    '{"strategy":"SMA Crossover","asset":"../../etc/passwd"}',
+    '{"strategy":"SMA Crossover","asset":"BTC-USD","timeframe":"99y"}',
+    '{"strategy":"SMA Crossover","asset":"BTC-USD","validation_mode":"eval"}',
+])
+def test_hostile_share_links_are_rejected(payload):
+    import base64
+
+    token = base64.urlsafe_b64encode(payload.encode()).decode().rstrip("=")
+    with pytest.raises(ValueError):
+        RunRequest.decode(token)
+
+
+def test_unavailable_presets_are_listed_but_refuse_to_run():
+    assert "Custom (code)" in strategies.PRESETS
+    assert not strategies.PRESETS["Custom (code)"].available
+    with pytest.raises(runtime.RunError, match="never executes untrusted code"):
+        runtime.execute(RunRequest(strategy="Custom (code)", asset="BTC-USD"))
+
+
+# --------------------------------------------------------------------------
+# Performance budget
+# --------------------------------------------------------------------------
+
+
+def test_default_three_year_daily_run_is_under_two_seconds():
+    runtime.cache_clear()
+    req = RunRequest(strategy="SMA Crossover", asset="BTC-USD",
+                     timeframe="1d", date_range="3Y")
+    runtime.execute(req)  # warm the slice cache
+    import time
+
+    t0 = time.perf_counter()
+    runtime.execute(req)
+    assert time.perf_counter() - t0 < 2.0