# REPLICATION.md — how to reproduce WP39

## Requirements
- Python ≥ 3.12 with `uv` (`uv venv -p 3.12 .venv && uv pip install -e ".[dev]"`).
- Access to FinData OS (owner-issued key with scopes `read:market, read:fundamentals, query, export`) exposed as
  `FINDATA_API_KEY` or a mode-600 file at `FINDATA_API_KEY_FILE`. Without access, Phases 2–5 cannot run; the saved
  evaluation artifacts in `artifacts/evaluation/` and `results/` allow Phase 6 (tables/figures/paper) to be regenerated.
- Read-only `psql` access to the FinData Postgres database on the storage node for `scripts/01a_extract_node_tables.sh`
  (earnings events, entities, corporate actions — not yet exposed by the API).
- Internet access to `sec.gov` (CIK/SIC) and the Kenneth French library (daily factors).
- TeX Live with `latexmk` for the paper.

## Order of execution (compute node, API on localhost)
```bash
export FINDATA_BASE_URL=http://127.0.0.1:8600/api/v1 WP39_CACHE=~/wp39-cache
bash scripts/01a_extract_node_tables.sh          # node extracts + manifests
python scripts/00_probe_findata.py               # contract reconciliation -> artifacts/logs/phase0_probe.json
python scripts/01_audit_universe.py              # universe.parquet, results/universe_audit.json
python scripts/02_build_pit_panel.py             # quarters.parquet (labels), design freeze hash
python scripts/03_build_features.py --workers 8  # streaming exports -> session features -> rolling windows
python scripts/04_build_labels.py                # sample_event.parquet, sample_calendar.parquet, cascades
python scripts/05_train_baselines.py             # B0-B5 logistic, ridge, firm hold-out, walk-forward
python scripts/06_train_advanced.py              # LightGBM equal-budget, horizon ladder, OOF signals
python scripts/07_evaluate.py                    # metrics, paired contrasts, GW tests, Holm, power
python scripts/08_run_robustness.py              # placebos, subgroups, panel regressions, H5
python scripts/09_make_manuscript.py             # tables, figures, results_macros.tex
cd paper && make                                 # main.pdf
pytest -q                                        # 29 tests; WP39_LIVE=1 adds the live API contract tests
```
Runtime on a Mac Studio M3 Ultra (28 cores): see `PROGRESS.md` for measured wall-times of each step.

## What is and is not in the package
- In: code, configs, docs, tests, manifests (hashes/versions/counts), derived evaluation tables, figures, paper.
- Out: raw bars and fundamentals (FirstRate Data license), the per-symbol feature cache (derived from licensed data;
  regenerable), model binaries.
- Determinism: all seeds come from `configs/research.yaml` (`seed: 20261102`); LightGBM uses `n_jobs=12` with
  deterministic histogram construction at the default settings, so results are reproducible to numerical precision on
  the same architecture.