166 lines
8.7 KiB
Markdown
166 lines
8.7 KiB
Markdown
---
|
|
phase: 01-tournament-engine
|
|
plan: 09
|
|
subsystem: api, tournament, financial
|
|
tags: [tournament-lifecycle, multi-tournament, icm, chop, deal, malmuth-harville, monte-carlo, lobby]
|
|
|
|
# Dependency graph
|
|
requires:
|
|
- phase: 01-tournament-engine/04
|
|
provides: Clock engine with registry, ticker, state machine
|
|
- phase: 01-tournament-engine/06
|
|
provides: Financial engine with transactions, prize pool, payouts
|
|
- phase: 01-tournament-engine/07
|
|
provides: Player management, rankings, buy-in flow
|
|
- phase: 01-tournament-engine/08
|
|
provides: Seating engine with tables, balancing, break table
|
|
provides:
|
|
- Tournament lifecycle service (create, start, pause, resume, end, cancel, auto-close)
|
|
- Multi-tournament manager with lobby view (MULTI-01, MULTI-02)
|
|
- ICM calculator (exact Malmuth-Harville for <=10, Monte Carlo for 11+)
|
|
- Chop/deal engine (ICM, chip chop, even chop, custom, partial chop)
|
|
- Tournament state aggregation for WebSocket connect
|
|
- Activity feed from audit trail
|
|
- Tournament API routes with deal proposal workflow
|
|
- Deal proposals migration (007_deal_proposals.sql)
|
|
affects: [01-11, 01-12, 01-14, phase-02]
|
|
|
|
# Tech tracking
|
|
tech-stack:
|
|
added: []
|
|
patterns: [tournament-scoped-state, template-first-creation, local-copy-semantics, proposal-confirm-workflow, icm-dispatcher-pattern]
|
|
|
|
key-files:
|
|
created:
|
|
- internal/tournament/tournament.go
|
|
- internal/tournament/state.go
|
|
- internal/tournament/multi.go
|
|
- internal/financial/icm.go
|
|
- internal/financial/chop.go
|
|
- internal/server/routes/tournaments.go
|
|
- internal/store/migrations/007_deal_proposals.sql
|
|
- internal/financial/icm_test.go
|
|
- internal/financial/chop_test.go
|
|
- internal/tournament/tournament_test.go
|
|
- internal/tournament/integration_test.go
|
|
modified: []
|
|
|
|
key-decisions:
|
|
- "ICM dispatcher: exact Malmuth-Harville for <=10 players, Monte Carlo (100K iterations) for 11+"
|
|
- "Deal proposal/confirm workflow: ProposeDeal returns preview, ConfirmDeal applies payouts"
|
|
- "Full chop sets all players to 'deal' status and completes tournament; partial chop continues play"
|
|
- "Integration tests use file-based DB with WAL mode for clock ticker goroutine compatibility"
|
|
- "Tournament auto-close: 1 remaining = end, 0 remaining = cancel"
|
|
|
|
patterns-established:
|
|
- "Tournament-scoped state: all state (clock, players, tables, financials) keyed by tournament_id"
|
|
- "Template-first creation: CreateFromTemplate loads expanded template, applies overrides, copies all refs"
|
|
- "Proposal-confirm pattern: deal proposals are stored, reviewed, then confirmed or cancelled"
|
|
- "ICM dispatcher pattern: CalculateICM auto-selects exact vs Monte Carlo based on player count"
|
|
- "Activity feed: audit entries converted to human-readable ActivityEntry structs"
|
|
|
|
requirements-completed: [MULTI-01, MULTI-02, FIN-11, SEAT-06]
|
|
|
|
# Metrics
|
|
duration: 25min
|
|
completed: 2026-03-01
|
|
---
|
|
|
|
# Plan 09: Tournament Lifecycle + Multi-Tournament + Chop/Deal Summary
|
|
|
|
**Full tournament lifecycle (create/start/pause/resume/end/cancel/auto-close) with multi-tournament lobby, ICM calculator (exact + Monte Carlo), and chop/deal engine supporting 5 deal types**
|
|
|
|
## Performance
|
|
|
|
- **Duration:** ~25 min
|
|
- **Started:** 2026-03-01T07:45:00Z
|
|
- **Completed:** 2026-03-01T08:10:00Z
|
|
- **Tasks:** 2
|
|
- **Files created:** 11
|
|
|
|
## Accomplishments
|
|
- Tournament lifecycle service with all state transitions, template-first creation with local copy semantics, and auto-close on last player standing
|
|
- Multi-tournament manager enabling lobby view with independent state per tournament (clocks, financials, players, tables)
|
|
- ICM calculator with exact Malmuth-Harville algorithm (<=10 players, <2ms) and Monte Carlo simulation (11+ players, 100K iterations, <25ms)
|
|
- Chop/deal engine with 5 deal types (ICM, chip chop, even chop, custom, partial chop) and proposal/confirm workflow
|
|
- 31 new tests across 4 test files: 12 ICM, 6 chop, 9 tournament unit, 4 integration
|
|
|
|
## Task Commits
|
|
|
|
Each task was committed atomically:
|
|
|
|
1. **Task I1: Tournament lifecycle and multi-tournament management** - `75ccb6f` (feat)
|
|
2. **Task I2: ICM calculator, chop/deal engine, and comprehensive tests** - `2958449` (test)
|
|
|
|
## Files Created/Modified
|
|
- `internal/tournament/tournament.go` - Tournament service: create from template, start, pause, resume, end, cancel, auto-close, list
|
|
- `internal/tournament/state.go` - State aggregation for WebSocket snapshots and activity feed
|
|
- `internal/tournament/multi.go` - Multi-tournament manager with lobby view, active tournament listing
|
|
- `internal/financial/icm.go` - ICM calculator: exact Malmuth-Harville + Monte Carlo dispatcher
|
|
- `internal/financial/chop.go` - Chop engine: 5 deal types, proposal/confirm workflow, position assignment
|
|
- `internal/server/routes/tournaments.go` - Tournament API routes: CRUD, lifecycle, deal proposals
|
|
- `internal/store/migrations/007_deal_proposals.sql` - Deal proposals table migration
|
|
- `internal/financial/icm_test.go` - 12 ICM tests (exact, Monte Carlo, validation, performance, convergence)
|
|
- `internal/financial/chop_test.go` - 6 chop/deal tests (all deal types, positions, tournament end)
|
|
- `internal/tournament/tournament_test.go` - 9 tournament unit tests (template, start, auto-close, multi, state)
|
|
- `internal/tournament/integration_test.go` - 4 integration tests (lifecycle, deal, cancel, pause/resume)
|
|
|
|
## Decisions Made
|
|
- **ICM dispatcher pattern:** CalculateICM auto-selects exact for <=10 players (factorial complexity manageable) and Monte Carlo with 100K iterations for 11+ (converges to <2% deviation with equal stacks)
|
|
- **Deal proposal/confirm workflow:** ProposeDeal calculates and stores proposal without applying; ConfirmDeal applies payouts as chop transactions -- matches the TD review flow from CONTEXT.md
|
|
- **Full vs partial chop:** Full chop sets all players to 'deal' status and completes the tournament; partial chop applies partial payouts and lets tournament continue with remaining pool
|
|
- **Integration test DB strategy:** In-memory DBs with libsql don't support cross-goroutine access; integration tests use file-based DB with WAL mode and busy_timeout for clock ticker compatibility
|
|
- **Auto-close semantics:** CheckAutoClose called after every bust-out; 1 player remaining triggers EndTournament, 0 players triggers CancelTournament
|
|
|
|
## Deviations from Plan
|
|
|
|
### Auto-fixed Issues
|
|
|
|
**1. [Rule 1 - Bug] Fixed in-memory DB cross-goroutine access in integration tests**
|
|
- **Found during:** Task I2 (integration tests)
|
|
- **Issue:** `setupTestDB` creates per-test in-memory DBs that aren't accessible from the clock ticker's background goroutine, causing "no such table" errors
|
|
- **Fix:** Created `setupIntegrationDB` using file-based temp DB with WAL mode and busy_timeout=5000; added StopTicker call after StartTournament
|
|
- **Files modified:** internal/tournament/integration_test.go
|
|
- **Verification:** All 4 integration tests pass
|
|
- **Committed in:** 2958449
|
|
|
|
**2. [Rule 1 - Bug] Fixed blind_levels notes NULL scan failure**
|
|
- **Found during:** Task I2 (tournament tests)
|
|
- **Issue:** blind_levels notes column could be NULL, causing scan into string to fail when loading template
|
|
- **Fix:** Used sql.NullString for notes scanning in loadLevelsFromDB; added explicit empty string notes to seed data
|
|
- **Files modified:** internal/tournament/tournament.go, internal/tournament/tournament_test.go
|
|
- **Verification:** TestCreateFromTemplate passes
|
|
- **Committed in:** 2958449
|
|
|
|
**3. [Rule 1 - Bug] Fixed payout_brackets column name mismatch**
|
|
- **Found during:** Task I2 (tournament tests)
|
|
- **Issue:** Test DDL used `payout_structure_id` but service queries use `structure_id` column name
|
|
- **Fix:** Renamed column to `structure_id` in test DDL to match production schema
|
|
- **Files modified:** internal/tournament/tournament_test.go
|
|
- **Verification:** All tournament unit tests pass
|
|
- **Committed in:** 2958449
|
|
|
|
---
|
|
|
|
**Total deviations:** 3 auto-fixed (3 Rule 1 bugs)
|
|
**Impact on plan:** All auto-fixes necessary for test correctness. No scope creep.
|
|
|
|
## Issues Encountered
|
|
- libsql PRAGMA handling: `PRAGMA journal_mode=WAL` returns a row, so `Exec` fails with "Execute returned rows" -- must use `QueryRow` with `Scan` instead. This is consistent with the decision logged in 01-02 about libsql PRAGMA inconsistency.
|
|
|
|
## User Setup Required
|
|
None - no external service configuration required.
|
|
|
|
## Next Phase Readiness
|
|
- Tournament lifecycle is complete and ready for wiring into the full server
|
|
- Multi-tournament support enables lobby view for the frontend (Plan 11/14)
|
|
- ICM and chop engines ready for frontend deal UI integration
|
|
- API routes registered but need wiring into server.go router (will happen in final assembly plan)
|
|
|
|
## Self-Check: PASSED
|
|
|
|
All 11 created files verified present. Both task commits (75ccb6f, 2958449) verified in git log.
|
|
|
|
---
|
|
*Phase: 01-tournament-engine*
|
|
*Completed: 2026-03-01*
|