SniperGold_ML/docs/P3_S16_SETUP_DATASET_CONTRACT_v1.md

# P3-S.16 SETUP-LEVEL DATASET CONTRACT v1 — SNIPERGOLD_ML

```text
Status   : AUTHORITATIVE CONTRACT FOR THE LITERATURE-LEVEL TRAINING OBSERVATION.
Scope    : Defines the canonical ML observation unit (ONE Candidate Setup) and
           its deterministic transformation into ONE training observation, with
           the separation of (i) immutable setup identity, (ii) derived training
           features, and (iii) outcome labels. This contract is the ORACLE for
           the P3-S.16 test suite and dataset generator (ml/p3/setup_dataset/).
Session  : P3-S.16 — Setup-Level Dataset / Label Contract Implementation.
Date     : 2026-08-23
Status tag: CONTRACT v1 (P3-S.16). Numeric research parameters are explicitly
           OPEN where noted; they must NOT be selected by AUC/PF (session §29).
Provenance: P3-S.15 decision docs/P3_S15_ML_PATH_ARCHITECTURE_DECISION.md
           P3-S.15 docs/P3_S15_SETUP_LEVEL_TRAINING_CONTRACT_PROPOSAL.md
           frozen P3-S.10 docs/SNIPERGOLD_CANONICAL_SETUP_CONTRACT_v1.md (§E/§F)
           P3-S.13 docs/P3_S13_CANDIDATE_SETUP_REPAIR.md (AFCandidateSetup F3)
           P3.2/P3.2.2 forensic (docs/P3_2_LABEL_FORENSIC.md,
           docs/P3_2_2_DEOVERLAP_SURVIVAL.md)
Human verification : REMAINS CANCELLED (historical only).
```

---

## A. OBJECTIVE

> 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?

This contract answers that question at the CONTRACT level. It fixes the
observation unit, its immutable identity, the separation boundaries, the
feature snapshot discipline, and the dataset mechanics — so that the generator
(`ml/p3/setup_dataset/`) can build a deterministic, auditable dataset and the
label computation can be validated against this contract as ORACLE.

---

## B. OBSERVATION UNIT — ONE CANDIDATE SETUP

```text
ONE TRAINING OBSERVATION = the occurrence of ONE CANDIDATE_SETUP
(entity AFCandidateSetup, frozen P3-S.13 §C), captured at the moment its chain
completes and (optionally) at the deterministic ENTRY timestamp (§D below).

The Candidate Setup is the ONLY valid training unit because:
  - it is the runtime decision granularity (P3-S.15 §6.3),
  - its identity is CAUSAL and DETERMINISTIC (P3-S.13 §J),
  - its lifecycle is fully specified (P3-S.13 §D),
  - the bar-level unit FAILED unit-validity (P3.2.2 §K: 97-99% redundant,
    1.5% retention) — the setup unit removes per-bar redundancy.
```

```text
IMMUTABLE SETUP IDENTITY (the observation key — immutable, never derived):
  setup_id                 : monotonic integer at CANDIDATE_SETUP.
  direction                : +1 bullish / -1 bearish (chain direction).
  creation_timestamp       : M15 creation_bar open time (CANDIDATE_SETUP bar).
  creation_bar_index       : absolute M15 bar index (monotonic, repo-defined).
  setup_state              : CANDIDATE_SETUP (or M3_CONFIRMED) at capture.
  sweep_onset              : Liquidity EVENT onset bar index + sweep_direction.
  choch_onset              : CHoCH/MSS EVENT onset bar index + choch_direction.
  zone_type                : OB | FVG.
  zone_formation_timestamp : zone formation bar open time.
  zone_bounds              : {lower_bound, upper_bound} at creation (F2 contract).
  zone_mit_at_creation     : F2 mitigation state when the chain consumed it.
  m15_entry_condition_ts   : the M15 decision bar when the M15 entry condition
                             held (bar that advanced chaim to ENTRY_ARMED; the
                             creation bar for the CANDIDATE_SETUP completion).
  m3_confirmation_ts       : nullable — M3 bar timestamp if M3_CONFIRMED, else null.
  provenance               : contract version + generator version + source
                             dataset hash (see §K).
  source_timeframe_set     : {H4, M30, M15, M3} with as-of timestamps per TF.

UNIQUENESS: two setups are the same observation iff their CAUSAL key matches:
  (direction, sweep_onset, choch_onset, zone_formation_timestamp,
   creation_timestamp). (P3-S.10 §K, P3-S.13 §J.)
```

