DECISIONS.md

# DECISIONS

Running log of choices the build spec left open, and of anything that failed.
Newest phase last.

---

## Phase −1 — Provisioning

### D-001 — The Space lives under the personal namespace, not the org — **decided by the human**

`create_repo(..., repo_type="space", space_sdk="gradio")` under
`The-Bit-Trading-Company` returns **402 Payment Required**:

> Static Spaces are free for everyone, but hosting Gradio and Docker Spaces on
> free cpu-basic requires a Team or Enterprise plan for organization
> The-Bit-Trading-Company.

Verified this is a plan limit, not a token-scope problem: the token has
`repo.write` on the org, the dataset repo created fine under the org, and a
*static* Space probe under the org succeeded. The org has no paid plan; the
owner's personal account is PRO.

This hit the "anything requiring payment" flag, so it went to the human, who
chose the personal namespace.

| Repo | Location |
|---|---|
| Signal store (dataset) | `The-Bit-Trading-Company/bit-signal-store` |
| Backtest Lab (Space) | `Bit-Trading-Company/bit-backtest-lab` |

The shared data asset keeps the company namespace; only the app URL changes.
The personal account being PRO means ZeroGPU is still available for Phase 4, so
no capability is lost. Moving the Space to the org later is a rename, and
`src/config.py` reads both ids from env (`BIT_SPACE_REPO`, `BIT_STORE_REPO`).

### D-002 — Python 3.11 toolchain

The machine had only Python 3.14, which numba (and therefore vectorbt) does not
support. Used `uv` to install 3.11.15 into a local `.venv`. Final resolved
stack: vectorbt 1.1.0, numpy 2.4.6, pandas 2.3.3, numba 0.67.0, pyarrow 25.0.1,
plotly 6.9.0, gradio 5.49.1. `requirements.txt` pins these for the Space, and
the Space is pinned to `python_version: "3.11"` to match.

### D-003 — Writes are one atomic commit, not "manifest last"

The spec asks for `CommitScheduler` with "atomic manifest update last". A single
`create_commit` carrying the parquet slices *and* the manifest is strictly
stronger: readers can never observe a manifest referencing a slice that has not
landed yet. `SignalStore.flush()` does that, ordering the manifest as the final
operation within the commit. `SignalStore.attach_scheduler()` still provides
`CommitScheduler`-based background batching for the running Space, pointed at
the same local mirror, so the two paths cannot disagree about what is on disk.

### D-004 — `Custom (code)` preset is present but inert

The design's preset list ends with `Custom (code)`, backed by a code editor. The
build spec says "No arbitrary code execution from user input anywhere", which is
the stronger constraint. The control is rendered, disabled, with an explanation,
rather than silently dropped from the design — see `DESIGN_NOTES.md`.

### D-005 — Design source recovered from local files

`claude.ai/design/p/00cbd10f…` returned 403 to every unauthenticated fetch and
no Chrome instance was connected, so the design was unreachable at first. The
human supplied the export locally. The Bit design system tokens and fonts are
vendored verbatim into `space/assets/`; `space/DESIGN_NOTES.md` records the
extracted layout, copy and component inventory that Phase 3 is built against.

### Provisioning results

| Action | Result |
|---|---|
| `whoami` with token | OK — user `Bit-Trading-Company`, PRO, admin of the org |
| Token scope | fine-grained; `repo.write` on org + user |
| Create dataset `The-Bit-Trading-Company/bit-signal-store` | **created**, public |
| Create Space under org | **failed, 402** — see D-001 |
| Create Space `Bit-Trading-Company/bit-backtest-lab` | **created**, gradio, cpu-basic, public |
| Space secret `HF_WRITE_TOKEN` | **set** via API; value never logged or committed |
| Signal store init | **committed** — `manifest.json` (schema_version 1), `signals/ prices/ comparisons/ runs/`, dataset card |
| Hardware `zero-a10g` | not yet requested — deferred to Phase 4 per spec |

Token hygiene: the value lives only in the local `key.txt` (gitignored at the
repo root) and in the Space secret. It appears in no source file, no committed
config, and no log line. `.env.example` documents variable names only.

---

## Phase 0 — Data layer

### D-006 — Providers are config; both primaries failed and the chain absorbed it

