# Replication guide (WP46)

## 0. Environment
```bash
cd finance/wp46_garch_benchmark
uv venv -p 3.12 .venv && uv pip install -p .venv/bin/python -e ".[dev]"      # arch==8.0.0 pinned
.venv/bin/python -m pytest -q tests/unit tests/integration                    # ~1 min, no data needed
.venv/bin/python -m pytest -q tests/simulation -m slow                         # Monte Carlo recovery, ~5 min
Rscript -e 'install.packages(c("rugarch","jsonlite"))' && .venv/bin/python -m pytest -q tests/replication -m r   # rugarch cross-check
```
Without a FinData OS credential, stop here: the synthetic fixture `data/synthetic/` (see `scripts/make_synthetic.py`) exercises the
whole pipeline (panel → forecasts → losses → analysis) on simulated data.

## 1. Data (requires the owner's FinData OS key; FirstRate Data private licence)
```bash
export FINDATA_API_KEY_FILE=~/findata-secrets/api-key-wp46.txt   # or FINDATA_API_KEY
.venv/bin/python scripts/audit_findata.py                          # docs/findata_audit.md + results/manifests/findata_audit.json
.venv/bin/python scripts/ingest_bars.py --workers 3                # 1-min + daily bars -> ~/wp46-cache/bars (≈ 230 M rows, ≈ 25 min on the data node)
.venv/bin/python scripts/build_panels.py --workers 10              # daily panels -> ~/wp46-cache/panels, results/manifests/panels_manifest.json
.venv/bin/python scripts/build_rcov.py                             # Tier C realized covariances -> ~/wp46-cache/rcov
```
Dataset versions and SHA-256 of every exported file are in `results/manifests/ingest_manifest.json`; panel hashes in `panels_manifest.json`.

## 2. Pilot and protocol
```bash
.venv/bin/python scripts/run_pilot.py --symbols SPY,AAPL,CL,EURUSD  # validation period only -> results/metrics/pilot/
git tag prereg-frozen                                                # the protocol was frozen at 3590bd6 before any test-period loss
```

## 3. Benchmark (3,276 jobs; < 1 h on six Apple-silicon nodes, ≈ 30 CPU-hours)
```bash
.venv/bin/python scripts/make_jobs.py --name main
.venv/bin/python scripts/dispatch_nodes.py sync-panels --name main
.venv/bin/python scripts/dispatch_nodes.py launch --jobs results/manifests/jobs_main.json --name main
.venv/bin/python scripts/dispatch_nodes.py status --name main
.venv/bin/python scripts/dispatch_nodes.py collect --name main      # -> results/forecasts/main/<symbol>/<spec_id>.parquet (+ .fits.parquet, _runs.jsonl)
# single machine alternative:
.venv/bin/python scripts/run_benchmark.py --jobs results/manifests/jobs_main.json --workers 8 --out results/forecasts/main
.venv/bin/python scripts/run_tier_c.py                               # Tier C (data node)
```

## 4. Evaluation and exhibits
```bash
.venv/bin/python scripts/compute_losses.py --run main --workers 6                 # results/metrics/losses_main/
.venv/bin/python scripts/analyze.py --run main --period test                     # results/metrics/analysis_main_test/, results/tables/pooled_main_test.csv
.venv/bin/python scripts/analyze.py --run main --period validation               # exploratory, reported as such
.venv/bin/python scripts/analyze_tier_c.py test
.venv/bin/python scripts/build_paper.py --run main --period test                 # paper/numbers.tex, paper/tables/*.tex, paper/figures/*.pdf
cd paper && make                                                                  # latexmk -> main.pdf
```

## 5. Provenance
`results/forecasts/<run>/_runs.jsonl` records, per job, git SHA, host, Python/arch/numpy/scipy/pandas versions, CPU count, wall and
CPU time, peak RSS and status counts. `results/manifests/figure_audit.csv` lists the sources of every figure.