set50-system/docs/engineering-log/2026-08-24-pit-price-contract.md

PIT Daily Price Archive Contract — 2026-08-24

Status

• Implementation: complete for the local research/paper vertical slice.
• Provider evidence: not established yet.
• Backtest/event-study readiness: blocked until a real archive satisfies this contract and the BOT source reaches the independent-vintage threshold.
• Existing revised vendor history remains point_in_time=false.

Contract

point_in_time=true is accepted only when all of the following are present and bound into the immutable price manifest:

• quality=point_in_time_archive.
• archive_contract=pit-daily-v1.
• Non-empty provider_release_id, source_url, parser_version, and timezone-aware retrieved_at.
• point_in_time_evidence with known_at_field=known_at, known_at_semantics=provider_release_time, a matching provider release ID, and timezone-aware release_published_at.
• Every series has a matching canonical_symbol, an IANA timezone, and ordered unique bars.
• Every bar has session_date, timezone-aware known_at, OHLC, adjusted_close, and volume values. known_at must not be after the session date in the market timezone or after retrieval.
• Snapshot raw-payload hashes, normalized hash, manifest identity, and contract metadata must agree on reload.

The generic Yahoo collector does not produce this evidence and continues to persist revised_vendor_history with point_in_time=false.

No-lookahead behavior

The event-study runner has an explicit require_price_known_at=True mode. The research runner enables it for PIT snapshots. It rejects missing timestamps and rejects any price whose known_at falls on a later market-local session date, including UTC timestamps that cross the market-timezone boundary.

Changed files

• backend/app/prices.py — PIT contract validation, per-bar known-at checks, timezone validation, manifest binding.
• backend/app/event_study.py — known-at-aware price joining and market-timezone no-lookahead checks.
• backend/app/research.py — carries session date, known-at, and market timezone into the event-study join; enables the PIT check.
• backend/app/__init__.py — exposes contract metadata in price health and keeps backtest readiness fail-closed.
• backend/tests/test_prices.py, backend/tests/test_event_study.py, backend/tests/test_research.py — RED/GREEN regression coverage for missing contract evidence, missing known-at, manifest binding, revised-history preservation, and timezone lookahead.

Verification

• PYTHONPATH=backend .venv/bin/python -W error -m unittest discover -s backend/tests -v — 93 tests passed.
• PYTHONPATH=backend .venv/bin/python -m compileall -q backend — passed.
• npm run build — passed.
• npm audit --omit=dev --audit-level=high — 0 vulnerabilities.
• git diff HEAD --check and git diff --cached --check — passed.
• Static credential-pattern scan over git diff HEAD — 0 findings.
• Final bounded independent review deleg_c08f6dd8 — exact schema returned passed=true with empty security-concern, logic-error, and suggestion arrays. Two earlier reviewer attempts timed out and were not counted.
• App smoke check: /api/v1/prices/health returned HTTP 200 for revised history; /api/v1/backtest/tourism?min_events=1 returned HTTP 409 with blocked / price_series_not_point_in_time.

Remaining work

• Obtain an actual provider archive/release contract and evidence for PIT semantics; do not flip the live Yahoo flag by configuration alone.
• Collect at least 12 independent BOT releases; repeated observations of one release do not count.
• Only after both gates pass should a frozen event-study/backtest result be treated as available. No alpha or investment claim is established here.
• No commit or push was performed in this session.