SniperGold_ML/docs/SESSION_HANDOVER_2026-08-23_P3_S16_SETUP_DATASET.md

# SESSION HANDOVER — P3-S.16 SETUP-LEVEL DATASET / LABEL CONTRACT

```text
Date       : 2026-08-23
Session    : P3-S.16 — Setup-Level Dataset / Label Contract Implementation
Baseline   : P3-S.15 checkpoint acb5f2b56d4e8ba6563076a1ee2687cb2c53f421 VERIFIED
             (local == origin/main, branch main, working tree CLEAN)
Scope      : RESEARCH-ONLY. Dataset contract + label computation + setup-event
             extraction + tests. NO training, NO production change.
Human verif: REMAINS CANCELLED (historical only).
Verdict    : CONTRACT COMPLETE WITH OPEN PARAMETERS
             (semantics settled; numeric research params explicitly OPEN,
              NOT selected by AUC/PF)
Next gate  : P3-S.17 = DATASET AUDIT / LABEL VALIDATION.
```

---

## 1. What P3-S.16 established

```text
A. Observation unit = ONE CANDIDATE_SETUP (the only valid training unit;
   P3.2.2 §K bar unit FAILED validity). Identity is immutable & causal.

B. Entry timestamp = CLOSE of the CANDIDATE_SETUP creation bar (M15), chosen
   on causality. M3 is optional/post-creation and does NOT move entry.

C. Label target = SETUP-OUTCOME (TP-before-SL), SEVERED from the legacy
   L1 24-bar/0.75 ATR direction-drift label.

D. Label classes fully defined (WIN / LOSS / UNRESOLVED / AMBIGUOUS) with
   entry, TP/SL, horizon, first-hit, same-bar ambiguity, censoring, missing
   data, and session/gap behavior. UNRESOLVED is never forced to LOSS;
   AMBIGUOUS same-bar never forced to WIN/LOSS.

E. De-overlap redesigned at the SETUP level (lead-setup-per-episode,
   analogous P3.2.2 §B adapted to setups) for causally independent
   observations; not metric fishing.

F. Sampling: every valid Candidate Setup becomes an observation (natural
   population preserved; no random undersampling).

G. Feature snapshot is a contract PROPOSAL (separate Store 2), NOT added to
   FEATURE_CONTRACT.md. Feature-as-of strict (causally available at entry).

H. Split / reproducibility requirements defined (temporal split, purge gap,
   no label-window overlap, no future info) as FUTURE requirements; split
   percentages are OPEN parameters.

I. Test-first implementation in ml/p3/setup_dataset/ with the frozen contract
   as ORACLE; spec_oracle == truth, implementation_port == observed. 20/20 PASS.
```

---

## 2. Deliverables created

```text
docs/P3_S16_SETUP_DATASET_CONTRACT_v1.md
docs/P3_S16_LABEL_CONTRACT.md
docs/P3_S16_SETUP_DATASET_IMPLEMENTATION.md
ml/p3/setup_dataset/setup_dataset_contract.py
ml/p3/setup_dataset/spec_tests_setup_dataset.py
ml/p3/setup_dataset/output/p3_s16_dataset_report.json     (20/20 PASS)
docs/SESSION_HANDOVER_2026-08-23_P3_S16_SETUP_DATASET.md  (this file)
```

---

## 3. Regression status (verified re-run after P3-S.16)

```text
P3-S.2 17/17 · P3-S.7 22/22 · P3-S.8 25/25 · F1 8/8 · F2 20/20 ·
F3 25/25 · F4 16/16 —— all PASS. NO historical suite modified or weakened.
The new setup_dataset test suite (DS-T01..T16 + DS-17..20) = 20/20.
```

---

## 4. Explicitly unchanged areas (§31)

```text
- Candidate Setup runtime                         unchanged
- F1 event semantics                              unchanged
- F2 FVG/OB zone semantics                        unchanged
- F4 runtime MTF                                  unchanged
- Feature Contract (FEATURE_CONTRACT.md)          unchanged
- SniperGold_ML.mqh / weights / labels            unchanged
- production .mq5/.mqh                            unchanged
- legacy model                                    unchanged (reference only)
- No AUC/PF/backtest/optimization used
- Human annotation verification remains CANCELLED
```

---

## 5. Open / deferred for P3-S.17 (NOT decided here)

```text
1. DATASET AUDIT / LABEL VALIDATION (P3-S.17): validate the contract against
   real price data, compute the actual setup population + label distribution
   (without training). Re-measure natural class balance on CANONICAL setups.
2. OPEN NUMERIC PARAMETERS (semantically anchored, NOT optimized):
   k_tp/k_sl (default 1.5/0.75; robustness 1.0/1.0), horizon (primary 16 /
   robustness 8), split percentages & purge-gap numeric, W_m3 (frozen F3
   placeholder). These feed P3-S.17 validation, not AUC selection.
3. Feature-snapshot numeric contract (Store 2) is authored LATER (separate
   proposal), never by mutating FEATURE_CONTRACT.md.
4. Training / baseline / temporal / regime / calibration = FUTURE authorized
   phases beyond P3-S.17. Legacy MLP remains frozen reference.
```

---

## 6. Handoff

```text
P3-S.17 SHOULD (with separate authorization):
  - confirm the P3-S.16 checkpoint (P3_S16_FINAL_SHA below),
  - run a dataset AUDIT + LABEL VALIDATION on real data using the contract,
  - measure the natural setup population and label distribution truthfully,
  - NOT train a model, NOT optimize any numeric by AUC/PF,
  - NOT modify the frozen Candidate Setup / F1 / F2 / runtime / FEATURE_CONTRACT.
```

---

## 7. Provenance / Checkpoint

```text
Forge HEAD (start)  : acb5f2b56d4e8ba6563076a1ee2687cb2c53f421 (P3-S.15) VERIFIED
Branch / remote     : main == origin/main
Working tree        : CLEAN at start; CLEAN after P3-S.16 push
Commits             : 8d934b4 test: define setup-level dataset and label contract coverage
                    : dcb4c96 research: implement deterministic setup-level dataset generation
                    : ef8781f docs: record P3-S.16 setup dataset and label contract
P3_S16_FINAL_SHA    : ef8781f  (to be finalized in the handover-record commit)
Human verification  : CANCELLED
```

*End P3-S.16 handover.*