Initial Commit
This commit is contained in:
144
openspec/changes/enterprise-gaming-leaderboard/proposal.md
Normal file
144
openspec/changes/enterprise-gaming-leaderboard/proposal.md
Normal file
@@ -0,0 +1,144 @@
|
||||
# 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`.
|
||||
45
openspec/changes/enterprise-gaming-leaderboard/tasks.md
Normal file
45
openspec/changes/enterprise-gaming-leaderboard/tasks.md
Normal file
@@ -0,0 +1,45 @@
|
||||
# Tasks: enterprise-gaming-leaderboard
|
||||
|
||||
## 0. Pre-flight (non-negotiable)
|
||||
|
||||
- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
|
||||
- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
|
||||
- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
|
||||
|
||||
## Phase 1 — Scaffold
|
||||
|
||||
- [ ] Create `gaming/multiplayer/leaderboard/` (`@suaveplan/leaderboard`, `0.1.0`, `sideEffects: false`)
|
||||
- [ ] `tsconfig.json`, `vitest.config.ts`
|
||||
|
||||
## Phase 2 — Error codes & constants
|
||||
|
||||
- [ ] `src/error-codes.ts` + `src/constants/index.ts` — `DEFAULT_PAGE_SIZE`, `DEFAULT_AROUND_RADIUS`
|
||||
|
||||
## Phase 3 — Types
|
||||
|
||||
- [ ] `src/types/common.ts` + `common.md`
|
||||
|
||||
## Phase 4 — Leaderboard
|
||||
|
||||
- [ ] `src/core/leaderboard/leaderboard.ts` — sorted array (binary search insert), submit/getEntry/getRank/getPage/aroundPlayer/reset, OTel
|
||||
- [ ] Tests (rank monotonicity, maxEntries eviction, asc/desc ordering)
|
||||
- [ ] Docs
|
||||
|
||||
## Phase 5 — Season manager
|
||||
|
||||
- [ ] `src/core/season-manager/season-manager.ts` — season lifecycle, archiveCurrent, tick expiry, events
|
||||
- [ ] Tests + docs
|
||||
|
||||
## Phase 6 — Property tests
|
||||
|
||||
- [ ] `tests/property.test.ts` — rank = position in sorted order for any input sequence; aroundPlayer always includes player
|
||||
|
||||
## Phase 7 — Integration tests
|
||||
|
||||
- [ ] `tests/integration.test.ts` — submit → rank → season reset → archive
|
||||
|
||||
## Phase 8 — Pre-publish gate
|
||||
|
||||
- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/leaderboard` green
|
||||
- [ ] 100% coverage
|
||||
- [ ] Publish: `bun scripts/publish.ts --package @suaveplan/leaderboard`
|
||||
Reference in New Issue
Block a user