SniperGold_ML/docs/P3_S16_SETUP_DATASET_IMPLEMENTATION.md

# P3-S.16 SETUP-LEVEL DATASET & LABEL CONTRACT — IMPLEMENTATION RECORD

```text
Date       : 2026-08-23
Session    : P3-S.16 — Setup-Level Dataset / Label Contract Implementation.
Status     : IMPLEMENTED (research-only) — deterministic contract + label
             computation + setup-event extraction + tests. NO training.
Baseline   : P3-S.15 checkpoint acb5f2b56d4e8ba6563076a1ee2687cb2c53f421
             VERIFIED (local == origin/main, branch main, working tree CLEAN).
Scope      : RESEARCH-ONLY. NO production runtime change, NO FEATURE_CONTRACT
             change, NO model retrain/export/deploy, NO legacy change.
Human verif: REMAINS CANCELLED (historical only). No AUC/PF/backtest/opt used.
```

---

## A. OBJECTIVE (restated)

> How do we turn ONE verified Candidate Setup into ONE reproducible training
> observation with a causally valid setup-outcome label, WITHOUT reintroducing
> the overlap, redundancy, and look-ahead problems of the old bar-level ML
> pipeline?

P3-S.16 answers this by:
1. fixing the contract (observation unit = ONE Candidate Setup; entry = close
   of the creation bar; label = setup-outcome TP-before-SL),
2. implementing a deterministic, research-only dataset/label generator,
3. validating it with a test-first suite against the contract as ORACLE, and
4. recording reproducibility / split / provenance requirements for the future
   (authorized) training phase.

---

## B. DELIVERABLES

```text
docs/P3_S16_SETUP_DATASET_CONTRACT_v1.md         (contract — observation unit,
                                                  identity, entry, separation,
                                                  de-overlap, feature discipline)
docs/P3_S16_LABEL_CONTRACT.md                     (TPS before-SL outcome contract:
                                                  WIN/LOSS/UNRESOLVED/AMBIGUOUS,
                                                  TP/SL, horizon, first-hit,
                                                  censoring, ambiguity, gap)
ml/p3/setup_dataset/setup_dataset_contract.py      (implementation PORT)
ml/p3/setup_dataset/spec_tests_setup_dataset.py    (test-first; ORACLE = contract)
ml/p3/setup_dataset/output/p3_s16_dataset_report.json (test report: 20/20 PASS)
docs/P3_S16_SETUP_DATASET_IMPLEMENTATION.md        (this record)
docs/SESSION_HANDOVER_<DATE>_P3_S16_SETUP_DATASET.md (handover)
```

---

## C. IMPLEMENTATION SUMMARY

```text
setup_dataset_contract.py provides:
  - entry_timestamp_of(setup, times) : close of the CANDIDATE_SETUP creation
    bar (contract §D; M3 optional does NOT shift entry).
  - entry_price_of / atr_at_entry     : reference price + ATR at entry.
  - resolve_outcome(...)              : TP-before-SL first-hit resolver with
    WIN/LOSS/UNRESOLVED/AMBIGUOUS and same-bar ambiguity (conservative).
  - build_observation(...)            : ONE setup -> ONE row, with identity_ /
    feature_ / label_ namespaces separated (contract §B/§C).
  - deoverlap_setups / build_dataset  : setup-level lead-setup-per-episode
    de-overlap + duplicate setup_id rejection.
All constants (k_tp/k_sl=1.5/0.75, H=16, robustness H=8) are OPEN parameters
recorded by the contract; none selected by AUC.
```

---

## D. KEY CONTRACT DECISIONS RECORDED (see the contract docs for full text)

