Historical Precedent Engine [HPE]

WHAT IT DOES

HPE takes the last few candles on your chart, searches that chart's own history for
earlier sequences that resemble them, and shows you what price did after those earlier
sequences. It is an analog study. The output is a summary of precedent, not a forecast.

TUNING IS NOT OPTIONAL — READ THIS FIRST

This is a matcher, and a matcher only speaks when it finds something. Every enabled
filter is a hard gate applied to every candle in the fingerprint, and the gates compound:
a sequence qualifies only if candle 1 passes wick, body and volume, and candle 2 passes
all three, and so on, and the sequence momentum passes, and the direction rule passes.
Tighten two of those and the survivor count does not halve, it collapses.

So the normal failure mode is an empty dashboard. Median outcome, tolerance band, delta
and range all read "—", Bias reads Neutral, and Matches Used reads 0. That is not a bug
and it is not the tool being broken. It means nothing in this chart's history was close
enough to the present under the settings you have. The honest answer for that bar is
silence, and the tool gives it.

The tolerance units

Wick and body are measured as a percentage of the candle's own high-to-low range, not of
price. An upper wick occupying a fifth of its candle scores 20, whether that candle is a
one-minute Bitcoin bar or a daily equity bar. A tolerance of 12 therefore means "within
12 percentage points of range", and it means the same thing on every instrument and every
timeframe.

That is deliberate. Measured against price instead, the same tolerance would need to be
roughly a hundred times larger on a daily equity chart than on a one-minute crypto chart,
and no single default could serve both — one setting would accept everything on one chart
and nothing on the other.

On Auto-Tune, which ships OFF

Auto-Tune moves the wick and body tolerances based on how well recent projections
resolved. It ships disabled, for two measured reasons.

It cannot start from nothing. It does not act until at least five projections have been
scored, so if your tolerances are too tight to ever produce a match, there are no
projections, nothing is scored, and it never moves. It is a regulator, not a starter
motor.

And once it does start, it tends not to stop. It can only travel between a quarter and
four times your input, and when widening fails to improve fit — which is the usual case
if the matches were poor to begin with — it widens every bar until it pins at four times
your input and stays there. On the test chart it did exactly that, and the difference it
made was 50 resolved projections instead of 49. It bought one projection out of fifty
while making the number in the settings box a fiction.

So it is off, and what you type is what runs. Turn it on if you want it, knowing both of
the above.

The order to loosen in, most effective first:

1. Strict Direction off. With it on, every candle must match direction, which is a
1-in-2^N filter before any tolerance is applied. This is the single biggest lever.
2. Shorten Sequence Length. Fewer candles means fewer conjunctive conditions. Three is
the minimum and is the default for that reason.
3. Raise Wick and Body Tolerance, in the units described above.
4. Turn off Require Per-Candle Volume Match and Require Momentum Match. Volume ratios in
particular are noisy on short timeframes and reject a lot for little gain.
5. Lower Min Matches Required. It ships at 2 rather than 3 because on the instrument
these defaults were measured on, 3 never fires. Read the last paragraph of this
description before you take that as a recommendation.

Where the defaults came from

They were measured with a full 1,000-sequence library on three charts chosen to be as
unalike as possible, and they were picked to make the engine speak at all rather than to
make it look good:

COINBASE:BTCUSD 1-minute 73 projections over 25,837 bars
COINBASE:BTCUSD 1-hour 33 projections over 22,764 bars
AMEX:SPY daily 29 projections over 8,436 bars

That is between one bar in 290 and one bar in 690 — the same order of magnitude across a
crypto intraday chart and an equity daily chart, with no per-instrument tuning. It should
still be quiet, and you should still retune for your own instrument and horizon, but the
defaults are a measured starting point rather than a guess.

One note on reading the dashboard while you do that. The calibration row shows total
projections alongside how many sit in the calibration window, and that window is capped by
Calibration window (samples) — 50 by default. Watch the total, not the window. The window
fills early and then stops moving, which makes a well-tuned setup and a barely-working one
look identical.

ON LIBRARY SIZE

Max Stored Sequences is the pool the matcher searches, and a bigger pool is the one way
to get more matches without making each match mean less. It is capped at 1,000 by default
for a practical reason: raising it substantially can push the script past TradingView's
calculation limit, at which point it stops reporting entirely. If you raise it and the
indicator goes blank rather than merely empty, that is what happened. Put it back. This
cap is also the real ceiling on how often the engine can fire at a tolerance tight enough
to be meaningful, and it is worth knowing that before you go hunting for settings.

