Sanctioning Governor

import { governors } from 'tods-competition-factory';

const { sanctioningGovernor } = governors;

The sanctioningGovernor re-exports all sanctioning mutation and query functions for use outside the sanctioning engine. While the sanctioningEngine provides a complete stateful API, the governor exports individual functions that can be called directly with a sanctioningRecord parameter.

Reachable since 7.x

The governor was implemented but never registered in the governors index, so none of its methods reached any engine and nothing here could be imported. Registering it added 35 methods to the engine surface. If you tried to use this page before 7.x and could not, that is why.

For full engine documentation including state management, executionQueue, and workflow examples, see Sanctioning Engine.

---

Mutations

createSanctioningRecord

Creates a new SanctioningRecord in DRAFT status.

{
  governingBodyId: string;
  applicant: Applicant;
  proposal: TournamentProposal;
  sanctioningTier?: TierClassification;
  sanctioningPolicy?: string;
}

Returns: { success, sanctioningRecord }

---

updateProposal

Updates proposal fields on a record in editable status (DRAFT or MODIFICATION_REQUESTED).

{
  sanctioningRecord: SanctioningRecord;
  updates: Partial<TournamentProposal>;
}

---

addEventProposal / removeEventProposal / updateEventProposal

CRUD operations for event proposals within a sanctioning record.

// Add
{
  sanctioningRecord;
  eventProposal: EventProposal;
}
// Returns: { success, eventProposalId }

// Remove
{
  sanctioningRecord;
  eventProposalId: string;
}

// Update
{
  sanctioningRecord;
  eventProposalId: string;
  updates: Partial<EventProposal>;
}

---

submitApplication

Transitions DRAFT → SUBMITTED. Validates endorsement if required by policy. Snapshots the policy version.

{ sanctioningRecord; sanctioningPolicy?: SanctioningPolicy; submittedBy?: string }

---

reviewApplication

Transitions SUBMITTED → UNDER_REVIEW.

{ sanctioningRecord; reviewer?: Reviewer }

---

approveApplication

Transitions UNDER_REVIEW or CONDITIONALLY_APPROVED → APPROVED.

{ sanctioningRecord; approvedBy?: string; reason?: string }

---

conditionallyApprove

Transitions UNDER_REVIEW → CONDITIONALLY_APPROVED with conditions.

{ sanctioningRecord; conditions: Array<{ description: string }>; approvedBy?: string }

---

meetCondition

Marks a condition as met. Returns { allConditionsMet: boolean }.

{ sanctioningRecord; conditionId: string; metNotes?: string }

---

rejectApplication

Transitions to REJECTED (terminal).

{ sanctioningRecord; rejectedBy?: string; reason?: string }

---

withdrawApplication

Transitions to WITHDRAWN (terminal). Available from DRAFT, SUBMITTED, CONDITIONALLY_APPROVED, APPROVED, MODIFICATION_REQUESTED.

{ sanctioningRecord; withdrawnBy?: string; reason?: string }

---

requestModification

Transitions to MODIFICATION_REQUESTED, making the proposal editable again.

{ sanctioningRecord; requestedBy?: string; note?: string }

---

requestEndorsement / endorseApplication / declineEndorsement

Endorsement sub-workflow.

// Request
{ sanctioningRecord; endorserId: string; endorserName?: string; endorserContact?: PersonReference }

// Endorse
{ sanctioningRecord; endorserNotes?: string; conditions?: string[] }

// Decline
{ sanctioningRecord; declineReason?: string }

---

addReviewNote

Adds a review note to the record.

{ sanctioningRecord; note: string; reviewerId?: string; reviewerName?: string }

Returns: { success, noteId }

---

openProposalRegistration

Opens (or adjusts) public registration on a proposal before a tournamentRecord exists. Assigns a tournamentId to the proposal (minting one if absent) so a public site can render a registration page against a not-yet-activated proposal, and gives each proposed event a stable eventId. Merges any supplied registrationProfile fields and ensures entriesOpen is set (opening now when no explicit value is present). Gated only against terminal statuses (REJECTED, WITHDRAWN, CLOSED); stricter workflow/policy is enforced by the consuming service.

{ sanctioningRecord; tournamentId?: string; registrationProfile?: Partial<RegistrationProfile> }

Returns: { success, tournamentId, registrationProfile }

---

activateFromSanctioning

