# XAUUSD Backtest Journal Schema

All backtest workers MUST use the exact canonical schemas below. Do not invent alternate field names such as `entry_price`, `sl_price`, `tp_price`, `pnl_r`, `pd_array`, `fib_alignment`, or `reason` in production data files.

## Confirmed trade schema

Write confirmed manually replayed trades to both:

- `data/journal.json`
- `data/backtest-data.json`

Both files must use object format:

```json
{
  "metadata": {
    "symbol": "XAUUSD",
    "mode": "manual_tradingview_replay",
    "period": "2026-01-01 to 2026-07-17",
    "currency": "USD",
    "riskPerR": 100,
    "startingBalance": 10000,
    "isDummy": false,
    "source": "manual_tradingview_replay_confirmed"
  },
  "strategies": [
    "Aryy HTF Narrative Fib 50/62",
    "ICT Sweep + MSS + FVG",
    "Order Block Reclaim",
    "Liquidity Sweep Reversal",
    "Breaker Continuation"
  ],
  "sessions": ["Asia", "London", "NY AM", "London Close", "NY PM"],
  "trades": []
}
```

Each trade object MUST use:

```json
{
  "id": 1,
  "date": "2026-01-06",
  "timestamp": "2026-01-06T14:30:00Z",
  "symbol": "XAUUSD",
  "strategy": "Liquidity Sweep Reversal",
  "direction": "Long",
  "session": "NY AM",
  "narrative": "External → Internal",
  "htf_context": "W/D/H4 narrative summary",
  "ltf_trigger": "M15/M5 setup trigger summary",
  "entry": 4436.835,
  "stop": 4427.635,
  "target": 4460.525,
  "fib": "N/A",
  "pd": "Rejection Block",
  "outcome": "Win",
  "r": 2.57,
  "confidence": "High",
  "notes": "One concise replay reason and result note."
}
```

Required fields:

- `id`
- `date`
- `strategy`
- `direction`
- `session`
- `entry`
- `stop`
- `target`
- `fib`
- `pd`
- `outcome`
- `r`
- `notes`

Allowed values:

- `direction`: `Long` or `Short`
- `session`: `Asia`, `London`, `NY AM`, `London Close`, `NY PM`
- `outcome`: `Win`, `Loss`, `BE`
- `r`: numeric realized R multiple

## Shadow / observed entry schema

Write shadow, observed, missed, and paper entries to:

- `data/shadow-trades.json`

Use object format only:

```json
{
  "metadata": {
    "symbol": "XAUUSD",
    "mode": "manual_tradingview_replay_shadow_entries",
    "period": "2026-01-01 to 2026-07-17",
    "isDummy": false,
    "source": "manual_tradingview_replay_observed"
  },
  "shadowTrades": []
}
```

Each shadow object MUST use:

```json
{
  "id": "shadow_2026-01-07_001",
  "date": "2026-01-07",
  "timestamp": "2026-01-07T11:15:00Z",
  "symbol": "XAUUSD",
  "type": "Paper win",
  "strategy": "Bearish FVG Retracement",
  "direction": "Short",
  "entry": 4479.115,
  "stop": 4492.415,
  "target": 4460.0,
  "r": 1.43,
  "note": "Reason and result."
}
```

Required fields:

- `id`
- `date`
- `type`
- `r`
- `note`

Allowed `type` examples:

- `Observed`
- `Missed`
- `Paper win`
- `Paper loss`
- `Paper BE`

## Write rules

1. Never overwrite a data file with a single new entry.
2. Always read the current file, append/merge, then write the complete object back.
3. Use canonical field names only.
4. Confirmed trades go to `journal.json` and `backtest-data.json`.
5. Shadow entries go only to `shadow-trades.json`.
6. Do not write dummy/sample trades to production data files.
7. If a replay batch finds no valid confirmed trade, add no trade; update state only.
8. Validate JSON after every write:

```bash
python3 -m json.tool data/journal.json >/dev/null
python3 -m json.tool data/backtest-data.json >/dev/null
python3 -m json.tool data/shadow-trades.json >/dev/null
```