Skip to main content

Round Robin Tally Policy

The Round Robin Tally Policy controls how participants are ranked within round robin groups, including tiebreaking procedures, head-to-head calculations, and group order determination.

The ordering itself is the standings engine's, shared with season tables and the competition leaderboard: see Standings, including which sports' rules it can express.


CODES schema

This policy's shape is the RoundRobinTallyPolicy definition in tournament.schema.json (under PolicyDefinitions), open by decision, like its TypeScript type: it lists the members the tally reads, and validateTallyPolicy checks their values where a policy is saved. Policies are stored in each element's first-class appliedPolicies attribute (the appliedPolicies extension on older records).

Overview​

Round robin groups require sophisticated tiebreaking rules to determine final standings when participants have equal records. The tally policy provides:

  • Flexible tiebreaking through configurable tallyDirectives
  • Head-to-head comparisons between tied participants
  • Percentage calculations (matches, sets, games, points)
  • Statistical tracking (wins, losses, defaults, retirements)
  • Threshold-based rules via maxParticipants attribute
  • Composite scoring through GEMscore
  • Group totals for percentage calculations

Default Behavior​

When no custom tally policy is specified, the system applies a comprehensive default tiebreaking procedure that follows widely-accepted tournament standards.

Standard Tiebreaking Sequence​

The default tally policy implements the following hierarchy:

  1. Primary criterion: Participants grouped by matchUpsWon
  2. Head-to-head comparison: When participants are tied, their direct results against each other are evaluated
  3. Percentage-based tiebreakers: Match, set, game, and point percentages (in order)
  4. Scope escalation: First evaluate all group matches, then recalculate among tied participants only

Algorithm Overview​

The tiebreaking algorithm works as follows:

  1. Group participants by the primary attribute (default: matchUpsWon)
  2. For each tied group:
    • If only 1 participant: resolved (no tie)
    • If exactly 2 participants: compare head-to-head record
    • If 3+ participants: apply tallyDirectives sequence
  3. Apply directives until ties are broken or all directives exhausted
  4. Recursive separation: As each directive separates participants, smaller groups are formed and process repeats

Head-to-Head Logic​

When 2 participants are tied:

  • Their win-loss record across every meeting
  • More wins over the other places higher
  • If the record is level, or they didn't play: move to next directive

When 3+ participants are tied:

  • Calculate statistics among only the tied participants
  • Look for clear separation
  • If circular tie (A>B>C>A): move to next directive

Head-to-head is applied BEFORE tallyDirectives unless explicitly disabled via headToHead: { disabled: true }.

Head-to-head reads the record between the two participants across every meeting: the one with more wins over the other is placed first. A level record (1-1 in a double round robin) or no meeting does not separate them, and the tallyDirectives decide. The order in which meetings are listed never matters. (Before the standings engine, any one victory decided, so a pair that split two meetings was decided by whichever meeting was found first.)

A directive's disableHeadToHead (skip head-to-head when sorting the sets that directive splits off) takes effect only when the policy also declares a headToHead object.


Implementation Details​

Calculated Attributes​

For each participant, the following attributes are calculated from match results:

Match-level:

  • matchUpsWon - Total matches won
  • matchUpsLost - Total matches lost
  • matchUpsCancelled - Matches that were cancelled/abandoned
  • matchUpsPct - Win percentage: matchUpsWon / (matchUpsWon + matchUpsLost)

Set-level:

  • setsWon - Total sets won
  • setsLost - Total sets lost
  • setsPct - Win percentage: setsWon / (setsWon + setsLost)

Game-level:

  • gamesWon - Total games won
  • gamesLost - Total games lost
  • gamesPct - Win percentage: gamesWon / (gamesWon + gamesLost)

Point-level:

  • pointsWon - Total points won
  • pointsLost - Total points lost
  • pointsPct - Win percentage: pointsWon / (pointsWon + pointsLost)

Incomplete matches:

  • defaults - Number of times participant defaulted
  • walkovers - Number of times participant walked over
  • retirements - Number of times participant retired
  • allDefaults - Total of all exit statuses (defaults + walkovers + retirements)

TEAM events (tieMatchUps):

  • tieMatchUpsWon - Individual matches won
  • tieMatchUpsLost - Individual matches lost
  • tieSinglesWon - Singles matches won
  • tieSinglesLost - Singles matches lost
  • tieDoublesWon - Doubles matches won
  • tieDoublesLost - Doubles matches lost

Final result:

  • groupOrder - Final placement (1-based, lower is better)
  • GEMscore - Composite score (if configured)

Calculation Scoping​

Global scope (idsFilter: false):

// Calculate from ALL group matches
matchUpsPct = matchUpsWon / (matchUpsWon + matchUpsLost);

Filtered scope (idsFilter: true):

// Calculate from ONLY matches among tied participants
// Example: If A, B, C are tied, only count A-B, A-C, B-C matches
matchUpsPct = matchUpsWon_amongTied / (matchUpsWon_amongTied + matchUpsLost_amongTied);

Group Totals​

Participant-based (groupTotals: false - default):

gamesPct = gamesWon / (gamesWon + gamesLost);
// Each participant's denominator is their own games
// Sum of all gamesPct can exceed 1.0

Group-based (groupTotals: true):

totalGroupGames = sum of all gamesWon by all participants
gamesPct = gamesWon / totalGroupGames
// Sum of all gamesPct = 1.0

Directive Processing​

Directives are applied sequentially:

for (const directive of tallyDirectives) {
// 1. Check maxParticipants threshold
if (directive.maxParticipants && tiedCount > directive.maxParticipants) {
continue; // Skip this directive
}

// 2. Calculate attribute (with idsFilter if specified)
const values = calculateAttribute(directive, tiedParticipants);

// 3. Sort (reversed if specified)
const sorted = directive.reversed
? sortAscending(values) // Least to greatest
: sortDescending(values); // Greatest to least

// 4. Separate into groups by value
const groups = groupByValue(sorted);

// 5. Recursively process each group
groups.forEach((group) => {
if (group.length > 1) {
// Still tied, continue with next directive
} else {
// Resolved! Assign groupOrder
}
});
}

Precision in Percentages​

Percentages are calculated with configurable precision:

const precision = Math.pow(10, tallyPolicy?.precision || 3);
// precision: 3 → 1000 → 0.667
// precision: 5 → 100000 → 0.66667

matchUpsPct = Math.round((matchUpsWon / matchUpsTotal) * precision) / precision;

Policy Structure​

type RoundRobinTallyPolicy = {
policyName?: string;

// Initial grouping attribute
groupOrderKey?:
| 'matchUpsWon'
| 'tieMatchUpsWon'
| 'tieSinglesWon'
| 'tieDoublesWon'
| 'pointsWon'
| 'gamesWon'
| 'setsWon'
| 'gamesPct'
| 'setsPct'
| 'pointsPct'
| 'matchUpsPct';

// Tiebreaking sequence
tallyDirectives?: Array<{
attribute: string; // Which statistic to compare
idsFilter?: boolean; // Compare only tied participants
reversed?: boolean; // Least-to-greatest instead of greatest-to-least
maxParticipants?: number; // Only apply if # tied <= threshold
groupTotals?: boolean; // Use group totals for percentages
disableHeadToHead?: boolean; // Skip head-to-head for this directive
}>;

// Head-to-head configuration
headToHead?: {
disabled?: boolean; // Skip head-to-head entirely
};

// Percentage calculation options
groupTotalGamesPlayed?: boolean; // Use all group games for gamesPct
groupTotalSetsPlayed?: boolean; // Use all group sets for setsPct
precision?: number; // Decimal precision (default: 3)

// Disqualification rules
disqualifyDefaults?: boolean; // Push defaulting participants to bottom
disqualifyWalkovers?: boolean; // Push walkover participants to bottom

// Exclude specific match statuses
excludeMatchUpStatuses?: string[]; // e.g., ['ABANDONED', 'INCOMPLETE']

// Credit for incomplete matches
setsCreditForDefaults?: boolean;
setsCreditForWalkovers?: boolean;
setsCreditForRetirements?: boolean;
gamesCreditForDefaults?: boolean;
gamesCreditForWalkovers?: boolean;
gamesCreditForRetirements?: boolean;
gamesCreditForTiebreakSets?: boolean; // Default: true

// Composite score attributes
GEMscore?: string[]; // Attributes to include in GEMscore calculation
};

