Artifex/docs/trading_program_understanding_20260817.md

# Trading Program Understanding

## Scope

This report records read-only archaeology of `S:\PycharmProjects\SquadWatch`,
the Spark replay workspace, and the Pi service state. No exchange action,
credential access, service restart, or database mutation occurred.

## Current Decision

**CONFIRMED: no existing strategy qualifies for Shadow Mode from the latest
Spark evidence.** The latest 45-day selection/final comparison selected 50
families and recorded `survivor_count: 0`. This is a successful falsification
result, not a reason to loosen the gate.

## Data

| Status | Evidence |
| --- | --- |
| CONFIRMED | Spark snapshot `/home/daniel/hyperscalper-replay/binance_btcusd_2m_455d.csv` has 327,599 BTCUSD 2-minute OHLCV rows with `timestamp,open,high,low,close,volume`. Its observed range is Unix `1743840960` through `1783152720`. |
| CONFIRMED | Spark has a chronologically separated 90-day OOS snapshot and 45-day selection/final partitions: `binance_btcusd_2m_oos_90d.csv`, `binance_btcusd_2m_oos_select_45d.csv`, and `binance_btcusd_2m_oos_final_45d.csv`. The selection/final boundary is adjacent, not shuffled. |
| CONFIRMED | The newest discovered Spark HyperScalper artifacts were written 2026-08-08. They are not current market data on 2026-08-17. |
| CONFIRMED | Pi logs were updated 2026-08-17, but `hyperscalper-live.service` and `hyperscalper-risk50-paper.service` were inactive during the read-only check. |
| UNKNOWN | Current live exchange positions, fills, and account equity were not queried. Trading Studio V0.1 intentionally does not make exchange calls. |
| UNKNOWN | Funding, open interest, order book, tick, and liquidation datasets were not located in the verified Spark replay input. They must not be implied by OHLCV availability. |

## HyperScalper Architecture

| Status | Evidence |
| --- | --- |
| CONFIRMED | The source system is `src/hyperscalper` in SquadWatch. It contains indicator/search code, paper replay, feed, bot, executor, risk, and Postgres/SQLite journaling components. |
| CONFIRMED | Live topology documented in `docs/hyperscalper_pi_deployments.md` is feed -> paper/signal authority -> webhook-only live runner -> Hyperliquid executor. Documented initial live controls were single position, 1x leverage, and max notional 20. |
| CONFIRMED | The Pi documentation states a known accounting limitation: bot-managed exits may record local trigger price/PnL rather than the actual exchange close fill. Historical live PnL therefore needs reconciliation before it is treated as canonical. |
| INFERRED | Existing execution controls are useful source material but cannot be trusted as an Artifex execution adapter until restart recovery, idempotency, account-level risk persistence, and reconciliation are audited. |

## Features And Leakage

| Status | Evidence |
| --- | --- |
| CONFIRMED | `fast_engine.py`, `indicators_depth_nb.py`, and `indicator_library.py` provide a large multi-family feature universe. The implementation uses trend, oscillator, volatility, channel, pivot, time, and candle-derived signals. |
| CONFIRMED | The active paper-like replay computes signal at completed-bar close and enters at next-bar open with intrabar TP/SL handling. |
| BLOCKED | The high-throughput search kernel enters at same-bar close while the paper replay uses next-bar open. Search PnL is not execution-equivalent evidence and cannot qualify a strategy. |
| BLOCKED | Search volatility percentile calibration is derived from the full evaluated window in `fast_engine.py`; this leaks later observations into early threshold calibration. It must be fit on train only and frozen before validation/holdout. |
| SUSPICIOUS | Existing walk-forward code has no documented purge/embargo around position/cooldown boundaries. Future Artifex folds must embargo at least the maximum holding period plus cooldown. |

## Existing Strategy Evidence

| Status | Evidence |
| --- | --- |
| CONFIRMED | Spark report `/home/daniel/hyperscalper-replay/reports/oos_45d_selection_final_comparison.json` applied its stated selection rule to 50 candidates and reported zero final survivors. |
| CONFIRMED | The selection candidates exhibited strong prior-window PFs, while the displayed final-window results were negative with PF below one. This is direct evidence of regime/search fragility, not a live execution result. |
| CONFIRMED | `walkforward_14d_14d.json` states it used a read-only transaction and that selection used only fully completed training trades. It is useful historical evidence, but its thresholds and data partition policy must be revalidated by Artifex before reuse. |
| UNKNOWN | The local 14-row SQLite live journal is too small to establish a live alpha conclusion. The documented main 60-day paper database was not present in the inspected local workspace. |

## Backtester Integrity Assessment

**PARTIAL / NOT QUALIFIED FOR PROMOTION**

- Reuse candidate: `src/hyperscalper/paper_replay.py` because its timing model is closer to intended paper/live semantics.
- Reject for qualification: `fast_engine.evaluate_combo()` and the close-only kernel until same-bar and full-window calibration issues are repaired.
- Required before a future cohort: immutable source hash, chronological discovery/train/validation/holdout split, train-only thresholds, purge/embargo, fixed cost version, and next-open/intrabar conservative replay.
- Required before Shadow: a fresh data snapshot after the 2026-08-08 Spark cutoff, a successful independent cohort, and an Artifex shadow runner that records intended order, observed market evolution, and simulated fill without exchange submission.

## V0.1 Cohort Policy

The first Artifex cohort is bounded to 20 pre-existing, fingerprint-deduplicated
strategy genomes. It must run the paper-like replay with frozen data/splits and
cost stress. The latest Spark report already proves that the current 50-candidate
selection did not survive its final partition. Artifex must preserve that failure
knowledge and must not promote any member of that family from those results.

## Shadow Readiness

**NOT READY.** No shadow command is authorized to start yet. Once a new current
market snapshot is registered, has passed quality validation, and an offline
cohort produces a holdout-qualified survivor, the future explicit command is:

```powershell
python manage.py trading_shadow --project crypto-hyperscalper --strategy-version <uuid> --dry-run
```

That command is intentionally not implemented in V0.1 because it would create a
false impression that shadow qualification is currently satisfied.