20 KiB
20 KiB
SNIPERGOLD CANONICAL SETUP CONTRACT v1
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
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)
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:
- 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)
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:
- 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)
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)
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:
- 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)
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)
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)
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)
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)
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)
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):
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:
- 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):
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)
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)
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)
- 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
- 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.