SniperGold_ML/docs/SESSION_HANDOVER_2026-08-22_P3_S2_LIQUIDITY_SPEC.md

# SESSION HANDOVER — SNIPERGOLD_ML P3-S.2: LIQUIDITY SWEEP SPEC + CONFORMANCE

```text
Date       : 2026-08-22 (session close)
Status     : P3-S.2 COMPLETE — spec + conformance audit done; commit+push verified
Forge      : https://forge.mql5.io/chiki2bum2/SniperGold_ML
Checkpoint : c7a2b3f5e6acbf8deb748315dcbcc200046d0b84 (P3-S.2, pushed)
```

---

## 1. SESSION OBJECTIVE

```text
Formal Specification + Code-Conformance Audit for Liquidity Sweep.

Question answered:
  Does DetectLiquidityGrabs() really implement the formal Liquidity Sweep
  definition according to the PROJECT SEMANTIC SPECIFICATION?

Questions NOT answered:
  - Does Liquidity Sweep have a trading edge?
  - Is the SMC strategy profitable?
  - Is the spec universally correct for every SMC trader?
```

Principle: SPEC FIRST, CODE AUDIT SECOND. Human verification = CANCELLED.
No production code changes (Phase D).

---

## 2. SOURCE MATERIAL (14 sources, reconciled)

```text
 1 FEATURE_CONTRACT v1.0 (f7)          docs/FEATURE_CONTRACT.md
 2 DESIGN.md (Algo Forge)              docs/DESIGN.md
 3 DESAIN_MTF_v45.md                   Shared Projects\SniperGold_ML
 4 v4.4/v4.5 DetectLiquidityGrabs      Indicators\Downloads\SniperGold_SMC_ProPlus_v4_4/4_5.mq5
 5 EA DetectLiquidityGrabs (current)   Experts\AlgoForge_Backtest_Baseline.mq5:365-394
 6 build_features_p2.py                ml/parity/build_features_p2.py
 7 smc_semantic_common.py              ml/p3/smc_semantic/
 8 machine_annotator.py                ml/p3/smc_semantic/
 9 AF_DetectSweep (Engine 2)           Include\AlgoForge\AF_Engine2_Agents.mqh:261
10 P3-S.0 forensic                     docs/P3_S_F7_EVENT_LIFECYCLE_FORENSIC.md
11 P3-S.1 doc                          docs/P3_S1_HUMAN_MACHINE_F7_VALIDATION.md
12 Golden dataset doc                  docs/P3_SMC_SEMANTIC_GOLDEN_DATASET.md
13 audit_liquidity_sweep.json          ml/p3/smc_semantic/output/
14 P2.2 EQH/EQL forensic               docs/P2_2_EQH_EQL_FORENSIC.md

Three semantic layers separated:
  INTENDED : sweep = liquidity taken + price returns (intrinsic rejection);
             direction opposite the taken side; event -> CHoCH -> entry chain
             (InpSeqWindow 40).
  LEGACY   : identical wick+close-back trigger; PERSISTENT state (never reset);
             40 = signal-chain gate (v4.4:1049-1052).
  CURRENT  : trigger identical; f7 emission uses the 40-bar lifecycle (P3-S.0);
             internal g_swpDir state still persistent (f9/f18 without expiry);
             f10/f11 = "break" without rejection (AUC decision, DESAIN_MTF_v45).
```

---

## 3. SPECIFICATION (docs/SMC_LIQUIDITY_SWEEP_SPEC_v1.md)

