20 KiB
20 KiB
SMC CHOCH / MSS — PROJECT SEMANTIC SPECIFICATION v1
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:
- 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;
- 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;
- The event carries a new direction interpretation opposite to the previous structure (reversal), not continuation (continuation = BOS);
- 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)
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)
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
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)
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)
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 listP3_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:
- P3-S.3 assesses CHoCH as the primitive the project claims;
- "MSS" as a separate concept (e.g. the common SMC definition: MSS = structure break + displacement + liquidity context) is NOT adopted by the project;
- 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.
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)
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
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)
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)
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)
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)
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)
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)
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)
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
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)