```text
SEPARATION OF THREE STORES (this contract — NEVER mixed):

  STORE 1 — IMMUTABLE IDENTITY  (§B): fixed at creation; part of the key;
                                     never derived, never a label, never a
                                     learning feature that encodes the outcome.
  STORE 2 — DERIVED TRAINING FEATURES (§G / proposal): functions of causally
                                     available SMC state as-of the ENTRY
                                     timestamp. Respects FEATURE_CONTRACT.md
                                     (not modified).
  STORE 3 — OUTCOME LABEL (§ label contract): the TP-before-SL outcome
                                     measured from ENTRY forward. NEVER a
                                     feature of STORE 2.
```

---

## C. SETUP IDENTITY vs FEATURE vs LABEL — SEPARATION RULE

```text
The three stores must remain DISTINCT in the dataset schema:
  - a field that is part of the CAUSAL IDENTITY is not a learning feature;
  - a LEARNING FEATURE must be causally available at ENTRY (no future data);
  - the LABEL is a function of FUTURE price after ENTRY and must never appear
    in the feature store.
The dataset row therefore has three explicit namespaces:
  identity_*  : immutable key + provenance (Store 1)
  feature_*   : causally-available SMC features at entry (Store 2)
  label_*     : outcome class + horizons + levels (Store 3)
```

---

## D. ENTRY TIMESTAMP (MANDATORY — §10 of the brief)

```text
DECISION: the deterministic ENTRY timestamp for outcome measurement is

    entry_timestamp := CLOSE of the CANDIDATE_SETUP creation bar
                       (= M15 creation_bar close time),
    at timeframe M15.

Justification (causality, NOT profitability):
  - The Candidate Setup COMPLETES at creation_bar (chain whole, direction
    fixed, M15 entry condition already satisfied within the chain). The first
    closed bar at/after completion is the earliest causally-available
    executable point.
  - M3 confirmation is OPTIONAL and occurs AFTER creation; it is a
    confirmation, not a validity gate (§M canonical: absence does not
    invalidate; contrary reduces only micro-score). Therefore it CANNOT be the
    entry timestamp without breaking the "optional" semantics.
  - M15 entry-condition (ENENTRY_ARMED) and zone membership are already
    satisfied at creation_bar by construction; no separate entry re-trigger.
  - This matches the P3.2/P3.2.2 entry semantics (A = close of decision bar,
    robustness B = next-bar open, |A-B| ~ 0.008 ATR, P3.2 §6).

ENTRY CONTRACT:
  entry_timestamp      : creation_bar CLOSE (M15), computed as open_time + 900s.
  entry_price_source   : close of the creation_bar.
  price_convention     : bid for long / ask for short is a FUTURE EXECUTION
                         detail; for the LABEL CONTRACT (research, not trade)
                         a single mid/reference price is used per symbol, with
                         execution spread/slippage OUT of scope (see §H below).
  price_reference      : the creation_bar close (mid, contract-defined).
  spread handling      : NOT applied in the research label (would require an
                         execution model). Documented; applied only in a later
                         execution-aware phase, never in P3-S.16.
  timeframe            : M15 (fixed by the setup carrier).

If entry could not be fixed deterministically the project would STOP as
BLOCKED. It is fixed; no blocker.
```

---

## E. DATA CONTRACT FIELDS (canonical training observation row)

