Add HANDOFF.md

HANDOFF.md

@@ -0,0 +1,166 @@
+# Backtest Lab v1.0.0 — Handoff
+
+Built end-to-end and deployed. Everything below was verified against the **live
+Space**, not just locally.
+
+## Live URLs
+
+| What | URL |
+|---|---|
+| **Backtest Lab** (Space) | https://huggingface.co/spaces/Bit-Trading-Company/bit-backtest-lab |
+| Direct app | https://bit-trading-company-bit-backtest-lab.hf.space |
+| **Signal store** (Dataset) | https://huggingface.co/datasets/The-Bit-Trading-Company/bit-signal-store |
+
+Both tagged `v1.0.0`. Space stage: **RUNNING** on **`zero-a10g` (ZeroGPU)**.
+
+## Deployment status
+
+| Check | Result |
+|---|---|
+| Build | ✅ 142s build + ~30s app start |
+| Cold start (app boot) | ✅ ~30s, under the 60s budget |
+| HTTP response | ✅ 200 in 0.74s |
+| Hardware | ✅ ZeroGPU (`zero-a10g`) **granted** — no billing escalation needed |
+| Example config end-to-end | ✅ `/load_example` returns the design's worked example |
+| Backtest on live Space | ✅ +33.2%, 12 trades, $486 costs — **bit-identical to local** |
+| Warm run time | ✅ **0.1s** engine time for a 3-year daily run (budget: <2s) |
+| Coverage map from live manifest | ✅ 18 rows, all labelled `real` |
+| Login button | ✅ present; `/login/huggingface` returns 302 |
+| ZeroGPU detected in-app | ✅ "ZEROGPU AVAILABLE · EXTENSION RUNS ON YOUR OWN QUOTA" |
+
+## Tests: all green
+
+`bash tests/run_all.sh --slow` → **191 passed**, run with `-W error::FutureWarning`.
+
+Verified on **both** Python 3.11 (dev) and **Python 3.10** (what the ZeroGPU
+image actually provides) — 190 offline + 1 real-model test.
+
+### The six known-answer tests
+
+| # | Test | Status |
+|---|---|---|
+| 1 | Buy & Hold, zero costs, reproduces the asset return (tol 1e-9) | ✅ |
+| 2 | Deliberately lookahead-biased strategy is caught structurally | ✅ |
+| 3 | Zero-cost vs costed run differ by exactly the modelled costs | ✅ |
+| 4 | Zero-signal strategy → flat equity, zero trades | ✅ |
+| 5 | Walk-forward train/test never overlap; holdout untouched by selection | ✅ |
+| 6 | Same config + same data → bit-identical results | ✅ |
+
+31 tests cover these six directly. Test 2 catches three distinct cheats:
+reading bar `t+1`, a centred rolling window, and full-sample normalisation.
+
+## Spec compliance
+
+- ✅ **No lookahead paths.** Enforced two ways: the engine applies the one-bar
+  shift itself (a strategy cannot bypass it), and `assert_causal` proves it by
+  perturbing future prices up *and* down and requiring earlier outputs to be
+  bit-identical. All seven shipped presets pass.
+- ✅ **Fills at next bar open.** `fill` accepts only `next_open`; anything else
+  raises. A test asserts the entry price equals bar 1's open, not bar 0's.
+- ✅ **Costs default ON.** `Costs().enabled is True`. `gross − costs = net` holds
+  to 1e-9 on every trade row. Costs-off runs are labelled "these numbers are
+  not achievable" in the UI.
+- ✅ **Every displayed metric traceable to engine output.** The stat band, trade
+  table and report are asserted against `metrics.py` values in `test_ui.py`.
+- ✅ **No placeholder slices remain.** All 18 signal slices are real
+  Chronos-Bolt output. The `PLACEHOLDER` labelling machinery is still present
+  and tested for contributors on weaker hardware.
+- ✅ **No arbitrary code execution.** Adapter families are allow-listed, model
+  ids are validated, `trust_remote_code` is never set, and the design's
+  `Custom (code)` preset is rendered disabled with an explanation.
+- ✅ **Token hygiene.** Scanned every file in both repos: the token appears in
+  none of them. It exists only in the local gitignored `key.txt` and as the
+  `HF_WRITE_TOKEN` Space secret.
+
+## What shipped
+
+**Signal store** — 18 signal slices / **60,375 real rows** across
+`chronos-bolt-small` + `chronos-bolt-base`, 6 assets (BTC, ETH, SOL, SPY, QQQ,
+NVDA) × 3 timeframes (1d, 1h, 15m); 15 price slices; 4 precomputed comparison
+tables (model performance, calibration, directional accuracy, strategy×timeframe
+heatmap).
+
+**Derived data worth reading**: Chronos-Bolt is consistently **over-dispersed** —
+its nominal 80% q10–q90 band actually covers 83–89% of outcomes across every
+slice. Worth knowing before trusting a q10 stop level.
+
+**Engine** — vectorbt, next-bar-open fills, commission + fixed/volume-scaled
+slippage, SL/TP/trailing stops, fixed-% and vol-target sizing, three validation
+modes with a locked holdout, full IS/OOS/holdout metric split, trade list with
+R-multiple, MAE/MFE and per-trade trigger reasons.
+
+**UI** — the design implemented in Gradio Blocks with the Bit design system
+vendored verbatim (tokens + Styrene/Mac Minecraft fonts): Strategy Builder
+(5 numbered sections), Results Canvas (Overview / Trades / Comparison /
+Robustness / Report / Coverage), Run Manager, pinned disclaimer footer.
+
+## ⚠️ Human-verify checklist
+
+These need a real human with a real account — I cannot complete them:
+
+1. **OAuth login end-to-end.** The button renders and `/login/huggingface`
+   redirects correctly, but I cannot complete a real sign-in. Click
+   *Sign in with Hugging Face* and confirm you land back signed in.
+   If it fails, check Space settings → the `hf_oauth: true` header is set in
+   `README.md` and may need the owner to approve the OAuth app once.
+2. **ZeroGPU extension with a real account.** Sign in, open the **Coverage**
+   tab, pick an uncovered range, press *Estimate* then *Extend coverage*.
+   Confirm: progress stages appear, the commit lands in the dataset repo, and
+   the toast reads "Coverage extended by @you". This is the only path that
+   spends real GPU quota, so it is untested against real hardware.
+3. **Add-model flow** with a real Hub model id, same reason.
+4. **Torch version difference.** The Space runs torch **2.11.0** (ZeroGPU only
+   accepts 2.11/2.10/2.9.1/2.8); my adapter smoke test ran locally on 2.13.0.
+   The first real ZeroGPU extension doubles as the check that Chronos inference
+   behaves identically on 2.11.
+5. **Visual pass on a real screen.** I verified the UI functionally and via
+   screenshots, but the in-app browser stalled before I could click through
+   every tab at full size. Worth a human eye on the Comparison and Robustness
+   tabs with several runs loaded.
+
+## Open items from DECISIONS.md
+
+- **D-001 — Space is under the personal namespace.** Gradio Spaces under an org
+  need a paid Team/Enterprise plan (402). You chose the personal namespace; the
+  dataset stays under the org. To move it later, subscribe and re-point
+  `BIT_SPACE_REPO`.
+- **D-006 — Binance is geo-blocked (451)** from the seeding machine; crypto came
+  from Coinbase via the fallback chain. **Stooq now serves an HTML block page**,
+  so the equity chain effectively runs on yfinance alone. Tiingo is wired but
+  needs a `TIINGO_KEY` secret to join the chain.
+- **Sentiment is a stub.** `Sentiment-Gated Momentum` runs on a labelled,
+  deterministic price-derived proxy behind a `SentimentSource` interface — not
+  news sentiment. Wiring a real feed is the obvious next task.
+- **Pairs Trading** is in the design's preset list but not runnable in v1
+  (needs a second leg). It is shown disabled with that reason.
+- **Equity intraday depth** is provider-capped (~730d hourly, ~60d 15m) and
+  recorded in the manifest as `provider_max_days`, not hidden.
+
+## Things I'd flag as genuinely uncertain
+
+- The **example strategy loses money on the locked holdout** (−5.2%, Sharpe
+  −0.38). That is the system working: the holdout is doing its job and the app
+  reports it rather than burying it. Don't read the headline +33.2% as a result.
+- **Walk-forward on short ranges produces no OOS windows at all.** The app now
+  says so explicitly instead of printing `0.00`, but it is easy to configure a
+  run that looks complete and has no out-of-sample content. Watch for the red
+  note.
+- **`vectorbt` is pinned to 1.0.0**, not the 1.1.0 I developed against, because
+  1.1.0 requires Python ≥3.11 and the ZeroGPU image is 3.10. The full suite
+  passes on both, but that is a real version skew between dev and prod.
+
+## Repo layout
+
+```
+hugging-face/
+  key.txt            local only, gitignored, never committed
+  DECISIONS.md       15 logged decisions across all phases
+  HANDOFF.md         this file
+  ops/               provisioning scripts (local only, not deployed)
+  store_stage/       dataset card staging
+  space/             → pushed to the Space
+    app.py  src/{store,data,engine,strategies,adapters,charts,metrics,
+                 comparisons,runtime,extension,config,ui/theme}.py
+    scripts/seed_store.py   tests/ (191)   assets/ (vendored design system)
+    DESIGN_NOTES.md  the extracted design contract Phase 3 was built against
+```