417 lines
20 KiB
Markdown
417 lines
20 KiB
Markdown
# 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)
|
|
```
|