Built-in Policies​

Default Tally Policy​

Standard tiebreaking procedure:

import { fixtures } from 'tods-competition-factory';
const { POLICY_ROUND_ROBIN_TALLY_DEFAULT } = fixtures.policies;

const policy = POLICY_ROUND_ROBIN_TALLY_DEFAULT[POLICY_TYPE_ROUND_ROBIN_TALLY];
// {
// policyName: 'Default Round Robin Tally',
// groupOrderKey: 'matchUpsWon',
// tallyDirectives: [
// { attribute: 'matchUpsPct', idsFilter: false },
// { attribute: 'allDefaults', reversed: true, idsFilter: false },
// { attribute: 'defaults', reversed: true, idsFilter: false },
// { attribute: 'walkovers', reversed: true, idsFilter: false },
// { attribute: 'retirements', reversed: true, idsFilter: false },
// { attribute: 'setsPct', idsFilter: false },
// { attribute: 'gamesPct', idsFilter: false },
// { attribute: 'pointsPct', idsFilter: false },
// { attribute: 'matchUpsPct', idsFilter: true },
// { attribute: 'setsPct', idsFilter: true },
// { attribute: 'gamesPct', idsFilter: true },
// { attribute: 'pointsPct', idsFilter: true },
// ],
// }

Tiebreaking sequence:

  1. Match win percentage (all group matches)
  2. Fewest all defaults (any exit status)
  3. Fewest defaults
  4. Fewest walkovers
  5. Fewest retirements
  6. Set win percentage (all group matches)
  7. Game win percentage (all group matches)
  8. Point win percentage (all group matches)
  9. Match win percentage (among tied teams only)
  10. Set win percentage (among tied teams only)
  11. Game win percentage (among tied teams only)
  12. Point win percentage (among tied teams only)

JTT Tally Policy​

Junior Team Tennis format:

import { fixtures } from 'tods-competition-factory';
const { POLICY_ROUND_ROBIN_TALLY_JTT } = fixtures.policies;

// {
// policyName: 'JTT Round Robin Tally',
// groupOrderKey: 'gamesWon',
// tallyDirectives: [
// { attribute: 'matchUpsPct', idsFilter: true },
// { attribute: 'gamesWon', idsFilter: false },
// { attribute: 'matchUpsWon', idsFilter: false },
// { attribute: 'tieMatchUpsWon', idsFilter: false },
// { attribute: 'setsWon', idsFilter: false },
// ],
// }

Key features:

  • Primary criterion: Most games won
  • Head-to-head first: matchUpsPct with idsFilter: true
  • Designed for team tennis where games won is primary metric

TOC Tally Policy​

Tournament of Champions format:

import { fixtures } from 'tods-competition-factory';
const { POLICY_ROUND_ROBIN_TALLY_TOC } = fixtures.policies;

// {
// policyName: 'TOC Round Robin Tally',
// groupOrderKey: 'matchUpsPct',
// tallyDirectives: [
// { attribute: 'matchUpsPct', idsFilter: true, maxParticipants: 2 },
// { attribute: 'gamesPct', idsFilter: false },
// { attribute: 'gamesWon', idsFilter: false },
// { attribute: 'gamesLost', idsFilter: false, reversed: true },
// ],
// }

Key features:

  • maxParticipants: 2 on head-to-head (only if 2 teams tied)
  • Games percentage for 3+ team ties
  • Fewest games lost as final tiebreaker

USTA League Championship Policy​

POLICY_ROUND_ROBIN_TALLY_USTA_LEAGUE: the USTA League championship tie procedure as copied into section regulations (USTA/Midwest Section 2026, Combo section M):

  • the most individual matches (lines) won (tieMatchUpsWon);
  • then the winner of the head-to-head match;
  • then the fewest sets lost, then the fewest games lost;
  • then the Midwest committee method: the fewest sets lost in the head-to-head match, then the fewest games lost in it, then a coin toss (terminal: 'LOT').

An individual default counts 6-0, 6-0 for the receiver, and a match tie-break counts as one set and one game. A section that varies the order needs its own policy.

FIBA Policy​

POLICY_ROUND_ROBIN_TALLY_FIBA: FIBA Official Basketball Rules 2026, Appendix D:

  • resultPoints: 2 for a win, 1 for a loss including by default, 0 for a loss by forfeit (a forfeit mapped to WALKOVER, a default to DEFAULTED);
  • level teams are separated by the games between them, then points difference and points scored in those games, then the same over all group games, then a draw (terminal: 'LOT');
  • onSplit: 'RESTART' (D.1.4).

The FIBA ranking step (national-team competitions) is an external value and is not applied.

Premier League Policy​

POLICY_ROUND_ROBIN_TALLY_PREMIER_LEAGUE: Premier League Handbook 2025/26, rules C.4 to C.7 and C.17:

  • resultPoints: 3 for a win, 1 for a draw; goals are each half's score (HAL2A-S:T45), so goal difference is gamesDiff and goals scored gamesWon;
  • clubs level on points are separated by goal difference, then goals scored (C.5, C.6); clubs still level share the place (C.7, terminal: 'SHARE');
  • C.17 applies only at the end of the season and only where the title, relegation or qualification depends on it: the points in the matches between the tied clubs, as a directive when: { purposes: ['ADVANCEMENT', 'MOVEMENT'], phase: 'FINAL' }. A season table asked for one of those purposes applies it; a caller deciding the title asks with ADVANCEMENT.

Not applied: C.17's away goals between the tied clubs (the factory records no home or away side) and its play-off, which is a match the organiser arranges.

MLS Policy​

POLICY_ROUND_ROBIN_TALLY_MLS: MLS 2026 Competition Guidelines, regular-season tiebreaking procedures:

  • resultPoints: 3 for a win, 1 for a tie;
  • level clubs are separated by total wins, goal differential, goals for, then head-to-head points and goal differential, then the fewest disciplinary points (an external value, disciplinaryPoints, fewer is better), then a coin toss or drawing of lots (terminal: 'LOT');
  • once a club is separated, the clubs still tied go through the procedure again (onSplit: 'EXTRACT_ONE').

