14 KiB
14 KiB
SMC LIQUIDITY SWEEP — PROJECT SEMANTIC SPECIFICATION v1
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:
- A reference liquidity level already exists before the event (temporal causality: the reference precedes the penetration);
- Price breaks through the level (excess/wick penetration);
- Price closes back across the level (rejection / close-back);
- 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)
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:
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):
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)
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)
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)
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):
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:
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)
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):
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):
[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 (buy-side) / low[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 |