lookahead-free

Verifiable look-ahead-freedom for the value-independent fragment of data pipelines. Declare your pipeline as a temporally annotated DAG 鈥?reads with release times, windows with ends, PIT reads with cutoffs, decisions with decision times 鈥?and lf check proves, in linear time, that no decision consumes data that was not knowable yet. Python 3.11+, zero dependencies, Windows / Linux / macOS.

Status: v0.1 鈥?alpha. The model follows Fonseca (2026); expect the op kinds and CLI to grow.

Why this exists

Look-ahead bias is the quiet killer of backtests: a pipeline that computes today's signal from data that only becomes available at 16:00, then "decides" at 15:00, looks great and lies. The usual defenses are heuristics 鈥?reviewers eyeballing code, linters matching patterns. This tool is different: it checks a declarative description of the pipeline and gives an exact verdict on the fragment where exactness is possible.

Grounding. Fonseca (2026), "Look-Ahead-Freedom as Temporal Non-Interference" (arXiv:2607.04958, submitted to ACM TOSEM) proves that look-ahead-freedom is undecidable in general (螤鈦扳倎-hard when availability depends on data values), but admits a linear-time decidable type-effect system on the value-independent fragment 鈥?windowing, resampling, joins, point-in-time and vintage reads. This tool implements exactly that system:

• every op carries a temporal bound (release / window end / PIT cutoff / decision time),
• output availability is derived exactly (monotone: no op can produce a fact earlier than the facts it consumes),
• decision availability is checked exactly: every input of a decision must be available at or before the decision time.

Honest boundary (stated, not hidden). Operations declared value_dependent: true are flagged at the heuristic boundary (P1): their temporal structure is still checked exactly, but for the operation itself no verifiable claim exists 鈥?Fonseca's undecidability result is precisely about value-dependent availability. The tool says so, in the report, every time.

Quick start

# install from PyPI (once published)
pip install lookahead-free

# or run without installing anything:
#   PYTHONPATH=src python -m lookahead_free --help

python examples/demo.py                    # clean pipeline passes, leaky one fails

lf check --pipeline examples/factor-pipeline.json
lf check --pipeline pipeline.json --json   # machine-readable verdict

Exit codes: 0 = no look-ahead in the value-independent fragment, 1 = at least one P0 temporal violation (or unresolvable DAG), 2 = usage error. Wire it into CI as a hard gate on every pipeline definition.

Pipeline format

A JSON object with a name and an operations list. Each op:

Availability of an op's output = its explicit bound, or the maximum availability of its inputs. See examples/factor-pipeline.json for a complete factor pipeline (quotes 鈫?windows 鈫?PIT fundamentals 鈫?join 鈫?agentic retrieval 鈫?decision).

The checks

Philosophy

Prices must be knowable; decisions must be honest; undecidability must be stated.

The reproducibility crisis in computational research is structural, and in quantitative finance it shows up first as leakage: point-in-time data discipline (Kelly et al., NBER w35247; Look-Ahead-Bench, arXiv:2601.13770) is now an industry-wide principle because look-ahead silently inflates alpha (Daniel, Sornette & Wohrmann 2008). What has been missing is a machine-checkable statement of compliance. lookahead-free makes the claim "this pipeline does not peek" a CI gate instead of an audit ritual 鈥?and where the theory says no proof exists, it says so instead of pretending.

Development

python -m pip install -e . pytest
python -m pytest

CI runs the full test suite on Ubuntu, Windows and macOS with Python 3.11 and 3.12. Issues are handled on weekends; pull requests are welcome.

Related work

• Fonseca (2026), Look-Ahead-Freedom as Temporal Non-Interference (arXiv:2607.04958) 鈥?the formal property and its decidability boundary
• Daniel, Sornette & Wohrmann (2008), Look-Ahead Benchmark Bias (SSRN 1289222) 鈥?the bias, quantified
• Kelly et al., Scaling Point-in-Time Language Models (NBER w35247) 鈥?PIT as an industry principle
• Look-Ahead-Bench (arXiv:2601.13770) 鈥?measuring look-ahead in PIT systems
• Temporal Leakage in LLM Backtesting (arXiv:2608.02985) 鈥?why passive scores cannot separate skill from leakage

Project family

Part of Foolproof Labs — a toolchain against self-deception in quantitative research:

• pit-adjuster — PIT back-adjustment with static forward-adjustment drift detection
• falsification-ledger — pre-registration and falsification ledger
• factor-qc — fail-closed backtest quality gate
• lesson-book — tuition memory for traders
• lookahead-free — verifiable look-ahead-freedom checks
• ashare-data-immunity — data immunity for A-share daily bars

License

MIT