Skip to main content

Draft matrix

The draft matrix selects an ideal remaining roster, then chooses the next pick from that selection. Use this page to understand positional needs, candidate order and clock-limited publication.

Which players and capacity are available?​

InputRule
Pick eventsRedis draft_picks:{leagueId} consumer group
IdentityResolve ESPN IDs through the player crosswalk; persist picks
PoolRequested season/week projections, week 1 by default
ExclusionAlready in draft_picks; not post-draft roster ownership
VORPRecompute coefficient, structural baselines and scarcity over the undrafted pool
CapacityConfigured starters plus BE; exclude IR
Missing BE settingTotal roster-size fallback 16
FLEXDefault RB/WR/TE shares, largest-remainder rounding
BenchSame RB/WR/TE shares
starting_need[position] = max(0, positional_slots + FLEX_share − drafted_by_us)
position_cap[position] = max(0, positional_slots + FLEX_share + bench_share − drafted_by_us)
target_picks = min(remaining_picks, pool_size,
Σ min(position_cap[position], available_count[position]))

How is the immediate target selected?​

StepRule
Remaining-roster ILPMaximize total scarcity-adjusted VORP with exactly target_picks and position upper caps
Required negative-value picksEquality forces picks even when all values are zero/negative
Empty pool, zero capacity or non-optimal solveNo recommendation
First ranking tierSelected players at positions still needing starters; descending VORP
Second ranking tierRemaining selected players; descending VORP
Candidate limitFive; no additional equal-score preference
Starter need comes first

A lower-valued needed starter can precede a higher-valued bench candidate. The immediate pick comes from the selected remaining-roster solution, not from the whole pool's highest score.

When does the listener recompute?​

EventBehavior
StartupSeed VORP lookup; recover this consumer's unacknowledged backlog
Opponent pickRecompute when our turn is next under the known snake order
Our confirmed pickRecord whether it matched the attempted target
New filled pickCancel stale pending publisher
Draft completeStop listener
Processed Stream eventAcknowledge after processing

The Redis board records recommendation, candidates, VORP lookup and listener/timer evidence.

What limits auto-publication?​

Setting or gateDefault behavior
Hold delay8 seconds
Pick clock90 seconds, measured from upstream Stream event
Safety margin5 seconds
Minimum auto-publish window10 seconds; clamp delay to available window
Pause/autodraft/modeGate the publisher
Transient failureRetry every 2 seconds within the clock
Three consecutive failed publicationsTrip auto-publish circuit breaker
Next pick cycleMay re-enable circuit-breaker disable; preserve manual disable
Confirmed ESPN rejectionAdvance to next precomputed candidate after readback
Do not treat uncertainty as rejection

Backlog processing does not restart the clock. A recommendation, queued target and landed ESPN pick are separate evidence; uncertainty does not authorize choosing another player.

How do the listener and room connector run?​

Both run through the job launcher as class: service catalog jobs. The draft endpoints request and cancel those runs; they never create Kubernetes Jobs themselves.

EndpointRun
POST /v1/draft/startdraft-listener or practice-draft-listener; with with_publisher, also draft-connector
POST /v1/draft/practice/sync-jobpractice-draft-connector for the room URL
POST /v1/draft/stop, DELETE /v1/draft/practice/sync-jobCancel the runs, wait for their pods, then clear Redis

Service runs don't count toward or wait on the launcher's pod cap, and their deadline is capped by max_service_deadline instead of max_deadline. The draft clock and mode reach the listener as env vars through the catalog's param_env.

A practice run is retired automatically once the connector's draft:{league_id}:health heartbeat has been gone for longer than the job's grace: the watcher records it as timeout with reason unhealthy. Live runs have no health key, so only their deadline or /stop ends them.

Listener CLI arguments

The launcher normally starts the listener. For a direct invocation, IDs must name the intended draft.

ArgumentRequirement
--league-idRequired
--team-idRequired
--seasonRequired
--weekOptional; default 1
--auto-draft-delay-secondsOptional