SniperGold_ML/docs/P3_S15_SETUP_LEVEL_TRAINING_CONTRACT_PROPOSAL.md

# P3-S.15 SETUP-LEVEL TRAINING CONTRACT PROPOSAL — SNIPERGOLD_ML

```text
Status   : PROPOSAL (NOT authorized implementation; NOT a new pipeline).
Session  : P3-S.15 — ML Path / Training Architecture Decision.
Date     : 2026-08-23
Scope    : Defines WHAT a future setup-level training contract must specify,
           so that a SEPARATE, AUTHORIZED implementation phase (P3-S.16 and
           beyond) can build the dataset, labels, and model without ambiguity.
           This proposal does NOT implement the pipeline, does NOT add features
           to FEATURE_CONTRACT.md, does NOT retrain, and does NOT change the
           frozen Candidate Setup.
Purpose   : Resolve the architecture-level "training-contract" question posed
           by §13 of the session brief, and hand a deterministic contract
           skeleton to the future phase.
Provenance: P3-S.15 decision docs/P3_S15_ML_PATH_ARCHITECTURE_DECISION.md;
           frozen P3-S.10 canonical contract; P3-S.13/14 handovers; P2.6/P3.1/
           P3.2/P3.2.2 forensic evidence.
Human verification : REMAINS CANCELLED (historical only).
```

---

## 1. PRINCIPLE

The future training target must be a **single discrete Candidate Setup**,
measured from its **creation bar** forward, with an outcome defined causally
and economically, and with features that are **as-of the creation decision**
(no future information). The legacy per-bar 24-bar direction "label" is a
different target and is NOT a valid setup-outcome label (P3.2 classification B).

---

## 2. OBSERVATION UNIT (what one ML sample is)

```text
ONE ROW = ONE CANDIDATE SETUP (AFCandidateSetup, frozen F3).

  setup_id               : monotonic integer, assigned at CANDIDATE_SETUP.
  direction              : +1 bullish / -1 bearish (chain direction).
  sweep_onset, sweep_dir : originating Liquidity EVENT reference.
  choch_onset, choch_dir : structure EVENT reference (after sweep).
  zone_type              : OB | FVG.
  zone_formation         : zone formation bar.
  zone_dir               : zone direction.
  zone_mit_at_creation   : mitigation state when the chain consumed it.
  creation_bar           : M15 bar when the chain completed (CANDIDATE_SETUP).
  m3_bar                 : M3 confirmation bar or -1 (optional).
  identity               : (direction, sweep onset, choch onset,
                           zone formation ts, creation ts) — causal unique key.
  lifecycle              : state + terminal reason (EXPIRED|INVALIDATED|CONSUMED).
  reasons                : provenance per stage.

  This identity is SUFFICIENT as an ML observation key (P3-S.15 §6.3/§12).
  Missing-fields check for the contract (§13 of brief):
    - The frozen object lacks explicit LOT/SL/TP (correctly outside setup
      validity: §A "trade" is outside setup). The LABEL must therefore be
      defined in the contract with its OWN TP/SL constants (a research label,
      not an object field).
    - Optional M3 confirmation is present (m3_bar).
    - H4/M30 gate states at creation are NOT stored in the setup object; the
      H4/M30 context features must be aligned to the setup's creation — this
      is a FEATURE-PIPELINE requirement, not a setup-object mutation.
```

---

## 3. LABEL CONTRACT (what P3-S.16 must define) — DIRECTION ONLY HERE

The label family to be measured (P3-S.15 §7), expressed as the future contract:

```text
TARGET: setup-outcome (L3 successor, TP-before-SL) with censoring.

  START       : the creation_bar's close (entry A = close of decision bar;
                B = next-bar open as robustness, |A-B| ~ 0.008 ATR, P3.2 §6).
  OUTCOME     : measure from creation_bar forward.
  TP          : distance in ATR (k_tp) in the setup direction.
  SL          : distance in ATR (k_sl) against the setup.
  HORIZON     : bounded by the FRESH SETUP LIFETIME (P3.2 §6/§8: common
                outcomes within 1-8 bars; ~90% <= 8; low censoring >= H16).
  CLASSES     : WIN / LOSS / UNRESOLVED (censored) / AMBIGUOUS (same-bar TP+SL).
                UNRESOLVED is true censoring — MUST NOT be forced to LOSS.
  INVALIDATION: opposite structure break (f8/f5 flip) and/or canonical
                lifecycle INVALIDATED — recorded as a secondary metric, NOT a
                replacement for SL (P3.2.2 §I: SL is faster than structure invalidation).

CONTRACT ITEMS the future phase must FIX in advance (NOT selected from AUC/PF):
  - k_tp / k_sl values (and whether symmetric or asymmetric R:R).
  - horizon length (bars) consistent with setup lifetime.
  - censoring handling rule (UNRESOLVED treatment; exclusion or survival).
  - de-overlap rule at the SETUP level: distinct setups with overlapping
    outcome windows -> lead-setup-per-episode policy (analogous P3.2.2 §B).
  - class-balance handling (real distribution is LOSS-heavy on old units;
    must be re-measured on canonical setups, not artificially balanced).
  - entry semantics (A = close of creation bar; B robustness).

SEVERED: the 24-bar / 0.75 ATR DIRECTION label is NOT the setup-outcome label.
```

---

## 4. FEATURE ARCHITECTURE (proposal; NOT added to FEATURE_CONTRACT.md)

Aligned to the canonical setup entity (P3-S.15 §8). Every feature is as-of the
frozen MTF as-of contract (all consumed bars closed before creation-bar close):

```text
H4 narrative state (gate direction), M30 context state (gate direction),
Liquidity EVENT ref (onset, dir, freshness, size/ATR),
CHoCH EVENT ref (onset, dir, latency after sweep),
ZONE ref (OB|FVG, age, width/ATR, price-in-zone offset, mit-at-creation),
Displacement attribute at creation,
M15 entry condition boolean + premium/discount filter + distance-to-zone/ATR,
M3 confirmation presence + direction,
identity/times (creation_bar, times-since-onset, time-since-zone-formation,
setup lifecycle stage),
geometry (zone geometry, distance measures).

These are a PROPOSAL ONLY. The full numeric contract (lookbacks, conditions,
defaults) will be authored in P3-S.16 as a NEW proposal document, keeping
docs/FEATURE_CONTRACT.md unchanged (§19 policy).
```

---

## 5. COMPARABILITY / PIPELINE

```text
Proposed future pipeline (NOT built here):
  Market Data -> SMC primitives -> repaired Events/Zones -> Candidate Setup
  -> Setup Snapshot -> Outcome Label -> ML Dataset -> setup-level model.

The old pipeline (M15 bars -> features -> 24-bar label -> MLP) is NOT
comparable as a predictor: unit, label, MTF set and consumer semantics all
differ (P3-S.15 §11.3). The legacy pipeline is retained only as evidence.
```

---

## 6. STATUS

```text
PROPOSAL ONLY. This document authorizes nothing and builds nothing.
   - No dataset created.
   - No label computed.
   - No model trained.
   - FEATURE_CONTRACT.md not modified.
   - Candidate Setup / F1 / F2 / runtime unchanged.
The P3-S.16 IMPLEMENTATION phase is a separately-authorized scope that will
consume this contract skeleton. No retrain / no optimization preceded it.
```

*End of P3-S.15 setup-level training contract proposal (documentation only).*