SniperGold_ML/docs/SNIPERGOLD_CANONICAL_SETUP_CONTRACT_v1.md

# SNIPERGOLD CANONICAL SETUP CONTRACT v1

```text
Status   : PROPOSED AUTHORITATIVE DESIGN CONTRACT (FROZEN at design level)
Session  : P3-S.10 — Owner Adjudication & Canonical Setup Contract Freeze
Date     : 2026-08-22
Scope    : The single canonical definition of ONE Candidate Setup and the
           H4/M30/M15/M3 participation contract for the SniperGold_ML /
           Algo Forge project. This document is the DESIGN contract only.
           NOT implemented. No production file modified.
Decisions: OD-1..OD-5 resolved in docs/P3_S10_OWNER_ADJUDICATION.md
           (this contract implements those decisions).
Supersedes: SMC_CANDIDATE_SETUP_SPEC_v1.md §CS-1..CS-3 (Definition A as
           the setup definition) for the SETUP LAYER ONLY — see §J.
           All historical docs remain immutable; the supersession is
           recorded, not rewritten.
Provenance: Forge HEAD 533c8c6647a552d01a1a290cb2d0505f94887666 (P3-S.6);
           P3-S.7/P3-S.8/P3-S.9 artifacts intact. Human verification CANCELLED.
```

---

## A. OBJECTIVE

```text
A Candidate Setup is a DISCRETE, CAUSALLY-ORDERED ENTITY created on the M15
entry layer when a COMPLETE sequence completes within its validity windows:

  H4 context gate (direction-compatible)
    AND M30 context gate (direction-compatible)
    AND fresh Liquidity EVENT
    AND CHoCH/MSS EVENT after the sweep (fresh, same direction)
    AND price inside an UNMITIGATED OB or FVG ZONE (direction-compatible)
    AND M15 entry condition
  -> CANDIDATE_SETUP (direction = chain direction)
  [M3 micro-confirmation: OPTIONAL -> M3_CONFIRMED; absence does not
   invalidate the Candidate Setup.]

It is an ENTITY (one setup = one identity = one lifecycle), NOT a per-bar
fuzzy weight, NOT a score, NOT a vote, and NOT a signal.

What it is NOT (explicit, kept from P3-S.8 R-1..R-5 and P3-S.9 D.1):
  market state  : H4/M30 context states are INPUTS to the chain, not the setup.
  event         : sweep/CHoCH are STAGES of the setup, not the setup.
  zone          : OB/FVG membership is the ZONE stage, not the setup.
  confirmation  : CHoCH/M15 confirmation is a STAGE, not the setup.
  score         : confluence/score may RANK setups but never creates one.
  signal        : a directional signal may exist WITHOUT a setup; an ENTRY
                  SIGNAL may only be emitted for a valid setup.
  trade         : execution (lot/SL/TP/result) is outside setup validity.
```

---

## B. CANONICAL MTF MODEL (OD-2)

```text
CANONICAL RUNTIME/SETUP MODEL (frozen):

  H4  = NARRATIVE / higher-TF CONTEXT STATE   (gate)
  M30 = CONTEXT STATE                         (gate)
  M15 = ENTRY / CHAIN CARRIER                 (setup layer)
  M3  = PRICE ACTION / OPTIONAL MICRO CONFIRMATION

Role definitions:
  H4  Narrative  : "Which way is the market?"  (trend/structure state)
  M30 Context    : "Which zone is price in?"   (zone/S-R state)
  M15 Entry      : "Is there entry confirmation?" (the setup chain lives here)
  M3  Price Act. : "When to open?"             (optional micro confirmation)

TRAINING SEMANTICS (unchanged this session, recorded for alignment):
  D1/H4/H1 + M15 = legacy/current training semantics (FEATURE_CONTRACT f0-f18).
  H4/M30/M15/M3  = canonical setup/runtime semantics.
  -> The ML pipeline is NOT modified. A FUTURE alignment requirement (F4)
     must reconcile training to the canonical model or document the
     divergence as intentional. D1/H4/H1 is deprecated to REFERENCE status
     for the agent/setup path (P3-S.7 D-6).
```

