2026-08-22 22:32:57 +07:00
# 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
2026-08-22 22:33:55 +07:00
P3_S12_FINAL_SHA = db03906e3e2e1b3d0965b29937302fbb9497068a (P3-S.12 repair-series head; Forge HEAD at session close = 98d7ef7bb3b188e72b7a8ed115b51e2167b20524)
2026-08-22 22:32:57 +07:00
```
---
## 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.*