Generates a tournamentRecord from an APPROVED sanctioning record and transitions to ACTIVE. Reuses the tournamentId and per-event eventIds already assigned by openProposalRegistration — so registrations collected before activation remain valid — otherwise mints new ids.

{ sanctioningRecord; sanctioningPolicy?: SanctioningPolicy; venues?: Venue[] }

Venues. Pass venues to materialize canonical venues onto the generated tournamentRecord — typically pulled by the caller from a facility registry for the facility the sanctioning record was attached to. They are supplied, not resolved: the factory has no runtime dependencies and no service awareness, so resolution belongs to the caller and materialization to the engine. A canonical venue carries facilityId and typed courts, so the activated tournament inherits one cross-tournament identity for the place it is played at instead of a re-entered venue.

When no venues are supplied, proposal.venues (VenueProposal[]) is materialized instead. That is a fallback: a proposal venue is what an applicant typed, so it has no canonical identity — its facilityId defaults to its own venueId — and numberOfCourts is deliberately not expanded into placeholder courts, which would fabricate identities to be reconciled against a registry later. Supplied venues always win over the proposal description.

Returns: { success, tournamentRecord }

---

proposeAmendment

Proposes changes to an APPROVED or ACTIVE record. Minor amendments are auto-approved; substantial amendments require review.

{ sanctioningRecord; changes: ProposalChange[]; sanctioningPolicy?: SanctioningPolicy; proposedBy?: string }

Returns: { success, amendmentId, severity, autoApproved }

---

reviewAmendment

Approves or rejects a proposed amendment. Approved amendments apply their changes to the proposal.

{ sanctioningRecord; amendmentId: string; approved: boolean; reviewerNotes?: string }

---

transitionToPostEvent

Transitions ACTIVE → POST_EVENT.

{ sanctioningRecord; transitionedBy?: string }

---

submitComplianceItem / verifyComplianceItem / waiveComplianceItem

Compliance item lifecycle management.

// Submit
{ sanctioningRecord; itemId: string; value?: any }

// Verify
{ sanctioningRecord; itemId: string }
// Returns: { success, allCompliant: boolean }

// Waive
{ sanctioningRecord; itemId: string; reason?: string }

---

flagComplianceIssues

Transitions POST_EVENT → ISSUES_FLAGGED.

{ sanctioningRecord; transitionedBy?: string; reason?: string }

---

closeApplication

Transitions to CLOSED (terminal).

{ sanctioningRecord; closedBy?: string; reason?: string }

---

Queries

querySanctioningRecord

Returns a deep copy of the sanctioning record.

{
  sanctioningRecord;
}

---

getAvailableTransitions

Returns valid status transitions for the record's current status.

{
  sanctioningRecord;
}

Returns: { success, availableTransitions: SanctioningStatus[] }

---

getStatusHistory

Returns the full status transition history.

{
  sanctioningRecord;
}

Returns: { success, statusHistory: StatusTransition[] }

---

getCompleteness

Returns a completeness score (0-100%) with missing fields.

{ sanctioningRecord; sanctioningPolicy?: SanctioningPolicy }

Returns: { success, completeness: { score, totalFields, completedFields, missingFields } }

---

getEligibleTiers

Returns which policy tiers the proposal qualifies for.

{
  proposal: TournamentProposal;
  sanctioningPolicy: SanctioningPolicy;
}

Returns: { success, eligibleTiers, tierEligibilities }

---

getCalendarConflicts

Detects scheduling conflicts using injected calendar context.

{
  sanctioningRecord;
  calendarContext: CalendarContext;
}

Returns: { success, conflicts, errors, warnings, hasConflicts }

Conflict types: PROXIMITY, SAME_WEEK, BLACKOUT, MAX_EVENTS_PER_WEEK

---

validateProposal

Validates proposal against policy and optional tier constraints.

{ proposal: TournamentProposal; sanctioningPolicy: SanctioningPolicy; sanctioningTier?: TierClassification }

Returns: { success, valid, issues, errors, warnings }

Checks: insurance, safety plan, medical plan, anti-corruption, safeguarding, lead time, prize money, courts, event types, draw types, draw sizes, match formats, genders, qualifying, personnel.

---

validateStatusTransition

Validates whether a status transition is allowed.

{
  fromStatus: SanctioningStatus;
  toStatus: SanctioningStatus;
}

Returns: { success, valid } or { error } with valid targets in context.