state

type Announcement struct {
	ID        string    `json:"id" yaml:"id"`
	Message   string    `json:"message" yaml:"message"`
	SentAt    time.Time `json:"sentAt" yaml:"sent_at"`
	ExpiresAt time.Time `json:"expiresAt" yaml:"expires_at"`
}

type AnnouncementStore struct {
	// contains filtered or unexported fields
}

type Bracket struct {
	Rounds [][]BracketMatch `json:"rounds"`
	// Preview marks a bracket whose leaves are pool-origin PLACEHOLDERS
	// (e.g. "Pool A 1st") rather than resolved players. It is generated on a
	// mixed (Pools + Knockout) competition at draw time so the operator can
	// see the elimination structure that the pools feed, mirroring the Excel
	// Tree sheet. A preview bracket is read-only: the actual knockout is
	// played in the separate playoffs competition created from this source.
	Preview bool `json:"preview,omitempty"`
	// ThirdPlaceMatch is the optional 3rd-place (bronze) playoff match. It is a
	// SIBLING field rather than a row in Rounds: Rounds is power-of-two,
	// position-encoded (propagateBracketWinner advances winner i into
	// Rounds[rIdx+1][i/2]), so splicing a bronze match into that geometry would
	// corrupt advancement math. The pointer + omitempty keeps bracket.json
	// backward-compatible: nil for every existing/kendo bracket. Generated only
	// for naginata competitions with a real semifinal round (len(Rounds) >= 2);
	// its ID is always "m-bronze", and its sides are filled from the two
	// semifinal losers by propagateBracketWinner.
	ThirdPlaceMatch *BracketMatch `json:"thirdPlaceMatch,omitempty"`
}

type BracketMatch struct {
	ID          string      `json:"id"`
	SideA       string      `json:"sideA"`
	SideB       string      `json:"sideB"`
	Winner      string      `json:"winner"`
	Status      MatchStatus `json:"status"`
	Court       string      `json:"court"`
	ScheduledAt string      `json:"scheduledAt"`
	// Additional fields from design
	ScoreA        string `json:"scoreA"`
	ScoreB        string `json:"scoreB"`
	IsOverridden  bool   `json:"isOverridden"`
	QueuePosition int    `json:"queuePosition,omitempty"`
	// MatchNumber is the sequential bracket match number, matching the
	// "Match N" label printed on the Excel tree sheet. 0 means unset; for a
	// BracketMatch that is a hidden/bye placeholder, or a legacy bracket saved
	// before numbering was assigned.
	MatchNumber int `json:"matchNumber,omitempty"`
	// Decision-type metadata mirrors MatchResult so an elimination-stage
	// kiken/fusenpai/encho is reconstructable from bracket.json alone
	// (label rendering, Excel export, SSE replays).
	Decision       string         `json:"decision,omitempty"`
	DecisionBy     string         `json:"decisionBy,omitempty"`
	DecisionReason string         `json:"decisionReason,omitempty"`
	Encho          *EnchoMetadata `json:"encho,omitempty"`
	// DecidedByHantei mirrors MatchResult.DecidedByHantei for bracket reads.
	// YAML tag included for parity with MatchResult and future YAML-serialised contexts.
	DecidedByHantei bool `json:"decidedByHantei,omitempty" yaml:"decided_by_hantei,omitempty"`
	// SubResults persists per-bout results for team bracket matches so the
	// score editor can restore hantei state and bout-level detail on re-open.
	SubResults []SubMatchResult `json:"subResults,omitempty"`
	// ResultSource mirrors MatchResult.ResultSource for bracket matches.
	ResultSource string `json:"resultSource,omitempty"`
	// CorrectionReason mirrors MatchResult.CorrectionReason for bracket
	// matches, persisted in bracket.json for audit. Set when an operator
	// overwrites a completed result (correction), omitted on first completion.
	CorrectionReason string `json:"correctionReason,omitempty"`
	// FlagsA / FlagsB mirror MatchResult.FlagsA/FlagsB for engi (kata
	// demonstration) bracket bouts, persisted in bracket.json so the flag
	// counts survive a restart. Zero for non-engi matches.
	FlagsA int `json:"flagsA,omitempty"`
	FlagsB int `json:"flagsB,omitempty"`
	// Display metadata (mp-7f2w); additive, computed at generation time so the
	// viewer can render the bracket with the SAME effective-round columns as the
	// printed Excel Tree sheet (matches grouped by depth-from-root, structural
	// byes skipping a column) instead of the balanced pow2 rounds. These fields
	// are purely for rendering; the resolution/scoring/scheduling logic continues
	// to use the positional ID + "Winner of rX-mY" scheme unchanged.
	//
	// DisplayRound is the effective round counted from the final (1 = Final,
	// 2 = Semifinal, …). 0 means unset; either a legacy bracket generated before
	// this field existed (viewer falls back to positional rendering) or a Hidden
	// phantom match. Hidden marks a structural-bye match (empty-vs-empty dead
	// match, or a latent bye where one side never had an opponent) that is not a
	// real bout and must not be drawn as a match card. Feeders holds the IDs of
	// the two real feeder matches whose winners meet here, in [A, B] order; an
	// empty string means that side is a seeded entrant / bye (no connector line).
	DisplayRound int      `json:"displayRound,omitempty"`
	Hidden       bool     `json:"hidden,omitempty"`
	Feeders      []string `json:"feeders,omitempty"`
	// ModifiedAt mirrors MatchResult.ModifiedAt (mp-y3nk): the server-relative
	// unix-millis timestamp of the last change to this bracket match's result,
	// persisted in bracket.json so timestamp reconciliation survives a restart.
	// 0 = unstamped/legacy: arrival-order, still applies (never dropped). See
	// domain.ApplyByTimestamp.
	ModifiedAt int64 `json:"modifiedAt,omitempty"`
}

