Schedule order and refresh horizon
Use this page to understand the dependency order of the Tuesday jobs and what the daily projection/VORP refresh does when a stage fails. For triage, start at Job alerts.
Why do Tuesday jobs run in this order?
The launcher's tuesday-weekly chain (base/launcher/catalog.yaml) starts at 16:00 America/Chicago each regular-season Tuesday. Each step starts when its parent ends, so a slow step delays the rest instead of overlapping them. The generated schedule inventory draws the chain from the catalog.
| Edge | Behavior |
|---|---|
success | Data steps. The step runs only if its parent succeeded; otherwise it's skipped (dependency_failed), and so is every success step after it. |
finish | The refresh and the acting steps. The step runs once its parent ends, whatever its status, as the CronJobs did. A failed ingestion still refreshes projections and still sets the lineup. |
latest | The old CronJob times stay as upper bounds: lineup, waivers and rumor actions start by then even if their parent is still running. |
Each step keeps its old CronJob's deadline and retries, except rumor-action-trigger: its 15-minute deadline keeps a dead run's hold (deadline plus the watcher's 10-minute orphan grace) under the 30-minute wait of an event run queued behind it. The chain ends after 8 hours (max_duration), skipping any step that hasn't started. On Tuesday, the refresh's own 18:00 slot and rumor actions' 21:45 slot are skipped (chain_step) while the chain covers them. If the chain skipped the refresh, the 18:00 slot still runs it.
| Job | Placement reason |
|---|---|
sync-league first | Refreshes league_rosters before metrics and that day's decisions. It's the only scheduled place rosters refresh after a draft, trade or waiver. |
espn-ownership-sync | Takes ESPN's current-only ownership snapshot for the upcoming week. It's also a standalone daily job at 17:45, so each day's 18:00 refresh sees same-day ownership. In the chain it waits for sync-league and the refresh waits for it, both on finish: a failed ESPN fetch blocks nothing. |
| Score sync | Mirrors ESPN player actuals only into weekly_stats rows the ingestor has created, so it follows the ingestor. |
| Friday 10:00 reconciliation | The sync-actual-scores job's own schedule. Stores any week Tuesday couldn't (stats not yet official, a postponed game) plus ESPN stat corrections, before Friday's trade jobs: an hour of catch_up plus both attempts ends by 12:00. The trade context's opponent strength reads these stored scores. |
| Daily 07:00 trade candidates | Follows the previous evening's 18:00 projection/VORP rebuild and the most recent weekly metrics ingestion. |
| Wednesday/Friday 12:30 trade candidates | Refreshes stored candidates after Friday's 10:00 score reconciliation and before the 13:00 scan. |
| Wednesday/Friday 13:00 trade scan | Follows the previous evening's projection/VORP rebuild and the 12:30 candidate run. |
| Daily refresher and rumor actions | Also run at 18:00 and 21:45 on other days. Rumor actions also run after each digest, on rumor.signal_created, and the chain step waits for such a run still in flight. |
Trade-candidate rollout and verification
Deploy a core API image containing the trade-candidate module and migrations first. Its startup run_migrations() must create trade_candidate_runs and trade_candidates before trade-candidates runs. The job uses CORE_IMAGE, the digest the API deployment runs.
trade-candidates has two schedules: daily at 07:00 and Wednesday/Friday at 12:30, both America/Chicago across DST. It runs python -m src.jobs.trade_candidates, resolving the upcoming week from the configured season without a fixed week argument. The daily slot uses the previous evening's refresh; there is no morning metrics refresh.
Both slots share one job, so overlap: forbid covers them, and each run has a 25-minute deadline. There are no automatic retries, so the league-wide scoring is never replayed near a scan. The 12:30 slot allows two minutes of start delay, including time queued behind the pod cap, which leaves three minutes of headroom before 13:00. The 07:00 slot allows an hour, since nothing depends on its exact start. A slot that can't start in time ends skipped (expired). Scheduling provides spacing, not a success dependency: a failed refresh or candidate run does not stop the scan.
After rollout, check the pod logs (kubectl logs -n default -l fantasy.job=trade-candidates --tail=200) and the trade-candidates row in run_log. Verify a fresh stored candidate run for the upcoming week lands before each scan. An unresolved week or unavailable trade context exits 1 and fires the launcher run-failed alert; offseason exits successfully without writing candidates. That alert doesn't guarantee readiness by 13:00.
Ingestion timing
The chain starts at 21:00Z during daylight saving time and 22:00Z during standard time. The later slot gives publication headroom after Monday-night games.
| Evidence (2026-10-06) | Timestamp |
|---|---|
| nflverse current-season pbp assets updated | 15:53Z |
| nflverse schedules assets updated | 19:47–19:48Z |
Release APIs expose only current asset timestamps. Four Tuesdays of upstream pbp workflow history are supporting timing evidence, not a guarantee that each week's data is complete.
Ingestion limits
There is no second ingestion window. A successful partial ingestion doesn't trigger an automatic retry, and a later correction needs another VORP rebuild before dependent decisions.
- The roster sync is the chain's first step, so it finishes before metrics and that day's scheduled decisions. No early-Tuesday scheduled consumer requires it.
- Inspect ingestion counts and refresher logs before trusting a run's data.
- The launcher's run-failed alert doesn't detect a successful partial ingestion.
Projection and VORP refresh horizon
The refresh (projections-refresh, daily at 18:00 America/Chicago and in Tuesday's chain) resolves the target week W once. For each week from W through min(W+3, 18) it runs sync_projections → sync_kicker_dst → vorp_matrix, and it always finishes W before future weeks. Every command receives the same configured season and its own week.
| Case | Behavior |
|---|---|
| Target above week 18 | Offseason no-op. |
| Target below week 1 | Fails. |
| Per-week budget | Shared 600-second subprocess budget per week. Four weeks total 2400 seconds. |
| Deadline | Stays one hour, which also bounds Pending time and leaves headroom for startup and scheduling. |
| Resources | Existing CPU/memory requests and limits are unchanged. Work is sequential, so four weeks increase runtime without multiplying peak demand. |
| Failure in W | Stops the run immediately. |
| Failure in a future week | Skips that week's remaining stages but allows the other weeks to refresh. |
| Any failed week | The run fails after processing finishes, so the launcher's run-failed alert also reports an incomplete horizon. |
| Retries | max_attempts: 1 prevents an automatic whole-run replay. Ingestion's internal retries remain. |
In the chain, lineup waits for the refresh to end, up to 19:15. Completed W writes remain committed and usable even when the run fails later. Steps commit independently, so a failed week can retain partial writes.
To recover, investigate the failed stage and let the next daily run refresh the horizon.
What to read in the logs and dashboard
- Logs include season, week, stage, elapsed time and a
Refresh summarywithcompleted_weeksandfailed_weeks. - A failed horizon ends the run
failure, even when W completed. - Each stage is a child run of the refresh in
run_log, so its status shows which stage failed. The run's status covers the whole horizon, not individual-week readiness.
Future-week data
Future-week rows feed two consumers when populated: the lineup optimizer's target-week source (when rostered non-K/D-ST VORP exists) and the waiver service's exact-week pools. They are refreshed daily, but failed refreshes can leave older rows available.
- Empty upstream responses are successful no-ops. They aren't permission to copy another week's VORP or synthesize missing projections.
- Missing weekly rows stay unscored by the trade scorer.
- Sleeper ingestion doesn't remove previously written skill-player rows when a later response is empty.
- ESPN ingestion deletes matched K/D-ST target-week rows whose projections are no longer present.
- The refresher preserves all of these behaviors.
Verify a rollout
| Check | How |
|---|---|
| Supervisor (offline) | core's tests/test_draft_prep_refresh.py, for src/jobs/draft_prep_refresh.py |
Chain edges and latest times, roster-sync placement, DST coverage | python3 -m unittest tests.test_launcher_manifests tests.test_weekly_schedules |
| A scheduled run, read-only | Verify W completes before the Tuesday consumers, compare each week's ingestion/VORP counts and inspect the scorer's per-week coverage. |
| Provider availability | Verify nonempty Sleeper stats.pts_ppr and ESPN kona_player_info target-period projected stats, not player counts alone. |
Use read-only provider requests when investigating availability. Ingestion commands write to the database. Print counts and week identifiers, never session credentials.