392 lines
17 KiB
Markdown
392 lines
17 KiB
Markdown
# P3-S.12 ZONE CONTRACT REPAIR — SNIPERGOLD_ML (F2)
|
|
|
|
```text
|
|
Date : 2026-08-22
|
|
Session : P3-S.12 — F2 ZONE CONTRACT REPAIR (FVG + Order Block zone
|
|
lifecycle: formation, active state, mitigation, invalidation,
|
|
consumer semantics — implemented after the frozen canonical
|
|
architecture, P3-S.10, and the F1 event-contract repair, P3-S.11).
|
|
Status : IMPLEMENTED — test-first, contract enforced, consumers audited,
|
|
regression green, compilation 0/0. No F3/F4/F5/ML changes.
|
|
Baseline : P3_S11_FINAL_SHA d626a6d3e3732f78acb90881442e5e864664cdae
|
|
Contract : docs/SNIPERGOLD_CANONICAL_SETUP_CONTRACT_v1.md (frozen §K/§M/§O)
|
|
FVG spec : docs/SMC_FVG_SPEC_v1.md (S-1..S-13) [immutable]
|
|
OB spec : docs/SMC_ORDER_BLOCK_SPEC_v1.md (S-1..S-15) [immutable]
|
|
F1 report : docs/P3_S11_EVENT_CONTRACT_REPAIR.md
|
|
Test report: ml/p3/smc_semantic/output/p3_s12_zone_contract_report.json
|
|
Human verification : CANCELLED. No AUC/PF/profit/backtest/optimization used.
|
|
```
|
|
|
|
---
|
|
|
|
## A. P3-S.10 Architecture Lock (verified)
|
|
|
|
```text
|
|
Frozen canonical ZONE contract (§K):
|
|
ZONE { ts, dir, upper, lower, mit_state, invalidated }
|
|
- a ZONE is a persistent entity, NOT a repeated event (a zone that stays
|
|
untraded for N bars is ONE zone, not N events — S-8).
|
|
- consumers may read ONLY unmitigated, non-invalidated zones.
|
|
- FVG mitigation = wick full-fill (P3-S.4 S-9 legacy canonical).
|
|
- OB mitigation = close-through full fill (P3-S.5 S-9).
|
|
- no age expiry (W_zone_age = OPEN NUMERIC PARAMETER, default none; §M).
|
|
- chain stage 3 = unmitigated OB OR FVG ZONE, direction-compatible (§D).
|
|
No post-P3-S.11 commit exists (git log verified: HEAD == d626a6d, diff empty),
|
|
so the architecture lock is intact at session start.
|
|
```
|
|
|
|
---
|
|
|
|
## B. P3-S.11 Event Contract Baseline (verified)
|
|
|
|
```text
|
|
F1 repaired the EVENT contract (sweep/CHoCH: {ts,dir,valid_until,superseded,
|
|
source}; W=40; chain bound) in the ML-path EA. FVG and OB were explicitly
|
|
NOT touched by F1 ("F2 Zone Contract (FVG/OB mitigation)" = later phase).
|
|
The F2 baseline therefore carries forward:
|
|
BUG-P3S4-001 (Engine-2 FVG no mitigation filter)
|
|
BUG-P3S4-002 (Engine-2/display FVG 1-bar lag)
|
|
BUG-P3S5-001 (Engine-2 OB no mitigation/age filter)
|
|
A-2 (FVG mitigation trigger divergence: wick canonical vs display CLOSE)
|
|
All other P3-S.2..S.11 semantics unchanged.
|
|
```
|
|
|
|
---
|
|
|
|
## C. F2 Scope (this session)
|
|
|
|
```text
|
|
IN SCOPE : FVG, Order Block, zone formation, zone identity, zone active
|
|
state, mitigation, invalidation, zone expiration semantics
|
|
(none — open parameter), zone consumer contract, duplicate-zone
|
|
prevention (one zone per formation, by construction).
|
|
OUT OF SCOPE (NOT modified): Liquidity Sweep, CHoCH/MSS, Displacement,
|
|
Candidate Setup, H4/M30 gates, M15 carrier, M3, MTF model,
|
|
training pipeline, ML, FEATURE_CONTRACT. Dependencies found are
|
|
DOCUMENTED ONLY (see §O).
|
|
```
|
|
|
|
---
|
|
|
|
## D. FVG Before / After
|
|
|
|
```text
|
|
DETECTOR GEOMETRY (S-1/S-2/S-4/S-5): UNCHANGED — 3-candle wick gap;
|
|
bull Low(C3)>High(C1) zone [High(C1),Low(C3)]; bear High(C3)<Low(C1)
|
|
zone [High(C3),Low(C1)]; C2 extremes unused; no min-gap in definition;
|
|
no displacement required; closed-bar, non-repainting.
|
|
|
|
BEFORE (Engine-2 AF_FindFVG, P3-S.4 audit):
|
|
- no mitigation filter -> a FULLY-FILLED (wick full-fill) FVG was returned
|
|
to the C/E agents as a valid zone (BUG-P3S4-001);
|
|
- loop started at i=1 -> the newest closed bar was never C3 (1-bar lag,
|
|
BUG-P3S4-002): a zone whose C3 == newest closed bar was missed until one
|
|
bar later; C lookback 40 vs E lookback 20 (documented A-6, unchanged);
|
|
- display AF_CollectFVG mitigated by CLOSE (A-2 divergence).
|
|
|
|
AFTER (F2):
|
|
- AF_FindFVG returns the NEWEST ACTIVE zone: candidates are scanned
|
|
newest-first, each candidate's state is computed (AF_FVGZoneState) and
|
|
wick full-filled zones are skipped (S-9);
|
|
- loop starts at i=0 -> the newest closed bar IS eligible as C3 (S-6):
|
|
no future candle (all inputs closed via Engine-1 lock), no needless
|
|
1-bar delay (F2-T07/F2-T08);
|
|
- display AF_CollectFVG unified to wick full-fill mitigation (S-9) and
|
|
i=0 start (S-6).
|
|
|
|
Evidence (synthetic, from p3_s12_zone_contract_report.json; no profitability):
|
|
F2-T04 (FVG-T10 equivalent, full mitigation): before d1[100.4,100.2]
|
|
(mitigated zone still returned) -> after: no active zone.
|
|
F2-T05 (mitigated newest NOT consumed): before d1[100.95,100.9]
|
|
(mitigated b=9 consumed) -> after: older ACTIVE b=4 returned.
|
|
F2-T07/T08 (timing): before: none (1-bar lag) -> after: zone at C3 close.
|
|
F2-T15 (FVG-T13 equiv, multiple): before d1[100.55,100.5] (older b=3 due
|
|
to lag) -> after: newest b=6 returned.
|
|
F2-T17 (FVG-T12 equiv, overlapping): before d1[100.65,100.6] (b=4, lag)
|
|
-> after: newest b=5 returned.
|
|
```
|
|
|
|
---
|
|
|
|
## E. OB Before / After
|
|
|
|
```text
|
|
DETECTOR FORMATION (S-1..S-4, frozen §O): UNCHANGED — opposite-color candle B
|
|
immediately before strong-move candle M (|body(M)| >= 1.5 x avg body over 20);
|
|
zone = FULL RANGE [Low(B),High(B)]; direction = move direction; no structural
|
|
precondition (canonical; legacy BOS/CHoCH definition is A-2 historical, NOT
|
|
restored); 1.5x is the intentional proxy for Displacement 1.6x (OD-5).
|
|
|
|
BEFORE (Engine-2 AF_FindOrderBlock, P3-S.5 audit):
|
|
- no mitigation filter -> a close-through FULLY-FILLED OB was returned to
|
|
the C/E agents (BUG-P3S5-001);
|
|
- newest-only selection (older unmitigated zones invisible to agents,
|
|
A-5 documented, unchanged).
|
|
|
|
AFTER (F2):
|
|
- AF_FindOrderBlock returns the NEWEST ACTIVE zone: each candidate's state
|
|
is computed (AF_OBZoneState) and close-through full-filled zones are
|
|
skipped (S-9). The move candle is included in the mitigation scan
|
|
(display-consistent). No formation change; no age bound added.
|
|
|
|
Evidence (synthetic, from the F2 report; no profitability):
|
|
F2-T12 (OB-T11 equivalent, full mitigation): before d1[100.5,99.8]
|
|
(mitigated returned) -> after: no active zone.
|
|
F2-T13 (mitigated newest NOT consumed): before d1[100.6,99.7]
|
|
(mitigated b=20 consumed) -> after: older ACTIVE b=10 returned.
|
|
F2-T14 (OB-T12/T16 equivalents, terminal): before d1[100.5,99.8] ->
|
|
after: no active zone; the opposite move after mitigation does NOT
|
|
reactivate the zone (no breaker — S-12 unchanged).
|
|
```
|
|
|
|
---
|
|
|
|
## F. Zone Contract (implemented)
|
|
|
|
```text
|
|
ZONE (frozen §K, made explicit per the F2 brief §5/§11):
|
|
|
|
ZONE { ts(formation bar), dir, upper, lower, mit_state, invalidated }
|
|
|
|
mit_state : UNMITIGATED(0) | PARTIALLY_FILLED(1) | FULLY_MITIGATED(2)
|
|
- PARTIALLY_FILLED is ACTIVE (S-9: partial fill != mitigation); it is an
|
|
informational state that keeps the zone consumable.
|
|
- FULLY_MITIGATED is terminal (not consumable).
|
|
invalidated: terminal flag; zone-level = set when FULLY_MITIGATED (frozen
|
|
§M "invalidation = mitigation is the terminal usable-state"); the same
|
|
field is what the future setup layer (F3) will set on chain-level
|
|
invalidation.
|
|
consumer : available iff mit_state in {UNMITIGATED, PARTIALLY_FILLED}
|
|
and NOT invalidated. Consumers read the NEWEST ACTIVE zone.
|
|
persistence: one formation = one zone; the zone identity (formation bar)
|
|
persists across bars; never re-emitted per bar (S-8).
|
|
no age expiry (W_zone_age = OPEN NUMERIC PARAMETER, default none).
|
|
|
|
Implemented as AFZoneState {bar, dir, top, bot, mit_state, partial_filled,
|
|
invalidated} + IsActive() + AF_FVGZoneState() / AF_OBZoneState() in
|
|
AF_Engine2_Agents.mqh (Engine-2 stateless per-bar, P3-S.7 S-ST).
|
|
```
|
|
|
|
---
|
|
|
|
## G. Mitigation (deterministic, per frozen contract)
|
|
|
|
```text
|
|
FVG (S-9): wick full-fill.
|
|
bull: exists j > C3 with Low(j) <= bot (= High(C1))
|
|
bear: exists j > C3 with High(j) >= top (= Low(C1))
|
|
PARTIAL FILL (not mitigation): any j > C3 whose range overlaps the zone.
|
|
Display (AF_CollectFVG) unified from CLOSE to WICK (A-2 resolved).
|
|
|
|
OB (S-9): close-through full fill.
|
|
bull: exists j > B with Close(j) < bot (= Low(B))
|
|
bear: exists j > B with Close(j) > top (= High(B))
|
|
scan includes the move candle (display-consistent); strict inequality
|
|
(a close exactly ON a boundary is NOT mitigation — S-3/S-9).
|
|
PARTIAL FILL (not mitigation): any j strictly after the move candle whose
|
|
range overlaps the zone.
|
|
|
|
Tested: touch only / partial entry / wick through (FVG) / close inside /
|
|
close beyond (OB) — F2-T03/T04/T11/T12 + P3-S.4 FVG-T09/T10 + P3-S.5
|
|
OB-T10/T11 remain green.
|
|
```
|
|
|
|
---
|
|
|
|
## H. Invalidation
|
|
|
|
```text
|
|
Zone-level (F2): invalidation = full-fill mitigation (frozen §M). A zone
|
|
whose mit_state becomes FULLY_MITIGATED has invalidated=true; the transition
|
|
is TERMINAL and IRREVERSIBLE — price re-entering the zone area later does
|
|
NOT reactivate it (F2-T06/F2-T14). No breaker / flipped-OB state exists
|
|
(S-12, unchanged). Setup-level INVALIDATED (chain break) belongs to F3 and
|
|
will reuse the same field.
|
|
```
|
|
|
|
---
|
|
|
|
## I. Zone Identity / Deduplication
|
|
|
|
```text
|
|
Identity (causal, minimal for F2): formation bar (FVG: C3; OB: candle B)
|
|
+ type + direction + boundaries. The formation bar is the persistent entity
|
|
key: querying at bar t and at t+k yields the SAME zone (F2-T02/F2-T10).
|
|
Duplicate-zone prevention is BY CONSTRUCTION: the detectors are per-bar
|
|
stateless queries over the newest formation; a persistent zone is ONE zone,
|
|
never re-emitted (S-8). No per-bar "new zone / new zone" stream exists for
|
|
FVG/OB (verified F2-T02/T10 and P3-S.4 FVG-T14 / P3-S.5 OB-T09).
|
|
Overlap: separate formations stay separate zones; no merge, no replace
|
|
(F2-T15..T18, S-11). Display dedupe (AF_CollectOBs 0.5 ATR) is display-only,
|
|
unchanged (A-3 documented).
|
|
```
|
|
|
|
---
|
|
|
|
## J. Consumer Audit (no raw legacy state bypasses)
|
|
|
|
```text
|
|
FVG: detector AF_FindFVG -> zone state (AF_FVGZoneState) -> consumers:
|
|
C agent (AF_Engine2_Agents.mqh:514, lookback 40) -> membership trap.
|
|
E agent (:610, lookback 20) -> mZone + ZONE+CONFIRMATION rule.
|
|
Both now receive ONLY the newest ACTIVE zone.
|
|
display AF_CollectFVG (AF_Engine2_Display.mqh) -> AF_BuildDisplayData
|
|
(:387) -> AF_Engine3_Render (draws unmitigated zones only).
|
|
legacy DetectAndDrawFVG (v4.3/v4.4/v4.5) = HISTORICAL path, untouched.
|
|
OB: detector AF_FindOrderBlock -> zone state (AF_OBZoneState) -> consumers:
|
|
C agent (:512) / E agent (:608) -> newest ACTIVE OB only.
|
|
display AF_CollectOBs (:386 -> render) already close-through conforming.
|
|
legacy RecordOB / RecordOB_mtf = HISTORICAL path, untouched.
|
|
EA (AlgoForge_Backtest_Baseline.mq5), Python training, FEATURE_CONTRACT:
|
|
FVG/OB absent (N/A by absence, S-13/S-15) -> unaffected.
|
|
Aggregator consumes AFSignalOut (agent outputs), never raw zones.
|
|
CONCLUSION: ZONE-CONSUMER-DRIFT eliminated — no consumer reads a historical
|
|
(mitigated/invalidated) zone as active.
|
|
```
|
|
|
|
---
|
|
|
|
## K. Tests
|
|
|
|
```text
|
|
New suite: ml/p3/smc_semantic/spec_tests_zone_contract.py (F2-T01..F2-T20)
|
|
F2-T01 FVG formation F2-T11 OB partial mitigation
|
|
F2-T02 FVG one zone many bars F2-T12 OB full mitigation
|
|
F2-T03 FVG partial mitigation (still ACTIVE)
|
|
F2-T04 FVG full mitigation (wick) F2-T13 OB mitigated NOT consumed
|
|
F2-T05 FVG mitigated NOT consumed F2-T14 OB invalidation terminal
|
|
F2-T06 FVG invalidation terminal F2-T15 two independent FVG zones
|
|
F2-T07 FVG formation timing boundary F2-T16 two independent OB zones
|
|
F2-T08 FVG one-bar timing regression F2-T17 overlapping FVG zones
|
|
F2-T09 OB formation (move = newest bar) F2-T18 overlapping OB zones
|
|
F2-T10 OB one zone many bars F2-T19 future-bar mutation
|
|
F2-T20 bull/bear symmetry
|
|
Discipline (existing infra, no parallel framework):
|
|
- spec oracle vs expected : ASSERT (canonical zone contract = truth)
|
|
- repaired port vs spec : ASSERT (the MQL5 fix must satisfy the contract)
|
|
- legacy port vs repaired : REPORT (before/after differential evidence)
|
|
- invariance: transform, future-mutation, symmetry : ASSERT
|
|
Result: 20/20 PASS. Report: output/p3_s12_zone_contract_report.json.
|
|
```
|
|
|
|
---
|
|
|
|
## L. Regression (all green)
|
|
|
|
```text
|
|
P3-S.2 Liquidity Sweep 17/17 PASS
|
|
P3-S.3 CHoCH/MSS 20/20 PASS
|
|
P3-S.4 FVG 20/20 PASS (spec oracle unchanged; the P3-S.4
|
|
code_port documents the LEGACY
|
|
Engine-2 behavior as historical
|
|
evidence — BUG-P3S4-001/-002)
|
|
P3-S.5 Order Block 20/20 PASS (same: code_port = legacy
|
|
BUG-P3S5-001 evidence)
|
|
P3-S.6 Displacement 20/20 PASS
|
|
P3-S.7 MTF Alignment 22/22 PASS
|
|
P3-S.8 Candidate Setup 25/25 PASS
|
|
P3-S.12 F2 Zone Contract 20/20 PASS
|
|
The P3-S.4/S.5 suites assert the SPEC oracle (immutable truth) and REPORT
|
|
the legacy code port; the repaired behavior is asserted by the F2 suite.
|
|
No unrelated suite weakened; none failed (no STOP/INVESTIGATE triggered).
|
|
```
|
|
|
|
---
|
|
|
|
## M. Compilation
|
|
|
|
```text
|
|
MetaEditor build 6140, target AVX512 + FMA3:
|
|
MQL5\Indicators\AlgoForge\AF_Engine3_Display.mq5 -> 0 errors, 0 warnings
|
|
MQL5\Experts\AlgoForge_Engine2_UnitTest.mq5 -> 0 errors, 0 warnings
|
|
MQL5\Experts\AlgoForge_Engine3_UnitTest.mq5 -> 0 errors, 0 warnings
|
|
Repo and terminal copies of the modified headers are byte-identical (fc /b).
|
|
```
|
|
|
|
---
|
|
|
|
## N. Files Changed
|
|
|
|
```text
|
|
MQL5\Include\AlgoForge\AF_Engine2_Agents.mqh (fix)
|
|
+ AFZoneMitState enum, AFZoneState struct, AF_FVGZoneState,
|
|
AF_OBZoneState helpers (canonical zone representation/state).
|
|
+ AF_FindOrderBlock: close-through mitigation filter (BUG-P3S5-001).
|
|
+ AF_FindFVG: i=0 (no 1-bar lag, BUG-P3S4-002) + wick mitigation filter
|
|
(BUG-P3S4-001); newest ACTIVE zone consumer query.
|
|
MQL5\Include\AlgoForge\AF_Engine2_Display.mqh (fix)
|
|
+ AF_CollectFVG: mitigation CLOSE -> WICK full-fill (S-9, A-2) and
|
|
i=0 start (S-6, no display 1-bar lag).
|
|
ml\p3\smc_semantic\spec_tests_zone_contract.py (test) — F2-T01..T20.
|
|
ml\p3\smc_semantic\output\p3_s12_zone_contract_report.json (test artifact).
|
|
docs\P3_S12_ZONE_CONTRACT_REPAIR.md (docs) — this report.
|
|
```
|
|
|
|
---
|
|
|
|
## O. Explicitly Unchanged Areas
|
|
|
|
```text
|
|
F3 Candidate Setup : NOT started (this is the next gate).
|
|
F4 MTF / Training : H4/M30/M15/M3 model, as-of logic, conflict
|
|
policy, hierarchy, train_model.py,
|
|
build_features.py, FEATURE_CONTRACT — untouched.
|
|
F5 Display : render logic unchanged (draws the same zone
|
|
objects; only the collector's mitigation rule and
|
|
timing were aligned to the canonical contract).
|
|
ML : model, LSTM, regime, meta-label — untouched.
|
|
Legacy v4.3/v4.4/v4.5 : DetectAndDrawFVG / RecordOB / RecordOB_mtf /
|
|
FindEntryFVG/OB — HISTORICAL path, NOT repaired.
|
|
Liquidity Sweep, CHoCH/MSS, Displacement : untouched (F1 scope; P3-S.6).
|
|
EA (AlgoForge_Backtest_Baseline.mq5) : untouched (no FVG/OB).
|
|
Python training mirror (train_model.build_features): untouched (no FVG/OB);
|
|
the documented F1 leftovers (f7 frame, choch_conf
|
|
legacy) remain F4/Phase-VI items.
|
|
```
|
|
|
|
---
|
|
|
|
## P. Forge Commit(s)
|
|
|
|
```text
|
|
1. test: define F2 zone contract regression coverage (F2-T01..T20)
|
|
- ml/p3/smc_semantic/spec_tests_zone_contract.py
|
|
2. fix: enforce canonical FVG and OB zone lifecycle
|
|
- MQL5/Include/AlgoForge/AF_Engine2_Agents.mqh
|
|
- MQL5/Include/AlgoForge/AF_Engine2_Display.mqh
|
|
3. docs: record P3-S.12 zone contract repair
|
|
- docs/P3_S12_ZONE_CONTRACT_REPAIR.md
|
|
- ml/p3/smc_semantic/output/p3_s12_zone_contract_report.json
|
|
```
|
|
|
|
---
|
|
|
|
## Q. Final Forge HEAD
|
|
|
|
```text
|
|
P3_S12_FINAL_SHA = db03906e3e2e1b3d0965b29937302fbb9497068a (P3-S.12 repair-series head; Forge HEAD at session close = 98d7ef7bb3b188e72b7a8ed115b51e2167b20524)
|
|
```
|
|
|
|
---
|
|
|
|
## R. Working Tree
|
|
|
|
```text
|
|
local HEAD == remote HEAD, working tree CLEAN (verified after push).
|
|
```
|
|
|
|
---
|
|
|
|
## S. P3-S.13 Readiness
|
|
|
|
```text
|
|
The zone leg of the canonical chain is now representable and consumable
|
|
correctly: an unmitigated OB or FVG ZONE (with explicit mit_state and
|
|
invalidated flags, identity by formation bar, newest-ACTIVE consumer query)
|
|
is available to the future F3 Candidate Setup layer. No setup state machine
|
|
was built here. Next gate: P3-S.13 = F3 CANDIDATE SETUP LAYER
|
|
(H4 gate -> M30 gate -> Liquidity EVENT -> CHoCH EVENT -> OB|FVG ZONE ->
|
|
M15 entry -> identity/lifecycle -> optional M3). NOT started in this session.
|
|
```
|
|
|
|
*End of P3-S.12 F2 zone contract repair record. No F3/F4/F5/ML change.*
|