---

## C. PRIMITIVE ROLES (frozen)

| Primitive | Role (canonical) | Required? | Produces | Window |
|---|---|---|---|---|
| H4 | CONTEXT STATE (Narrative) | REQUIRED — direction-compatible gate | STATE | as-of closed bar |
| M30 | CONTEXT STATE (Context) | REQUIRED — direction-compatible gate | STATE | as-of closed bar |
| Liquidity Sweep | EVENT (stage 1 of chain) | REQUIRED | EVENT | W_sweep = 40 M15 bars |
| CHoCH/MSS | STRUCTURAL EVENT (stage 2, after sweep) | REQUIRED | EVENT | W_choch = 40 M15 bars |
| OB | ZONE (stage 3 — OB OR FVG) | ALTERNATIVE | ZONE | unmitigated; no age expiry |
| FVG | ZONE (stage 3 — OB OR FVG) | ALTERNATIVE | ZONE | unmitigated; no age expiry |
| Displacement | ATTRIBUTE / OPTIONAL CONFIRMATION | OPTIONAL | ATTRIBUTE | per-bar only |
| M15 | ENTRY CONDITION / CHAIN CARRIER | REQUIRED | CONDITION | per closed M15 bar |
| M3 | OPTIONAL MICRO CONFIRMATION | OPTIONAL | CONDITION/EVENT | optional (W_m3 open) |

Rules:
```text
- No primitive holds two conflicting roles; the table is the single role map.
- H4/M30 are GATES for the setup layer (OD-1), overriding P3-S.7 S-N/S-C
  permissiveness FOR THE SETUP LAYER ONLY. The flat vote remains a
  signal-scoring layer on top of valid setups.
- FILTER: premium/discount position is a FILTER on the M15 entry condition
  (not in premium for buy / not in discount for sell), carried from legacy
  Definition B.
- SCORE: confluence may RANK setups (post-creation); it never creates one.
```

---

## D. REQUIRED CANDIDATE SETUP CHAIN (frozen)

```text
H4 context gate (direction-compatible)
        |
        v
M30 context gate (direction-compatible)
        |
        v
fresh Liquidity EVENT (M15, W_sweep)
        |
        v
CHoCH/MSS EVENT after the sweep (M15, W_choch, same direction)
        |
        v
unmitigated OB OR FVG ZONE (M15, direction-compatible, mitigation-aware)
        |
        v
M15 entry condition (zone membership + confirmation conjunction;
        premium/discount filter; displacement may boost)
        |
        v
CANDIDATE_SETUP
        |
        v
[optional M3 confirmation -> M3_CONFIRMED]
```

Chain invariants:
```text
- Strict stage order; no skipping.
- CHoCH onset >= sweep onset (causal order, legacy B semantics).
- Every stage must complete within its own validity window; a lapsed stage
  prevents CANDIDATE_SETUP (the forming setup is discarded).
- The zone must be UNMITIGATED at every decision bar; mitigation mid-chain
  invalidates the setup.
- Direction = chain direction; every stage must be direction-compatible.
```

---

## E. SETUP IDENTITY (frozen)

```text
setup_id               : monotonic integer, assigned at CANDIDATE_SETUP
direction              : +1 bullish / -1 bearish (chain direction)
originating liquidity  : {sweep onset timestamp, sweep direction,
                          sweep validity window}
structure event        : {choch onset timestamp, choch direction}
zone                   : {zone type (OB|FVG), zone formation timestamp,
                          boundaries, mitigation state at creation}
entry timeframe        : M15 (fixed by construction)
creation timestamp     : M15 bar timestamp when the chain completed
confirmation timestamp : M3 bar timestamp when M3_CONFIRMED (nullable)
expiry/invalidation    : enumerated (EXPIRED|INVALIDATED|CONSUMED|NONE)

UNIQUENESS: two setups differ iff (direction, sweep onset, choch onset,
zone formation timestamp, creation timestamp) differ.
The identity is CAUSAL — every component is a dated event/zone/state from
the chain. No arbitrary/random id.
```

