Competition Profile
drawDefinition.competitionProfile is a first-class, versioned configuration attribute. It describes the competition format; matchUps, scores and applied-round provenance live separately. It is separate from competitionFormat, which describes how a sport is played.
Configure a rotating-partner draw
Create an AD_HOC doubles draw with no matchUps, then set its profile:
const result = tournamentEngine.setCompetitionProfile({
drawId,
competitionProfile: {
version: 1,
format: 'MEXICANO',
entrantScope: 'INDIVIDUAL',
matchUpType: 'DOUBLES',
scoring: { combinedPointTotal: 32 },
standings: { metric: 'SIDE_POINTS', attribution: 'EACH_INDIVIDUAL' },
pairing: {
seed: baseSeed,
algorithmVersion: 1,
groupBy: 'ADJACENT_STANDINGS',
partners: 'FIRST_FOURTH_SECOND_THIRD',
},
completion: { kind: 'ROUND_COUNT', rounds: 7 },
},
});
For Americano, use format: 'AMERICANO', pairing: { seed, algorithmVersion: 1 } and completion: { kind: 'PARTNERSHIP_COVERAGE' }. Store the Americano generator's seedUsed or Mexicano's baseSeed. Seeds must be safe integers; combined point totals and round counts must be positive safe integers. Version and pairing algorithm version are currently 1.
The governing scoring policy permits variants; the selected variant is saved in the profile and each applied round. Individual admission and round application use the APIs below. Manual/live scoring and individual standings use the historical contracts saved with applied rounds.
Read, change and remove
const { competitionProfile } = tournamentEngine.getCompetitionProfile({ drawId });
const result = tournamentEngine.removeCompetitionProfile({ drawId });
Queries and writes copy profile data, so changing caller objects does not change the record. An absent profile returns success with an undefined profile. Mutations emit the ordinary draw modification notice and the containing tournament record can be saved by its consumer. The attribute is first-class in every schema write mode; no extension migration is involved.
Once any matchUps exist in the draw or its nested structures, attaching, changing or removing the profile returns EXISTING_MATCHUPS. Reapplying an identical profile is an idempotent success. This protects already-generated rounds from being reinterpreted. Future correction and configuration-amendment workflows require their own explicit contracts.
Ladder configuration and state
A LADDER draw accepts { version: 1, format: 'LADDER' }. This identifies its format without changing existing ladder policy resolution. Challenge eligibility, movement and validation rules remain in the inherited ladder policy.
Rank standings are stored in structure position assignments; rating standings are derived from participant rating scales. Challenges and result attestations use matchUps and their timeItems, while dated participant scale items preserve standing history. Neither those records nor mutable standings belong in a policy or this configuration attribute. A later ladder normalization can add explicit configuration fields without copying its existing state here.
Governing scoring policy
getRotatingPartnerScoringPolicy({ drawId, structureId?, selectedVariant? }) returns the resolved
contract, scoringPolicy and selectionLocked. It reads the existing scoring policy's
rotatingPartners.AMERICANO or rotatingPartners.MEXICANO section. Policy precedence is
structure → draw → event → tournament; a nearer scoring policy replaces the whole scoring policy,
rather than merging nested fields. Missing format rules use the engine default; malformed rules fail.
const policyDefinitions = {
scoring: {
rotatingPartners: {
AMERICANO: {
defaultVariant: { tieResolution: 'ALLOW' },
permittedVariants: [{ tieResolution: 'ALLOW' }, { tieResolution: 'DECIDING_POINT' }],
permittedPointTotals: [24, 32],
},
},
},
};
tournamentEngine.attachPolicies({ drawId, policyDefinitions });
const result = tournamentEngine.getRotatingPartnerScoringPolicy({ drawId });
A singleton permitted list locks the organizer's choice. Otherwise the selected variant must match
one of the permitted variants exactly. WIN_BY_MARGIN requires a safe-integer winningMargin
of at least two; other variants prohibit a margin. Point totals must be positive safe integers and,
when restricted, belong to permittedPointTotals.
The engine default permits ALLOW, DECIDING_POINT, and WIN_BY_MARGIN with margin two,
defaulting to ALLOW. This query validates and previews configuration; use the persistence mutation below to save a
selection. Applied rounds capture the resolved rules used by manual/live scoring and individual standings. Timed scoring requires the explicit enablement below.
Persisting the scoring choice
Call setRotatingPartnerScoring({ drawId, selectedVariant? }) before generating matchUps. Omitting
selectedVariant saves the approved policy default. The mutation stores the choice in
competitionProfile.scoring.selectedVariant; point total and selected variant together define the
resolved combined-point contract. Timed minutes and the selected timed variant define a timed contract. Direct profile writes validate these choices against the governing scoring and tally policies.
getRotatingPartnerScoringContract({ drawId }) reads that saved contract without consulting current
policies. It refuses an unconfigured profile. This is the query historical scoring must use; the
policy query remains the preview of current governing rules. Changing inherited policies cannot
rewrite the saved contract. Repeating an identical write succeeds without effect; changing or removing
the profile is refused once any matchUps exist. The new mutation also respects DRAWS locks.
The draw-level match contract is captured in each applied round. Mixed scoring between rounds, session conclusion and timed deciding-point exclusion are separate deliveries.
Timed rounds
Timed scoring stays on profile version: 1. Set scoring: { kind: 'TIMED', minutes: 15 } and save
an approved variant with setRotatingPartnerScoring. Minutes must be positive safe integers.
ALLOW maps to SET1-S:T15P; DECIDING_POINT maps to SET1-S:T15P/TB1. Timed WIN_BY_MARGIN,
mixed duration/combined-total fields and timed winning margins are refused.
A scoring policy must explicitly enable timed for the format. An omitted timed section disables
it, including under the engine default. timed.permittedMinutes restricts durations when supplied;
once explicitly enabled, omission permits any positive safe-integer minutes. Whole-policy inheritance
and singleton variant locks apply. A known single structure contributes its inherited timed rules
at selection; generation revalidates the selected structure's scoring and tally policies.
Here is a complete factory example, using an imported tournamentEngine:
const playerIds = ['a', 'b', 'c', 'd'];
tournamentEngine.setState({
tournamentId: 'timed-example',
participants: playerIds.map((participantId) => ({
participantId,
participantType: 'INDIVIDUAL' as const,
participantRole: 'COMPETITOR' as const,
})),
events: [
{
eventId: 'timed-event',
eventType: 'DOUBLES',
entries: playerIds.map((participantId) => ({ participantId, entryStatus: 'UNGROUPED' as const })),
drawDefinitions: [
{
drawId: 'timed-draw',
drawType: 'AD_HOC',
matchUpType: 'DOUBLES',
entries: playerIds.map((participantId) => ({ participantId, entryStatus: 'DIRECT_ACCEPTANCE' as const })),
structures: [{ structureId: 'timed-court', matchUps: [] }],
},
],
},
],
});
tournamentEngine.attachPolicies({
policyDefinitions: {
scoring: {
rotatingPartners: {
AMERICANO: {
defaultVariant: { tieResolution: 'ALLOW' },
permittedVariants: [{ tieResolution: 'ALLOW' }],
timed: {
defaultVariant: { tieResolution: 'ALLOW' },
permittedVariants: [{ tieResolution: 'ALLOW' }, { tieResolution: 'DECIDING_POINT' }],
permittedMinutes: [15, 20],
},
},
},
},
},
});
const configured = tournamentEngine.setCompetitionProfile({
drawId: 'timed-draw',
competitionProfile: {
version: 1,
format: 'AMERICANO',
entrantScope: 'INDIVIDUAL',
matchUpType: 'DOUBLES',
scoring: { kind: 'TIMED', minutes: 15 },
standings: { metric: 'SIDE_POINTS', attribution: 'EACH_INDIVIDUAL' },
pairing: { seed: 42, algorithmVersion: 1 },
completion: { kind: 'PARTNERSHIP_COVERAGE' },
},
});
if (!configured.success) throw new Error('Timed profile refused');
tournamentEngine.setRotatingPartnerScoring({ drawId: 'timed-draw' });
const timedPreview = tournamentEngine.getRotatingPartnerRoundPreview({ drawId: 'timed-draw', roundNumber: 1 });
if (timedPreview.error) throw new Error('Timed preview refused');
const timedRound = tournamentEngine.generateRotatingPartnerRound({
drawId: 'timed-draw',
roundNumber: 1,
requestId: 'timed-round-1',
expectedPairings: timedPreview.round!,
expectedScoringContract: timedPreview.scoringContract!,
});
if (timedRound.error) throw new Error('Timed application refused');
const timedResult = tournamentEngine.setMatchUpStatus({
drawId: 'timed-draw',
matchUpId: timedRound.matchUps![0].matchUpId,
outcome: {
matchUpStatus: 'COMPLETED',
winningSide: 1,
score: { sets: [{ setNumber: 1, side1Score: 11, side2Score: 8, winningSide: 1 }] },
},
});
if (timedResult.error) throw new Error('Timed result refused');
const timedStandings = tournamentEngine.getRotatingPartnerStandings({ drawId: 'timed-draw' });
// Both partners receive their side's actual points: 11, 11, 8, 8.
For Mexicano, retain the existing Mexicano pairing/completion fields and enable its own timed policy. Every previous result must be resolved before generating the next round. Pairing algorithms and individual ranking remain unchanged.
Scores alone do not complete a timed match. Send an explicit COMPLETED outcome, or the scorer's
completed state after ending the segment. A live 11–8 stays live; tied ALLOW finishes without a
winner. Completed 0–0 and tied DECIDING_POINT results are refused atomically. A deciding rally must
be included in the final totals: both manual 11–10 and a scorer-produced 10–10 plus one rally credit
11 and 10. A one-point margin alone does not identify a deciding rally. No countdown, elapsed-time
enforcement or automatic completion scheduler is provided.
All actual rally points count. Timed DECIDING_POINT with tally decidingPoints: 'EXCLUDE' is refused
at selection and generation until decided-result evidence supports exclusion. overtimePoints
remains required but has no effect for timed scoring, which has no overtime phase. Existing exit
status treatments, settlements, corrections, locks and historical Mexicano snapshots still apply.
Applied rounds and exact retries use saved contracts, even after policy changes. New rounds use
current policy. Legacy combined-point profiles and contracts may omit kind or explicitly name
COMBINED_POINTS; these compare equally without rewriting historical JSON. Changing saved minutes,
formats or incompatible contracts is refused.
The format code owns the duration: these timed rounds report 15 minutes by default, including /TB1.
Use scheduling averageTimes keyed by the code for venue allowances. Scoring stays fixed for the draw.
Consumer score entry, server rollout and TMX creation require their separate compatible deliveries;
this factory API example does not provide those integrations.
Individual entrants and partnership sides
For a configured Americano or Mexicano draw, pass drawId to addEventEntries to enter individual
competitors into its doubles event as UNGROUPED (or explicitly UNPAIRED) and into the rotating
draw with an accepted status. DIRECT_ACCEPTANCE belongs only to the rotating draw, never the doubles
event. Standard doubles entry behavior remains unchanged
when no rotating draw is targeted. Gender/category checks remain in force. An invalid mixed batch is
refused before event or draw entry writes; PAIRs, unknown IDs and non-competitor roles are refused.
checkValidEntries recognizes the individual roster only in the targeted rotating draw. Event
validation uses the existing ungrouped-status convention. Ordinary draws cannot accept these
individuals as doubles competitors; existing loose, ungrouped AD_HOC entries remain supported.
Deleting the rotating draw retains valid ungrouped event entries. Remove its individual draw entries
before removing its competitionProfile.
Match sides remain PAIR participants. addAdHocMatchUps accepts partnerships outside the draw entry
list when each has two distinct individual entrants. It requires positive logical round numbers and
refuses any individual appearing twice within a round, including matchUps already inserted. Repeating
people across different rounds is permitted. These insertion guards also apply to the atomic round API below.
Preview and apply a round
const preview = tournamentEngine.getRotatingPartnerRoundPreview({
drawId,
structureId, // optional when the draw has exactly one structure
roundNumber: 1,
});
if (!preview.error) {
const result = tournamentEngine.generateRotatingPartnerRound({
drawId,
structureId: preview.structureId,
roundNumber: 1,
requestId, // unique application identifier; retain for retries
expectedPairings: preview.round,
expectedScoringContract: preview.scoringContract,
});
}
Preview creates no participants or matchUps. Application recomputes the preview, refuses changed approved pairings or scoring rules and stages PAIR creation and match insertion before committing. Existing partnerships are reused; new participants and matchUps have IDs derived from the draw, request and round for server/client replay. Successful retries with the same request return the stored round without additional writes. Changed request arguments, removed matches or edited PAIR membership are refused.
Applied provenance lives in drawDefinition.competitionRounds, separate from configuration. Each round record
captures side memberships, matchUp IDs, algorithm version, base/round seeds and scoring/tally contracts.
The frozen roster is stored once in drawDefinition.competitionRoster; Mexicano records also capture
the source standings snapshot and round cutoff. No freshness token is persisted. Do not edit PAIR memberships after application.
Americano supports sequential application of its complete saved rotation. Mexicano starts from zero
points and uses authoritative individual standings for subsequent rounds. Every prior result must be
settled under its saved tally contract before the next Mexicano round can be previewed.
The roster must stay fixed after application. The round API honours DRAWS locks and participant locks
when adding PAIRs. Court allocation uses existing scheduling methods. Each matchUp carries a fixed-total or timed matchUpFormat derived from its saved round scoring contract.
Applied round formats cannot be changed through matchUp, structure, draw or event scope. Scheduling
edits and unrelated PAIR additions do not invalidate approved pairings.
Individual standings and tally policies are documented in Rotating Partner Pairing.