type BulkCheckInResult struct {
	CheckedIn        int      `json:"checkedIn"`
	AlreadyCheckedIn int      `json:"alreadyCheckedIn"`
	NotFound         []string `json:"notFound"`
}

type Competition struct {
	ID                   string            `yaml:"id" json:"id"`
	Name                 string            `yaml:"name" json:"name"`
	Kind                 string            `yaml:"kind" json:"kind"`
	Format               string            `yaml:"format" json:"format"`
	PoolFormat           string            `yaml:"pool_format,omitempty" json:"poolFormat,omitempty"` // "full" (default) | "partial"
	TeamSize             int               `yaml:"team_size" json:"teamSize"`
	PoolSize             int               `yaml:"pool_size" json:"poolSize"`
	PoolSizeMode         string            `yaml:"pool_size_mode" json:"poolSizeMode"`
	PoolWinners          int               `yaml:"pool_winners" json:"poolWinners"`
	RoundRobin           bool              `yaml:"round_robin" json:"roundRobin"`
	Courts               []string          `yaml:"courts" json:"courts"`
	StartTime            string            `yaml:"start_time" json:"startTime"`
	Date                 string            `yaml:"date" json:"date"`
	Status               CompetitionStatus `yaml:"status" json:"status"`
	Mirror               bool              `yaml:"mirror" json:"mirror"`
	WithZekkenName       bool              `yaml:"with_zekken_name" json:"withZekkenName"`
	NumberPrefix         string            `yaml:"number_prefix,omitempty" json:"numberPrefix,omitempty"`
	HasParticipantIDs    bool              `yaml:"has_participant_ids,omitempty" json:"hasParticipantIDs,omitempty"`
	PoolMatchDuration    int               `yaml:"pool_match_duration,omitempty" json:"poolMatchDuration,omitempty"`
	PlayoffMatchDuration int               `yaml:"playoff_match_duration,omitempty" json:"playoffMatchDuration,omitempty"`
	// MaxEnchoPeriods caps how many encho (overtime) periods one match
	// may run before the operator must call daihyosen. Zero means
	// unlimited (FIK general default). T104, CHK029.
	MaxEnchoPeriods int `yaml:"max_encho_periods,omitempty" json:"maxEnchoPeriods,omitempty"`

	// TeamMatchType selects the team-match format (FR-044). Empty value
	// is treated as TeamMatchTypeFixed for backward compatibility; all
	// N×1 bouts are pre-scheduled by position. TeamMatchTypeKachinuki
	// schedules only the first bout; subsequent bouts are derived
	// dynamically from prior bout outcomes ("winner stays on"). See
	// engine/kachinuki.go for the advancement semantics. Ignored when
	// TeamSize is 0 (individual competitions).
	TeamMatchType TeamMatchType `yaml:"team_match_type,omitempty" json:"teamMatchType,omitempty"`

	// Legacy single-phase duration. Captured at unmarshal time and used by
	// ApplyCompetitionDefaults to populate the per-phase fields above when
	// they are zero. Not persisted on save; only here so older YAML files
	// round-trip through the new schema.
	MatchDuration int `yaml:"match_duration,omitempty" json:"matchDuration,omitempty"`

	// SwissRounds is the number of rounds played in a Swiss-format
	// competition (FR-050a). Ignored when Format != CompFormatSwiss.
	// Persisted so resuming a Swiss tournament reads the same round
	// budget on subsequent loads.
	SwissRounds int `yaml:"swiss_rounds,omitempty" json:"swissRounds,omitempty"`

	// SwissCurrentRound tracks which round has been generated so far
	// (FR-050d). 0 = not started; the value increments after each
	// successful GenerateSwissRound. Used by the "Generate next round"
	// gate to refuse re-generation of an in-progress round.
	SwissCurrentRound int `yaml:"swiss_current_round,omitempty" json:"swissCurrentRound,omitempty"`

	// Naginata selects the Naginata ippon set for this competition.
	// When true, the score editor offers an extra "S" (Sune) button
	// in addition to the standard M/K/D/T/H set. Default false = Kendo.
	Naginata bool `yaml:"naginata,omitempty" json:"naginata"`

	// Engi selects flag-scoring (Engi-kyogi / kata competition) mode for this
	// competition. When true, bouts are decided by referee flag counts
	// (FlagsA/FlagsB) instead of ippon waza letters, and standings rank by
	// wins then accumulated own-side flags. Independent of the Naginata flag;
	// engi has no ippons or Sune. Supports all formats (pools, league, knockout,
	// mixed). Locked after draw like Naginata. Default false = ippon-scored.
	//
	// Engi competitors are PAIRS (two member names, one shared dojo). On the Go
	// side a pair is a single competitor whose Player.Name holds BOTH member
	// names combined as "Name 1 - Name 2"; Player.Dojo holds the shared dojo.
	// Engi does not alter the participant CSV layout: when WithZekkenName is
	// set, Player.DisplayName carries the combined pair zekken
	// ("ZEKKEN1 - ZEKKEN2") exactly like any other competition.
	Engi bool `yaml:"engi,omitempty" json:"engi"`

	CheckInEnabled bool `yaml:"check_in_enabled,omitempty" json:"checkInEnabled,omitempty"`

	FightingSpiritAwards []FightingSpiritAward `yaml:"fighting_spirit_awards,omitempty" json:"fightingSpiritAwards,omitempty"`

	// LeagueTiebreakTopN is the highest finishing position (rank) whose ties must
	// be broken before league play can finish, so a league earns its top
	// placements like a bracket instead of completing with an unearned tie. It is
	// operator-settable (3 or 4) only for TEAM leagues; INDIVIDUAL leagues are not
	// given the control and use the default band (3) via effectiveTopN. Team
	// leagues break ties with a daihyosen (LeagueTiebreakCandidates); individual
	// leagues break them with an ippon-shobu bout (tieNeedsIndividualBreak ->
	// InjectTiebreakerMatches). Allowed explicit values are 3 (default) and 4.
	//
	// A "consequential" tied group is one whose position range intersects the
	// band [1..LeagueTiebreakTopN]; i.e. its best (lowest-numbered) position is
	// ≤ TopN. For example, with TopN=3 a tie involving teams at positions 1–2 is
	// consequential (it affects who wins or is runner-up), but a tie at positions
	// 4–5 is not. When the best-placed team in a tied group finishes WORSE than
	// position TopN (its top position is strictly greater than TopN, so the whole
	// group sits below the band), the group is non-consequential and no
	// tie-breaker is needed.
	//
	// The kendo convention of two joint 3rd places interacts here: when
	// LeagueTwoThirdPlaces is true and TopN is 3 or 4, a tied group that sits
	// ENTIRELY at position 3 or below does not need a 3rd-vs-4th decider;
	// both teams are awarded 3rd place and the group is non-consequential.
	// Zero is treated as the default (3) for a team league (Format == "league"
	// && Kind == "team") at draw time.
	LeagueTiebreakTopN int `yaml:"league_tiebreak_top_n,omitempty" json:"leagueTiebreakTopN,omitempty"`

	// LeagueTwoThirdPlaces controls whether two (or more) joint 3rd places are
	// awarded when competitors tie at the 3rd-position boundary. Applies to ALL
	// leagues (team AND individual); the standard kendo convention enables it,
	// naginata leaves it off (single 3rd).
	//
	// Two effects:
	//   - Standings rank (all leagues): a genuine tied group whose best position
	//     is 3rd or lower is given a SHARED rank (e.g. 3,3) rather than arbitrary
	//     sequential ranks, so the standings table and the closing-ceremony podium
	//     show joint 3rd places instead of relabeling the 4th finisher. See
	//     CalculatePoolStandings (engine/scoring.go).
	//   - Team-league tie-breaker gating: a tied group whose ENTIRE position range
	//     falls at position ≥ 3 is treated as non-consequential (both receive 3rd
	//     place, no bronze decider). See isConsequentialTie (engine).
	//
	// When false (default), all ties within [1..LeagueTiebreakTopN] are
	// consequential and may require a tie-breaker, and the podium shows a single
	// 3rd place.
	LeagueTwoThirdPlaces bool `yaml:"league_two_third_places,omitempty" json:"leagueTwoThirdPlaces,omitempty"`

	// LeagueTiebreakFinalized is set to true by the operator via
	// POST /api/competitions/:id/league-tiebreak/finalize to accept the
	// current standings as final without running a tie-breaker. When true,
	// LeagueTiebreakCandidates returns an empty slice (even if consequential
	// ties remain), which allows MaybeAutoCompletePools to transition the
	// competition to CompStatusComplete. Phase 3b.
	LeagueTiebreakFinalized bool `yaml:"league_tiebreak_finalized,omitempty" json:"leagueTiebreakFinalized,omitempty"`

	Players []domain.Player `yaml:"-" json:"players"`
}