---

## F. SETUP LIFECYCLE (frozen)

```text
NONE
  |
  v
CONTEXT_VALID        (H4 + M30 direction-compatible states; as-of <= t)
  |
  v
LIQUIDITY_TRIGGERED  (sweep EVENT fresh; window W_sweep)
  |
  v
STRUCTURE_CONFIRMED  (CHoCH EVENT after sweep, fresh; window W_choch)
  |
  v
ZONE_READY           (price inside an UNMITIGATED OB|FVG zone;
                      zone mitigation terminates -> INVALIDATED)
  |
  v
ENTRY_ARMED          (M15 entry condition holds; displacement may boost)
  |
  v
CANDIDATE_SETUP      (COMPLETE — the chain is whole; direction fixed)
  |--(optional M3 alignment)--> M3_CONFIRMED (micro-confirmed)
  |--(setup validity window exceeded)-------> EXPIRED
  |--(zone mitigated / contrary CHoCH / context break) -> INVALIDATED
  |--(entry signal emitted from this setup)--> CONSUMED
```

Transition rules:
```text
- Every stage requires the previous stage ACTIVE (no skipping).
- Sweep and CHoCH are EVENTS: they set the stage at onset; the stage expires
  when its validity window lapses.
- A stage expiry BEFORE CANDIDATE_SETUP discards the forming setup (it never
  becomes a Candidate Setup; recorded EXPIRED/INVALIDATED for diagnostics).
- ZONE_READY requires an UNMITIGATED zone at every decision bar.
- ENTRY_ARMED is re-evaluated per closed M15 bar (price may leave the zone;
  the setup is NOT destroyed by exit; it waits for re-entry within its
  validity window).
- CANDIDATE_SETUP is the terminal FORMATION state; EXPIRED/INVALIDATED/
  CONSUMED are terminal, NON-REVERSIBLE (no reactivation).
- AT MOST ONE entry signal per setup (CONSUMED); a new setup requires a new
  chain (dedup by identity).
- M3_CONFIRMED is optional: absence does not invalidate; a contrary M3
  reduces only the micro-score (OD-4).
```

---

## G. ONE-SETUP-ONE-IDENTITY RULE (frozen)

```text
ONE CAUSAL SETUP = ONE SETUP IDENTITY.

A Candidate Setup must NOT be recreated every bar. The identity (§E) is
derived from dated chain components; while the chain's stages remain active,
the same identity persists across bars. Deduplication is BY CONSTRUCTION:
a new setup exists only when a NEW chain completes (new sweep onset /
new CHoCH / new zone reference), producing a distinct identity.
```

---

## H. ONE-ENTRY RULE (frozen)

```text
MAXIMUM ONE ENTRY SIGNAL PER SETUP.

A setup that has emitted its entry signal is CONSUMED and cannot re-emit.
Multiple entries require multiple setups (multiple chains). This is the
project default and is ADOPTED (no evidence in project intent for
multiple entries per setup; legacy B fires one signal per gate pass).
```

---

## I. SCORE SEPARATION (frozen)

```text
SCORE != SETUP EXISTENCE.

- The flat aggregator (weighted vote) becomes a SCORING/RANKING function over
  VALID setups (P3-S.9 §M.1, resolves D-9/D-1 partially).
- A score cannot create a setup; a setup can exist with any score.
- Scoring may rank setups (e.g., confluence, weight, confidence) but never
  substitutes for the chain.
- The aggregated vote may still produce a DIRECTIONAL SIGNAL without a setup
  (§J) — that is a bias, not an entry recommendation.
```

---

