# BTC Macro Elliott Demo Guide

`ElliottWaveBtcMacroCycleDemo` is now the BTC reporting wrapper over the unified core Elliott engine. The historical BTC macro study and the live BTC preset no longer rely on a preferred demo-local interpretation path.

## What you can run

- Historical truth-set validation:
  - uses the ossified BTC daily dataset plus the locked BTC anchor registry
  - scores the candidate profiles against the major macro turns
  - emits the macro-cycle JSON report and regression chart
- Live BTC preset:
  - uses only the `BarSeries` you provide at runtime
  - infers the current-cycle start from that supplied window alone
  - emits the current-cycle JSON summary plus the base case and alternate charts

## Canonical entrypoints

- Generic canonical demo:
  - `ElliottWaveMacroCycleDemo`
  - owns the series-native historical study, live preset, and shared chart/report rendering flow
- Stable BTC wrapper:
  - `ElliottWaveBtcMacroCycleDemo`
  - keeps fixed BTC resources, default filenames, and BTC-oriented entrypoints for users and regression tests
- Calibration and compatibility harness:
  - `ElliottWaveAnchorCalibrationHarness`
  - owns truth-target scoring, routine/targeted calibration artifacts, and the temporary legacy anchored comparison path

The important line is that the legacy-anchored study is no longer a first-class runtime demo. If you need legacy-versus-canonical comparison, use the harness artifacts rather than treating the old anchored path as a second production engine.

## What stays the same

- The BTC demo still writes the same chart/report artifacts.
- The live preset still keeps compatibility with the existing file naming and reporting flow.

## Which entrypoint to use

- Use `ElliottWaveBtcMacroCycleDemo` when you want the fixed ossified BTC dataset, the locked BTC truth registry, and the stable BTC artifact names.
- Use `ElliottWaveMacroCycleDemo` when you already have a `BarSeries` and want the canonical historical study or live preset without BTC-specific resource loading.
- Use `ElliottWaveAnchorCalibrationHarness` when you are calibrating, benchmarking, or comparing canonical output against the committed BTC truth target.

## What changed

- Historical anchor-to-anchor fits and live current-cycle fits now come from the same core-ranked Elliott logic.
- The BTC truth set is the regression guardrail for the core engine, not a second “smarter BTC-only engine.”
- The preferred BTC answer is no longer a legacy local-structure path. If the wrapper remains, it is there to load BTC resources, choose the prevalidated default profile, and render outputs.

## BTC truth target

The BTC anchor registry is now a calibration asset, not a runtime input. It encodes the committed macro truth target the canonical engine must learn to reproduce from price alone.

- Reference early segment:
  - `2011-06-09` top
  - `2011-11-18` low
  - calibration-only evidence, not production runtime structure
- Accepted validation cycle turns:
  - `2013-11-30` top, expected `WAVE5`
  - `2015-08-19` low, expected `CORRECTIVE_C`
  - `2017-12-18` top, expected `WAVE5`
  - `2018-12-16` low, expected `CORRECTIVE_C`
- Holdout cycle turns:
  - `2021-11-11` top, expected `WAVE5`
  - `2022-11-22` low, expected `CORRECTIVE_C`

The harness resolves broad committed registry windows against the ossified BTC daily dataset, then converts the distance from the resolved extremum to each window edge into `toleranceBefore` and `toleranceAfter`. That keeps acceptable match windows pinned to the committed truth target instead of drifting via runtime heuristics.

## Runtime contract

- Runtime historical decomposition must not depend on the BTC anchor registry.
- Live current-cycle analysis must not depend on the BTC anchor registry.
- `ElliottWaveMacroCycleDemo` is the canonical runtime controller/view surface.
- `ElliottWaveBtcMacroCycleDemo` may remain as a thin BTC convenience wrapper, but it must not own distinct structure inference logic.
- The registry is valid only for:
  - offline calibration
  - offline regression
  - holdout scoring
  - debugging and evidence output
- If a runtime chart or report needs anchors to decide structure, that path is still not the canonical engine.

## Maintainer note

- Treat the BTC anchor registry and ossified BTC dataset as validation assets for core Elliott behavior.
- When changing Elliott ranking, swing preservation, or current-cycle fitting, rerun the real BTC macro regression and compare:
  - selected profile / hypothesis
  - accepted historical cycles / segments
  - current wave
  - phase and structural invalidation output
- Historical truth-set validation answers “does core still explain the locked BTC cycle turns?”
- Live runtime analysis answers “what does the unified core engine infer from the bars supplied right now?”
- Prefer these operating modes when validating changes:
  - `--targeted` for fast BTC window checks
  - `routine` for the default full-history BTC sanity lane
  - `--exhaustive` only when you explicitly need the broader profile search and portability sweep

## Release validation

Before shipping changes that touch the canonical macro-cycle flow, rerun both the focused BTC regression slice and the quiet full build:

```bash
mvn -q -pl ta4j-examples -am -Dsurefire.failIfNoSpecifiedTests=false \
  -Dtest=ElliottWaveBtcMacroCycleDemoTest,ElliottWaveMacroCycleTruthTargetScoringTest,ElliottWaveMacroCycleDetectorTest,ElliottWavePresetDemoTest \
  test

scripts/run-full-build-quiet.sh
```

The focused slice proves truth-target recovery, canonical historical/live reuse, and chart/report persistence. The quiet full build is the production gate.