SniperGold_ML/docs/P3_S13_CANDIDATE_SETUP_REPAIR.md

# P3-S.13 CANDIDATE SETUP LAYER — SNIPERGOLD_ML (F3)

```text
Date       : 2026-08-22
Session    : P3-S.13 — F3 CANDIDATE SETUP LAYER (third implementation phase
             of the frozen canonical architecture, P3-S.10).
Status     : IMPLEMENTED — test-first, contract enforced, consumer audit done,
             regression green, compilation 0/0, Forge pushed.
Baseline   : P3_S12_CLOSE_SHA e8efab9e950d5f851d354061a7e862a95e20f018
Contract   : docs/SNIPERGOLD_CANONICAL_SETUP_CONTRACT_v1.md (frozen)
Adjudication: docs/P3_S10_OWNER_ADJUDICATION.md (OD-1..OD-5)
F1 report  : docs/P3_S11_EVENT_CONTRACT_REPAIR.md
F2 report  : docs/P3_S12_ZONE_CONTRACT_REPAIR.md
Test report: ml/p3/smc_semantic/output/p3_s13_candidate_setup_report.json
Human verification : CANCELLED. No AUC/PF/profit/backtest/optimization used.
```

---

## A. Frozen Architecture (implemented)

```text
H4 context gate (direction-compatible)
        -> M30 context gate (direction-compatible)
        -> fresh Liquidity EVENT (M15, W_sweep = 40)
        -> CHoCH/MSS EVENT after the sweep (M15, W_choch = 40, same direction)
        -> unmitigated OB OR FVG ZONE (M15, direction-compatible)
        -> M15 entry condition
        -> CANDIDATE_SETUP (direction = chain direction)
        -> [optional M3 confirmation -> M3_CONFIRMED]
```

Primitive roles (frozen §C): H4 = CONTEXT STATE (gate), M30 = CONTEXT STATE
(gate), Liquidity Sweep = EVENT (required, W_sweep=40), CHoCH/MSS =
STRUCTURAL EVENT (required, W_choch=40, after sweep, inside the sweep chain),
OB = ZONE (alternative), FVG = ZONE (alternative), Displacement = OPTIONAL
ATTRIBUTE (per-bar, no persistent state), M15 = ENTRY CONDITION / CHAIN
CARRIER (required), M3 = OPTIONAL MICRO CONFIRMATION (no veto).

Semantic separation (frozen §A/§J): STATE != EVENT != ZONE != CONDITION !=
CANDIDATE_SETUP != SIGNAL != TRADE. A directional signal may exist without a
setup; a Candidate Setup requires the complete canonical chain.

---

## B. Implementation Scope

```text
IN SCOPE  : Candidate Setup entity, identity, lifecycle state machine,
            H4/M30 gates, event-chain consumption (F1), zone consumption (F2),
            M15 entry condition validation, optional M3 confirmation,
            one-setup-one-identity, one-entry rule, score separation,
            deterministic dedup, regression + compilation.
OUT OF SCOPE (NOT modified): F4 MTF/training alignment, F5 display
            redesign, ML/training pipeline, FEATURE_CONTRACT, legacy v4.x
            restoration, primitive detection formulas (sweep/CHoCH/FVG/OB/
            displacement unchanged), the flat aggregator's arithmetic.
```

---

## C. Candidate Setup Object

```text
AFCandidateSetup (AF_Engine2_Setup.mqh, frozen §E):

  setup_id               : monotonic integer, assigned at CANDIDATE_SETUP
  direction              : +1 bullish / -1 bearish (chain direction)
  state                  : lifecycle enum (frozen §F)
  sweep_onset, sweep_dir : originating Liquidity EVENT reference
  choch_onset, choch_dir : structure EVENT reference
  zone_type              : OB | FVG
  zone_formation         : zone formation bar (causal identity)
  zone_dir               : zone direction
  zone_mit_at_creation   : F2 mitigation state when the chain consumed it
  creation_bar           : M15 bar when the chain completed
  m3_bar                 : M3 confirmation bar (-1 = none)
  reason                 : provenance / lifecycle reason
  entry_bound            : one-entry bookkeeping (frozen §H)

NO execution fields (lot/SL/TP/ticket) — those are outside F3 (frozen §A,
CS-31). The scoring layer may attach score/confidence/ranking AFTER setup
existence (frozen §I) but never creates one.
```

