The bug that silently improves your backtest

scipy.ndimage.minimum_filter1d(x, 20) looks innocent. Its default origin=0 makes it a centered window [t-10, t+9] — it reads 9 future days, runs without error or warning, and only makes the equity curve prettier. One missing parameter once invalidated 14 rounds of research.

lookahead-guard turns "this isn't a lookahead bug, right?" from a prayer into a re-runnable gate.

Four independent layers

• A — Primitive semantics. Does this rolling/filter primitive equal the true trailing window [t-n+1, t]? Compared cell-by-cell against a reference implementation for a=1..30.

• B — Future-blind test (the only decisive one). Perturb data after time t; if any output at or before t changes, it is a lookahead bug. Depends on no returns, no assumptions.

• C — Static AST sentinel. Flags centered windows, negative shift, full-sample standardization, bfill, random splits.

• D — Permutation test. Uses a circular-shift null rather than naive shuffling — naive shuffling destroys autocorrelation and yields optimistic p-values.

What it does not do

It does not predict returns, rank strategies, or promise profit. It answers exactly one question: does this code or signal peek at the future?

Install

pip install lookahead-guard
pip install "lookahead-guard[full]"   # adds pandas/scipy for the B layer

Honest boundaries — please read

• Layer C is a heuristic, not a proof. Passing C does not mean you are clean; B is the real test.

• full-sample-stat deliberately marks cross-sectional statistics MEDIUM, because that pattern is often legitimate.

• negative-shift alone is usually innocent — shift(-1) is standard when building forward-return labels.

• Layer A must compare against the same window. An earlier version compared against len(a) instead of n and became a new contamination source; there is a regression test for that bug.

MIT licensed. Pure Python, no network calls, no telemetry, runs fully offline.