## J. SIGNAL SEPARATION (frozen)

```text
SIGNAL != CANDIDATE SETUP.

Two signal concepts are distinguished:
1. DIRECTIONAL SIGNAL (informational): the aggregated vote / any single-TF
   bias. MAY exist without a Candidate Setup (H4-only, M30-only, M15-only
   signals remain possible). This is NOT an entry instruction.
2. ENTRY SIGNAL (actionable): BUY/SELL with entry/SL/TP. MAY ONLY be emitted
   when bound to a VALID CANDIDATE_SETUP (or M3_CONFIRMED) entity.
   Resolves P3-S.8 D-9 and P3-S.9 §M.1.

Consequence (P3-S.7 S-N/S-C overridden AT THE SETUP LAYER only):
  - H4-only BUY may exist as a DIRECTIONAL SIGNAL.
  - H4-only BUY may NOT create a Candidate Setup (context gate alone is a
    STATE, not a setup).
```

---

## K. EVENT / ZONE / STATE / ATTRIBUTE / CONDITION CONTRACT (frozen)

```text
EVENT     (sweep, choch, m3):
  { timestamp      : onset bar open time
    direction      : +1 / -1 / 0
    valid_until    : timestamp + validity window (unit: bars of its TF)
    superseded     : bool — a newer onset of the same type replaced it
    source         : detector/feature id (e.g., f7, AF_DetectSweep) }
  Consumers may read ONLY within [onset, valid_until] and only if NOT
  superseded. (Fixes root causes A, C, D.)

ZONE      (OB, FVG):
  { timestamp      : formation timestamp (OB = open of candle B; FVG = open of C3)
    direction      : +1 / -1
    upper_bound    : zone top
    lower_bound    : zone bottom
    mitigation_state : UNMITIGATED | MITIGATED
    invalidated    : bool (setup-level terminal flag) }
  Consumers may read ONLY unmitigated, non-invalidated zones.
  Mitigation: OB = close-through full fill (P3-S.5 S-9);
              FVG = wick full-fill (P3-S.4 S-9 legacy canonical).
  (Fixes root causes B, D.)

STATE     (H4 narrative, M30 context):
  { value     : +1 / -1 / 0
    as_of     : closed bar timestamp
    timeframe : H4 | M30 }
  Consumers may read the NEWEST closed value only. (Fixes root cause A.)

ATTRIBUTE (displacement):
  { value         : +1 / -1 / 0
    bar_timestamp : the closed bar it was evaluated on
    timeframe     : M15 (canonical consumer) }
  No persistence, no expiry (already conforming, P3-S.6).

CONDITION (M15 entry, M3 micro):
  { boolean   : true / false
    as_of     : closed bar timestamp
    timeframe : M15 | M3
    reason    : human-readable stage reference }
  The E-rule output, re-evaluated each closed bar. (Fixes D-11.)

CONSUMER CONTRACT (the rule that prevents the f7/f9/f18 bug class):
  - A consumer of an EVENT must apply its validity window.
  - A consumer of a ZONE must apply mitigation/invalidation.
  - A consumer of a STATE must use the as-of closed value.
  - A consumer of a SETUP must use identity + lifecycle, never raw detector
    states.
```

---

## L. MTF AS-OF CONTRACT (frozen)

```text
For a decision at M15 timestamp t (decision bar = newest CLOSED M15 bar):

  H4_asof(t)  : newest CLOSED H4 bar with close_time <= t
  M30_asof(t) : newest CLOSED M30 bar with close_time <= t
  M15_asof(t) : newest CLOSED M15 bar with close_time <= t (= decision bar)
  M3_asof(t)  : newest CLOSED M3 bar with close_time <= t

Invariants (must hold for EVERY decision):
  H4_close_time  <= t
  M30_close_time <= t
  M15_close_time <= t
  M3_close_time  <= t

Rules:
  - latest CLOSED bar only; no future bar; no partial HTF candle.
  - Mechanism: Engine 1 closed-bar lock (P3-S.7 S-T) — cache holds ONLY
    closed bars; the forming bar is dropped at Build.
  - Deterministic HTF-close visibility: a new H4 bar closed at 04:00 becomes
    visible at the first decision time t >= 04:00 (P3-S.7 S-T).
```