---

## D. State Machine

```text
NONE -> CONTEXT_VALID -> LIQUIDITY_TRIGGERED -> STRUCTURE_CONFIRMED ->
ZONE_READY -> ENTRY_ARMED -> CANDIDATE_SETUP -> [M3_CONFIRMED]
        -> EXPIRED | INVALIDATED | CONSUMED

Rules (frozen §F):
  - strict stage order; no skipping;
  - a lapsed stage BEFORE CANDIDATE_SETUP discards the forming setup;
  - CANDIDATE_SETUP / M3_CONFIRMED are the ACTIVE formation states;
  - EXPIRED / INVALIDATED / CONSUMED are terminal and NON-REVERSIBLE
    (no reactivation);
  - at most one entry signal per setup (CONSUMED);
  - M3_CONFIRMED is optional; a contrary/absent M3 does NOT invalidate.
```

---

## E. H4/M30 Gate

```text
OD-1: H4 and M30 are HARD direction-compatible gates for the setup layer.
  - H4_state(asof) and M30_state(asof) must each be non-zero and equal to
    the chain direction.
  - H4 <-> M30 conflict (opposite signs) -> BLOCKED (no chain).
  - A neutral (0) state fails the gate -> no chain.
  - M15 chain conflict with H4/M30 -> BLOCKED (OD-4).
The flat vote remains a scoring/signal layer (signal != setup, §J); the
gates apply to the SETUP LAYER ONLY (OD-1 override recorded).
```

---

## F. Event Chain

```text
Consumed via the F1 EVENT contract (P3-S.11):
  sweep : fresh event only — age <= W_sweep (40 M15 bars);
          onset <= decision bar <= onset + W_sweep.
  CHoCH : fresh event — age <= W_choch (40);
          AFTER the sweep (choch onset >= sweep onset);
          inside the sweep validity chain (choch onset - sweep onset <= 40);
          same direction as the sweep.
No raw historical detector state is read; the F3 layer consumes F1 events
(AF_DetectSweepEvent / AF_DetectChochEvent materialize the onset that the
stateless detectors already compute; geometry unchanged).
```

---

## G. Zone Consumption

```text
Consumed via the F2 ZONE contract (P3-S.12):
  Candidate Setup may use ACTIVE + UNMITIGATED OB (AF_SETUP_ZONE_OB) OR
  ACTIVE + UNMITIGATED FVG (AF_SETUP_ZONE_FVG) — direction-compatible.
  Fully mitigated / invalidated zones are NOT consumable (AFZoneState
  mit_state + invalidated; F2 semantics reused).
  Zone mitigation mid-chain invalidates the setup (frozen §F).
F3 does NOT reimplement FVG/OB mitigation — it consumes AFZoneState.
```

---

## H. M15 Entry Condition

```text
The canonical M15 entry semantics are the project's own E-rule (Definition A,
SMC_CANDIDATE_SETUP_SPEC_v1 CS-1), retained as the M15 entry-condition
predicate inside the chain (P3-S.9 D.1):
  m15_cond(d) = zone membership AND confirmation conjunction (sweep OR
  choch direction-compatible) AND premium/discount filter (not in premium
  for buy / not in discount for sell); displacement may boost.
In the canonical chain the confirmation legs are already validated as stages
(§F); the M15 entry condition is the final direction-compatible CONDITION.
It is consumed as a semantic input (m15) by the F3 layer — the layer
validates it, it does not recompute the E-rule arithmetic. The M15 layer
acts as ENTRY CONDITION / CHAIN CARRIER, NOT as a second scoring system.
```

---

## I. M3 Confirmation

```text
Optional (frozen §F/§N, OD-4):
  - M3 direction-compatible within W_m3 of creation -> M3_CONFIRMED.
  - M3 contrary or absent -> M3_CONFIRMED = FALSE.
  - The Candidate Setup REMAINS VALID (M3 is not a gate).
  - A contrary M3 reduces only the micro-score (never the setup existence).
W_m3 = OPEN NUMERIC PARAMETER; placeholder test boundary 2 M15 decision
bars (~10 M3 bars at the 5:1 M3:M15 ratio), documented, NOT optimized.
```