```text
REFERENCE   : f7 = internal swing pivot (fractal len=5) SINGLE level.
              EQH/EQL & swing len=50 VALID for f10/f11. HTF/external NOT
              VALID for f7 (bias only f0-f2). Others out of scope.
FORMATION   : fractal 5/5, equal allowed, confirmation <= t (closed-bar);
              window p in [max(95, t-604), t-5]; gate MIN_BARS=160.
TRIGGER     : wick break + close-back SAME BAR; b in (p, p+8]; first-match =
              one onset per reference.
DIRECTION   : buy-side swept -> -1 (bearish); sell-side swept -> +1 (bullish).
REJECTION   : REQUIRED (intrinsic) for the f7 sweep event; f10/f11 = NOT PART.
CLOSED-BAR  : all inputs <= t; no future visibility.
WINDOW      : nominal GRAB_WINDOW=8; EFFECTIVE 3 bars (b-p in {6,7,8}) — coupling
              with fractal confirmation (verified on real data, 2.837 onsets, 100%).
LIFECYCLE   : NO_SWEEP / SWEEP_ONSET / ACTIVE (b..b+40) / EXPIRED / SUPERSEDED;
              INVALIDATED & CONSUMED not modeled.
TIMEFRAME   : f7 = M15 ONLY; canonical project sweep = SPECIFICATION AMBIGUOUS
              (Engine 2/v4.5 per-TF, ML features still M15).
SEQ_WINDOW=40 : derived from v4.4 InpSeqWindow (sweep->CHoCH->entry chain),
                NOT a universal SMC constant.
```

---

## 4. CONFORMANCE (docs/P3_S2_LIQUIDITY_SWEEP_CONFORMANCE.md)

```text
Detection chain (E-1..E-8, E-12, E-14)  : CONFORMING
  reference, formation, trigger, excess>=1 tick, direction, close-back,
  closed-bar, timeframe, nominal/effective window.
In-function lifecycle (E-9)            : PARTIALLY CONFORMING
  the function is a state detector; the event exists only at the emission caller.
Consumer lifecycle f9/f18 (E-10)        : NON-CONFORMING (BUG-P3S2-001)
  g_swpDir has no age bound -> stale state keeps contributing weight.
Same-bar precedence (E-11)              : PARTIALLY CONFORMING
  undocumented; unreachable with consistent data (proven).
Runtime-training lookback (E-13)        : PARTIALLY CONFORMING
  theoretical divergence; empirical 0/1500.
```

---

## 5. SYNTHETIC TESTS

```text
Runner  : ml/p3/smc_semantic/spec_tests_liquidity_sweep.py
Cases   : ml/p3/smc_semantic/spec_test_cases_liquidity_sweep.json (17 cases)
Report  : ml/p3/smc_semantic/output/spec_tests_liquidity_sweep_report.json

Result  : 17/17 PASS
  LS-T01..T15 (required) + LS-T16 (tie, unreachable) + LS-T17 (window edge)
  spec_oracle (truth, from SPEC) == expected in all cases.
  code_port (EA port, observation) MATCHES spec in all cases (including
  T09 expiry, T13 closed-bar, T16/T17).
Expected derived from SPEC, NOT from production code.
NO AUC/PF/backtest/human annotation/ML on the test path.
```

---

## 6. VERDICT

```text
PARTIALLY CONFORMING

  Detection semantics            = CONFORMING
  Event-consumer lifecycle       = NON-CONFORMING (f9/f18)
  Overall implementation         = PARTIALLY CONFORMING

Verdict = conformance to the project specification, NOT profitability/edge.
DO NOT replace with PASS just because 17/17 tests pass.
```

---

## 7. CONFIRMED BUGS (document-only; NOT fixed in P3-S.2)

```text
BUG-P3S2-001 [MEDIUM] CONFIRMED, NOT FIXED
  f9/f18 consume g_swpDir without SEQ_WINDOW -> stale sweep state keeps
  contributing confluence weight (f18 +15, f9-confirm) for hundreds of bars.
  Fix: apply validity at consumption OR refactor the event source (P3-S.3+).

BUG-P3S2-002 [LOW] DOCUMENTED — same-bar tie precedence
  legacy: the oldest pivot wins (strict guard b>g_swpBar);
  unreachable under consistent data (fractal+confirmation).

BUG-P3S2-003 [LOW] DOCUMENTED — runtime vs training window
  theoretical divergence (grab from a pivot < r-699); empirical 0/1500.

BUG-P3S2-004 [LOW] DOCUMENTED — FEATURE_CONTRACT §0 wording ambiguity
  "[t-649,t-50]" = swing window; internal = [max(95,t-604), t-5].

BUG-P3S2-005 [INFO] DOCUMENTED — unused parameter time[]
  in DetectLiquidityGrabs.
```

