Skip to content

feat: DataPhase1 preflight — fail-fast credential + dependency checks#55

Merged
cipher813 merged 1 commit into
mainfrom
feat/dataphase1-preflight
Apr 17, 2026
Merged

feat: DataPhase1 preflight — fail-fast credential + dependency checks#55
cipher813 merged 1 commit into
mainfrom
feat/dataphase1-preflight

Conversation

@cipher813
Copy link
Copy Markdown
Owner

Summary

  • New `validators/preflight.py` runs at the START of `_run_phase1` before any collector executes.
  • Catches credential drift, external-API outages, and S3/ArcticDB misconfiguration in ~10s instead of ~55min into a doomed spot run.
  • Complements postflight (PR feat: DataPhase1 postflight — producer-side consumer-contract checks #52, output-contract checks AFTER writes) — same failure surface, opposite side of the pipeline.

Five checks (cheapest-first)

  1. Required env vars present + non-empty (`POLYGON_API_KEY`, `FRED_API_KEY`)
  2. S3 bucket HEAD + sentinel PUT/DELETE (validates IAM beyond list)
  3. ArcticDB connect + `universe`/`macro` libraries present
  4. FRED reachable + auth valid (DFF observation call)
  5. polygon.io reachable + auth valid (reference-data call)

Failure surface

`PreflightError` → `results["status"] = "preflight_failed"` → `SystemExit(1)` → SSM → SF HandleFailure → `alpha-engine-saturday-sf-failed` alarm. One named failure, one alarm.

Scope-out

  • Skipped on `--only ` (single-collector debug runs don't need preflight).
  • Skipped on `--phase 2` (Lambda has different deps; its own preflight when needed).
  • Does NOT do value-range / outlier validation — tracked as P2 in ROADMAP.
  • Does NOT do schema-registry-style contract validation — tracked as P3 in ROADMAP.

Test plan

  • 24 new unit tests cover each check + end-to-end `run()` ordering + short-circuit on first failure.
  • Full data-module suite: 84 passed, zero regressions.
  • Saturday 2026-04-18 00:00 UTC live validation: `spot_data_weekly.sh` should log `preflight: all DataPhase1 fail-fast checks passed` within ~10s of bootstrap completing, before `COLLECTING: constituents`.

Composes with

  • PR feat: DataPhase1 postflight — producer-side consumer-contract checks #52 (postflight) — preflight + postflight together gate every input AND output of DataPhase1.
  • ROADMAP P2 (per-collector value-range guard) — middle layer between the two, catches in-flight bad data.
  • ROADMAP P3 (data contract registry) — eventual unification of all five callsites currently hand-rolling each contract.

🤖 Generated with Claude Code

Complements postflight (PR #52) which validates output contracts AFTER
writes. Preflight runs at the START of _run_phase1 before any collector
executes, catching the failure class where a credential drift, external-
API outage, or misconfiguration would otherwise burn ~55min of spot-EC2
time before failing on the 40th collector call.

Five fail-fast checks (cheapest-first ordering, total ~10s wall-time):

  1. Required env vars present + non-empty (POLYGON_API_KEY, FRED_API_KEY)
  2. S3 bucket HEAD + sentinel PUT/DELETE (validates IAM beyond list)
  3. ArcticDB connect + universe/macro libraries present
  4. FRED reachable + auth valid (DFF observation call)
  5. polygon.io reachable + auth valid (reference-data call)

Failure semantics match postflight: PreflightError → results["status"]
= "preflight_failed" → SystemExit(1) → SSM → SF HandleFailure →
alpha-engine-saturday-sf-failed alarm. Single named failure surface,
same blast radius as postflight (one alarm, not three downstream).

Skipped on --only single-collector runs (avoids preflight overhead for
local debug invocations like `python weekly_collector.py --only macro`).
Skipped on --phase 2 (Lambda has different dependency surface; gets its
own preflight when needed).

Tests: 24 new unit tests covering each check + end-to-end run() ordering
+ short-circuit on first failure. Full data-module suite: 84 passed.

ROADMAP: adds P2 (per-collector value-range outlier guard) and P3 (data
contract registry / Pydantic schema-first validation) as the natural
follow-ups for pushing validation further upstream/centralizing.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@cipher813 cipher813 merged commit dd18e27 into main Apr 17, 2026
1 check passed
@cipher813 cipher813 deleted the feat/dataphase1-preflight branch April 17, 2026 20:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant