Define leakage-resistant delay-model contract

[mitulpatel123]

What changed

• defined the exact T-24h arrival-delay prediction task
• documented the BTS source, cohort, target, candidate study window, and chronological split
• separated schedule-time features from prohibited post-departure leakage fields
• established missing-data, category, evaluation, calibration, error-slice, and threshold-selection rules
• added reproducibility and model-artifact safety requirements
• excluded raw/processed data and model/report artifacts from Git

Why

The live v0.1 API currently exposes a transparent rules baseline. Before adding a trained model, the project needs an auditable contract that prevents target leakage, retrospective metric inflation, and unsafe artifact handling.

Impact

Issue #2 now has a concrete foundation for preprocessing and training. Future model results can be evaluated against a fixed question and acceptance standard instead of changing the task to fit the output.

Validation

• python -m pytest — 6 passed
• git diff --check
• source and field definitions checked against the official BTS Reporting Carrier On-Time Performance documentation

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4c642918d5

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Cut historical aggregates off at the prediction timestamp

For a T-24h prediction, requiring only that an aggregate use rows earlier than the current row still permits future outcomes. For example, when scoring an 18:00 flight at 18:00 the previous day, a same-day 10:00 flight sorts earlier but its ArrDel15 is not yet known. Implementing the contract literally would therefore leak labels into every listed prior-delay feature and invalidate validation/test metrics; require each contributing outcome to have become available before the current flight's T-24h timestamp, including the prior used for smoothing.

Useful? React with 👍 / 👎.