Two provider-level blocks appeared during seeding, and both were handled by the
fallback chain rather than by editing code:

- **Binance returns HTTP 451** ("restricted location") from the seeding machine.
  Crypto OHLCV therefore came from **Coinbase**, the configured fallback.
- **Stooq now serves an HTML block page** instead of CSV. `data.py` detects the
  missing CSV header and advances the chain, so equities ran on **yfinance**.

Neither was silently swallowed: every fallback is recorded in the fetch result's
notes, and `source` is stored per price row. Recorded here rather than escalated
because the spec's flag-to-human bar is provider blocking that persists *after
backoff and fallback exhaustion* — the fallbacks succeeded.

### D-007 — Equity gap counts are calendar gaps, not data faults

Daily equity series report ~171 "gaps" over three years. Those are weekends and
holidays. The gap report measures distance from a continuous bar grid and is
surfaced as information; it never fails validation.

## Phase 1 — Engine

### D-008 — Causality is checked by perturbation, in both directions

The spec asks for a structural lookahead assertion. `assert_causal` scales the
tail of the price frame and requires every earlier output to be bit-identical.
Scaling **up only** proved insufficient: a boolean comparison that is already
`True` can survive an upward bump unchanged, and a peeking strategy slipped
through on one seed. The check now perturbs up *and* down at four probe points,
which catches obvious lookahead, centred rolling windows, and full-sample
normalisation.

### D-009 — R-multiple when no stop is configured

R is P&L over initial risk, and initial risk is the stop distance. With no stop
there is no such distance, so the engine falls back to
`risk_per_trade_pct` (default 2% of entry notional). It is a documented config
field rather than a hidden constant.

### D-010 — Costs are one atomic identity on every trade row

Slippage is embedded in the fill price rather than booked as a fee, so it is
reconstructed from the *unslipped* reference price (direction-aware: a buy fills
high, a sell fills low). This makes `gross − costs = net` exact to 1e-9 on every
row, which is what known-answer test 3 asserts.

### D-011 — The holdout applies to every validation mode

Originally only `mode="holdout"` reserved one. Walk-forward could then roll its
windows across the whole period. Since the design shows rolling windows and an
"OOS holdout LAST 6MO" side by side, `holdout_months > 0` now reserves a holdout
in every mode except `none`.

### D-012 — An empty segment renders as "—", never 0.00

A short range under walk-forward can produce no out-of-sample window at all. The
stat band was reporting `OOS Sharpe 0.00` for that case, which asserts something
false. Segments with zero bars now render an em dash, the plan carries an
explicit note explaining why no OOS exists, and the overfit verdict counts it as
a failed check.

## Phase 2 — Adapters & seed

### D-013 — The v1 seed contains no placeholder slices

The spec allows clearly-labelled synthetic placeholders where GPU capacity is
short. Batched Chronos-Bolt inference on local MPS ran at roughly **1 ms/step**,
so the entire v1 seed was generated for real: **18 slices, 60,375 rows**, across
`chronos-bolt-small` and `chronos-bolt-base`, 6 assets, 3 timeframes.
`PlaceholderAdapter` and its `PLACEHOLDER` labelling remain in the codebase and
are still tested, because contributors on weaker hardware may need them.

### D-014 — Dedup compares the *producible* range, not the requested one

A forecast needs a full trailing context window, so the first producible
timestamp sits `context_len` bars after the start of a price slice. Comparing
the user's typed range against manifest coverage therefore reported
already-covered slices as uncovered and would have paid for the same inference
twice. Both `scripts/seed_store.py` and `extension.estimate()` now compare the
range the request would actually produce. This was caught by the Phase 4 dedup
test, not by inspection.

## Phase 5 — Ship

### D-015 — torch pinned to 2.11.0 for ZeroGPU

The first deploy landed in `CONFIG_ERROR`: ZeroGPU accepts only torch 2.11.0,
2.10.0, 2.9.1 or 2.8.0, and the build was pinned to the locally-tested 2.13.0.
Pinned to **2.11.0**. The local test environment still runs 2.13.0, so the
adapter code path is exercised on a newer torch than the Space uses — noted in
HANDOFF.md as a residual difference worth a post-deploy check.