The head-to-head steps are for a conference table (MLS applies them intraconference only); a table across both conferences (the Supporters' Shield) drops them. Not applied: the away and home goal steps, since the factory records no home or away side.

FIVB Policy​

POLICY_ROUND_ROBIN_TALLY_FIVB: FIVB Volleyball Nations League 2026 Competition Regulations, § 2.5:

  • teams are ranked on victories (matchUpsWon), then match points: 3 for a 3-0 or 3-1 win, 2 for a 3-2 win, 1 for a 2-3 loss, 0 for a 0-3 or 1-3 loss, and 0 for a forfeit (a forfeit mapped to WALKOVER, 3 to the winner);
  • then set ratio and points ratio (rally points are each set's tiebreak score, SET5-S:TB25-F:TB15; nothing lost ranks first);
  • then the matches among the tied teams only, on the same criteria (onSplit: 'CONTINUE');
  • then the FIVB World Ranking, an external value, worldRanking (lower is better).

The regulations name no step after the World Ranking.

Key Attributes​

groupOrderKey​

Purpose: Initial attribute to group participants by before applying tiebreakers.

Valid values:

  • 'matchUpsWon' (default)
  • 'tieMatchUpsWon' (for TEAM events)
  • 'tieSinglesWon' (for TEAM events)
  • 'tieDoublesWon' (for TEAM events)
  • 'pointsWon'
  • 'gamesWon'
  • 'setsWon'
  • 'gamesPct'
  • 'setsPct'
  • 'pointsPct'
  • 'matchUpsPct'

Example:

const policy = {
[POLICY_TYPE_ROUND_ROBIN_TALLY]: {
groupOrderKey: 'gamesWon', // Group by total games won
tallyDirectives: [{ attribute: 'gamesPct', idsFilter: false }],
},
};

tallyDirectives​

Purpose: Sequence of tiebreaking rules applied in order.

Structure:

{
attribute: string; // Statistic to compare
idsFilter?: boolean; // Scope to tied participants only
reversed?: boolean; // Reverse sort order (least-to-greatest)
maxParticipants?: number; // Threshold-based application
groupTotals?: boolean; // Use group totals for percentages
}

Directive attributes:

  • matchUpsPct - Match win percentage
  • setsPct - Set win percentage
  • gamesPct - Game win percentage
  • pointsPct - Point win percentage
  • matchUpsWon - Total matches won
  • setsWon - Total sets won
  • gamesWon - Total games won
  • pointsWon - Total points won
  • matchUpsLost - Total matches lost
  • setsLost - Total sets lost
  • gamesLost - Total games lost
  • pointsLost - Total points lost
  • defaults - Number of defaults
  • walkovers - Number of walkovers
  • retirements - Number of retirements
  • allDefaults - All exit statuses combined
  • tieMatchUpsWon - Individual matches won (TEAM events)
  • tieSinglesWon - Singles matches won (TEAM events)
  • tieDoublesWon - Doubles matches won (TEAM events)

See also: maxParticipants documentation for threshold-based tiebreaking


idsFilter​

Purpose: Scope calculations to only the tied participants.

When false (default):

  • Statistics calculated from ALL group matches
  • Example: gamesPct = gamesWon / (gamesWon + gamesLost) across entire group

When true:

  • Statistics calculated ONLY from matches among tied participants
  • Example: If A, B, C are tied, only count A-B, A-C, B-C matches
  • Used for head-to-head comparisons

Example:

tallyDirectives: [
// Stage 1: Overall group performance
{ attribute: 'gamesPct', idsFilter: false },

// Stage 2: Performance among tied teams only
{ attribute: 'gamesPct', idsFilter: true },
];

reversed​

Purpose: Reverse sort order from greatest-to-least to least-to-greatest.

Use cases:

  • Fewest losses
  • Fewest defaults/walkovers/retirements
  • Fewest penalty minutes
  • Any "lower is better" metric

Example:

tallyDirectives: [
{ attribute: 'gamesWon', reversed: false }, // Most games won
{ attribute: 'gamesLost', reversed: true }, // Fewest games lost
];

maxParticipants​

Purpose: Only apply directive when number of tied participants does not exceed threshold.

Common usage:

{
attribute: 'matchUpsPct',
idsFilter: true,
maxParticipants: 2 // Only if exactly 2 teams tied
}

Why this exists:

  • 2 teams: Direct head-to-head works (one beat the other)
  • 3+ teams: Circular ties possible (A>B>C>A)
  • Sports rules universally distinguish 2-team vs 3+-team ties

See: maxParticipants documentation for complete details and sports precedents


groupTotals​

Purpose: Use total group games/sets for percentage calculations instead of participant totals.

When false (default):

gamesPct = gamesWon / (gamesWon + gamesLost)
// Sum of all gamesPct can be > 1.0

When true:

gamesPct = gamesWon / (total games played by all participants)
// Sum of all gamesPct = 1.0

Example:

tallyDirectives: [
{
attribute: 'gamesPct',
idsFilter: false,
groupTotals: true, // Use total group games as denominator
},
];

Or set at top level:

{
groupTotalGamesPlayed: true, // All gamesPct calculations
groupTotalSetsPlayed: true, // All setsPct calculations
}

headToHead​

Purpose: Configure head-to-head tiebreaking behavior.

Default behavior:

  • When 2 participants tied: Compare their head-to-head record
  • When 3+ participants tied: Try to separate with head-to-head among all tied

Disable completely:

{
headToHead: { disabled: true },
tallyDirectives: [
// Head-to-head skipped, go straight to directives
{ attribute: 'gamesPct', idsFilter: false },
],
}

Note: Head-to-head happens BEFORE tallyDirectives. Disabling it forces all tiebreaking through directives.


Splits, gates and the final step​

These fields are read by the standings engine, which orders round-robin groups and season tables alike.

onSplit​

What happens when a directive splits a tied set.

  • 'RESTART' (default): every part goes back to the first directive. A pair split off by setsPct is settled by head-to-head next. FIBA, NBA, IIHF and FIDE work this way.
  • 'CONTINUE': every part continues with the next directive. A mini-league directive (idsFilter: true) is first re-applied to the residue it leaves, so a pair it splits off is settled by their own meeting before any overall measure is read.
  • 'EXTRACT_ONE': one participant is resolved per step, the leader of the top part, and everyone else (including the rest of the top part) goes back to the first directive. This is the NFL's procedure.

minParticipants​

The directive is passed over when fewer than this many participants are tied, as maxParticipants passes it over when more are. For example, aggregate measures for a three-way tie, head-to-head for two.

when​

{ purposes?: string[]; phase?: 'PROVISIONAL' | 'FINAL' } on a directive. purposes limits it to tables computed for those purposes: getSeasonStandings({ purpose }), with STANDINGS_PURPOSE_MOVEMENT passed by getSeasonMovement and STANDINGS_PURPOSE_ADVANCEMENT by getSeasonAdvancement. phase: 'FINAL' skips the directive while results are outstanding (a provisional order). A directive skipped by when is not reported.

headToHead directives (RECORD, SWEEP)​

Head-to-head may also be written as a directive, { attribute: 'headToHead', mode }:

  • 'RECORD' (the default reading): two tied participants, the one with more wins over the other.
  • 'SWEEP': any number tied. A participant who beat every other one is placed first, or else one who lost to every other one is placed last (the NFL's wild-card rule); everyone else goes back to the first directive. With no sweep, nothing splits.

external​

{ attribute: 'external', externalKey } reads values from outside the results: a curling Draw Shot Challenge, a ranking, fair-play points. They are passed by the caller as externalValues: { [externalKey]: { [participantId]: number } } to tallyParticipantResults, or keyed by subjectId to getSeasonStandings; the factory never fetches them. A participant without a value reads 0. Use reversed: true where lower is better (a draw-shot distance).

terminal​

What happens to a set no directive splits.

  • 'ADJUDICATE' (default): the set shares a place, and an organiser's sub-order (setSubOrder) may order it.
  • 'SHARE': the place is shared and stays shared, whatever a sub-order says.
  • 'LOT': a draw seeded by the structure (a group) or the season and tier (a season table). The same seed always draws the same order, and the report records the seed.
{
onSplit: 'CONTINUE',
terminal: 'LOT',
tallyDirectives: [
{ attribute: 'matchUpsPct', idsFilter: true },
{ attribute: 'gamesPct', minParticipants: 3 },
{ attribute: 'gamesWon', when: { purposes: ['MOVEMENT'], phase: 'FINAL' } },
],
}

Percentage Calculations​

precision​

Purpose: Control decimal precision for percentage calculations.

Default: 3 (1000)

Example:

{
precision: 5, // Results: 0.66667 instead of 0.667
}

Formula: Math.pow(10, precision)

  • precision: 3 → 1000 → 0.667
  • precision: 5 → 100000 → 0.66667
  • precision: 7 → 10000000 → 0.6666667

precision: 'EXACT'​

precision: 'EXACT' compares and stores percentages unrounded, so two percentages tie only when their fractions are equal. With a number (default 3), values equal after rounding to that many decimal places tie. Many rulebooks state this explicitly ("win percentage to three decimal places"), so it is a ranking rule, not only a display setting.

Zero denominators​

A percentage with nothing played is 0. For example, setsPct for a participant whose only result is a walkover. A ratio with nothing lost is unbounded: it ranks first when anything was won, and is 0 when nothing was won either. A directive can change that with zeroDivision (below).

Differences and ratios​

setsDiff, gamesDiff and pointsDiff (won minus lost) are stored with the other measures. setsRatio, gamesRatio and pointsRatio (won over lost) are computed only when ordering, never stored, because a ratio with nothing lost is unbounded and a stored tally must stay serialisable. Any of them may be the groupOrderKey or a directive attribute.

A ratio directive's zeroDivision decides what an unbeaten ratio means for that directive:

  • 'MAX' (default): it ranks first (FIVB's convention).
  • 'ZERO': it reads as 0.
  • 'SKIP': the directive is passed over for any tied set where it happens.

Strength of schedule (graph measures)​

buchholz, buchholzCut1, buchholzMedian and sonnebornBerger read the whole table, scoring each opponent by the policy's primary measure (its groupOrderKey), once per meeting:

  • buchholz: the sum of the opponents' scores.
  • buchholzCut1: the same without the lowest.
  • buchholzMedian: the same without the highest and the lowest.
  • sonnebornBerger: the scores of the opponents beaten, plus drawCredit (default 0.5) of the scores of those drawn with.

They are computed only when ordering and never stored. They may be directive attributes, but not the groupOrderKey (the primary measure scores the opponents), not scoped by idsFilter, and not a crossGroup measure. FIDE's convention for unplayed rounds (a virtual opponent) is not applied: only meetings that were played count.

Common opponents​

commonOpponents is the NFL's "won-lost-tied percentage in common games". Its value depends on who is tied: for the set being sorted, the common opponents are the participants every member of the set has met, and each member is scored by its win percentage over every meeting with them, a draw counting drawCredit (default 0.5). No member of the set is a common opponent of the others, so the meetings among the tied are not counted; head-to-head is a separate directive.

{ attribute: 'commonOpponents', minSample: 4 }

minSample (default 1) is the fewest meetings against common opponents each member needs. When any member of the set has fewer, the directive does not split that set and the next directive is tried; the report records { attribute: 'commonOpponents', skipped: 'minSample', participantIds }. The NFL requires four for a wild-card tie.

It is most useful where not everyone meets everyone, as in a season table; in a complete round robin, every participant outside the set is a common opponent.

Groupings: divisions, conferences and sets​

Divisions and conferences are supplied by the caller, like externalValues; the factory never fetches them. A season derives them instead: getSeasonStandings({ combine: true }) orders a parent tier's table over its divisions' matchUps with the grouping tier (see Seasons). Elsewhere they are passed to tallyParticipantResults (and the ordering core) by name:

tallyParticipantResults({
matchUps,
policyDefinitions,
// named groupings: participantId → group key
groupings: { division: { A: 'EAST', B: 'EAST', C: 'WEST' } },
// each participant's place in its own group's table, decided by that group's own policy (1 leads it)
groupRanks: { division: { B: 1, A: 2, C: 1 } },
// sets that records are read against
participantSets: { eligible: ['A', 'C'] },
});

preReduce: { groupBy } (the NFL wild card's first step): in a tied set where two or more members share a group, only each group's best-ranked member competes for the next place. The candidates are ordered by the directives, the first one placed is taken, and everyone else, its group-mates included, goes back through the same procedure. A team therefore cannot be placed ahead of a tied team that leads it in its own division, but it is not held back behind the other divisions' leaders either. When the top candidates stay tied, they keep their shared place and the rest follow. A participant with no group, or with no rank, is not reduced. The report records each step as { attribute: 'preReduce', groupBy, candidates, placed }.

{ preReduce: { groupBy: 'division' }, onSplit: 'EXTRACT_ONE', tallyDirectives: [ /* the wild-card steps */ ] }

Three more directive measures read the groupings:

  • groupLeader (groupBy): 1 for a participant ranked first in its group, else 0. The NBA's "division winner".
  • recordVsGroup (groupBy): the record against the members of its own group, the division or conference win percentage. It splits only a set whose members all share a group; otherwise it is passed over for that set and the report records skipped: 'groupBy' (NBA: "only if in the same division").
  • recordVsSet (setKey): the record against the members of participantSets[setKey], such as the NBA's postseason-eligible teams. The caller defines the set; the NBA's definition depends on the standings themselves.

A record is a win percentage with a draw counting drawCredit, like commonOpponents. A member of the set with no meeting to count passes the directive over for that set (skipped: 'noMeetings').

Tied-set measures​

commonOpponents, groupLeader, recordVsGroup and recordVsSet are computed only when ordering and never stored. They may be directive attributes, but not the groupOrderKey, not scoped by idsFilter (each reads the whole table), and not a crossGroup measure.

resultPoints​

Classification points by result, for sports whose tables award points per result rather than counting wins: FIBA's 2 for a win, 1 for a played or defaulted loss and 0 for a forfeit, or volleyball's 3 for a 3-0 or 3-1 win and 2 and 1 for a 3-2. The rules are matched in order, and the first that matches decides.

{
groupOrderKey: 'classificationPoints',
resultPoints: {
rules: [
{ id: 'forfeit', matchUpStatuses: ['WALKOVER'], winner: 3, loser: 0 },
{ id: 'five-sets', loserSetsWon: [2], winner: 2, loser: 1 },
{ id: 'win', winner: 3, loser: 0 },
{ id: 'draw', isDrawn: true, points: 1 },
],
},
}
  • A decided rule may name matchUpStatuses and loserSetsWon (the sets the loser won), and awards winner and loser points. A drawn rule awards points to both sides.
  • Statuses are mapped by the rules, never inferred: whether a sport's "forfeit" is a WALKOVER is the policy author's decision.
  • A decided rule may also name loserMarginAtMost: the loser lost by no more than that many, the sides' scores summed over every set and then subtracted (rugby's points, recorded as each half's score in HAL2A-S:T40).
  • A rule with bonus: true adds to the deciding rule's award instead of deciding. Every bonus rule that matches adds its points, wherever it is listed; a result that no deciding rule matches earns no bonus either, and the rules must include at least one rule that is not a bonus. A bonus that awards a side nothing is not listed among its contributions. Rugby's losing bonus (the PREM league table regulations, read 2026-11-04: 4 for a win, 2 for a draw, 1 to a team that loses a match by 7 points or less):
{
groupOrderKey: 'classificationPoints',
resultPoints: {
rules: [
{ id: 'win', winner: 4, loser: 0 },
{ id: 'draw', isDrawn: true, points: 2 },
{ id: 'losingBonus', bonus: true, loserMarginAtMost: 7, winner: 0, loser: 1 },
],
},
}

Rugby's four-try bonus needs the tries, which a score does not record; it is not yet expressible.

  • A decided rule may name decidedIn (the phase that completed the result: REGULATION, OVERTIME, DECIDER, or EXTERNAL for a winner decided outside the score) and decidedBy (how that winner was decided: SHOOTOUT, COMPETITION_RULE, LOTS, OFFICIAL_DECISION). A result with no record was decided in REGULATION. IIHF's 3-2-1-0 over a format that declares its overtime and shootout (PER3XA-S:T20P-O:1SD/T5P-F:SO5), which records decidedIn on every result:
{
groupOrderKey: 'classificationPoints',
resultPoints: {
rules: [
{ id: 'regulation', decidedIn: ['REGULATION'], winner: 3, loser: 0 },
{ id: 'overtime', decidedIn: ['OVERTIME', 'DECIDER'], winner: 2, loser: 1 },
],
},
}

Where the format declares no shootout and one is entered as a decided result, the rule for it is { id: 'shootout', decidedBy: ['SHOOTOUT'], winner: 2, loser: 1 }.

  • A drawn result is a COMPLETED matchUp with no winner whose score is a level finish its format permits: a level combined total (SET1-S:P32), a level aggregate over all of its segments (HAL2A-S:T45, a soccer 1-1), or a level count of sets (SET3-S:T10, a timed set closing level; SET2X-S:6/TB7, one set each). It stands only where no winner is needed: a round robin or an ad hoc draw. A format with a declared overtime (-O:) is drawn where the scoring engine completes it with no winner: a finite overtime with no decider that stays level. A level result with a winner decided outside the score (score.overtime.decidedIn: 'EXTERNAL') is that winner's win, not a draw.
  • An unfinished, excluded or BYE result earns nothing. A decided or drawn result that matches no rule is listed on both participants in classificationUnmatched rather than counted as 0 in silence.
  • Each participant's tally carries classificationPoints, and classificationContributions records each result's rule and points. Nothing is written without resultPoints.

denominator​

denominator: 'EXPECTED' makes setsPct and gamesPct divide by the sets and games a participant was expected to play. For example, a walkover win counts as sets the winner was due to play. The engine works the expected meetings out from the group itself (any number of meetings per pair). 'PLAYED' (default) divides by what was actually played.

Completion​

A group is complete when every meeting has a result, so a double round robin and a group with an excluded status (excludeMatchUpStatuses) complete, and their order is written as groupOrder. Before the standings engine, they only ever received provisionalOrder.

groupTotalGamesPlayed / groupTotalSetsPlayed​

Purpose: Use total group games/sets as denominator for percentage calculations.

Example scenario:

4 participants in round robin (6 total matches):
- Participant A: 12 games won, 6 games lost
- Participant B: 10 games won, 8 games lost
- Participant C: 8 games won, 10 games lost
- Participant D: 6 games won, 12 games lost
Total: 36 games won, 36 games lost (72 games total)

Without groupTotalGamesPlayed:

A: 12/18 = 66.7%
B: 10/18 = 55.6%
C: 8/18 = 44.4%
D: 6/18 = 33.3%
Total: 200%

With groupTotalGamesPlayed:

A: 12/72 = 16.7%
B: 10/72 = 13.9%
C: 8/72 = 11.1%
D: 6/72 = 8.3%
Total: 50% (games won / total games)

Credit for Incomplete Matches​

setsCreditForDefaults / setsCreditForWalkovers / setsCreditForRetirements​

Purpose: Award winner full sets when opponent doesn't complete match.

Default: All false

Example:

// Best of 3 (2 sets to win)
// Match: A vs B, score 6-3, B retires

// Without setsCreditForRetirements:
A: 1 set won

// With setsCreditForRetirements:
A: 2 sets won (awarded setsToWin)

Policy:

{
setsCreditForRetirements: true,
setsCreditForDefaults: true,
setsCreditForWalkovers: true,
}

gamesCreditForDefaults / gamesCreditForWalkovers / gamesCreditForRetirements​

Purpose: Award winner estimated games when opponent doesn't complete match.

Default: All false

Example:

// Best of 3, standard scoring (6 games per set)
// Match: A vs B, score 6-3, B retires

// Without gamesCreditForRetirements:
A: 6 games won

// With gamesCreditForRetirements:
A: 12 games won (estimated from setsToWin * 6)

gamesCreditForTiebreakSets​

Purpose: Count tiebreak set as 1 game won.

Default: true

Example:

// Match: A vs B, score 6-3 3-6 [10-5]

// With gamesCreditForTiebreakSets: true
A: 6 + 3 + 1 = 10 games won
B: 3 + 6 = 9 games won

// With gamesCreditForTiebreakSets: false
A: 6 + 3 = 9 games won
B: 3 + 6 = 9 games won

Policy:

{
gamesCreditForTiebreakSets: false, // Don't count [10-x] as game
}

Disqualification​

disqualifyDefaults / disqualifyWalkovers​

Purpose: A participant who conceded a walkover (disqualifyWalkovers) or a default (disqualifyDefaults) is ordered below every participant who conceded none, whatever their record. The disqualified participants are then ordered among themselves by the same policy. A retirement does not disqualify.

Default: true in the built-in default, JTT and TOC policies.

Implemented by the standings engine. Before it, these flags were declared in the built-in policies but read by no code, so a participant who conceded a walkover was ordered by their record like anyone else.

Example:

// 4 participants:
// A: 2-1
// B: 2-1
// C: 1-2
// D: 1-2 (with 1 DEFAULT)

// With disqualifyDefaults: true
Order: A, B, C, D (4th - pushed to bottom)

// With disqualifyDefaults: false
Order: A, B, C/D tied (use tiebreakers)

Policy:

{
disqualifyDefaults: true,
disqualifyWalkovers: true,
}

Exclude Match Statuses​

excludeMatchUpStatuses​

Purpose: Exclude specific match statuses from tally calculations.

Use cases:

  • Exclude ABANDONED matches
  • Exclude INCOMPLETE matches
  • Exclude matches that shouldn't count toward standings

Example:

{
excludeMatchUpStatuses: ['ABANDONED', 'INCOMPLETE'],
}

Effect:

  • Excluded matches don't count toward wins/losses
  • Not included in percentage calculations
  • Treated as if they never happened

GEMscore​

Purpose: Create composite score from multiple attributes.

Formula: Weighted combination of percentage attributes

Attributes:

  • matchUpsPct
  • tieMatchUpsPct
  • setsPct
  • gamesPct
  • pointsPct

Result:

participantResults: {
participantId123: {
matchUpsWon: 2,
matchUpsLost: 1,
matchUpsPct: 0.667,
setsPct: 0.714,
gamesPct: 0.650,
GEMscore: 85234567, // Composite integer score
}
}

Usage:

  • Alternative ranking metric
  • Visual representation of overall performance
  • Can be used as tiebreaker attribute

Best finishers across groups​

crossGroup​

When a playoff takes the best finishers of a position across several groups (the best third-placed participants), the candidates are compared by crossGroup: an ordered list of stored measures, higher first, a reversed one lower first. The first measure that differs decides. Head-to-head cannot apply across groups.

{
crossGroup: [{ attribute: 'matchUpsPct' }, { attribute: 'gamesDiff' }, { attribute: 'gamesLost', reversed: true }],
}

The values are written to each participant's tally as crossGroupValues when the group is tallied. Without a crossGroup, candidates are compared by GEMscore, as before. A ratio cannot be a crossGroup measure, because ratios are computed only when ordering and are never stored.


Usage Examples​

Example 1: Standard Tournament​

import { fixtures, policyConstants } from 'tods-competition-factory';
const { POLICY_TYPE_ROUND_ROBIN_TALLY } = policyConstants;
const { POLICY_ROUND_ROBIN_TALLY_DEFAULT } = fixtures.policies;

const tournament = {
policyDefinitions: POLICY_ROUND_ROBIN_TALLY_DEFAULT,
};

tournamentEngine.generateDrawDefinition({
drawType: ROUND_ROBIN,
policyDefinitions: tournament.policyDefinitions,
drawSize: 16,
// ... other options
});

Example 2: Custom Tiebreaking​

const customPolicy = {
[POLICY_TYPE_ROUND_ROBIN_TALLY]: {
policyName: 'Custom Tournament 2024',
groupOrderKey: 'matchUpsWon',

tallyDirectives: [
// 1. Head-to-head if exactly 2 tied
{
attribute: 'matchUpsPct',
idsFilter: true,
maxParticipants: 2,
},

// 2. Games percentage (all matches)
{
attribute: 'gamesPct',
idsFilter: false,
},

// 3. Sets percentage (all matches)
{
attribute: 'setsPct',
idsFilter: false,
},

// 4. Games won among tied teams
{
attribute: 'gamesWon',
idsFilter: true,
},

// 5. Fewest games lost
{
attribute: 'gamesLost',
idsFilter: false,
reversed: true,
},
],

disqualifyDefaults: true,
disqualifyWalkovers: true,
},
};

Example 3: Team Tennis (TEAM Events)​

const teamPolicy = {
[POLICY_TYPE_ROUND_ROBIN_TALLY]: {
policyName: 'Team Championship',
groupOrderKey: 'tieMatchUpsWon', // Individual matches won

tallyDirectives: [
// Team match record among tied teams
{
attribute: 'matchUpsPct',
idsFilter: true,
maxParticipants: 2,
},

// Individual matches won
{
attribute: 'tieMatchUpsWon',
idsFilter: false,
},

// Singles matches won
{
attribute: 'tieSinglesWon',
idsFilter: false,
},

// Doubles matches won
{
attribute: 'tieDoublesWon',
idsFilter: false,
},

// Sets won
{
attribute: 'setsWon',
idsFilter: false,
},
],
},
};

Example 4: Games-Based Ranking​

const gamesPolicy = {
[POLICY_TYPE_ROUND_ROBIN_TALLY]: {
policyName: 'Games Primary',
groupOrderKey: 'gamesWon',

tallyDirectives: [
// Most games won
{
attribute: 'gamesWon',
idsFilter: false,
},

// Fewest games lost
{
attribute: 'gamesLost',
idsFilter: false,
reversed: true,
},

// Game percentage
{
attribute: 'gamesPct',
idsFilter: false,
},

// Head-to-head if 2 teams
{
attribute: 'matchUpsPct',
idsFilter: true,
maxParticipants: 2,
},
],

// Award games for walkovers/defaults
gamesCreditForWalkovers: true,
gamesCreditForDefaults: true,
},
};

Example 5: Hockey-Style with Penalty Minutes​

const hockeyPolicy = {
[POLICY_TYPE_ROUND_ROBIN_TALLY]: {
policyName: 'Hockey Tournament',
groupOrderKey: 'matchUpsWon',

tallyDirectives: [
// Head-to-head (2 teams only)
{
attribute: 'matchUpsPct',
idsFilter: true,
maxParticipants: 2,
},

// Most wins
{
attribute: 'matchUpsWon',
idsFilter: false,
},

// Goal average (custom attribute - would need implementation)
// { attribute: 'goalAverage', idsFilter: false },

// Fewest penalty minutes (custom attribute)
// { attribute: 'penaltyMinutes', idsFilter: false, reversed: true },

// Fallback to games
{
attribute: 'gamesPct',
idsFilter: false,
},
],
},
};

Best Practices​

1. Always Provide Fallback Directives​

// ✓ GOOD: Multiple tiebreakers
tallyDirectives: [
{ attribute: 'matchUpsPct', idsFilter: true, maxParticipants: 2 },
{ attribute: 'gamesPct', idsFilter: false },
{ attribute: 'gamesWon', idsFilter: false },
{ attribute: 'gamesLost', idsFilter: false, reversed: true },
];

// ✗ BAD: Single tiebreaker might not resolve all ties
tallyDirectives: [{ attribute: 'matchUpsPct', idsFilter: true, maxParticipants: 2 }];

2. Use maxParticipants for Head-to-Head​

// ✓ GOOD: Only apply head-to-head when it makes sense
{
attribute: 'matchUpsPct',
idsFilter: true,
maxParticipants: 2 // Skip if 3+ teams (circular ties possible)
}

// ✗ RISKY: Head-to-head with 3+ teams can be indeterminate
{
attribute: 'matchUpsPct',
idsFilter: true // May not separate circular ties
}

3. Order Directives Logically​

// ✓ GOOD: Broad criteria first, narrow criteria later
tallyDirectives: [
{ attribute: 'matchUpsPct', idsFilter: false }, // Overall record
{ attribute: 'setsPct', idsFilter: false }, // Overall sets
{ attribute: 'matchUpsPct', idsFilter: true }, // Head-to-head
{ attribute: 'setsPct', idsFilter: true }, // H2H sets
];

// ✗ CONFUSING: Narrow then broad
tallyDirectives: [
{ attribute: 'matchUpsPct', idsFilter: true }, // H2H first
{ attribute: 'matchUpsPct', idsFilter: false }, // Then overall
];

4. Document Tournament-Specific Rules​

const tournamentPolicy = {
[POLICY_TYPE_ROUND_ROBIN_TALLY]: {
policyName: 'Spring Championship 2024',
// Document: "Per tournament regulations section 5.3"
groupOrderKey: 'matchUpsWon',
tallyDirectives: [
// Rule 5.3.1: Head-to-head if 2 teams tied
{ attribute: 'matchUpsPct', idsFilter: true, maxParticipants: 2 },
// Rule 5.3.2: Games won percentage
{ attribute: 'gamesPct', idsFilter: false },
// Rule 5.3.3: Fewest games lost
{ attribute: 'gamesLost', idsFilter: false, reversed: true },
],
},
};


Methods​

tallyParticipantResults​

Calculate participant results and group order based on the round robin tally policy.

import { competitionEngine } from 'tods-competition-factory';
const { tallyParticipantResults } = competitionEngine;

const { participantResults, order, report, readableReport } = tallyParticipantResults({
matchUps, // Array of matchUps
policyDefinitions, // Policy definitions object
matchUpFormat, // Optional default format
generateReport: true, // Optional: generate detailed tiebreaking report
});

// participantResults: {
// [participantId]: {
// matchUpsWon: number;
// matchUpsLost: number;
// setsWon: number;
// setsLost: number;
// gamesWon: number;
// gamesLost: number;
// pointsWon: number;
// pointsLost: number;
// matchUpsPct: number;
// setsPct: number;
// gamesPct: number;
// pointsPct: number;
// defaults: number;
// walkovers: number;
// retirements: number;
// allDefaults: number;
// groupOrder: number; // Final placement (when bracket complete)
// provisionalOrder: number; // Current placement (when incomplete)
// GEMscore?: number; // If configured
// }
// }
Understanding Tiebreaking

When generateReport: true, the function returns detailed information showing exactly how tiebreaks were resolved step-by-step. This is invaluable for:

  • Explaining to participants why they finished in a specific position
  • Verifying that tiebreaking followed the expected policy
  • Debugging complex tiebreaking scenarios
  • Creating transparent tournament reports

See Query Governor - tallyParticipantResults for complete documentation of the generateReport parameter and examples of using the tiebreaking report.


Notes​

groupOrder vs provisionalOrder​

  • groupOrder: Assigned when bracket is complete
  • provisionalOrder: Assigned when bracket is incomplete
  • See provisionalPositioning in Draws Governor

Bracket Completion​

Group order is ONLY assigned when all required matchUps are complete:

const bracketComplete = relevantMatchUps.filter((matchUp) => isComplete(matchUp)).length === relevantMatchUps.length;

if (bracketComplete && groupOrder) {
// Assign groupOrder to participantResults
}

For incomplete brackets, use provisionalOrder instead.

Circular Ties​

With 3+ participants, circular ties are possible:

  • Team A beats Team B
  • Team B beats Team C
  • Team C beats Team A
  • All teams 1-1 head-to-head

Solution: Use maxParticipants: 2 on head-to-head rules to skip circular tie scenarios.

See maxParticipants documentation for details.


Validation​

A tally policy is checked where it is saved: attachPolicies (before anything is written) and validateSeason (for a season's or a tier's tallyPolicy) refuse it with INVALID_VALUES. validateTallyPolicy({ tallyPolicy }) runs the same checks on its own. A season standings calculation does not refuse for its policy; the season was checked when saved. Previously an unknown groupOrderKey was accepted and silently ranked by matchUpsWon.

An absent policy (undefined) is valid. Every other value is checked against the rules below, in the order they are listed, and every rule that fails is collected; the refusal is

{ error: INVALID_VALUES, info: '<the message of the first rule that fails>', context: { errors: ['<every message>'] }, stack: ['validateTallyPolicy'] }

attachPolicies returns that refusal as it is. validateSeason lists each message in its own context.errors, prefixed by its owner and a space: season tallyPolicy: or tier <tierId> tallyPolicy:.

Accepted names​

  • Primary measures (groupOrderKey): tieMatchUpsWon, tieSinglesWon, tieDoublesWon, matchUpsWon, matchUpsDrawn, standingsPoints, pointsWon, gamesWon, setsWon, gamesPct, setsPct, pointsPct, matchUpsPct, setsDiff, gamesDiff, pointsDiff, setsRatio, gamesRatio, pointsRatio, classificationPoints.
  • Measures (a directive attribute): allDefaults, defaults, walkovers, retirements, matchUpsWon, matchUpsLost, matchUpsDrawn, matchUpsCancelled, matchUpsPct, setsWon, setsLost, setsPct, gamesWon, gamesLost, gamesPct, pointsWon, pointsLost, pointsPct, tieMatchUpsWon, tieMatchUpsLost, tieMatchUpsPct, tieSinglesWon, tieSinglesLost, tieDoublesWon, tieDoublesLost, standingsPoints, setsDiff, gamesDiff, pointsDiff, setsRatio, gamesRatio, pointsRatio, classificationPoints, buchholz, buchholzCut1, buchholzMedian, sonnebornBerger.
  • Directive-only attributes, which are not measures: headToHead, external.
  • Tied-set measures (a directive attribute only): commonOpponents, groupLeader, recordVsGroup, recordVsSet.
  • Ratio measures: setsRatio, gamesRatio, pointsRatio.
  • Graph measures: buchholz, buchholzCut1, buchholzMedian, sonnebornBerger.
  • A season's extra measures: a season's or a tier's policy may also use valueWon and valueLost, both as the primary measure and as a measure.

Rules​

"Whole number" means an integer value (2 and 2.0 alike). "Finite number" means a number that is neither infinite nor NaN. In a message, [i] is the zero-based index and a value is written as text (an absent one as undefined). Each rule's example is a policy that it refuses, with the message it gives.

RuleRefusedMessage
The policy is an object (null is not)."text"tallyPolicy must be an object
groupOrderKey, when present, is a primary measure.{ "groupOrderKey": "gamesWonn" }unknown groupOrderKey: gamesWonn
groupOrderKey is not a graph measure (a graph measure scores opponents by the primary measure; it is also not a primary measure, so the rule above fails first).{ "groupOrderKey": "sonnebornBerger" }unknown groupOrderKey: sonnebornBerger
tallyDirectives, when present, is an array.{ "tallyDirectives": {} }tallyDirectives must be an array
Each directive is an object (null is not).{ "tallyDirectives": [3] }tallyDirectives[0] must be an object
A directive's attribute is a measure, a tied-set measure or a directive-only attribute.{ "tallyDirectives": [{ "attribute": "gamesWonn" }] }tallyDirectives[0]: unknown attribute gamesWonn
A headToHead directive's mode, when present, is RECORD or SWEEP.{ "tallyDirectives": [{ "attribute": "headToHead", "mode": "FIRST" }] }tallyDirectives[0]: headToHead mode must be one of RECORD, SWEEP
An external directive has an externalKey that is a non-empty string.{ "tallyDirectives": [{ "attribute": "external" }] }tallyDirectives[0]: an external directive needs an externalKey
A directive's minParticipants, when present, is a whole number of at least 1.{ "tallyDirectives": [{ "attribute": "gamesWon", "minParticipants": 0 }] }tallyDirectives[0]: minParticipants must be a whole number of at least 1
A directive's maxParticipants, when present, is a whole number of at least 1.{ "tallyDirectives": [{ "attribute": "gamesWon", "maxParticipants": 1.5 }] }tallyDirectives[0]: maxParticipants must be a whole number of at least 1
A directive's zeroDivision, when present, is MAX, ZERO or SKIP (any directive may carry it; only a ratio reads it).{ "tallyDirectives": [{ "attribute": "setsRatio", "zeroDivision": "INFINITY" }] }tallyDirectives[0]: zeroDivision must be one of MAX, ZERO, SKIP
A directive's when, when present, is an object (null is not).{ "tallyDirectives": [{ "attribute": "gamesWon", "when": "FINAL" }] }tallyDirectives[0]: when must be an object
when.purposes, when present, is an array of strings.{ "tallyDirectives": [{ "attribute": "gamesWon", "when": { "purposes": "MOVEMENT" } }] }tallyDirectives[0]: when.purposes must be an array of strings
when.phase, when present, is PROVISIONAL or FINAL.{ "tallyDirectives": [{ "attribute": "gamesWon", "when": { "phase": "LIVE" } }] }tallyDirectives[0]: when.phase must be one of PROVISIONAL, FINAL
A graph measure directive is not scoped by idsFilter (a truthy idsFilter); it reads the whole table.{ "tallyDirectives": [{ "attribute": "buchholz", "idsFilter": true }] }tallyDirectives[0]: buchholz reads the whole table; idsFilter cannot scope it
A tied-set measure directive is not scoped by idsFilter (a truthy idsFilter); it reads the whole table.{ "tallyDirectives": [{ "attribute": "commonOpponents", "idsFilter": true }] }tallyDirectives[0]: commonOpponents reads the whole table; idsFilter cannot scope it
A directive's minSample, when present, is on a commonOpponents directive (nothing else reads it).{ "tallyDirectives": [{ "attribute": "gamesPct", "minSample": 4 }] }tallyDirectives[0]: minSample applies only to commonOpponents
A directive's groupBy, when present, is on a groupLeader or recordVsGroup directive (nothing else reads it).{ "tallyDirectives": [{ "attribute": "gamesWon", "groupBy": "division" }] }tallyDirectives[0]: groupBy applies only to groupLeader, recordVsGroup
A groupLeader or recordVsGroup directive has a groupBy that is a non-empty string.{ "tallyDirectives": [{ "attribute": "groupLeader" }] }tallyDirectives[0]: groupLeader needs a groupBy
A directive's setKey, when present, is on a recordVsSet directive (nothing else reads it).{ "tallyDirectives": [{ "attribute": "recordVsGroup", "groupBy": "division", "setKey": "eligible" }] }tallyDirectives[0]: setKey applies only to recordVsSet
A recordVsSet directive has a setKey that is a non-empty string.{ "tallyDirectives": [{ "attribute": "recordVsSet" }] }tallyDirectives[0]: recordVsSet needs a setKey
A commonOpponents directive's minSample, when present, is a whole number of at least 1.{ "tallyDirectives": [{ "attribute": "commonOpponents", "minSample": 0 }] }tallyDirectives[0]: minSample must be a whole number of at least 1
The policy's headToHead, when present, is an object (null is not).{ "headToHead": true }headToHead must be an object
precision, when present, is EXACT or a whole number of at least 0.{ "precision": -1 }precision must be a whole number of decimal places, or 'EXACT'
denominator, when present, is PLAYED or EXPECTED.{ "denominator": "ALL" }denominator must be one of PLAYED, EXPECTED
crossGroup, when present, is an array.{ "crossGroup": {} }crossGroup must be an array
Each crossGroup entry's attribute is a stored measure: a measure that is neither a ratio nor a graph measure.{ "crossGroup": [{ "attribute": "setsRatio" }] }crossGroup[0]: setsRatio is not a stored measure
preReduce, when present, is an object with a groupBy that is a non-empty string.{ "preReduce": {} }preReduce must be an object with a groupBy
resultPoints, when present, has rules: a non-empty array.{ "resultPoints": { "rules": [] } }resultPoints.rules must be a non-empty array
Each rule has an id, a non-empty string.{ "resultPoints": { "rules": [{ "winner": 2, "loser": 0 }] } }resultPoints.rules[0] needs an id
No two rules share an id.{ "resultPoints": { "rules": [{ "id": "win", "winner": 2, "loser": 0 }, { "id": "win", "winner": 2, "loser": 1 }] } }resultPoints.rules[1]: duplicate id win
A drawn rule (a truthy isDrawn) has points, a finite number.{ "resultPoints": { "rules": [{ "id": "draw", "isDrawn": true }] } }resultPoints.rules[0]: a drawn rule needs finite points
Any other rule is decided: it has winner and loser, both finite numbers.{ "resultPoints": { "rules": [{ "id": "win", "winner": 2 }] } }resultPoints.rules[0]: a decided rule needs finite winner and loser points
A rule's matchUpStatuses, when present, is an array.{ "resultPoints": { "rules": [{ "id": "wo", "winner": 2, "loser": 0, "matchUpStatuses": "WALKOVER" }] } }resultPoints.rules[0]: matchUpStatuses must be an array
A rule's loserSetsWon, when present, is an array of whole numbers of at least 0.{ "resultPoints": { "rules": [{ "id": "close", "winner": 2, "loser": 1, "loserSetsWon": [-1] }] } }resultPoints.rules[0]: loserSetsWon must be an array of whole numbers
A rule's loserMarginAtMost, when present, is a finite number of at least 0.{ "resultPoints": { "rules": [{ "id": "close", "winner": 4, "loser": 1, "loserMarginAtMost": -1 }] } }resultPoints.rules[0]: loserMarginAtMost must be a finite number of at least 0
loserMarginAtMost is a condition on a decided result, so a drawn rule cannot have one.{ "resultPoints": { "rules": [{ "id": "draw", "isDrawn": true, "points": 2, "loserMarginAtMost": 7 }] } }resultPoints.rules[0]: loserMarginAtMost applies only to a decided rule
A rule's bonus, when present, is true or false.{ "resultPoints": { "rules": [{ "id": "win", "winner": 4, "loser": 0, "bonus": "yes" }] } }resultPoints.rules[0]: bonus must be true or false
The rules include one that is not a bonus: a bonus only adds to what a deciding rule awarded.{ "resultPoints": { "rules": [{ "id": "close", "winner": 0, "loser": 1, "loserMarginAtMost": 7, "bonus": true }] } }resultPoints.rules needs a rule that is not a bonus
A rule's decidedIn, when present, is a non-empty array of REGULATION, OVERTIME, DECIDER, EXTERNAL.{ "resultPoints": { "rules": [{ "id": "win", "winner": 3, "loser": 0, "decidedIn": ["PENALTIES"] }] } }resultPoints.rules[0]: decidedIn must be a non-empty array of REGULATION, OVERTIME, DECIDER, EXTERNAL
decidedIn is a condition on a decided result, so a drawn rule cannot have one.{ "resultPoints": { "rules": [{ "id": "draw", "isDrawn": true, "points": 1, "decidedIn": ["REGULATION"] }] } }resultPoints.rules[0]: decidedIn applies only to a decided rule
A rule's decidedBy, when present, is a non-empty array of SHOOTOUT, COMPETITION_RULE, LOTS, OFFICIAL_DECISION.{ "resultPoints": { "rules": [{ "id": "so", "winner": 2, "loser": 1, "decidedBy": [] }] } }resultPoints.rules[0]: decidedBy must be a non-empty array of SHOOTOUT, COMPETITION_RULE, LOTS, OFFICIAL_DECISION
decidedBy is a condition on a decided result, so a drawn rule cannot have one.{ "resultPoints": { "rules": [{ "id": "draw", "isDrawn": true, "points": 1, "decidedBy": ["LOTS"] }] } }resultPoints.rules[0]: decidedBy applies only to a decided rule
onSplit, when present, is RESTART, CONTINUE or EXTRACT_ONE.{ "onSplit": "RESTARTS" }onSplit must be one of RESTART, CONTINUE, EXTRACT_ONE
terminal, when present, is ADJUDICATE, SHARE or LOT.{ "terminal": "COIN" }terminal must be one of ADJUDICATE, SHARE, LOT
drawCredit, when present, is a finite number from 0 to 1.{ "drawCredit": 2 }drawCredit must be a finite number between 0 and 1
outcomePoints, when present, is an object whose win, draw and loss are finite numbers.{ "outcomePoints": { "win": 3, "draw": 1 } }outcomePoints requires finite win, draw and loss values
A policy ranking by standingsPoints (its groupOrderKey or any directive's attribute) has outcomePoints.{ "groupOrderKey": "standingsPoints" }standingsPoints ranking requires outcomePoints

Each directive is checked in turn, through its own rules from attribute to idsFilter. Every rule in the table can fail together with the others, except the last three: of drawCredit, outcomePoints and the standingsPoints rule, only the first that fails is reported.

A policy that uses every option and passes:

{
"groupOrderKey": "classificationPoints",
"precision": "EXACT",
"denominator": "EXPECTED",
"onSplit": "EXTRACT_ONE",
"preReduce": { "groupBy": "division" },
"terminal": "LOT",
"drawCredit": 0.5,
"outcomePoints": { "win": 3, "draw": 1, "loss": 0 },
"headToHead": { "disabled": false },
"crossGroup": [{ "attribute": "gamesDiff" }, { "attribute": "pointsWon", "reversed": true }],
"resultPoints": {
"rules": [
{ "id": "close", "winner": 2, "loser": 1, "loserSetsWon": [2], "matchUpStatuses": ["COMPLETED"] },
{ "id": "win", "winner": 3, "loser": 0 },
{ "id": "draw", "isDrawn": true, "points": 1 }
]
},
"tallyDirectives": [
{ "attribute": "headToHead", "mode": "SWEEP" },
{ "attribute": "standingsPoints", "minParticipants": 2, "maxParticipants": 4 },
{ "attribute": "setsRatio", "zeroDivision": "SKIP", "when": { "purposes": ["MOVEMENT"], "phase": "FINAL" } },
{ "attribute": "buchholz", "idsFilter": false },
{ "attribute": "commonOpponents", "minSample": 4 },
{ "attribute": "groupLeader", "groupBy": "division" },
{ "attribute": "recordVsGroup", "groupBy": "conference" },
{ "attribute": "recordVsSet", "setKey": "eligible" },
{ "attribute": "external", "externalKey": "drawShot", "reversed": true }
]
}

Testing​

Comprehensive test coverage in src/tests/documentation/roundRobinTallyPolicy.test.ts:

  • ✅ All built-in policies
  • ✅ Precision calculations
  • ✅ maxParticipants thresholds
  • ✅ Reversed attributes
  • ✅ Disqualification rules
  • ✅ Exclude match statuses
  • ✅ Credit for incomplete matches
  • ✅ groupTotals calculations
  • ✅ idsFilter scoping
  • ✅ Head-to-head configurations
  • ✅ GEMscore generation
  • ✅ TEAM event statistics
  • ✅ Circular tie scenarios