type CompetitionStatus string

type CourtOccupancy struct {
	CompID  string
	MatchID string
}

type EnchoMetadata struct {
	PeriodCount int `json:"periodCount" yaml:"periodCount"`
}

type FightingSpiritAward struct {
	Title         string `yaml:"title" json:"title"`
	RecipientName string `yaml:"recipient_name" json:"recipientName"`
	RecipientDojo string `yaml:"recipient_dojo,omitempty" json:"recipientDojo,omitempty"`
}

type LoadParticipantsOpts struct {
	WithSeeds bool  // set false to skip the seeds.csv read (hot list paths)
	HasIDs    *bool // nil = auto-detect from first line; non-nil uses cached Competition.HasParticipantIDs
}

type MatchResult struct {
	ID     string `json:"id"`
	SideA  string `json:"sideA"` // Player/Team Name
	SideB  string `json:"sideB"`
	Winner string `json:"winner"`
	// SideAID/SideBID/WinnerID carry the participant UUID for each side and
	// the winner when available. Sides are stored by name everywhere else,
	// but a name is not unique within a competition; two participants from
	// different dojos may share a name (CheckDuplicateEntriesByNameDojo only
	// rejects same-name AND same-dojo). These ids let consumers (e.g. the
	// league matrix) cross-reference a match cell to the right row/column
	// player AND tell apart the winner when two identical-name players meet.
	// Purely additive metadata: all Go scoring/standings logic still keys on
	// name, and these stay empty for legacy data, so behavior is unchanged
	// when ids are absent. omitempty + append-only CSV columns keep old
	// files/readers fully compatible.
	SideAID  string `json:"sideAId,omitempty"`
	SideBID  string `json:"sideBId,omitempty"`
	WinnerID string `json:"winnerId,omitempty"`
	// WinnerSide is a transient hint ("A"/"B") set by scoring handlers that
	// know the winning SIDE unambiguously (e.g. quick-score, where the
	// winner is decided by ippon counts, not a name). writeMatchResult uses
	// it to resolve WinnerID from the stored side ids even when both sides
	// share a name. Never persisted (json/CSV omit); it only carries the
	// side decision from the handler to the id-resolution step.
	WinnerSide     string           `json:"-" yaml:"-"`
	IpponsA        []string         `json:"ipponsA"` // waza letters M/K/D/T/H/S (naginata), or ○ (FIK default-win marker)
	IpponsB        []string         `json:"ipponsB"`
	HansokuA       int              `json:"hansokuA"`
	HansokuB       int              `json:"hansokuB"`
	Decision       string           `json:"decision"`
	DecisionBy     string           `json:"decisionBy,omitempty"`
	DecisionReason string           `json:"decisionReason,omitempty"`
	Status         MatchStatus      `json:"status"`
	Court          string           `json:"court"`
	Round          int              `json:"round" yaml:"round"`
	ScheduledAt    string           `json:"scheduledAt"`
	SubResults     []SubMatchResult `json:"subResults,omitempty"`
	Encho          *EnchoMetadata   `json:"encho,omitempty" yaml:"encho,omitempty"`
	QueuePosition  int              `json:"queuePosition,omitempty" yaml:"-"`
	// DecidedByHantei is true when the winner was declared by referee
	// hantei on a tied bout (FIK Article 7-5 / 29-6). Overtime is not a
	// precondition: a tied scoreline may be taken straight to a judges'
	// decision. Distinguishes a judges' decision from an ippon-derived win
	// for stats, audit, and display. Zero value omitted from the wire.
	//
	// Pointer semantics at the API boundary: when a client omits the
	// field (nil) on a BRACKET-match score request, the engine preserves
	// whatever value is already stored; when the client explicitly sends
	// true or false the engine applies it. This prevents a re-score that
	// doesn't mention the flag from silently clearing a previously-
	// recorded hantei decision.
	//
	// Preserve-on-nil applies ONLY to bracket matches (see
	// engine/scoring.go:recordBracketMatchResult and
	// engine/scoring_tx.go's bracket commit branch; both gate the
	// assignment on result.DecidedByHantei != nil). Pool matches are
	// merged with `*r = *result`, so a nil pointer there will clear any
	// stored value. This is acceptable in practice because FIK rules
	// don't permit hantei in pool play (see persistence caveat below).
	//
	// On READ paths that project BracketMatch.DecidedByHantei (bool) back
	// into MatchResult for SSE / HTTP responses, use HanteiPtr below so
	// non-hantei matches emit nil (omitempty), keeping the wire payload
	// minimal and signalling "no hantei" by absence rather than an
	// explicit false.
	//
	// Persistence caveat: pool matches are stored in pool-matches.csv,
	// whose column layout does NOT include this field; so a hantei
	// decision on a pool match survives in-memory and on the SSE wire,
	// but does NOT survive a server restart. Bracket matches are stored
	// in bracket.json, which serializes the full struct, so the flag
	// survives there. See BracketMatch.DecidedByHantei for the mirror;
	// pool-level hantei is a rare-enough case (FIK doesn't normally
	// allow it in pool play) that the gap is acceptable. The yaml tag
	// is retained for future YAML-serialised contexts.
	DecidedByHantei *bool `json:"decidedByHantei,omitempty" yaml:"decided_by_hantei,omitempty"`
	// ResultSource records how the result was submitted: "admin" (operator with
	// password), "self-reported" (participant in self-run mode), or "" (legacy/
	// unset). Set by the score handler; omitted from wire when empty.
	ResultSource string `json:"resultSource,omitempty" yaml:"result_source,omitempty"`
	// CorrectionReason is a mandatory audit justification when an operator
	// overwrites a completed match result. Format: "<category>: <note>" (e.g.
	// "Scoring error: wrong waza entered"). Only required on corrections
	// (completed → completed); omitted on first completions. Append-only CSV
	// column (rec index 19, the 20th column, after the original 19) and the
	// bracket.json field keep older files fully compatible.
	CorrectionReason string `json:"correctionReason,omitempty" yaml:"correction_reason,omitempty"`
	// RepPlayerA / RepPlayerB name the individual competitor each TEAM fields
	// for a pool/league daihyosen or tiebreaker rep bout ("Pool X-DH-N" /
	// "Pool X-TB-N"). For those bouts SideA/SideB hold the TEAM names (the
	// standings entries are teams), so the actual fighters can't be recovered
	// from the sides alone. The operator records them in the rep-bout scorer
	// (picked from each team's roster) and the per-court display shows the rep
	// player above the team name. Empty for every non-supplementary match.
	// Append-only CSV columns (rec index 20/21, after CorrectionReason at 19)
	// keep older pool-matches.csv files fully compatible. (mp-62vr)
	RepPlayerA string `json:"repPlayerA,omitempty" yaml:"rep_player_a,omitempty"`
	RepPlayerB string `json:"repPlayerB,omitempty" yaml:"rep_player_b,omitempty"`
	// FlagsA / FlagsB are the referee flag counts per side for engi (kata
	// demonstration) bouts. Storage only; kendo scoring never reads or writes
	// them. For pool matches they survive a restart via append-only trailing CSV
	// columns (rec index 22/23, after RepPlayerB at 20/21); older files with the
	// columns absent load as 0. Bracket matches persist fine via bracket.json.
	FlagsA int `json:"flagsA,omitempty" yaml:"flags_a,omitempty"`
	FlagsB int `json:"flagsB,omitempty" yaml:"flags_b,omitempty"`
	// Rev is a client-monotonic revision counter carried on "running"-status
	// autosave writes. The server uses it (scoped to RevSession) to drop stale
	// in-flight writes that arrive out of order after a reconnect flush
	// (C2 rev-guard). It is wire-only: never serialized to CSV (no column) nor
	// to bracket.json (which uses BracketMatch), and yaml:"-" keeps it out of
	// config persistence. A plain value copy of MatchResult carries it in
	// memory, which is harmless. Defaulting to 0 (omitempty) means a payload
	// without the field is treated as unversioned and always proceeds.
	Rev int64 `json:"rev,omitempty" yaml:"-"`
	// RevSession identifies the client scoring session (one per page load,
	// random). The rev-guard compares Rev ONLY within the same RevSession; a
	// write from a new session (page reload / different device) always takes
	// over rather than being dropped as stale against a high-water mark left
	// by a prior session. Same wire-only persistence guarantees as Rev.
	RevSession string `json:"revSession,omitempty" yaml:"-"`
	// ModifiedAt is the SERVER-RELATIVE unix-millis timestamp of the last change
	// to this match's result-bearing fields (mp-y3nk timestamp reconciliation).
	// Clients stamp each score/override write with server-relative time (learned
	// via GET /api/time). Timestamp last-write-wins currently applies to the
	// BRACKET write path only: for a bracket match the handler drops a write
	// whose ModifiedAt is older than the stored value (so a reconnecting offline
	// court's stale change never overwrites a newer one), and it is persisted in
	// bracket.json (see BracketMatch.ModifiedAt) so the comparison survives a
	// restart. For POOL matches this field is wire-only: it is NOT written to
	// pool-matches.csv and NOT yet used for reconciliation (a scoped follow-up),
	// so it resets to 0 on restart and pool writes keep arrival-order behavior.
	// The completed-never-reverted guard stays on top regardless. 0
	// (absent/legacy) means "unstamped": it is treated as arrival-order and still
	// APPLIES (it does NOT lose to a stamped write), so old files and un-stamped
	// clients behave exactly as before rather than having a legitimate change
	// silently dropped. See domain.ApplyByTimestamp.
	ModifiedAt int64 `json:"modifiedAt,omitempty" yaml:"-"`
}