---

## M. VALIDITY-WINDOW CONTRACT (OD-3)

Each primitive has its OWN validity semantics. A single global SeqWindow is
NOT reused everywhere.

| Window | Primitive | Unit | Start | End condition | Numeric |
|---|---|---|---|---|---|
| W_sweep | Liquidity EVENT | M15 bars | sweep onset bar b | b + W_sweep | **40** (justified: InpSeqWindow=40, P3-S.0/P3-S.2 R-H) |
| W_choch | CHoCH/MSS EVENT | M15 bars | CHoCH onset bar b' | b' + W_choch | **40** (justified: legacy gate freshness, P3-S.3 S-9/S-10) |
| W_zone_age | OB/FVG ZONE | M15 bars | zone formation | no age expiry (mitigation/invalidation only) | **NONE by semantics** (P3-S.4 S-8, P3-S.5 S-8); an explicit cap = OPEN NUMERIC PARAMETER |
| W_m3 | M3 micro-confirmation | M3 bars | setup formation | setup validity end | OPEN NUMERIC PARAMETER (optional; absence does not invalidate) |
| W_setup | Candidate Setup | M15 bars | creation timestamp | creation + W_setup | OPEN NUMERIC PARAMETER (no project semantics justify a value; must NOT be selected from performance) |

Chain-ordering bound (causal, not a window):
```text
sweep onset <= CHoCH onset          (CHoCH after the sweep)
CHoCH onset <= sweep onset + W_sweep (sweep still fresh when CHoCH occurs)
decision t  <= CHoCH onset + W_choch (CHoCH still fresh at decision)
zone leg    : unmitigated at every decision bar
```

Terminal semantics per primitive:
```text
- EVENT  : expiration = EXPIRED after window; supersession = newer onset;
           consumption = read-only (consumers read; the SETUP consumes stages).
- ZONE   : expiration = NONE (persistent); invalidation = mitigation is the
           terminal usable-state; setup-level INVALIDATED marks the zone
           reference dead inside that setup.
- STATE  : no lifecycle (recomputed per closed bar).
- ATTRIBUTE : no lifecycle (per-bar).
- SETUP  : EXPIRED / INVALIDATED / CONSUMED (terminal, non-reversible).
```

OPEN NUMERIC PARAMETERS (recorded, NOT selected from performance):
```text
W_setup    : post-formation Candidate Setup validity (M15 bars).
W_m3       : M3 confirmation lookback after setup formation (M3 bars).
W_zone_age : optional cap on zone age (default: none — project semantics).
FVG min-gap / OB min-size / zone-consumer scope : F2/F6 scope (P3-S.4 A-1,
             P3-S.5 A-1/A-3/A-5).
```

---

## N. MTF CONFLICT POLICY (OD-4)

```text
For the SETUP LAYER (frozen):

  H4  <-> M30 conflict (opposite signs):
      Candidate Setup = BLOCKED (context gate fails).

  H4/M30 compatible, M15 chain conflicts with H4 or M30:
      Candidate Setup = BLOCKED (gate fails). NOT arithmetic.

  M3 conflict (contrary micro-confirmation):
      M3_CONFIRMED = FALSE.
      The Candidate Setup MAY remain valid (M3 is optional).
      A contrary M3 reduces ONLY the micro-score.

CANONICAL AUTHORITY:
  H4/M30 = directional context GATES
  M15    = setup authority (the chain carrier)
  M3     = optional micro confirmation (no veto, no arithmetic role)

No arithmetic voting resolves setup-layer conflicts. The flat aggregator
may continue to exist LATER as a scoring/signal layer, but it is NOT the
canonical definition of Candidate Setup.
```