```text
---- identity_* (Store 1) ----
  identity_setup_id
  identity_direction
  identity_creation_timestamp
  identity_creation_bar_index
  identity_setup_state
  identity_sweep_onset_index
  identity_sweep_direction
  identity_choch_onset_index
  identity_choch_direction
  identity_zone_type
  identity_zone_formation_timestamp
  identity_zone_lower
  identity_zone_upper
  identity_zone_mit_at_creation
  identity_m15_entry_condition_ts
  identity_m3_confirmation_ts        (nullable)
  identity_provenance_*
  identity_source_timeframes

---- feature_* (Store 2) — PROPOSAL, see §G / P3-S.15 §8 ----
  feature_h4_context                (gate direction as-of entry)
  feature_m30_context               (gate direction as-of entry)
  feature_sweep_age_bars
  feature_choch_age_bars
  feature_choch_latency_after_sweep
  feature_zone_age_bars
  feature_zone_width_atr
  feature_price_in_zone_offset_atr
  feature_m15_distance_to_zone_atr
  feature_displacement_at_creation
  feature_m15_entry_condition
  feature_m3_present
  feature_m3_direction
  feature_sweep_size_atr
  feature_atr_at_entry

---- label_* (Store 3) — see label contract ----
  label_outcome            (WIN | LOSS | UNRESOLVED | AMBIGUOUS)
  label_tp_level
  label_sl_level
  label_horizon_bars
  label_tp_hit_bar          (nullable)
  label_sl_hit_bar          (nullable)
  label_timeout             (bool)
  label_invalidated_early   (secondary; observation may be resolved by
                             lifecycle invalidation — recorded, see label contract)
  label_contract_version
```

---

## F. SETUP RELATIONSHIP / DE-OVERLAP (§18 — independence of observations)

The training unit is now the Candidate Setup. Two DISTINCT setups may still
overlap in TIME (their outcome windows can share bars). For ML label
independence (P3.2.2 §J: serial dependence must be ~0), define causally:

```text
SAME SETUP        : identical identity key — same observation (never duplicated).
FOLLOW-ON SETUP   : a new distinct setup formed while the PREVIOUS setup's
                    outcome window is STILL OPEN (creation_timestamp is within
                    [prev.entry, prev.entry+horizon]). Its outcome window
                    overlaps the previous one -> NOT an independent sample.
INDEPENDENT SETUP : a distinct setup whose ENTRY occurs AFTER the previous
                    setup's outcome window has CLOSED (gap-separated by the
                    setup-level purge; see below).
OVERLAPPING SETUP : generic term for a setup sharing outcome-window bars with
                    another distinct setup.

DE-OVERLAP RULE (setup-level, analogous to P3.2.2 §B adapted to setups):
  define an EPISODE as a maximal run of distinct setups where successive
  entries are within the outcome horizon of the previous entry.
  LEAD SETUP (kept)   : the FIRST setup of each episode.
  FOLLOW-ON (reported): all later setups of the episode (excluded from the
                        primary independent dataset, but preserved & reported,
                        NOT deleted).
  VERIFY: for the de-overlapped stream, next_lead_entry - lead_entry > horizon.

PURPOSE: independent training observations. NOT a means to reduce samples for
better metrics; not driven by AUC.
```

---

## G. FEATURE SNAPSHOT CONTRACT (PROPOSAL — Store 2)

Every feature is causally available at entry_timestamp. This section is a
PROPOSAL from P3-S.15 §8 / §20, repeated here as the contract must bind them.
It does NOT modify docs/FEATURE_CONTRACT.md (which remains unchanged and
bar-level; the setup-level feature namespace is NEW and lives only in this
contract proposal).

```text
FEATURE-TIMESTAMP DISCIPLINE (per feature):
  feature          source         TF      as-of rule                       avail at entry?  leakage?
  h4_context       narrative state H4     newest closed H4 bar close_time <= entry        YES          NO
  m30_context      context state  M30    newest closed M30 bar close_time <= entry        YES          NO
  sweep_age_bars   liquidity event M15   entry_bar - sweep_onset                          YES          NO
  choch_age_bars   structure event M15   entry_bar - choch_onset                          YES          NO
  choch_latency    structure changeM15   (choch_onset - sweep_onset)                      YES          NO
  zone_age_bars    zone formation  M15   entry_bar - zone_formation                       YES          NO
  zone_width_atr   zone           M15   (upper-lower)/ATR(entry)                          YES          NO
  price_in_zone    zone/price     M15   (entry_close - zone)/width, etc.                  YES          NO
  dist_to_zone_atr zone/price     M15   distance(entry_close, zone)/ATR                   YES          NO
  displacement_at_creation attribute M15 value at creation_bar (closed)                   YES          NO
  m15_entry_condition condition   M15   boolean at creation_bar                           YES          NO
  m3_present / dir  micro confirmation M3 m3_bar <= W_m3 after creation (causal)          YES          NO
  sweep_size_atr    event         M15   sweep move / ATR(entry)                           YES          NO
  atr_at_entry      ATR           M15   ATR(14) over closed bars ending at entry          YES          NO

  RULE: if feature availability is uncertain at ENTRY, the generator must
        BLOCK/fail that row (do not infer). (§21.)
```

