Season Governor
import { seasonGovernor } from 'tods-competition-factory';
The seasonGovernor answers questions about a CODES Season: whether it is well formed, its standings, who
advances out of a period and who moves between tiers when a period closes. A season references competitions across
tournament records and never contains them, so every method here is pure. The caller passes the season and the
in-context matchUps it has already selected from the referenced records; the factory loads nothing and stores
nothing. Whichever service declares a season stores it.
For the model itself (Series, Season, tiers, periods, placements, advancements and movement rules) and worked
examples, see Seasons. Season tables are ordered by the same standings engine as round-robin
groups: see Standings.
Every method returns the usual { success } or { error }, plus the fields listed below.
validateSeason
Structural validation of a Season: identities, the tier lattice, the periods and what they reference, placements and
advancements. Every problem is reported, not only the first.
{
season: Season;
checkPolicies?: boolean; // default true: also check the season's and each tier's tally policy
}
Returns: { valid, errors? }. On an invalid season, error is set and context.errors lists every problem.
It cannot check that a CompetitionRef resolves to a record that exists, since the factory holds no store.
getSeasonStandings reports a reference no matchUp answered.
getSeasonStandings
Standings per tier, derived from the results of the competitions the season's periods reference.
{
season: Season;
matchUps: HydratedMatchUp[]; // in-context, from every referenced record
periodId?: string; // one period; otherwise every period with includeInStandings
tierId?: string;
getSubjectId?: (participant) => string | undefined; // participant => durable subject id
orderBy?: (keyof SeasonStandingsTally)[]; // rank flat by these fields, higher first
tallyPolicy?: RoundRobinTallyPolicy; // overrides the season's and tiers' policies
purpose?: string; // STANDINGS_PURPOSE_*: a policy's directives may apply only for some purposes
externalValues?: Record<string, Record<string, number>>; // read by `external` tally directives
combine?: boolean; // add a table over each parent tier's own and descendants' matchUps
groupings?: Record<string, Record<string, string>>; // by name, then subjectId: a group key
groupRanks?: Record<string, Record<string, number>>; // by name, then subjectId: a place in its group's own table
participantSets?: Record<string, string[]>; // by key: subjectIds, read by `recordVsSet`
}
Returns:
standings: tables keyed bytierId, ranked.provisional: keyed bytierId, true while any referenced matchUp in the tier has no result.unanswered: references that no matchUp answered (a missing, unpublished or unselected competition).unmapped: participants no subject id could be resolved for.unplaced: subjects who played in a tier the period's placements do not put them in.
Nothing is dropped silently: each of those is reported rather than shrinking a table. By default a TEAM is identified by
its participantId and an individual by person.personId. A pair, or a team whose participantId is not stable across
records, needs getSubjectId. See Seasons → getSeasonStandings for
ordering and tie rules.
getSeasonAdvancement
Who advances out of a period into a later competition of the same season (local league to area playoff, area to sectionals). Applies each declared advancement to its from-period's standings. It proposes and records nothing; the caller places the advancing subjects.
{
season: Season;
matchUps: HydratedMatchUp[]; // in-context
advancementId?: string; // one declared advancement; otherwise every one the season declares
getSubjectId?: (participant) => string | undefined;
orderBy?: (keyof SeasonStandingsTally)[];
tallyPolicy?: RoundRobinTallyPolicy;
}
Returns: { outcomes }, one per advancement: { advancement, berths, advancing, tiedAtCut? }. advancing lists the
subjects who advance, best first. Subjects level on rank across the cut are not chosen between: they are returned in
tiedAtCut for the season's tie-break rules to decide.
getSeasonMovement
Who moves up, down or stays at the close of a period, under the season's declared movementRules. It proposes and
records nothing.
{
season: Season;
periodId: string; // the period whose close the movement is computed for
matchUps: HydratedMatchUp[]; // in-context
getSubjectId?: (participant) => string | undefined;
orderBy?: (keyof SeasonStandingsTally)[];
tallyPolicy?: RoundRobinTallyPolicy;
}
Returns: { proposals, tiedAtCut? }. Every subject in a tier's standings gets a proposal, HELD included, except
subjects level on rank across a cut: those are returned in tiedAtCut and decided by an operator or the season's rules.
planNextPeriod
Turns accepted movement into the next period's placements. It returns the placements and never writes them into the season.
{
season: Season;
periodId: string; // the period the movement was computed for
movements: SeasonMovementProposal[]; // usually getSeasonMovement(...).proposals
tiedAtCut?: SeasonMovementTie[]; // the ties getSeasonMovement left undecided
overrides?: SeasonMovementOverride[]; // operator decisions; the last one given for a subject wins
}
Returns: { nextPeriodId?, placements, revisions }.
nextPeriodId: absent when the next placements open a new season.revisions: every proposal an override changed and every tie an override settled, so a decision that departs from the declared rule stays visible.
A tied subject without an override is an error, not a guess.