type MatchStatus string

type Overrides struct {
	PoolRanks map[string]map[string]int `json:"poolRanks"` // PoolID -> PlayerName -> Rank
	Winners   map[string]string         `json:"winners"`   // MatchID -> WinnerName
}

type PlayerStanding struct {
	Player           domain.Player `json:"player"`
	Wins             int           `json:"wins"`
	Losses           int           `json:"losses"`
	Draws            int           `json:"draws"`
	IpponsGiven      int           `json:"ipponsGiven"`
	IpponsTaken      int           `json:"ipponsTaken"`
	Points           int           `json:"points"`
	ScoreSummary     string        `json:"scoreSummary,omitempty"`
	Rank             int           `json:"rank"`
	IsOverridden     bool          `json:"isOverridden"`
	IndividualWins   int           `json:"individualWins,omitempty"`
	IndividualLosses int           `json:"individualLosses,omitempty"`
	IndividualDraws  int           `json:"individualDraws,omitempty"`
	PointsWon        int           `json:"pointsWon,omitempty"`
	PointsLost       int           `json:"pointsLost,omitempty"`
	Tied             bool          `json:"tied,omitempty"`
	// Flags is the total accumulated own-side referee flags for engi (kata
	// demonstration) standings. A dedicated field, NOT an overload of
	// IpponsGiven, so the wire stays self-describing (wins vs flags as distinct
	// columns). Zero for non-engi competitions (omitempty drops it).
	Flags int `json:"flags,omitempty"`
}

