# SMC CHOCH / MSS — PROJECT SEMANTIC SPECIFICATION v1 ```text Status : PROJECT SEMANTIC SPECIFICATION (not "universal SMC ground truth") Session : P3-S.3 — Formal Specification + Code-Conformance Audit (CHoCH / MSS) Date : 2026-08-22 Scope : The CHoCH (change of character) primitive as consumed by feature f8 (choch_dir), f9 (choch_confirms), f18 (confluence), the legacy signal chain (InpRequireCHoCH / InpSeqWindow), and Engine 2 (AF_DetectChoch). MSS (market structure shift) is discussed as project terminology (see §5) — there is NO separate MSS implementation in the codebase. Secondary reference : AF_DetectChoch (Engine 2), AF_BuildStructLines (display) — implementation comparisons, NOT the f8/f9 definition. Provenance : P2 8d330343 | contract C44CC6F2 (P2-era) / 7b908b12 (committed) model 06df8452 | Forge HEAD 595b4c9a (P3-S.2 checkpoint) ``` > This document ESTABLISHES what "CHoCH" (and the status of "MSS") means in the > SniperGold_ML / Algo Forge project, derived from: (a) the feature contract > (FEATURE_CONTRACT f8/f9), (b) design intent (DESIGN.md, DESAIN_MTF_v45.md), > (c) the legacy entry chain (Sweep→CHoCH→OB/FVG, InpSeqWindow), (d) logical > requirements (temporal causality, closed-bar, event vs state). > This document is NOT a claim of universal SMC truth; CHoCH definitions outside > this project (e.g. variants requiring displacement) do not automatically apply here. --- ## 1. CONCEPTUAL DEFINITION (CORE) **CHoCH** in this project is an *event* of internal structure reversal: 1. A **directional internal structure** already exists beforehand (running internal trend ≠ 0; a bullish CHoCH needs a bearish internal structure, a bearish CHoCH needs a bullish one) — causality: the structure precedes the event; 2. Price **closes across the last opposite internal swing pivot** (bullish CHoCH: close above the last internal pivot high; bearish CHoCH: close below the last internal pivot low) — **close-confirmed**; 3. The event carries a **new direction interpretation opposite to the previous structure** (reversal), not continuation (continuation = BOS); 4. An internal CHoCH must **not oppose the swing structure (len=50)** at the same bar (confluence gate / InpConfluenceFilter). CHoCH is a **reversal-indication** primitive: it marks the first bar where the internal structure flips. CHoCH **does not require displacement** and **does not require a liquidity event** to be detected as structure (the Sweep→CHoCH chain is a consumption chain, not the CHoCH detection definition). **BOS** (break of structure) is CHoCH's counterpart in the same structure engine: a break **in the same direction** as the previous structure (continuation). CHoCH = reversal break; BOS = continuation break. --- ## 2. STRUCTURE SOURCE (answer 6.1) | Structure Type | CHoCH status (f8/f9) | Used by | |----------------|----------------------|--------------| | **Internal swing high/low (fractal len=5)** | **VALID — the ONLY break source for f8/f9** | f8 `choch_dir`, f9 `choch_confirms`, f18, legacy signal chain | | **Swing high/low (fractal len=50)** | VALID only as the **confluence gate** (SwingTrendAt), not as the f8 CHoCH break level | g_swTrend, AddTrend timeline, f3/f5, f6/f14/f15/f17, f10/f11 | | **Fractal 2/2 (Engine 2)** | VALID for **AF_DetectChoch** (agents N/E) — separate definition (see §4.2) | Engine 2 (H4/M30/M15/M3) | | **HTF / external structure (D1/H4/H1)** | NOT VALID as a CHoCH break level | only direction bias f0-f2; v4.5 MTF structure not in ML features | Note: the same structure engine produces **two timelines**: `ProcessStructure(len=50, internal=false)` → swing timeline (g_swTrend + AddTrend) and `ProcessStructure(len=5, internal=true)` → internal timeline (g_inTrend + CHoCH). CHoCH f8/f9 comes ONLY from the internal timeline. --- ## 3. SWING DEFINITION (answer 6.2) ### 3.1 Internal pivot (source of CHoCH f8/f9) ```text Pivot definition : symmetric fractal high/low, length INTERNAL_LEN = 5 (5 left bars + 5 right bars). Equal-height/low bars do NOT cancel a pivot (only STRICTLY higher/lower bars cancel — "equal allowed"). Lookback / window : 700-bar cache ending at the decision bar t; 600-bar analysis region; internal pivots effectively on bars [max(95, t-604), t-5] (derived: begin = max(100, t-599); pivot p = i-LEN, i in [begin, t], LEN=5). Full-cache case (t>=699): p in [t-604, t-5]. Minimum bars : a pivot needs 5 confirmation bars per side; analysis starts at begin = max(100, t-599); the EA gate requires at least 160 bars (AF_BT_MIN_BARS) before analysis. Confirmation : a pivot at bar p is confirmed at bar p+5 (last right confirmation bar). A CHoCH break at bar b is valid only if p+5 <= b (the reference is locked before the break). Equal handling : equal HIGH/LOW bars with neighbors do NOT cancel a pivot (strict inequality only on the more extreme side). NO price/ATR tolerance for formation. Minimum pivot displacement : NO height threshold; only the fractal rule. ``` ### 3.2 Swing timeline (confluence gate) ```text Source : ProcessStructure(len=SWING_LEN=50, internal=false) Swing break : close[i] > last swing pivot high (bullish) / < last swing pivot low (bearish) — close-confirmed, fractal 50/50, equal allowed. SwingTrendAt(b) : the swing trend value (from the last swing break <= b): +1 / -1 / 0 (0 = no swing break yet in the window). ``` ### 3.3 Operational definition of "swing high/low" (non-CHoCH) The term "swing high/low" used by f6/f14/f15/f17/f10/f11 (P2.3) means the **last swing pivot (fractal len=50) in the absolute window [t-649, t-50]**; not a window extreme, not an intuitive "swing". Applies only to those features (established in P2.3/P3-S.2); CHoCH f8/f9 does not use these levels as break targets. --- ## 4. CHOCH DEFINITION (answer 6.3) ### 4.1 Feature CHoCH (f8/f9) — formal definition ```text Break reference : the LAST confirmed internal pivot (fractal len=5, equal allowed) before the break, on the opposite side: bullish CHoCH -> last internal pivot HIGH (H); bearish CHoCH -> last internal pivot LOW (L). Break condition : BULLISH CHOCH at bar b (p+5 <= b): close[b] > H (strict >; >= 1 tick excess) BEARISH CHOCH at bar b (p+5 <= b): close[b] < L (strict <) Precondition : BULLISH: prior internal trend < 0 (bearish internal structure before b; trend = direction of the last internal break before b). BEARISH: prior internal trend > 0. Confluence gate : BULLISH: SwingTrendAt(b) >= 0 (swing len=50 NOT down at bar b). BEARISH: SwingTrendAt(b) <= 0 (swing NOT up). Onset : the first bar b (per bar, forward) satisfying break + precondition + gate. One CHoCH per structure transition; later bars still on the break side are NOT new events. Wick break : NOT SUFFICIENT — the break must be by close (close[b] crosses the level). Close break : REQUIRED (definition above). Body-confirmed : NOT required (no body vs wick check). Displacement : NOT required for CHoCH f8/f9 (displacement is a separate primitive: AF_DetectDisplacement / fD Engine 2). Liquidity event : NOT required for CHoCH f8 detection (CHoCH stands alone as structure). The Sweep->CHoCH chain is consumption (f9, signal gate), not the detection definition. ``` ### 4.2 Engine 2 CHoCH (AF_DetectChoch) — second definition (not f8/f9) ```text Break reference : fractal 2/2 swing high/low (AF_BuildSwing), 200-bar lookback, max 64 pivots per side; break against highs[0]/lows[0] (the NEWEST swing). Trend precondition : AF_TrendFromSwing (4 newest highs + 4 newest lows, counting up/down pairs): bullish CHoCH needs trend<0; bearish needs trend>0. Break condition : close (newest closed slot bar) > highs[0] (bullish) / < lows[0] (bearish). Close-confirmed. Gate / displacement / liquidity : NONE. Timeframe : per agent slot (H4/M30/M15/M3 per AF_E2_TF_S1..S4). Note : this definition applies to the fuzzy N/E agents; NOT used by the ML features f8/f9. Two CHoCH definitions live in one project (see §12 ambiguities). ``` ### 4.3 Display CHoCH (AF_BuildStructLines) — third definition (visual) ```text Fractal 2/2, close break, "CHoCH" label when trend<0 (bullish break) / trend>0 (bearish break), otherwise "BOS". No confluence gate, no displacement. Visual only (Engine 3); not used by ML. ``` --- ## 5. MSS DEFINITION (answer 6.4) — TERMINOLOGY STATUS **The project treats CHoCH and MSS as the SAME concept.** Evidence: - The only "MSS" occurrence in design documentation is the combined label `CHoCH/MSS` (DESIGN.md §9, agent-N table; the P3 concept list `P3_SMC_SEMANTIC_VALIDATION`), written with a slash = synonym. - **NO MSS implementation exists anywhere in the codebase**: no function, no feature, no state, no dedicated document (verified: grep -ri "mss" = 0 code matches; the only matches are the DESIGN labels). - FEATURE_CONTRACT defines only CHoCH (f8/f9). The structure engine distinguishes only CHoCH vs BOS (reversal vs continuation). Consequences for the audit: 1. P3-S.3 assesses **CHoCH** as the primitive the project claims; 2. "MSS" as a separate concept (e.g. the common SMC definition: MSS = structure break + displacement + liquidity context) is **NOT adopted** by the project; 3. If a reader wants MSS = "break + displacement", then the project **does not define** such a primitive → that label is **SPECIFICATION AMBIGUOUS** at the terminology level, but NO code claims to detect it → not an audit target. ```text SPEC DECISION: CHoCH == MSS in the project's semantics (one structure-reversal primitive). The CHoCH/MSS distinction known in SMC literature (CHoCH = first reversal indication; MSS = displacement break) is NOT adopted: the project CHoCH does NOT require displacement. No code needs to be audited for "MSS as a different concept". ``` --- ## 6. DIRECTION (answer 6.5) ```text Bullish CHoCH (+1) : close > last internal pivot high; prior internal trend < 0; swing gate >= 0. = reversal from a DOWN structure. Bearish CHoCH (-1) : close < last internal pivot low; prior internal trend > 0; swing gate <= 0. = reversal from an UP structure. Neutral (0) : no active CHoCH / no valid reversal break. Bullish BOS (+1) : close > last internal pivot high; prior internal trend > 0 (upward continuation). Bearish BOS (-1): symmetric. ``` The CHoCH direction = direction of the NEW structure (post-reversal), not the break direction itself (an upward break = bullish CHoCH). Not merely a variable sign — the definition comes from the close-vs-level relation + the trend precondition. --- ## 7. BREAK SEMANTICS (answer 6.6) — MANDATORY ```text PROJECT CHOICE: CLOSE-CONFIRMED. - wick-only : NOT SUFFICIENT (the close must cross the level) - close-confirmed : YES — close[b] strictly > H (bull) / < L (bear) - body-confirmed : NOT required (no body/wick rule) - displacement-confirmed : NOT required (a separate primitive) Reason: FEATURE_CONTRACT f8 ("trend reversal at a break") + the ProcessStructure implementation (`close[i]>upTarget`) are consistent; no AUC/PF decision changed the CHoCH break definition in DESAIN_MTF_v45.md (AUC decisions only touched f10/f11 rejection). ``` Minimum excess: strict inequality (`>`/`<`); in tick-quantized prices = >= 1 tick. No ATR threshold, no tolerance. --- ## 8. PRECONDITION / PREVIOUS STRUCTURE (answer 6.7) ```text REQUIRED (defined): - Bullish CHoCH : prior internal trend < 0 (the last internal break before b is bearish; if there has never been a break -> trend=0 -> the first window break = BOS, NOT CHoCH). - Bearish CHoCH : prior internal trend > 0. - Swing gate : SwingTrendAt(b) not opposing (>=0 / <=0). NOT required: - An explicit HH/HL or LH/LL sequence is NOT computed; the precondition is only the last internal trend direction (not a sequence check). - The HTF trend state is NOT a CHoCH f8 precondition (HTF is only bias f0-f2). Status: NOT AMBIGUOUS — the precondition is defined by the structure engine. ``` --- ## 9. TEMPORAL SEMANTICS (answer 6.8) ```text Decision timestamp : closed bar t (the last M15 bar in the cache, Engine-1 closed-bar lock). All inputs <= t. Break bar b : the bar where close[b] crosses the level; b <= t. CHoCH can be detected ON the decision bar t (age 0). Pivot confirmation : pivot p valid only if p+5 <= b (the entire fractal confirmation window closed before the break). Lookback : internal pivots [max(95, t-604), t-5] (full cache); 600-bar analysis region from the 700-bar cache. Future visibility : NONE — break & confirmation use only bars <= t. Mutating future bars (b > t) must NOT change the CHoCH decision at t (property test CH-T14). Repaint : Engine-1 closed-bar lock; ProcessStructure re-runs per bar on closed data -> deterministic. ``` --- ## 10. EVENT VS STATE (answer 6.9) ```text CHoCH = EVENT + VALIDITY WINDOW in the semantic consumer chain. - DETECTION : CHoCH is an EVENT (onset bar b). One structure transition = one event. Bars b+1..b+n still on the break side are NOT new events (no duplicate emission). - f8 : "direction of the LAST CHoCH" — STATE of the last event (persistent until a newer event replaces it; SUPERSEDED by a CHoCH with a newer bar). This is per the FEATURE_CONTRACT f8 contract. - f9/f18 : chain consumers (choch confirm / confluence) must treat CHoCH as an EVENT with a VALIDITY WINDOW = SEQ_WINDOW (40), derived from v4.4 InpSeqWindow ("sweep -> CHoCH -> entry must chain within") — see §11. - Signal : the legacy v4.4/v4.5 gate uses (curBar - g_chochBar) <= InpSeqWindow + g_chochBar >= g_swpBar (freshness + ordering). ``` Do not treat every bar still in the "post-CHoCH" state as a new CHoCH event — this is exactly the f7 bug pattern (P3-S.0) that must be prevented. --- ## 11. LIFECYCLE (answer 6.10) ```text NO_CHOCH (0) -> CHOCH_ONSET (b, dir) : bar b, direction ±1 (from §4.1) -> ACTIVE : state f8 = dir; valid as "last CHoCH" -> EXPIRED (f9/f18 chain) : when age (t - b) > SEQ_WINDOW (40) — the event is no longer valid for confirm/confluence -> SUPERSEDED : a newer CHoCH (b' > b) replaces the f8 state (and the old event is no longer valid) -> NO_CHOCH : back to 0 only if no event ever occurred (f8 state) / after expiry (chain) INVALIDATED & CONSUMED : NOT modeled (same as the P3-S.2 sweep spec). Special note (f7-pattern audit): - The f8 state WITHOUT an age bound is PER CONTRACT (last CHoCH direction). - Chain consumers (f9/f18/signal gate) MUST apply SEQ_WINDOW. - The detector must still produce ONE onset per structure transition; hundreds of "post-CHoCH" bars must NOT become hundreds of events. ``` --- ## 12. TIMEFRAME (answer 6.11) ```text f8/f9 (ML features) : M15 ONLY (Engine-1 M15 slot; training-consistent). AF_DetectChoch (E2) : per agent-slot TF (H4/M30/M15/M3) — a different definition (fractal 2/2, no gate). Display : chart TF (fractal 2/2). HTF (D1/H4/H1) : only direction bias f0-f2; NOT a CHoCH f8 break reference. v4.5 MTF structure : computes BOS/CHoCH per TF (D1/H4/H1/M15) but is NOT wired to the ML features f8/f9. Project canonical status: feature CHoCH = M15 EXPLICIT; "canonical project CHoCH" (whether HTF structure must affect LTF events) = SPECIFICATION AMBIGUOUS (same as the P3-S.2 sweep finding G-3). ``` --- ## 13. SEMANTIC RELATIONSHIP WITH LIQUIDITY SWEEP (answer §17) ```text CHoCH detection (f8) : STANDS ALONE — does not require a sweep. f9 consumption : chochOK = CHoCH AFTER the sweep (chochBar >= swpBar) and same direction (chochDir == swpDir). This is a CHAIN, not the definition. Legacy signal gate : Sweep -> CHoCH -> OB/FVG within InpSeqWindow (40) — InpRequireSweep / InpRequireCHoCH (default true). Engine 2 E agent : ZONE + CONFIRMATION (sweep OR choch) = setup. NO detection dependency: CHoCH can occur without a sweep. f7 (sweep) MUST NOT be changed to satisfy the CHoCH requirements (and vice versa). ``` --- ## 14. SPEC DECISION SUMMARY (tabular) | # | Aspect | Decision | |---|-------|-----------| | S-1 | Structure source | Internal swing pivot fractal 5/5 (equal allowed) — feature f8/f9; swing 50 only as gate; Engine 2 fractal 2/2 | | S-2 | Swing definition | fractal 5/5, confirmation p+5, window [max(95,t-604), t-5], equal allowed, no height threshold | | S-3 | CHoCH | close > last internal pivot high (bull) / < last pivot low (bear); opposite prior internal trend; non-opposing swing gate | | S-4 | MSS | SAME AS CHOCH (project synonym label); no separate primitive; the MSS+displacement definition NOT adopted | | S-5 | Direction | +1 bullish (reversal from down), -1 bearish (reversal from up), 0 none | | S-6 | Break semantics | CLOSE-CONFIRMED (wick-only insufficient; body not required; displacement not required) | | S-7 | Precondition | prior internal trend != 0 (reversal); non-opposing swing gate; NO explicit HH/HL/LH/LL sequence | | S-8 | Temporal | closed bar t; break b <= t; pivot p+5 <= b; no future visibility | | S-9 | Event vs State | EVENT (detection) + STATE (f8 last dir) + VALIDITY WINDOW 40 (f9/f18/gate) | | S-10 | Lifecycle | NO_CHOCH / ONSET / ACTIVE / EXPIRED / SUPERSEDED; INVALIDATED & CONSUMED not modeled | | S-11 | Timeframe | f8/f9 = M15 only; Engine 2 per-TF; canonical project = SPECIFICATION AMBIGUOUS | | S-12 | Sweep relation | detection independent; consumption chain (f9/gate) uses ordering + freshness | --- ## 15. RECORDED AMBIGUITIES (SPECIFICATION AMBIGUOUS) ```text A-1 MSS vs CHoCH at the terminology level: the project uses "CHoCH/MSS" as a synonym; if a reader wants a different MSS definition (break + displacement), the project does NOT define it -> AMBIGUOUS (no code). A-2 Canonical CHoCH timeframe (MTF vs M15): f8/f9 M15 explicit; the role of HTF structure on LTF events not established -> AMBIGUOUS (project). A-3 Same-bar two-direction break precedence (bullish & bearish breaks can both be evaluated on the same bar in ProcessStructure): the bull-then-bear execution order in the code; NOT adjudicated; unreachable with consistent data (analogous to the P3-S.2 sweep E-11 proof). A-4 Weak confluence gate: SwingTrendAt(b)>=0/<=0 (non-opposing), NOT "aligned" (>=1 / <=-1). The InpConfluenceFilter comment ("must align with swing trend") is stronger than the implementation. Weak vs strong gate intent NOT adjudicated -> AMBIGUOUS (small). ``` --- ## 16. PROVENANCE & CHECKPOINT ```text Forge HEAD (audit) : 595b4c9a622703b05228bd563b4979fef81a2ebf (P3-S.2) P3-S.2 spec : docs/SMC_LIQUIDITY_SWEEP_SPEC_v1.md (immutable) FEATURE_CONTRACT : C44CC6F2... (P2-era) / 7b908b12... (committed) Reconciled sources : see docs/P3_S3_CHOCH_MSS_CONFORMANCE.md §A Human verification : CANCELLED (human annotation is not a validation gate; old packages remain historical artifacts) ```