SniperGold_ML/docs/P3_S16_LABEL_CONTRACT.md

# P3-S.16 LABEL CONTRACT — SNIPERGOLD_ML (Setup-Outcome)

```text
Status   : AUTHORITATIVE LABEL CONTRACT for the FUTURE_L3_SETUP_OUTCOME target.
Scope    : Defines the setup-outcome label (TP-before-SL) for P3-S.16 and the
           future training phase. This is Store 3 (outcome) of the setup-level
           dataset contract. ORACLE for label computation in the generator.
Session  : P3-S.16 — Setup-Level Dataset / Label Contract Implementation.
Date     : 2026-08-23
Verbatim target: ONE Candidate Setup -> SETUP OUTCOME (TP-before-SL).
              SEPARATE from the legacy L1 directional-dRIFT label (§J).
Numeric selections: constants below are semantic candidates recorded as OPEN
              parameters; they must NOT be finalized by AUC/PF (session §29).
Provenance: P3-S.15 proposal §3; P3.2 (docs/P3_2_LABEL_FORENSIC.md)
           P3.2.2 (docs/P3_2_2_DEOVERLAP_SURVIVAL.md)
Human verification : REMAINS CANCELLED.
```

---

## A. PRINCIPLE

The label must measure **whether the expected setup outcome occurred BEFORE
invalidation**, not "future price direction." P3.2 (official classification B —
LABEL IS MISALIGNED) established the 24-bar/0.75 ATR label measures directional
drift (L1), not setup validation. P3.2.2 established the L3 (TP-before-SL)
mechanism is viable on a discrete setup unit. This contract instantiates that
mechanism on the CANONICAL Candidate Setup.

---

## B. ENTRY (from dataset contract §D — repeated for the label)

```text
entry_timestamp = CLOSE of the CANDIDATE_SETUP creation bar (M15).
entry_price     = creation_bar close (mid reference, contract §H).
```

---

## C. OUTCOME CLASSES

```text
WIN        : the TP level is reached BEFORE the SL level.
LOSS       : the SL level is reached BEFORE the TP level.
UNRESOLVED : neither TP nor SL is reached within the HORIZON (censored), OR
             there is insufficient future data (end of series / gap), OR the
             remaining path is not price-continuous enough to decide.
AMBIGUOUS  : the TP and SL are triggered within the SAME bar (same-bar
             conflict) — cannot be resolved without finer data; classified per
             the contract's deterministic rule (§F), never by arbitrary OHLC
             ordering.
```

---

## D. TP / SL SEMANTICS (§11, §14)

```text
TP_LEVEL = setup_direction * k_tp * ATR(entry)   above/below entry_price.
SL_LEVEL = setup_direction * k_sl * ATR(entry)   opposite to entry direction.

REFERENCE : ATR at ENTRY (causally available at entry; NOT post-entry
            recalculation — fixed at entry for the whole measurement).
ATR basis : rolling 14-bar M15 ATR ending at the entry bar (the project's
            contract ATR convention, FEATURE_CONTRACT §0).
SYMMETRY  : the contract allows BOTH symmetric (k_tp==k_sl) and asymmetric
            (k_tp!=k_sl) configurations, selected as an OPEN parameter; the
            DEFAULT CANDIDATE recorded from P3.2 evidence is asymmetric
            TP=1.5 ATR / SL=0.75 ATR (a 2:1 semantic R-R), with 1.0/1.0 as a
            symmetric robustness sensitivity.
            Explicitly: the choice of constants is OPEN (not AUC-optimized).
```

---

## E. HORIZON (§13)

```text
SEMANTIC BASIS (from P3.2/P3.2.2 lifetime evidence):
  - setup outcomes mostly occur within 1-8 M15 bars; ~90% within 8;
    >98% within 16; <= 24 adds only late SL (P3.2.2 §G).
  - the old 24-bar horizon FAR exceeded the setup lifetime and measured drift.

CONTRACT:
  PRIMARY HORIZON : H = 16 M15 bars (semantic: captures >98% of outcomes with
                    low censoring). Chosen on LIFETIME evidence, not metrics.
  ROBUSTNESS       : H = 8 (short) recorded as robustness; NOT a substitute.
  TIMEOUT          : if neither TP nor SL by bar H -> UNRESOLVED (censored).

H is recorded as an OPEN numeric parameter pending authorized confirmation,
but its SEMANTIC basis (setup lifetime <= ~16 bars) is fixed by evidence, not
optimization.
```

