Skip to main content

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.

EdgeBehavior
successData steps. The step runs only if its parent succeeded; otherwise it's skipped (dependency_failed), and so is every success step after it.
finishThe 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.
latestThe 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.

JobPlacement reason
sync-league firstRefreshes 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-syncTakes 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 syncMirrors ESPN player actuals only into weekly_stats rows the ingestor has created, so it follows the ingestor.
Friday 10:00 reconciliationThe 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 candidatesFollows the previous evening's 18:00 projection/VORP rebuild and the most recent weekly metrics ingestion.
Wednesday/Friday 12:30 trade candidatesRefreshes stored candidates after Friday's 10:00 score reconciliation and before the 13:00 scan.
Wednesday/Friday 13:00 trade scanFollows the previous evening's projection/VORP rebuild and the 12:30 candidate run.
Daily refresher and rumor actionsAlso 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 updated15:53Z
nflverse schedules assets updated19: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​

A partial ingestion isn't retried

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.

CaseBehavior
Target above week 18Offseason no-op.
Target below week 1Fails.
Per-week budgetShared 600-second subprocess budget per week. Four weeks total 2400 seconds.
DeadlineStays one hour, which also bounds Pending time and leaves headroom for startup and scheduling.
ResourcesExisting CPU/memory requests and limits are unchanged. Work is sequential, so four weeks increase runtime without multiplying peak demand.
Failure in WStops the run immediately.
Failure in a future weekSkips that week's remaining stages but allows the other weeks to refresh.
Any failed weekThe run fails after processing finishes, so the launcher's run-failed alert also reports an incomplete horizon.
Retriesmax_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 summary with completed_weeks and failed_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​

CheckHow
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 coveragepython3 -m unittest tests.test_launcher_manifests tests.test_weekly_schedules
A scheduled run, read-onlyVerify W completes before the Tuesday consumers, compare each week's ingestion/VORP counts and inspect the scorer's per-week coverage.
Provider availabilityVerify nonempty Sleeper stats.pts_ppr and ESPN kona_player_info target-period projected stats, not player counts alone.
Read-only provider requests

Use read-only provider requests when investigating availability. Ingestion commands write to the database. Print counts and week identifiers, never session credentials.