# Hybrid Candidate Schema — XAUUSD 2026

Purpose: define the scanner output used by the hybrid workflow.

The hybrid scanner is a **candidate finder only**. A candidate is not a valid trade until it is reviewed chronologically in TradingView Bar Replay and, if accepted, written to the canonical manual replay journal files.

## Files

- Scanner input: `hybrid/data/ohlcv_M15.json` (required for real scans)
- Optional lower-timeframe input: `hybrid/data/ohlcv_M5.json`
- Scanner output: `hybrid/candidates/candidates.json`
- Manual labels/review notes: `hybrid/reviews/reviews.json`
- Confirmed trades after manual replay only: `data/journal.json` and `data/backtest-data.json`
- Shadow/missed/observed replay entries only: `data/shadow-trades.json`

Do not write scanner candidates directly to confirmed journal/dashboard data.

## Candidate output root object

`hybrid/candidates/candidates.json` MUST be an object:

```json
{
  "metadata": {
    "symbol": "XAUUSD",
    "mode": "hybrid_candidate_scanner",
    "period": "2026",
    "timeframes": ["M15", "M5"],
    "source": "historical_ohlcv_mechanical_scan",
    "isFinalBacktest": false,
    "generated_at": "2026-07-17T00:00:00Z",
    "scanner_version": "0.1.0-scaffold",
    "input_files": {
      "M15": "hybrid/data/ohlcv_M15.json",
      "M5": "hybrid/data/ohlcv_M5.json"
    },
    "notes": "Mechanical candidates only; final validity requires manual TradingView Bar Replay review."
  },
  "candidates": []
}
```

## Candidate record schema

Every candidate object MUST use these canonical field names:

```json
{
  "id": "candidate_2026-01-06T14-30-00Z_long_ict_sweep_mss_fvg",
  "date": "2026-01-06",
  "timestamp": "2026-01-06T14:30:00Z",
  "symbol": "XAUUSD",
  "strategy": "ICT Sweep + MSS + FVG",
  "direction": "Long",
  "session": "NY AM",
  "timeframe": "M15",
  "entry_timeframe": "M5",
  "narrative": "TBD manual review",
  "htf_context": "TBD manual review",
  "ltf_trigger": "Mechanical sweep/displacement candidate; manual replay required",
  "liquidity_swept": "PDL",
  "entry": null,
  "stop": null,
  "target": null,
  "fib": "TBD",
  "pd": "TBD",
  "candidate_score": 0,
  "confidence": "Unreviewed",
  "status": "unreviewed",
  "requires_manual_replay": true,
  "scanner_flags": ["pdl_sweep", "displacement_candidate"],
  "notes": "Scanner-generated candidate only; not a confirmed trade."
}
```

### Required candidate fields

- `id`
- `date`
- `timestamp`
- `symbol`
- `strategy`
- `direction`
- `session`
- `timeframe`
- `entry_timeframe`
- `narrative`
- `htf_context`
- `ltf_trigger`
- `liquidity_swept`
- `entry`
- `stop`
- `target`
- `fib`
- `pd`
- `candidate_score`
- `confidence`
- `status`
- `requires_manual_replay`
- `scanner_flags`
- `notes`

### Allowed values

- `symbol`: `XAUUSD`
- `direction`: `Long`, `Short`
- `session`: `Asia`, `London`, `NY AM`, `London Close`, `NY PM`, `Other`
- `strategy`:
  - `Aryy HTF Narrative Fib 50/62`
  - `ICT Sweep + MSS + FVG`
  - `Order Block Reclaim`
  - `Liquidity Sweep Reversal`
  - `Breaker Continuation`
- `confidence`: `Unreviewed`, `Low`, `Medium`, `High`
- `status`: `unreviewed`, `accepted`, `rejected`, `shadow`, `needs_more_context`
- `requires_manual_replay`: always `true` for scanner output
- `candidate_score`: integer or float from `0` to `100`; this is pre-review ranking only, not final expectancy.

## Manual review file schema

`hybrid/reviews/reviews.json` MUST start as an empty review object:

```json
{
  "metadata": {
    "symbol": "XAUUSD",
    "mode": "hybrid_manual_replay_reviews",
    "period": "2026",
    "source": "manual_tradingview_replay_review_labels",
    "isDummy": false,
    "notes": "Review labels for scanner candidates. Confirmed trades must still be written to canonical journal/dashboard files."
  },
  "reviews": []
}
```

Each future review object should reference `candidate_id` and never overwrite the candidate record:

```json
{
  "candidate_id": "candidate_2026-01-06T14-30-00Z_long_ict_sweep_mss_fvg",
  "reviewed_at": "2026-07-17T00:00:00Z",
  "reviewer": "manual_tradingview_replay",
  "status": "accepted",
  "outcome": "Win",
  "r": 1.8,
  "journal_trade_id": 23,
  "notes": "Replay-confirmed after W/D/H4 narrative and M15/M5 execution review."
}
```

## Integrity rules

1. Scanner output is not final trade history.
2. No dummy/sample candidates should be committed as if real scanner findings.
3. Confirmed trades must use the canonical `JOURNAL_SCHEMA.md` fields and be written only after manual replay review.
4. Use canonical price names: `entry`, `stop`, `target`. Do not use `entry_price`, `sl_price`, `tp_price`, `take_profit`, or `pnl_r`.
5. Keep scanner notes explicit: `requires_manual_replay: true`.
6. If no OHLCV is present, the scaffold may write an empty candidates file with a metadata warning, but it must not synthesize candidates.