---
phase: 01-tournament-engine
plan: 08
subsystem: seating
tags: [table-balancing, break-table, tda-rules, auto-seating, dealer-button, hand-for-hand, chi-router]

requires:
  - phase: 01-tournament-engine
    provides: "table schema, tournament_players schema, audit trail, WebSocket hub, clock registry"
provides:
  - "BalanceEngine with TDA-compliant suggestion generation and live-adaptive invalidation"
  - "BreakTableService for fully automatic player redistribution"
  - "Full REST API for tables, seating, balancing, blueprints, dealer button, hand-for-hand"
  - "TableService.DB() accessor for cross-service database access"
affects: [02-multi-device, frontend-tournament-view]

tech-stack:
  added: []
  patterns: [live-adaptive-suggestions, stale-detection-on-accept, clockwise-distance-fairness]

key-files:
  created:
    - internal/seating/balance.go
    - internal/seating/breaktable.go
    - internal/seating/balance_test.go
    - internal/seating/breaktable_test.go
    - internal/server/routes/tables.go
  modified:
    - internal/seating/table.go

key-decisions:
  - "Balance suggestions use clockwise distance from dealer button for move fairness (player closest after button moves first)"
  - "Stale suggestion re-validation requires fromCount - toCount >= 2 before accepting (ensures move still needed)"
  - "Break table is fully automatic (applies immediately, result is informational per CONTEXT.md)"
  - "Blueprint routes are venue-level (not tournament-scoped); admin role required for mutations"

patterns-established:
  - "Live-adaptive pattern: suggestions are proposals that are re-validated on accept and invalidated on state change"
  - "Break table distributes by iterating sorted destination tables (ascending player count) for each player"

requirements-completed: [SEAT-01, SEAT-02, SEAT-03, SEAT-04, SEAT-05, SEAT-06, SEAT-07, SEAT-08, SEAT-09]

duration: 6min
completed: 2026-03-01
---

# Phase 1 Plan 8: Table & Seating Engine Summary

**TDA-compliant balance engine with live-adaptive suggestions, fully automatic break table, and complete REST API for table/seating management**

## Performance

- **Duration:** 6 min
- **Started:** 2026-03-01T03:19:29Z
- **Completed:** 2026-03-01T03:25:01Z
- **Tasks:** 2
- **Files modified:** 6

## Accomplishments
- Balance engine detects unbalanced tables (diff > 1) and generates TDA-compliant move suggestions with button-aware fairness
- Suggestions are live and adaptive: re-validated on accept, auto-invalidated when state changes (bust, move, etc.)
- Break table fully automatically distributes players evenly and deactivates the dissolved table
- Complete REST API covering tables, seating, balancing, blueprints, dealer button, and hand-for-hand
- 15 tests covering balance detection, suggestion lifecycle, stale detection, auto-seat, break table distribution, and dealer button advancement

## Task Commits

Each task was committed atomically:

1. **Task H1: Table management, auto-seating, blueprints, hand-for-hand** - `e947ab1` (feat)
2. **Task H2: Balance engine, break table, API routes, tests** - `2d3cb0a` (feat)

## Files Created/Modified
- `internal/seating/balance.go` - BalanceEngine with CheckBalance, SuggestMoves, AcceptSuggestion, CancelSuggestion, InvalidateStaleSuggestions
- `internal/seating/breaktable.go` - BreakTableService with BreakTable (fully automatic redistribution)
- `internal/seating/table.go` - Added DB() accessor method for cross-service use
- `internal/seating/balance_test.go` - 10 tests: balance detection, suggestions, stale detection, auto-seat, dealer button
- `internal/seating/breaktable_test.go` - 5 tests: even distribution, odd count, deactivation, error cases
- `internal/server/routes/tables.go` - Full REST API handler with 22 endpoints

## Decisions Made
- Balance suggestions use clockwise distance from dealer button for fairness: player closest after button (small blind position) is moved first, as they are least disadvantaged by a move
- Stale suggestion re-validation requires source table to have at least 2 more players than destination (the threshold that makes a move necessary)
- Break table is fully automatic per CONTEXT.md -- moves are applied immediately and result is informational for TD display
- Blueprint CRUD routes are venue-level (not tournament-scoped) with admin role for mutations, read for any authenticated user

## Deviations from Plan

None - plan executed exactly as written.

## Issues Encountered
None

## User Setup Required
None - no external service configuration required.

## Next Phase Readiness
- Table and seating engine is feature-complete for Phase 1
- Frontend can integrate table views, balance alerts, and break table UI
- Balance suggestions ready for real-time WebSocket push to connected clients

---
*Phase: 01-tournament-engine*
*Completed: 2026-03-01*