---

## J. Identity / Deduplication

```text
Frozen §E/§G:
  uniqueness = (direction, sweep onset, choch onset, zone formation ts,
                creation ts). CAUSAL identity — every component is a dated
  chain element; no random id; no per-bar regeneration.
  ONE CAUSAL SETUP = ONE SETUP IDENTITY. While the same chain remains
  active, the same setup_id persists across bars (F3-T14/T23/T24).
  A new setup exists only when a NEW chain completes (new sweep onset /
  new CHoCH / new zone reference), producing a distinct identity.
  Dedup BY CONSTRUCTION: the engine's identity registry rejects a second
  setup with the same chain key (F3-T23/T24).
```

---

## K. Score Separation

```text
Frozen §I/§J: SCORE != SETUP EXISTENCE.
  - The flat aggregator (weighted vote) remains a SCORING/RANKING layer.
  - A score can never create a Candidate Setup (F3-T13).
  - A Candidate Setup can exist with ANY score, including a low one
    (F3-T25).
  - The aggregated vote may still produce a DIRECTIONAL SIGNAL without a
    setup (F3-T12) — that is a bias, not an entry instruction.
  - Entry signals (actionable) may only be emitted when bound to a valid
    CANDIDATE_SETUP (frozen §J.2).
Consumer audit: AFAggOut carries NO setup field; AF_Engine2_Aggregator /
AF_Engine2_Display / AF_Engine3_Render have zero references to the F3 layer.
```

---

## L. Tests

```text
New suite: ml/p3/smc_semantic/spec_tests_candidate_setup_runtime.py
  F3-T01..T25 (all 25 required by the brief §15):

  F3-T01  Valid complete setup (OB)          -> ONE CANDIDATE_SETUP
  F3-T02  FVG alternative                    -> ONE CANDIDATE_SETUP
  F3-T03  No zone                            -> NO CANDIDATE_SETUP
  F3-T04  Stale sweep (age 41 > 40)          -> NO CANDIDATE_SETUP
  F3-T05  CHoCH before sweep                 -> NO CANDIDATE_SETUP
  F3-T06  CHoCH outside sweep window         -> NO CANDIDATE_SETUP
  F3-T07  Wrong direction (chain vs context) -> NO CANDIDATE_SETUP
  F3-T08  H4 conflict                        -> BLOCKED
  F3-T09  M30 conflict                       -> BLOCKED
  F3-T10  M15 conflict                       -> BLOCKED
  F3-T11  M3 opposite                        -> setup valid, M3=FALSE
  F3-T12  H4-only signal                     -> signal exists, setup NONE
  F3-T13  High score without setup           -> score exists, setup NONE
  F3-T14  Identity stability                 -> same setup_id across bars
  F3-T15  One entry per setup                -> max one entry binding
  F3-T16  Setup expiration (W_setup=40)      -> EXPIRED
  F3-T17  Setup invalidation (zone mitigated)-> INVALIDATED
  F3-T18  Setup consumption                  -> CONSUMED, no 2nd entry
  F3-T19  Two independent setups             -> two distinct setup_ids
  F3-T20  Future mutation                    -> historical setup unchanged
  F3-T21  Zone mitigation before M15 entry   -> NO CANDIDATE_SETUP
  F3-T22  Context change after formation     -> INVALIDATED (canonical §F)
  F3-T23  Repeated raw state                 -> one event chain, one setup
  F3-T24  Duplicate formation prevention     -> no duplicate setup
  F3-T25  Candidate vs score                 -> setup EXISTS with low score

Discipline: canonical oracle vs expected ASSERT; repaired port (the MQL5
setup engine) vs oracle ASSERT; legacy port (PRE-F3, P3-S.8 facts) REPORT;
invariance (future mutation) ASSERT. Report:
ml/p3/smc_semantic/output/p3_s13_candidate_setup_report.json.
```

---

## M. Regression

