# 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.*