```text
D1 OBSERVATION UNIT : ONE CANDIDATE_SETUP (identity + lifecycle). Bar unit is
      invalid (P3.2.2 §K).
D2 ENTRY TIMESTAMP  : close of the CANDIDATE_SETUP creation bar (M15). Chosen
      on causality, NOT profitability. M3 is optional/post-creation and does
      NOT move entry.
D3 LABEL TARGET     : setup-outcome (TP-before-SL), SEVERED from the legacy
      L1 24-bar direction-drift label. Never UNRESOLVED->LOSS; never
      AMBIGUOUS->WIN/LOSS.
D4 TP/SL            : TP=+k_tp*ATR(entry), SL=-k_sl*ATR(entry); reference ATR
      at entry (causally available); asymmetric 1.5/0.75 candidate (2:1 R:R)
      with 1.0/1.0 symmetry as OPEN robustness.
D5 HORIZON          : primary H=16 M15 bars (semantic: >98% of lifetimes,
      low censoring); robustness H=8; timeout -> UNRESOLVED (censored).
D6 AMBIGUITY        : same-bar TP+SL -> AMBIGUOUS (no OHLC-ordering assumption).
D7 CENSORING        : UNRESOLVED only at timeout / insufficient data / gap;
      never forced to LOSS.
D8 DE-OVERLAP       : setup-level lead-setup-per-episode (analogous P3.2.2 §B
      adapted to setups); independent observations, not metric fishing.
D9 SAMPLING         : every valid Candidate Setup is an observation (natural
      population preserved; no random undersampling).
```

---

## E. TESTS (test-first; ORACLE = frozen contract)

```text
spec_tests_setup_dataset.py — DS-T01..T16 (brief §27) + DS-17..20:
  DS-T01 one setup -> one observation; DS-T02 same setup stays one;
  DS-T03 two independent setups -> two; DS-T04 duplicate setup_id rejected;
  DS-T05 entry deterministic; DS-T06 future bars cannot alter snapshot;
  DS-T07 TP-before-SL -> WIN; DS-T08 SL-before-TP -> LOSS;
  DS-T09 timeout -> UNRESOLVED; DS-T10 same-bar TP/SL -> AMBIGUOUS;
  DS-T11 insufficient data -> UNRESOLVED; DS-T12 overlapping follow-on;
  DS-T13 independent setup handling; DS-T14 no look-ahead in features;
  DS-T15 closed-bar/as-of correctness; DS-T16 bullish/bearish symmetry;
  DS-17 M3 doesn't move entry; DS-18 UNRESOLVED not forced to LOSS;
  DS-19 AMBIGUOUS not forced; DS-20 implementation port == spec oracle.
RESULT: 20/20 PASS.
```

---

## F. REGRESSION (§30) — verified PASS after P3-S.16

```text
P3-S.2 17/17 (re-run) · P3-S.7 22/22 (re-run) · P3-S.8 25/25 (re-run) ·
F1 8/8 (re-run) · F2 20/20 (re-run) · F3 25/25 (re-run) · F4 16/16 (re-run).
No historical suite was modified; none weakened by the new research module.
```

---

## G. EXPLICITLY UNCHANGED / PRODUCTION PROTECTION (§31)

```text
Candidate Setup runtime, F1, F2, F4 runtime MTF, FEATURE_CONTRACT.md,
SniperGold_ML.mqh, production .mq5/.mqh, legacy model: NONE changed.
No model trained/exported/deployed. The new code is research-only under
ml/p3/setup_dataset/.
```

---

## H. FUTURE SPLIT / REPRODUCIBILITY (defined, not executed — §23/§24)

```text
Temporal split by entry_timestamp; purge gap == outcome horizon; no overlap
between label windows; no future info. Split percentages = OPEN parameters.
Every future run records source-hash, setup-dataset-hash, contract version,
feature version, label version, seed if used, generation timestamp.
```

---

## I. VERDICT

```text
CONTRACT COMPLETE WITH OPEN PARAMETERS.
Semantics fully settled: observation unit, identity separation, entry timestamp,
TP/SL semantics, horizon basis, WIN/LOSS/UNRESOLVED/AMBIGUOUS, de-overlap,
sampling, feature timing discipline, provenance, split/reproducibility.
OPEN NUMERIC PARAMETERS (not selected by AUC/PF): k_tp/k_sl (default 1.5/0.75),
horizon (primary 16, robustness 8), split percentages, purge-gap numeric,
W_m3 (frozen F3 placeholder). These do not block the contract.
```

---

## J. NEXT GATE

```text
P3-S.17 = DATASET AUDIT / LABEL VALIDATION (per P3-S.16 §34/§37). No retraining.
The legacy MLP remains frozen as reference. Setups treated as deterministic
training observations; the outcome label is causally valid and reproducible.
```

*End of P3-S.16 setup dataset & label contract implementation record.*