type ScheduleEntry struct {
	MatchType   string `json:"matchType"` // pool | bracket | break
	MatchRef    string `json:"matchRef"`  // ID of the match (empty for breaks)
	Court       string `json:"court"`
	Date        string `json:"date"`        // DD-MM-YYYY (matches Tournament.Date / Competition.Date canonical), reserved for future multi-day tournament use
	ScheduledAt string `json:"scheduledAt"` // HH:MM
	Status      string `json:"status"`
	IsBreak     bool   `json:"isBreak,omitempty"`
	Label       string `json:"label,omitempty"` // display label for breaks
}

type Sponsor struct {
	Name string `yaml:"name" json:"name"`
	File string `yaml:"file" json:"file"`
	Link string `yaml:"link,omitempty" json:"link,omitempty"`
}

type Store struct {
	// contains filtered or unexported fields
}

type StoreTx interface {
	LoadCompetition(compID string) (*Competition, error)
	SaveCompetition(c *Competition) error
	LoadPools(compID string) ([]helper.Pool, error)
	SavePools(compID string, pools []helper.Pool) error
	LoadPoolMatches(compID string) ([]MatchResult, error)
	SavePoolMatches(compID string, matches []MatchResult) error
	LoadBracket(compID string) (*Bracket, error)
	SaveBracket(compID string, b *Bracket) error
	LoadCompetitorStatus(compID string) (map[string]domain.CompetitorStatus, error)
	SetCompetitorStatus(compID string, status domain.CompetitorStatus) error
	LoadTeamLineups(compID string) (map[string]domain.TeamLineup, error)
	SetTeamLineup(compID string, l domain.TeamLineup, teamSize int) error
	LoadParticipants(compID string, withZekkenName bool) ([]domain.Player, error)

	// UpdatePoolMatchByID is the tx-aware twin of
	// Store.UpdatePoolMatchByID. Same semantics, same return values; the
	// only difference is that it skips re-acquiring the per-comp lock
	// (already held by WithTransaction). Score / decision handlers (T156)
	// use this to keep their match-result write under the SAME lock
	// acquire as the competitor-status side effects.
	UpdatePoolMatchByID(compID, matchID string, mutate func(*MatchResult)) (bool, error)
	// UpdateBracket is the tx-aware twin of Store.UpdateBracket. The
	// mutate closure may modify the bracket arbitrarily and signal "match
	// not found" by returning an error (typically wrapping the engine's
	// match-not-found sentinel, see engine.withBracketMatch).
	UpdateBracket(compID string, mutate func(*Bracket) error) error
	// UpdateParticipant is the tx-aware twin of
	// Store.updateParticipantNoLock. Applies transform to the target
	// participant while the transaction lock is held, so the caller
	// can serialise a competition-status pre-check (via LoadCompetition
	// in the same tx body) and the participant write under one lock
	// acquire. Participants.csv and seeds.csv are written directly via
	// atomic rename, they are not staged through the WAL, but each
	// write is individually crash-safe, and no other WAL-staged file
	// is touched by this path, so cross-file atomicity is not required.
	UpdateParticipant(compID, pid string, withZekkenName bool, transform func(*domain.Player) error) (*domain.Player, error)
}