HOW IT WORKS

1. Fingerprint. On every confirmed bar, the last N candles are reduced to a five-field
vector per candle: upper wick, lower wick, body, direction, and volume measured
against its own moving average.

2. Store. That fingerprint is written to a rolling library along with what price did over
the following bars.

3. Match. The current fingerprint is compared against every stored sequence. A stored
sequence qualifies only if each candle falls inside the wick, body and volume
tolerances, and only if the sequence momentum falls inside its tolerance. Direction
matching is separate: with Strict Direction on, every candle must match direction;
with it off, only the final candle must. An optional session filter restricts matches
to the same trading session.

4. Summarise. Qualifying matches are ranked by how well their own past projections
resolved, and the strongest are combined into a single percentile outcome — the median
by default. If fewer than Min Matches Required qualify, nothing is drawn.

5. Calibrate. Once the horizon elapses, each projection is scored against what actually
happened. That score weights how much a stored sequence counts in future matches, and
feeds Auto-Tune if you have enabled it.

READING THE CHART

Projection line and band — the percentile outcome of the current match set, extended to
the horizon.

Consensus paths — the individual paths of the top matches, drawn separately, so you can
see the spread the single summary line came from. A tight cluster and a wide scatter
produce the same median.

Rolling projection trail — past projections left on the chart beside what price actually
did. This is deliberate. A tool that hides its misses is not worth reading.

Dashboard — match count, median outcome, ±1σ range, session, library size, live
tolerances, and the calibration block. The projection values — median outcome, tolerance
band, delta, range, bias, match count and best-match error — are cleared at the start of
every confirmed bar, so those rows always show that bar's answer and never a leftover
from an earlier bar that happened to match. The library and calibration counters are
cumulative by design and do not clear.

The same state is also published to the Data Window as plain numbers, which is easier to
read than canvas text while you are tuning.

ON THE CALIBRATION NUMBERS

The dashboard reports mean projection error, not accuracy.

It is the average distance between projection and outcome, expressed as a share of the
size of the move that actually occurred, measured over the most recent resolved
projections on the chart you are looking at. It is computed in-sample, on bars the engine
had already stored, and it is not a forward result.

It is there so you can tell whether your tolerances are set sensibly. It is not evidence
that the tool works, and it should not be read as a hit rate. Because the actual move is
the denominator, the figure also moves with volatility regime rather than with skill
alone — quiet bars punish it, large moves flatter it.

ON REPAINTING

Two specific claims, both checkable in the source:

There are no request.security() calls anywhere in this script. Every value is computed
from the chart's own bars, so there is no higher-timeframe lookahead question to get
wrong in the first place.

Every drawing and every dashboard write sits inside a single barstate.isconfirmed gate.
Nothing is created, moved or deleted while the live bar is still forming.

A projection does extend to bars that have not happened yet. It does not move once drawn.
It is simply right or wrong, and the trail is there so you can see which.

SETTINGS WORTH KNOWING

Sequence Length — how many candles form the fingerprint. Longer is stricter and finds
fewer matches, and the effect is multiplicative rather than linear.

Min Matches Required — below this count nothing is drawn.

Delta Percentile — 50 is the median. Move it to read the pessimistic or optimistic tail
of the same match set rather than its centre.

Auto-Tune Tolerances — off by default; see above before enabling.

Strict Direction — the difference between "these candles had the same shape" and "these
candles had the same shape and went the same way."

WHAT THIS IS NOT

This is a visualization and analysis tool, not a trading system. It does not produce
advice. Nothing here is a signal to enter or exit a position, and no performance is
claimed or implied. Markets change regime, and any tool built on historical structure
will fail when they do. Use it as context alongside your own analysis.

One more thing worth saying plainly, and it is the honest counterweight to the tuning
advice above: a small sample of matches is a small sample. Two historical analogs tell
you very little, and the engine will draw a line from two just as readily as from thirty.
Min Matches ships at 2 because that is what it took to get the engine to speak on the
instrument it was measured on — which is a statement about how hard analogs are to find
in a 1,000-sequence library, not a claim that two is enough to believe. Loosening the
filters until something appears is easy, and it is exactly how you end up reading noise.
Watch the match count before you read the line, and treat a projection drawn from a
handful of precedents as the weak evidence it is.