fix(api)!: validate declared bar grids before feature computation - #90

Closes #76

Outcome

Validate a declared schedule before feature computation can treat a multi-period price return as a one-bar return. Missing, duplicate and off-grid observations fail atomically. The validator uses existing exchange schedule adapters, including real holidays, early closes and breaks, without inferring frequency from observation spacing or filling prices.

compute_features(prices, [], feed_spec=contract) validates and orders prices before the caller derives returns. Finite returns adjacent to missing prices are rejected, so reindexing already-derived returns cannot conceal an outage.

Compatibility

This targets the next minor version (0.2), not the qualified 0.1.7 patch. Calendar selection follows the shared Specs v2 contract: explicit argument, then declared metadata, then NYSE. Explicit calendar=None selects observation rows in their original order. Calendar-aware calls require declared fixed intraday bar semantics and support expected-bar windows; session and elapsed windows fail explicitly.

Existing row-based examples now select calendar=None. Legacy Specs v1 serialization stays unchanged; old omitted-calendar feature calls are intentionally not claimed compatible.

Specs PR35 is merged. Its main commit 701bde68744035050ede386efce498234c661c21 has the identical tree to reviewed ee125aab3878e3d3f98254e91b59c8fe25bfb6ab. Project metadata and uv.lock pin the merged immutable HTTPS Git source. Wheel metadata carries the same dependency, so a clean install cannot silently resolve published Specs 0.1.5, which lacks this API. Before PyPI publication, replace the source dependency with a verified published Specs version containing v2 and repeat installed-package qualification. No release is requested here.

Verification

Base public API 2ef47fe with the qualified Specs v2 dependency fails all 38 original acceptance cases. Two expose silent acceptance of undeclared/incomplete grids; remaining new-keyword cases expose the missing public API. Integrated source 650bc88 passes those same cases. Regressions exercise public prices-to-returns-to-features workflows for continuous hourly bars, NYSE closures and missing scheduled bars, true row-mode invariance, shared JSON/YAML producer handoff, overrides, and failure before any feature executes.

At 3080414915c5c8fd7afd90203d7defb3d221a6bb, full Linux suites passed 4,358 tests on each supported Python 3.12, 3.13 and 3.14. All 62 public API cases passed from each installed wheel. Coverage was 95.86% lines and 89.65% branches, with all repository thresholds passing. Ruff, format, ty, real hooks, strict MkDocs, executable documentation, build and strict Twine passed. These earlier runs used the exact unpublished Specs qualification wheel and are not presented as hosted evidence.

At source-pin revision 4119918405cfd4dae5214061e38e9ac0c63cfb88, clean uv sync fetched and built the merged immutable Specs source. The 82 public/grid cases, whole-source Ruff/format, ty, build and all-file hooks pass. Supported hosted qualification is triggered by this PR; its actual results govern readiness.

Follow-up head 2ad32557f588cdf119e3f6eeb74786eb7bd402a0 resolves the first hosted failure: a configuration test still demanded the old Specs bound. Source qualification now permits only an immutable canonical Specs pin matching the lock, while actual release selection rejects Git/URL dependencies from both built wheel and sdist metadata before any publication or documentation deployment. Real Hatch-built source-dependent artifacts reproduce the missing release rejection on dc184b4 (one failure and one index-dependency passing control); the repaired release/artifact suite passes 30 tests.

Independent public API review also reproduced a fine-grid resource defect at 4119918: two prices an hour apart with a valid one-microsecond grid timed out after five seconds while allocating expected bars. dc184b4 generates labels incrementally, skips intervals preceding observed coverage arithmetically and stops at the first missing label. The same eager/lazy public workflows now reject the first missing microsecond promptly; all 84 API/grid cases pass. Hosted qualification is rerunning at the current head. No checks were disabled or waived.

Current reviewed head 163cd56988ceedf8f34779bdf50dc28f26dbc986 also rejects sub-microsecond timestamps before converting to Python datetime, preserving aligned nanosecond timestamps and row mode. Real Polars input on 2ad3255 reproduced silent acceptance of one-nanosecond off-grid offsets (two failures, two aligned-input passing controls).

At current head 163cd56, full local Linux suites pass 4,366 tests each on Python 3.12, 3.13 and 3.14. Installed-wheel focused API/grid/legacy-contract/artifact/policy suites pass 124 tests each. Coverage is 95.88% lines, 89.66% branches, with every repository threshold passing. All-file hooks/types, package build and strict Twine pass. Installed API/grid bytes match the exact wheel; original outage, row mode and caller-normalized price workflows pass independently on all three interpreters. All three installed environments pass uv pip check. Earlier full results above retain their actual tested revisions.

Merged normally at 0e7865273cd462c507de02a9d3b64de7c6cbb099 after all 30 applicable PR checks passed, with only the configured Python 3.15 wait skipped. All nine supported source cells passed; all nine installed-wheel cells completed ten full suites each, with 4,366 passing tests per suite. CI, ecosystem qualification, security, docs.

Reviewed head 163cd56, tested synthetic merge f813ea574250b00f7768ab559f5b027d9fdd902c and actual main have exactly tree c84ab57376409b4f704e12246076d8f056b7d95b. Fresh main checks pass 124 focused tests and strict docs. Separate automatically triggered main CI is running and is not relabeled as complete. No check waiver, admin bypass, release, tag or documentation deployment occurred.

AI assistance

Codex helped produce the implementation, tests, migration documentation and this description, and executed the recorded checks. The implementation and diff were reviewed in this maintenance session; no numerical feature definitions were changed.