# OpenSpec Change: enterprise-gaming-leaderboard

- **Change ID**: enterprise-gaming-leaderboard
- **Package**: `@suaveplan/leaderboard`
- **Category**: gaming/multiplayer
- **Target path**: `gaming/multiplayer/leaderboard`
- **Status**: PROPOSED
- **Date**: 2026-04-24
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/leaderboard.md`

---

## Summary

Deliver `@suaveplan/leaderboard` on the genesis branch from scratch at enterprise quality. The package provides a leaderboard system with ranked score submission, seasonal resets, and around-player rank queries. A `Leaderboard` uses an in-memory sorted structure (array + binary search for O(log n) insert/rank); a `SeasonManager` tracks active season with start/end timestamps and archives previous season results; `aroundPlayer` returns N entries above and below a given player for contextual ranking display. Genesis adds Zod schemas, structured errors, OTel submission counter, injectable clock, and 100% coverage with property tests for rank monotonicity.

---

## Current-state audit (genesis)

Package does not exist on genesis yet — fresh build.

---

## Available workspace deps on genesis

| Package | Role |
|---|---|
| `@suaveplan/error` (`workspace:^`) | `LeaderboardError`; `LB.*` codes |
| `@suaveplan/types` (`workspace:^`) | `Clock` |
| `@suaveplan/events` (`workspace:^`) | `lb:score_updated`, `lb:season_reset`, `lb:rank_achieved` events |
| `zod` (`catalog:forms`) | `LeaderboardEntry`, `Season` schemas |
| `@opentelemetry/api` (`catalog:observability`) | Submission counter, entry count gauge |

---

## Public API surface

```ts
interface LeaderboardEntry {
  playerId: string
  displayName: string
  score: number
  rank: number
  updatedAt: number
  metadata?: Record<string, unknown>
}

function createLeaderboard(options?: LeaderboardOptions): Leaderboard

interface LeaderboardOptions {
  name?: string
  maxEntries?: number       // default unlimited (in-memory); set for top-N boards
  order?: 'desc' | 'asc'   // default 'desc' (higher = better)
  clock?: Clock
}

interface Leaderboard {
  submit(playerId: string, displayName: string, score: number, metadata?: Record<string, unknown>): LeaderboardEntry
  getEntry(playerId: string): LeaderboardEntry | undefined
  getRank(playerId: string): number | undefined
  getPage(page: number, pageSize?: number): LeaderboardEntry[]
  aroundPlayer(playerId: string, radius?: number): LeaderboardEntry[]
  remove(playerId: string): void
  reset(): void
  readonly size: number
}

// Seasons
function createSeasonManager(options: SeasonManagerOptions): SeasonManager

interface SeasonManagerOptions {
  seasonDuration: number    // seconds
  clock?: Clock
}

interface SeasonManager {
  getCurrentSeason(): Season
  tick(dt: number): void    // check for season expiry
  getArchive(): ArchivedSeason[]
  archiveCurrent(leaderboard: Leaderboard): void
}

interface Season {
  id: string
  number: number
  startedAt: number
  endsAt: number
  isActive: boolean
}

interface ArchivedSeason extends Season {
  topEntries: LeaderboardEntry[]
}
```

### Error codes

```ts
type LbErrorCode =
  | 'LB_ENTRY_NOT_FOUND'
  | 'LB_INVALID_SCORE'
  | 'LB_SEASON_NOT_ACTIVE'
  | 'LB_PAGE_OUT_OF_RANGE'
```

---

## File layout

```text
gaming/multiplayer/leaderboard/
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts
    error-codes.ts
    constants/index.ts
    types/common.ts
    types/common.md
    core/
      leaderboard/
        leaderboard.ts
        leaderboard.md
        leaderboard.types.ts
        leaderboard.test.ts
        index.ts
      season-manager/
        season-manager.ts
        season-manager.md
        season-manager.types.ts
        season-manager.test.ts
        index.ts
  tests/
    property.test.ts
    integration.test.ts
```

---

## Impact

**Downstream**: `@suaveplan/react-game-hud` renders mini leaderboard widget; `@suaveplan/api-plugin-game-server` exposes leaderboard HTTP routes. Prerequisites: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`.