type SubMatchResult struct {
	Position        int            `json:"position"`
	SideA           string         `json:"sideA"`
	SideB           string         `json:"sideB"`
	IpponsA         []string       `json:"ipponsA"`
	IpponsB         []string       `json:"ipponsB"`
	HansokuA        int            `json:"hansokuA"`
	HansokuB        int            `json:"hansokuB"`
	Winner          string         `json:"winner"`
	Decision        string         `json:"decision"`
	DecidedByHantei bool           `json:"decidedByHantei,omitempty" yaml:"decided_by_hantei,omitempty"`
	Encho           *EnchoMetadata `json:"encho,omitempty"           yaml:"encho,omitempty"`
}

type TeamMatchType string

type TeamResultLine struct {
	ShiroIV int `json:"shiroIV"`
	AkaIV   int `json:"akaIV"`
	ShiroPW int `json:"shiroPW"`
	AkaPW   int `json:"akaPW"`
}

type Theme struct {
	PrimaryColor    string `yaml:"primary_color,omitempty"    json:"primaryColor,omitempty"`
	AccentSoftColor string `yaml:"accent_soft_color,omitempty" json:"accentSoftColor,omitempty"`
	WindowTitle     string `yaml:"window_title,omitempty"      json:"windowTitle,omitempty"`
	LogoPath        string `yaml:"logo_path,omitempty"         json:"-"` // disk filename; served via /api/branding/logo
}