---

## F. FIRST-HIT & SAME-BAR AMBIGUITY (§15, §17)

```text
FIRST-HIT RULE : scan bars strictly AFTER the entry bar, in time order; the
                 FIRST bar in which either TP or SL is touched decides:
                   - TP only  -> WIN
                   - SL only  -> LOSS
                   - both     -> AMBIGUOUS (§F2)
                   - neither  -> continue until H; then UNRESOLVED.

SAME-BAR TP/SL (both touched within one bar):
  The contract does NOT assume intra-bar OHLC ordering (which touch came
  first is undecidable from OHLC without tick chronology). Rule:
    SAME-BAR AMBIGUOUS : classify AMBIGUOUS deterministically. It is neither
    WIN nor LOSS. (No arbitrary "open vs close first" assumption.)

VAILIATION: if the project later adopts lower-timeframe reconstruction or tick
chronology, that becomes a SEPARATE, authorized revision of THIS rule — it is
not decided by P3-S.16 and not improvised here.
```

---

## G. CENSORING / UNRESOLVED (§16)

```text
UNRESOLVED occurs EXACTLY when:
  (a) neither TP nor SL by bar H within available price data, OR
  (b) insufficient future data to reach H (end of series / history cut), OR
  (c) a market-closure / data-gap makes the path non-continuous (price cannot
      be traced between the last available bar and the next), so outcome cannot
      be causally determined.
RULE: UNRESOLVED is TRUE censoring. It is NEVER forced to LOSS. It is excluded
from any naive accuracy count and reported as its own class (or handled with
survival-style methods in a later phase).
```

---

## H. INVALIDATION (secondary; recorded, not primary)

```text
The canonical lifecycle can invalidate a setup (EXPIRED / INVALIDATED /
CONSUMED) BEFORE the TP/SL needle resolves. For the LABEL CONTRACT:
  - TP/SL (price) remains the PRIMARY outcome (P3.2.2 §I: SL is faster than
    structure invalidation; invalidation rarely precedes TP/SL).
  - a setup that is lifecycle-INVALIDATED before TP/SL is recorded with
    label_invalidated_early=True and the price outcome is still resolved by
    TP/SL; the invalidation is a SECONDARY diagnostic, not a label replacement.
```

---

## I. LABEL CONTRACT STATUS

```text
Semantics settled: WIN / LOSS / UNRESOLVED / AMBIGUOUS fully defined, with
entry, TP/SL, horizon, first-hit, same-bar ambiguity, censoring, missing-data,
and session/gap behavior defined (§B-§H).
OPEN parameters (semantically anchored, NOT optimized by AUC/PF):
  - k_tp / k_sl (default candidate 1.5/0.75; robustness 1.0/1.0),
  - H (primary 16, robustness 8),
  - W_m3 (frozen F3 placeholder) if used in features.
Classified accordingly in the final verdict as "CONTRACT COMPLETE WITH
OPEN PARAMETERS" — semantics fully settled.
```

---

## J. LEGACY SEVERANCE

```text
LEGACY_L1_BAR_DRIFT   : 24-bar / 0.75 ATR DIRECTION drift (never reused here).
FUTURE_L3_SETUP_OUTCOME: setup-outcome TP-before-SL (THIS contract).
Only the FUTURE_L3_SETUP_OUTCOME label is produced by the P3-S.16 generator.
```

---

## K. REPRODUCIBILITY

```text
Label computation is deterministic over (source price, setup identity, TP/SL
constants, H, ambiguity rule). A future dataset records the label-contract
version + generator version + constants hash for reproducibility (§24).
```

*End of P3-S.16 label contract.*