---

## H. PRICE / SPREAD / EXECUTION (label-basis)

```text
The research label uses a single REFERENCE PRICE (mid = (bid+ask)/2, or a
single close series) at the entry bar. TP/SL are computed as price offsets in
ATR units from that reference. Spread/slippage/commission are NOT applied in
P3-S.16 (an execution model is a later, separate phase). The contract records
this limitation explicitly so the research label is never misread as an
execution P&L.
```

---

## I. DATA SPLIT / REPRODUCIBILITY (§23, §24) — FUTURE REQUIREMENT (defined, not run)

```text
SPLIT (future, not executed in P3-S.16):
  - temporal split by entry_timestamp (chronological; no shuffle across time).
  - purge gap == outcome horizon between train/validation/test label windows.
  - NO overlap between label windows across split boundaries.
  - NO future information across any boundary.
  - exact split percentages = FUTURE RESEARCH PARAMETERS (OPEN; not optimized).

REPRODUCIBILITY (every future dataset generation must record):
  - source-data hash (per symbol/TF feed),
  - setup-dataset hash (deterministic over the generator),
  - contract version (this doc + label contract),
  - feature version, label version,
  - seed where applicable (deterministic generator may be seed-free),
  - generation timestamp.
  The dataset must be reproducible from the same source + contract alone.
```

---

## J. LEGACY COMPATIBILITY (§25)

```text
The new setup-level dataset is SEVERED from the legacy bar-level pipeline:
  LEGACY_L1_BAR_DRIFT  : 19 features, 24-bar direction drift, per M15 bar, MLP.
  FUTURE_L3_SETUP_OUTCOME : one Candidate Setup -> setup outcome (this contract).

The two are NEVER mixed. The legacy FEATURE_CONTRACT.md and the legacy model
remain reference-only and are NOT reused for the setup-outcome target.
```

---

## K. PROVENANCE (future observation provenance — §22)

```text
Every observation row must preserve:
  setup_id, symbol, timeframe, creation_timestamp, entry_timestamp,
  source-data provenance (dataset/hash), contract version, feature-contract
  version, label-contract version.
The dataset must not depend on undocumented external state.
```

---

## L. CONTRACT VERDICT / BOUNDARY

```text
This contract settles the SEMANTICS (unit, identity, entry, label family,
de-overlap, sampling, feature discipline, reproducibility). The following are
carried as OPEN numeric/parameter requirements (documented; NOT optimized):
  - TP/SL constants (ATR multiples)                 -> label contract OPEN
  - outcome horizon bars (semantic basis fixed)     -> label contract OPEN
  - split percentages / purge gap=numeric           -> §I OPEN
  - W_m3 (M3 confirmation lookback)                 -> frozen F3 placeholder
  - exact feature numeric lookbacks                 -> future feature contract
These OPEN parameters do NOT invalidate the CONTRACT semantics; they are the
"OPEN PARAMETERS" recorded per the session §33 classification intent, pending
authorized determination WITHOUT AUC/PF.
```

---

## M. EXPLICITLY UNCHANGED / NOT MODIFIED

```text
Candidate Setup runtime, F1, F2, F4 runtime MTF, FEATURE_CONTRACT.md,
SniperGold_ML.mqh, production .mq5/.mqh, legacy model: NONE changed by this
contract. No training, no model export, no deployment.
```

*End of P3-S.16 setup-level dataset contract v1.*