# SMC LIQUIDITY SWEEP — PROJECT SEMANTIC SPECIFICATION v1 ```text Status : PROJECT SEMANTIC SPECIFICATION (not "universal SMC ground truth") Session : P3-S.2 — Formal Specification + Code-Conformance Audit Date : 2026-08-22 Scope : The Liquidity Sweep primitive as consumed by feature f7 (sweep_dir) and its semantic consumers (f9 choch_confirm, f18 confluence). Secondary reference : AF_DetectSweep (Engine 2) — discussed as an implementation comparison, NOT as the definition. Provenance : P2 8d330343 | contract C44CC6F2 (P2-era) / 7b908b12 (committed) model 06df8452 | machine v2 6d7c0b41 | case set da3a0d01 ``` > This document ESTABLISHES what "Liquidity Sweep" means in the SniperGold_ML / > Algo Forge project, derived from: (a) the SMC concept (SniperGold SMC ProPlus > 75466), (b) project design intent (FEATURE_CONTRACT, DESIGN.md, > DESAIN_MTF_v45.md), (c) explicit logical requirements, (d) temporal causality. > This document is NOT a claim of universal SMC truth; the term "sweep" may have > different definitions outside this project. --- ## 1. CONCEPTUAL DEFINITION (CORE) **Liquidity Sweep** is a price-action *event* in which: 1. A **reference liquidity level** already exists before the event (temporal causality: the reference precedes the penetration); 2. **Price breaks through the level** (excess/wick penetration); 3. **Price closes back across the level** (rejection / close-back); 4. The event carries a **direction interpretation opposite to the taken side**: - *buy-side* liquidity taken (above the high) → **bearish** intent (-1); - *sell-side* liquidity taken (below the low) → **bullish** intent (+1). This definition is consistent with the SniperGold SMC ProPlus 75466 description and the `AF_DetectSweep` comment: `"+1 sell-side swept then price returns (bullish), -1 buy-side swept then price returns (bearish)"`. --- ## 2. LIQUIDITY REFERENCE (answer 7.1) Validity table for each reference type in the project: | Reference Type | Valid? | Used by | Justification | |----------------|--------|---------|---------------| | **Equal High (EQH)** | VALID (for the EQ primitive) | f10 `eqh_swept` | The project adopts EQH/EQL as liquidity references (P2.2, legacy v4.4) | | **Equal Low (EQL)** | VALID (for the EQ primitive) | f11 `eql_swept` | Same as EQH | | **Swing High / Swing Low (fractal len=50)** | VALID | f10/f11 (EQ pairs), f6/f14/f15/f17 (sw_high/sw_low) | Main project structure reference (InpSwingLen=50) | | **Internal Swing High / Low (fractal len=5)** | VALID — **the ONLY reference for f7** | f7 `sweep_dir` | FEATURE_CONTRACT f7: "internal pivot"; InpInternalLen=5 | | **External swing / HTF level (D1/H4/H1)** | NOT VALID for f7 | — | HTF provides only direction bias (f0-f2), not the f7 liquidity reference. Project status: see §10 (SPECIFICATION AMBIGUOUS at the project level) | | **Others (trendline, round number, volume node)** | NOT VALID | — | Not represented in any implementation; out of scope | Important notes: - For the **f7 sweep event**, one reference = **one internal swing high/low level** (not a pair, not EQ, not an HTF level). - f10/f11 use EQ references (swing len=50 pairs) and are *state* primitives "level broken", not sweep events — the two must **not be mixed** as one definition (see §6). --- ## 3. REFERENCE FORMATION (answer 7.2) ```text Pivot definition : symmetric fractal high/low, length INTERNAL_LEN = 5 (5 left bars + 5 right bars). Equal-height/low bars do NOT cancel a pivot (only STRICTLY higher/lower bars cancel). Lookback / window : 700-bar cache ending at the decision bar t; 600-bar analysis region; internal pivots effectively on bars [max(95, t-604), t-5] (derived: begin = max(100, t-599); pivot p = i-LEN, i in [begin, t], LEN=5). Full-cache case (t>=699): p in [t-604, t-5]. Swing len=50 pivots on [t-649, t-50] (contract §0 — for f10/f11). Minimum bars : a pivot needs 5 confirmation bars on each side; analysis starts at begin = max(100, t-599); the EA gate requires at least AF_BT_MIN_BARS = 160 bars before analysis. Equal-level tolerance : NONE for f7 (single pivot; no price tolerance). EQ tolerance (0.10*ATR) is only for f10/f11. ATR tolerance : NONE for the f7 reference formation. Reference lifetime : the pivot list is rebuilt every bar from the cache. A pivot stays a candidate while inside the analysis window and not yet swept. Closed-bar : a pivot is only formed if all confirmation bars (p-5 .. p+5) <= t (closed bars). ``` **Temporal causality (logical requirement):** the reference must be *confirmable* at the decision bar t. That is, a pivot at bar p is valid only if p+5 <= t (confirmation finished before/at the decision). A sweep at bar b must satisfy b > p (penetration AFTER the reference bar). --- ## 4. SWEEP DEFINITION (answer 7.3) Formally, for a single reference level `L` at pivot bar `p`: ```text Detection window : b in (p, min(t, p + GRAB_WINDOW)] ; GRAB_WINDOW = 8 Buy-side swept : isHigh(L) AND high[b] > L AND close[b] < L (wick breaks ABOVE the level + close returns BELOW the level, ON THE SAME BAR) Sell-side swept : !isHigh(L) AND low[b] < L AND close[b] > L (wick breaks BELOW the level + close returns ABOVE the level, ON THE SAME BAR) Minimum excess : > 0 — STRICT inequality condition (> / <). In tick-quantized prices, penetration >= 1 tick counts. NO ATR threshold, NO separate tick tolerance, NO normalization. Onset : the FIRST bar b satisfying the condition in the window = event onset. Per reference ONLY ONE onset (first-match; later bars satisfying the condition in the same window are NOT new events). ``` The penetration meant is the **wick** (high/low), not the close. However, the close must participate in the same condition (close-back) — this is the project's "grab" definition: *one bar that simultaneously breaks and rejects*. **Consequence note (effective 3-bar window):** because the reference is a 5/5 fractal, bars p+1 .. p+5 are the pivot confirmation bars; a level break in those bars CANCELS the pivot (the pivot would never enter the reference list). Therefore, for a truly valid pivot, the mathematically possible sweep bars are only **b ∈ [p+6, min(t, p+8)]** — the nominal 8-bar window = **effective 3 bars**. Derived consequence: at the decision bar t, the newest pivot that can produce a sweep is p = t-6 (the freshest possible onset = bar t, age 0). This is a mathematical consequence of the reference-formation rule, not an extra parameter. --- ## 5. DIRECTION (answer 7.4) Direction semantics stated explicitly (not dependent on variable names): ```text Buy-side liquidity taken (internal HIGH swept: high[b] > L, close[b] < L) -> dir = -1 (BEARISH interpretation) Sell-side liquidity taken (internal LOW swept: low[b] < L, close[b] > L) -> dir = +1 (BULLISH interpretation) dir = 0 (NO_SWEEP) when there is no active event. ``` Logic: taking liquidity on one side indicates the opposite movement — an upward penetration that fails to hold (close returns below) signals selling pressure; the reverse for the lower side. --- ## 6. REJECTION / CLOSE-BACK (answer 7.5) ```text Close-back status for the sweep EVENT (f7): REQUIRED — intrinsic part of the definition. A Sweep is NOT considered to have occurred without a close-back on the same bar. Close-back status for the f10/f11 primitives (EQ swept): NOT PART OF THE DEFINITION. f10/f11 state "EQ level broken" (wick break) WITHOUT close-back. This is a documented project decision (DESAIN_MTF_v45.md) chosen based on backtest/AUC results — NOT on SMC semantics. P3-S.2 records: two primitives in one model use different "sweep" definitions (f7: event+rejection; f10/f11: state without rejection). For the f7 audit, close-back = REQUIRED. For the project-semantic audit, this divergence is recorded as an ambiguity (see P3_S2_CONFORMANCE §G). ``` --- ## 7. TEMPORAL SEMANTICS (answer 7.6) ```text Decision timestamp : the M15 bar closes; t = open time of the decision bar; tc = t + 900 s (FEATURE_CONTRACT §0). Closed-bar rule : ALL inputs are closed bars (Engine 1 closed-bar lock; the forming bar is never used). Lookback : 700-bar cache; 600-bar analysis region; internal pivots [t-604, t-5] (full cache); 8-bar grab window. Future visibility : NONE. All bars used are <= t. Bars > t must not affect the decision at t (closed-bar stability). Onset visibility : an onset at bar b is recognized at a decision t >= b; f7[t] reflects the NEWEST onset with b <= t. ``` --- ## 8. EVENT vs STATE (answer 7.7) ```text Liquidity Sweep = EVENT + VALIDITY WINDOW - one onset per reference (first-match); - BOUNDED validity: the event is active only during the validity window after the onset; - expiration: after the window, the event is no longer active (NO_SWEEP). Validity length: SEQ_WINDOW = 40 bars. - NOT a universal SMC constant. - Derived from existing implementation/design semantics: the v4.4/v4.5 input `InpSeqWindow = 40` — "Max bars: sweep -> CHoCH -> entry must chain within" (SniperGold_SMC_ProPlus_v4_4.mq5:98) and the signal gates `sweepBull/Bear` + `chochBull/Bear` (v4.4:1049-1052). - Adopted as the f7 event validity window by P3-S.0 (not arbitrary). Event chain: a new onset (from another/newer reference) REPLACES (refreshes) the old event — it does not extend a single onset. ``` --- ## 9. EVENT LIFECYCLE (answer 7.8) States used by the project (explicit subset): ```text NO_SWEEP : no active sweep event (f7 = 0). SWEEP_ONSET : the bar b where the reference is first swept; direction set. ACTIVE : bars r with b <= r <= b + SEQ_WINDOW (f7 = dir). EXPIRED : r > b + SEQ_WINDOW (event past its validity; f7 = 0). SUPERSEDED : a new onset (b' > b) replaces the old event (existing condition: "update if b > g_swpBar" — project semantics). INVALIDATED : NOT modeled in f7 (no cancellation mechanism other than supersession) — documented, not required. CONSUMED : NOT modeled in f7. Consumers f9/f18 read the event without consuming it. Note: f9/f18 do NOT apply the validity window (see BUG-P3S2-001 in the conformance report). ``` Event occurrence (f7 series) for one onset at bar b: ```text r < b : 0 (NO_SWEEP) r = b : dir (SWEEP_ONSET, age 0) b < r <= b+40 : dir (ACTIVE) r > b+40 : 0 (EXPIRED) ``` --- ## 10. TIMEFRAME (answer 7.9) ```text f7 (sweep_dir) : M15 ONLY. Computed on the M15 decision bar. HTF (D1/H4/H1) : role = DIRECTION bias (f0-f2), NOT the f7 liquidity reference. AF_DetectSweep (E2) : computed per agent slot (H4/M30/M15/M3) — a separate primitive, not part of the ML features. v4.5 (MTF structure) : per-TF structure (HH/HL/OB/FVG/EQ) computed for context, BUT the ML features (including f7) stay M15. Does the project require "Liquidity Sweep = M15 only"? - For feature f7: YES (explicit feature contract). - For the project-level sweep concept (Engine 2/v4.5): NO — sweep is evaluated per TF. - Status: SPECIFICATION AMBIGUOUS for the "canonical project sweep" (no decision yet on whether ML may use HTF liquidity references). - P3-S.2 does NOT change the architecture; the ambiguity is recorded. ``` --- ## 11. ILLUSTRATIVE EXAMPLE (normalized prices) Example M15 bars (XAUUSD prices, 1:1 scale, arbitrary): ```text Bar p=10 : internal HIGH pivot L=2000.0 Bar b=12 : high=2001.5, low=1999.0, close=1999.5 -> high[12] > 2000.0 (breaks) AND close[12] < 2000.0 (close-back) -> BUY-SIDE SWEPT @12, dir=-1 (bearish) Bar b=12 : high=2000.0 (== level), close=1999.5 -> NOT swept (strict > fails; touch without break) Bar b=12 : high=2001.0, close=2000.5 -> NOT swept (breaks BUT close does not return below the level) ``` --- ## 12. SPEC CONSISTENCY AUDIT (Phase F) Performed on this document (details in conformance report §F): ```text [1] same-bar close-back (f7) vs close-back N/A (f10/f11) : deliberate divergence across primitives; DOCUMENTED (not an internal f7 contradiction). Project-level ambiguity. [2] "absolute valid pivots [t-649, t-50]" (contract §0) : the contract text refers to SWING pivots (len=50). For INTERNAL pivots (len=5) the actual range is [t-604, t-5]. This document separates the two — the contract text is ambiguous for f7 (documented, BUG-P3S2-004). [3] Multi-reference precedence on the same bar : NOT defined in any design document. This document establishes: "the LATEST onset (newest swept reference) wins; if still tied on the same bar, precedence is NOT DEFINED (SPECIFICATION AMBIGUOUS)". The implementation uses a different rule (the oldest pivot wins on a bar tie) — see BUG-P3S2-002. [4] The terms "grab" vs "sweep" : the project uses both interchangeably (DetectLiquidityGrabs = liquidity grab; AF_DetectSweep = sweep). This document establishes that both refer to the same concept (a sweep event with close-back). No circularity. [5] SEQ_WINDOW=40 : origin documented (§8) — not circular. ``` --- ## 13. AUDITED REQUIREMENTS (summary for conformance) | ID | Requirement | Specification | |----|-------------|---------------| | R-A | Reference | Internal swing pivot len=5, single level, closed-bar, window [t-604,t-5] | | R-B | Reference formation | Fractal 5/5, equal allowed, confirmation <= t | | R-C | Sweep trigger | high[b]>L && close[b]L (sell-side), same bar, b in (p, p+8] | | R-D | Excess | >= 1 tick (strict >), no ATR/tick tolerance | | R-E | Direction | buy-side->-1; sell-side->+1 | | R-F | Close-back | REQUIRED (intrinsic) | | R-G | Closed-bar | all inputs <= t; no future | | R-H | Event lifecycle | single onset per reference; valid b..b+40; expired -> 0; supersession | | R-I | Consumers | f7 applies validity; f9/f18 must be consistent (audit) | | R-J | Timeframe | M15 for f7 | | R-K | Per-bar | one f7 value per bar; explicit precedence | | R-L | Lookback | 600 analysis bars, 700 cache |