type Tournament struct {
	Name     string   `yaml:"name" json:"name"`
	Date     string   `yaml:"date" json:"date"`
	Venue    string   `yaml:"venue" json:"venue"`
	Courts   []string `yaml:"courts" json:"courts"`
	Password string   `yaml:"password" json:"password"`

	// DurationDays is the number of consecutive calendar days this
	// tournament spans, starting from Date (Day 1). Default 1 (single-day).
	// Maximum 30. Use Days() to obtain the derived per-day DD-MM-YYYY list.
	//
	// omitempty drops the field only when the value is 0 (Go's zero value),
	// never when it is 1; so tournaments saved by this code always persist
	// an explicit duration_days. The omitempty matters in the reverse
	// direction: legacy tournament.md files predating this field carry no
	// duration_days key, so they deserialize to 0 and are migrated to 1 by
	// the load path (and ApplyTournamentDefaults).
	DurationDays int `yaml:"duration_days,omitempty" json:"durationDays,omitempty"`

	// AdminPassword gates destructive operations (spec 004 / mp-e21):
	// competition delete, draw/override/invalidate, and participant roster
	// mutations. It is a SEPARATE, higher-privilege credential from
	// Password (which gates the API as a whole).
	//
	// CRITICAL: it is WRITE-ONLY at the API boundary; `json:"-"` means it
	// is never emitted in any response AND never populated by binding a
	// request body into a Tournament. That is the opposite of Password
	// (which is a peer of the credential gating /tournament, so returning
	// it is harmless). AdminPassword is HIGHER privilege than that gate, so
	// leaking it via GET; or letting a main-password holder overwrite it
	// via the bulk PUT; would collapse the separation. It is set only via
	// the dedicated, elevated-gated PUT /api/auth/admin-password handler.
	// File mode only; in locked mode the env-var bcrypt hash is
	// authoritative and any on-disk value here is inert.
	AdminPassword string `yaml:"admin_password,omitempty" json:"-"`

	// Ceremony blocks expressed as human duration strings (e.g. "30m",
	// "1h"). When set, the auto-scheduler reserves a contiguous range
	// at the appropriate point in the day and skips match slots that
	// would land inside it. Optional; zero/empty means no block.
	// FR-056, R9, data-model §6.
	OpeningBlock string `yaml:"opening_block,omitempty" json:"openingBlock,omitempty"`
	LunchBlock   string `yaml:"lunch_block,omitempty" json:"lunchBlock,omitempty"`
	ClosingBlock string `yaml:"closing_block,omitempty" json:"closingBlock,omitempty"`

	// ClockToElapsedMultiplier scales the on-clock match duration to
	// "real elapsed minutes"; coin tosses, scoring transitions, salutes
	// and crossings, etc. Defaults to 1.5 via ApplyTournamentDefaults
	// when zero. FR-055, R9.
	ClockToElapsedMultiplier float64 `yaml:"clock_to_elapsed_multiplier,omitempty" json:"clockToElapsedMultiplier,omitempty"`

	// SlowestCourtBufferPct is the % buffer added when distributing total
	// elapsed minutes across N parallel courts; the slowest court usually
	// runs longer than the mean. Defaults to 10 via ApplyTournamentDefaults
	// when zero. FR-057, R9.
	SlowestCourtBufferPct int `yaml:"slowest_court_buffer_pct,omitempty" json:"slowestCourtBufferPct,omitempty"`

	// Mode selects the auth posture for the whole tournament, chosen at
	// creation and IMMUTABLE thereafter (mp-7h7). "officiated" (default)
	// gates the full admin surface behind X-Tournament-Password.
	// "self-run" inverts the boundary: constructive actions (scoring,
	// check-in, start/complete) are public; only destructive actions
	// (those already gated by RequireElevatedPassword / enforceElevated)
	// still require X-Admin-Password. omitempty means older tournament.md
	// files (Mode == "") normalise to "officiated" via ApplyTournamentDefaults.
	Mode string `yaml:"mode,omitempty" json:"mode,omitempty"`

	// Public tournament info fields (mp-ef3). All optional (omitempty).
	// Rendered read-only on the viewer home page; editable in the admin setup form.
	// PublicURL is the externally-shareable base URL for this tournament (mp-s1gl).
	// When set it overrides window.location.origin for QR codes and share links.
	PublicURL    string              `yaml:"public_url,omitempty" json:"publicURL,omitempty"`
	VenueAddress string              `yaml:"venue_address,omitempty" json:"venueAddress,omitempty"`
	VenueMapURL  string              `yaml:"venue_map_url,omitempty" json:"venueMapURL,omitempty"`
	OpeningTime  string              `yaml:"opening_time,omitempty" json:"openingTime,omitempty"`
	ClosingTime  string              `yaml:"closing_time,omitempty" json:"closingTime,omitempty"`
	WebsiteURL   string              `yaml:"website_url,omitempty" json:"websiteURL,omitempty"`
	AwardsNote   string              `yaml:"awards_note,omitempty" json:"awardsNote,omitempty"`
	InfoNotes    string              `yaml:"info_notes,omitempty" json:"infoNotes,omitempty"`
	Contacts     []TournamentContact `yaml:"contacts,omitempty" json:"contacts,omitempty"`

	// RulesURLLegacy captures the pre-rename `rules_url` YAML key from
	// tournament.md files written before the field was renamed to
	// website_url. It is migrated into WebsiteURL by ApplyTournamentDefaults
	// and is never emitted on the wire (json:"-") nor re-persisted (the
	// migration clears it, so omitempty drops the old key on the next save).
	// Field-based capture + migrate keeps the change additive: no custom
	// Tournament.UnmarshalYAML that would have to enumerate every field.
	RulesURLLegacy string `yaml:"rules_url,omitempty" json:"-"`

	// Sponsors is the ordered list of sponsor banners shown on the public
	// viewer home page only (the /display TV/lobby surfaces intentionally
	// omit them; mp-c38/mp-vb3u). Stored as omitempty so legacy tournament.md
	// files without sponsors round-trip cleanly (no `sponsors: []` key emitted).
	Sponsors []Sponsor `yaml:"sponsors,omitempty" json:"sponsors,omitempty"`

	// Theme holds optional branding overrides: custom accent colors and a
	// tournament logo (mp-scf). All fields are omitempty so existing
	// tournament.md files without a theme block round-trip cleanly.
	Theme *Theme `yaml:"theme,omitempty" json:"theme,omitempty"`
}

type TournamentContact struct {
	Label string `yaml:"label" json:"label"`
	Value string `yaml:"value" json:"value"`
}