---

## 8. SEMANTIC AMBIGUITIES

```text
1. f10/f11 rejection semantics : f7 REQUIRED vs f10/f11 NONE (chosen via AUC
   — DESAIN_MTF_v45). Two "sweep" definitions in one model.
2. Timeframe canonicality      : f7 M15 strict; project canonical (HTF liquidity
   as sweep reference) = AMBIGUOUS.
3. Internal swing as liquidity : f7 uses len=5 — the weakest liquidity form
   per the SMC concept; valid per project, not adjudicated.
4. GRAB_WINDOW effective       : nominal 8 vs effective 3 bars (b-p in {6,7,8});
   design intent not yet adjudicated.
5. Tie precedence              : SPECIFICATION AMBIGUOUS; unreachable.
```

---

## 9. NO PRODUCTION CHANGE

```text
No production code was modified.
  DetectLiquidityGrabs / f7 / f9 / f18 / f10/f11 / AF_DetectSweep /
  OB / FVG / CHoCH / ML : NOT touched.

Only P3-S.2 research artifacts added (spec, conformance, tests).
Historical evidence preserved: machine_annotations_f7_v2.csv hash
6d7c0b41... UNCHANGED.
```

---

## 10. HUMAN VERIFICATION STATUS

```text
HUMAN VERIFICATION = CANCELLED
  Human annotation not required for P3-S.2.
  Human A/B comparison NOT part of the validation path.
  No new human annotation requests.
  The human_package/ remains as a historical artifact.
```

---

## 11. NEXT GATE

```text
P3-S.3 : CHoCH / MSS
  Same protocol:
    SPEC FIRST -> CODE AUDIT -> SYNTHETIC TESTS -> VERDICT
  After CHoCH/MSS: FVG, OB, Displacement, MTF Alignment, Candidate Setup.
  DO NOT start P3-S.3 in this session.
```

---

## 12. CHECKPOINT & PROVENANCE (P3-S.2)

```text
Forge HEAD (before the P3-S.2 commit) : 0c8847b
P3-S.0 commit                      : b519a34
P3-S.1 commit                      : 8c1ef6c
P2 source commit                   : 8d330343af688e2de2b2a1d12ce19a582714709a
P2.6 model hash                    : 06df8452a112290ecb9bae1a3dbff6df492e084f8b872885d808bb0303ec6a70
machine v2 hash                    : 6d7c0b41aeb6d8ab64dcda9d0723f8e82abce771ab86fc9834ddeb874dd58583
case set hash                      : da3a0d0154b7d4b2b853b088e1948fd780d7677fbb00929eef24fc4e0132733a
FEATURE_CONTRACT                   : C44CC6F2... (P2-era, pre-commit) / 7b908b12... (committed) — recorded
P3_S2_CHECKPOINT_SHA               : c7a2b3f5e6acbf8deb748315dcbcc200046d0b84
symbol/tf                          : XAUUSD / M15 (2017-01-01 .. 2026-08-20)
```

---

## 13. IMMUTABLE CHECKPOINT RULE

```text
After push:
  the P3-S.2 specification
  + conformance report
  + 17/17 synthetic evidence
are treated as IMMUTABLE RESEARCH EVIDENCE.

Do not rewrite the reports because future implementations differ.
Future changes = a NEW version/checkpoint.
```

---

## 14. P3-S.2 ARTIFACTS

```text
docs/SMC_LIQUIDITY_SWEEP_SPEC_v1.md
docs/P3_S2_LIQUIDITY_SWEEP_CONFORMANCE.md
ml/p3/smc_semantic/spec_tests_liquidity_sweep.py
ml/p3/smc_semantic/spec_test_cases_liquidity_sweep.json
ml/p3/smc_semantic/output/spec_tests_liquidity_sweep_report.json
docs/SESSION_HANDOVER_2026-08-22_P3_S2_LIQUIDITY_SPEC.md  (this document)
```