```text
P3-S.2  Liquidity Sweep     17/17  PASS
P3-S.3  CHoCH/MSS           20/20  PASS
P3-S.4  FVG                 20/20  PASS
P3-S.5  Order Block         20/20  PASS
P3-S.6  Displacement        20/20  PASS
P3-S.7  MTF Alignment       22/22  PASS
P3-S.8  Candidate Setup     25/25  PASS
F1      Event Contract       8/8   PASS
F2      Zone Contract       20/20  PASS
F3      Candidate Setup     25/25  PASS
No suite weakened; no oracle changed. P3-S.4/S.5 still assert the SPEC
oracle (immutable) and REPORT the legacy code port as historical evidence;
the repaired Engine-2 behavior is asserted by the F2/F3 suites.
```

---

## N. Compilation

```text
MetaEditor build 6140, target AVX512 + FMA3:
  MQL5\Experts\AlgoForge_Engine2_UnitTest.mq5  -> 0 errors, 0 warnings
  MQL5\Indicators\AlgoForge\AF_Engine3_Display.mq5 -> 0 errors, 0 warnings
  MQL5\Experts\AlgoForge_Engine3_UnitTest.mq5  -> 0 errors, 0 warnings
Engine-2 unit test (Strategy Tester, XAUUSD M15, every tick):
  PASS=35891 FAIL=0 — includes T7a..T7e synthetic setup-layer checks.
Repo and terminal copies of the modified headers are byte-identical (fc /b).
```

---

## O. Explicitly Unchanged Areas

```text
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 untouched (no F5 redesign in F3).
ML                    : model, LSTM, regime, meta-label — untouched.
Legacy v4.3/v4.4/v4.5 : historical evidence only; NOT restored.
Primitive detection   : AF_DetectSweep / AF_DetectChoch / AF_FindFVG /
                        AF_FindOrderBlock / AF_DetectDisplacement geometry
                        UNCHANGED (F1/F2 repairs retained).
Flat aggregator       : AFAggregator arithmetic unchanged (scoring layer).
EA (AlgoForge_Backtest_Baseline.mq5) : untouched (its F1 event contract is
                        consumed conceptually; no EA edit in F3).
```

---

## P. Remaining F4/F5 work

```text
F4 (next gate, P3-S.14): H4/M30/M15/M3 canonical alignment,
    runtime/training MTF mismatch, D1/H4/H1/M15 legacy training path,
    FEATURE_CONTRACT implications. The F3 layer consumes semantic inputs;
    the MTF wiring (Engine-1 slots -> semantic inputs) and any runtime
    integration belong to F4. If F4 discovers the current MTF layer cannot
    provide the required data, that is documented as an F4 blocker — NOT
    modified inside F3.
F5: display the setup entity (id, stages, lifecycle) instead of the bare
    vote signal in the "TRADE SETUP" panel — deferred, NOT started.
Phase VI: setup dataset rebuild for training — after F3/F4 validation.
```

---

## Q. Forge Commit(s)

```text
1. test: define F3 candidate setup regression coverage
   - ml/p3/smc_semantic/spec_tests_candidate_setup_runtime.py
   - ml/p3/smc_semantic/output/p3_s13_candidate_setup_report.json
2. feat: implement canonical candidate setup layer
   - MQL5/Include/AlgoForge/AF_Engine2_Setup.mqh      (new — F3 layer)
   - MQL5/Include/AlgoForge/AF_Defines.mqh            (W_setup/W_m3)
   - MQL5/Include/AlgoForge/AF_Engine2_Agents.mqh     (F1 event helpers)
   - MQL5/Experts/AlgoForge_Engine2_UnitTest.mq5      (T7 setup checks)
3. docs: record P3-S.13 candidate setup implementation
   - docs/P3_S13_CANDIDATE_SETUP_REPAIR.md            (this report)
```

---

## R. Final Forge HEAD

```text
P3_S13_FINAL_SHA = (recorded after push; see session handover).
```

---

## S. Working Tree

```text
local HEAD == remote HEAD, working tree CLEAN (verified after push).
```

---

## T. P3-S.14 Readiness

```text
The canonical Candidate Setup entity now exists: one causal chain = one
setup_id, deterministic lifecycle, H4/M30 gates enforced, fresh sweep +
CHoCH-after-sweep + unmitigated OB|FVG + M15 entry required, M3 optional,
score separated from setup existence, future data cannot alter past setup.
Next gate: P3-S.14 = F4 MTF / Training Alignment. NOT started in this
session.
```

*End of P3-S.13 F3 candidate setup layer record. No F4/F5/ML change.*