316 lines
14 KiB
Markdown
316 lines
14 KiB
Markdown
# 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 (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 |
|