# 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.*