---

## O. CANONICAL ORDER BLOCK SEMANTICS (OD-5)

```text
CANONICAL OB (frozen):
  Formation : opposite-color closed candle B immediately before a strong-move
              closed candle M; |body(M)| >= 1.5 x avg body (20-bar mean).
  Zone      : full range of B: [Low(B), High(B)].
  Direction : +1 bullish (bearish B + bullish M); -1 bearish; 0 none.
  Structural precondition : NONE (BOS/CHoCH/displacement/liquidity NOT
              required for OB detection — P3-S.5 S-5).
  Mitigation: close-through full fill (P3-S.5 S-9).
  Invalidation: not modeled at zone level; setup-level flag per §K.

ADJUDICATION (explicit answers to the A/B/C/D/E question):
  A. YES — the OB "strong move" (1.5x avg body) is INTENTIONALLY a simpler
     proxy for Displacement (1.6x avg body): same concept family, lower
     threshold, ZONE-FORMATION gate (P3-S.6 §7 answer B, adopted).
  B. NO — OB does NOT require canonical Displacement as an input.
     Displacement remains an independent OPTIONAL confirmation attribute
     (P3-S.6 S-5/S-7/S-13). The 1.5 vs 1.6 constants are KEPT SEPARATE and
     documented (BUG-P3S6-001 -> DOCUMENT ONLY, F6) — unifying would modify
     a validated CONFORMING detector and conflate two distinct roles
     (zone-formation gate vs confirmation attribute).
  C. NO — OB does NOT require BOS/CHoCH. The legacy structure-break
     definition (P3-S.5 A-2) is historical and non-canonical. In the
     canonical Candidate Setup chain the CHoCH stage ALREADY supplies the
     structural confirmation; a separate OB structural-break requirement is
     REDUNDANT (it would re-require a structure event the chain already
     demands and would create an inconsistency with the FVG alternative,
     which has no structural requirement).
  D. The canonical OB = (opposite-color candle B) + (strong move M,
     1.5x avg) + (zone = full range of B) + (unmitigated until close-through
     full fill). No additional combination.
  E. RESOLVED — not left open.

SUPERSEDED BY OD-5: any reading of SMC_ORDER_BLOCK_SPEC_v1.md §5 that
treats the legacy structure-break definition as canonical for the setup
layer. The spec's CANONICAL current definition (S-1..S-9) is CONFIRMED
unchanged.
```

---

## P. SOURCE OF THE CONTRACT (evidence anchors)

```text
- Chain shape  : the project's own legacy v4.x institutional gate
                 (P3-S.8 Definition B), the only real setup state machine.
- Causal order : the brief's causal order (Liquidity -> Structure Change ->
                 Zone -> Return -> Confirmation) + DESIGN.md top-down order.
- M3 optional  : P3-S.7 S-P evidence ("M3 is NOT mandatory; can only reduce
                 support arithmetically").
- M15 entry    : the E-rule (Definition A) retained ONLY as the M15
                 entry-condition predicate inside the chain (P3-S.9 D.1).
- Windows      : W_sweep/W_choch = 40 from InpSeqWindow origin
                 (P3-S.0/P3-S.2/P3-S.3), NOT from performance.
- Identity/lifecycle/contracts : P3-S.9 §G/§H/§I design contracts, frozen.
- As-of        : P3-S.7 S-T closed-bar lock.
```

---

## Q. NON-GOALS OF THIS CONTRACT

```text
- NO ML pipeline change (D1/H4/H1 training semantics untouched this session).
- NO FEATURE_CONTRACT.md modification.
- NO production code change (no .mq5/.mqh/.py modified).
- NO numeric selection from AUC/PF/profit/backtest.
- NO human verification restart.
- NO legacy v4.x code restoration (semantics extracted only).
```

*End of SNIPERGOLD_CANONICAL_SETUP_CONTRACT_v1.*