Ladder Governor
Some methods on this page are candidates for removal from production engine exports at the 8.0.0 boundary. Their implementation references have moved: getLadderMovement, refreshLadderRatings. Existing 7.x routes remain available; final decisions and external-integrator confirmations are tracked in the transition index.
import { ladderGovernor } from 'tods-competition-factory';
The ladderGovernor drives a LADDER draw: seating participants, the challenge lifecycle, reported results and
their attestation, movement of the standing, lapses and ratings. A ladder is a continuous, challenge-driven competition
whose positionAssignments are the standing, with drawPosition read as rank (1 is the top).
For the model, the policy (POLICY_LADDER) and worked examples, see Ladder.
Every method resolves the ladder from drawId alone, so engine callers pass drawId (and structureId where a draw
has more than one structure). Called on the governor directly, a method takes the resolved drawDefinition and
tournamentRecord instead. Times are always supplied by the caller as ISO strings (issuedAt, respondedAt,
asOf, ...): no ladder method reads a clock, and expiry is derived from those instants rather than stored.
tournamentEngine.addLadderParticipant({ drawId, participantId, addedAt });
tournamentEngine.issueChallenge({ drawId, challengerParticipantId, defenderParticipantId, issuedAt });
const standing = tournamentEngine.getLadderStanding({ drawId });
Mutations
addLadderParticipant
Seats a participant on a ladder. The policy's placement decides where: BOTTOM (the default) or BY_RATING. An
unrated participant under BY_RATING goes to the bottom. Under RATING ordering the participant is appended and the
standing sorts them on the next read.
{
drawId: string;
participantId: string;
addedAt: string; // the scaleDate of any positions this shifts
structureId?: string;
}
Returns: { success, drawPosition }
removeLadderParticipant
Removes a participant by hand, closing everyone below up one rank: a member who has left, is injured for a season or has died. The only position change not driven by a challenge, and it never fires on its own.
{
drawId: string;
participantId: string;
removedAt: string;
reason?: string; // recorded: an override with no reason is indistinguishable from a mistake
structureId?: string;
}
Returns: { success, vacatedPosition }
issueChallenge
One participant challenges another, creating the CHALLENGED matchUp the ladder is played through. Eligibility is
enforced here: a downward challenge, a self-challenge, a participant not on the ladder, a challenge outside the policy's
range, and any drawType other than LADDER are refused.
{
drawId: string;
challengerParticipantId: string;
defenderParticipantId: string;
issuedAt: string;
structureId?: string;
}
Returns: { success, matchUpId }
acceptChallenge
The defender accepts: the challenge becomes an ordinary fixture to be played. An expired challenge is refused, judged
against respondedAt.
{
drawId: string;
matchUpId: string;
respondedAt: string;
}
declineChallenge
The defender declines. The decline is recorded first and the lapse evaluated after, so this decline counts; any consequence the policy says the defender has earned is applied here.
{
drawId: string;
matchUpId: string;
respondedAt: string;
}
Returns: { success, applied?, consequence?, lapseCount? }
→ Lapses
submitResult
A participant reports the score of a ladder match they played. The score lands on the matchUp, but its status becomes
AWAITING_RESULT, not COMPLETED: a reported score is not yet an agreed one, and the standing will not move on it.
{
drawId: string;
matchUpId: string;
participantId: string; // who reports
submittedAt: string;
outcome: { winningSide: 1 | 2; score?: any };
}
confirmResult
The other participant, or an operator, agrees the reported score. Only now does the matchUp become COMPLETED and
the standing become movable. The policy's resultValidation (PEER, OPERATOR or EITHER) decides whose
confirmation counts.
{
drawId: string;
matchUpId: string;
confirmedAt: string;
participantId?: string; // a peer confirming
operator?: boolean; // an official confirming
}
disputeResult
A participant contests the reported score. A completed matchUp goes back to AWAITING_RESULT, and a disputed result
cannot move the standing.
{
drawId: string;
matchUpId: string;
participantId: string;
disputedAt: string;
reason?: string;
}
applyLadderMovement
Rearranges the standing after a challenge resolves, and records each changed rank as a dated scale item (the ladder's
history). The only place a RANK standing moves. Under RATING ordering it does nothing and says so, since the
standing is derived from ratings.
{
drawId: string;
appliedAt: string; // the scaleDate of the resulting standing
trigger: 'RESULT' | 'FORFEIT';
matchUpId?: string; // required for RESULT: the attested matchUp is the evidence
challengerParticipantId?: string; // required for FORFEIT
defenderParticipantId?: string; // required for FORFEIT
structureId?: string;
}
Returns: { success, moved?, ratingsUpdated? }
RESULT takes no caller opinion about the outcome: challenger, defender and winner come off the matchUp, and an
unattested or disputed result is refused.
refreshLadderRatings
Writes externally sourced ratings for the participants on a ladder. The factory does not fetch ratings: the caller
supplies the values. Participants absent from ratings are left as they were, since a partial refresh is normal.
{
drawId: string;
ratings: Record<string, number>; // { participantId: ratingValue }
refreshedAt: string; // becomes the values' scaleDate
}
Returns: { success, updated, skipped }
→ Ratings on a rating-ordered ladder
Queries
getLadderStanding
The standing, ordered by whichever mechanism the policy declares. Under RANK it is positionAssignments as stored;
under RATING it is derived from each participant's rating, in the direction ratingsParameters[ratingType].ascending
declares (WTN is lower-is-better, UTR higher-is-better). Nothing is mutated by asking.
{
drawId: string;
structureId?: string;
}
Returns: { position, participantId, ratingValue? }[]
getChallengeState
What has become of a challenge at an explicit instant: PENDING, EXPIRED, ACCEPTED or DECLINED. asOf is
required because expiry is derived from issuedAt and the policy's acceptanceDays, never stored.
{
drawId: string;
matchUpId: string;
asOf: string;
}
Returns: { state, expiresAt? }
→ Expiry is derived, never stored
getResultAttestation
Whether a submitted score has become a result, and on whose word.
{
drawId: string;
matchUpId: string;
}
Returns: { attested, disputed, submittedBy?, confirmedBy?, reason? }
getLapses
What a participant has failed to do as a defender (declined, expired or unplayed challenges), counted at an instant.
{
drawId: string;
participantId: string;
asOf: string;
structureId?: string;
}
Returns: { lapses, count, allowance, exceeded, consequence?, dropPositions? }
getLadderPolicy
The ladder policy in force, with defaults filled in. Resolved through the ordinary policy hierarchy (structure, draw, event, tournament); a ladder with no policy attached runs on the defaults.
{
drawId: string;
}
Returns: the LadderPolicy
→ Policy
getLadderOrdering
The ordering in force: RANK (the default) or RATING. Ask this rather than reading policy.ordering or assuming
positionAssignments is the source of truth.
{
drawId: string;
}
getLadderMovement
The movement rule under RANK ordering: SWAP (the default) or INSERTION.
{
drawId: string;
}
→ SWAP and INSERTION are different competitions
isChallengeInRange
Whether the participant at challengerPosition may challenge the one at defenderPosition. Upward only, and bounded
by the policy's challengeRange (a number of places, or ANY).
{
drawId: string;
challengerPosition: number;
defenderPosition: number;
}
Returns: boolean